SpecKit Companion

• Define requirements with structured specs
• Track progress through Specify → Plan → Tasks → Done
• Review with inline comments, just like a code review
• Extend with custom workflows, commands, and any AI assistant

Features

Visual Workflow Editor

Guide your features through structured phases with a dedicated editor that renders markdown specs, shows phase progress, and provides one-click actions for each step. Mermaid diagrams render inline with zoom controls for navigating complex diagrams.

Inline Review Comments

Review spec documents with inline comments. Add feedback directly on specific lines, refine requirements, and collaborate on specs before implementation begins.

Create Specs Visually

Create new specs with a dedicated dialog — write a detailed description, select your workflow, and attach screenshots or mockups for context.

Spec-Driven Phases

Each feature flows through four phases:

Specify — Define requirements with user stories and acceptance scenarios.

Plan — Create the technical design with research, data models, and implementation strategy.

Tasks — Generate an implementation checklist with progress tracking and parallel execution markers.

Sidebar at a Glance

The sidebar organizes everything your AI assistant needs: Specs for feature development, Steering for AI guidance documents, Agents for custom agent definitions, Skills for reusable capabilities, and Hooks for automation triggers.

Specs are grouped into three collapsible sections based on their status (stored in .spec-context.json):

• Active — Specs in progress, sorted by creation date (newest first), expanded by default
• Completed — Specs marked as done, collapsed by default
• Archived — Specs moved to archive, collapsed by default

Right-click a spec to access Mark as Completed and Archive Spec actions. The spec viewer footer shows lifecycle buttons based on the spec's current status:

• Active (tasks incomplete): Regenerate, Archive, + primary CTA (Plan/Tasks/Implement depending on next step)
• Active (tasks 100% complete): Archive + Complete (primary)
• Completed: Archive + Reactivate
• Archived: Reactivate only

The lifecycle flow is Active → Completed → Archived, with Reactivate available on Completed and Archived specs to return them to Active.

Transition logging: Every workflow step change is automatically recorded in the transitions array inside .spec-context.json. Each entry captures the previous step, new step, source (extension or sdd), and timestamp. External changes (e.g., from SDD tools) are detected via file watcher and logged to the SpecKit output channel.

Badge and dates are derived from .spec-context.json (the single source of truth for workflow state):

• The badge in the metadata bar shows the current workflow state (e.g., SPECIFYING, PLANNING, IMPLEMENTING, COMPLETED). Hidden when no context exists.
• Created and Last Updated dates are derived from stepHistory timestamps in .spec-context.json. Gracefully omitted when context is missing or incomplete.
• Specs with only a .spec-context.json (no markdown files yet) still appear in the explorer, so SDD in-progress specs are always visible.

Color indicators:

• Green beaker icon — completed spec
• Blue beaker icon — spec with an active workflow step
• Green check — completed step
• Green pulsing glow — step actively being worked on
• Blue dot — current step

When a workflow step command is running for a spec, the spec node displays a spinning progress indicator instead of its default icon.

Custom Workflows & Commands

SpecKit Companion isn't tied to a single methodology. Swap out the default phases for any SDD workflow — Agent Teams Lite, your own team's process, or anything that uses commands and produces markdown files. Define custom steps, labels, output files, and sub-documents. Add custom commands that appear as action buttons in specific phases (e.g., Verify, Archive, Commit, Create PR).

The sidebar, progress tracking, and workflow editor all adapt automatically to your custom workflow. See Configuration below.

Getting Started

1. Install the extension from a .vsix file or the VS Code marketplace
2. Open the sidebar — click the SpecKit icon in the activity bar
3. Create a spec — click the + button in the Specs view to start your first feature

Supported AI Providers

Configure your preferred provider: Settings > speckit.aiProvider

Configuration

Permission Mode

Controls whether AI CLIs run with permission prompts (safe) or bypass them (YOLO):

{
  "speckit.permissionMode": "interactive"
}

This applies to all providers that support it: Claude (--permission-mode bypassPermissions), Copilot (--yolo), and Qwen (--yolo). Gemini and Codex ignore this setting.

Command Format

Controls how speckit commands are formatted when sent to AI providers:

{
  "speckit.commandFormat": "auto"
}

Use auto unless your speckit version requires a specific command format. Override with dot or dash when the provider's default doesn't match what your setup expects.

Spec Directories

By default, specs live in specs/. You can configure multiple directories or use glob patterns:

{
  "speckit.specDirectories": ["specs", "openspec/changes/*"]
}

Simple names (e.g., specs) list their children as specs. Patterns with wildcards treat each match as a spec folder.

Custom Workflows

Define alternative workflows with custom steps, output files, and sub-documents. Any SDD methodology that uses commands and produces markdown files can be plugged into SpecKit Companion.

Real-world example — Agent Teams Lite

Here's a full configuration using Agent Teams Lite, a multi-agent SDD framework:

{
  "speckit.customWorkflows": [
    {
      "name": "agent-teams-lite",
      "displayName": "Agent Teams Lite (SDD)",
      "description": "Multi-agent SDD workflow",
      "steps": [
        { "name": "specify", "label": "Spec",   "command": "sdd-spec",   "file": "spec.md", "subDir": "specs" },
        { "name": "plan",    "label": "Design", "command": "sdd-design", "file": "design.md", "includeRelatedDocs": true },
        { "name": "tasks",   "label": "Tasks",  "command": "sdd-tasks",  "file": "tasks.md" }
      ]
    }
  ],
  "speckit.specDirectories": ["specs", "openspec/changes/*", "openspec/changes/archive/*"],
  "speckit.customCommands": [
    { "name": "verify",  "title": "Verify",  "command": "/sdd-verify",  "step": "tasks", "tooltip": "Validate implementation matches specs" },
    { "name": "archive", "title": "Archive", "command": "/sdd-archive", "step": "tasks", "tooltip": "Archive completed change" }
  ]
}

Notice how custom workflows, spec directories, and custom commands work together:

• The workflow defines Spec → Design → Tasks phases with custom labels and commands
• specDirectories tells the sidebar where to find specs (including archived ones)
• Custom commands add Verify and Archive buttons to the Tasks phase

Basic example — remap default steps

{
  "speckit.customWorkflows": [
    {
      "name": "sdd",
      "displayName": "SDD Workflow",
      "steps": [
        { "name": "specify",   "label": "Specify",   "command": "sdd.specify",   "file": "spec.md" },
        { "name": "plan",      "label": "Plan",      "command": "sdd.plan",      "file": "plan.md" },
        { "name": "tasks",     "label": "Tasks",     "command": "sdd.tasks",     "file": "tasks.md" },
        { "name": "implement", "label": "Implement", "command": "sdd.implement", "actionOnly": true }
      ],
      "commands": [
        {
          "name": "auto",
          "title": "Auto Mode",
          "command": "sdd:auto",
          "step": "specify",
          "tooltip": "Goes through the whole specification in auto mode"
        }
      ]
    }
  ]
}

Workflow Commands

Workflows can define commands — extra action buttons that appear next to the primary action for a given step. For example, a command with "step": "specify" renders as a button next to Submit in the spec editor.

{
  "commands": [
    {
      "name": "auto",
      "title": "Auto Mode",
      "command": "sdd:auto",
      "step": "specify",
      "tooltip": "Runs the full pipeline automatically"
    }
  ]
}

Commands with step: "specify" appear as secondary buttons next to Submit in the spec creation dialog. Multiple commands per step are supported.

Steps with sub-files

Steps can declare child documents that appear as expandable items in the sidebar:

{
  "steps": [
    {
      "name": "plan",
      "label": "Plan",
      "command": "speckit.plan",
      "file": "plan.md",
      "subDir": "plan"
    }
  ]
}

This scans plan/ for .md files and shows them as children of the Plan step. You can also use an explicit list:

{
  "subFiles": ["plan/architecture.md", "plan/api-design.md"]
}

Step Properties

Behavior

• The sidebar shows only the steps declared by the active workflow
• Steps with missing output files appear as "not started"
• Steps with actionOnly: true are action-only — they appear in the workflow editor but not in the file tree
• When a spec is created via the editor, the selected workflow is automatically persisted to .spec-context.json in the spec directory
• If no workflow is selected, the speckit.defaultWorkflow setting is used (falls back to the built-in default)
• Once persisted, all subsequent operations (viewer, step execution, command palette) use the same workflow consistently
• The default workflow (spec.md → plan.md → tasks.md → implement) is always available

Custom Commands

Add custom slash commands that appear in the workflow editor and the SpecKit: Run Custom Command picker.

{
  "speckit.customCommands": [
    "review",
    {
      "name": "commit",
      "title": "Commit Changes",
      "command": "/speckit.commit",
      "step": "tasks",
      "tooltip": "Generate a commit for completed work",
      "requiresSpecDir": false
    },
    {
      "name": "pr",
      "title": "Create PR",
      "command": "/speckit.pr",
      "step": "tasks",
      "tooltip": "Create a pull request for the feature"
    }
  ]
}

Properties:

• name — Command identifier
• title — Display name in picker
• command — Slash command to execute
• step — Phase to show in: spec, plan, tasks, or all (default)
• tooltip — Description shown on hover
• autoExecute — Auto-run in terminal (default: true)
• requiresSpecDir — Inject spec directory (default: true)

Development

Setup

git clone https://github.com/alfredoperez/speckit-companion.git
cd speckit-companion
npm install
npm run compile

Running

1. Open the project in VS Code
2. Press F5 to launch Extension Development Host

Building

npm run package
# Output: speckit-companion-{version}.vsix

Platform Support

Acknowledgments

This project started from the amazing work at https://github.com/notdp/kiro-for-cc

License

MIT License