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., 007-auth-feature/) that contains documentation for a single feature/task or a coordinated packet of related phase work:
Spec folders may also be nested as coordination-root packets with direct-child phase folders (e.g., specs/02--track/022-feature/011-phase/002-child/).
- Purpose: Track specifications, plans, tasks, and decisions for one unit of work
- Location: Under
specs/ using either ###-short-name/ at the root or nested packet paths for phased coordination
- Contents: Markdown files (spec.md, plan.md, tasks.md, and implementation-summary.md when work is complete) plus optional support folders such as
scratch/, research/, or review/
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]"
- Positive keywords include add, implement, fix, update, create, modify, rename, delete and configure. The authoritative Gate 3 classifier intentionally omits
analyze, decompose and phase from positive triggers; analyze is a read-only disqualifier unless a real write, memory-save or resume trigger is also present.
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.
Status: ✅ This requirement applies immediately once file edits are requested.
Distributed Governance Rule
Any agent writing authored spec folder docs MUST use contract-backed templates through create.sh or the inline renderer.
Authored docs: spec.md, plan.md, tasks.md, acceptance-criteria.md, implementation-summary.md, decision-record.md, handover.md, review-report.md, debug-delegation.md, goal.md and timeline.md.
acceptance-criteria.md is from Level 2. Docs after implementation-summary.md are optional add-ons or packet-type docs.
goal.md may come from /create:goal. Its per-kind templates are parity-checked copies of goal.md.tmpl.
This is a workflow-required gate, not a runtime hook.
Run bash .skilled/skills/system-spec-kit/runtime/cli/spec/validate.sh <spec-folder> --strict --quiet once after the last authored spec-doc write and before completion claims.
Section 9 of references/workflows/spec-authoring-card.md defines the gate.
Each /speckit workflow runs its own strict gate after each doc-writing step.
Then route continuity updates through /speckit:save.
The template rule exempts workflow-owned deep-research packet markdown: research/iterations/*.md, research/deep-research-*.md and progressive research/research.md loop updates.
/deep:research must run targeted strict validation after every spec.md mutation it performs.
@deep-research exclusively writes research/research.md. @debug exclusively writes debug-delegation.md.
handover.md stays in the canonical recovery ladder and is maintained through /speckit:save handover_state routing using the handover template for initial creation.
review-report.md remains owned by @deep-review when deep review workflows synthesize findings.
- The deep loops write their own
resource-map.md evidence ledger into their artifact directory; it is not a packet add-on.
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 /speckit:save handover maintenance |
debug-delegation.md |
"stuck", "can't fix", "tried everything", "same error", "fresh eyes", "hours on this", "still failing", "need help debugging" |
Suggest Task-tool debug delegation |
Rule: When detected, proactively suggest the appropriate action.
2. SMART ROUTING
No hub sits above this skill, so the triggers in WHEN TO USE select it.
A request that writes any file selects it, and so does a create, a save, a resume or a validation question.
references/workflows/quick-reference.md loads first on every invocation as the command surface.
The intent keywords choose the rest through RESOURCE_MAP. A plan, implement or plain write request starts with references/workflows/spec-authoring-card.md.
A request that matches no intent returns UNKNOWN_FALLBACK and its checklist rather than a silent default.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Core Workflow
- Gate 3 selects an existing, new, related, skipped, or phase spec folder before file changes.
- For new folders, estimate level from LOC, risk, affected systems, and verification needs; create from contract-backed templates.
- Keep phase parents lean: parent folders hold
spec.md, description.json, and graph-metadata.json; child phases hold working docs.
- Clear both completion gates before claiming done: the priority-ordered checklist in the
tasks.md verification section, and the closure verdict in acceptance-criteria.md. See Two Completion Gates below.
- Preserve continuity in
implementation-summary.md or through canonical /speckit:save with generate-context.js.
Two Completion Gates
Level 2+ packets close through two different documents. They are often conflated, so keep the question each one answers distinct.
|
tasks.md verification section |
acceptance-criteria.md |
| Answers |
Is the work done? |
May the packet close? |
| Unit |
A checklist item |
A criterion, written Given / When / Then |
| Vocabulary |
[ ] / [x], tagged P0, P1 or P2 |
Met, Unmet, Waived, Superseded |
| Enforced by |
check-completion.sh |
AC_CLOSURE and AC_COVERAGE in validate.sh |
| Blocks when |
A P0 or P1 item is incomplete, an item carries no priority tag, or a completed P0/P1 item cites no evidence. P2 blocks only under --strict |
Any criterion is still Unmet, or a Waived or Superseded row names a decision record that does not exist |
The two are linked rather than parallel. AC_COVERAGE requires every criterion's evidence to trace back into the merged tasks document, so tasks.md is where the proof lives and acceptance-criteria.md is where the verdict lives. A criterion marked Met with no traceable item behind it is the failure that rule exists to catch.
acceptance-criteria.md is an optional add-on: validate.sh warns when a Level 2+ packet has none. Once the file exists, AC_CLOSURE is an error-severity gate on that packet.
Retrieval and Continuity
Retrieval is file-based and needs no running service.
Gate 1 resolves a prompt against the committed trigger index with node .skilled/skills/system-spec-kit/runtime/cli/retrieval/lookup-trigger-index.mjs --json -- "<prompt>".
When the index scores nothing, it also scores the declared trigger_phrases of spec docs the index does not list yet and reports that scan in staleFallback; --no-stale-fallback keeps it index-only.
It exits 0 on candidates from either source, 1 on a clean no-hit and 2 on a bad invocation or unreadable index.
Free-text retrieval uses the literal ripgrep recipes in references/retrieval/retrieval-conventions.md.
The trailing positional path scopes them by track and packet. The recipes are precise only because the corpus is regular.
references/structure/grep-convention.md holds the frontmatter, anchor, naming and body-preservation rules. validate.sh enforces them on every spec document.
Recovery follows the continuity ladder, which stays the primary path, rather than inferring a session:
handover.md
- The
_memory.continuity frontmatter block
- Packet-first spec docs
- The bounded context recipe
/speckit:resume owns the ladder. A claimed handoff note can add one bounded ## History Lookup section, and that lookup never replaces the ladder.
Saves go through node .skilled/skills/system-spec-kit/runtime/cli/dist/continuity/generate-context.js, invoked by /speckit:save.
The writer updates the packet's continuity surfaces in place.
- A
--full-auto save also writes the payload's operatorDecisions into the target packet's decision-record.md, creating it when absent and first stamping a missing level marker into spec.md so the packet's level does not move.
- No indexing hand-off follows.
Regenerate the index with node .skilled/skills/system-spec-kit/runtime/cli/retrieval/generate-trigger-index.mjs after spec-doc frontmatter changes. The artifact at runtime/data/trigger-index.json is committed, so a fresh clone answers Gate 1 before anything is built.
Declared loss. Semantic paraphrase matching, vector and BM25 fusion, decay scoring, access tracking, session dedup and causal traversal are gone.
They have no file-based successor.
A lookup with no match returns nothing. Callers must say so plainly, not guess.
The index cannot find undeclared trigger_phrases. See references/retrieval/retrieval-conventions.md §8 for what belongs there.
Reranking
Nothing reranks retrieval today.
Model-based cross-encoder/local-GGUF reranking, the local model path, the local rerank sidecar skill and cloud rerankers are retired.
Ripgrep produces matches, paths and lines. It never orders them by relevance.
The caller orders them with the deterministic tuple in references/retrieval/retrieval-conventions.md §5.
That tuple is a stable sort, not a relevance model.
The SPECKIT_CROSS_ENCODER/RERANKER_LOCAL flags are no longer wired.
Security
VOYAGE_API_KEY is read from the process environment only. It must never be logged, written into spec docs, or persisted to disk by Spec Kit. Operators should set it in shell init files owned by the operator with mode 600.
- Tests may mutate env vars, but must restore them in
afterEach. Production code paths should not treat mutable process env as request-time configuration.
Validation and Recovery
Run .skilled/skills/system-spec-kit/runtime/cli/spec/validate.sh <spec-folder> --strict before completion claims.
Validation errors block completion. Address or document warnings.
Startup, resume, hook, goal plugin, code graph and Code Graph readiness details live in references/config/hook-system.md, .skilled/skills/system-skill-advisor/hooks/skill-advisor-hook.md, .skilled/hooks/goal/goal-plugin.md, runtime/hooks/README.md and code graph references.
That README covers Claude and OpenCode hook folders. OpenCode uses plugin-backed delivery.
- Eligibility: A Draft packet repairs itself during a
--strict run if every error is derived-metadata that repair-derived.cjs can fix.
- Repair and revalidation:
validate.sh then applies the repair once, prints each rewritten file and validates again.
- Disable conditions: Auto-repair is disabled if
CI is set, SPECKIT_RULES names a subset, or SPECKIT_DRAFT_AUTO_REPAIR is 0, false or off.
- Child validator behavior: Child validator runs inside read-only tools set it to
0.
- Measured-behavior warning: A
spec.md stamped v2.4 or later warns under MEASURED_BEHAVIOR if the measured-behavior anchor is missing or holds neither command output nor a reasoned N/A:.
OpenCode Goal Plugin
- Goal state: The packet
goal.md is the source of goal state.
- Runtime binding and injection: On OpenCode, bind the session with
opencode_goal({ action: "bind", packetPath }). On Pi, use bin/goal.cjs bind <packet> --workspace <repo root>. Each turn, the runtime injects the objective slice built from the file. The per-session record under .skilled/skills/.state/goal/ keeps only the pointer, liveness and telemetry. Use this surface when an operator says "set the goal", "bind the goal", "update the goal" or "resend the goal". Render the parent's chat slice from the file and hand it over to be set. Keep reminding the operator while it stays unset. Never stop work for it. node .skilled/hooks/goal/bin/goal.cjs packet <packet> --workspace <repo root> prints it as chat_slice. Section 4 of sk-create-goal's budget-and-handoff.md defines what the slice contains and when you may send it.
- Authoring:
/create:goal owns authoring or amending a goal.md.
- OpenCode plugin contract: The OpenCode surface is
.opencode/plugins/opencode-goal.js and .opencode/commands/goal-opencode.md. It injects with experimental.chat.system.transform and observes lifecycle events through the plugin event hook. It exposes opencode_goal / opencode_goal_status plugin tools. Use .skilled/hooks/goal/goal-plugin.md for the operator contract, restart requirement, environment variables, validation commands and boundary between raw objective and generated goalPrompt.
Code Graph and Search Routing
4. RULES
✅ ALWAYS
- Determine level (1/2/3/3+) before ANY file changes - Count LOC, assess complexity/risk
- Scaffold from contract-backed templates - Use
create.sh or inline-gate-renderer, NEVER create from scratch
- Fill ALL placeholders - Remove placeholder markers and sample content
- Ask A/B/C/D when file modification detected - Present options, wait for selection. Child dispatch: when
AI_SESSION_CHILD=1 marks a non-interactive worker bound to a lineage directory, Gate 3 is pre-resolved to that directory and the worker does not ask. Interactive sessions always ask.
- Prefer coordinated related packets before new top-level folders - Check active and related specs, their scope, status, and Phase Documentation Map. When related work qualifies for phase decomposition, recommend one phased packet rather than separate single-spec folders.
- Get explicit user approval before changes - Show level, path, templates, approach. Child dispatch: when
AI_SESSION_CHILD=1 marks a non-interactive worker bound to a lineage directory, record the approval request in that directory and continue. Interactive sessions always ask.
- Use consistent folder naming -
specs/###-short-name/ format
- Clear both completion gates (Level 2+) - The
tasks.md verification checklist AND the acceptance-criteria.md closure verdict. Load both before claiming done; see §3 Two Completion Gates
- Mark items
[x] with evidence - Include links, test outputs, screenshots
- Complete P0/P1 before claiming done - No exceptions
- Suggest handover.md on session-end keywords - "continue later", "next session"
- Run validate.sh before completion - Completion Verification requirement
- Create implementation-summary.md at end of implementation phase (Level 1+) - Document what was built
- Suggest /speckit:save when session-end keywords detected OR after extended work (15+ tool calls) - Proactive context preservation
- Suggest Task-tool debug delegation after 3+ failed fix attempts on same error - Do not continue without offering a fresh debugging pass
- Apply the phased-packet preference without bypassing qualification
- Suggest
/speckit:plan :with-phases only when phase complexity score >= 25 AND documentation level >= 3.
- If either condition fails, use a standard packet.
- If the work is new or unrelated, create a separate packet and evaluate it independently.
- A series parent is the exception. A different change to the same artifact as an existing packet in that track joins or creates a series parent (
references/structure/phase-definitions.md §2).
- Route all code creation/updates through
sk-code - Full surface alignment is mandatory before claiming completion
- Authoring-time vs review-time load:
sk-code is loaded at TWO distinct points in /speckit:complete.
- (a) Authoring-time (Step 10 development): For implementation targets under
.skilled/skills/, .skilled/agents/, .skilled/commands/ or .opencode/specs/, load the matching sk-code authoring checklist (../sk-code/sk-code-skilled/assets/checklists/{surface}-authoring.md) before the first write.
For .opencode/specs/ targets, also load these system-spec-kit spec-folder docs before the first write: references/workflows/spec-folder-authoring-checklist.md and references/workflows/spec-folder-write-recipe.md.
- (b) Review-time (Step 11 review): The existing
sk-code code-review mode overlay runs after writes complete. It uses the findings-first baseline and router-selected surface evidence.
- Authoring-time load surfaces invariants the writer needs to honor. Review-time load catches drift the writer did not honor.
- See the
cross_skill_authoring_load block in speckit-complete.yaml for the YAML contract.
- Route all documentation creation/updates through
sk-doc - Full alignment is mandatory before claiming completion
- Enforce ToC policy from validation rules - Only
research/research.md may include a Table of Contents section; remove ToC headings from standard spec artifacts
- Literal naming for AI-derived spec folders and phases
- When the AI (not the user) picks a spec-folder or phase slug, it MUST describe the concrete work being built or fixed.
- Names need a specific subject token: the component, behavior or bug being addressed.
- Forbidden as standalone slugs:
remediation, cleanup, fix, phase-N, review-remediation, round-N.
- Good remediation-packet examples:
fix-deep-review-p1-p2-findings-for-sk-doc-skill, harden-mcp-server-startup-races, fix-singleton-leak-in-launcher.
- Good phase-decomposition examples:
data-model-design, api-implementation, ui-integration.
- Remediation-packet source/target rule: slugs MUST follow
NNN-fix-<source>-for-<target>, where:
- Source = the event or evidence that triggered the packet (e.g.
deep-review-p0-p1-findings, verdict-fail, audit-finding-NN).
- Target = the specific component being remediated (e.g.
skill-local-benchmarks-format, trigger-index-generator, launcher-cache).
- The source names WHERE the work comes from. The target names WHAT is fixed.
- Do not conflate them. The target, not the source, is what is remediated.
- Worked example:
007-fix-deep-review-p0-p1-findings-for-skill-local-benchmarks-format (source=deep-review-p0-p1-findings, target=skill-local-benchmarks-format).
- Documentation-layer guidance:
validate.sh does not lint slugs today (operator decision; may be lifted in a follow-on packet).
⛔ NEVER
- Create documentation from scratch - Use templates only
- Skip spec folder creation - Unless user explicitly selects D
- Make changes before spec + approval - Spec folder is prerequisite. Child dispatch: when
AI_SESSION_CHILD=1 marks a non-interactive worker bound to a lineage directory, record the approval request in that directory and continue. Interactive sessions always ask.
- Leave placeholders in final docs - All must be replaced
- Decide autonomously update vs create - Always ask user. When
AI_SESSION_CHILD=1 marks a non-interactive child, record the update-or-create question with its default in the lineage directory and continue.
- Claim done without clearing both completion gates - Level 2+ requires the
tasks.md verification checklist verified with evidence AND every acceptance-criteria.md criterion Met, Waived or Superseded
- Proceed without spec folder confirmation - Wait for A/B/C/D. Child dispatch: when
AI_SESSION_CHILD=1 marks a non-interactive worker bound to a lineage directory, Gate 3 is pre-resolved to that directory and the worker does not ask. Interactive sessions always ask.
- Skip validation before completion - Completion Verification hard block
- Add ToC sections to standard spec artifacts -
spec.md, plan.md, tasks.md, acceptance-criteria.md, decision-record.md, implementation-summary.md, handover.md and debug-delegation.md must not contain ToC headings
⚠️ ESCALATE IF
- Scope grows during implementation - Run
upgrade-level.sh to add higher-level templates (recommended), then auto-populate all placeholder content:
- Read all existing spec files (spec.md, plan.md, tasks.md, implementation-summary.md) for context
- Replace every placeholder marker pattern in newly injected sections with content derived from that context
- For sections without sufficient source context, write "N/A - insufficient source context" instead of fabricating content
- Run
check-placeholders.sh <spec-folder> to verify zero placeholders remain (see level specifications reference for the full procedure)
- Document the level change in changelog
- Uncertainty about level <80% - Present level options to user, default to higher. When
AI_SESSION_CHILD=1 marks a non-interactive child, record the level question with the higher level as its default in the lineage directory and continue.
- Template doesn't fit requirements - Adapt closest template, document modifications
- User requests skip (Option D) - Warn about tech debt, explain debugging challenges, confirm consent. When
AI_SESSION_CHILD=1 marks a non-interactive child, record the skip request in the lineage directory with documentation kept as the default and continue.
- Validation fails with errors - Report specific failures, provide fix guidance, re-run after fixes
5. SUCCESS CRITERIA
Success means the selected spec folder uses the right template set, placeholders and sample content are removed, links between packet docs work, continuity is saved or updated, Level 2+ tasks.md P0/P1 checklist items are verified with evidence, every acceptance-criteria.md criterion is Met, Waived or Superseded, and validate.sh --strict has no blocking errors.
6. INTEGRATION POINTS
P0 blocks, P1 requires completion or approved deferral, and P2 is optional. Code updates route through sk-code; documentation updates route through sk-doc; git handoff routes through sk-git.
Quick Reference Commands
| Command |
Usage |
| Canonical intake |
/speckit:plan --intake-only "Description" |
| Create spec folder |
./runtime/cli/spec/create.sh "Description" --short-name name --level 2 |
| Create in a track |
Add --track <track> to the create command. The new packet is also listed in specs/<track>/graph-metadata.json |
| Create in a sub-track |
Add --track <track>/<sub> for a declared sub-track. Numbering restarts inside it, and suggest-subtracks.mjs names the best-fitting sub-track for a description |
| Track-root lists |
node .skilled/skills/system-spec-kit/runtime/cli/spec/refresh-track-roots.mjs --apply after moving, renaming or deleting a packet in a track by hand; archive.sh refreshes it itself. The pre-push hook blocks a commit whose track lists other packets than it holds |
| Validate |
.skilled/skills/system-spec-kit/runtime/cli/spec/validate.sh specs/007-feature/ |
| Verify code alignment drift |
python3 .skilled/skills/sk-code/sk-code-skilled/assets/scripts/verify_alignment_drift.py --root .skilled/skills/system-spec-kit |
| Save context |
node .skilled/skills/system-spec-kit/runtime/cli/dist/continuity/generate-context.js /tmp/save-context-data-<session-id>.json specs/007-feature/ |
| Gate 1 trigger lookup |
node .skilled/skills/system-spec-kit/runtime/cli/retrieval/lookup-trigger-index.mjs --json -- "<prompt>" (exit 0 hit, 1 no-hit, 2 broken) |
| Regenerate trigger index |
node .skilled/skills/system-spec-kit/runtime/cli/retrieval/generate-trigger-index.mjs |
| Free-text retrieval |
The ripgrep recipes in references/retrieval/retrieval-conventions.md §2, scoped by the trailing positional path |
| Next spec number |
find specs/<root> specs/<root>/z_archive -mindepth 1 -maxdepth 1 -type d -name '[0-9]*' 2>/dev/null | sed 's#.*/##' | grep -o '^[0-9]*' | sort -n | tail -1 | awk '{n=$1} END{printf "%03d\n", n+1}'. Name one root: a track, a declared sub-track or specs itself. Archived packets count, as they do for create.sh. Without --track, create.sh also counts numbered git branches, so its number can be higher |
| Upgrade level |
bash .skilled/skills/system-spec-kit/runtime/cli/spec/upgrade-level.sh specs/007-feature/ --to 2 |
| Completeness |
.skilled/skills/system-spec-kit/runtime/cli/spec/calculate-completeness.sh specs/007-feature/ |
| Worktree isolation |
.skilled/bin/worktree-session.sh creates a per-session git worktree with isolated SPEC_KIT_DB_DIR / SPECKIT_IPC_SOCKET_DIR. Pair with worktree-reaper.sh for teardown and worktree-guard.sh for lock enforcement |
| Session cleanup |
.skilled/scripts/session-cleanup.sh resolves PIDs across claude/opencode/opencode runtimes |
Canonical command lifecycle:
/speckit:plan --intake-only establishes or repairs the packet when standalone intake is needed.
/deep:research follows ../system-deep-loop/deep-research/references/protocol/spec-check-protocol.md when research needs bounded spec.md anchoring.
- Either
/speckit:plan or /speckit:complete continues from the same folder. It reuses the shared intake contract (.skilled/skills/system-spec-kit/references/workflows/intake-contract.md) only when local folder_state still needs repair.
- When intake runs, the returned
start_state is the canonical downstream field.
Remember: This skill is the foundational documentation orchestrator. It enforces structure, template usage, context preservation, and workflow-required validation for all file modifications. Every conversation that modifies files MUST have a spec folder.
7. REFERENCES AND RELATED RESOURCES
The router discovers reference, asset and script docs dynamically.
Start with these references: references/workflows/quick-reference.md, references/templates/template-guide.md, references/validation/validation-rules.md, references/retrieval/retrieval-conventions.md, references/structure/grep-convention.md and references/memory/save-workflow.md.
Then load task-specific resources from references/, templates from assets/ and automation from runtime/cli/ when present.
Scripts: runtime/cli/spec/validate.sh, runtime/cli/spec/create.sh, runtime/cli/dist/continuity/generate-context.js, runtime/cli/spec/check-completion.sh, runtime/cli/spec/relocate.mjs (moves, renumbers and re-parents packets), runtime/cli/spec/suggest-subtracks.mjs (proposes a sub-track map) and runtime/cli/spec/archive.sh (archives and restores packets).
Related skills: sk-doc for authored documentation quality, sk-code for code changes, sk-git for git handoff, and system-deep-loop for iterative research and audit (its research and review modes).
1---2name: system-spec-kit3description: "Spec-folder workflow + context preservation: Levels 1-3+, validation, trigger-index, ripgrep retrieval. Required for file changes."4allowed-tools: [Bash, Edit, Glob, Grep, Read, Task, Write]5version: 2.13.2.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/system-spec-kit8---910<!-- Keywords: spec-kit, speckit, documentation-workflow, spec-folder, template-enforcement, context-preservation, progressive-documentation, validation, trigger-index, retrieval-conventions, ripgrep-retrieval, continuity-writer, handover, opencode-goal, goal-plugin, active_goal, session-goal, importance-tiers -->1112# Spec Kit - Mandatory Conversation Documentation1314Orchestrates 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.1516## 1. WHEN TO USE1718### What is a Spec Folder?1920A **spec folder** is a numbered directory (e.g., `007-auth-feature/`) that contains documentation for a single feature/task or a coordinated packet of related phase work:2122Spec folders may also be nested as coordination-root packets with direct-child phase folders (e.g., `specs/02--track/022-feature/011-phase/002-child/`).2324- **Purpose**: Track specifications, plans, tasks, and decisions for one unit of work25- **Location**: Under `specs/` using either `###-short-name/` at the root or nested packet paths for phased coordination26- **Contents**: Markdown files (spec.md, plan.md, tasks.md, and implementation-summary.md when work is complete) plus optional support folders such as `scratch/`, `research/`, or `review/`2728Think of it as a "project folder" for AI-assisted development - it keeps context organized and enables session continuity.2930### Activation Triggers3132**MANDATORY for ALL file modifications:**33- Code files: JS, TS, Python, CSS, HTML34- Documentation: Markdown, README, guides35- Configuration: JSON, YAML, TOML, env templates36- Templates, knowledge base, build/tooling files3738**Request patterns that trigger activation:**39- "Add/implement/create [feature]"40- "Fix/update/refactor [code]"41- "Modify/change [configuration]"42- Positive keywords include add, implement, fix, update, create, modify, rename, delete and configure. The authoritative Gate 3 classifier intentionally omits `analyze`, `decompose` and `phase` from positive triggers; `analyze` is a read-only disqualifier unless a real write, memory-save or resume trigger is also present.4344**Example triggers:**45- "Add email validation to the signup form" → Level 1-246- "Refactor the authentication module" → Level 2-347- "Fix the button alignment bug" → Level 148- "Implement user dashboard with analytics" → Level 34950### When NOT to Use5152- Pure exploration/reading (no file modifications)53- Single typo fixes (<5 characters in one file)54- Whitespace-only changes55- Auto-generated file updates (package-lock.json)56- User explicitly selects Option D (skip documentation)5758**Rule of thumb:** If modifying ANY file content → Activate this skill.59Status: ✅ This requirement applies immediately once file edits are requested.6061### Distributed Governance Rule6263Any agent writing authored spec folder docs MUST use contract-backed templates through `create.sh` or the inline renderer.64Authored docs: `spec.md`, `plan.md`, `tasks.md`, `acceptance-criteria.md`, `implementation-summary.md`, `decision-record.md`, `handover.md`, `review-report.md`, `debug-delegation.md`, `goal.md` and `timeline.md`.65`acceptance-criteria.md` is from Level 2. Docs after `implementation-summary.md` are optional add-ons or packet-type docs.66`goal.md` may come from `/create:goal`. Its per-kind templates are parity-checked copies of `goal.md.tmpl`.67This is a workflow-required gate, not a runtime hook.68Run `bash .skilled/skills/system-spec-kit/runtime/cli/spec/validate.sh <spec-folder> --strict --quiet` once after the last authored spec-doc write and before completion claims.69Section 9 of `references/workflows/spec-authoring-card.md` defines the gate.70Each /speckit workflow runs its own strict gate after each doc-writing step.71Then route continuity updates through `/speckit:save`.72The template rule exempts workflow-owned deep-research packet markdown: `research/iterations/*.md`, `research/deep-research-*.md` and progressive `research/research.md` loop updates.73`/deep:research` must run targeted strict validation after every `spec.md` mutation it performs.74@deep-research exclusively writes `research/research.md`. @debug exclusively writes `debug-delegation.md`.7576- `handover.md` stays in the canonical recovery ladder and is maintained through `/speckit:save` handover_state routing using the handover template for initial creation.77- `review-report.md` remains owned by `@deep-review` when deep review workflows synthesize findings.78- The deep loops write their own `resource-map.md` evidence ledger into their artifact directory; it is not a packet add-on.7980### Utility Template Triggers8182| Template | Trigger Keywords | Action |83| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------- |84| `handover.md` | "handover", "next session", "continue later", "pass context", "ending session", "save state", "multi-session", "for next AI" | Suggest `/speckit:save` handover maintenance |85| `debug-delegation.md` | "stuck", "can't fix", "tried everything", "same error", "fresh eyes", "hours on this", "still failing", "need help debugging" | Suggest Task-tool debug delegation |8687**Rule:** When detected, proactively suggest the appropriate action.8889---9091## 2. SMART ROUTING9293No hub sits above this skill, so the triggers in `WHEN TO USE` select it.94A request that writes any file selects it, and so does a create, a save, a resume or a validation question.95`references/workflows/quick-reference.md` loads first on every invocation as the command surface.96The intent keywords choose the rest through `RESOURCE_MAP`. A plan, implement or plain write request starts with `references/workflows/spec-authoring-card.md`.97A request that matches no intent returns `UNKNOWN_FALLBACK` and its checklist rather than a silent default.98Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.99100---101102## 3. HOW IT WORKS103104### Core Workflow1051061. Gate 3 selects an existing, new, related, skipped, or phase spec folder before file changes.1072. For new folders, estimate level from LOC, risk, affected systems, and verification needs; create from contract-backed templates.1083. Keep phase parents lean: parent folders hold `spec.md`, `description.json`, and `graph-metadata.json`; child phases hold working docs.1094. Clear both completion gates before claiming done: the priority-ordered checklist in the `tasks.md` verification section, and the closure verdict in `acceptance-criteria.md`. See Two Completion Gates below.1105. Preserve continuity in `implementation-summary.md` or through canonical `/speckit:save` with `generate-context.js`.111112### Two Completion Gates113114Level 2+ packets close through two different documents. They are often conflated, so keep the question each one answers distinct.115116| | `tasks.md` verification section | `acceptance-criteria.md` |117|---|---|---|118| Answers | Is the work done? | May the packet close? |119| Unit | A checklist item | A criterion, written Given / When / Then |120| Vocabulary | `[ ]` / `[x]`, tagged P0, P1 or P2 | `Met`, `Unmet`, `Waived`, `Superseded` |121| Enforced by | `check-completion.sh` | `AC_CLOSURE` and `AC_COVERAGE` in `validate.sh` |122| Blocks when | A P0 or P1 item is incomplete, an item carries no priority tag, or a completed P0/P1 item cites no evidence. P2 blocks only under `--strict` | Any criterion is still `Unmet`, or a `Waived` or `Superseded` row names a decision record that does not exist |123124The two are linked rather than parallel. `AC_COVERAGE` requires every criterion's evidence to trace back into the merged tasks document, so `tasks.md` is where the proof lives and `acceptance-criteria.md` is where the verdict lives. A criterion marked `Met` with no traceable item behind it is the failure that rule exists to catch.125126`acceptance-criteria.md` is an optional add-on: `validate.sh` warns when a Level 2+ packet has none. Once the file exists, `AC_CLOSURE` is an error-severity gate on that packet.127128### Retrieval and Continuity129130Retrieval is file-based and needs no running service.131Gate 1 resolves a prompt against the committed trigger index with `node .skilled/skills/system-spec-kit/runtime/cli/retrieval/lookup-trigger-index.mjs --json -- "<prompt>"`.132When the index scores nothing, it also scores the declared `trigger_phrases` of spec docs the index does not list yet and reports that scan in `staleFallback`; `--no-stale-fallback` keeps it index-only.133It exits `0` on candidates from either source, `1` on a clean no-hit and `2` on a bad invocation or unreadable index.134Free-text retrieval uses the literal ripgrep recipes in [`references/retrieval/retrieval-conventions.md`](references/retrieval/retrieval-conventions.md).135The trailing positional path scopes them by track and packet. The recipes are precise only because the corpus is regular.136[`references/structure/grep-convention.md`](references/structure/grep-convention.md) holds the frontmatter, anchor, naming and body-preservation rules. `validate.sh` enforces them on every spec document.137138Recovery follows the continuity ladder, which stays the primary path, rather than inferring a session:1391401. `handover.md`1412. The `_memory.continuity` frontmatter block1423. Packet-first spec docs1434. The bounded context recipe144145`/speckit:resume` owns the ladder. A claimed handoff note can add one bounded `## History Lookup` section, and that lookup never replaces the ladder.146Saves go through `node .skilled/skills/system-spec-kit/runtime/cli/dist/continuity/generate-context.js`, invoked by `/speckit:save`.147The writer updates the packet's continuity surfaces in place.148149- A `--full-auto` save also writes the payload's `operatorDecisions` into the target packet's `decision-record.md`, creating it when absent and first stamping a missing level marker into `spec.md` so the packet's level does not move.150- No indexing hand-off follows.151152Regenerate the index with `node .skilled/skills/system-spec-kit/runtime/cli/retrieval/generate-trigger-index.mjs` after spec-doc frontmatter changes. The artifact at `runtime/data/trigger-index.json` is committed, so a fresh clone answers Gate 1 before anything is built.153154**Declared loss.** Semantic paraphrase matching, vector and BM25 fusion, decay scoring, access tracking, session dedup and causal traversal are gone.155They have no file-based successor.156A lookup with no match returns nothing. Callers must say so plainly, not guess.157The index cannot find undeclared `trigger_phrases`. See `references/retrieval/retrieval-conventions.md` §8 for what belongs there.158159### Reranking160161Nothing reranks retrieval today.162Model-based cross-encoder/local-GGUF reranking, the local model path, the local rerank sidecar skill and cloud rerankers are retired.163Ripgrep produces matches, paths and lines. It never orders them by relevance.164The caller orders them with the deterministic tuple in `references/retrieval/retrieval-conventions.md` §5.165That tuple is a stable sort, not a relevance model.166The `SPECKIT_CROSS_ENCODER`/`RERANKER_LOCAL` flags are no longer wired.167168### Security169170- `VOYAGE_API_KEY` is read from the process environment only. It must never be logged, written into spec docs, or persisted to disk by Spec Kit. Operators should set it in shell init files owned by the operator with mode `600`.171- Tests may mutate env vars, but must restore them in `afterEach`. Production code paths should not treat mutable process env as request-time configuration.172173### Validation and Recovery174175Run `.skilled/skills/system-spec-kit/runtime/cli/spec/validate.sh <spec-folder> --strict` before completion claims.176Validation errors block completion. Address or document warnings.177Startup, resume, hook, goal plugin, code graph and Code Graph readiness details live in `references/config/hook-system.md`, `.skilled/skills/system-skill-advisor/hooks/skill-advisor-hook.md`, `.skilled/hooks/goal/goal-plugin.md`, `runtime/hooks/README.md` and code graph references.178That README covers Claude and OpenCode hook folders. OpenCode uses plugin-backed delivery.179180- **Eligibility:** A Draft packet repairs itself during a `--strict` run if every error is derived-metadata that `repair-derived.cjs` can fix.181- **Repair and revalidation:** `validate.sh` then applies the repair once, prints each rewritten file and validates again.182- **Disable conditions:** Auto-repair is disabled if `CI` is set, `SPECKIT_RULES` names a subset, or `SPECKIT_DRAFT_AUTO_REPAIR` is `0`, `false` or `off`.183- **Child validator behavior:** Child validator runs inside read-only tools set it to `0`.184- **Measured-behavior warning:** A `spec.md` stamped v2.4 or later warns under `MEASURED_BEHAVIOR` if the `measured-behavior` anchor is missing or holds neither command output nor a reasoned `N/A:`.185186### OpenCode Goal Plugin187188- **Goal state:** The packet `goal.md` is the source of goal state.189- **Runtime binding and injection:** On OpenCode, bind the session with `opencode_goal({ action: "bind", packetPath })`. On Pi, use `bin/goal.cjs bind <packet> --workspace <repo root>`. Each turn, the runtime injects the objective slice built from the file. The per-session record under `.skilled/skills/.state/goal/` keeps only the pointer, liveness and telemetry. Use this surface when an operator says "set the goal", "bind the goal", "update the goal" or "resend the goal". Render the parent's chat slice from the file and hand it over to be set. Keep reminding the operator while it stays unset. Never stop work for it. `node .skilled/hooks/goal/bin/goal.cjs packet <packet> --workspace <repo root>` prints it as `chat_slice`. Section 4 of `sk-create-goal`'s [budget-and-handoff.md](../sk-doc/sk-create-goal/references/budget-and-handoff.md) defines what the slice contains and when you may send it.190- **Authoring:** `/create:goal` owns authoring or amending a `goal.md`.191- **OpenCode plugin contract:** The OpenCode surface is `.opencode/plugins/opencode-goal.js` and `.opencode/commands/goal-opencode.md`. It injects with `experimental.chat.system.transform` and observes lifecycle events through the plugin `event` hook. It exposes `opencode_goal` / `opencode_goal_status` plugin tools. Use [`.skilled/hooks/goal/goal-plugin.md`](../../hooks/goal/goal-plugin.md) for the operator contract, restart requirement, environment variables, validation commands and boundary between raw `objective` and generated `goalPrompt`.192193### Code Graph and Search Routing194195196---197198## 4. RULES199200### ✅ ALWAYS2012021. **Determine level (1/2/3/3+) before ANY file changes** - Count LOC, assess complexity/risk2032. **Scaffold from contract-backed templates** - Use `create.sh` or `inline-gate-renderer`, NEVER create from scratch2043. **Fill ALL placeholders** - Remove placeholder markers and sample content2054. **Ask A/B/C/D when file modification detected** - Present options, wait for selection. **Child dispatch:** when `AI_SESSION_CHILD=1` marks a non-interactive worker bound to a lineage directory, Gate 3 is pre-resolved to that directory and the worker does not ask. Interactive sessions always ask.2065. **Prefer coordinated related packets before new top-level folders** - Check active and related specs, their scope, status, and Phase Documentation Map. When related work qualifies for phase decomposition, recommend one phased packet rather than separate single-spec folders.2076. **Get explicit user approval before changes** - Show level, path, templates, approach. **Child dispatch:** when `AI_SESSION_CHILD=1` marks a non-interactive worker bound to a lineage directory, record the approval request in that directory and continue. Interactive sessions always ask.2087. **Use consistent folder naming** - `specs/###-short-name/` format2098. **Clear both completion gates (Level 2+)** - The `tasks.md` verification checklist AND the `acceptance-criteria.md` closure verdict. Load both before claiming done; see §3 Two Completion Gates2109. **Mark items `[x]` with evidence** - Include links, test outputs, screenshots21110. **Complete P0/P1 before claiming done** - No exceptions21211. **Suggest handover.md on session-end keywords** - "continue later", "next session"21312. **Run validate.sh before completion** - Completion Verification requirement21413. **Create implementation-summary.md at end of implementation phase (Level 1+)** - Document what was built21514. **Suggest /speckit:save when session-end keywords detected OR after extended work (15+ tool calls)** - Proactive context preservation21615. **Suggest Task-tool debug delegation after 3+ failed fix attempts on same error** - Do not continue without offering a fresh debugging pass21716. **Apply the phased-packet preference without bypassing qualification**218 - Suggest `/speckit:plan :with-phases` only when phase complexity score >= 25 AND documentation level >= 3.219 - If either condition fails, use a standard packet.220 - If the work is new or unrelated, create a separate packet and evaluate it independently.221 - A series parent is the exception. A different change to the same artifact as an existing packet in that track joins or creates a series parent (`references/structure/phase-definitions.md` §2).22217. **Route all code creation/updates through `sk-code`** - Full surface alignment is mandatory before claiming completion223 - **Authoring-time vs review-time load**: `sk-code` is loaded at TWO distinct points in `/speckit:complete`.224 - **(a) Authoring-time (Step 10 development):** For implementation targets under `.skilled/skills/`, `.skilled/agents/`, `.skilled/commands/` or `.opencode/specs/`, load the matching sk-code authoring checklist (`../sk-code/sk-code-skilled/assets/checklists/{surface}-authoring.md`) before the first write.225 For `.opencode/specs/` targets, also load these system-spec-kit spec-folder docs before the first write: `references/workflows/spec-folder-authoring-checklist.md` and `references/workflows/spec-folder-write-recipe.md`.226 - **(b) Review-time (Step 11 review):** The existing `sk-code` code-review mode overlay runs after writes complete. It uses the findings-first baseline and router-selected surface evidence.227 - Authoring-time load surfaces invariants the writer needs to honor. Review-time load catches drift the writer did not honor.228 - See the `cross_skill_authoring_load` block in `speckit-complete.yaml` for the YAML contract.22918. **Route all documentation creation/updates through `sk-doc`** - Full alignment is mandatory before claiming completion23019. **Enforce ToC policy from validation rules** - Only `research/research.md` may include a Table of Contents section; remove ToC headings from standard spec artifacts23120. **Literal naming for AI-derived spec folders and phases**232 - When the AI (not the user) picks a spec-folder or phase slug, it MUST describe the concrete work being built or fixed.233 - Names need a specific subject token: the component, behavior or bug being addressed.234 - Forbidden as standalone slugs: `remediation`, `cleanup`, `fix`, `phase-N`, `review-remediation`, `round-N`.235 - Good remediation-packet examples: `fix-deep-review-p1-p2-findings-for-sk-doc-skill`, `harden-mcp-server-startup-races`, `fix-singleton-leak-in-launcher`.236 - Good phase-decomposition examples: `data-model-design`, `api-implementation`, `ui-integration`.237 - **Remediation-packet source/target rule:** slugs MUST follow `NNN-fix-<source>-for-<target>`, where:238 - **Source** = the event or evidence that triggered the packet (e.g. `deep-review-p0-p1-findings`, `verdict-fail`, `audit-finding-NN`).239 - **Target** = the specific component being remediated (e.g. `skill-local-benchmarks-format`, `trigger-index-generator`, `launcher-cache`).240 - The source names WHERE the work comes from. The target names WHAT is fixed.241 - Do not conflate them. The target, not the source, is what is remediated.242 - Worked example: `007-fix-deep-review-p0-p1-findings-for-skill-local-benchmarks-format` (source=deep-review-p0-p1-findings, target=skill-local-benchmarks-format).243 - Documentation-layer guidance: `validate.sh` does not lint slugs today (operator decision; may be lifted in a follow-on packet).244245### ⛔ NEVER2462471. **Create documentation from scratch** - Use templates only2482. **Skip spec folder creation** - Unless user explicitly selects D2493. **Make changes before spec + approval** - Spec folder is prerequisite. **Child dispatch:** when `AI_SESSION_CHILD=1` marks a non-interactive worker bound to a lineage directory, record the approval request in that directory and continue. Interactive sessions always ask.2504. **Leave placeholders in final docs** - All must be replaced2515. **Decide autonomously update vs create** - Always ask user. When `AI_SESSION_CHILD=1` marks a non-interactive child, record the update-or-create question with its default in the lineage directory and continue.2526. **Claim done without clearing both completion gates** - Level 2+ requires the `tasks.md` verification checklist verified with evidence AND every `acceptance-criteria.md` criterion `Met`, `Waived` or `Superseded`2537. **Proceed without spec folder confirmation** - Wait for A/B/C/D. **Child dispatch:** when `AI_SESSION_CHILD=1` marks a non-interactive worker bound to a lineage directory, Gate 3 is pre-resolved to that directory and the worker does not ask. Interactive sessions always ask.2548. **Skip validation before completion** - Completion Verification hard block2559. **Add ToC sections to standard spec artifacts** - `spec.md`, `plan.md`, `tasks.md`, `acceptance-criteria.md`, `decision-record.md`, `implementation-summary.md`, `handover.md` and `debug-delegation.md` must not contain ToC headings256257### ⚠️ ESCALATE IF2582591. **Scope grows during implementation** - Run `upgrade-level.sh` to add higher-level templates (recommended), then auto-populate all placeholder content:260 - Read all existing spec files (spec.md, plan.md, tasks.md, implementation-summary.md) for context261 - Replace every placeholder marker pattern in newly injected sections with content derived from that context262 - For sections without sufficient source context, write "N/A - insufficient source context" instead of fabricating content263 - Run `check-placeholders.sh <spec-folder>` to verify zero placeholders remain (see level specifications reference for the full procedure)264 - Document the level change in changelog2652. **Uncertainty about level <80%** - Present level options to user, default to higher. When `AI_SESSION_CHILD=1` marks a non-interactive child, record the level question with the higher level as its default in the lineage directory and continue.2663. **Template doesn't fit requirements** - Adapt closest template, document modifications2674. **User requests skip (Option D)** - Warn about tech debt, explain debugging challenges, confirm consent. When `AI_SESSION_CHILD=1` marks a non-interactive child, record the skip request in the lineage directory with documentation kept as the default and continue.2685. **Validation fails with errors** - Report specific failures, provide fix guidance, re-run after fixes269270---271272## 5. SUCCESS CRITERIA273274Success means the selected spec folder uses the right template set, placeholders and sample content are removed, links between packet docs work, continuity is saved or updated, Level 2+ `tasks.md` P0/P1 checklist items are verified with evidence, every `acceptance-criteria.md` criterion is `Met`, `Waived` or `Superseded`, and `validate.sh --strict` has no blocking errors.275276---277278## 6. INTEGRATION POINTS279280P0 blocks, P1 requires completion or approved deferral, and P2 is optional. Code updates route through `sk-code`; documentation updates route through `sk-doc`; git handoff routes through `sk-git`.281282### Quick Reference Commands283284| Command | Usage |285| --- | --- |286| Canonical intake | `/speckit:plan --intake-only "Description"` |287| Create spec folder | `./runtime/cli/spec/create.sh "Description" --short-name name --level 2` |288| Create in a track | Add `--track <track>` to the create command. The new packet is also listed in `specs/<track>/graph-metadata.json` |289| Create in a sub-track | Add `--track <track>/<sub>` for a declared sub-track. Numbering restarts inside it, and `suggest-subtracks.mjs` names the best-fitting sub-track for a description |290| Track-root lists | `node .skilled/skills/system-spec-kit/runtime/cli/spec/refresh-track-roots.mjs --apply` after moving, renaming or deleting a packet in a track by hand; `archive.sh` refreshes it itself. The pre-push hook blocks a commit whose track lists other packets than it holds |291| Validate | `.skilled/skills/system-spec-kit/runtime/cli/spec/validate.sh specs/007-feature/` |292| Verify code alignment drift | `python3 .skilled/skills/sk-code/sk-code-skilled/assets/scripts/verify_alignment_drift.py --root .skilled/skills/system-spec-kit` |293| Save context | `node .skilled/skills/system-spec-kit/runtime/cli/dist/continuity/generate-context.js /tmp/save-context-data-<session-id>.json specs/007-feature/` |294| Gate 1 trigger lookup | `node .skilled/skills/system-spec-kit/runtime/cli/retrieval/lookup-trigger-index.mjs --json -- "<prompt>"` (exit `0` hit, `1` no-hit, `2` broken) |295| Regenerate trigger index | `node .skilled/skills/system-spec-kit/runtime/cli/retrieval/generate-trigger-index.mjs` |296| Free-text retrieval | The ripgrep recipes in `references/retrieval/retrieval-conventions.md` §2, scoped by the trailing positional path |297| Next spec number | `find specs/<root> specs/<root>/z_archive -mindepth 1 -maxdepth 1 -type d -name '[0-9]*' 2>/dev/null \| sed 's#.*/##' \| grep -o '^[0-9]*' \| sort -n \| tail -1 \| awk '{n=$1} END{printf "%03d\n", n+1}'`. Name one root: a track, a declared sub-track or `specs` itself. Archived packets count, as they do for `create.sh`. Without `--track`, `create.sh` also counts numbered git branches, so its number can be higher |298| Upgrade level | `bash .skilled/skills/system-spec-kit/runtime/cli/spec/upgrade-level.sh specs/007-feature/ --to 2` |299| Completeness | `.skilled/skills/system-spec-kit/runtime/cli/spec/calculate-completeness.sh specs/007-feature/` |300| Worktree isolation | `.skilled/bin/worktree-session.sh` creates a per-session git worktree with isolated `SPEC_KIT_DB_DIR` / `SPECKIT_IPC_SOCKET_DIR`. Pair with `worktree-reaper.sh` for teardown and `worktree-guard.sh` for lock enforcement |301| Session cleanup | `.skilled/scripts/session-cleanup.sh` resolves PIDs across claude/opencode/opencode runtimes |302303Canonical command lifecycle:304- `/speckit:plan --intake-only` establishes or repairs the packet when standalone intake is needed.305- `/deep:research` follows `../system-deep-loop/deep-research/references/protocol/spec-check-protocol.md` when research needs bounded `spec.md` anchoring.306- Either `/speckit:plan` or `/speckit:complete` continues from the same folder. It reuses the shared intake contract (`.skilled/skills/system-spec-kit/references/workflows/intake-contract.md`) only when local `folder_state` still needs repair.307- When intake runs, the returned `start_state` is the canonical downstream field.308309**Remember**: This skill is the foundational documentation orchestrator. It enforces structure, template usage, context preservation, and workflow-required validation for all file modifications. Every conversation that modifies files MUST have a spec folder.310311---312313## 7. REFERENCES AND RELATED RESOURCES314315The router discovers reference, asset and script docs dynamically.316Start with these references: `references/workflows/quick-reference.md`, `references/templates/template-guide.md`, `references/validation/validation-rules.md`, `references/retrieval/retrieval-conventions.md`, `references/structure/grep-convention.md` and `references/memory/save-workflow.md`.317Then load task-specific resources from `references/`, templates from `assets/` and automation from `runtime/cli/` when present.318319Scripts: `runtime/cli/spec/validate.sh`, `runtime/cli/spec/create.sh`, `runtime/cli/dist/continuity/generate-context.js`, `runtime/cli/spec/check-completion.sh`, `runtime/cli/spec/relocate.mjs` (moves, renumbers and re-parents packets), `runtime/cli/spec/suggest-subtracks.mjs` (proposes a sub-track map) and `runtime/cli/spec/archive.sh` (archives and restores packets).320321Related skills: `sk-doc` for authored documentation quality, `sk-code` for code changes, `sk-git` for git handoff, and `system-deep-loop` for iterative research and audit (its `research` and `review` modes).