# System Spec Kit

> Unified documentation and context preservation: spec folder workflow (levels 1-3), template enforcement, validation, Spec Kit Memory with vector search, six-tier importance system, constitutional rules, checkpoint save/restore. Mandatory for all file modifications.

- Skill: `majiayu000/system-spec-kit-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/system-spec-kit-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/system-spec-kit-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/majiayu000/system-spec-kit-2

---


> **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.

<!-- Keywords: spec-kit, speckit, documentation-workflow, spec-folder, template-enforcement, context-preservation, progressive-documentation, validation, spec-kit-memory, vector-search, constitutional-tier, checkpoint, importance-tiers -->

# 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

| Template              | Trigger Keywords                                                                                                              | Action                    |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `handover.md`         | "handover", "next session", "continue later", "pass context", "ending session", "save state", "multi-session", "for next AI"  | Suggest creating handover |
| `debug-delegation.md` | "stuck", "can't fix", "tried everything", "same error", "fresh eyes", "hours on this", "still failing", "need help debugging" | Suggest `/spec_kit:debug` |

**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.

| Trigger Pattern | Action | MCP Tool |
|-----------------|--------|----------|
| "save context", "save memory", `/memory:save` | Generate + index memory file | `spec_kit_memory_memory_save()` |
| "search memory", "find prior", "what did we decide" | Semantic search across sessions | `spec_kit_memory_memory_search({ query: "..." })` (query OR concepts required) |
| "list memories", "show context" | Browse stored memories | `spec_kit_memory_memory_list()` |
| "checkpoint", "save state" | Create named checkpoint | `spec_kit_memory_checkpoint_create()` |
| "restore checkpoint", "rollback" | Restore from checkpoint | `spec_kit_memory_checkpoint_restore()` |
| Gate enforcement (any file modification) | Auto-surface constitutional rules | `spec_kit_memory_memory_match_triggers()` |

### Resource Router

**Phase-Based Loading:**

| Phase              | Trigger                               | Load Resources                             | Execute             |
| ------------------ | ------------------------------------- | ------------------------------------------ | ------------------- |
| **Planning**       | New feature, "plan", "design"         | level_specifications.md, template_guide.md | /spec_kit:plan      |
| **Research**       | "investigate", "explore", "analyze"   | quick_reference.md, worked_examples.md     | /spec_kit:research  |
| **Implementation** | "implement", "build", "code"          | validation_rules.md, template_guide.md     | /spec_kit:implement |
| **Debugging**      | "stuck", "error", "not working"       | quick_reference.md, troubleshooting.md     | /spec_kit:debug     |
| **Completion**     | "done", "finished", "complete"        | validation_rules.md, phase_checklists.md   | /spec_kit:complete  |
| **Handover**       | "stopping", "break", "continue later" | quick_reference.md                         | /spec_kit:handover  |
| **Resume**         | "continue", "pick up", "resume"       | quick_reference.md                         | /spec_kit:resume    |

### Reference Sub-folders

| Sub-folder | Purpose | Files |
|------------|---------|-------|
| `memory/` | Context preservation, MCP tools | memory_system.md, save_workflow.md, trigger_config.md |
| `templates/` | Template system, level specs | level_specifications.md, template_guide.md, template_style_guide.md |
| `validation/` | Validation rules, checklists | validation_rules.md, phase_checklists.md, path_scoped_rules.md |
| `structure/` | Folder organization, routing | folder_structure.md, folder_routing.md, sub_folder_versioning.md |
| `workflows/` | Usage workflows, examples | quick_reference.md, execution_methods.md, worked_examples.md |
| `debugging/` | Troubleshooting, debugging | troubleshooting.md, universal_debugging_methodology.md |
| `config/` | Configuration | environment_variables.md |

### Keyword-Based Routing

| Keywords | Route To |
|----------|----------|
| "memory", "save context", "MCP", "trigger" | `references/memory/` |
| "embeddings", "vector", "semantic", "decay" | `references/memory/` |
| "anchor", "snapshot" | `references/memory/` |
| "template", "level 1/2/3", "spec.md format" | `references/templates/` |
| "validate", "rules", "checklist", "P0/P1/P2" | `references/validation/` |
| "folder", "naming", "structure", "versioning" | `references/structure/` |
| "workflow", "example", "commands", "quick" | `references/workflows/` |
| "debug", "error", "stuck", "troubleshoot" | `references/debugging/` |
| "env", "environment", "configuration" | `references/config/` |
| "scripts", "generate-context", "check-completion" | `scripts/` |

### Resource Inventory

**Templates by Level (`templates/`):**

| Level | Required Files | Optional |
| ----- | -------------- | -------- |
| 1     | spec.md, plan.md, tasks.md, implementation-summary.md | — |
| 2     | Level 1 + checklist.md | — |
| 3     | Level 2 + decision-record.md | research.md |
| Any   | — | handover.md, debug-delegation.md |

**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:**

| Script | Purpose |
|--------|---------|
| `generate-context.js` | Generate memory files from conversation (modular: 44 modules in 10 dirs) |
| `validate-spec.sh` | Validate spec folder structure |
| `create-spec-folder.sh` | Create new spec folders with templates |
| `check-completion.sh` | Verify checklist completion status |
| `recommend-level.sh` | Suggest documentation level based on LOC |
| `archive-spec.sh` | Archive completed spec folders |
| `cleanup-orphaned-vectors.js` | Removes orphaned vector entries |
| `check-prerequisites.sh` | Checks prerequisites before implementation |
| `common.sh` | Shared shell utilities |
| `setup.sh` | Initial setup script |
| `calculate-completeness.sh` | Calculates spec completeness percentage |
| `package.json` | Node.js dependencies |
| `README.md` | Scripts documentation |
| `tests/test-validation.sh` | Validation test runner |
| `tests/test-embeddings-factory.js` | Test embedding provider configuration |
| `tests/test-bug-fixes.js` | Bug fix regression tests |

**References (`references/`):**

| Sub-folder | File | Purpose | When to Load |
|------------|------|---------|--------------|
| `memory/` | `memory_system.md` | MCP tool behavior and config | Memory operations |
| `memory/` | `save_workflow.md` | Memory save workflow docs | Context preservation |
| `memory/` | `trigger_config.md` | Trigger phrase configuration | Setup |
| `templates/` | `level_specifications.md` | Complete Level 1-3 requirements | Planning |
| `templates/` | `template_guide.md` | Template selection and usage | Planning, Implementation |
| `templates/` | `template_style_guide.md` | Template formatting conventions | Documentation |
| `validation/` | `validation_rules.md` | All validation rules and fixes | Implementation, Completion |
| `validation/` | `phase_checklists.md` | Per-phase validation | Completion |
| `validation/` | `path_scoped_rules.md` | Path-scoped validation | Advanced |
| `structure/` | `folder_structure.md` | Folder naming conventions | Planning |
| `structure/` | `folder_routing.md` | Folder routing logic | Planning |
| `structure/` | `sub_folder_versioning.md` | Sub-folder workflow | Reusing spec folders |
| `workflows/` | `quick_reference.md` | Commands and checklists | Any phase |
| `workflows/` | `execution_methods.md` | Script execution patterns | Operations |
| `workflows/` | `worked_examples.md` | Real-world examples | Learning |
| `debugging/` | `troubleshooting.md` | Common issues and solutions | Debugging |
| `debugging/` | `universal_debugging_methodology.md` | Stack-agnostic 4-phase debugging | Debugging |
| `config/` | `environment_variables.md` | Env var configuration | Setup |

**Assets (`assets/`):**

| File | Purpose |
|------|---------|
| `level_decision_matrix.md` | LOC thresholds and complexity factors |
| `template_mapping.md` | Template-to-level mapping rules |
| `parallel_dispatch_config.md` | Agent dispatch configuration |

**generate-context.js Input Modes:**

| Mode | Usage | Description |
|------|-------|-------------|
| **Direct** | `node generate-context.js specs/007-feature/` | Auto-captures context from OpenCode session |
| **JSON** | `node generate-context.js /tmp/context-data.json` | Manual context injection via JSON file |

**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](./scripts/README.md) for module details and extension points.

**JSON mode documentation:** See [save_workflow.md](./references/memory/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
```

| Option          | Description                        | Best For                        |
| --------------- | ---------------------------------- | ------------------------------- |
| **A) Existing** | Continue in related spec folder    | Iterative work, related changes |
| **B) New**      | Create `specs/###-name/`           | New features, unrelated work    |
| **C) Update**   | Add to existing documentation      | Extending existing docs         |
| **D) Skip**     | No spec folder (creates tech debt) | Trivial changes only            |

**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 | LOC Guidance | Required Files                                                           | Use When                     |
| ----- | ------------ | ------------------------------------------------------------------------ | ---------------------------- |
| **1** | <100         | spec.md, plan.md, tasks.md, implementation-summary.md                    | All features (minimum)       |
| **2** | 100-499      | Level 1 + checklist.md                                                   | QA validation needed         |
| **3** | ≥500         | Level 2 + decision-record.md                                             | Complex/architecture changes |

**Level Selection Examples:**

| Task                 | LOC Est. | Level | Rationale                      |
| -------------------- | -------- | ----- | ------------------------------ |
| Fix CSS alignment    | 10       | 1     | Simple, low risk               |
| Add form validation  | 80       | 1-2   | Borderline, low complexity     |
| Modal component      | 200      | 2     | Multiple files, needs QA       |
| Auth system refactor | 600      | 3     | Architecture change, high risk |
| Database migration   | 150      | 3     | High risk overrides LOC        |

**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:

| Priority | Meaning      | Deferral Rules                          |
| -------- | ------------ | --------------------------------------- |
| **P0**   | HARD BLOCKER | MUST complete, cannot defer             |
| **P1**   | Required     | MUST complete OR user-approved deferral |
| **P2**   | Optional     | Can defer without approval              |

**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:**
```markdown
## 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:**
```bash
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](./references/structure/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:**
```markdown
<!-- 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:**

| Tool | Purpose |
|------|---------|
| `memory_search()` | Semantic search with vector similarity |
| `memory_match_triggers()` | Fast keyword matching (<50ms) |
| `memory_save()` | Index a memory file |
| `memory_list()` | Browse stored memories with pagination |
| `memory_delete()` | Delete memories by ID or spec folder |
| `memory_update()` | Update memory metadata and importance tier |
| `memory_stats()` | Get system statistics and counts |
| `memory_validate()` | Record validation feedback for confidence |
| `memory_index_scan()` | Bulk scan and index workspace |
| `memory_health()` | Check system health status |
| `checkpoint_create()` | Create named checkpoint |
| `checkpoint_list()` | List all available checkpoints |
| `checkpoint_restore()` | Restore from checkpoint |
| `checkpoint_delete()` | Delete a checkpoint |

> **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.

```javascript
// 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](./references/memory/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):**

| Model      | Best For                         | Characteristics                |
| ---------- | -------------------------------- | ------------------------------ |
| **Claude** | General debugging, code analysis | Anthropic models (Sonnet/Opus) |
| **Gemini** | Multi-modal, large context       | Google models (Pro/Ultra)      |
| **Codex**  | Code generation, reasoning       | OpenAI models (GPT-4/o1)       |
| **Other**  | User-specified model             | Custom selection               |

**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](./assets/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

| Code | Meaning                         | Action                       |
| ---- | ------------------------------- | ---------------------------- |
| 0    | Passed (no errors, no warnings) | Proceed with completion      |
| 1    | Passed with warnings            | Address or document warnings |
| 2    | Failed (errors found)           | MUST fix before completion   |

### 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](./references/validation/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

| Priority | Level    | Deferral                                 |
| -------- | -------- | ---------------------------------------- |
| **P0**   | Blocker  | Cannot proceed without resolution        |
| **P1**   | Warning  | Must address or defer with user approval |
| **P2**   | Optional | Can defer without approval               |

### 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

| Pattern                       | Trigger                                 | Prevention                                |
| ----------------------------- | --------------------------------------- | ----------------------------------------- |
| Skip Gate 3 on exciting tasks | "comprehensive", "fix all", "15 agents" | STOP → Ask spec folder → Wait for A/B/C/D |
| Rush to code                  | "straightforward", "simple fix"         | Analyze → Verify → Simplest solution      |
| Create docs from scratch      | Time pressure                           | Always copy from templates/               |
| Skip checklist verification   | "trivial edit"                          | Load checklist.md, verify ALL items       |
| Manual memory file creation   | "quick save"                            | MUST use generate-context.js script       |
| Autonomous update vs create   | "obvious choice"                        | Always ask user for A/B/C/D               |

### Quick Reference Commands

**Create new spec folder:**
```bash
./scripts/create-spec-folder.sh "Add feature description" --short-name feature-name --level 2
```

**Validate spec folder:**
```bash
.opencode/skill/system-spec-kit/scripts/validate-spec.sh specs/007-feature/
```

**Save context:**
```bash
node .opencode/skill/system-spec-kit/scripts/generate-context.js specs/007-feature/
```

**Find next spec number:**
```bash
ls -d specs/[0-9]*/ | sed 's/.*\/\([0-9]*\)-.*/\1/' | sort -n | tail -1
```

**Calculate documentation completeness:**
```bash
.opencode/skill/system-spec-kit/scripts/calculate-completeness.sh specs/007-feature/
```

---

## 8. 🔗 RELATED RESOURCES

### Related Skills

| Direction      | Skill                   | Integration                                        |
| -------------- | ----------------------- | -------------------------------------------------- |
| **Upstream**   | None                    | This is the foundational workflow                  |
| **Downstream** | workflows-code          | Uses spec folders for implementation tracking      |
| **Downstream** | workflows-git           | References spec folders in commit messages and PRs |
| **Downstream** | workflows-documentation | Validates spec folder documentation quality        |
| **Integrated** | Spec Kit Memory         | Context preservation via MCP (merged into this skill) |

### External Dependencies

| Resource       | Location                                                      | Purpose                      |
| -------------- | ------------------------------------------------------------- | ---------------------------- |
| Templates (10) | `templates/`                                                  | All spec folder templates    |
| Validation     | `scripts/validate-spec.sh`                                    | Automated validation         |
| Gates          | `AGENTS.md` Section 2                                         | Gate definitions             |
| Memory gen     | `.opencode/skill/system-spec-kit/scripts/generate-context.js` | Memory file creation         |
| MCP Server     | `.opencode/skill/system-spec-kit/mcp_server/context-server.js`| Spec Kit Memory MCP          |
| Database       | `.opencode/skill/system-spec-kit/database/context-index.sqlite`| Vector search index         |
| Constitutional | `.opencode/skill/system-spec-kit/constitutional/`             | Always-surface rules         |

---

**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.