@runecraft/grimoire 1.0.0

package/skills/spec-driven/README.md

@@ -0,0 +1,335 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/Skill-spec--driven-blue?style=for-the-badge" alt="skill badge" />
+  <img src="https://img.shields.io/badge/Stack-Agnostic-green?style=for-the-badge" alt="stack agnostic" />
+  <img src="https://img.shields.io/badge/Version-5.0.0-purple?style=for-the-badge" alt="version" />
+</p>
+
+<h1 align="center">🎯 spec-driven</h1>
+
+<p align="center">
+  <strong>Spec-driven planning with 4 adaptive phases and an independent Verifier.<br/>Tests derive from spec. One atomic commit per task. Lessons improve over time.</strong>
+</p>
+
+---
+
+## ✨ What Is This Skill?
+
+**spec-driven** is a feature planning skill that turns a description into traceable requirements, an atomic task breakdown, a verifiable implementation, and a self-improving lessons log. It auto-sizes depth by complexity — using inline execution for small changes and a full phase workflow for large or ambiguous features.
+
+```
+SPECIFY → (DESIGN) → (TASKS) → EXECUTE → VERIFY → LEARN
+```
+
+| Scope | Effort | What happens |
+|-------|--------|--------------|
+| **Small** | ≤3 files, one sentence | One-liner spec inline, implement + verify inline |
+| **Medium** | Clear feature, <10 tasks | Brief spec, design and tasks implicit in Execute |
+| **Large** | Multi-component | Full spec with requirement IDs, architecture, task breakdown |
+| **Complex** | Ambiguity, new domain | Full spec, gray-area discussion, research-backed design, interactive UAT |
+
+> **The complexity is in the system, not in your workflow.** Trigger naturally — the skill decides how deep to go.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Install with the catalog installer (`npx @runecraft/grimoire install`) or copy the skill folder manually — see the [catalog README](../../README.md) for targets and options.
+
+### First Commands
+
+| What You Want | Say This |
+|---------------|----------|
+| Specify a feature | `/spec` or `specify feature` or `vamos especificar` |
+| Discuss gray areas | `discuss feature` or `discutir este caso` |
+| Design the approach | `design` or `design da feature` |
+| Break into tasks | `plan this` or `quebrar em tarefas` |
+| Implement | `/build` or `implement` or `implementar` |
+| Validate / verify | `validate`, `verify work`, `UAT`, `validar implementação` |
+| Pause session | `/spec pause` or `pausar trabalho` |
+| Resume session | `/spec resume` or `retomar trabalho` |
+
+**🇵🇹 🇬🇧 PT/EN — both languages are first-class triggers; the skill body is English.**
+
+---
+
+## 📁 Project Structure
+
+The skill creates and maintains a `.specs/` directory:
+
+```
+.specs/
+├── STATE.md                 # Project memory: Decisions log (AD-NNN) + Handoff snapshot
+├── LESSONS.md               # Self-improving lessons playbook (rendered, do not hand-edit)
+├── lessons.json             # Canonical lessons state (machine-owned)
+└── features/
+    └── <name>/              # One per feature
+        ├── spec.md          # Requirements with traceable IDs
+        ├── context.md       # User decisions for gray areas (Complex scope)
+        ├── design.md        # Architecture & components (Large/Complex)
+        ├── tasks.md         # Atomic tasks with verification
+        └── validation.md    # Verifier report: PASS/FAIL, evidence, sensor result
+```
+
+---
+
+## 🔄 The Four Phases
+
+#### SPECIFY — Requirements & Traceability
+**Goal:** Capture what to build with testable, traceable requirements.  
+**Triggers:** `/spec`, `specify feature`, `vamos especificar`  
+**Skipped when:** Never — always required.  
+**Output:** `spec.md` with `[FEAT-NN]` requirement IDs.
+
+#### DESIGN — Architecture & Components
+**Goal:** Define the technical approach, code reuse analysis, and component boundaries.  
+**Triggers:** `design`, `design da feature`  
+**Skipped when:** Small/Medium scope (no architectural decisions).  
+**Output:** `design.md` with architecture overview, components, data models, decisions.
+
+#### TASKS — Atomic Breakdown
+**Goal:** Decompose the spec into atomic, independently verifiable, sequentially ordered tasks.  
+**Triggers:** `break into tasks`, `quebrar em tarefas`  
+**Skipped when:** ≤3 obvious steps (implicit in Execute).  
+**Output:** `tasks.md` with What, Where, Requirement IDs, and Done-when criteria.
+
+#### EXECUTE — Implement + Verify
+**Goal:** Implement each task sequentially with one atomic commit per task.  
+**Triggers:** `/build`, `implement`, `implementar`  
+**Skipped when:** Never — always required.  
+**Output:** Code changes, task checkmarks, atomic commits, `validation.md` from the Verifier.
+
+---
+
+## 🛡️ The Verifier
+
+After the last task is committed, a **fresh Verifier sub-agent** runs automatically — never optional, never prompted. The author is not the verifier: the Verifier re-derives coverage independently.
+
+The Verifier:
+
+1. **Spec-anchored outcome check** — confirms each test's asserted value matches the spec-defined expected outcome. Flags spec-precision gaps.
+2. **Discrimination sensor** — injects behavior-level faults in scratch state, confirms tests kill them. Surviving mutants become fix tasks.
+3. **Writes `validation.md`** — PASS/FAIL, per-AC evidence, sensor result, diff range.
+4. **Returns a compact verdict** + ranked gap list to the orchestrator.
+5. **Distills lessons** — turns each grounded failure into a reusable project-local lesson via `scripts/lessons.py`. A clean PASS records nothing.
+
+The fix→re-verify loop is bounded to 3 iterations before escalating.
+
+---
+
+## 📚 Lessons
+
+The lessons layer turns verification failures into project-local guidance:
+
+```bash
+# Load confirmed lessons at Specify / Design
+python3 scripts/lessons.py list --status confirmed
+
+# Record a new lesson
+python3 scripts/lessons.py add --rule "..." --rationale "..." --source feature-x
+```
+
+`LESSONS.md` is rendered from `lessons.json` — do not hand-edit. Confirmed lessons only are loaded into planning context; candidates are kept isolated to avoid noise.
+
+---
+
+## 🎯 Complete Trigger Reference
+
+### English Triggers
+
+| Phase | Triggers |
+|-------|----------|
+| **SPECIFY** | `/spec`, `specify feature`, `write spec`, `what should we build` |
+| **DISCUSS** | `discuss feature`, `capture context`, `how should this work` |
+| **DESIGN** | `design`, `design the feature` |
+| **TASKS** | `break into tasks`, `create tasks` |
+| **EXECUTE** | `/build`, `implement`, `execute tasks` |
+| **VALIDATE** | `validate`, `verify work`, `UAT`, `walk me through it` |
+| **MEMORY** | `record decision`, `pause work`, `resume work` |
+| **LESSONS** | `load lessons`, `record lesson`, `distill lessons` |
+
+### Portuguese Triggers
+
+| Fase | Triggers |
+|------|----------|
+| **SPECIFY** | `vamos especificar`, `preciso de um spec`, `especificar feature` |
+| **DISCUSS** | `discutir feature`, `discutir este caso` |
+| **DESIGN** | `design da feature`, `arquitetura` |
+| **TASKS** | `quebrar em tarefas`, `criar tarefas` |
+| **EXECUTE** | `implementar`, `build`, `construir` |
+| **VALIDATE** | `validar implementação`, `verificar`, `testar comigo` |
+| **MEMORY** | `pausar trabalho`, `retomar trabalho`, `salvar decisão` |
+| **LESSONS** | `carregar lições`, `registrar lição` |
+
+### Special Triggers
+
+| Trigger | Action |
+|---------|--------|
+| `/spec pause` or `pausar trabalho` | Save handoff snapshot, update STATE.md |
+| `/spec resume` or `retomar trabalho` | Load handoff, re-confirm Decisions, propose next step |
+
+---
+
+## 🔁 Workflow Examples
+
+### Greenfield Feature
+
+```
+/spec payment-flow → /build → Verifier (auto) → done
+```
+
+Full pipeline: write spec with traceable IDs, design the architecture, break into atomic tasks, implement, independent Verifier.
+
+### Brownfield Fix
+
+```
+specify: fix dark mode persistence → inline execute → Verifier (auto) → done
+```
+
+Small scope: one-liner spec, inline implementation, automatic verification.
+
+### Session Continuity
+
+```
+Session 1: /spec → /build (partial) → /spec pause
+Session 2: /spec resume → continue /build → Verifier (auto) → done
+```
+
+Pause at any point, resume exactly where you left off via STATE.md Handoff.
+
+---
+
+## 🧠 Context Management
+
+The skill manages a **40k context token budget** for planning, with 160k+ reserved for work, reasoning, and outputs:
+
+| Tier | Documents | When loaded |
+|------|-----------|-------------|
+| **Always-on-demand** | `.specs/STATE.md` (Decisions at Design, Handoff on resume) | Per phase |
+| **Confirmed lessons** | `python3 scripts/lessons.py list --status confirmed` | Specify, Design |
+| **Feature context** | `spec.md`, `context.md`, `design.md`, `tasks.md` | Per feature |
+| **Never simultaneous** | Multiple feature specs, multiple architecture docs | — |
+
+If context exceeds 40k, display status and apply the [context-limits](references/context-limits.md) strategy.
+
+---
+
+## 🔗 Skill Integrations
+
+| Skill | When activated | Behavior |
+|-------|---------------|----------|
+| **mermaid-studio** | During DESIGN, for architecture diagrams | Delegates diagram generation |
+| **codenavi** | During SPECIFY/DESIGN | Deep codebase navigation for context |
+
+Detected automatically. Gracefully falls back if not installed.
+
+---
+
+## 📚 Reference Files
+
+12 supporting files, loaded on-demand within the 40k budget:
+
+### Phase files
+| File | Purpose |
+|------|---------|
+| `specify.md` | Spec writing discipline, requirement IDs, traceability |
+| `discuss.md` | Gray-area discussion, user-decision capture |
+| `design.md` | Architecture, code reuse analysis, components |
+| `tasks.md` | Atomic task breakdown, dependencies, verification |
+| `implement.md` | Build cycle, atomic commit policy, gate enforcement |
+| `validate.md` | Verifier behavior, spec-anchored check, discrimination sensor |
+
+### Memory & patterns
+| File | Purpose |
+|------|---------|
+| `memory.md` | STATE.md (Decisions log + Handoff), pause/resume |
+| `lessons.md` | Lessons layer, machine-owned state, distillation rules |
+| `sub-agents.md` | Sub-agent delegation contracts, Verifier payload |
+| `code-analysis.md` | Code search & structural analysis tools |
+| `coding-principles.md` | Coding standards enforced during BUILD |
+| `context-limits.md` | Token budget strategy, what to drop under pressure |
+
+### Script
+| File | Purpose |
+|------|---------|
+| `scripts/lessons.py` | Lessons CLI — list, add, confirm, render LESSONS.md |
+
+---
+
+## ⚡ Tips for Best Results
+
+### Do's ✅
+- Trigger naturally in PT or EN — the skill understands both
+- Trust the auto-sizing — the skill decides phase depth from scope
+- Read reference files completely (to EOF) before acting on them
+- Say `/spec pause` before ending a session
+- Let the Verifier run — never skip it, never self-validate
+
+### Don'ts ❌
+- Don't weaken, skip, or delete tests to make them pass
+- Don't batch multiple tasks into a single commit
+- Don't load multiple feature specs simultaneously
+- Don't fabricate APIs or patterns — follow the Knowledge Verification Chain
+- Don't accept "tests pass" without checking the test asserts spec outcomes, not implementation details
+
+---
+
+## 🤖 Compatibility
+
+Tested and verified on:
+
+| Agent | Status | Notes |
+|-------|--------|-------|
+| **Claude Code** | ✅ Fully supported | Primary reference agent |
+| **Cursor** | ✅ Fully supported | Excellent for inline editing |
+| **Opencode** | ✅ Fully supported | Multi-agent routing works natively |
+| **GitHub Copilot** | ✅ Fully supported | Via custom instructions |
+
+Works with any agent supporting custom instructions and tool use.
+
+---
+
+## ❓ FAQ
+
+**Q: Why is the Verifier separate from the executor?**  
+A: Author ≠ verifier prevents the executor's mental model from biasing the validation. The Verifier re-derives coverage independently using evidence-or-zero: each AC either has test evidence or counts as a gap.
+
+**Q: What if a test passes but doesn't actually test the spec outcome?**  
+A: The spec-anchored outcome check flags this as a spec-precision gap. The test asserts implementation details instead of the spec-defined behavior; the test must be rewritten.
+
+**Q: What is the discrimination sensor?**  
+A: A mutation-testing pass. The Verifier injects behavior-level faults in scratch state and confirms the test suite kills them. Surviving mutants mean tests are too weak; those mutants become fix tasks.
+
+**Q: How do lessons work?**  
+A: Each grounded failure (surviving mutant, spec-precision gap, failed AC) becomes a lesson via `scripts/lessons.py`. Confirmed lessons load into Specify and Design context. A clean PASS records nothing — the skill stays quiet when nothing went wrong.
+
+**Q: Why did the auto-sizing skip TASKS for my Medium feature?**  
+A: When there are ≤3 obvious steps, tasks become implicit in Execute. The safety valve: Execute ALWAYS lists atomic steps inline first. If the list reveals >5 steps or complex dependencies, STOP and create a formal `tasks.md`.
+
+**Q: Can I use this for small bug fixes?**  
+A: Yes — that's the Small scope (≤3 files, one sentence). One-liner spec inline, implement, verify. No ceremony.
+
+**Q: What if I close my session mid-task?**  
+A: Say `/spec pause` before ending. The Handoff snapshot in STATE.md captures the in-flight state; `/spec resume` next session continues from there.
+
+**Q: PT or EN?**  
+A: Both. All triggers work in Portuguese and English as first-class citizens. The skill body is English.
+
+**Q: Does this work with any tech stack?**  
+A: Yes. Stack-agnostic. Works with any language, framework, or architecture.
+
+**Q: Will the agent fabricate APIs or patterns?**  
+A: No. The Knowledge Verification Chain enforces: codebase → project docs → Context7 MCP → web search → flag as uncertain. It never guesses silently.
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+<p align="center">
+  <sub>Part of the <a href="https://github.com/runecraftai/skills">Grimoire</a> catalog</sub>
+</p>

package/skills/spec-driven/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: spec-driven
+description: >
+  Planning and implementation with 4 adaptive phases — Specify, Design, Tasks, Execute. Auto-sizes
+  depth by complexity. Atomic tasks with verification criteria, atomic git commits, requirement
+  traceability. Independent Verifier (author != verifier, evidence-or-zero), decision log
+  (STATE.md), test-coverage-matrix-driven tests, self-improving lessons layer. Stack-agnostic. Use
+  when planning features (requirements, design, task breakdown), implementing with verification
+  and atomic commits, or validating against a spec. Triggers (PT/EN): "specify feature", "vamos
+  especificar", "discutir feature", "discutir este caso", "design", "design da feature",
+  "tarefas", "quebrar em tarefas", "implementar", "build", "validar", "verify work", "UAT",
+  "validar implementação", "record decision", "pause work", "pausar trabalho", "resume work",
+  "retomar trabalho". Do NOT use for architecture decomposition analysis (use architecture skills)
+  or technical design docs (Complex scope: gray areas + architecture-focused design).
+license: CC-BY-4.0
+metadata:
+  version: 5.0.0
+---
+
+# spec-driven
+
+Plan and implement features with precision. Granular tasks. Clear dependencies. Right tools. Zero ceremony.
+
+```
+┌──────────┐   ┌──────────┐   ┌─────────┐   ┌─────────┐
+│ SPECIFY  │ → │  DESIGN  │ → │  TASKS  │ → │ EXECUTE │
+└──────────┘   └──────────┘   └─────────┘   └─────────┘
+   required      optional*      optional*     required
+
+* Agent auto-skips when scope doesn't need it
+```
+
+## Critical Rules (read before acting)
+
+**Loading this skill's files.** Reference files live under `references/` in this skill's own directory (where this `SKILL.md` resides). Resolve them relative to the skill directory — never the workspace root — and load them through the active skill by name; never assume a fixed install path. When a step tells you to read a reference, **read it completely (to EOF)** before acting — never act on a partial/truncated read.
+
+**Execution contract — every task, non-negotiable (holds even if you do not open the reference files):**
+
+1. Tests derive from the spec's acceptance criteria and assert spec-defined outcomes — they never mirror the implementation.
+2. The gate must pass (tests pass) before a task is done — the test runner decides, not self-assessment.
+3. One atomic commit per task. Never batch tasks; never weaken, skip, or delete tests to make them pass.
+4. After the LAST task, a fresh **Verifier always runs automatically** (author ≠ verifier) — spec-anchored outcome check + discrimination sensor. It is never optional and never prompted. See Sub-Agent Delegation.
+
+**Before Execute:** read [implement.md](references/implement.md) completely; if a formal `tasks.md` has more than 3 phases, present the sub-agent offer first (see Sub-Agent Delegation).
+
+## Auto-Sizing: The Core Principle
+
+**The complexity determines the depth, not a fixed pipeline.** Before starting any feature, assess its scope and apply only what's needed:
+
+| Scope       | What                     | Specify                                                 | Design                                          | Tasks                         | Execute                                               |
+| ----------- | ------------------------ | ------------------------------------------------------- | ----------------------------------------------- | ----------------------------- | ----------------------------------------------------- |
+| **Small**   | ≤3 files, one sentence   | One-liner spec (inline)                                 | Skip                                            | Skip                          | Implement + verify inline                             |
+| **Medium**  | Clear feature, <10 tasks | Spec (brief)                                            | Skip — design inline                            | Skip — tasks implicit         | Implement + verify                                    |
+| **Large**   | Multi-component feature  | Full spec + requirement IDs                             | Architecture + components                       | Full breakdown + dependencies | Implement + verify per task                           |
+| **Complex** | Ambiguity, new domain    | Full spec + [discuss gray areas](references/discuss.md) | [Research](references/design.md) + architecture | Breakdown + parallel plan     | Implement + [interactive UAT](references/validate.md) |
+
+**Rules:**
+
+- **Specify and Execute are always required** — you always need to know WHAT and DO it
+- **Design is skipped** when the change is straightforward (no architectural decisions, no new patterns)
+- **Tasks is skipped** when there are ≤3 obvious steps (they become implicit in Execute)
+- **Discuss is triggered within Specify** when the agent detects ambiguous gray areas that need user input, or when the feature has any implicit-requirement dimension present (persistence/state, external calls, auth, payments, concurrency, state transitions)
+- **Interactive UAT is triggered within Execute** only for user-facing features with complex behavior
+
+**Safety valve:** Even when Tasks is skipped, Execute ALWAYS starts by listing atomic steps inline (see [implement.md](references/implement.md)). If that listing reveals >5 steps or complex dependencies, STOP and create a formal `tasks.md` — the Tasks phase was wrongly skipped.
+
+## .specs Structure
+
+```
+.specs/
+├── STATE.md            # Project memory: Decisions log (AD-NNN) + Handoff snapshot
+├── LESSONS.md          # Self-improving lessons playbook (rendered by scripts/lessons.py — do not hand-edit)
+├── lessons.json        # Canonical lessons state (machine-owned)
+└── features/           # Feature specifications
+    └── [feature]/
+        ├── spec.md         # Requirements with traceable IDs
+        ├── context.md      # User decisions for gray areas (only when discuss is triggered)
+        ├── design.md       # Architecture & components (only for Large/Complex)
+        ├── tasks.md        # Atomic tasks with verification (only for Large/Complex)
+        └── validation.md   # Verifier report: PASS/FAIL, per-AC evidence, sensor result, diff range
+```
+
+## Workflow
+
+**New feature:**
+
+1. Specify → (Design) → (Tasks) → Execute (depth auto-sized)
+
+**Resume work:**
+
+Read `.specs/STATE.md` — Handoff section for in-flight state, Decisions section to re-confirm active constraints — then propose the next step.
+
+## Context Loading Strategy
+
+**On-demand load (only what the current task needs):**
+
+- `.specs/STATE.md` — Decisions section (read at Design, re-read on resume); Handoff section (read on resume only)
+- confirmed lessons — load at Specify and Design via `python3 scripts/lessons.py list --status confirmed` ([lessons.md](references/lessons.md)); confirmed only, never candidates
+- spec.md (when working on a specific feature)
+- context.md (when designing or implementing from user decisions)
+- design.md (when implementing from design)
+- tasks.md (when executing tasks)
+
+**Never load simultaneously:**
+
+- Multiple feature specs
+- Multiple architecture docs
+
+**Target:** <40k tokens total context
+**Reserve:** 160k+ tokens for work, reasoning, outputs
+**Monitoring:** Display status when >40k (see [context-limits.md](references/context-limits.md))
+
+## Sub-Agent Delegation
+
+**Trigger:** >3 phases → offer one worker per phase (sequential); ≤3 phases → execute inline.
+
+**Offer-then-confirm** — never auto-spawn. The user must accept before any sub-agent is dispatched.
+
+**One worker per phase:** Each phase worker executes all its tasks in order (implement → gate → atomic commit), then reports a compact summary (tasks done, commit hashes, test counts, deviations). Workers never spawn further sub-agents.
+
+**Verifier (always-on, never prompted):** After the final task is committed, the orchestrator dispatches a fresh Verifier sub-agent automatically — regardless of phase count. Validation never requires a user prompt; it is the closing step of Execute. **Author ≠ verifier**: the Verifier re-derives coverage independently using evidence-or-zero; it does not inherit the author's mental model. The Verifier: (1) performs a **spec-anchored outcome check** — confirms each test's asserted value matches the spec-defined expected outcome, flags spec-precision gaps; (2) runs a **discrimination sensor** — injects behavior-level faults in scratch state, confirms tests kill them, discards mutations, surviving mutants become fix tasks; (3) writes `.specs/features/[feature]/validation.md` (PASS/FAIL, per-AC evidence, sensor result, diff range); (4) returns a compact verdict + ranked gap list to the orchestrator in chat. Gaps become fix tasks; the fix→re-verify loop is bounded to 3 iterations before escalating. (5) **distills lessons** — turns each grounded failure (surviving mutant, spec-precision gap, failed AC, SPEC_DEVIATION) into a reusable project-local lesson via `scripts/lessons.py`; a clean PASS records nothing (see [lessons.md](references/lessons.md)).
+
+**Standalone fallback:** Without sub-agents, run `validate.md` as an independent fresh-eyes pass after the final commit — including the spec-anchored check and discrimination sensor.
+
+Full mechanics (worker payload, compact summary format, failure handling, context sizing, Verifier report format): [sub-agents.md](references/sub-agents.md).
+
+## Commands
+
+**Feature-level (auto-sized):**
+| Trigger Pattern | Reference |
+|----------------|-----------|
+| Specify feature, define requirements | [specify.md](references/specify.md) |
+| Discuss feature, capture context, how should this work | [discuss.md](references/discuss.md) |
+| Design feature, architecture | [design.md](references/design.md) |
+| Break into tasks, create tasks | [tasks.md](references/tasks.md) |
+| Implement task, build, execute | [implement.md](references/implement.md) |
+| Validate, verify, test, UAT, walk me through it | [validate.md](references/validate.md) |
+
+**Memory:**
+| Trigger Pattern | Reference |
+|----------------|-----------|
+| Record decision, this is a project-level decision | [memory.md](references/memory.md) |
+| Pause work, end session, I need to stop | [memory.md](references/memory.md) |
+| Resume work, continue, pick up where we left off | [memory.md](references/memory.md) |
+| Load lessons, what have we learned, apply past lessons | [lessons.md](references/lessons.md) |
+| Record lesson, distill lessons (auto-runs after validation) | [lessons.md](references/lessons.md) |
+
+## Knowledge Verification Chain
+
+When researching, designing, or making any technical decision, follow this chain in strict order. Never skip steps.
+
+```
+Step 1: Codebase → check existing code, conventions, and patterns already in use
+Step 2: Project docs → README, docs/, inline comments, `.specs/STATE.md` (Decisions)
+Step 3: Context7 MCP → resolve library ID, then query for current API/patterns
+Step 4: Web search → official docs, reputable sources, community patterns
+Step 5: Flag as uncertain → "I'm not certain about X — here's my reasoning, but verify"
+```
+
+**Rules:**
+
+- Never skip to Step 5 if Steps 1-4 are available
+- Step 5 is ALWAYS flagged as uncertain — never presented as fact
+- **NEVER assume or fabricate.** If you cannot find an answer, say "I don't know" or "I couldn't find documentation for this". Inventing APIs, patterns, or behaviors causes cascading failures across design → tasks → implementation. Uncertainty is always preferable to fabrication.
+
+## Output Behavior
+
+**Model guidance:** After completing lightweight tasks (validation, feature-level checks), naturally mention once per session that such tasks work well with faster/cheaper models. For heavy tasks (complex design, large features), briefly note the reasoning requirements before starting.
+
+Be conversational, not robotic. Don't interrupt workflow—add as a natural closing note. Skip if user seems experienced or has already acknowledged the tip.
+
+## Code Analysis
+
+Use available tools with graceful degradation. See [code-analysis.md](references/code-analysis.md).

package/skills/spec-driven/references/code-analysis.md

@@ -0,0 +1,98 @@
+# Code Analysis Tools
+
+Use graceful degradation for code search and structural analysis.
+
+## Tool Priority
+
+1. **ast-grep** (`sg`) - Structural pattern-based search
+2. **ripgrep** (`rg`) - Fast context-aware text search
+3. **grep** - Standard text search (always available)
+
+## Detection
+
+Check tool availability before use:
+
+```bash
+# Check for ast-grep
+if command -v sg >/dev/null 2>&1; then
+  # Use ast-grep for structural search
+elif command -v rg >/dev/null 2>&1; then
+  # Fall back to ripgrep
+else
+  # Use standard grep as final fallback
+fi
+```
+
+## Usage Examples
+
+**Finding function definitions:**
+
+```bash
+# ast-grep (best - structural)
+sg -p 'function $NAME($$$) { $$$ }'
+
+# ripgrep (fallback - fast text)
+rg '^function\s+\w+\(' --type-add 'source:*.[extension]' -t source
+
+# grep (last resort - basic)
+grep -r '^function ' --include="*.[extension]"
+```
+
+**Finding imports/requires:**
+
+```bash
+# ast-grep
+sg -p 'import { $$$ } from "$MODULE"'
+
+# ripgrep
+rg '^import .* from' --type-add 'source:*.[extension]' -t source
+
+# grep
+grep -r '^import ' --include="*.[extension]"
+```
+
+**Finding class/component definitions:**
+
+```bash
+# ast-grep
+sg -p 'class $NAME { $$$ }'
+
+# ripgrep
+rg '^(class|export class)\s+\w+' --type-add 'source:*.[extension]' -t source
+
+# grep
+grep -r '^class ' --include="*.[extension]"
+```
+
+## Search Scope
+
+**Best practices:**
+
+- Limit to source file extensions relevant to project
+- Exclude directories: `node_modules`, `vendor`, `dist`, `build`, `.git`
+- Focus on source directories: `src`, `lib`, `app`
+- Use file type filters when available
+
+**Performance tips:**
+
+- Use specific patterns over broad searches
+- Limit directory depth with `--max-depth` (ripgrep/grep)
+- Cache results for repeated queries
+
+## Fallback Notice
+
+If ast-grep unavailable, display once per session:
+
+```
+⚠️ ast-grep not detected. Install for more precise structural code analysis.
+   https://ast-grep.github.io/guide/quick-start.html
+```
+
+## When to Use
+
+- Finding usage patterns across codebase
+- Identifying code structure and organization
+- Locating function/class/component definitions
+- Analyzing import/dependency patterns
+- Refactoring impact analysis
+- Code navigation in unfamiliar codebases

package/skills/spec-driven/references/coding-principles.md

@@ -0,0 +1,56 @@
+# Coding Principles
+
+Behavioral bias, not checklist. Read before every implementation.
+
+---
+
+## Before Coding
+
+- State assumptions explicitly. If uncertain, ask.
+- Multiple interpretations exist? Present all—don't pick silently.
+- Simpler approach exists? Say so. Push back when warranted.
+- Something unclear? Stop. Name what's confusing. Ask.
+- User's approach seems wrong? Disagree honestly. Don't be sycophantic.
+
+---
+
+## During Implementation
+
+### Simplicity
+
+- No features beyond what was asked
+- No abstractions for single-use code
+- No "flexibility" or "configurability" not requested
+- No error handling for impossible scenarios
+- 200 lines that could be 50? Rewrite it.
+
+### Surgical Changes
+
+- Don't "improve" adjacent code, comments, or formatting
+- Don't refactor things that aren't broken
+- Match existing style, even if you'd do differently
+- Unrelated dead code noticed? Mention it—don't delete it
+- Remove ONLY imports/variables/functions YOUR changes orphaned
+- Don't remove pre-existing dead code unless asked
+
+### Test Integrity
+
+- NEVER weaken an existing test assertion to make it pass
+- NEVER delete a test to reduce failure count
+- NEVER use the test framework's skip/disable/pending mechanism to bypass a failing test
+- NEVER modify a task's tests afterward to make the implementation pass
+- If a test is genuinely wrong, STOP and confirm with the user before changing it
+- Tests are the spec — implementation conforms to tests, not the other way around
+
+### Goal-Driven
+
+- Transform vague tasks into verifiable goals
+- Multi-step work? State brief plan with verify checkpoints
+- Every changed line must trace directly to user's request
+
+---
+
+## After Each Change
+
+Ask: "Would senior engineer call this overcomplicated?"
+If yes → simplify before proceeding.