Skip to content

vt-c-complete

Mark the active specs as completed and advance to the next ready spec.

Plugin: core-standards
Category: Other
Command: /vt-c-complete

/vt-c-complete — specs Completion

Workflow position: /vt-c-activate → /vt-c-2-plan → /vt-c-3-build → /vt-c-4-review → /vt-c-complete → next specs

Marks the current spec as done and offers to activate the next one.

Purpose

Completes the active specs and advances the execution sequence. This is the counterpart to /vt-c-activate — activation starts work, completion finishes it.

When to Use

  • After /vt-c-4-review passes and the feature is ready
  • When all implementation work for the current spec is done

Prerequisites

  • A spec must be currently in_progress (derived from branch name or .active-spec file)
  • The spec's specs/[N]-feature/state.yaml must exist

Invocation

/vt-c-complete                     # Complete the active spec

Execution Steps

Step 1: 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

  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 → continue to Step 2
  7. If branch matches fix/bug-NNN-*: extract NNN → BUG-NNN → go to Step 1.5 (Bug Completion)
  8. Example: feature/spec-012-design-state-split → SPEC-012

  9. Example: fix/bug-007-login-safari → BUG-007

  10. Fallback: No active spec or bug found

  11. Display: "No active spec or bug found. Use /vt-c-activate to start working on a spec or bug."
  12. Exit gracefully

Step 1.5: Bug Completion (for fix/bug-NNN-* branches)

  1. Extract NNN from the branch name: fix/bug-007-login-safari → 007
  2. Glob bugs/007-*/state.yaml (replace 007 with the extracted number) to find the bug directory
  3. If not found:
  4. Display: "BUG-007 directory not found in bugs/. Cannot mark as verified."
  5. Exit gracefully
  6. Read bugs/NNN-slug/state.yaml
  7. If status: verified already:
  8. Display: "BUG-NNN is already verified."
  9. Exit without changes
  10. Update bugs/NNN-slug/state.yaml: set status: verified, add verified_at: [ISO-8601 now]
  11. Display: 
    ✓ BUG-NNN marked as verified
  Branch: fix/bug-NNN-slug
  State: bugs/NNN-slug/state.yaml → verified
  12. Exit — do not continue to Step 2 (spec completion flow does not apply)

Step 2: Read Spec State

  1. Read specs/[N]-feature/state.yaml for the active spec
  2. If state.yaml does not exist:
  3. Display: "No state file found for SPEC-NNN. Use /vt-c-activate to properly activate a spec first."
  4. Exit gracefully

Step 2.5: Verify Workflow Gates

Read specs/[N]-feature/state.yaml and check all 4 phase gates. Display a dashboard:

Workflow Gate Check:
  [✓/✗] Plan     — [status or NOT RUN]
  [✓/✗] Build    — [status or NOT RUN]
  [✓/✗] Review   — [status or NOT RUN]
  [✓/✗] Finalize — [status or NOT RUN]

Gate check logic:

  1. plan_gate exists AND plan_gate.status == COMPLETE → ✓
  2. build_gate exists AND build_gate.status == COMPLETE → ✓
  3. review_gate exists AND review_gate.status == PASS → ✓ (FAIL → ✗)
  4. finalize_gate exists AND finalize_gate.status == GO → ✓ (NO-GO → ✗)

If all 4 gates pass: 

✓ Workflow gates verified: plan ✓, build ✓, review PASS, finalize GO
Continue to Step 3.

If any gate is missing or failing: 

BLOCKED: Workflow gates incomplete.

Missing/failing gates:
  [✗] Review  — NOT RUN → Run /vt-c-4-review
  [✗] Finalize — NOT RUN → Run /vt-c-5-finalize

Complete the missing phases before marking this spec done.

Use AskUserQuestion: - Run the missing phase — exit and run the next required phase - Skip gate check (emergency only) — records bypass permanently in state.yaml

If emergency bypass selected: Ask for a reason via AskUserQuestion (free text). Then write to state.yaml: 

gate_bypass:
  date: "YYYY-MM-DD"
  reason: "[user-provided reason]"
  skipped_gates: [list of missing gates]
This creates a permanent, committed record of the bypass. Continue to Step 3.

Backward compatibility: If state.yaml has no gate fields at all (old spec completed before SPEC-095), skip this check silently — do not retroactively enforce on specs that predate the gate system.

Step 3: Check Already Completed

If state.yaml already shows status: completed: - Display: "SPEC-NNN is already completed. Use /vt-c-activate to pick the next spec." - Exit without modifying state

Step 4: Warn on Incomplete Steps

If steps: exists in state.yaml and any step is not completed:

⚠ Not all steps are completed:
  Step 5: US4 — PR template  (pending)
Mark as completed anyway?

Use AskUserQuestion: - Yes, complete anyway — proceed to Step 4.5 - No, go back — exit without changes

Step 4.5: State Documentation Check (advisory)

Check whether this spec's changes may have affected UI state documentation.

  1. Check for state matrix existence: Look for 01-docs/deliverables/implementation-readiness/ui-state-matrix.md in the project. If the file does not exist → skip to Step 5 silently.

  2. Get changed files for this spec: 

    git diff --name-only $(git merge-base HEAD main) HEAD
    If the git command fails → skip to Step 5 silently.

  3. Grep for state-affecting patterns in changed file names and content:

  4. Filename patterns: *state*, *State*, *guard*, *route*

  5. Content patterns: enum.*State, interface.*State, type.*State, ngIf, ngSwitch, @if, @switch, [hidden], canActivate

  6. If matches found (advisory, non-blocking): 

    State documentation advisory:
─────────────────────────────────────────────────────────────────
This spec changed {N} file(s) with UI state logic. Consider updating:
• 01-docs/deliverables/implementation-readiness/ui-state-matrix.md
• Test dataset (if permutations changed)
─────────────────────────────────────────────────────────────────

  7. Proceed to Step 4.6 regardless (advisory only).

Step 4.6: Compound Knowledge Capture

Before marking the spec done, check whether it produced reusable learnings worth documenting.

Auto-skip conditions (any ONE is sufficient to skip — proceed to Step 5 silently): - No plan.md exists for this spec (was a quick fix, not a planned feature) - Git diff from branch is small (<50 lines changed) AND all review findings were LOW or informational

If none of the auto-skip conditions are met, proceed with compound capture.

If compound capture is warranted:

  1. Read the spec's artifacts:
  2. specs/[N]-feature/spec.md — problem and goal
  3. specs/[N]-feature/plan.md — key architecture decisions
  4. Review findings from specs/[N]-feature/review-triage.md (if exists)

  5. Session journal entries from docs/vt-c-journal/ (if any for this spec)

  6. Identify compound-worthy learnings:

  7. Non-obvious solutions (the fix wasn't what you'd expect)
  8. Architecture decisions with rationale (chose X over Y because Z)
  9. Patterns applicable beyond this spec (reusable across projects)

  10. Gotchas or pitfalls discovered during implementation

  11. If learnings found, present a preview: 

    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Compound Knowledge Capture
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

From SPEC-{NNN}: {title}

Learning: {1-2 sentence summary of the reusable insight}

Problem: {from spec problem section}
Solution: {from plan key decisions}
Prevention: {how this pattern prevents future issues}
Tags: {extracted from spec and review}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  12. Use AskUserQuestion:

  13. Capture — Write compound doc using /vt-c-compound format
  14. Edit first — User modifies the summary before writing

  15. Skip — No learnings worth capturing, proceed to Step 5

  16. If "Capture" or "Edit first": invoke the compound-docs skill's writing logic — the doc is written to the appropriate docs/solutions/{category}/ subdirectory using the compound-docs YAML frontmatter schema (symptoms, root_cause, resolution_type, severity, module, problem_type, date, tags). Reference SPEC-NNN in the body.

Step 5: Mark as Completed

Update specs/[N]-feature/state.yaml: - Set status: completed - Set completed_at timestamp (ISO 8601 format)

Step 5.5: User Manual Update (optional)

If docs/user-manual/mkdocs.yml exists:

  1. Check if the completed spec has a docs_page field in its state.yaml, OR if a matching feature page exists in docs/user-manual/docs/features/
  2. If a matching page is found or docs_page exists: 
    User manual page found for this feature.
    Use AskUserQuestion:
  3. Update user manual (Recommended) — runs /vt-c-user-manual-update for this spec
  4. Skip — continue without updating the manual
  5. If no match found: skip silently (feature may not have a manual page)

If docs/user-manual/ does not exist: skip this step silently.

Step 6: Identify Next Ready specs

  1. Read .design-state.yaml for static metadata (dependencies, priorities)
  2. Scan all specs/[N]-feature/state.yaml files for current status
  3. Find specs whose dependencies are all completed and whose own status is not completed or in_progress
  4. Sort by priority (P0 first), then by numeric ID

Step 7: Offer Next Spec or Show Completion

If next ready specs exist: 

SPEC-002: Dashboard Layout completed!
Next: SPEC-003: Data Import. Activate?

Use AskUserQuestion: - Yes, activate SPEC-003 — delegate to /vt-c-activate SPEC-003 - No, show dashboard — run /vt-c-activate --status

If all specs completed: 

All specs completed!

Progress: 6/6 completed
Run /vt-c-5-finalize for final governance audit and deployment.