Skip to content
specdacular

Your First Feature

This guide walks through a complete feature lifecycle — from empty project to shipped code. We’ll use a user authentication feature as the example.

Before you start

Section titled “Before you start”

Make sure you have:

  • specdacular installed
  • Claude Code open in your project
  • Git initialized (specdacular commits progress automatically)

Step 1: Map your codebase

Section titled “Step 1: Map your codebase”

Every feature benefits from codebase context. Start by running:

/specd.codebase.map

Four agents will run in parallel and write to .specd/codebase/. When complete, you’ll have:

  • MAP.md — A function-level map of your codebase
  • PATTERNS.md — Coding conventions and patterns Claude should follow
  • STRUCTURE.md — Directory layout and where new code should go
  • CONCERNS.md — Tech debt, gotchas, and things to avoid

This takes a few minutes for large codebases. For small projects (under 10 files) you can skip this step — specdacular works fine without it.

Step 2: Initialize the feature

Section titled “Step 2: Initialize the feature”
/specd.new user-auth

Claude will ask: “What are you building?” Describe the feature. For our example, something like:

“I need user authentication — email/password signup, login, logout, and protected routes. We’re using Express on the backend with PostgreSQL. JWT tokens for sessions. Password reset via email eventually but not in this first version.”

Claude will follow up with questions:

  • How should tokens be stored? (Cookies vs. localStorage)
  • Do we need refresh tokens or will short-lived JWTs be fine?
  • Is there an existing user table or are we creating one?
  • What routes need protection?

Answer each question. When Claude has what it needs, it writes FEATURE.md with the technical requirements and offers to continue or stop.

Step 3: Run research

Section titled “Step 3: Run research”
/specd.continue user-auth

With discussion complete, continue moves to research. Three parallel agents investigate:

  1. Codebase integration — How does auth fit into your existing code? What patterns does your codebase use?
  2. External patterns — What are the established approaches for JWT auth in your stack?
  3. Pitfalls — What are the common mistakes and security concerns?

Results are written to RESEARCH.md. You’ll see a summary when research completes.

Step 4: Review and approve the plan

Section titled “Step 4: Review and approve the plan”

After research, continue moves to planning. Claude analyzes the research findings and creates ROADMAP.md with phases like:

Phase 1: Database schema and user model
Phase 2: Registration and login endpoints
Phase 3: JWT generation and middleware
Phase 4: Protected routes and session handling

Review the roadmap. If something looks off, run /specd.toolbox user-auth and choose Discuss to adjust requirements before execution begins.

Step 5: Execute phase by phase

Section titled “Step 5: Execute phase by phase”

When you run continue again, it enters the phase-execution loop. For Phase 1, it will:

  1. Plan — Write a detailed PLAN.md from the roadmap goal. This is what the implementing agent will receive.
  2. Pause — Show you the plan and ask: “Execute, Review plan, or Stop for now?”
  3. Execute — Implement the plan. Commits as it goes.
  4. Review — A code review agent checks the implementation against the plan.
  5. Approve or revise — You approve the phase or request fixes.

Repeat for each phase. Later phases can adapt based on what was learned in earlier ones.

Step 6: Handle review feedback

Section titled “Step 6: Handle review feedback”

The review agent compares what was built against what was planned. If it finds deviations:

  • Issues are documented in the review output
  • A fix plan is created (e.g., phases/phase-01.1/PLAN.md)
  • continue loops back to execute the fix plan

You can approve partial fixes or iterate until the review passes.

Step 7: Task complete

Section titled “Step 7: Task complete”

When all phases pass review:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 TASK COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


Task: user-auth
Phases completed: 4
Decisions made: 12


All phases executed and reviewed. Task is done!

What you end up with

Section titled “What you end up with”
.specd/tasks/user-auth/
├── FEATURE.md        # Requirements
├── CONTEXT.md        # Full discussion history
├── DECISIONS.md      # All decisions with rationale
├── CHANGELOG.md      # Implementation log
├── RESEARCH.md       # Research findings
├── ROADMAP.md        # Phase overview
├── STATE.md          # Completion status
├── config.json       # Task metadata
└── phases/
    ├── phase-01/PLAN.md
    ├── phase-02/PLAN.md
    ├── phase-03/PLAN.md
    └── phase-04/PLAN.md

Every decision, every research finding, every implementation choice is documented and committed to git.

Tips

Section titled “Tips”

Don’t over-specify up front. The discussion + research + just-in-time planning flow handles discovery naturally. You don’t need to know every detail before starting.

Use --interactive on complex features. When you want control at every step:

/specd.continue user-auth --interactive

Stop and resume freely. The brain saves state before every dispatch. You can stop mid-pipeline and pick up days later:

/specd.continue user-auth

Use toolbox for out-of-band work. If you make ad-hoc changes and want to re-run review:

/specd.toolbox user-auth

Then choose Review.

Next steps

Section titled “Next steps”