Ctrlk
Repository
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Spec-Driven Development

Comprehensive specification-driven development workflow plugin that transforms prompts into production-ready implementations through structured planning, architecture design, and quality-gated execution.

This plugin is designed to consistently and reproducibly produce working code. It was tested on real-life production projects by our team, and in 100% of cases it generated working code aligned with the initial prompt. If you find a use case it cannot handle, please report it as an issue.

Key Features

  • Development as compilation — The plugin functions like a "compilation" or "nightly build" for your development process: task specs → run /implement-task → working code. After writing your prompt, you can launch the plugin and expect a functional result when you return. The completion time depends on task complexity — simple tasks may finish within 30 minutes, while complex ones can take several days.

  • Benchmark-level quality in real life — Model benchmarks improve with each release, yet real-world results often stagnate. This is because benchmarks reflect the best possible output a model can achieve, whereas in practice LLMs tend to drift toward sub-optimal, non-functional solutions. This plugin uses a variety of patterns to keep the model operating at peak performance.

  • Customizable — Balance result quality and process speed by adjusting command parameters. Learn more in the Customization section.

  • Developer time-efficiency — The overall process is designed to minimize developer time and reduce the number of interactions, while still producing results superior to what a model can generate from scratch. However, overall quality is proportional to the time invested in iterating on and refining the specification.

  • Industry-standard — The plugin's specification template is based on the arc42 standard, adjusted for LLM capabilities. Arc42 is a widely adopted, high-quality standard for software development documentation used by many organizations.

  • Works best in complex or large codebases — While most other frameworks work best for new projects and greenfield development, this plugin is designed to perform better as your codebase grows and your architecture becomes more structured. Each planning phase includes a codebase impact analysis step that evaluates which files may be affected and which patterns to follow to achieve the desired result.

  • Simple — This plugin avoids unnecessary complexity by primarily using only three commands, offloading process complexity to the model via multi-agent orchestration. /implement-task is a single command that produces functional code from a task specification. To create that specification, you run /sdd:add-task and /plan-task, which analyze your prompt and iteratively refine the specification until it meets the required quality standards.

Quick Start

/plugin marketplace add NeoLabHQ/context-engineering-kit

Enable the sdd plugin in the installed plugins list:

/plugin
# Installed -> sdd -> Space to enable

Then run the following commands:

Run /clear (or re-open Claude Code) to clear context and start fresh. Then run the following command:

Overall Flow

End-to-end task implementation process from initial prompt to pull request, including commands from the git plugin:

  • /add-task → Creates a .specs/tasks/draft/<name>.<type>.md file with the initial task description.

  • /plan-task → Generates a .claude/skills/<skill-name>/SKILL.md file with the skills needed to implement the task (by analyzing the library and framework documentation used in the codebase), then updates the task file with a refined specification, writes one sub-task file per implementation step under .specs/sub-tasks/<task-name>/, and moves the task to .specs/tasks/todo/.

  • /implement-task → Produces a working implementation, reviews it at the end of every implementation phase, then moves the task to .specs/tasks/done/.

  • /commit → Commits changes.

  • /create-pr → Creates a pull request.

Planning Pipeline

/plan-task runs four pipeline segments — parallel analysis, architecture synthesis, decomposition, promote:

The first segment fans out into three parallel agent phases, so five phases in all are model-assigned — 2a, 2b, 2c, 3 and 4 — and each is followed by its own LLM-as-Judge quality gate (Judges 2a, 2b, 2c, 3 and 4). Promotion is a plain file move — no agent, no model tier, no judge.

  • Phase 2c writes the task's # Description and the single ## Acceptance Criteria section, which holds six sub-blocks in order: **Checklist:**, **Regular Checks:**, **Rubric:**, **Rubric Score Definitions:**, **Test Strategy:** and **Definition of Done:**. Business and technical criteria are mixed inside each sub-block.

  • Phase 4 writes only the task file's ## Implementation Process section — a ### Parallelization Overview (dependency diagram plus a step table with Step | Phase | Model | Agent | Depends on | Parallel with | Sub-Task File) and a ### Phase Overview that gives each phase its Steps:, its Reviewer model: and the checklist items and rubrics due at that milestone.

Sub-Task File Layout

Phase 4 writes every implementation step as its own file, so the agent that executes the step reads only that step:

Each sub-task file carries **Task File:** (a back-reference to the parent task), **Phase:**, **Model:**, **Agent:**, **Depends on:**, **Parallel with:**, **Note:**, **Goal:**, a step description, #### Expected Output, #### Success Criteria, #### Subtasks and #### Blockers & Risks. Because the folder never moves, the paths recorded in the Parallelization Overview stay valid for the whole task lifecycle.

During /implement-task, one implementation agent is dispatched per step with the task file path and its sub-task file path, at the model named in that step's Model column of the Parallelization Overview. A single sdd:code-reviewer then runs at the end of each phase, at that phase's Reviewer model, scoring only the acceptance criteria that phase lists as due.

Commands

Core workflow commands:

  • /add-task - Create task template file with initial prompt

  • /plan-task - Analyze prompt, generate required skills and refine task specification

  • /implement-task - Produce working implementation of the task and verify it

Additional commands useful before creating a task:

  • /create-ideas - Generate diverse ideas on a given topic using creative sampling techniques

  • /brainstorm - Refine vague ideas into fully-formed designs through collaborative dialogue

Available Agents

The SDD plugin uses specialized agents for different phases of development:

Agent
Description
Used By

researcher

Technology research, dependency analysis, best practices; creates a reusable skill file

/plan-task (Phase 2a)

code-explorer

Codebase analysis, pattern identification, architecture mapping

/plan-task (Phase 2b)

business-analyst

Requirements discovery, scope and user scenarios, and the whole ## Acceptance Criteria section — checklist, regular checks, rubric, score definitions, test strategy and definition of done, mixing business and technical criteria

/plan-task (Phase 2c)

software-architect

Architecture design, component design, solution strategy and expected changes

/plan-task (Phase 3)

tech-lead

Decomposition into per-step sub-task files, dependency mapping, parallelization, risk analysis, and grouping steps into independently verifiable phases with a reviewer model each

/plan-task (Phase 4)

developer

Implements exactly one step, from its own sub-task file, and leaves the tree building and green

/implement-task (per step)

code-reviewer

Reviews a whole implementation phase against the acceptance criteria that phase lists as due, plus code quality, Muda waste analysis and test coverage

/implement-task (end of each phase)

tech-writer

Technical documentation, API guides, usage examples, and architecture updates

/implement-task

Patterns

Key patterns implemented in this plugin:

  • Structured reasoning templates — Includes Zero-shot and Few-shot Chain of Thought, Tree of Thoughts, Problem Decomposition, and Self-Critique. Each is tailored to a specific agent and task, enabling sufficiently detailed decomposition so that isolated sub-agents can implement each step independently.

  • Multi-agent orchestration for context management — Context isolation of independent agents prevents "context rot," maintaining optimal LLM performance at each step. The main agent acts as an orchestrator that launches sub-agents and manages their workflow.

  • Quality gates based on LLM-as-Judge — Evaluates the quality of each planning and implementation step using evidence-based scoring and predefined verification rubrics. This eliminates cases where an agent produces non-functional or incorrect solutions.

  • Continuous learning — Automatically builds specific skills the agent needs to implement a task, which it might otherwise be unable to perform from scratch.

  • Spec-driven development pattern — Based on the arc42 specification standard adjusted for LLM capabilities, this pattern eliminates elements of the specification that do not add value to implementation quality.

  • MAKER — An agent reliability pattern introduced in Solving a Million-Step LLM Task with Zero Errors. It minimizes agent mistakes caused by context accumulation and hallucinations by utilizing clean-state agent launches and filesystem-based memory storage.

Vibe Coding vs. Specification-Driven Development

This plugin is not a "vibe coding" solution, though it can function like one out of the box. By default, it is designed to work from a single prompt through to task completion, making reasonable assumptions and evidence-based decisions instead of constantly asking for clarification. This is because developer time is more valuable than model time, allowing the developer to decide how much time is worth spending on a task. The plugin will always produce functional results, but quality may be sub-optimal without human feedback.

To improve quality, you can correct the generated specification or leave comments using //, then run the /plan-task command again with the --refine flag. You can also verify each planning and implementation phase by adding the --human-in-the-loop flag. Majority of researches show that human feedback is the most effective way to improve results.

Our tests showed that even when the initially generated specification was incorrect due to missing information or task complexity, the agent was still able to self-correct until it reached a working solution. However, this process often took longer, as the agent explored incorrect paths and stopped more frequently. To avoid this, we strongly recommend decomposing complex tasks into smaller, separate tasks with dependencies and reviewing the specification for each one. You can add dependencies between tasks as arguments to the /sdd:add-task command, and the model will link them by adding a depends_on section to the task file's frontmatter.

Even if you prefer a less hands-on approach, you can still use the plugin for complex tasks without decomposition or human verification — though you may need tools to keep the session active for longer periods, for example ralph-loop.

Learn more about available customization options in Customization.

FAQ

Do I need to re-run /plan-task or /implement-task after context compaction (/compact)?

After compaction, close the terminal and resume with /plan-task --continue or /implement-task --continue. This produces more predictable results than continuing in a compacted context. Using /model sonnet[1m] reduces compaction frequency.

Do I need to prefix every prompt with /plan-task or /implement-task?

No. Run these commands once to start the workflow. The only time to invoke them again is when you change the specification or code and want agents to update misaligned sections — use /plan-task --refine or /implement-task --refine.

Should I clear context between /plan-task and /implement-task?

Yes. Run /clear (or re-open Claude Code) after /plan-task completes and before running /implement-task. The planning phase fills the context with analysis artifacts; a clean context gives implementation agents better results.

Theoretical Foundation

The SDD plugin is based on established software engineering methodologies and research:

Core Methodologies

  • GitHub Spec Kit - Specification-driven development templates and workflows

  • OpenSpec - Open specification format for software requirements

  • BMad Method - Structured approach to breaking down complex features

Supporting Research

PreviousUsage Examples
Nextadd-task

Last updated