Autonomous Development Workflow

Overview

Generate comprehensive documentation that enables autonomous agents to implement features, fixes, or changes without constant human supervision. All work is tracked in session docs (spec, plan, tasks) that serve as long-term memory across implementation sessions.

When to Use This Skill

Use this skill when:

• Working on well-defined features or fixes
• Work can be fully specified upfront
• Implementation can proceed autonomously with minimal supervision
• Long-term session memory is desired for tracking progress

Do NOT use for:

• Exploratory work requiring human decisions at each step (use dev-guided instead)
• Trivial changes that don't require planning
• Quick iterations where formal documentation is overhead

Workflow Phases

This workflow consists of 5 phases. Some run interactively in the main conversation (requiring user input), while others can run as autonomous subagents.

Phase 1: Specification (Interactive)

Generate a comprehensive design specification through iterative questioning.

Process:

1. Examine the project to understand current state
2. Ask ONE question at a time (preferring multiple choice)
3. Refine understanding through Q&A until certain
4. Present specification in 200-300 word sections
5. Get approval for each section before proceeding
6. Write final spec to docs/development/NNN-<name>/spec.md

Reference: See references/phase-spec.md for detailed guidance

User involvement: Answer questions, approve spec sections

Phase 2: Planning (Interactive or Subagent)

Create detailed implementation plan assuming implementer has minimal context.

Approach:

1. Tech stack selection (when needed) - Research and document library/framework choices
2. File/module mapping - Exact paths for new/modified code
3. Dependency order - Build sequence so later pieces have foundations
4. Integration points - How new code connects to existing code
5. Risk flags - Potentially tricky parts
6. Testing guidance - What to test, where tests go

CRITICAL: No code in the plan. Describe what needs to be built, not how to code it.

Reference: See references/phase-plan.md for detailed requirements

For subagent implementation: See references/templates/subagent-plan.md for prompt template

Output: docs/development/NNN-<name>/plan.md

User involvement: Review and approve the plan

Phase 3: Task Extraction (Interactive or Subagent)

Break down the plan into trackable tasks.

Task format:

- [ ] Task description (Plan lines: XX-YY)

Task granularity: Each task should deliver coherent, testable functionality. NOT file operations or single-line changes.

Reference: See references/phase-tasks.md for extraction rules

For subagent implementation: See references/templates/subagent-tasks.md for prompt template

Output: docs/development/NNN-<name>/tasks.md

User involvement: Review task list

Phase 4: Implementation (Autonomous - Subagent or External Agent)

Implement tasks one at a time in isolated sessions.

Implementation Options:

Option A: Claude Subagent

• Spawn fresh subagent for each task
• Embed full context in prompt (spec sections, plan section, project context)
• Subagent implements according to plan (NO deviation)
• Follows TDD/DRY/YAGNI
• Reports completion but does NOT mark complete or commit yet

Reference: See references/phase-impl.md for implementation constraints

For subagent implementation: See references/templates/subagent-impl.md for prompt template

Option B: External Coding Agent

• Provide agent with task list, spec, plan file paths
• Provide agent with references/phase-impl.md instructions
• Agent implements next uncompleted task
• Agent reports completion (does NOT mark complete or commit)

Option C: Human Implementation

• Read next task from tasks.md
• Read corresponding spec and plan sections
• Implement according to plan
• Report completion for review

User involvement: Choose implementation method, trigger each task

Phase 5: Review (Interactive)

Review completed work before marking complete.

Process:

1. Read the spec, plan section, and implementation
2. Check against requirements, code quality, tests
3. Provide specific feedback OR sign-off
4. Route feedback to implementer if issues found
5. After sign-off, authorize task completion and commit

Reference: See references/phase-review.md for review checklist

User involvement:

• Trigger review after implementation completes
• Authorize task completion and commit after sign-off

Session Memory

All artifacts in docs/development/NNN-<name>/ serve as long-term memory:

docs/development/NNN-<name>/
├── spec.md       # What we're building (design specification)
├── plan.md       # How we're building it (implementation plan)
└── tasks.md      # Implementation checklist with progress tracking

These files enable:

• Resuming work after interruption (check tasks.md for progress)
• Context for autonomous agents (read spec + plan + task)
• Historical record of implementation decisions
• Progress tracking across multiple sessions

Using This Skill

Full Workflow

Invoke this skill and say:

"I want to implement [feature/fix description]"

The skill will guide through all 5 phases.

Individual Phases

Invoke specific phases when needed:

• "Start spec phase" - Begin specification
• "Generate plan from spec" - Create plan (provide spec path)
• "Extract tasks from plan" - Create task list (provide plan path)
• "Implement next task" - Implement next uncompleted task (provide task list path)
• "Review implementation" - Review completed work (provide task number)

Resuming After Interruption

If interrupted mid-workflow:

1. Read docs/development/NNN-<name>/tasks.md to see completed tasks
2. Continue with next uncompleted task
3. The autonomous agent will pick up from current progress

Modifying the Plan

If plan needs adjustment during implementation:

1. Edit docs/development/NNN-<name>/plan.md
2. Update affected tasks in tasks.md
3. Continue implementation with updated plan

For Autonomous Agents

When implementing tasks autonomously (subagents or external agents), follow this critical principle:

Subagents start with NO context. They cannot discover information on their own. For reliable results, embed all necessary content directly in the prompt:

1. Full content of relevant reference files (not just paths)
2. Full content of spec sections (not just the file path)
3. Specific plan sections extracted by line number
4. Project context (test commands, file locations, patterns)

Templates: Use the prompt templates in references/templates/ which show exactly what content to embed for each phase.

Key Principles

1. Separation of concerns - Design, implementation, and review are distinct phases
2. Plan adherence - Autonomous implementers follow the plan strictly
3. Rich context for agents - Embed content in prompts, not just file paths
4. Incremental commits - Each task gets its own commit after review sign-off
5. Session memory - All artifacts persist for long-term tracking
6. Quality gates - Nothing marked complete without review sign-off

Resources

Detailed phase instructions in references/:

• phase-spec.md - Specification generation guidance
• phase-plan.md - Planning requirements and format
• phase-tasks.md - Task extraction rules
• phase-impl.md - Implementation constraints
• phase-review.md - Review checklist

Subagent prompt templates in references/templates/:

• subagent-plan.md - Planning subagent template
• subagent-tasks.md - Task extraction subagent template
• subagent-impl.md - Implementation subagent template