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.

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.

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

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 multiple workflows exist, you're prompted to choose when starting a new spec
• 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