| name | feature-spec |
|---|---|
| description | A spec-driven workflow for orchestrating AI-assisted feature development. Gives solo developers a structured, phase-gated process for designing, reviewing, and implementing features with an AI agent without losing architectural control. |
What this is: A complete methodology and template for writing feature specifications that an AI agent can execute safely, one phase at a time, under your supervision.
Who this is for: Solo developers (or small teams) who use AI coding agents and want to ship complex features without architectural drift, scope creep, or "prompt and pray" frustration.
When you hand an AI agent a feature request in plain English and let it build autonomously, three things go wrong:
-
Context degradation. As the token window fills, the agent forgets earlier decisions. Code written in minute 30 contradicts architecture established in minute 5.
-
Stateless sessions. When the session ends (timeout, token limit, crash), the agent resets completely. The next session starts from zero with no memory of what was built, what was tested, or what remains.
-
Architectural drift. Without explicit boundaries, agents default to path-of-least-resistance solutions. They introduce new patterns, ignore established conventions, and make design decisions that belong to you.
The spec-driven workflow solves all three by giving the agent a persistent, structured document that acts as its memory, its guardrails, and its execution plan.
The specification document is not just a plan. It is a state machine that the agent updates as it works. Phase checkboxes, status markers, and deviation logs persist across sessions. When a new agent starts a new session, it reads the tracker and knows exactly where to resume.
This is what makes the workflow resilient to session disruptions. Your progress lives in the file, not in the agent's context window.
Features are broken into sequential phases (typically 3-6). The agent works one phase at a time and stops at each gate. Between phases, you:
- Run your test suite to catch regressions
- Playtest the feature manually if applicable
- Commit the code to create a clean restore point
- Review the agent's work before authorizing the next phase
This prevents the agent from building an entire castle on a bad foundation. A regression caught after Phase 1 costs 5 minutes to fix. The same regression caught after Phase 4 can cascade into hours of untangling.
You are not a bottleneck. You are a velocity multiplier. AI agents are highly capable syntax generators but they lack subjective, spatial, and holistic judgement. Your role between phases is to verify things the agent cannot:
- Does this feel right in the UI?
- Does the user flow make intuitive sense?
- Did the agent accidentally break something outside the spec's scope?
- Is the code quality up to your standards?
True "fire-and-forget" autonomy across complex feature logic compounds silent errors. Short human validation gates between structural milestones protect project momentum.
Writing a detailed spec might look like Waterfall overhead. In practice, the heavy lifting is co-authored with the agent. You describe the feature; the agent generates the structured markdown, the risk tables, the file change summaries, and the pseudocode. You review and refine.
This means a solo developer can maintain structured, detailed planning docs at AI speed. The spec is not bureaucracy. It is the cheapest insurance you will ever buy against cascading rework.
Implementation never survives first contact with the codebase perfectly intact. Rather than the agent pivoting autonomously when it hits a roadblock, the spec forces a protocol:
- Agent proposes the deviation
- You approve or reject
- Approved deviations are logged in the spec with rationale
This transforms the spec from a static plan into a historical record of design decisions. Six months later, when you wonder "why does this work this way?", the deviation log has the answer.
Every feature goes through two distinct stages, each with a different dynamic between you and the agent.
Dynamic: Collaborative brainstorm. You and the agent co-author the specification.
Flow:
- You describe the feature idea in plain language
- The agent drafts a structured spec using the template
- You review, challenge, and refine
- The agent performs an architectural review of the spec against your coding standards (as if wearing a "senior architect" hat)
- You resolve the review feedback
- The spec is locked for implementation
Key discipline: Do not start coding during Stage 1. Resist the urge to "just try it." The spec is faster to edit than code.
Dynamic: Directed execution. The agent follows the spec; you validate between phases.
Flow:
- The agent reads the completed spec and the project context
- Agent implements Phase 1, updates the status tracker
- Agent stops. You test, review, commit
- Agent implements Phase 2, updates the tracker
- Repeat until all phases are complete
- Agent logs any deviations that occurred during implementation
- Spec is moved to the "resolved" archive
Key discipline: The agent proposes; you approve. The agent does not make design decisions during implementation. If it encounters something the spec did not anticipate, it proposes a deviation, not a unilateral change.
Not every feature needs a 20-section, 800-line specification. The template in Part 3 is the maximum. Scale it down based on complexity.
Use when: Simple, self-contained changes. A new utility, a UI tweak, a config change, a small refactor.
Include:
- Summary (what and why)
- File change list
- Implementation steps (no phases needed, single pass)
- Risk notes (if any)
Skip: Architect review, deviation log, status tracker, systems design
Use when: A new feature touching 3+ files, with UI, logic, and state changes.
Include:
- Summary and design rationale
- Systems design (key methods, state changes, API surface)
- File change summary
- Phased implementation plan with status tracker
- Risk assessment
- Deviation log (starts empty)
Skip: Architect review can be informal (inline review notes rather than a full section)
Use when: Major system additions, cross-cutting refactors, features that touch 10+ files, anything with PRNG/determinism concerns, anything with complex state lifecycle.
Include: Everything in the template. Every section earns its weight at this complexity level.
Ask yourself: "If the agent started implementing this and I stepped away for an hour, how badly could it go wrong?"
- Not badly: Light spec
- Somewhat badly: Standard spec
- Catastrophically: Full spec
When a feature is complete, rename the spec file with a .resolved extension (or move it to a resolved/ directory). Do not delete it.
Resolved specs serve three purposes:
-
Institutional memory. They document why things were built the way they were, what alternatives were considered, and what deviations occurred during implementation.
-
Agent training examples. When starting a new spec for a similar feature, point the agent at a resolved spec: "Follow the same structure and level of detail as this one." The output quality improves dramatically.
-
Bug archaeology. When something breaks months later, grepping the resolved specs for the file or function name often reveals the design context that explains the behavior.
Use this prompt (adapt the bracketed sections) to kick off spec creation:
I want to build [feature description]. Here is my rough idea:
[2-5 sentences describing the feature, its purpose, and any
constraints or design preferences you have]
Please draft a feature specification following the spec template
in [path to template, e.g. .agents/templates/feature-spec.md].
Read the project context skill first if you have not already:
[path to project-context skill, e.g. .agents/skills/project-context/SKILL.md]
For the spec draft:
1. Fill in the summary, design rationale, and systems design sections
2. Identify which files will be touched
3. Break the implementation into logical phases
4. Flag any architectural risks you can see
5. Propose the spec to me for review before we proceed
Now review this spec as a senior architect. Check it against
our coding standards and architectural principles. Flag:
- Violations of our established patterns
- Missing edge cases
- State lifecycle gaps (will data survive across [your persistence boundaries]?)
- Circular dependency risks
- Missing cleanup/teardown paths
Present your findings as numbered action items. Do not modify
the spec yet. I will review your feedback and decide which
items to address.
Use this prompt to start the implementation phase:
Implement the feature specified in [path to spec file].
Before you begin:
1. Read our project context: [path to project-context skill]
2. Read the full specification: [path to spec file]
3. Work ONE PHASE AT A TIME in the order listed in the status tracker
After completing each phase:
1. Update the status tracker in the spec (check the boxes, update
the timestamp and current phase)
2. Stop coding. Tell me what you completed and ask me to test
and commit before proceeding to the next phase
If you encounter something the spec did not anticipate:
1. Do NOT implement a workaround silently
2. Propose the deviation to me with your rationale
3. Only proceed after I approve
4. Log the approved deviation in the Deviations section of the spec
Do not modify files outside the scope listed in the spec's
file change summary unless you flag it to me first.
If the session times out or you start a new conversation:
I am resuming implementation of [feature name].
Please read:
1. Project context: [path to project-context skill]
2. Feature spec: [path to spec file]
Check the status tracker in the spec to see which phases are
complete and which phase to resume from. Tell me what you see
before writing any code.
Document Type: Implementation Specification & Roadmap Feature Focus: [One-sentence summary of the feature] Status: Spec Draft / Under Review / Implementation Phase X / COMPLETE Last Updated: YYYY-MM-DD Implementing Agent: [Agent name, or "Unassigned"]
BEFORE writing any code, you MUST:
- Read the project context. If you have not recently done so, read the project context skill at
[path to your project-context skill]to familiarize yourself with the architecture, coding standards, and rules of engagement. - Read this entire spec. Understand the full feature scope before touching any file.
- Work one phase at a time in the order listed in the status tracker below. Do NOT skip ahead.
AFTER completing each phase, you MUST:
- Stop coding. Do not proceed to the next phase.
- Update the status tracker below (mark tasks as complete, update the timestamp).
- Confirm with the developer in chat that the phase is complete and await explicit approval before starting the next phase.
If you encounter something the spec did not anticipate:
- Do not deviate unilaterally. Propose the change with your reasoning.
- Wait for approval. Only proceed after the developer confirms.
- Log approved deviations in the "Deviations from Spec" section at the end of this document.
Last Updated: YYYY-MM-DD Current Phase: Pre-implementation
- 1.1 [Task description, e.g. "Add FEATURE config block to config.js"]
- 1.2 [Task description, e.g. "Add state properties to state module + reset()"]
- 1.3 [Task description]
- 1.4 PAUSE: Developer runs tests and commits. Zero regressions confirmed: [ ]
- 2.1 [Task description, e.g. "Create feature.logic.js with core methods"]
- 2.2 [Task description]
- 2.3 [Task description]
- 2.4 PAUSE: Developer runs tests and commits. Zero regressions confirmed: [ ]
- 3.1 [Task description, e.g. "Add HTML structure to index.html"]
- 3.2 [Task description, e.g. "Add CSS styles"]
- 3.3 [Task description, e.g. "Create UI module and wire event handlers"]
- 3.4 PAUSE: Developer runs tests and commits. Zero regressions confirmed: [ ]
- 4.1 [Task description, e.g. "Add tutorial tip / onboarding"]
- 4.2 [Task description, e.g. "Add logging / analytics"]
- 4.3 [Task description, e.g. "Wire audio / SFX"]
[What are we building, why, and what is the core mechanic?]
Design Intent: [How does this feature interact with the rest of the system? What is the core design philosophy or tension?]
UI Architecture: [Where does this live visually? What existing patterns does it follow?]
Key Risks & Mitigations:
| Risk | Impact | Mitigation |
|---|---|---|
| [e.g. Circular imports between new and existing modules] | High | [e.g. Use callback injection pattern to break the cycle] |
| [e.g. State not surviving across session boundaries] | Medium | [e.g. Persist in storage module; document reset behavior] |
| [e.g. New CSS animations causing frame drops on mobile] | Low | [e.g. Use compositor-only properties (transform, opacity)] |
// Add to your config file:
[Placeholder for config values]
// New state properties:
[Placeholder for state additions + reset behavior]
[Describe the main methods, their inputs, outputs, and critical edge cases. Include pseudocode for non-obvious algorithms.]
| Method | Signature | Purpose |
|---|---|---|
[methodName] |
[params] => [return] |
[What it does] |
[methodName] |
[params] => [return] |
[What it does] |
[Describe DOM structure, rendering patterns, event handling approach, and any reactive/dirty-check patterns.]
| File | Change Type | Description |
|---|---|---|
[file path] |
New | [What the new file does] |
[file path] |
Modify | [What changes] |
[file path] |
Modify | [What changes] |
Reviewer: [Agent name / "Senior Architect" role] Date: YYYY-MM-DD Scope: Full spec review against coding standards and architectural principles.
[Pending review...]
- [Action item #1]
- [Action item #2]
- [Action item #3]
-
[Edge case title]. [Description and expected behavior.]
-
[Edge case title]. [Description and expected behavior.]
-
[Edge case title]. [Description and expected behavior.]
- [Constraint]. [Why this constraint exists.]
- [Constraint]. [Why.]
- [Constraint]. [Why.]
AGENT INSTRUCTION: Log any agreed technical deviations here. You must obtain developer approval before deviating from this spec.
| # | Phase | Category | Original Spec | Actual Implementation | Rationale | Approver |
|---|---|---|---|---|---|---|
| 1 | - | - | - | - | - | Developer |
AGENT INSTRUCTION: Log significant bugs encountered during implementation. This builds institutional knowledge for future features.
- Bug: [Description of what went wrong]
- Fix: [How it was resolved]
- Learning: [What to remember for future features]
Some features require preparatory refactoring before the feature itself can be built. Extracting a shared utility, renaming a parameter, or decoupling two modules. Bundling these into a "Phase 0" before the feature phases has two benefits:
- The refactor is committed and tested in isolation, so if the feature is later paused or reverted, the codebase still benefits.
- The feature phases start on a clean foundation with no "oh, and also refactor this" distractions.
Complex features often depend on infrastructure built by earlier features. Noting these dependencies at the top of the spec (e.g., "Prerequisite: The Modifier Engine must be implemented through Phase 5") prevents agents from starting work that requires unfinished foundations.
For features that touch many files, explicitly listing files and systems that are not affected can be as valuable as listing what changes. This prevents the agent from "helpfully" modifying adjacent systems outside the spec's scope.
For features with input/output relationships (URL routing, mode selection, cost calculations), a table of expected inputs and outputs serves as both documentation and a test plan:
| Input | Expected Output |
|---|---|
| [valid input A] | [expected result] |
| [valid input B] | [expected result] |
| [invalid input C] | [expected fallback] |
| [boundary input D] | [expected handling] |
For features involving multi-step flows (user action to system response to state change), a text-based sequence diagram in the spec prevents the agent from wiring things in the wrong order. Markdown code blocks with ASCII arrows work well enough:
User clicks button
|
[Guard checks]
|
[State mutation]
|
[Side effect: SFX, animation]
|
[UI re-render]
At the end of complex specs, a table mapping your coding standard IDs to how they are addressed in the spec serves as a pre-flight verification:
| Standard | How Addressed |
|---|---|
| CODE_04 (No Magic Values) | All thresholds in config block (Section 3.1) |
| ARCH_01 (Strict Decoupling) | New module has zero cross-module mutation |
| CODE_09 (Event Delegation) | Single container listener, not per-child |
This is particularly useful as a review checkpoint: if you cannot fill in the "How Addressed" column, the spec has a gap.
Distinct from the "Deviations" section, an implementation decision log captures choices made during development that the spec left open. These are not deviations from the plan; they are decisions the plan deliberately deferred to implementation time ("UX tuning decision", "value TBD from playtesting").
Keeping this log in the spec preserves the reasoning. Without it, these micro-decisions evaporate when the session ends.
Q: How long does it take to write a spec? A: With the agent co-authoring, a standard spec takes 15-30 minutes. A full spec for a complex feature takes 30-60 minutes. This is dramatically faster than writing it alone, and the time is recovered tenfold during implementation.
Q: What if the spec is wrong? A: That is what the architect review and the deviation log are for. The spec is not a contract; it is a best-effort plan that adapts to reality through a governed process. A spec that is 80% right and 20% revised through logged deviations is infinitely better than no spec at all.
Q: Should I use this for every change? A: No. Bug fixes, config tweaks, copy changes, and other small changes do not need a spec. Use the decision heuristic from Part 1: if the agent could cause meaningful damage working unsupervised, write a spec.
Q: What if I work with multiple agents across different tools? A: The spec is tool-agnostic. It is a markdown file in your repo. Any agent that can read files can consume it. The handoff prompts in Part 2 work with any conversational AI coding tool.
Q: Where should I store specs in my project?
A: A roadmap/ directory at the project root is a common pattern. Active specs live in roadmap/. Completed specs move to roadmap/resolved/. This keeps the root clean and the archive intact.
Q: How does this relate to the project-context skill? A: They are complementary. The project-context skill gives the agent a persistent mental map of the codebase (architecture, patterns, gotchas). The feature spec gives the agent a mission-specific execution plan for one feature. The spec references coding standards and patterns defined in the context skill. Together, they form a complete briefing: "here is the project, and here is what we are building today."