Skip to content

vt-c-activate

Load specs for development from specs directories or directly from a PRD. Computes execution sequence from dependencies and guides through the build cycle.

Plugin: core-standards
Category: Project Setup
Command: /vt-c-activate

/vt-c-activate — Spec Activation Manager

Unified Repo Workflow: PRD/PID → /vt-c-activate → /vt-c-2-plan → /vt-c-3-build → /vt-c-4-review → /vt-c-complete → next spec

Creates specs/[N]-feature/ directories per SpecKit convention. Accepts input from: - --from-prd: Reads a PRD directly, breaks it into feature-sized specs (preferred path) - specs directory: Legacy path — reads existing specs files and copies as spec.md

Purpose

Manages the spec execution lifecycle in a unified repo: 1. Generates specs from PRD directly (--from-prd) or loads existing specs 2. Sequences specs by dependency order and priority 3. Activates one spec at a time into specs/[N]-feature/spec.md 4. Tracks completion and auto-advances to the next ready spec 5. Shows a dashboard of execution progress

When to Use

  • After completing product design validation (/vt-c-pd-4-validate)
  • After /vt-c-pd-6-handoff transitions the repo to development mode
  • When starting work on the next feature (between /vt-c-4-review and /vt-c-2-plan)
  • To check overall progress (--status)

Prerequisites

  • Either a PRD file (for --from-prd mode) or a specs directory with at least one specs file
  • specs files should have spec_id in their metadata (auto-assigned from filename if missing)

Invocation

/vt-c-activate                     # Show wave dashboard, choose execution mode
/vt-c-activate BUG-007             # Activate bug — create fix/bug-007-* branch
/vt-c-activate --from-prd PATH     # Generate specs directly from a PRD (no specs needed)
/vt-c-activate spec-2              # Activate specific specs by filename (legacy)
/vt-c-activate SPEC-002            # Activate specific specs by ID
/vt-c-activate --status            # Show sequence dashboard only

Execution Steps

Step 1: Scan specs Directory

1a: Locate specs Directory

Search for spec files in these locations (first match wins): 1. specs/ (standard convention) 2. 05-specs/ (legacy template, with space) 3. 05-specs/ (legacy hyphen variant) 4. docs/specs/ (knowledge-work projects) 5. specs/ (legacy, no prefix) 6. Check .repo-manifest.yaml context paths for any directory containing "spec" (case-insensitive)

If no spec directory found in standard locations, prompt the user:

AskUserQuestion — "No spec directory found in standard locations. Where are your specs?" - Option 1: "Let me specify a path" — user provides a directory path containing spec files. Validate the directory exists, scan for .md files with spec-like content (YAML frontmatter with spec_id, or naming patterns like spec-*.md, SPEC-*.md, specs-*.md). If valid specs found, use that path as specs_directory in .design-state.yaml and continue with Step 1b. - Option 2: "Create specs/ directory" — create specs/ directory and a minimal .design-state.yaml with specs_directory: specs/. Report "Empty spec directory created. Add spec files to specs/ and re-run /activate." Then exit. - Option 3: "Exit" — report error and exit (preserves previous behavior).

1b: Parse specs Metadata

Read all files matching spec-*.md, SPEC-*.md, or specs-*.md (legacy).

For each file, extract metadata using a fallback chain:

1. YAML frontmatter (preferred): 

---
spec_id: SPEC-001
parent_prd: ../03-PRD/PRD.md
dependencies: [spec-0-project-setup]
priority: P0
status: draft
---

2. Markdown table metadata (legacy — used by older specs): 

## Metadata
| Feld | Wert |
|------|------|
| spec_id | SPEC-00 |
| dependencies | Keine |
| priority | KRITISCH |
| status | draft |
Parse table rows: field name in first column, value in second. Map priority values: KRITISCH → P0, HOCH → P0, MITTEL → P1, NIEDRIG → P2.

3. Auto-assign from filename (fallback when no spec_id found): 

spec-0-project-setup.md  → SPEC-000
spec-1-user-auth.md      → SPEC-001
spec-12-admin-panel.md   → SPEC-012

When auto-assigning, report to user: 

Auto-assigned SPEC IDs (no spec_id in metadata):
  spec-0-project-setup.md  → SPEC-000
  spec-1-user-auth.md      → SPEC-001
  ...
Use AskUserQuestion: - Add YAML frontmatter to files (Recommended) — inserts --- block at top of each file - Use auto-assigned IDs for this session only — no file changes

1c: Build Index

{
  "SPEC-000": { file: "spec-0-project-setup.md", deps: [], priority: "P0", name: "Project Setup" },
  "SPEC-001": { file: "spec-1-user-auth.md", deps: ["SPEC-000"], priority: "P0", name: "User Authentication" },
  "SPEC-002": { file: "spec-2-dashboard.md", deps: ["SPEC-001"], priority: "P1", name: "Dashboard Layout" },
  ...
}

Convert dependency references to SPEC IDs: - "spec-0-project-setup" → "SPEC-000" - "SPEC-000" → keep as-is - "Keine" or "None" → empty array

Step 2: Compute Execution Sequence

Perform topological sort on the dependency graph: 1. specs with no dependencies come first 2. Within the same dependency level, sort by priority (P0 before P1 before P2) 3. Within same priority, sort by numeric ID

Detect circular dependencies and report as error.

Step 2b: Compute Execution Waves

Group specs into dependency waves for parallel execution visibility. This extends Step 2's topological sort by assigning wave levels:

Algorithm: 1. Collect all specs with status != completed (using per-spec state.yaml) 2. Let resolved = set of all completed specs 3. Repeat until all specs are assigned: a. wave = specs whose dependencies are ALL in resolved (or have no dependencies) b. If wave is empty and specs remain → circular dependency detected, report error c. Sort wave internally: P0 > P1 > P2, then by numeric SPEC ID d. Add wave to the wave list e. Add all specs in wave to resolved 4. Store wave assignments for use by Step 4 and Step 5

Example output (internal): 

Wave 1: [SPEC-012, SPEC-014, SPEC-015, SPEC-024, SPEC-025]  # no deps / deps completed
Wave 2: [SPEC-006, SPEC-013, SPEC-021, SPEC-022]             # depend on Wave 1 specs
Wave 3: [SPEC-027]                                            # depends on Wave 2 specs

Step 3: Load Activation State

3a: Read or Create .design-state.yaml

If .design-state.yaml exists: 1. Read the file 2. If specs_status section exists → use as-is (static metadata only: file, priority, dependencies, specs_dir) 3. If specs_status section is MISSING (e.g., file exists from design workflow but has no specs tracking): - Add specs_status section with static metadata for all discovered specs - Preserve all existing sections (quality_gates, artifacts, iteration_history, etc.)

If .design-state.yaml does NOT exist: 1. Create it with initial structure: 

current_phase: development
specs_directory: specs/
specs_status:
  SPEC-000:
    file: spec-0-project-setup.md
    priority: P0
    dependencies: []
  # ... one entry per discovered specs (static metadata only)
2. If a specs/[N]-feature/spec.md exists and its content matches a specs file → create specs/[N]-feature/state.yaml with status: in_progress 3. Report: "Created .design-state.yaml from existing specs artifacts."

3a-bis: Derive Active Spec

Determine the active spec using this priority order:

  1. .active-spec file (if exists in project root):
  2. Read the file content (single line: e.g., SPEC-012)

  3. Use this as the active spec (escape hatch for non-standard branches)

  4. Git branch name (if no .active-spec):

  5. Run: git branch --show-current
  6. If branch matches feature/spec-NNN-*: extract NNN → SPEC-NNN

  7. Example: feature/spec-012-design-state-split → SPEC-012

  8. Fallback: No active spec (null)

  9. On main, master, or non-spec branches
  10. Skills should handle this gracefully

3b: Legacy Migration Check

If .speckit/ directory exists (old flat-file structure):

Display: 

⚠ Legacy .speckit/ structure detected.
  SpecKit now uses .specify/ for constitution and specs/[N]-feature/ for spec artifacts.

Use AskUserQuestion: - Migrate now (Recommended) — move files to new locations, remove .speckit/ - Skip — keep legacy for now (warn on each activation)

If migrating: 1. If .speckit/spec.md exists: - Identify which specs it matches (compare content or metadata) - Derive feature name and number from the match - Create specs/[N]-feature/ directory - Move .speckit/spec.md → specs/[N]-feature/spec.md - Move .speckit/plan.md → specs/[N]-feature/plan.md (if exists) - Move .speckit/tasks.md → specs/[N]-feature/tasks.md (if exists) 2. If .speckit/constitution.md exists: - Create .specify/memory/ if it does not exist - Move .speckit/constitution.md → .specify/memory/constitution.md 3. Remove empty .speckit/ directory 4. Update .design-state.yaml with specs_dir for the migrated spec 5. Report what was migrated

3c: Determine Current State

For each spec in .design-state.yaml specs_status: 1. Check if specs/[N]-feature/state.yaml exists 2. If yes: read status from that file 3. If no: treat as proposed (not yet activated)

Merge per-spec state.yaml status with dependency info to classify each: - completed — state.yaml has status: completed - in_progress — state.yaml has status: in_progress - pending — all dependencies met, ready to start (status: proposed or no state.yaml) - blocked — waiting on incomplete dependencies

Step 4: Display Wave-Grouped Dashboard

Display specs grouped by execution wave (computed in Step 2b). This replaces the flat sequential table and makes parallel opportunities immediately visible.

specs Execution Dashboard
═══════════════════════════════════════════════════

Wave 1 — ready now (can work in parallel):
  SPEC-015  IMS Content Workflow       P0  ready
  SPEC-012  Design State Split         P1  ready
  SPEC-014  Unified Init               P1  ready
  SPEC-024  Review Autofix Loop        P1  ready

Wave 2 — after Wave 1 completes:
  SPEC-006  Workflow Sequence Enf.     P1  blocked (SPEC-002)
  SPEC-013  Fork Auto Summary          P1  blocked (SPEC-007)

Wave 3 — after Wave 2 completes:
  SPEC-027  PD Capture Decisions       P2  blocked (SPEC-026)

Progress: 5/20 completed | 0 active | 4 ready | 11 blocked
═══════════════════════════════════════════════════

Rules: - Only show waves that have at least one non-completed spec - Within each wave, sort by priority (P0 first) then by numeric ID - Show status per spec: ready, in_progress, completed, blocked (SPEC-NNN) - Completed specs are omitted from wave display (they're in the progress count)

After the wave table, if bugchen_status: exists in .design-state.yaml AND has at least one entry:

For each entry, read bugs/NNN-slug/state.yaml for live status. Display:

Bug Backlog:
─────────────────────────────────────────────────
  BUG-001  login-fails-safari   high     fix-ready
  BUG-002  export-500-error     medium   triaged
─────────────────────────────────────────────────

Status values: triaged, fix-ready, in_progress, verified

If no bugchen_status: entries: skip this section silently.

If the active SPEC has steps: in its specs/[N]-feature/state.yaml, also display step progress:

Step Progress for SPEC-003 (Step-Level Progress Tracking):
─────────────────────────────────────────────────────────
  Step 1: Setup                    completed
  Step 2: US2 — Plan review step   completed
  Step 3: US1 — Build review gate  in_progress
  Step 4: US3 — Checkpoint field   pending
  Step 5: US4 — PR template        pending

  Progress: 2/5 steps completed | Step 3 in progress

If no steps: exist for the active SPEC, skip this section silently.

Step 5: Handle Invocation Mode

Mode: /vt-c-activate (no argument)

  1. Show wave-grouped dashboard (Step 4)
  2. Show ready specs via AskUserQuestion (single-select):
  3. Options sorted by priority (P0 first), then by ID
  4. Highest priority spec gets "(Recommended)" label
  5. User selects one spec
  6. Proceed to Step 6 (standard single-spec activation)
  7. After activation, if other ready specs exist in the same wave, show a parallel tip: 
    TIP: {N} other specs in Wave 1 can run in parallel (no dependencies on this one):
  SPEC-012, SPEC-014, SPEC-024

To work on them simultaneously:
  1. Open a new terminal/VS Code window
  2. Run: claude --worktree spec-12
  3. Then: /vt-c-activate SPEC-012
  8. If no other ready specs in the same wave: skip the tip

Mode: /vt-c-activate --from-prd PATH (Redirect)

Spec creation is a separate step from activation. Display:

Spec generation has moved to /vt-c-specs-from-prd.
Running it now with your PRD path.

Then delegate to /vt-c-specs-from-prd with the provided path (default: 03-PRD/PRD.md).

Mode: /vt-c-activate BUG-NNN

  1. Parse NNN from the argument (regex: ^BUG-\d+$)
  2. Glob bugs/NNN-*/ to find the bug directory
  3. If not found → error: 
    BUG-NNN not found in bugs/.
Run /vt-c-triage-bugs to promote it from intake first.
  4. Read bugs/NNN-slug/state.yaml
  5. If status is not fix-ready OR bugs/NNN-slug/investigation.md does not exist → warn: 
    ⚠ BUG-NNN is not ready for a fix branch.
  Status: [status] (expected: fix-ready)
  Investigation file: [present | MISSING]
Consider running /vt-c-investigate-bug BUG-NNN first.
Proceed anyway?
    Use AskUserQuestion: Proceed | Cancel — run /vt-c-investigate-bug BUG-NNN first
  6. Determine branch name: fix/bug-NNN-short-name (short-name = slug portion from bug dir, e.g. bugs/007-login-safari/ → fix/bug-007-login-safari) Check if branch already exists: git branch --list fix/bug-NNN-*
  7. If branch exists: use AskUserQuestion — Check out existing branch | Cancel
  8. If branch does not exist: run git checkout -b fix/bug-NNN-short-name
  9. Display bug context:
  10. Read and display key sections of bugs/NNN-slug/report.md (severity, steps, expected, actual)
  11. If bugs/NNN-slug/investigation.md exists: display "Investigation available — see bugs/NNN-slug/investigation.md"
  12. Confirmation: 
    Activated: BUG-NNN — [title]
Branch: fix/bug-NNN-short-name

Next steps:
  /vt-c-3-build    — implement the fix
  /vt-c-4-review   — review the fix
  /vt-c-complete   — mark bug verified

Mode: /vt-c-activate spec-N or /vt-c-activate SPEC-NNN (Legacy)

  1. Look up the requested specs
  2. Check if dependencies are met
  3. If blocked: "SPEC-004 is blocked by SPEC-003 (not yet completed). Activate anyway?"
  4. If ready or user confirms: proceed to Step 6

Mode: /vt-c-activate --complete (backward compatibility)

If --complete is passed, display: 

Completion has moved to /vt-c-complete. Running it now.
Then delegate to /vt-c-complete.

Mode: /vt-c-activate --status

  1. Show dashboard only (Step 4)
  2. Do not activate anything

Step 6: Activate specs

  1. Check current state: Derive active spec from branch (Step 3a-bis). If a different spec is currently in_progress (check per-spec state.yaml files): 

    specs currently in_progress: SPEC-002 (Dashboard Layout)
Replace with SPEC-003 (Data Import)?

  2. Read specs file: Load from discovered specs directory (Step 1a)

  3. Create SpecKit directory: Derive the feature directory name from the specs filename:

  4. spec-3-data-import.md → specs/3-data-import/
  5. Create specs/[N]-feature/ directory

  6. Copy specs content into specs/[N]-feature/spec.md

  7. Ensure constitution exists: If .specify/memory/constitution.md does not exist:

  8. Check for 03-PRD/PRD.md
  9. Extract project principles and constraints
  10. Create .specify/memory/ directory if needed

  11. Create .specify/memory/constitution.md

  12. Create per-spec state.yaml: Write specs/[N]-feature/state.yaml: 

    status: in_progress
activated_at: "2026-02-13T10:00:00"
completed_at: null

  13. Update .design-state.yaml (static metadata only): Add or update the spec entry with static metadata only: 

    specs_status:
  SPEC-003:
    file: spec-3-data-import.md
    priority: P1
    dependencies: [SPEC-001]
    specs_dir: specs/3-data-import/
    Do NOT write status, activated_at, completed_at, steps, or active_specs to .design-state.yaml.

  14. Display confirmation: 

    Activated: SPEC-003 — Data Import

Feature: Data Import functionality for bulk CSV/Excel uploads
Priority: P1
Dependencies: SPEC-001 (User Authentication) — completed
Spec directory: specs/3-data-import/

Development cycle:
  /vt-c-2-plan   → formalize spec, research, plan, and task breakdown
  /vt-c-3-build  → implement the feature
  /vt-c-4-review → code review and spec compliance
  /vt-c-complete  → mark done, advance to next

If steps: exist in specs/[N]-feature/state.yaml from a previous session, also display: 

Step progress (from previous session):
  Steps 1-2 completed, Step 3 in progress
  Next: Step 3 — US1 (Build review gate)

Step 6.5: Deliverable Type Detection

After activation but before merit validation, determine which deliverable types this spec produces.

  1. Read deliverable_types from spec frontmatter: 

    Read: specs/[N]-feature/spec.md
    Check for deliverable_types: in the YAML frontmatter.

  2. If deliverable_types is present and non-empty:

  3. Use as-is
  4. Display: Deliverable types: {list}

  5. Skip to Step 7

  6. If deliverable_types is absent: Run heuristic detection against the spec title, problem, goal, and user stories. Score each type by keyword matches:

Type Keywords
code test, API, CLI, implementation, TDD, module, endpoint, controller, service, component
document guide, manual, policy, documentation, template, handbook, procedure
presentation slide, deck, presentation, keynote, pitch, talk
research research, analysis, RFC, study, investigation, survey, benchmark
project-plan timeline, roadmap, sprint, milestone, schedule, gantt, resource

Present detected types via AskUserQuestion (multi-select). Pre-check types with at least one keyword match. Always include code as an option.

  1. Write confirmed list to spec frontmatter: Add deliverable_types: [...] to the YAML frontmatter of specs/[N]-feature/spec.md.

  2. Update Step 6 confirmation display to include deliverable types and type-appropriate cycle hint: 

    Deliverable types: code, presentation

Development cycle:
  /vt-c-2-plan   → plan (with type-specific task templates)
  /vt-c-3-build  → build (with type-specific checklists)
  /vt-c-4-review → review (with type-specific reviewer agents)
  /vt-c-5-finalize → finalize (with type-conditional gates)
  /vt-c-complete  → mark done, advance to next

Step 6.7: Worktree Offer (Optional)

After activation and deliverable type detection, offer the developer an isolated worktree for parallel spec work. This integrates the /vt-c-git-worktree workflow into the activation flow so developers don't need to chain skills manually.

  1. Check for existing worktree/branch for this spec:

Derive the expected branch name from the spec directory: feature/spec-{N}-{slug} where {N} is the spec number and {slug} is the directory suffix (e.g., spec directory 93-worktree-activate-integration → branch feature/spec-93-worktree-activate-integration).

git branch --list "feature/spec-{N}-*"
ls .worktrees/feature-spec-{N}-*/ 2>/dev/null

If an existing worktree or branch is found:

Use AskUserQuestion: - Switch to existing worktree — display the cd command and VS Code open command: 

Existing worktree found for this spec.

## Open your worktree

**Option A: VS Code** (opens new window with worktree as root)
code <absolute-worktree-path>

**Option B: Terminal + Claude CLI** (start Claude directly in worktree)
cd <absolute-worktree-path> && claude
Then continue to Step 7. - Skip — stay in current directory — continue to Step 7.

If no existing worktree/branch found: proceed to substep 2.

  1. Offer worktree creation:

Use AskUserQuestion: "Work in a separate worktree? (recommended for parallel development)" - Yes — create worktree → proceed to substep 3 - No — stay in current directory → continue to Step 7

  1. Create worktree via manager script:

CRITICAL: Never call git worktree add directly. Always use the manager script, which handles .env file copying, .gitignore management, and consistent directory structure.

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature/spec-{N}-{slug}

The manager script converts branch slashes to hyphens for the directory path: - Branch: feature/spec-93-worktree-activate-integration - Directory: .worktrees/feature-spec-93-worktree-activate-integration/

  1. Display next steps:
Worktree created for SPEC-{NNN}.

## Next Steps — Open your worktree

**Option A: VS Code** (opens new window with worktree as root)
code <absolute-worktree-path>

**Option B: Terminal + Claude CLI** (start Claude directly in worktree)
cd <absolute-worktree-path> && claude
  1. Continue to Step 7 (Spec Merit Validation).

Step 7: Spec Merit Validation (Defense Line 2)

After the spec is created but before the user proceeds to /vt-c-2-plan, validate that the spec is actually worth building. This is the second line of defense against detrimental proposals (the first is in /vt-c-toolkit-review Step 3).

  1. Read the spec that was just created: 

    Read: specs/[N]-feature/spec.md

  2. Read the constitution (if it exists): 

    Read: .specify/memory/constitution.md

  3. Read affected components listed in the spec's "Affected Components", "Scope", or "Changes" section. For each component that will be modified, read its current file to understand the status quo.

  4. Run three focused checks:

Check 1: Constitution Alignment - Does the spec's goal conflict with any Constitution principle? - Does the spec create new cross-component dependencies that break self-containment (Principle IV)? - Does the spec maintain or improve security posture (Principle I)? - If conflict detected → TENSION([principle], [explanation])

Check 2: Problem Validation - Does the spec's "Problem" section describe an observed problem with concrete evidence? - Evidence includes: project references, RCA citations, user feedback, bug reports, incident reports - If the problem is described only in theoretical terms ("could cause", "might lead to", "for cleaner architecture") with no evidence of actual pain → THEORETICAL - If the problem cites concrete evidence → CONFIRMED

Check 3: Net Value - Count: files created vs. modified vs. deleted by this spec - Count: new cross-file dependencies introduced - Does the "Goal" section describe a clear, measurable improvement? - Is there a real, named consumer for every new artifact the spec creates? - If complexity increases without concrete benefit → UNCLEAR

  1. Present validation result:

If all checks pass: 

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Spec Validation: SOUND
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Constitution alignment: OK
Problem evidence: CONFIRMED — referenced in [source]
Net value: Positive ([brief explanation])

Proceed to /vt-c-2-plan when ready.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If concerns found: 

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Spec Validation: CONCERNS FOUND
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Constitution: [TENSION/OK] — [explanation]
Problem evidence: [CONFIRMED/THEORETICAL] — [explanation]
Net value: [Positive/UNCLEAR] — [explanation]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Then use AskUserQuestion: - Proceed to /vt-c-2-plan — acknowledge concerns, continue planning - Revise spec — edit the spec to address concerns before planning - Reject spec — mark as status: rejected in state.yaml with concerns as rejection_reason, do not proceed

The user always has the final say. This is a soft gate that informs, not blocks.

Workflow Position

[ /vt-c-activate ] → /vt-c-2-plan → /vt-c-3-build → /vt-c-4-review → /vt-c-5-finalize → /vt-c-complete
  ▲ YOU ARE HERE
  ↑ Step 6.5 detects deliverable_types for downstream dispatch

Integration Points

With /vt-c-4-review

When /vt-c-4-review passes, it should suggest: 

Review passed! Feature SPEC-003 (Data Import) looks good.
Next: /vt-c-complete to mark this specs done and advance.

With /vt-c-0-start

When /vt-c-0-start runs, show the specs dashboard as part of project status (aggregated from per-spec state.yaml files): 

Active specs: SPEC-003 — Data Import (derived from branch)
Progress: 2/6 completed | 1 active | 2 ready | 1 blocked

With /vt-c-3-build

During build, show active specs context: 

Building: SPEC-003 — Data Import
Spec: specs/3-data-import/spec.md (from spec-3-data-import.md)
Tasks: specs/3-data-import/tasks.md

With /vt-c-repo-audit

The audit checks that specs state is consistent: - specs/[N]-feature/spec.md content matches the specs file - Each specs/[N]-feature/state.yaml has valid status values - No orphaned spec directories without matching .design-state.yaml entry - No legacy .speckit/ directory present