System Spec Kit

Version Note: The version number (16.0.0) tracks the skill's evolution including documentation, templates, scripts, and MCP server. All package.json files are aligned to this version.

Spec Kit - Mandatory Conversation Documentation

Orchestrates mandatory spec folder creation for all conversations involving file modifications. Ensures proper documentation level selection (1-3), template usage, and context preservation through AGENTS.md-enforced workflows.

1. 🎯 WHEN TO USE

What is a Spec Folder?

A spec folder is a numbered directory (e.g., specs/007-auth-feature/) that contains all documentation for a single feature or task:

• Purpose: Track specifications, plans, tasks, and decisions for one unit of work
• Location: Always under specs/ directory with format ###-short-name/
• Contents: Markdown files (spec.md, plan.md, tasks.md) plus optional memory/ and scratch/ subdirectories

Think of it as a "project folder" for AI-assisted development - it keeps context organized and enables session continuity.

Activation Triggers

MANDATORY for ALL file modifications:

• Code files: JS, TS, Python, CSS, HTML
• Documentation: Markdown, README, guides
• Configuration: JSON, YAML, TOML, env templates
• Templates, knowledge base, build/tooling files

Request patterns that trigger activation:

• "Add/implement/create [feature]"
• "Fix/update/refactor [code]"
• "Modify/change [configuration]"
• Any keyword: add, implement, fix, update, create, modify, rename, delete, configure, analyze

Example triggers:

• "Add email validation to the signup form" → Level 1-2
• "Refactor the authentication module" → Level 2-3
• "Fix the button alignment bug" → Level 1
• "Implement user dashboard with analytics" → Level 3

When NOT to Use

• Pure exploration/reading (no file modifications)
• Single typo fixes (<5 characters in one file)
• Whitespace-only changes
• Auto-generated file updates (package-lock.json)
• User explicitly selects Option D (skip documentation)

Rule of thumb: If modifying ANY file content → Activate this skill.

Utility Template Triggers

Rule: When detected, proactively suggest the appropriate action.

2. 🧭 SMART ROUTING

Activation Detection

User Request
    │
    ├─► Contains "spec", "plan", "document", "checklist"?
    │   └─► YES → Activate SpecKit (spec folder workflow)
    │
    ├─► File modification requested?
    │   └─► Gate 3 triggered → Ask spec folder question
    │
    ├─► Contains "debug", "stuck", "help"?
    │   └─► Route to /spec_kit:debug
    │
    ├─► Contains "continue", "resume", "pick up"?
    │   └─► Route to /spec_kit:resume
    │
    ├─► Contains "save context", "save memory", "/memory:save"?
    │   └─► Execute generate-context.js → Index to Spec Kit Memory
    │
    ├─► Contains "search memory", "find context", "what did we"?
    │   └─► Use memory_search({ query: "..." }) MCP tool (query OR concepts required)
    │
    ├─► Contains "checkpoint", "save state", "restore"?
    │   └─► Use checkpoint_create/restore MCP tools
    │
    └─► Gate enforcement triggered (file modification)?
        └─► Constitutional memories auto-surface via memory_match_triggers()

Memory System Triggers

Note: Tool names use the full spec_kit_memory_* prefix as required by OpenCode MCP integration.

Resource Router

Phase-Based Loading:

Reference Sub-folders

Keyword-Based Routing

Resource Inventory

Templates by Level (templates/):

Internal Templates:

• context_template.md - Internal template for memory file generation (Mustache format)

Auto-Generated Folders:

• memory/ - Session context (via generate-context.js)
• scratch/ - Temporary workspace (manual creation)

Key Scripts:

References (references/):

Assets (assets/):

generate-context.js Input Modes:

Architecture: The script uses a modular architecture (142-line CLI entry point + 44 modules across 10 directories: core/, extractors/, lib/, loaders/, renderers/, rules/, spec-folder/, test-fixtures/, tests/, utils/). See scripts/README.md for module details and extension points.

JSON mode documentation: See save_workflow.md for full schema and examples.

3. 🛠️ HOW IT WORKS

Gate 3 Integration

See AGENTS.md Section 2 for the complete Gate 3 flow. This skill implements that gate.

When file modification detected, AI MUST ask:

**Spec Folder** (required): A) Existing | B) New | C) Update related | D) Skip

Enforcement: Constitutional-tier memory surfaces automatically via memory_match_triggers().

3-Level Progressive Enhancement

Level 1 (Baseline):     spec.md + plan.md + tasks.md + implementation-summary.md
         ↓
Level 2 (Verification): Level 1 + checklist.md
         ↓
Level 3 (Full):         Level 2 + decision-record.md + optional research.md

Level Selection Examples:

Override Factors (can push to higher level):

• High complexity or architectural changes
• Risk (security, config cascades, authentication)
• Multiple systems affected (>5 files)
• Integration vs unit test requirements

Decision rule: When in doubt → choose higher level. Better to over-document than under-document.

Checklist as Verification Tool (Level 2+)

The checklist.md is an ACTIVE VERIFICATION TOOL, not passive documentation:

AI Workflow:

1. Load checklist.md at completion phase
2. Verify items in order: P0 → P1 → P2
3. Mark [x] with evidence for each verified item
4. Cannot claim "done" until all P0/P1 items verified

Evidence formats:

• [Test: npm test - all passing]
• [File: src/auth.ts:45-67]
• [Commit: abc1234]
• [Screenshot: evidence/login-works.png]
• (verified by manual testing)
• (confirmed in browser console)

Example checklist entry:

## P0 - Blockers
- [x] Auth flow working [Test: npm run test:auth - 12/12 passing]
- [x] No console errors [Screenshot: evidence/console-clean.png]

## P1 - Required  
- [x] Unit tests added [File: tests/auth.test.ts - 8 new tests]
- [ ] Documentation updated [DEFERRED: Will complete in follow-up PR]

Folder Naming Convention

Format: specs/###-short-name/

Rules:

• 2-3 words (shorter is better)
• Lowercase, hyphen-separated
• Action-noun structure
• 3-digit padding: 001, 042, 099 (no padding past 999)

Good examples: fix-typo, add-auth, mcp-code-mode, cli-codex Bad examples: new-feature-implementation, UpdateUserAuthSystem, fix_bug

Find next number:

ls -d specs/[0-9]*/ | sed 's/.*\/\([0-9]*\)-.*/\1/' | sort -n | tail -1

Sub-Folder Versioning

When reusing spec folders with existing content:

• Trigger: Option A selected + root-level content exists
• Pattern: 001-original/, 002-new-work/, 003-another/
• Memory: Each sub-folder has independent memory/ directory
• Tracking: Spec folder path passed via CLI argument (stateless)

Example structure:

specs/007-auth-system/
├── 001-initial-implementation/
│   ├── spec.md
│   ├── plan.md
│   └── memory/
├── 002-oauth-addition/
│   ├── spec.md
│   ├── plan.md
│   └── memory/
└── 003-security-audit/
    ├── spec.md
    └── memory/

Full documentation: See sub_folder_versioning.md

Context Preservation

Manual context save (MANDATORY workflow):

• Trigger: /memory:save, "save context", or "save memory"
• MUST use: node .opencode/skill/system-spec-kit/scripts/generate-context.js [spec-folder-path]
• NEVER: Create memory files manually via Write/Edit (AGENTS.md Memory Save Rule)
• Location: specs/###-folder/memory/
• Filename: DD-MM-YY_HH-MM__topic.md (auto-generated by script)
• Content includes: PROJECT STATE SNAPSHOT with Phase, Last Action, Next Action, Blockers

Memory File Structure:

<!-- ANCHOR:context -->
## Project Context
[Auto-generated summary of conversation and decisions]
<!-- /ANCHOR:context -->

<!-- ANCHOR:state -->
## Project State Snapshot
- Phase: Implementation
- Last Action: Completed auth middleware
- Next Action: Add unit tests for login flow
- Blockers: None
<!-- /ANCHOR:state -->

<!-- ANCHOR:artifacts -->
## Key Artifacts
- Modified: src/middleware/auth.ts
- Created: src/utils/jwt.ts
<!-- /ANCHOR:artifacts -->

Spec Kit Memory System (Integrated)

Context preservation across sessions via vector-based semantic search.

MCP Tools:

Note: Full tool names use spec_kit_memory_ prefix (e.g., spec_kit_memory_memory_search()).

memory_search() Parameter Requirements:

IMPORTANT: query (string) OR concepts (array of 2-5 strings) is REQUIRED. specFolder alone is NOT sufficient and will cause E040 error.

// Correct usage
memory_search({ query: "session context", specFolder: "007-auth" })
memory_search({ concepts: ["auth", "session"], specFolder: "007-auth" })

// WRONG: Will cause E040 error
// memory_search({ specFolder: "007-auth" })

Key Concepts:

• Constitutional tier - Critical rules that ALWAYS surface at top of search results
• Decay scoring - Recent memories rank higher (~62-day half-life)
• Real-time sync - Use memory_save or memory_index_scan after creating files

Indexing Persistence Note: When generate-context.js creates a memory file, it performs internal indexing and reports "Indexed as memory #X". However, the running MCP server maintains its own database connection and may not immediately see the new index entry.

For immediate MCP visibility, call one of:

• memory_index_scan({ specFolder: "your-folder" }) - Re-scan and index
• memory_save({ filePath: "path/to/memory.md" }) - Index specific file

This is typically only needed if you want to search the memory immediately after creation in the same session.

Full documentation: See memory_system.md for tool behavior, importance tiers, and configuration.

Two-Stage Question Flow

When returning to an active spec folder:

STAGE 1: SPEC FOLDER
"Continue in '006-commands' or start fresh?"
  A) Continue in 006-commands
  B) Create new spec folder
  D) Skip documentation

[If A chosen AND memory files exist]

STAGE 2: MEMORY LOADING
"Found 3 previous session files. Load context?"
  A) Load most recent
  B) Load all recent (1-3)
  C) List and select specific
  D) Skip (start fresh)

Key Insight: "D" means different things:

• Stage 1 "D" = Skip documentation entirely
• Stage 2 "D" = Skip memory loading (stay in spec folder)

AI Actions by Stage 2 Choice:

• A: Read most recent memory file
• B: Read 3 most recent files (parallel)
• C: List up to 10 files, wait for selection
• D: Proceed without loading context

Debug Delegation Workflow

When to Trigger:

• Manual: /spec_kit:debug or "delegate this to a debug agent"
• Auto-suggest when detecting:
  • Same error 3+ times after fix attempts
  • Frustration keywords: "stuck", "can't fix", "tried everything"
  • Extended debugging: >15 minutes with 2+ fix attempts

⚠️ MANDATORY: After 3 failed attempts on the same error, you MUST suggest /spec_kit:debug. Do not continue attempting fixes without offering debug delegation first.

Model Selection (MANDATORY - never skip):

Workflow:

1. Ask which model to use
2. Generate debug-delegation.md with: error category, message, files, attempts, hypothesis
3. Dispatch sub-agent via Task tool
4. Present findings: Apply fix / Iterate / Manual review
5. Update debug-delegation.md with resolution

Auto-suggestion display:

💡 Debug Delegation Suggested - You've been working on this issue for a while.
Run: /spec_kit:debug

Command Pattern Protocol

Commands in .opencode/command/**/*.yaml are Reference Patterns:

1. Scan available commands for relevance to task
2. Extract logic (decision trees), sequencing (order of ops), structure (outputs)
3. Adapt if <80% match; apply directly if >80%
4. Report contributions in implementation-summary.md

Exception: Explicitly invoked commands (e.g., /spec_kit:complete) are ENFORCED LAW, not just reference.

Parallel Dispatch Configuration

SpecKit supports smart parallel sub-agent dispatch based on 5-dimension complexity scoring:

• <20% complexity: Proceed directly
• ≥20% + 2 domains: Ask user for dispatch preference
• Step 6 Planning: Auto-dispatches 4 parallel exploration agents

Full configuration: See parallel_dispatch_config.md

4. 📋 RULES

✅ ALWAYS

1. Determine level (1/2/3) before ANY file changes - Count LOC, assess complexity/risk
2. Copy templates from templates/ - NEVER create from scratch
3. Fill ALL placeholders - Remove [PLACEHOLDER] and sample content
4. Ask A/B/C/D when file modification detected - Present options, wait for selection
5. Check for related specs before creating new folders - Search keywords, review status
6. Get explicit user approval before changes - Show level, path, templates, approach
7. Use consistent folder naming - specs/###-short-name/ format
8. Use checklist.md to verify (Level 2+) - Load before claiming done
9. Mark items [x] with evidence - Include links, test outputs, screenshots
10. Complete P0/P1 before claiming done - No exceptions
11. Suggest handover.md on session-end keywords - "continue later", "next session"
12. Run validate-spec.sh before completion - Completion Verification requirement
13. Create implementation-summary.md at end of implementation phase (Level 1+) - Document what was built
14. Suggest /spec_kit:handover when session-end keywords detected OR after extended work (15+ tool calls) - Proactive context preservation
15. Suggest /spec_kit:debug after 3+ failed fix attempts on same error - Do not continue without offering debug delegation

❌ NEVER

1. Create documentation from scratch - Use templates only
2. Skip spec folder creation - Unless user explicitly selects D
3. Make changes before spec + approval - Spec folder is prerequisite
4. Leave placeholders in final docs - All must be replaced
5. Decide autonomously update vs create - Always ask user
6. Claim done without checklist verification - Level 2+ requirement
7. Proceed without spec folder confirmation - Wait for A/B/C/D
8. Skip validation before completion - Completion Verification hard block

⚠️ ESCALATE IF

1. Scope grows during implementation - Add higher-level templates, document change in changelog
2. Uncertainty about level <80% - Present level options to user, default to higher
3. Template doesn't fit requirements - Adapt closest template, document modifications
4. User requests skip (Option D) - Warn about tech debt, explain debugging challenges, confirm consent
5. Validation fails with errors - Report specific failures, provide fix guidance, re-run after fixes

5. ✅ VALIDATION

Automated validation of spec folder contents via validate-spec.sh.

Usage: .opencode/skill/system-spec-kit/scripts/validate-spec.sh <spec-folder>

Exit Codes

Completion Verification

Before claiming "done":

1. Run validation: ./scripts/validate-spec.sh <spec-folder>
2. Exit 2 → FIX errors
3. Exit 1 → ADDRESS warnings or document reason
4. Exit 0 → Proceed with completion claim

Full documentation: See validation_rules.md for all rules, configuration, and troubleshooting.

6. 🏆 SUCCESS CRITERIA

Documentation Created

• Spec folder exists at specs/###-short-name/
• Folder name follows convention (2-3 words, lowercase, hyphen-separated)
• Number is sequential (no gaps or duplicates)
• Correct level templates copied (not created from scratch)
• All placeholders replaced with actual content
• Sample content and instructional comments removed
• Cross-references to sibling documents work (spec.md ↔ plan.md ↔ tasks.md)

User Approval

• Asked user for A/B/C/D choice when file modification detected
• Documentation level presented with rationale
• Spec folder path shown before creation
• Templates to be used listed
• Explicit approval ("yes", "go ahead", "proceed") received before file changes

Context Preservation

• Context saved via generate-context.js script (NEVER manual Write/Edit)
• Memory files contain PROJECT STATE SNAPSHOT section
• Manual saves triggered via /memory:save or keywords
• Anchor pairs properly formatted and closed

Checklist Verification (Level 2+)

• Loaded checklist.md before claiming completion
• Verified items in priority order (P0 → P1 → P2)
• All P0 items marked [x] with evidence
• All P1 items marked [x] with evidence
• P2 items either verified or deferred with documented reason
• No unchecked P0/P1 items remain

Validation Passed

• Ran validate-spec.sh on spec folder
• Exit code is 0 (pass) or 1 (warnings only)
• All ERROR-level issues resolved
• WARNING-level issues addressed or documented

7. 🔌 INTEGRATION POINTS

Priority System

Validation Triggers

• AGENTS.md Gate 3 → Validates spec folder existence and template completeness
• AGENTS.md Completion Verification → Runs validate-spec.sh before completion claims
• Manual /memory:save → Context preservation on demand
• Template validation → Checks placeholder removal and required field completion

Cross-Skill Workflows

Spec Folder → Implementation:

system-spec-kit (creates spec folder)
    → workflows-code (implements from spec + plan)
    → workflows-git (commits with spec reference)
    → Spec Kit Memory (preserves conversation to spec/memory/ via MCP)

Documentation Quality:

system-spec-kit (creates spec documentation)
    → workflows-documentation (validates structure, scores quality)
    → Feedback loop: Iterate if scores <90

Validation Workflow:

Implementation complete
    → validate-spec.sh (automated checks)
    → Fix ERROR-level issues
    → Address WARNING-level issues
    → Claim completion with confidence

Common Failure Patterns

Quick Reference Commands

Create new spec folder:

./scripts/create-spec-folder.sh "Add feature description" --short-name feature-name --level 2

Validate spec folder:

.opencode/skill/system-spec-kit/scripts/validate-spec.sh specs/007-feature/

Save context:

node .opencode/skill/system-spec-kit/scripts/generate-context.js specs/007-feature/

Find next spec number:

ls -d specs/[0-9]*/ | sed 's/.*\/\([0-9]*\)-.*/\1/' | sort -n | tail -1

Calculate documentation completeness:

.opencode/skill/system-spec-kit/scripts/calculate-completeness.sh specs/007-feature/

8. 🔗 RELATED RESOURCES

Related Skills

External Dependencies

Remember: This skill is the foundational documentation orchestrator. It enforces structure, template usage, context preservation, and validation for all file modifications. Every conversation that modifies files MUST have a spec folder.