specdriven

Plain-English spec-driven development for people who would rather describe their idea than write a tech spec.

A drop-in skill that walks any AI coding agent through three phases — Concept ▸ Roadmap ▸ Features — before it writes a single line of code. Three one-page markdown artifacts, no jargon, no install.

  ┌────────────┐     ┌────────────┐     ┌────────────┐
  │  CONCEPT   │ ──▶ │  ROADMAP   │ ──▶ │  FEATURES  │
  │  the why   │     │  the path  │     │  the work  │
  └────────────┘     └────────────┘     └────────────┘
   concept.md         roadmap.md         features/NN-name.md

Why this exists

GitHub's spec-kit is great — and heavy: seven phases (Constitution, Specify, Clarify, Plan, Tasks, Analyze, Implement), a Python CLI, terminology that assumes you're already an engineer. For a hobbyist building a side project on Replit, that's too much friction.

specdriven keeps the part that actually matters — making the agent's intent explicit before it codes — and throws out everything else. The result is the smallest possible scaffold that still beats vibe-coding.

What the agent produces

In your project, after running through the three phases:

<your-project>/
└── specdriven/
    ├── concept.md     # what & why, who's it for, what done looks like
    ├── roadmap.md     # ordered features (S/M/L), with one-line whys
    └── features/
        ├── 01-sign-up.md
        ├── 02-create-post.md
        └── 03-share-link.md

Each file is one page. Each is read by the agent on every later turn so the work stays on contract.

Install

The same skill ships at two install paths so it works with both Claude Code's plugin system and the open agent-skills CLI (vercel-labs/skills, which targets Replit Agent, Cursor, Codex, OpenCode, and 50+ others). Both copies are identical — pick whichever fits your tool.

Claude Code (plugin)

Run both inside Claude Code:

/plugin marketplace add vasylrakivnenko/specdriven
/plugin install specdriven@specdriven

Or sideload during development:

git clone https://github.com/vasylrakivnenko/specdriven
cd specdriven
claude --plugin-dir ./plugin

See plugin/README.md for details.

Replit Agent / Cursor / Codex / OpenCode / others (npx skills)

npx skills add vasylrakivnenko/specdriven

Installs skills/specdriven/SKILL.md into whichever agent directory the CLI detects (.claude/skills/, .agents/skills/, .cursor/rules/, etc.). Scope flags: -g for global, -a <agent> to target a specific agent.

On Replit: run the command in the Shell tab (not the Agent chat). Confirm with y when npx asks to fetch the skills package, then start a fresh Agent session so it picks up the new skill.

How a session feels (example)

You: I want to build a tiny site where my book club picks the next book by voting.

Agent: (invokes specdriven) Let me draft the concept first. A few quick questions:

1. How big is your book club — 5 people or 50?
2. Should votes be anonymous or visible?
3. Anyone allowed to nominate, or just the host?
4. Phone-first or laptop-first?
5. Should we keep history of past picks?

You: (answers)

Agent: Here's specdriven/concept.md — one page. Look right? Once you're happy, I'll draft the roadmap.

The agent never just starts coding. It builds shared understanding first, then plans, then ships features one at a time.

What's in this repo

Path	Purpose
.claude-plugin/marketplace.json	Marketplace manifest for Claude Code
plugin/	The Claude Code plugin (manifest + skill copy)
plugin/skills/specdriven/SKILL.md	The skill body (Claude Code path)
skills/specdriven/SKILL.md	The skill body (npx skills add path) — identical to the plugin copy
README.md	This file
LICENSE	Apache-2.0

License

Apache-2.0.

Acknowledgements

The shape of this repo (dual-distribution: Claude Code plugin + npx skills add) mirrors SAICA-KG, where the same pattern was first proven out. The three-phase reduction from spec-kit's seven was sharpened in conversation with non-technical builders who wanted "spec-kit, but without the spec-kit-ness".