Create Implementation Spec

Create an implementation spec for $ARGUMENTS.

---

Outcome

A complete implementation spec written to the configured specs location that captures:

• What to build and why
• Key decisions with rationale
• Concrete implementation steps
• Edge cases and error handling
• Testing approach and scope boundaries

---

Acceptance Criteria

The spec file must contain these sections:

Section	Purpose
## Overview	What this feature does and why it matters
## Decisions	Key technical choices with rationale
## Implementation Steps	Ordered, actionable steps to build it
## Edge Cases	Error handling, boundary conditions, failure modes

Additional sections are welcome but these four are required.

Quality signals:

• Decisions reference actual codebase patterns (not generic advice)
• Implementation steps are specific to this codebase (file paths, function names)
• Edge cases reflect real constraints discovered in research

---

Constraints

Context Isolation

Research and writing happen in isolated subagent contexts to preserve main context for user interaction.

Phase	Agent	Model	Why
Research	codebase-explorer	inherit	Fast exploration without polluting main context
Writing	writer	inherit	Synthesis in isolation; has full research + interview context

Use the Task tool with the appropriate agent. The subagents have user-invocable: false so they're only accessible via Task.

User Interview Required

The user must be interviewed before writing. Research informs questions; questions surface decisions the user wouldn't think to mention.

Interview must cover:

• Core technical decisions (patterns, approaches, tradeoffs)
• Edge cases and error handling preferences
• Testing approach
• Scope boundaries (what's explicitly out)

Use AskUserQuestion. Good questions are informed by research, about tradeoffs, and codebase-specific.

File Locations

• Config: <git-root>/.bonfire/config.json contains specsLocation
• Default: .bonfire/specs/ if not configured
• Naming: <issue-id>-<topic>.md or <topic>.md

Verification

After writing, verify the spec contains all 4 required sections. If incomplete:

• Warn user what's missing
• Offer: proceed / retry / abort

Session Context

After writing the spec, add a reference to it in <git-root>/.bonfire/index.md under Current State. This links the spec to the session that created it.

Completion

After verification, confirm spec creation and offer options:

• Proceed with implementation
• Refine specific sections
• Save for later

---

Guidance (Not Rules)

These patterns tend to work well, but adapt as needed:

Research before interviewing - Findings make questions specific and valuable.

Three interview rounds - Core decisions → Edge cases → Testing & scope. But collapse if user is time-constrained.

Show your work - Tell user what you're doing: "Researching...", "Starting interview...", "Writing spec..."

Fallback gracefully - If subagent fails, do the work in main context. Warn user but don't stop.

Large codebases - Explorer may need multiple passes. Offer to continue if findings seem incomplete.

Writer context - When invoking the writer agent, specify document type as "spec" so it uses the correct format.

---

Anti-Patterns

Don't ask generic questions - "What features do you want?" wastes an interview slot.

Don't skip the interview - Research alone misses user intent. Interview alone misses codebase reality.

Don't write without verification - Subagents can produce partial output. Always check.

Don't over-specify implementation - Steps should guide, not micromanage. Leave room for implementation judgment.