Skip to content
specdacular

Quickstart

This tutorial walks you through planning and executing your first feature with specdacular. You’ll map your codebase, initialize a task, and drive it through the full lifecycle.

Time: ~10 minutes Prerequisites: specdacular installed, Claude Code running in your project

What you’ll build

Section titled “What you’ll build”

By the end of this tutorial you’ll have:

  • A codebase map in .specd/codebase/ that Claude can reference forever
  • A fully planned feature in .specd/tasks/user-auth/
  • Hands-on experience with the three core commands: new, continue, and status

  1. Map your codebase

    Section titled “Map your codebase”

    Before planning features, give Claude context about your project. Run this inside Claude Code:

    /specd.codebase.map

    Specdacular spawns 4 parallel agents that each explore a different aspect of your code:

    AgentOutputAnswers
    MapMAP.mdWhere is X? What functions exist?
    PatternsPATTERNS.mdHow do I write code that fits here?
    StructureSTRUCTURE.mdWhere do I put new code?
    ConcernsCONCERNS.mdWhat will bite me?

    Wait for all four agents to finish. You’ll see a confirmation when .specd/codebase/ is ready.

  2. Initialize your first task

    Section titled “Initialize your first task”

    Now create a task. Give it a short, kebab-case name:

    /specd.new user-auth

    Specdacular creates .specd/tasks/user-auth/ and starts the first discussion. Claude will ask what you’re building. Answer naturally — describe the feature, its constraints, and any decisions you’ve already made.

    Claude probes gray areas until the requirements are clear, then writes:

    • FEATURE.md — Technical requirements from your conversation
    • CONTEXT.md — Discussion transcript that accumulates over time
    • DECISIONS.md — Any decisions made, with rationale and date
    • STATE.md — Current position in the lifecycle
    • config.json — Task configuration

    When discussion wraps up, Claude will offer to continue or stop. For this tutorial, stop here so you can see the resume flow.

  3. Check your task status

    Section titled “Check your task status”
    /specd.status

    You’ll see a dashboard like:

    # Task Status
    

    _1 feature, 1 in progress_
    

    | Feature   | Stage      | Plans | Created    | Next Action         |
    |-----------|------------|-------|------------|---------------------|
    | user-auth | discussion | —     | 2025-01-15 | Continue discussion |

    Use --all to include completed tasks: /specd.status --all

  4. Drive the lifecycle with continue

    Section titled “Drive the lifecycle with continue”

    This is the most important command in specdacular. Run it now:

    /specd.continue user-auth

    The brain reads your task’s current state and determines the next step. From fresh discussion it will move into research — spawning parallel agents to find integration patterns and potential pitfalls in your specific codebase.

    After research, continue will move to planning, producing ROADMAP.md with phases derived from dependency analysis. Phase goals only — no detailed implementation plans yet.

    At each natural stopping point, you can:

    • Continue to the next stage
    • Stop and pick up later with /specd.continue user-auth

  5. Execute a phase

    Section titled “Execute a phase”

    Once planning is complete, continue enters the phase-execution loop. For each phase:

    1. Plan — Creates a detailed PLAN.md just-in-time from the roadmap goal
    2. Execute — Implements the plan, commits progress
    3. Review — A code review agent compares implementation against intent
    4. Revise — If review finds issues, creates fix plans (decimal phases like phase-01.1)

    You’ll be prompted before execution and review so you can inspect plans and approve code.

  6. You’re done

    Section titled “You’re done”

    When all phases complete, you’ll see:

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

    Task: user-auth
    Phases completed: 3
    Decisions made: 7
    

    All phases executed and reviewed. Task is done!

What’s next

Section titled “What’s next”