diff --git a/.agents/skills/sdd/SKILL.md b/.agents/skills/sdd/SKILL.md
new file mode 100644
index 0000000..1f3ebe9
--- /dev/null
+++ b/.agents/skills/sdd/SKILL.md
@@ -0,0 +1,293 @@
+---
+name: sdd
+version: 1.5.0
+description: >
+  Spec-driven development pipeline with 6 phases: Explore, Requirements,
+  Design, Task Plan, Implementation, Review. Enforces human approval gates
+  between phases. Also provides a standalone documentation workflow for
+  generating or updating project docs without starting a feature pipeline.
+  Use when user wants structured feature development, spec-first approach,
+  or says "I want to add feature X", "new feature", "implement", "build",
+  "generate documentation", "update docs", "actualize the documentation".
+  Keywords: spec, requirements, design document, TDD plan, task plan,
+  implementation, code review, pipeline, approval gates, WHEN/SHALL,
+  generate docs, update docs, documentation queue.
+---
+
+# Spec-Driven Development
+
+You are operating in **spec-driven development mode**.
+This project uses a 6-phase pipeline with human approval gates between each phase.
+
+## Pipeline
+
+```
+Explore → [APPROVE] → Requirements → [APPROVE] → Design → [APPROVE] → Task Plan → [APPROVE] → Implementation → [APPROVE] → Review → [APPROVE] → Done
+```
+
+Each phase has a dedicated prompt template. Read the template for the **current** phase before generating any output.
+
+## Quick Reference
+
+### Core Commands
+
+| Action | Command |
+|--------|---------|
+| Check state | `sh ./scripts/pipeline.sh status` |
+| Start feature | `sh ./scripts/pipeline.sh init <name>` |
+| Register output | `sh ./scripts/pipeline.sh artifact [path]` |
+| Advance phase | `sh ./scripts/pipeline.sh approve` (only after user says "approve") |
+| Mark task done | `sh ./scripts/pipeline.sh task T-N` (implementation phase only) |
+| Multi-feature | Add `--feature <name>` before any command |
+
+### Decision Points
+
+At these moments, **ask the user** before running a command:
+
+#### Starting a feature (`init`)
+
+If config has `auto_branch: true` or `auto_worktree: true` → use the config default silently.
+Otherwise, ASK: *"Create a separate branch for this feature? (branch / worktree / no)"*
+
+| User answer | Command |
+|------------|--------|
+| "branch" | `pipeline.sh init --branch <name>` |
+| "worktree" | `pipeline.sh init --worktree <name>` |
+| "no" / "нет" | `pipeline.sh init <name>` |
+
+#### Finishing a feature (`finish`)
+
+After pipeline reaches `done` and docs maintenance is handled, ASK: *"What to do with the branch? (merge / PR / keep / discard)"*
+
+| User answer | Command |
+|------------|--------|
+| "merge" | `pipeline.sh finish merge` |
+| "PR" / "pull request" | `pipeline.sh finish pr` |
+| "keep" / "оставить" | `pipeline.sh finish keep` |
+| "discard" / "удалить" | `pipeline.sh finish discard --confirm` |
+| On default branch / no git | `pipeline.sh finish keep` (auto, no question) |
+
+#### Documentation updates
+
+When `docs-check` reports issues, ASK the user (already described in Pre-flight Checklist step 3).
+
+| User answer | Command |
+|------------|--------|
+| "generate docs" | `pipeline.sh docs-init --all` |
+| "update docs" | `pipeline.sh docs-init --update` |
+| "skip" / "пропустить" | (no command) |
+
+**Hard rules:** check status first · never skip phases · never auto-approve · save artifacts to `.spec/features/<feature>/` · max 3 revisions then ask user
+
+**Config:** `.spec/config.yaml` → `context`, `rules.<phase>`, `test_skill`, `test_reference`, `docs_dir`, `auto_branch`, `branch_prefix`, `auto_worktree`, `worktree_dir`
+
+**Phase flow:** read template → generate artifact → save → `artifact` → present → wait for "approve" → `approve`
+
+## Phases
+
+| # | Phase          | Template                        | Produces                        |
+|---|----------------|---------------------------------|---------------------------------|
+| 1 | Explore        | `./templates/explore.md`        | Exploration & research document |
+| 2 | Requirements   | `./templates/requirements.md`   | Formal requirements document    |
+| 3 | Design         | `./templates/design.md`         | Architecture & design document  |
+| 4 | Task Plan      | `./templates/task-plan.md`      | TDD implementation plan         |
+| 5 | Implementation | `./templates/implementation.md` | Implementation report           |
+| 6 | Review         | `./templates/review.md`         | Code review document            |
+
+## State Machine
+
+The pipeline state is managed via a shell script:
+
+```sh
+# Check current phase and progress
+sh ./scripts/pipeline.sh status
+
+# Start a new feature pipeline (see Decision Points for branching options)
+sh ./scripts/pipeline.sh init <feature-name>
+
+# Register the artifact you generated for the current phase
+sh ./scripts/pipeline.sh artifact [path]
+
+# Advance to the next phase (only after user says "approve")
+sh ./scripts/pipeline.sh approve
+
+# View revision history
+sh ./scripts/pipeline.sh revisions [phase]
+
+# View all features and their status
+sh ./scripts/pipeline.sh history
+
+# Mark an implementation task as completed (enables resume)
+sh ./scripts/pipeline.sh task <T-N>
+
+# Validate config file
+sh ./scripts/pipeline.sh config-check
+
+# Inject a pre-written artifact and skip to that phase
+sh ./scripts/pipeline.sh inject <phase> <path>
+
+# Abandon an active pipeline
+sh ./scripts/pipeline.sh abandon [feature]
+```
+
+For standalone documentation workflow commands (`docs-init`, `docs-next`, `docs-done`, `docs-status`, `docs-reset`), see `./templates/docs-maintenance.md`.
+
+For all available flags and options: `sh ./scripts/pipeline.sh help`
+
+### Parallel Pipelines
+
+When multiple features are active simultaneously, add `--feature <name>` before the command:
+
+```sh
+sh ./scripts/pipeline.sh --feature auth-flow status
+sh ./scripts/pipeline.sh --feature payment approve
+```
+
+Without the flag, the pipeline auto-detects the active feature. If more than one is active, it will error and prompt you to use `--feature`.
+
+## Project Configuration
+
+If the file `.spec/config.yaml` exists in the project root, read it before starting any phase. See `.spec/config.yaml.example` for a template with all supported keys.
+
+> **Format limitation:** the pipeline parser reads flat `key: value` pairs only. Nested YAML structures, multi-line values, and quoted strings are not supported.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `context` | string | — | Project-wide background for ALL phases |
+| `rules.<phase>` | string | — | Phase-specific rules (supplement template) |
+| `rules.docs` | string | — | Rules for documentation generation |
+| `test_skill` | string | — | Skill name for delegated test generation |
+| `test_reference` | string | — | Glob/paths to representative test files |
+| `docs_dir` | string | `.spec` | Directory for project documentation |
+| `doc_freshness_days` | integer | `30` | Days before a generated doc is stale |
+| `auto_branch` | boolean | `false` | Auto-create git branch on `init` |
+| `branch_prefix` | string | `feature/` | Prefix for auto-created branches |
+| `auto_worktree` | boolean | `false` | Auto-create git worktree on `init` (mutually exclusive with `auto_branch`) |
+| `worktree_dir` | string | `.worktrees` | Directory for worktrees (add to `.gitignore`) |
+
+Phase-specific rule keys: `rules.explore`, `rules.requirements`, `rules.design`, `rules.task-plan`, `rules.implementation`, `rules.review`, `rules.docs`.
+
+Injection order: **context → phase rules → template instructions.**
+
+If the file does not exist, skip this step.
+
+## Standalone Documentation Workflow
+
+If the user requests documentation generation or update **without referring to a feature** (e.g. *"generate docs"*, *"update documentation"*, *"actualize the docs"*, *"refresh AUTH.md"*) — **do NOT run `pipeline.sh init`**. This is a standalone workflow with its own state machine.
+
+1. Read `./templates/docs-maintenance.md` § Standalone Documentation Workflow.
+2. Run `pipeline.sh docs-init [--all|--update|<template>...]` based on user intent.
+3. Choose execution strategy (subagent recommended when available, sequential as fallback).
+4. Drive the queue: `docs-next` → generate → `docs-done` (sequential), or dispatch up to 3 subagents in parallel (subagent mode).
+
+The standalone workflow is independent from feature pipelines — it does not create `.spec/features/<feature>/`, does not require approvals, and runs purely from `.spec/.docs-queue.kv` state.
+
+## Pre-flight Checklist
+
+Before starting any pipeline work, follow these steps in order:
+
+1. **Check pipeline state**: run `pipeline.sh status`.
+   - If exactly one active pipeline exists → resume from the current phase. Do NOT run `init` again.
+   - If no active pipeline → proceed to step 2.
+   - If multiple active pipelines → ask the user which feature to work on, then use `--feature <name>` with all subsequent commands.
+2. **Read project config**: check if `.spec/config.yaml` exists.
+   - If yes → read it, apply `context` to all phases, note `rules.*` for each phase.
+   - If no → proceed without config (defaults apply).
+3. **Check documentation** (MUST — do not skip this step): run `pipeline.sh docs-check`.
+   - **Docs directory missing** → suggest: *"Project documentation (<docs_dir>/) not found. I can generate it to better understand your codebase. Say 'generate docs' or 'skip'."* **Wait for the user's response** before proceeding. This is a soft gate — the pipeline works without documentation, but the user must explicitly acknowledge (say 'generate docs' or 'skip').
+   - **Docs exist, stale files found** → suggest: *"Some docs are outdated (<file>: <N> days old). Regenerate before starting? Say 'update docs' or 'skip'."* **Wait for the user's response.** If user agrees, read `./templates/docs-maintenance.md` for the Stale doc regeneration workflow.
+   - **Docs exist, all fresh** → use as supplementary context for ALL phases. Read `<docs_dir>/README.md` for the documentation map.
+   - If user says **"generate docs"** or **"update docs"**: read `./templates/docs-maintenance.md`, follow the workflow. Generated documentation files go to `<docs_dir>/` (default: `.spec/`), **NOT** to `.spec/features/<feature>/`.
+   - **Do NOT proceed to step 4 until the user responds** to the documentation suggestion.
+4. **Start pipeline**: run `pipeline.sh init <feature-name>`.
+
+For documentation generation, staleness checks, and regeneration workflows, read `./templates/docs-maintenance.md`.
+
+## When to Use This Pipeline
+
+**Use the pipeline for:**
+- New features ("add user authentication", "implement search")
+- Significant changes to existing features (new behavior, API changes, schema migrations)
+- Bug fixes that require investigation and design (root cause unknown, multiple components affected)
+
+**Do NOT use the pipeline for:**
+- Trivial changes: typo fixes, config tweaks, single-field additions, comment updates
+- Dependency updates with no code changes
+- Pure refactors with no behavioral change (unless they are large and risky)
+
+For trivial changes, just make the change directly — no pipeline needed. The skill is designed for work that **benefits from structured thinking before coding**.
+
+### Fast-track mode
+
+For **bug fixes with a known reproduction** or other small, well-understood changes:
+
+- All 6 phases still apply — do not skip phases.
+- Each phase produces a **minimal artifact**: 1-paragraph exploration, 1–2 requirements, focused design (CPs only for the bug scenario), 4–5 tasks (RED→GREEN→CODE→VERIFY→GATE), brief implementation report, short review.
+- Each template contains a "Fast-track mode" section with phase-specific minimums. Follow those rules when fast-track applies.
+
+**When to activate:** The agent activates fast-track when the user describes a bug with a known reproduction step, or a small, scoped change where investigation is unnecessary. At the start, announce: *"Using fast-track mode — all 6 phases, minimal artifacts."* If the user says "full pipeline", switch to the standard (non-abbreviated) flow.
+
+**Scope:** This pipeline is designed for a **single project or monorepo**. It is not intended for features that span multiple independent repositories. Within a monorepo, use one `.spec/` directory at the repository root.
+
+## Rules
+
+1. **MUST check status first.** Run `pipeline.sh status` before doing anything. Never generate phase output without checking status. If multiple active pipelines exist, use `--feature <name>` with all commands.
+2. **Never skip phases.** Follow the order: explore → requirements → design → task-plan → implementation → review.
+3. **Never auto-approve.** Wait for the user to explicitly say "approve" or equivalent.
+4. **Read the template.** Before generating output for a phase, read the corresponding template file.
+5. **Save artifacts.** Save phase artifacts (explore, requirements, design, task-plan, implementation, review) to `.spec/features/<feature>/` and register them with `pipeline.sh artifact`. **Project documentation** (README.md, ARCHITECTURE.md, DOMAIN.md, etc.) goes to `<docs_dir>/` (default: `.spec/`), NOT to `.spec/features/<feature>/` — these are separate directories with separate purposes.
+6. **Each phase produces one artifact** that becomes input for the next phase.
+7. **Artifacts are cumulative.** Each phase reads all prior artifacts.
+8. **Revision limit.** If the user rejects the same artifact 3 times in a row, stop generating and ask: "We've gone through 3 revisions — could you clarify what's missing or what direction you'd prefer?" Do not continue revising without explicit guidance.
+9. **Surface uncertainty.** If you are unsure about intent, scope, or technical approach — say so explicitly. State the assumption you would make and ask the user to confirm or correct it. Never silently assume.
+10. **Write in the user's language.** Detect the user's language from their first message and use it for ALL pipeline artifacts and conversational replies. What stays in English:
+    - Formal grammar keywords: `WHEN`, `SHALL`, `the system`
+    - Requirement IDs: `REQ-X.Y`
+    - Task IDs: `T-N`
+    - Instruction keywords: `CRITICAL`, `IMPORTANT`, `NOTE`, `DO NOT`, `GOAL`
+    - Correctness Property format: `Property N`, `Category`, `For all`, `Validates`
+    - Code identifiers, file paths, shell commands, Mermaid node labels
+    - Documentation in `<docs_dir>/` (`.spec/`) — always English (see `templates/docs/README.md`)
+
+    Everything else — prose, section headers, descriptions, interview questions, explanations — is written in the user's language.
+
+## Error Recovery
+
+- **Revising an artifact:** Overwrite the file, re-register with `pipeline.sh artifact`, and present the updated version to the user. The previous version is automatically saved as a revision in the feature’s `revisions/` directory. Use `pipeline.sh revisions` to view past revisions.
+
+
+## Documentation Maintenance
+
+After the pipeline reaches `phase=done`, read `./templates/docs-maintenance.md` § Documentation Maintenance to check if project documentation needs updating.
+
+## Branch Finishing
+
+After documentation maintenance is complete (or skipped), follow the **Finishing a feature** Decision Point in Quick Reference above.
+
+If on the default branch (main/master) or git is unavailable, run `pipeline.sh finish keep` automatically — no question needed.
+
+This is a soft suggestion, not a blocker. If the user ignores it, the pipeline is still complete.
+
+## Quick Start (for the agent)
+
+When the user says something like "I want to add feature X":
+
+1. Follow the **Pre-flight Checklist** (status → config → docs-check → init)
+2. Read `./templates/explore.md` — investigate the problem space (use `.spec/` docs as context if available)
+3. Generate the exploration document → save to `.spec/features/<feature>/explore.md`
+4. Run `pipeline.sh artifact`
+5. Present to user → wait for "approve"
+6. Run `pipeline.sh approve` → phase advances to requirements
+7. Read `./templates/requirements.md` → follow its interview process
+8. Generate the requirements document → save, register artifact, present, wait for approve
+9. Repeat for design phase
+10. Read `./templates/task-plan.md` → generate TDD implementation plan (no code yet)
+11. Save, register artifact, present, wait for approve
+12. Read `./templates/implementation.md` → execute the task plan (write tests, write code, mark tasks done)
+13. Save implementation report, register artifact, present, wait for approve
+14. Read `./templates/review.md` → review the written code against all prior artifacts
+15. Present review document with findings and verdict → wait for user instructions
+16. If user asks to fix findings → fix → generate new review → present again → wait for approve
+17. After review is approved → `pipeline.sh approve` → pipeline complete
+18. Check if documentation needs updating (see Documentation Maintenance)
+19. Check if the feature branch needs finalizing (see Branch Finishing) → present options → `pipeline.sh finish`
diff --git a/.agents/skills/sdd/scripts/pipeline.sh b/.agents/skills/sdd/scripts/pipeline.sh
new file mode 100755
index 0000000..3cecf09
--- /dev/null
+++ b/.agents/skills/sdd/scripts/pipeline.sh
@@ -0,0 +1,1723 @@
+#!/usr/bin/env sh
+# Spec-Driven Dev Pipeline — state machine (POSIX sh, zero dependencies)
+# Usage: sh pipeline.sh [--feature <name>] <command> [args]
+#
+# Shell compatibility: requires sh with `local` support (bash, dash, ash, zsh).
+#
+# Global flags:
+#   --feature <name>      Specify which feature to operate on (required when
+#                         multiple pipelines are active simultaneously)
+#
+# Commands:
+#   init [--branch|--no-branch] <feature-name>
+#                         Start a new pipeline for a feature
+#                         --branch: create git branch <prefix><name> (prefix from config, default: feature/)
+#                         --no-branch: skip branch creation even if auto_branch is set in config
+#   status                Show current phase, feature, and artifacts
+#   approve               Advance to next phase (requires artifact)
+#   artifact [path]       Register artifact for current phase
+#   history               Show all features and their status
+#   revisions [phase]     Show revision history for current or specified phase
+#   docs-check            Check project documentation status
+#   task <T-N>            Mark implementation task as completed (resume tracking)
+#   version               Show version
+#   help                  Show this help message
+
+set -e
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+FEATURES_DIR="$PROJECT_ROOT/.spec/features"
+CONFIG_FILE="$PROJECT_ROOT/.spec/config.yaml"
+
+# --- helpers ---
+
+VERSION="1.5.0"
+EXPLICIT_FEATURE=""
+
+die() { echo "ERROR: $*" >&2; exit 1; }
+info() { echo "→ $*"; }
+warn() { echo "⚠ $*" >&2; }
+
+iso_now() {
+  date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+iso_now_compact() {
+  date -u +"%Y-%m-%dT%H-%M-%SZ" 2>/dev/null || date +"%Y-%m-%dT%H-%M-%SZ"
+}
+
+# Escape a string for safe embedding in JSON values (RFC 8259)
+json_escape() {
+  printf '%s' "$1" | awk '
+    BEGIN { ORS="" }
+    {
+      gsub(/\\/, "\\\\")
+      gsub(/"/, "\\\"")
+      gsub(/\t/, "\\t")
+      gsub(/\r/, "\\r")
+      if (NR > 1) printf "\\n"
+      printf "%s", $0
+    }'
+}
+
+# Read a value from .spec/config.yaml (simple grep-based, no YAML parser)
+# Usage: read_config <key> [default]
+# Returns the value or default (empty string if no default)
+read_config() {
+  local key="$1" default="${2:-}"
+  if [ -f "$CONFIG_FILE" ]; then
+    local val
+    val="$(grep "^${key}:" "$CONFIG_FILE" 2>/dev/null | head -1 | sed "s/^${key}:[[:space:]]*//" | sed 's/[[:space:]]*$//')"
+    if [ -n "$val" ]; then
+      printf '%s' "$val"
+      return
+    fi
+  fi
+  printf '%s' "$default"
+}
+
+# --- per-feature state ---
+
+# Current feature paths (set by set_feature_context / resolve_feature)
+FEATURE_DIR=""
+STATE_FILE=""
+KV_FILE=""
+REVISIONS_DIR=""
+APPROVED_DIR=""
+
+set_feature_context() {
+  # set_feature_context <feature-name> — sets global paths for the feature
+  FEATURE_DIR="$FEATURES_DIR/$1"
+  KV_FILE="$FEATURE_DIR/pipeline.kv"
+  STATE_FILE="$FEATURE_DIR/pipeline.json"
+  REVISIONS_DIR="$FEATURE_DIR/revisions"
+  APPROVED_DIR="$FEATURE_DIR/approved"
+}
+
+ensure_feature_dir() {
+  # ensure_feature_dir <feature-name> — creates feature directory structure
+  local fdir="$FEATURES_DIR/$1"
+  mkdir -p "$fdir" "$fdir/revisions" "$fdir/approved"
+}
+
+read_field() {
+  [ -f "$KV_FILE" ] || return 1
+  local _line
+  _line="$(grep "^$1=" "$KV_FILE" 2>/dev/null | head -1)" || return 1
+  [ -n "$_line" ] || return 1
+  printf '%s' "$_line" | cut -d'=' -f2-
+}
+
+validate_kv() {
+  # Verify required fields exist in KV store; die with diagnostic on failure
+  [ -f "$KV_FILE" ] || die "Pipeline state file missing: $KV_FILE"
+  local missing=""
+  for field in feature phase created_at; do
+    grep -q "^${field}=" "$KV_FILE" 2>/dev/null || missing="$missing $field"
+  done
+  if [ -n "$missing" ]; then
+    die "Corrupted pipeline state ($KV_FILE): missing fields:$missing. Fix the file manually or remove and re-init."
+  fi
+  # Verify every line matches key=value format (key: lowercase + digits + underscore)
+  local line_num=0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line_num=$((line_num + 1))
+    case "$line" in
+      "") continue ;;  # skip blank lines
+      [a-z_]*=*) ;;    # valid key=value
+      *) die "Corrupted pipeline state ($KV_FILE): invalid line $line_num: $line" ;;
+    esac
+  done < "$KV_FILE"
+}
+
+# Escape a value for safe use in sed replacement string
+kv_escape_sed() {
+  printf '%s' "$1" | sed -e 's/[&\\/|]/\\&/g'
+}
+
+# Validate that a value is safe for the KV store (no =, |, or newlines)
+kv_validate_value() {
+  case "$1" in
+    *'='*) die "KV value must not contain '=': $1" ;;
+    *'|'*) die "KV value must not contain '|': $1" ;;
+  esac
+  # Check for newlines by comparing line count (portable across POSIX shells)
+  local line_count
+  line_count="$(printf '%s' "$1" | wc -l)"
+  if [ "$line_count" -ne 0 ]; then
+    die "KV value must not contain newlines: $1"
+  fi
+}
+
+# Validate artifact path: reject directory traversal and control characters
+validate_artifact_path() {
+  case "$1" in
+    */../*|*/..) die "Artifact path must not contain '..' traversal" ;;
+    ../*|..)     die "Artifact path must not contain '..' traversal" ;;
+  esac
+  if printf '%s' "$1" | grep -q '[[:cntrl:]]' 2>/dev/null; then
+    die "Artifact path must not contain control characters"
+  fi
+}
+
+write_field() {
+  kv_validate_value "$2"
+  if [ -f "$KV_FILE" ] && grep -q "^$1=" "$KV_FILE" 2>/dev/null; then
+    local tmp="$KV_FILE.tmp"
+    local escaped
+    escaped="$(kv_escape_sed "$2")"
+    sed "s|^$1=.*|$1=$escaped|" "$KV_FILE" > "$tmp" && mv "$tmp" "$KV_FILE"
+  else
+    echo "$1=$2" >> "$KV_FILE"
+  fi
+}
+
+detect_active_feature() {
+  # Scan all features, return the one with phase != done
+  [ -d "$FEATURES_DIR" ] || return 0
+  local active=""
+  local count=0
+  for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+    [ -f "$kv" ] || continue
+    local phase
+    phase="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+    if [ -n "$phase" ] && [ "$phase" != "done" ]; then
+      local fname
+      fname="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+      active="$fname"
+      count=$((count + 1))
+    fi
+  done
+  if [ "$count" -gt 1 ]; then
+    warn "Multiple active pipelines found:"
+    for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+      [ -f "$kv" ] || continue
+      local phase fname
+      phase="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+      fname="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+      if [ -n "$phase" ] && [ "$phase" != "done" ]; then
+        echo "  - $fname (phase: $phase)" >&2
+      fi
+    done
+    return 1
+  fi
+  [ -n "$active" ] && echo "$active"
+}
+
+resolve_feature() {
+  if [ -n "$EXPLICIT_FEATURE" ]; then
+    # Validate that the explicitly specified feature exists
+    if [ ! -f "$FEATURES_DIR/$EXPLICIT_FEATURE/pipeline.kv" ]; then
+      die "Feature '$EXPLICIT_FEATURE' not found. Run 'pipeline.sh history' to list features."
+    fi
+    set_feature_context "$EXPLICIT_FEATURE"
+    validate_kv
+    return 0
+  fi
+  local feat
+  feat="$(detect_active_feature)" || { warn "Hint: use --feature <name> to select one."; return 1; }
+  if [ -z "$feat" ]; then
+    return 1
+  fi
+  set_feature_context "$feat"
+  validate_kv
+  return 0
+}
+
+next_phase() {
+  case "$1" in
+    explore)        echo "requirements" ;;
+    requirements)   echo "design" ;;
+    design)         echo "task-plan" ;;
+    task-plan)      echo "implementation" ;;
+    implementation) echo "review" ;;
+    review)         echo "done" ;;
+    done)           echo "" ;;
+    *)              echo "" ;;
+  esac
+}
+
+phase_number() {
+  case "$1" in
+    explore)        echo "1" ;;
+    requirements)   echo "2" ;;
+    design)         echo "3" ;;
+    task-plan)      echo "4" ;;
+    implementation) echo "5" ;;
+    review)         echo "6" ;;
+    done)           echo "✓" ;;
+    *)              echo "?" ;;
+  esac
+}
+
+# Numeric ordering for comparisons (phase_number is for display)
+phase_order() {
+  case "$1" in
+    explore)        echo 1 ;;
+    requirements)   echo 2 ;;
+    design)         echo 3 ;;
+    task-plan)      echo 4 ;;
+    implementation) echo 5 ;;
+    review)         echo 6 ;;
+    done)           echo 7 ;;
+    *)              echo 0 ;;
+  esac
+}
+
+# Rebuild the JSON file from KV store (for agents to read)
+# Uses atomic write (tmp + mv) to prevent corruption on interruption
+rebuild_json() {
+  validate_kv
+  local feature phase created artifact
+  feature="$(json_escape "$(read_field feature)")"
+  phase="$(read_field phase)"
+  created="$(read_field created_at)"
+  artifact="$(read_field current_artifact)"
+  local history_count
+  history_count="$(read_field history_count)"
+  [ -z "$history_count" ] && history_count=0
+
+  local tmp_file="$STATE_FILE.tmp"
+  {
+    printf '{\n'
+    printf '  "feature": "%s",\n' "$feature"
+    printf '  "phase": "%s",\n' "$phase"
+    printf '  "created_at": "%s",\n' "$created"
+    if [ -n "$artifact" ]; then
+      printf '  "current_artifact": "%s",\n' "$(json_escape "$artifact")"
+    else
+      printf '  "current_artifact": null,\n'
+    fi
+    printf '  "history": [\n'
+
+    local i=0
+    while [ "$i" -lt "$history_count" ]; do
+      local h_phase h_artifact h_approved
+      h_phase="$(read_field "history_${i}_phase")"
+      h_artifact="$(json_escape "$(read_field "history_${i}_artifact")")"
+      h_approved="$(read_field "history_${i}_approved_at")"
+      [ "$i" -gt 0 ] && printf ',\n'
+      printf '    {"phase": "%s", "artifact": "%s", "approved_at": "%s"}' \
+        "$h_phase" "$h_artifact" "$h_approved"
+      i=$((i + 1))
+    done
+
+    printf '\n  ],\n'
+
+    # Include review_base_commit if set
+    local rbc
+    rbc="$(read_field review_base_commit 2>/dev/null || echo "")"
+    if [ -n "$rbc" ]; then
+      printf '  "review_base_commit": "%s",\n' "$(json_escape "$rbc")"
+    else
+      printf '  "review_base_commit": null,\n'
+    fi
+
+    # Include branch if set
+    local br
+    br="$(read_field branch 2>/dev/null || echo "")"
+    if [ -n "$br" ]; then
+      printf '  "branch": "%s",\n' "$(json_escape "$br")"
+    else
+      printf '  "branch": null,\n'
+    fi
+
+    # Include worktree if set
+    local wt
+    wt="$(read_field worktree 2>/dev/null || echo "")"
+    if [ -n "$wt" ]; then
+      printf '  "worktree": "%s",\n' "$(json_escape "$wt")"
+    else
+      printf '  "worktree": null,\n'
+    fi
+
+    # Include last_completed_task if set
+    local lct
+    lct="$(read_field last_completed_task 2>/dev/null || echo "")"
+    if [ -n "$lct" ]; then
+      printf '  "last_completed_task": "%s",\n' "$(json_escape "$lct")"
+    else
+      printf '  "last_completed_task": null,\n'
+    fi
+
+    # Include finish fields if set
+    local fa ft fb
+    fa="$(read_field finish_action 2>/dev/null || echo "")"
+    ft="$(read_field finished_at 2>/dev/null || echo "")"
+    fb="$(read_field finish_base 2>/dev/null || echo "")"
+    if [ -n "$fa" ]; then
+      printf '  "finish_action": "%s",\n' "$(json_escape "$fa")"
+      printf '  "finished_at": "%s",\n' "$(json_escape "$ft")"
+      if [ -n "$fb" ]; then
+        printf '  "finish_base": "%s"\n' "$(json_escape "$fb")"
+      else
+        printf '  "finish_base": null\n'
+      fi
+    else
+      printf '  "finish_action": null,\n'
+      printf '  "finished_at": null,\n'
+      printf '  "finish_base": null\n'
+    fi
+
+    printf '}\n'
+  } > "$tmp_file"
+  mv -f "$tmp_file" "$STATE_FILE"
+}
+
+# --- commands ---
+
+cmd_init() {
+  # Parse init-specific flags
+  local do_branch=""
+  local do_worktree=""
+  local feature=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --branch)      do_branch="yes"; shift ;;
+      --worktree)    do_worktree="yes"; shift ;;
+      --no-branch)   do_branch="no"; do_worktree="no"; shift ;;
+      -*)            die "Unknown flag for init: $1" ;;
+      *)
+        [ -n "$feature" ] && die "Unexpected argument: $1"
+        feature="$1"; shift
+        ;;
+    esac
+  done
+
+  [ -z "$feature" ] && die "Usage: pipeline.sh init [--branch|--worktree|--no-branch] <feature-name>"
+
+  # Mutual exclusion
+  if [ "$do_branch" = "yes" ] && [ "$do_worktree" = "yes" ]; then
+    die "--branch and --worktree are mutually exclusive."
+  fi
+
+  # Validate feature name (kebab-case)
+  case "$feature" in
+    *[!a-z0-9-]*) die "Feature name must be kebab-case (e.g. grpc-streaming-support)" ;;
+    -*|*-)        die "Feature name must be kebab-case (e.g. grpc-streaming-support)" ;;
+    *--*)         die "Feature name must be kebab-case (e.g. grpc-streaming-support)" ;;
+    [!a-z]*)      die "Feature name must be kebab-case (e.g. grpc-streaming-support)" ;;
+  esac
+
+  if [ ${#feature} -gt 64 ]; then
+    die "Feature name too long (max 64 chars): $feature"
+  fi
+
+  # Resolve branch/worktree creation: flag > config > default (neither)
+  if [ -z "$do_branch" ] && [ -z "$do_worktree" ]; then
+    local auto_branch auto_worktree
+    auto_worktree="$(read_config auto_worktree "false")"
+    case "$auto_worktree" in
+      true|yes|1) do_worktree="yes" ;;
+    esac
+    if [ "$do_worktree" != "yes" ]; then
+      auto_branch="$(read_config auto_branch "false")"
+      case "$auto_branch" in
+        true|yes|1) do_branch="yes" ;;
+        *)          do_branch="no" ;;
+      esac
+    fi
+  fi
+
+  local branch_name=""
+  local worktree_path=""
+
+  if [ "$do_worktree" = "yes" ]; then
+    # --- Worktree mode ---
+    if ! command -v git >/dev/null 2>&1; then
+      die "Git not found. Cannot create worktree."
+    fi
+    if ! git rev-parse --git-dir >/dev/null 2>&1; then
+      die "Not a git repository. Cannot create worktree."
+    fi
+
+    local prefix wt_dir
+    prefix="$(read_config branch_prefix "feature/")"
+    wt_dir="$(read_config worktree_dir ".worktrees")"
+    branch_name="${prefix}${feature}"
+    worktree_path="${wt_dir}/${feature}"
+
+    # Check if branch already exists
+    if git rev-parse --verify "$branch_name" >/dev/null 2>&1; then
+      die "Branch '$branch_name' already exists."
+    fi
+
+    # Warn if worktree_dir is not in .gitignore
+    if [ -f ".gitignore" ]; then
+      if ! grep -qx "$wt_dir" .gitignore 2>/dev/null && ! grep -qx "$wt_dir/" .gitignore 2>/dev/null; then
+        warn "Worktree directory '$wt_dir' is not in .gitignore. Consider adding it."
+      fi
+    else
+      warn "No .gitignore found. Consider adding '$wt_dir' to .gitignore."
+    fi
+
+    git worktree add "$worktree_path" -b "$branch_name" || die "Failed to create worktree at '$worktree_path'."
+    info "Created worktree: $worktree_path (branch: $branch_name)"
+
+  elif [ "$do_branch" = "yes" ]; then
+    # Verify git is available
+    if ! command -v git >/dev/null 2>&1; then
+      die "Git not found. Cannot create branch."
+    fi
+    if ! git rev-parse --git-dir >/dev/null 2>&1; then
+      die "Not a git repository. Cannot create branch."
+    fi
+
+    local prefix
+    prefix="$(read_config branch_prefix "feature/")"
+    branch_name="${prefix}${feature}"
+
+    # Check if branch already exists
+    if git rev-parse --verify "$branch_name" >/dev/null 2>&1; then
+      die "Branch '$branch_name' already exists."
+    fi
+
+    # Warn about dirty working tree
+    if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+      warn "Working tree has uncommitted changes."
+    fi
+
+    git checkout -b "$branch_name" || die "Failed to create branch '$branch_name'."
+    info "Created branch: $branch_name"
+  fi
+
+  local fdir="$FEATURES_DIR/$feature"
+
+  # Check if feature already exists
+  if [ -f "$fdir/pipeline.kv" ]; then
+    local existing_phase
+    existing_phase="$(grep "^phase=" "$fdir/pipeline.kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+    if [ "$existing_phase" = "done" ]; then
+      die "Feature '$feature' already completed. Choose a different name."
+    else
+      warn "Active pipeline for '$feature' exists (phase: $existing_phase)"
+      die "Complete or choose a different feature name."
+    fi
+  fi
+
+  ensure_feature_dir "$feature"
+  set_feature_context "$feature"
+
+  # Initialize KV store
+  {
+    echo "feature=$feature"
+    echo "phase=explore"
+    echo "created_at=$(iso_now)"
+    echo "current_artifact="
+    echo "history_count=0"
+    if [ -n "$branch_name" ]; then
+      echo "branch=$branch_name"
+    fi
+    if [ -n "$worktree_path" ]; then
+      echo "worktree=$worktree_path"
+    fi
+  } > "$KV_FILE"
+
+  rebuild_json
+  info "Pipeline initialized for '$feature'"
+  if [ -n "$worktree_path" ]; then
+    info "Worktree: $worktree_path (branch: $branch_name)"
+  elif [ -n "$branch_name" ]; then
+    info "Branch: $branch_name"
+  fi
+  info "Phase: [1/6] explore"
+  info "Artifacts: .spec/features/$feature/"
+  info "Read template: ./templates/explore.md"
+}
+
+cmd_status() {
+  if ! resolve_feature; then
+    info "No active pipeline."
+    # Show completed features if any
+    if [ -d "$FEATURES_DIR" ]; then
+      local has_completed=0
+      for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+        [ -f "$kv" ] || continue
+        local phase
+        phase="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        if [ "$phase" = "done" ]; then
+          if [ "$has_completed" -eq 0 ]; then
+            echo ""
+            echo "Completed features:"
+            has_completed=1
+          fi
+          local fname
+          fname="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+          printf "  ✓ %s\n" "$fname"
+        fi
+      done
+    fi
+    echo ""
+    info "Run: pipeline.sh init <feature-name>"
+    return 0
+  fi
+
+  local feature phase artifact history_count
+  feature="$(read_field feature)"
+  phase="$(read_field phase)"
+  artifact="$(read_field current_artifact)"
+  history_count="$(read_field history_count)"
+  [ -z "$history_count" ] && history_count=0
+
+  echo ""
+  echo "┌─────────────────────────────────────────────┐"
+  printf "│ Feature: %-35s│\n" "$feature"
+  printf "│ Phase:   [%s/6] %-30s│\n" "$(phase_number "$phase")" "$phase"
+  # Show branch/worktree info
+  local br_info wt_info
+  br_info="$(read_field branch 2>/dev/null || echo "")"
+  wt_info="$(read_field worktree 2>/dev/null || echo "")"
+  if [ -n "$wt_info" ]; then
+    printf "│ Worktree: %-34s│\n" "$wt_info"
+  elif [ -n "$br_info" ]; then
+    printf "│ Branch:  %-35s│\n" "$br_info"
+  fi
+  if [ -n "$artifact" ]; then
+    printf "│ Artifact: %-34s│\n" "$artifact"
+  else
+    printf "│ Artifact: %-34s│\n" "(none — register before approve)"
+  fi
+  # Show last completed task during implementation phase
+  if [ "$phase" = "implementation" ]; then
+    local lct
+    lct="$(read_field last_completed_task 2>/dev/null || echo "")"
+    if [ -n "$lct" ]; then
+      printf "│ Last task: %-33s│\n" "$lct"
+    fi
+  fi
+  echo "├─────────────────────────────────────────────┤"
+
+  # Show pipeline progress
+  local e_mark="○" r_mark="○" d_mark="○" t_mark="○" i_mark="○" rev_mark="○"
+  case "$phase" in
+    explore)        e_mark="●" ;;
+    requirements)   e_mark="✓"; r_mark="●" ;;
+    design)         e_mark="✓"; r_mark="✓"; d_mark="●" ;;
+    task-plan)      e_mark="✓"; r_mark="✓"; d_mark="✓"; t_mark="●" ;;
+    implementation) e_mark="✓"; r_mark="✓"; d_mark="✓"; t_mark="✓"; i_mark="●" ;;
+    review)         e_mark="✓"; r_mark="✓"; d_mark="✓"; t_mark="✓"; i_mark="✓"; rev_mark="●" ;;
+    done)           e_mark="✓"; r_mark="✓"; d_mark="✓"; t_mark="✓"; i_mark="✓"; rev_mark="✓" ;;
+  esac
+  printf "│ %s Ex → %s Rq → %s Ds → %s Tp → %s Im → %s Rv │\n" "$e_mark" "$r_mark" "$d_mark" "$t_mark" "$i_mark" "$rev_mark"
+  echo "└─────────────────────────────────────────────┘"
+
+  # Show history
+  if [ "$history_count" -gt 0 ]; then
+    echo ""
+    echo "Completed phases:"
+    local i=0
+    while [ "$i" -lt "$history_count" ]; do
+      local h_phase h_artifact h_approved
+      h_phase="$(read_field "history_${i}_phase")"
+      h_artifact="$(read_field "history_${i}_artifact")"
+      h_approved="$(read_field "history_${i}_approved_at")"
+      printf "  [%s] %-15s → %s (approved: %s)\n" "$((i+1))" "$h_phase" "$h_artifact" "$h_approved"
+      i=$((i + 1))
+    done
+  fi
+
+  # Hint for next action
+  echo ""
+  if [ "$phase" = "done" ]; then
+    info "Pipeline complete."
+  elif [ -z "$artifact" ]; then
+    info "Next: register artifact with 'pipeline.sh artifact <path>'"
+    info "Then: 'pipeline.sh approve' after user approval"
+  else
+    info "Artifact registered. Ask user to approve, then run 'pipeline.sh approve'"
+  fi
+  echo ""
+}
+
+cmd_artifact() {
+  resolve_feature || die "No active pipeline. Run 'pipeline.sh init <feature>' first."
+
+  local phase
+  phase="$(read_field phase)"
+  [ "$phase" = "done" ] && die "Pipeline is complete. Nothing to register."
+
+  local path="$1"
+
+  # If no path given, use the default: .spec/features/<feature>/<phase>.md
+  if [ -z "$path" ]; then
+    path="$FEATURE_DIR/${phase}.md"
+  fi
+
+  validate_artifact_path "$path"
+  [ -f "$path" ] || die "Artifact file does not exist: $path"
+
+  # Save a snapshot of the artifact being registered (revision tracking)
+  local rev_count
+  rev_count="$(read_field "revision_count_${phase}")"
+  [ -z "$rev_count" ] && rev_count=0
+  rev_count=$((rev_count + 1))
+  local rev_name
+  rev_name="${phase}-rev-${rev_count}-$(iso_now_compact).md"
+  cp "$path" "$REVISIONS_DIR/$rev_name"
+  write_field "revision_count_${phase}" "$rev_count"
+  if [ "$rev_count" -gt 1 ]; then
+    info "Revision $rev_count saved: $rev_name"
+  fi
+
+  write_field current_artifact "$path"
+  rebuild_json
+  info "Artifact registered for phase '$phase': $path"
+}
+
+cmd_approve() {
+  resolve_feature || die "No active pipeline."
+
+  local phase artifact history_count
+  phase="$(read_field phase)"
+  artifact="$(read_field current_artifact)"
+  history_count="$(read_field history_count)"
+  [ -z "$history_count" ] && history_count=0
+
+  [ "$phase" = "done" ] && die "Pipeline already complete."
+  [ -z "$artifact" ] && die "No artifact registered for phase '$phase'. Run 'pipeline.sh artifact <path>' first."
+  [ -f "$artifact" ] || die "Artifact file no longer exists: $artifact. Re-register with 'pipeline.sh artifact <path>'."
+
+  # Snapshot artifact contents
+  cp "$artifact" "$APPROVED_DIR/${phase}.md"
+
+  # Record base commit for review phase (git diff source)
+  if [ "$phase" = "task-plan" ]; then
+    local base_commit
+    base_commit="$(git rev-parse HEAD 2>/dev/null || echo "")"
+    write_field review_base_commit "$base_commit"
+  fi
+
+  # Record in history
+  write_field "history_${history_count}_phase" "$phase"
+  write_field "history_${history_count}_artifact" "$artifact"
+  write_field "history_${history_count}_approved_at" "$(iso_now)"
+  history_count=$((history_count + 1))
+  write_field history_count "$history_count"
+
+  # Advance phase
+  local next
+  next="$(next_phase "$phase")"
+  write_field phase "$next"
+  write_field current_artifact ""
+
+  # Clear task tracking when leaving implementation
+  if [ "$phase" = "implementation" ]; then
+    write_field last_completed_task ""
+  fi
+
+  rebuild_json
+
+  if [ "$next" = "done" ]; then
+    echo ""
+    echo "✅ Pipeline complete!"
+    echo ""
+    echo "All artifacts:"
+    local i=0
+    while [ "$i" -lt "$history_count" ]; do
+      printf "  [%s] %s → %s\n" "$((i+1))" \
+        "$(read_field "history_${i}_phase")" \
+        "$(read_field "history_${i}_artifact")"
+      i=$((i + 1))
+    done
+    echo ""
+    local feat
+    feat="$(read_field feature)"
+    info "Artifacts saved in: .spec/features/$feat/"
+    info "Next: check documentation (docs-check), then finish branch (pipeline.sh finish)"
+  else
+    info "Phase '$phase' approved."
+    info "Advanced to: [$(phase_number "$next")/6] $next"
+    info "Read template: ./templates/${next}.md"
+  fi
+}
+
+cmd_task() {
+  local task_id="$1"
+  [ -z "$task_id" ] && die "Usage: pipeline.sh task <T-N>"
+
+  resolve_feature || die "No active pipeline."
+
+  local phase
+  phase="$(read_field phase)"
+  [ "$phase" = "implementation" ] || die "Task tracking is only available during implementation phase (current: $phase)."
+
+  write_field last_completed_task "$task_id"
+  rebuild_json
+  info "Task $task_id marked complete"
+}
+
+cmd_history() {
+  if [ ! -d "$FEATURES_DIR" ]; then
+    info "No features found."
+    return 0
+  fi
+
+  local found=0
+  for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+    [ -f "$kv" ] || continue
+    found=1
+    local fname phase created
+    fname="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+    phase="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+    created="$(grep "^created_at=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+
+    local status_icon
+    if [ "$phase" = "done" ]; then
+      status_icon="✓"
+    else
+      status_icon="●"
+    fi
+
+    printf "  %s %-25s [%s/6] %-15s (created: %s)\n" \
+      "$status_icon" "$fname" "$(phase_number "$phase")" "$phase" "$created"
+  done
+
+  if [ "$found" -eq 0 ]; then
+    info "No features found."
+  fi
+}
+
+cmd_revisions() {
+  resolve_feature || die "No active pipeline."
+
+  local phase
+  phase="$(read_field phase)"
+
+  local target_phase="${1:-$phase}"
+  # Validate target phase
+  case "$target_phase" in
+    explore|requirements|design|task-plan|implementation|review|all) ;;
+    *) die "Unknown phase: $target_phase. Use: explore, requirements, design, task-plan, implementation, review, or all." ;;
+  esac
+
+  local found=0
+  local tmp
+  tmp="$(mktemp)"
+  if [ "$target_phase" = "all" ]; then
+    echo "All revisions:"
+    for p in explore requirements design task-plan implementation review; do
+      find "$REVISIONS_DIR" -name "${p}-rev-*" 2>/dev/null | sort > "$tmp"
+      while IFS= read -r f; do
+        printf "  [%s] %s\n" "$p" "$(basename "$f")"
+        found=1
+      done < "$tmp"
+    done
+  else
+    echo "Revisions for phase '$target_phase':"
+    find "$REVISIONS_DIR" -name "${target_phase}-rev-*" 2>/dev/null | sort > "$tmp"
+    while IFS= read -r f; do
+      printf "  %s\n" "$(basename "$f")"
+      found=1
+    done < "$tmp"
+  fi
+  rm -f "$tmp"
+
+  if [ "$found" -eq 0 ]; then
+    info "No revisions recorded yet."
+  fi
+}
+
+cmd_version() {
+  echo "Spec-Driven Dev Pipeline v${VERSION}"
+}
+
+# check_file_staleness <file> <templates_dir> <freshness_days> <now_epoch>
+# Outputs tab-separated: generated template age_days stale scope_changed
+check_file_staleness() {
+  local f="$1" templates_dir="$2" freshness_days="$3" now_epoch="$4"
+  local generated="null" template="null" age_days="null" stale="false" scope_changed="null"
+
+  local first_line
+  first_line="$(head -1 "$f" 2>/dev/null)"
+  case "$first_line" in
+    *"<!-- generated:"*"template:"*"-->"*)
+      local gen_date gen_tmpl
+      gen_date="$(echo "$first_line" | sed 's/.*<!-- generated: \([0-9-]*\),.*/\1/')"
+      gen_tmpl="$(echo "$first_line" | sed 's/.*template: \([^ ]*\) -->.*/\1/')"
+      if [ -n "$gen_date" ]; then
+        generated="\"$gen_date\""
+        template="\"$gen_tmpl\""
+        local gen_epoch
+        gen_epoch="$(date -j -f '%Y-%m-%d' "$gen_date" '+%s' 2>/dev/null || date -d "$gen_date" '+%s' 2>/dev/null || echo 0)"
+        if [ "$gen_epoch" -gt 0 ] && [ "$now_epoch" -gt 0 ]; then
+          age_days=$(( (now_epoch - gen_epoch) / 86400 ))
+
+          local tmpl_file="$templates_dir/$gen_tmpl"
+          if [ -f "$tmpl_file" ]; then
+            local scope_line
+            scope_line="$(head -1 "$tmpl_file" 2>/dev/null)"
+            case "$scope_line" in
+              "<!-- scope:"*"-->")
+                local patterns
+                patterns="$(echo "$scope_line" | sed 's/<!-- scope: //' | sed 's/ -->//' | sed 's/,[[:space:]]*/\n/g' | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
+                if [ -n "$patterns" ]; then
+                  local git_hits
+                  # shellcheck disable=SC2086
+                  git_hits="$(cd "$PROJECT_ROOT" && set -f && git log --oneline --since="$gen_date" -- $patterns 2>/dev/null | head -1)"
+                  if [ -n "$git_hits" ]; then
+                    scope_changed="true"
+                    if [ "$age_days" -gt "$freshness_days" ]; then
+                      stale="true"
+                    fi
+                  else
+                    scope_changed="false"
+                  fi
+                fi
+                ;;
+              *)
+                if [ "$age_days" -gt "$freshness_days" ]; then
+                  stale="true"
+                fi
+                ;;
+            esac
+          else
+            if [ "$age_days" -gt "$freshness_days" ]; then
+              stale="true"
+            fi
+          fi
+        fi
+      fi
+      ;;
+  esac
+  printf '%s\t%s\t%s\t%s\t%s' "$generated" "$template" "$age_days" "$stale" "$scope_changed"
+}
+
+cmd_docs_check() {
+  local config_file="$CONFIG_FILE"
+  local docs_dir=".spec"
+  local freshness_days=30
+
+  # Read docs_dir and doc_freshness_days from config.yaml if it exists
+  if [ -f "$config_file" ]; then
+    local configured_dir
+    configured_dir="$(grep '^docs_dir:' "$config_file" 2>/dev/null | head -1 | sed 's/^docs_dir:[[:space:]]*//' | sed 's/[[:space:]]*$//')"
+    if [ -n "$configured_dir" ]; then
+      docs_dir="$configured_dir"
+    fi
+    local configured_days
+    configured_days="$(grep '^doc_freshness_days:' "$config_file" 2>/dev/null | head -1 | sed 's/^doc_freshness_days:[[:space:]]*//' | sed 's/[[:space:]]*$//')"
+    if [ -n "$configured_days" ]; then
+      freshness_days="$configured_days"
+    fi
+  fi
+
+  local full_path="$PROJECT_ROOT/$docs_dir"
+  local templates_dir="$SKILL_DIR/templates/docs"
+  local now_epoch
+  now_epoch="$(date +%s 2>/dev/null || echo 0)"
+
+  if [ -d "$full_path" ]; then
+    printf '{"exists": true, "dir": "%s", "freshness_days": %d, "files": [' "$(json_escape "$docs_dir")" "$freshness_days"
+
+    # Single scan: find files into tmpfile, iterate once, capture stale names
+    local tmp_files tmp_stale
+    tmp_files="$(mktemp)"
+    tmp_stale="$(mktemp)"
+    find "$full_path" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort > "$tmp_files"
+
+    local first=1
+    while IFS= read -r f; do
+      local fname result generated template age_days stale scope_changed
+      fname="$(basename "$f")"
+      result="$(check_file_staleness "$f" "$templates_dir" "$freshness_days" "$now_epoch")"
+
+      generated="$(printf '%s' "$result" | cut -f1)"
+      template="$(printf '%s' "$result" | cut -f2)"
+      age_days="$(printf '%s' "$result" | cut -f3)"
+      stale="$(printf '%s' "$result" | cut -f4)"
+      scope_changed="$(printf '%s' "$result" | cut -f5)"
+
+      if [ "$first" -eq 1 ]; then
+        first=0
+      else
+        printf ', '
+      fi
+      printf '{"name": "%s", "generated": %s, "template": %s, "age_days": %s, "stale": %s, "scope_changed": %s}' \
+        "$(json_escape "$fname")" "$generated" "$template" "$age_days" "$stale" "$scope_changed"
+
+      if [ "$stale" = "true" ]; then
+        echo "$fname" >> "$tmp_stale"
+      fi
+    done < "$tmp_files"
+
+    printf '], "stale": ['
+    # Read stale names from tmpfile (no re-scan needed)
+    local sfirst=1
+    if [ -s "$tmp_stale" ]; then
+      while IFS= read -r sname; do
+        if [ "$sfirst" -eq 1 ]; then
+          sfirst=0
+        else
+          printf ', '
+        fi
+        printf '"%s"' "$(json_escape "$sname")"
+      done < "$tmp_stale"
+    fi
+    printf ']}\n'
+
+    rm -f "$tmp_files" "$tmp_stale"
+  else
+    printf '{"exists": false, "dir": "%s", "freshness_days": %d, "files": [], "stale": []}\n' "$(json_escape "$docs_dir")" "$freshness_days"
+  fi
+}
+
+# --- standalone docs queue ---
+
+DOCS_QUEUE_FILE="$PROJECT_ROOT/.spec/.docs-queue.kv"
+
+docs_queue_read() {
+  # docs_queue_read <key> — read value from queue file
+  [ -f "$DOCS_QUEUE_FILE" ] || return 1
+  local _line
+  _line="$(grep "^$1=" "$DOCS_QUEUE_FILE" 2>/dev/null | head -1)" || return 1
+  [ -n "$_line" ] || return 1
+  printf '%s' "$_line" | sed "s/^$1=//"
+}
+
+docs_queue_write_status() {
+  # docs_queue_write_status <index> <status>
+  local idx="$1" status="$2"
+  local tmp="$DOCS_QUEUE_FILE.tmp"
+  grep -v "^template_${idx}_status=" "$DOCS_QUEUE_FILE" > "$tmp" 2>/dev/null || true
+  echo "template_${idx}_status=$status" >> "$tmp"
+  mv -f "$tmp" "$DOCS_QUEUE_FILE"
+}
+
+docs_template_name() {
+  # Extract template name from generated file metadata (line 1)
+  local f="$1"
+  local first_line
+  first_line="$(head -1 "$f" 2>/dev/null)"
+  case "$first_line" in
+    "<!-- generated:"*"-->")
+      printf '%s' "$first_line" | sed -n 's/.*template:[[:space:]]*\([^[:space:]]*\)\.md[[:space:]]*-->/\1/p'
+      ;;
+  esac
+}
+
+cmd_docs_init() {
+  local mode="all"
+  local explicit_templates=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --all)    mode="all"; shift ;;
+      --update) mode="update"; shift ;;
+      -*)       die "Unknown flag for docs-init: $1" ;;
+      *)
+        explicit_templates="$explicit_templates $1"
+        mode="explicit"
+        shift
+        ;;
+    esac
+  done
+
+  [ -f "$DOCS_QUEUE_FILE" ] && die "Docs queue already exists at $DOCS_QUEUE_FILE. Run 'pipeline.sh docs-reset' first."
+
+  local templates_dir="$SKILL_DIR/templates/docs"
+  local docs_dir
+  docs_dir="$(read_config docs_dir ".spec")"
+  local full_path="$PROJECT_ROOT/$docs_dir"
+
+  local templates=""
+  case "$mode" in
+    all)
+      for f in "$templates_dir"/*.md; do
+        local name
+        name="$(basename "$f" .md)"
+        [ "$name" = "README" ] && continue
+        templates="$templates $name"
+      done
+      ;;
+    update)
+      [ -d "$full_path" ] || die "Docs directory '$docs_dir' does not exist. Use --all to bootstrap."
+      local freshness_days
+      freshness_days="$(read_config doc_freshness_days "30")"
+      local now_epoch
+      now_epoch="$(date +%s 2>/dev/null || echo 0)"
+      # Iterate stale files, extract template names
+      local tmp_list
+      tmp_list="$(mktemp)"
+      find "$full_path" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort > "$tmp_list"
+      while IFS= read -r f; do
+        local result stale tmpl
+        result="$(check_file_staleness "$f" "$templates_dir" "$freshness_days" "$now_epoch")"
+        stale="$(printf '%s' "$result" | cut -f4)"
+        if [ "$stale" = "true" ]; then
+          tmpl="$(docs_template_name "$f")"
+          if [ -n "$tmpl" ]; then
+            case " $templates " in
+              *" $tmpl "*) ;;
+              *) templates="$templates $tmpl" ;;
+            esac
+          fi
+        fi
+      done < "$tmp_list"
+      rm -f "$tmp_list"
+      ;;
+    explicit)
+      templates="$explicit_templates"
+      ;;
+  esac
+
+  mkdir -p "$(dirname "$DOCS_QUEUE_FILE")"
+
+  # Build queue file
+  local count=0
+  local tmp_queue="$DOCS_QUEUE_FILE.tmp"
+  {
+    echo "created_at=$(iso_now)"
+    echo "docs_dir=$docs_dir"
+    echo "mode=$mode"
+  } > "$tmp_queue"
+
+  for t in $templates; do
+    if [ ! -f "$templates_dir/$t.md" ]; then
+      warn "Template not found, skipping: $t"
+      continue
+    fi
+    echo "template_${count}=$t" >> "$tmp_queue"
+    echo "template_${count}_status=pending" >> "$tmp_queue"
+    count=$((count + 1))
+  done
+  echo "total=$count" >> "$tmp_queue"
+
+  if [ "$count" -eq 0 ]; then
+    rm -f "$tmp_queue"
+    info "No templates to queue (nothing stale or none selected)."
+    return 0
+  fi
+
+  mv -f "$tmp_queue" "$DOCS_QUEUE_FILE"
+
+  info "Docs queue created: $count template(s), mode=$mode."
+  info "Next: pipeline.sh docs-next"
+  info ""
+  info "Execution strategy:"
+  info "  - If your toolset supports subagent dispatch (Task/Composer/etc):"
+  info "    use SUBAGENT mode — dispatch up to 3 templates in parallel."
+  info "  - Otherwise: SEQUENTIAL mode — one template per iteration."
+  info "  See ./templates/docs-maintenance.md § Standalone Documentation Workflow."
+}
+
+cmd_docs_next() {
+  [ -f "$DOCS_QUEUE_FILE" ] || die "No docs queue. Run 'pipeline.sh docs-init' first."
+
+  local total
+  total="$(docs_queue_read total)"
+  [ -z "$total" ] && total=0
+
+  local i=0
+  local templates_dir="$SKILL_DIR/templates/docs"
+  local docs_dir
+  docs_dir="$(docs_queue_read docs_dir)"
+
+  while [ "$i" -lt "$total" ]; do
+    local status
+    status="$(docs_queue_read "template_${i}_status")"
+    if [ "$status" = "pending" ]; then
+      local name
+      name="$(docs_queue_read "template_${i}")"
+      printf '%s\t%s\n' "$name" "$templates_dir/$name.md"
+      # Sequential mode hint after position 3
+      if [ "$i" -ge 3 ]; then
+        info "" >&2
+        info "Tip: if context feels heavy, start a fresh chat and resume" >&2
+        info "     with 'pipeline.sh docs-status' (sequential mode)." >&2
+      fi
+      return 0
+    fi
+    i=$((i + 1))
+  done
+
+  info "Docs queue complete: all $total template(s) processed."
+  info "Run 'pipeline.sh docs-reset' to clear the queue."
+  return 0
+}
+
+cmd_docs_done() {
+  local name="${1:-}"
+  [ -z "$name" ] && die "Usage: pipeline.sh docs-done <template>"
+  [ -f "$DOCS_QUEUE_FILE" ] || die "No docs queue. Run 'pipeline.sh docs-init' first."
+
+  local total
+  total="$(docs_queue_read total)"
+  [ -z "$total" ] && total=0
+
+  local i=0
+  while [ "$i" -lt "$total" ]; do
+    local entry
+    entry="$(docs_queue_read "template_${i}")"
+    if [ "$entry" = "$name" ]; then
+      local status
+      status="$(docs_queue_read "template_${i}_status")"
+      if [ "$status" = "done" ]; then
+        warn "Template '$name' already marked done."
+        return 0
+      fi
+      docs_queue_write_status "$i" "done"
+      info "Marked done: $name ($((i + 1))/$total)"
+      # Check if queue is now complete
+      local remaining=0
+      local j=0
+      while [ "$j" -lt "$total" ]; do
+        local s
+        s="$(docs_queue_read "template_${j}_status")"
+        [ "$s" = "pending" ] && remaining=$((remaining + 1))
+        j=$((j + 1))
+      done
+      if [ "$remaining" -eq 0 ]; then
+        info "Docs queue complete. Run 'pipeline.sh docs-reset' to clear it."
+      fi
+      return 0
+    fi
+    i=$((i + 1))
+  done
+
+  die "Template '$name' not found in queue."
+}
+
+cmd_docs_status() {
+  if [ ! -f "$DOCS_QUEUE_FILE" ]; then
+    printf '{"exists": false}\n'
+    return 0
+  fi
+
+  local total docs_dir mode created_at
+  total="$(docs_queue_read total)"
+  docs_dir="$(docs_queue_read docs_dir)"
+  mode="$(docs_queue_read mode)"
+  created_at="$(docs_queue_read created_at)"
+  [ -z "$total" ] && total=0
+
+  local completed=0
+  local pending_list=""
+  local current=""
+  local first_pending_set=0
+  local i=0
+  while [ "$i" -lt "$total" ]; do
+    local name status
+    name="$(docs_queue_read "template_${i}")"
+    status="$(docs_queue_read "template_${i}_status")"
+    if [ "$status" = "done" ]; then
+      completed=$((completed + 1))
+    else
+      if [ "$first_pending_set" -eq 0 ]; then
+        current="$name"
+        first_pending_set=1
+      fi
+      if [ -z "$pending_list" ]; then
+        pending_list="\"$(json_escape "$name")\""
+      else
+        pending_list="$pending_list, \"$(json_escape "$name")\""
+      fi
+    fi
+    i=$((i + 1))
+  done
+
+  printf '{"exists": true, "total": %d, "completed": %d, "current": %s, "pending": [%s], "mode": "%s", "docs_dir": "%s", "created_at": "%s"}\n' \
+    "$total" \
+    "$completed" \
+    "$([ -n "$current" ] && printf '"%s"' "$(json_escape "$current")" || printf 'null')" \
+    "$pending_list" \
+    "$(json_escape "$mode")" \
+    "$(json_escape "$docs_dir")" \
+    "$(json_escape "$created_at")"
+}
+
+cmd_docs_reset() {
+  if [ ! -f "$DOCS_QUEUE_FILE" ]; then
+    info "No docs queue to reset."
+    return 0
+  fi
+
+  local total completed=0
+  total="$(docs_queue_read total)"
+  [ -z "$total" ] && total=0
+  local i=0
+  while [ "$i" -lt "$total" ]; do
+    local s
+    s="$(docs_queue_read "template_${i}_status")"
+    [ "$s" = "done" ] && completed=$((completed + 1))
+    i=$((i + 1))
+  done
+
+  rm -f "$DOCS_QUEUE_FILE"
+  info "Docs queue reset (was: $completed/$total completed)."
+}
+
+cmd_config_check() {
+  [ -f "$CONFIG_FILE" ] || { info "No config file found: $CONFIG_FILE"; return 0; }
+
+  local valid_keys=" context rules.explore rules.requirements rules.design rules.task-plan rules.implementation rules.review rules.docs test_skill test_reference docs_dir doc_freshness_days auto_branch branch_prefix auto_worktree worktree_dir "
+  local errors=0
+
+  info "Checking $CONFIG_FILE ..."
+
+  # Extract keys and validate against whitelist
+  local tmp
+  tmp="$(mktemp)"
+  grep '^[a-z]' "$CONFIG_FILE" 2>/dev/null > "$tmp" || true
+  while IFS= read -r line; do
+    local key
+    key="$(printf '%s' "$line" | sed 's/:.*//')"
+    case "$valid_keys" in
+      *" $key "*) ;;
+      *) warn "Unknown key: '$key'"; errors=$((errors + 1)) ;;
+    esac
+  done < "$tmp"
+  rm -f "$tmp"
+
+  # Type checks
+  local val
+  val="$(read_config doc_freshness_days "")"
+  if [ -n "$val" ]; then
+    case "$val" in
+      *[!0-9]*) warn "doc_freshness_days must be numeric, got: '$val'"; errors=$((errors + 1)) ;;
+    esac
+  fi
+
+  val="$(read_config auto_branch "")"
+  if [ -n "$val" ]; then
+    case "$val" in
+      true|false|yes|no|1|0) ;;
+      *) warn "auto_branch must be boolean (true/false/yes/no/1/0), got: '$val'"; errors=$((errors + 1)) ;;
+    esac
+  fi
+
+  val="$(read_config auto_worktree "")"
+  if [ -n "$val" ]; then
+    case "$val" in
+      true|false|yes|no|1|0) ;;
+      *) warn "auto_worktree must be boolean (true/false/yes/no/1/0), got: '$val'"; errors=$((errors + 1)) ;;
+    esac
+  fi
+
+  if [ "$errors" -eq 0 ]; then
+    info "Config OK — all keys valid."
+  else
+    warn "$errors problem(s) found."
+    return 1
+  fi
+}
+
+cmd_inject() {
+  local target_phase="${1:-}"
+  local artifact_path="${2:-}"
+
+  if [ -z "$target_phase" ] || [ -z "$artifact_path" ]; then
+    die "Usage: pipeline.sh inject <phase> <path>"
+  fi
+
+  # Validate target phase
+  case "$target_phase" in
+    explore|requirements|design|task-plan|implementation|review) ;;
+    *) die "Unknown phase: $target_phase. Use: explore, requirements, design, task-plan, implementation, review." ;;
+  esac
+
+  resolve_feature || die "No active pipeline. Run 'pipeline.sh init <feature>' first."
+
+  local current_phase
+  current_phase="$(read_field phase)"
+  [ "$current_phase" = "done" ] && die "Pipeline already complete."
+
+  # Validate current phase <= target phase
+  local current_num target_num
+  current_num="$(phase_order "$current_phase")"
+  target_num="$(phase_order "$target_phase")"
+  if [ "$current_num" -gt "$target_num" ]; then
+    die "Cannot inject backward: current phase is '$current_phase' ($current_num), target is '$target_phase' ($target_num)."
+  fi
+
+  validate_artifact_path "$artifact_path"
+  [ -f "$artifact_path" ] || die "Artifact file does not exist: $artifact_path"
+
+  # Lightweight content validation
+  case "$target_phase" in
+    requirements)
+      if ! grep -q 'WHEN\|SHALL' "$artifact_path" 2>/dev/null; then
+        warn "Requirements artifact should contain WHEN/SHALL keywords."
+      fi
+      ;;
+    design)
+      if ! grep -q 'Correctness\|Property' "$artifact_path" 2>/dev/null; then
+        warn "Design artifact should contain Correctness Properties."
+      fi
+      ;;
+  esac
+
+  # Skip intermediate phases (record as injected in history)
+  local p="$current_phase"
+  local history_count
+  history_count="$(read_field history_count)"
+  [ -z "$history_count" ] && history_count=0
+
+  while [ "$p" != "$target_phase" ]; do
+    write_field "history_${history_count}_phase" "$p"
+    write_field "history_${history_count}_artifact" "(injected)"
+    write_field "history_${history_count}_approved_at" "$(iso_now)"
+    history_count=$((history_count + 1))
+    p="$(next_phase "$p")"
+  done
+
+  # Set to target phase and register artifact
+  write_field phase "$target_phase"
+  write_field current_artifact "$artifact_path"
+  write_field history_count "$history_count"
+
+  # Save revision snapshot
+  local rev_count
+  rev_count="$(read_field "revision_count_${target_phase}")"
+  [ -z "$rev_count" ] && rev_count=0
+  rev_count=$((rev_count + 1))
+  local rev_name
+  rev_name="${target_phase}-rev-${rev_count}-$(iso_now_compact).md"
+  cp "$artifact_path" "$REVISIONS_DIR/$rev_name"
+  write_field "revision_count_${target_phase}" "$rev_count"
+
+  # Capture review_base_commit if injecting into implementation/review and not already set
+  case "$target_phase" in
+    implementation|review)
+      local rbc
+      rbc="$(read_field review_base_commit 2>/dev/null || echo "")"
+      if [ -z "$rbc" ]; then
+        local head_commit
+        head_commit="$(git rev-parse HEAD 2>/dev/null || echo "")"
+        if [ -n "$head_commit" ]; then
+          write_field review_base_commit "$head_commit"
+          info "Captured review_base_commit: $(printf '%.8s' "$head_commit")"
+        fi
+      fi
+      ;;
+  esac
+
+  rebuild_json
+
+  local skipped=$((target_num - current_num))
+  if [ "$skipped" -gt 0 ]; then
+    info "$skipped phase(s) skipped to reach '$target_phase'."
+  fi
+  info "Artifact injected for phase '$target_phase': $artifact_path"
+  info "Ask user to approve, then run 'pipeline.sh approve'"
+}
+
+cmd_finish() {
+  # Parse finish-specific flags and action
+  local action=""
+  local confirm=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --confirm) confirm="yes"; shift ;;
+      -*)        die "Unknown flag for finish: $1" ;;
+      *)
+        [ -n "$action" ] && die "Unexpected argument: $1"
+        action="$1"; shift
+        ;;
+    esac
+  done
+
+  [ -z "$action" ] && die "Usage: pipeline.sh finish <merge|pr|keep|discard> [--confirm]"
+
+  # Validate action
+  case "$action" in
+    merge|pr|keep|discard) ;;
+    *) die "Unknown finish action: $action. Use: merge, pr, keep, discard." ;;
+  esac
+
+  # Resolve feature (supports completed pipelines)
+  if [ -n "$EXPLICIT_FEATURE" ]; then
+    if [ ! -f "$FEATURES_DIR/$EXPLICIT_FEATURE/pipeline.kv" ]; then
+      die "Feature '$EXPLICIT_FEATURE' not found."
+    fi
+    set_feature_context "$EXPLICIT_FEATURE"
+    validate_kv
+  else
+    # For finish, we need to find a done-but-not-finished feature
+    local found=""
+    local count=0
+    if [ -d "$FEATURES_DIR" ]; then
+      for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+        [ -f "$kv" ] || continue
+        local p fa
+        p="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        fa="$(grep "^finish_action=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        if [ "$p" = "done" ] && [ -z "$fa" ]; then
+          local fn
+          fn="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+          found="$fn"
+          count=$((count + 1))
+        fi
+      done
+    fi
+    if [ "$count" -gt 1 ]; then
+      warn "Multiple completed pipelines awaiting finish:"
+      for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+        [ -f "$kv" ] || continue
+        local p fa fn
+        p="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        fa="$(grep "^finish_action=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        fn="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        if [ "$p" = "done" ] && [ -z "$fa" ]; then
+          echo "  - $fn" >&2
+        fi
+      done
+      die "Use --feature <name> to select one."
+    fi
+    if [ -z "$found" ]; then
+      die "No completed pipeline awaiting finish. Run 'pipeline.sh history' to list features."
+    fi
+    set_feature_context "$found"
+    validate_kv
+  fi
+
+  local phase
+  phase="$(read_field phase)"
+  [ "$phase" != "done" ] && die "Pipeline not complete (current phase: $phase). Finish is only available after all phases are done."
+
+  # Check idempotency
+  local existing_action
+  existing_action="$(read_field finish_action 2>/dev/null || echo "")"
+  if [ -n "$existing_action" ]; then
+    die "Already finished (action: $existing_action). Nothing to do."
+  fi
+
+  # Git availability check
+  if [ "$action" != "keep" ]; then
+    if ! command -v git >/dev/null 2>&1; then
+      die "Git not found. Use 'finish keep' to skip git operations."
+    fi
+    if ! git rev-parse --git-dir >/dev/null 2>&1; then
+      die "Not a git repository. Use 'finish keep' to skip git operations."
+    fi
+  fi
+
+  local feat branch current_branch worktree
+  feat="$(read_field feature)"
+  branch="$(read_field branch 2>/dev/null || echo "")"
+  worktree="$(read_field worktree 2>/dev/null || echo "")"
+  current_branch="$(git branch --show-current 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+
+  # Determine base branch for merge/discard
+  local base_branch=""
+  if [ "$action" = "merge" ] || [ "$action" = "discard" ]; then
+    # Try to find default branch
+    if git rev-parse --verify main >/dev/null 2>&1; then
+      base_branch="main"
+    elif git rev-parse --verify master >/dev/null 2>&1; then
+      base_branch="master"
+    else
+      die "Cannot determine base branch (no main or master). Merge/discard manually."
+    fi
+
+    # Check for uncommitted changes
+    if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+      die "Working tree has uncommitted changes. Commit or stash before '$action'."
+    fi
+  fi
+
+  # Determine which branch to operate on
+  local target_branch="${branch:-$current_branch}"
+
+  case "$action" in
+    merge)
+      [ -z "$target_branch" ] && die "No branch to merge (not on a feature branch and no branch recorded)."
+      [ "$target_branch" = "$base_branch" ] && die "Already on $base_branch. Nothing to merge."
+      # If worktree, remove it first (must not be in worktree dir when removing)
+      if [ -n "$worktree" ] && git worktree list 2>/dev/null | grep -q "$worktree"; then
+        git worktree remove "$worktree" || die "Failed to remove worktree '$worktree'."
+        info "Removed worktree: $worktree"
+      fi
+      git checkout "$base_branch" || die "Failed to checkout $base_branch."
+      git merge "$target_branch" || die "Merge failed. Resolve conflicts and retry."
+      write_field finish_action "merge"
+      write_field finished_at "$(iso_now)"
+      write_field finish_base "$base_branch"
+      rebuild_json
+      info "Merged '$target_branch' into '$base_branch'."
+      info "Tip: run tests to verify, then 'git branch -d $target_branch' to clean up."
+      ;;
+
+    pr)
+      [ -z "$target_branch" ] && die "No branch to push (not on a feature branch and no branch recorded)."
+      [ "$target_branch" = "$base_branch" ] && die "Already on $base_branch. Nothing to push."
+      git push -u origin "$target_branch" || die "Failed to push '$target_branch'."
+      write_field finish_action "pr"
+      write_field finished_at "$(iso_now)"
+      write_field finish_base "${base_branch:-}"
+      rebuild_json
+      info "Branch '$target_branch' pushed to origin."
+      info "Create a pull request: gh pr create --fill"
+      ;;
+
+    keep)
+      write_field finish_action "keep"
+      write_field finished_at "$(iso_now)"
+      rebuild_json
+      info "Branch kept as-is. Handle manually when ready."
+      ;;
+
+    discard)
+      [ "$confirm" != "yes" ] && die "Discard deletes the branch and all unmerged commits. Re-run with --confirm to proceed: pipeline.sh finish discard --confirm"
+      [ -z "$target_branch" ] && die "No branch to discard (not on a feature branch and no branch recorded)."
+      [ "$target_branch" = "$base_branch" ] && die "Cannot discard $base_branch."
+      # If worktree, force-remove it first
+      if [ -n "$worktree" ] && git worktree list 2>/dev/null | grep -q "$worktree"; then
+        git worktree remove --force "$worktree" || die "Failed to remove worktree '$worktree'."
+        info "Removed worktree: $worktree"
+      fi
+      git checkout "$base_branch" || die "Failed to checkout $base_branch."
+      git branch -D "$target_branch" || die "Failed to delete branch '$target_branch'."
+      write_field finish_action "discard"
+      write_field finished_at "$(iso_now)"
+      write_field finish_base "$base_branch"
+      rebuild_json
+      info "Branch '$target_branch' discarded."
+      ;;
+  esac
+}
+
+cmd_abandon() {
+  local feature="${1:-}"
+
+  # If --feature was specified globally, use it
+  if [ -z "$feature" ] && [ -n "$EXPLICIT_FEATURE" ]; then
+    feature="$EXPLICIT_FEATURE"
+  fi
+
+  # If still empty, try to resolve active feature
+  if [ -z "$feature" ]; then
+    feature="$(detect_active_feature)" || die "Multiple active pipelines. Use: pipeline.sh abandon <feature-name>"
+    [ -z "$feature" ] && die "No active pipeline to abandon."
+  fi
+
+  local fdir="$FEATURES_DIR/$feature"
+  [ -f "$fdir/pipeline.kv" ] || die "Feature '$feature' not found."
+
+  local phase
+  phase="$(grep "^phase=" "$fdir/pipeline.kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+  [ "$phase" = "done" ] && die "Feature '$feature' is already completed."
+
+  set_feature_context "$feature"
+  write_field phase "done"
+  write_field abandoned_at "$(iso_now)"
+  write_field finish_action "abandoned"
+  write_field finished_at "$(iso_now)"
+
+  # Clean up worktree if present
+  local wt
+  wt="$(read_field worktree 2>/dev/null || echo "")"
+  if [ -n "$wt" ] && command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+    if git worktree list 2>/dev/null | grep -q "$wt"; then
+      git worktree remove --force "$wt" 2>/dev/null && info "Removed worktree: $wt"
+    fi
+  fi
+
+  rebuild_json
+
+  info "Feature '$feature' abandoned (was in phase: $phase)."
+  info "Artifacts remain in: .spec/features/$feature/"
+}
+
+cmd_help() {
+  echo "Spec-Driven Dev Pipeline v${VERSION}"
+  echo ""
+  echo "Usage: sh pipeline.sh [--feature <name>] <command> [args]"
+  echo ""
+  echo "Global flags:"
+  echo "  --feature <name>  Select feature (needed when multiple are active)"
+  echo ""
+  echo "Commands:"
+  echo "  init [--branch|--worktree|--no-branch] <feature>"
+  echo "                    Start a new pipeline (kebab-case name)"
+  echo "                    --branch: create git branch <prefix><name>"
+  echo "                    --worktree: create git worktree in <worktree_dir>/<name>"
+  echo "                    --no-branch: skip auto-branch/worktree from config"
+  echo "  status            Show current phase, artifacts, progress"
+  echo "  artifact [path]   Register output artifact for current phase"
+  echo "  approve           Advance to next phase (needs artifact)"
+  echo "  revisions [phase] Show revision history (current phase or specify: explore, all)"
+  echo "  history           Show all features and their status"
+  echo "  docs-check        Check project documentation status (JSON)"
+  echo "  docs-init [--all|--update|<template>...]"
+  echo "                    Create standalone docs generation queue"
+  echo "                    --all: queue all available templates"
+  echo "                    --update: queue only stale templates"
+  echo "                    <template>...: queue explicit templates by name"
+  echo "  docs-next         Print next pending template (name + path)"
+  echo "  docs-done <name>  Mark template as completed in queue"
+  echo "  docs-status       Show docs queue progress (JSON)"
+  echo "  docs-reset        Clear the docs queue"
+  echo "  task <T-N>        Mark implementation task as completed (resume tracking)"
+  echo "  config-check      Validate .spec/config.yaml keys and types"
+  echo "  inject <phase> <path>"
+  echo "                    Inject pre-written artifact and skip to that phase"
+  echo "  finish <action>   Finalize branch after pipeline completes"
+  echo "                    Actions: merge, pr, keep, discard (--confirm)"
+  echo "  abandon [feature] Abandon an active pipeline (marks as done)"
+  echo "  version           Show version"
+  echo "  help              Show this message"
+  echo ""
+  echo "Workflow (6 phases):"
+  echo "  1. init my-feature"
+  echo "  2. (agent reads templates/explore.md, investigates)"
+  echo "  3. artifact  ← writes .spec/features/my-feature/explore.md"
+  echo "  4. approve   ← user confirms"
+  echo "  5. (agent reads templates/requirements.md, generates doc)"
+  echo "  6. artifact  ← writes .spec/features/my-feature/requirements.md"
+  echo "  7. approve   ← user confirms"
+  echo "  8. (agent reads templates/design.md, generates doc)"
+  echo "  9. artifact  ← writes .spec/features/my-feature/design.md"
+  echo " 10. approve   ← user confirms"
+  echo " 11. (agent reads templates/task-plan.md, creates TDD plan)"
+  echo " 12. artifact  ← writes .spec/features/my-feature/task-plan.md"
+  echo " 13. approve   ← user confirms"
+  echo " 14. (agent reads templates/implementation.md, executes TDD plan)"
+  echo " 15. artifact  ← writes .spec/features/my-feature/implementation.md"
+  echo " 16. approve   ← user confirms"
+  echo " 17. (agent reads templates/review.md, reviews code)"
+  echo " 18. artifact  ← writes .spec/features/my-feature/review.md"
+  echo " 19. approve   ← user confirms → done!"
+  echo " 20. docs-check ← update project documentation if needed"
+  echo " 21. finish     ← merge, push PR, keep, or discard branch"
+  echo ""
+  echo "All artifacts are saved permanently in .spec/features/<feature>/ and tracked by git."
+  echo "Tip: use 'revisions' to see previous versions of an artifact within a phase."
+}
+
+# --- main ---
+
+# Parse global flags before command dispatch
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --feature)
+      [ -n "$2" ] || die "--feature requires a value"
+      EXPLICIT_FEATURE="$2"
+      shift 2
+      ;;
+    *) break ;;
+  esac
+done
+
+case "${1:-help}" in
+  init)     shift; cmd_init "$@" ;;
+  status)   cmd_status ;;
+  artifact) shift; cmd_artifact "$@" ;;
+  approve)  cmd_approve ;;
+  revisions) shift; cmd_revisions "$@" ;;
+  history)  cmd_history ;;
+  docs-check) cmd_docs_check ;;
+  task)     shift; cmd_task "$@" ;;
+  config-check) cmd_config_check ;;
+  inject)   shift; cmd_inject "$@" ;;
+  finish)   shift; cmd_finish "$@" ;;
+  abandon)  shift; cmd_abandon "$@" ;;
+  docs-init)   shift; cmd_docs_init "$@" ;;
+  docs-next)   cmd_docs_next ;;
+  docs-done)   shift; cmd_docs_done "$@" ;;
+  docs-status) cmd_docs_status ;;
+  docs-reset)  cmd_docs_reset ;;
+  version|--version|-v) cmd_version ;;
+  help|--help|-h) cmd_help ;;
+  *)        die "Unknown command: $1. Run 'pipeline.sh help' for usage." ;;
+esac
diff --git a/.agents/skills/sdd/templates/_preamble.md b/.agents/skills/sdd/templates/_preamble.md
new file mode 100644
index 0000000..37ae049
--- /dev/null
+++ b/.agents/skills/sdd/templates/_preamble.md
@@ -0,0 +1,37 @@
+# Phase Preamble — Shared Instructions
+
+This file contains pipeline integration and project context instructions shared by all phase templates.
+
+Each phase template references this file instead of repeating these sections.
+
+---
+
+## Pipeline Integration
+
+Before starting any phase work:
+
+1. **Check pipeline state:**
+   ```
+   sh ./scripts/pipeline.sh status
+   ```
+2. **Read input artifacts:** read all completed phase artifacts listed in the status output (`history[N].artifact`). Later phases build on earlier ones — read them all for context.
+3. **After the user approves your output:**
+   a. Save the document to `.spec/features/<feature-name>/<phase-name>.md`
+   b. Register: `sh ./scripts/pipeline.sh artifact` (defaults to `.spec/features/<feature-name>/<phase-name>.md`)
+   c. Wait for user to confirm, then: `sh ./scripts/pipeline.sh approve`
+
+> **Directory separation — DO NOT mix these:**
+> - **Phase artifacts** (explore.md, requirements.md, design.md, …) → `.spec/features/<feature>/`
+> - **Project documentation** (README.md, ARCHITECTURE.md, DOMAIN.md, …) → `<docs_dir>/` (default: `.spec/`)
+>
+> Phase artifact instructions above apply ONLY to pipeline phase outputs. Project documentation is a separate workflow — see `./templates/docs-maintenance.md`.
+
+---
+
+## Project Context
+
+If `.spec/config.yaml` exists, read it now and apply:
+- **`context`** → treat as background knowledge about this project.
+- **`rules.<phase>`** → treat as additional rules for THIS phase (appended to the rules below, not replacing them). The phase-specific rule key is specified in each template.
+
+If the file does not exist, skip this step.
diff --git a/.agents/skills/sdd/templates/design.md b/.agents/skills/sdd/templates/design.md
new file mode 100644
index 0000000..432c64d
--- /dev/null
+++ b/.agents/skills/sdd/templates/design.md
@@ -0,0 +1,302 @@
+# Phase 3: Design
+
+You are a Software Architect. Your task: accept the approved requirements document and transform it into a detailed design document that fully describes **HOW** to implement the requirements.
+
+You do **NOT** write implementation code.
+You do **NOT** create task lists.
+You **design** the solution: architecture, interfaces, data models, correctness properties, and verification strategy.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.design`
+- **Input artifacts:** read `history[0..1].artifact` (exploration, requirements documents)
+- **Output:** `.spec/features/<feature-name>/design.md`
+
+---
+
+### Fast-track mode
+
+When the requirements artifact contains 1–2 REQs for a small bug fix:
+
+- **§2.1 Overview:** 1 paragraph.
+- **§2.2 Architecture:** simplified diagram — only the modified component(s). Omit unchanged context unless needed for understanding.
+- **§2.3 Components:** only files requiring changes + 1–2 unchanged files for context. Skip exhaustive "NOT Requiring Changes" list.
+- **§2.4 Key Decisions:** 1 ADR max. Omit if the fix is straightforward with no meaningful alternatives.
+- **§2.5 Data Models:** omit entirely if no new types or schema changes.
+- **§2.6 Correctness Properties:** 2–3 properties focused on the bug scenario. Skip categories that don't apply.
+- **§2.7 Error Handling:** 1–2 rows (main error path + fallback if applicable).
+- **§2.8 Testing Strategy:** reference existing test infrastructure. No new test patterns needed unless the bug exposed a gap.
+
+Target artifact size: **≤ 1.5 pages**.
+
+---
+
+## Language
+
+Write the design document in the **user's language** (detected from their first message). This includes:
+- Section headers (translate "Overview", "Architecture", "Key Decisions", "Error Handling", etc.)
+- All prose: overviews, ADR context/rationale/consequences, error scenario descriptions, test descriptions
+- File change descriptions in §2.3 tables (the "Description" column)
+- Correctness Property statements: write in the user's language, but keep the formal frame in English — `Property N`, `Category`, the quantifier `For all`, and `Validates: Requirements X.Y`
+
+Keep in English (do not translate):
+- Code signatures, type definitions, field names, import paths
+- Mermaid diagram node labels (they reference code constructs)
+- File paths in §2.3 tables
+- Project Commands table values (commands must be verbatim)
+- Tag names in test tables: `Feature/<name>`, `Property/<N>`
+
+---
+
+## Step 1: Context Clarification (optional)
+
+Ask clarifying questions when:
+- The requirements admit multiple substantially different architectural solutions
+- You need information about the existing codebase to make sound design decisions
+- There are contradictions or ambiguities in the requirements
+
+Group 2–4 questions in a single message. If the requirements are self-contained and unambiguous, you may skip this step — but then label every design assumption with `[ASSUMPTION: ...]` inline where it appears, so the user can spot and correct unstated beliefs during review.
+
+---
+
+## Step 2: Design Document Generation
+
+Produce a design document with the following sections. All marked **[REQUIRED]** must appear in every design document. Sections marked **[IF APPLICABLE]** should be included when relevant.
+
+---
+
+### 2.1 Overview [REQUIRED]
+
+Provide a brief description of the feature or change being designed. If the task divides into distinct logical parts, list them explicitly.
+
+---
+
+### 2.2 Architecture [REQUIRED]
+
+Describe the overall architecture using one or more **Mermaid diagrams**. Diagrams must visually distinguish:
+
+- **New** components: `fill:#90EE90` (green)
+- **Modified** components: `fill:#FFD700` (yellow)
+- **Existing/unchanged** components: default styling
+
+Also specify the **implementation order** — which parts should be built first and why.
+
+---
+
+### 2.3 Components and Interfaces [REQUIRED]
+
+#### Files Requiring Changes
+
+Provide a table of all files that must be created or modified:
+
+| File | Change Type | Description |
+|------|-------------|-------------|
+| `path/to/file` | `[NEW]` / `[MODIFIED]` / `[DELETED]` | What specifically is added, changed, or removed |
+
+For `[MODIFIED]` files — state **what exactly changes** (not "various changes"). Example:
+- ✓ `[MODIFIED]` — adds `refreshToken()` method, modifies `authenticate()` return type
+- ✗ `[MODIFIED]` — various authentication changes
+
+#### Files NOT Requiring Changes
+
+Explicitly list files that are in scope or might be expected to change, but will **not** be modified:
+
+| File | Reason Unchanged |
+|------|-----------------|
+| `path/to/file` | Explanation of why this file is unaffected |
+
+> Do not leave this table empty or skip it. Explicitly stating what is not changing is part of the design.
+
+For each interface, provide:
+- **Signature only** — no function bodies or implementation details
+- Input and output types
+- Any preconditions or postconditions in prose
+
+---
+
+### 2.4 Key Decisions (ADR) [REQUIRED]
+
+For each significant design decision, document an Architecture Decision Record (ADR):
+
+**Decision: [short title]**
+- **Context:** What problem or trade-off necessitates this decision
+- **Options considered:** List 2–3 alternatives
+- **Decision:** Which option was chosen
+- **Rationale:** Why this option was selected over the others
+- **Consequences:** Any trade-offs or implications of this choice
+
+Include at least one ADR per non-trivial design choice. Every ADR must capture a **choice between alternatives** — not a restatement of the requirements.
+
+If the feature changes a public API, wire protocol, database schema, or configuration contract, include a **Versioning & Backward Compatibility ADR**:
+- **Versioning strategy** — how old clients/schemas coexist with new (e.g., URL versioning, header negotiation, schema migration with rollback)
+- **Breaking change assessment** — what breaks if deployed without coordination
+- **Migration path** — steps for consumers to adopt the new version
+
+---
+
+### 2.5 Data Models [IF APPLICABLE]
+
+Show full type definitions (struct/class/interface/type alias) for all data structures involved in the feature. Include:
+
+- All fields with their types and a brief comment
+- Mark new types as `[NEW]`
+- Mark types that replace or supersede existing types as `[REMOVED: <OldTypeName>]`
+- Mark modified types explicitly
+
+Example format:
+
+```
+// [NEW] Represents a scheduled job entry
+JobEntry {
+  id:         string   // Unique identifier
+  name:       string   // Human-readable label
+  schedule:   string   // Cron expression
+  enabled:    boolean  // Whether the job is active
+  lastRunAt:  datetime // Timestamp of most recent execution, nullable
+}
+```
+
+Use the syntax natural to your project's language. The goal is precision and completeness, not adherence to any specific language.
+
+---
+
+### 2.6 Correctness Properties [REQUIRED]
+
+Define formal, verifiable properties that the implementation must satisfy. These serve as the specification for testing.
+
+**Format for each property:**
+
+```
+Property <N>: <Name>
+Category: <Equivalence | Absence | Round-trip | Propagation | Exclusion>
+Statement: For all <inputs/states>, <condition that must hold>
+Validates: Requirements <X.Y>
+```
+
+**Category definitions:**
+- **Equivalence** — Two computations that should produce the same result always do
+- **Absence** — A specific error, state, or condition never occurs
+- **Round-trip** — An operation followed by its inverse returns the original value
+- **Propagation** — A change in one place correctly flows through to dependent locations
+- **Exclusion** — Two conditions or states that must never both be true simultaneously
+
+**Rules:**
+- Every property must use the "For all" quantifier — no existential claims
+- Every property must include a `Validates: Requirements X.Y` reference
+- Every requirement from the requirements document must be covered by at least one property
+- Properties must be verifiable — not vague assertions
+- When referenced in tables (Coverage Matrix, Traceability Matrix), use the abbreviated form `CP-N` (e.g., `CP-1`, `CP-2`). The full form `Property N` is used only in definitions above.
+
+**Worked examples** of each category (Equivalence, Absence, Round-trip, Propagation, Exclusion) with §2.6 definitions and §2.8 test table entries: read `./templates/reference/correctness-properties-examples.md`.
+
+---
+
+### 2.7 Error Handling [REQUIRED]
+
+Enumerate all error scenarios and specify how each is detected and handled:
+
+| Scenario | Detection | Action |
+|----------|-----------|--------|
+| Description of what can go wrong | How the system detects this condition | What the system does in response |
+
+Cover edge cases, not just happy-path failures. Include:
+- Invalid or malformed inputs
+- Missing or unavailable dependencies (files, services, connections)
+- Concurrent or race conditions (if applicable)
+- Partial failure states
+
+---
+
+### 2.8 Testing Strategy [REQUIRED]
+
+#### Test Style Source
+
+Before specifying any tests, determine the test style source using the priority cascade defined in `./templates/task-plan.md` § Test Infrastructure Discovery. If `test_skill` is configured, delegate test specification to that skill and skip the rest of §2.8.
+
+**Output:** Include a `Test Style Source` block at the top of §2.8:
+
+```markdown
+**Test Style Source:** Tier <1|2|3>
+- <Evidence: skill name / reference test file paths / "no adjacent tests found">
+- <Key patterns to follow, if Tier 2>
+```
+
+All tests specified below MUST follow the patterns identified in the Test Style Source.
+
+#### Project Commands
+
+Copy the Verification Commands table from the requirements document (§2.8) into the design document. These exact commands will be used in the implementation plan for all test/build/lint/generate steps. If the requirements document lacks this table, read the exploration document's Build Tooling section or discover commands directly from `Makefile`, `Taskfile.yml`, or `package.json` scripts.
+
+```markdown
+**Project Commands:**
+| Action   | Command     |
+|----------|-------------|
+| Test     | `<command>` |
+| Build    | `<command>` |
+| Lint     | `<command>` |
+| Generate | `<command>` |
+```
+
+> The **Generate** row is required only if the project uses code generation. These commands are passed verbatim to the implementation phase.
+
+---
+
+#### Unit Tests
+
+Define the tests required to verify the design. Tag each test with the feature or property it validates.
+
+| Test | Description | Tags |
+|------|-------------|------|
+| `test_<name>` | What is being tested and what the expected outcome is | `Feature/<name>` |
+
+#### Property-Based Tests
+
+Use a property-based testing library appropriate for the project's language. For each correctness property defined in section 2.6, provide a corresponding property-based test:
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_<name>` | Property N from section 2.6 | What inputs are randomly generated | `Property/<N>` |
+
+**Rules:**
+- Every correctness property from section 2.6 must have a corresponding property-based test
+- If no property-based testing library is available for the project's language, substitute targeted unit tests covering representative inputs for each correctness property. Mark them `prop_<name>` and tag with `Property/<N>` as usual. In the Test Style Source block, note: "PBT unavailable — using targeted unit tests as substitute."
+- Every unit test must reference at least one `Feature/` or `Property/` tag
+- Tests are specified by **what they verify** — not by implementation
+
+---
+
+## Quality Control Checklist
+
+Before presenting the design document, verify:
+
+- [ ] Every requirement from the requirements document is covered by at least one correctness property
+- [ ] Every correctness property includes a `Validates: Requirements X.Y` reference
+- [ ] Every correctness property has a corresponding property-based test in section 2.8
+- [ ] Mermaid diagrams use correct colors: green for new, yellow for modified, default for unchanged
+- [ ] The "Files NOT Requiring Changes" table in section 2.3 is filled out
+- [ ] All data types referenced in interfaces are fully defined in section 2.5 (if applicable)
+- [ ] Error handling covers edge cases and partial failure states
+- [ ] Test Style Source (§2.8) is documented with tier and evidence
+- [ ] If the feature changes public APIs, database schemas, or protocols, a versioning/backward-compatibility ADR is present in §2.4
+- [ ] The document is self-contained: a reader unfamiliar with prior context can understand the design
+
+---
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Every requirement from the requirements document is traced to at least one correctness property.
+2. Every correctness property has a corresponding property-based test in §2.8.
+3. The "Files NOT Requiring Changes" table in §2.3 is non-empty.
+4. Mermaid diagrams use correct color coding: green (`#90EE90`) = new, yellow (`#FFD700`) = modified, default = unchanged.
+5. At least one ADR is present in §2.4. If changing API/schema/protocol contracts, a versioning ADR is included.
+6. Test Style Source is documented in §2.8 with tier selection and evidence.
+7. Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Antipatterns to Avoid
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Design.
diff --git a/.agents/skills/sdd/templates/docs-maintenance.md b/.agents/skills/sdd/templates/docs-maintenance.md
new file mode 100644
index 0000000..dedf4da
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs-maintenance.md
@@ -0,0 +1,209 @@
+# Documentation Workflows
+
+This file contains all documentation generation, staleness checking, and post-pipeline maintenance workflows. Referenced from `SKILL.md`.
+
+---
+
+## Standalone Documentation Workflow
+
+**Trigger:** the user requests documentation generation or update **without referring to a feature**. Examples:
+- *"Generate the project documentation"* / *"сгенерируй документацию"*
+- *"Update the docs"* / *"обнови документацию"*
+- *"Refresh AUTH.md"* / *"actualize the architecture doc"*
+
+**DO NOT** run `pipeline.sh init <feature>` for these requests. Documentation generation is a **standalone workflow** with its own state machine — `.spec/.docs-queue.kv` — driven by `pipeline.sh docs-*` commands.
+
+### Step 1: Detect intent
+
+| User intent | Command |
+|-------------|---------|
+| Bootstrap docs from scratch (no `<docs_dir>/` yet) | `pipeline.sh docs-init --all` |
+| Update stale docs only | `pipeline.sh docs-init --update` |
+| Regenerate specific docs (user named them, e.g. "regenerate AUTH and API") | `pipeline.sh docs-init auth api` |
+| User unsure | Run `pipeline.sh docs-check`. If `exists: false` → propose `--all`. If `stale: []` → propose `--update`. Wait for user confirmation. |
+
+### Step 2: Initialize the queue
+
+Run the chosen `docs-init` command. It writes `.spec/.docs-queue.kv` with the list of templates to process. If a queue already exists, the command errors — run `pipeline.sh docs-reset` first if you intend to start over.
+
+Then verify with `pipeline.sh docs-status` (returns JSON with `total`, `completed`, `pending`, `current`, `mode`).
+
+### Step 2.5: Evaluate Execution Strategy
+
+Documentation templates are **independent** (no shared state) and **heavy** (each requires reading dozens of source files). This makes parallelization safe and beneficial.
+
+**Default: SUBAGENT mode** — recommended whenever your toolset supports subagent dispatch (e.g. Claude Code `Task` tool, Cursor Composer, GitHub Copilot subagents, or equivalent).
+
+**Fallback: SEQUENTIAL mode** — used only when subagent dispatch is unavailable.
+
+**Skip mode selection if `total = 1`** — sequential always (overhead of dispatch not justified).
+
+#### Subagent mode (recommended default)
+
+You become the **controller**. Loop:
+
+1. Read `pipeline.sh docs-status` to see pending templates.
+2. **Dispatch up to 3 subagents in parallel** (rate-limit + controller context safety). Each subagent gets one template via this **context package**:
+   - Path to template file (e.g. `./templates/docs/auth.md`)
+   - `docs_dir` value (where to save output)
+   - `rules.docs` from `.spec/config.yaml` (if set)
+   - `context` from `.spec/config.yaml` (if set)
+   - One- or two-sentence summary of project stack (language, framework, key patterns)
+3. **Receive each subagent's report** — it should report which file(s) were created and where.
+4. **Verify** each generated file (controller, never delegated):
+   - File exists at the expected path
+   - **Line 1** matches `<!-- generated: YYYY-MM-DD, template: <name>.md -->`
+   - File is non-trivial (≥ 50 lines)
+5. **If verification fails**: re-dispatch with the verification error in the context package. Maximum **2 retries per template**, then escalate to the user.
+6. **If verification passes**: call `pipeline.sh docs-done <template>`.
+7. Repeat from step 1 until `docs-next` reports the queue is complete.
+8. Run `pipeline.sh docs-reset` to clear the queue.
+
+**Subagent rules:**
+- One subagent per template — never bundle multiple templates into one dispatch.
+- Subagents do NOT interact with `pipeline.sh` — only the controller does.
+- Up to 3 in parallel (no more — controller context fills up receiving multiple large outputs at once).
+- Verification is always performed by the controller.
+
+#### Sequential mode (fallback)
+
+Loop:
+
+1. Run `pipeline.sh docs-next` — it prints the next pending template name and path (tab-separated).
+2. Read the template file from the printed path.
+3. Read `rules.docs` and `context` from `.spec/config.yaml` (if set).
+4. Generate the documentation file(s) following the template's instructions. Save to `<docs_dir>/`. Verify line 1 has the `<!-- generated: ... -->` metadata.
+5. Run `pipeline.sh docs-done <template-name>`.
+6. Repeat until `docs-next` reports the queue is complete.
+
+**Fresh-chat hint:** after position 3, `docs-next` automatically prints a hint suggesting you start a fresh chat to avoid context exhaustion. The queue persists in `.spec/.docs-queue.kv` — in a new chat, run `pipeline.sh docs-status` to see your position and continue with `docs-next`.
+
+### Step 3: Auto-trigger from `docs-check`
+
+When `pipeline.sh docs-check` reports `stale: [...]` non-empty (during pre-pipeline check or on-demand), the workflow is:
+
+1. Inform the user: *"Found N stale doc(s): X, Y, Z. Initialize update queue? Say 'update docs' or 'skip'."*
+2. If user agrees → `pipeline.sh docs-init --update` → proceed to Step 2.5 (execution strategy).
+3. If user declines → no action. The user can run `pipeline.sh docs-init --update` later.
+
+The script does not auto-create the queue — explicit user consent is always required to begin a regeneration cycle.
+
+---
+
+## Documentation Context
+
+The skill supports a self-documenting mechanic via a project documentation directory (default: `.spec/`, configurable via `docs_dir` in `config.yaml`).
+
+> **Directory separation:** Project documentation files (README.md, ARCHITECTURE.md, DOMAIN.md, etc.) live in `<docs_dir>/` (default: `.spec/`). Pipeline phase artifacts (explore.md, requirements.md, design.md, etc.) live in `.spec/features/<feature>/`. **Never place project documentation into the feature directory or vice versa.**
+
+### Pre-pipeline check
+
+When running `pipeline.sh init <feature-name>`, before starting the Explore phase:
+
+1. Determine the docs directory: read `docs_dir` from `.spec/config.yaml`. If not set, default to `.spec`.
+2. Run `pipeline.sh docs-check` to determine if documentation exists and check freshness.
+3. If the docs directory **exists and contains `README.md`**:
+   - Read `README.md` for the documentation map
+   - Use available docs (`ARCHITECTURE.md`, `PACKAGES.md`, etc.) as supplementary context for ALL phases
+   - This is richer than `config.yaml` context and reduces the file-read budget in Explore phase
+   - Check the `stale` array in docs-check output. If stale files exist, suggest: *"Some docs are outdated (<file>: <N> days old). Regenerate before starting? Say 'update docs' or 'skip'."* If user agrees, follow the **Standalone Documentation Workflow** above (`pipeline.sh docs-init --update`).
+4. If the docs directory **does not exist**:
+   - Suggest to the user: *"Project documentation (<docs_dir>/) not found. I can generate it to better understand your codebase. Say 'generate docs' or 'skip'."*
+   - If user says **"generate docs"**: follow the **Standalone Documentation Workflow** above (`pipeline.sh docs-init --all`).
+   - If user says **"skip"**: proceed with the pipeline normally — documentation is NOT required
+   - **This is a soft suggestion, not a blocker.** The pipeline works without documentation.
+
+### Stale doc regeneration workflow (legacy ad-hoc)
+
+> **Prefer the Standalone Documentation Workflow** (top of this file) which uses the `docs-init --update` queue. The ad-hoc steps below remain as a reference for manual single-file regeneration.
+
+When `pipeline.sh docs-check` reports stale files (or the user requests a doc update), follow these steps:
+
+1. Parse the `docs-check` JSON output — read the `stale` array.
+2. For each stale file, extract the `template` field from its freshness metadata.
+3. Group stale files by template (one template may generate multiple files).
+4. For each affected template:
+   a. Read the template from `./templates/docs/<template>.md`.
+   b. Read the existing generated file(s) as baseline — preserve project-specific content where possible.
+   c. Regenerate following the template instructions.
+   d. Update the freshness metadata: `<!-- generated: YYYY-MM-DD, template: <name>.md -->`.
+5. Present updated files to the user for review before saving.
+6. **Never auto-overwrite.** Always confirm with the user.
+
+Use this lookup table to find the owner template for any generated file:
+
+| Generated file | Owner template |
+|----------------|----------------|
+| `README.md`, `agent-rules.md` | `bootstrap.md` |
+| `AGENTS.md` | `agents-index.md` |
+| `ARCHITECTURE.md`, `PACKAGES.md`, `DOMAIN.md`, `CODE_STYLE.md` | `core.md` |
+| `TOOLS.md`, `TESTING.md`, `FILES.md` | `development.md` |
+| `ERRORS.md` | `errors.md` |
+| `AUTH.md`, `OAUTH.md` | `auth.md` |
+| `DATABASE.md` | `database.md` |
+| `API.md` | `api.md` |
+| `DEPLOYMENT.md` | `deployment.md` |
+| `SECURITY.md` | `security.md` |
+| `CLIENTS.md` + per-client docs | `clients.md` |
+| `FEATURE_FLAGS.md` | `feature-flags.md` |
+| `BACKGROUND_JOBS.md` | `background-jobs.md` |
+| `<COMPONENT>.md` (infra) | `infrastructure.md` |
+| `CLI.md` | `cli.md` |
+| `STATE.md` | `state-management.md` |
+| `EVENTS.md` | `events.md` |
+| `COMPONENTS.md` | `components.md` |
+| `ROUTING.md` | `routing.md` |
+
+### Documentation generation templates
+
+Templates for generating project documentation are in `./templates/docs/`. Read the manifest (`./templates/docs/README.md`) to discover available templates. When generating docs:
+- Apply `rules.docs` from `config.yaml` (if present) as additional rules
+- Apply `context` from `config.yaml` as background knowledge
+- Each template is self-contained and generates one or more files in `<docs_dir>/`
+- **Freshness metadata**: when generating or updating any file in `<docs_dir>/`, MUST add `<!-- generated: YYYY-MM-DD, template: <template-name>.md -->` as the **first line** of the file (before the title). This enables `pipeline.sh docs-check` to track documentation age and detect stale files.
+- **Freshness metadata validation**: after saving a generated doc, verify that line 1 matches the pattern `<!-- generated: YYYY-MM-DD, template: <name>.md -->`. If the metadata is missing or malformed, fix it immediately — `docs-check` will silently skip files without valid metadata.
+- **Content-aware staleness**: `pipeline.sh docs-check` uses scope metadata from templates (`<!-- scope: ... -->` first line) combined with `git log --since=<generated_date>` to determine staleness. A doc is marked stale only if (a) files matching its template's scope patterns were changed since generation **and** (b) the doc exceeds the freshness threshold. Docs whose scope shows no changes remain fresh regardless of age. If a template has no scope line, the check falls back to pure age-based staleness. The JSON output includes a `scope_changed` field (`true`/`false`/`null`) per file.
+
+---
+
+## Documentation Maintenance
+
+After the pipeline reaches `phase=done` and artifacts are published, check if project documentation needs updating.
+
+### Step 1: Identify affected docs
+
+Read the design document §2.3 ("Files Requiring Changes" table). Match changed file paths against this pattern table:
+
+| Changed file pattern | Affected doc | Owner template |
+|----------------------|-------------|----------------|
+| `*domain*`, `models/*`, `types/*`, `*entity*` | `DOMAIN.md` | `core.md` |
+| new directory under `internal/`, `pkg/` | `PACKAGES.md` | `core.md` |
+| `cmd/*`, new service, layer changes | `ARCHITECTURE.md` | `core.md` |
+| `*_test*`, `__tests__/`, test config files | `TESTING.md` | `development.md` |
+| `Makefile`, `Taskfile`, `scripts/*`, CI tool changes | `TOOLS.md` | `development.md` |
+| `*error*`, `*errs*`, error codes, error types | `ERRORS.md` | `errors.md` |
+| `*auth*`, `*oauth*`, `*login*`, `*session*` | `AUTH.md` / `OAUTH.md` | `auth.md` |
+| `migrations/*`, `schema*`, `*_repo*`, `*_store*` | `DATABASE.md` | `database.md` |
+| `*handler*`, `*route*`, `*endpoint*`, `*.proto`, `openapi*` | `API.md` | `api.md` |
+| `Dockerfile`, `.github/workflows/*`, `k8s/*`, `docker-compose*` | `DEPLOYMENT.md` | `deployment.md` |
+| `*redis*`, `*kafka*`, `*traefik*`, `*prometheus*`, `*nats*` | `<COMPONENT>.md` | `infrastructure.md` |
+| `*client*`, `*frontend*`, `*mobile*` | `CLIENTS.md` | `clients.md` |
+| `*cors*`, `*csrf*`, `*rate_limit*`, `*security*`, `*helmet*` | `SECURITY.md` | `security.md` |
+| `*feature_flag*`, `*toggle*`, `*experiment*` | `FEATURE_FLAGS.md` | `feature-flags.md` |
+| `*worker*`, `*job*`, `*queue*`, `*cron*`, `*scheduler*` | `BACKGROUND_JOBS.md` | `background-jobs.md` |
+| new code style rule, naming convention change | `CODE_STYLE.md` | `core.md` |
+| `cmd/*`, `cli/*`, `commands/*`, `*cobra*`, `*clap*`, `*click*` | `CLI.md` | `cli.md` |
+| `*store*`, `*redux*`, `*bloc*`, `*provider*`, `*zustand*`, `*pinia*` | `STATE.md` | `state-management.md` |
+| `*event*`, `*messaging*`, `*pubsub*`, `*subscriber*`, `*producer*`, `*consumer*` | `EVENTS.md` | `events.md` |
+| `components/*`, `ui/*`, `design-system/*`, `*widget*`, `atoms/*`, `molecules/*` | `COMPONENTS.md` | `components.md` |
+| `routes/*`, `router/*`, `pages/*`, `screens/*`, `navigation/*` | `ROUTING.md` | `routing.md` |
+
+### Step 2: Filter and suggest
+
+1. Collect unique affected docs from the pattern matches.
+2. **Filter**: only suggest docs that already exist in `<docs_dir>/`. Do not suggest creating new docs post-pipeline.
+3. Present to user: *"This feature touched auth and database files. Update AUTH.md and DATABASE.md? Say 'update docs' or 'skip'."*
+4. If user says **"update docs"**: for each affected doc, read its owner template from `./templates/docs/`, regenerate the doc, update freshness metadata.
+5. If user says **"skip"**: done, no action.
+6. If the docs directory does not exist at all, suggest full generation (same as Pre-flight Checklist step 3).
+7. **Never auto-update documentation.** Always ask the user first.
diff --git a/.agents/skills/sdd/templates/docs/README.md b/.agents/skills/sdd/templates/docs/README.md
new file mode 100644
index 0000000..6239849
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/README.md
@@ -0,0 +1,91 @@
+# Documentation Templates — Manifest
+
+This directory contains prompt templates for generating project documentation in the `.spec/` directory (configurable via `docs_dir` in `config.yaml`).
+
+> **IMPORTANT — Output directory:** All files generated by these templates go to `<docs_dir>/` (default: `.spec/`), **NOT** to `.spec/features/<feature>/`. The features directory is for pipeline phase artifacts only. These are separate directories with separate purposes.
+
+Each template is a self-contained prompt that instructs the AI agent to analyze the project and generate specific documentation files.
+
+## Available Templates
+
+Execution order: **Bootstrap → Core → Domain-Specific**. Run Bootstrap templates first to create the index, then Core for fundamental docs, then Domain-Specific as needed.
+
+| Template | Stage | Generates | When to Use |
+|----------|-------|-----------|-------------|
+| `bootstrap.md` | Bootstrap | `README.md`, `agent-rules.md` | **Run first** — creates the root index and agent rules |
+| `agents-index.md` | Bootstrap | `AGENTS.md` (root) | First-time setup — creates the entry point that explains `.spec/` to agents |
+| `core.md` | Core | `ARCHITECTURE.md`, `PACKAGES.md`, `DOMAIN.md`, `CODE_STYLE.md` | First-time setup or after significant architectural changes |
+| `development.md` | Core | `TOOLS.md`, `TESTING.md`, `FILES.md` | First-time setup or after tooling/testing convention changes |
+| `errors.md` | Core | `ERRORS.md` | If the project defines custom error types, error codes, or error mapping |
+| `auth.md` | Domain | `AUTH.md` or `OAUTH.md` | If the project has authentication (OAuth, email+password, API keys, etc.) |
+| `database.md` | Domain | `DATABASE.md` | If the project uses SQL/NoSQL databases |
+| `api.md` | Domain | `API.md` | If the project exposes REST/gRPC/GraphQL API |
+| `deployment.md` | Domain | `DEPLOYMENT.md` | If the project has Dockerfile, CI/CD, k8s, or PaaS config |
+| `infrastructure.md` | Domain | One `<COMPONENT>.md` per infra component | If the project has Redis, Kafka, Traefik, observability, etc. |
+| `clients.md` | Domain | `CLIENTS.md` + per-client docs | If the project has frontend, mobile, Telegram, CLI clients |
+| `security.md` | Domain | `SECURITY.md` | If the project needs a security audit (input validation, CORS, secrets, OWASP) |
+| `feature-flags.md` | Domain | `FEATURE_FLAGS.md` | If the project uses feature flags, A/B testing, or gradual rollouts |
+| `background-jobs.md` | Domain | `BACKGROUND_JOBS.md` | If the project has background workers, cron jobs, task queues, or async processing |
+| `cli.md` | Domain | `CLI.md` | If the project is a CLI application (commands, flags, config, exit codes) |
+| `state-management.md` | Domain | `STATE.md` | If the project uses state management (Redux, Zustand, BLoC, Pinia, MobX, etc.) |
+| `events.md` | Domain | `EVENTS.md` | If the project uses event-driven patterns (Kafka, NATS, domain events, pub/sub) |
+| `components.md` | Domain | `COMPONENTS.md` | If the project has a UI component library or design system |
+| `routing.md` | Domain | `ROUTING.md` | If the project has client-side routing, navigation guards, or page-based structure |
+
+## Usage
+
+The agent reads this manifest to discover available templates when:
+1. **Pre-pipeline check**: `.spec/` directory is missing — agent offers to generate it
+2. **Post-pipeline update**: feature touched files that affect documentation — agent offers targeted regeneration
+
+The agent selects the relevant template(s), reads them, and follows the instructions to generate documentation.
+
+### Multi-Service / Monorepo Projects
+
+When the project contains multiple services, languages, or independently deployable components:
+- **One `.spec/` per repository, not per service.** Documentation is scoped to the repository level.
+- **Core templates** (`core.md`, `development.md`) cover the overall architecture. Use sections within generated files to describe per-service specifics (e.g., `ARCHITECTURE.md` has a section per service).
+- **Domain templates** (`api.md`, `database.md`, etc.) may be run multiple times — once per service that has the relevant concern. Name generated files with a service prefix if needed (e.g., `API-gateway.md`, `API-users.md`).
+- **Template selection is per-concern, not per-service.** Don't generate `DEPLOYMENT.md` for a service with no deployment config.
+
+## Adding a New Template
+
+To add documentation for a new topic (e.g., AUTH.md, OBSERVABILITY.md, CACHING.md):
+
+1. Create a new file `<topic>.md` in this directory
+2. Follow the structure convention below
+3. Add an entry to the "Available Templates" table above
+
+### Structure Convention
+
+Every template file must follow this structure:
+
+```markdown
+# <Topic> Documentation Template
+
+## What This Generates
+<List of files this template creates, with brief descriptions>
+
+## Instructions
+<Detailed prompt for the AI agent>
+
+### File 1: .spec/<FILENAME>.md
+<Structure and content requirements for this file>
+
+### File 2: .spec/<FILENAME>.md (if multiple)
+<Structure and content requirements for this file>
+
+## General Rules
+<Shared rules for all files generated by this template>
+```
+
+### Rules for template authors:
+- **Language**: English only
+- **Language-neutral examples**: Templates use generic or Go-like examples for illustration, but generated documentation MUST use actual code from the project in its real language/framework. Agents should adapt patterns, naming conventions, and idioms to match the project's tech stack.
+- **Examples**: Use generic placeholders, not project-specific code
+- **Self-contained**: Each template must be usable independently
+- **Real code only**: Templates must instruct the agent to use examples from actual project source, not invented ones
+- **Skip if absent**: If a topic doesn't apply to the project, the agent should skip it (not generate empty docs)
+- **Freshness metadata**: Instruct the agent to add `<!-- generated: YYYY-MM-DD, template: <name>.md -->` as the first line of every generated file. This is parsed by `pipeline.sh docs-check` for staleness detection.
+- **Single owner**: Each piece of data must live in exactly one `.spec/` file. If another template already owns a topic, add a one-line pointer (e.g., "See `ERRORS.md`") instead of duplicating content.
+- **Scope metadata**: Every template must include `<!-- scope: pattern1, pattern2, ... -->` as the **first line** (before the title). Patterns are glob expressions matching source files relevant to the template's topic. `pipeline.sh docs-check` reads these patterns to perform content-aware staleness detection — a doc is only marked stale if files matching its scope were actually changed since the last generation. Example: `<!-- scope: **/migrations/*, **/schema*, **/*repo*, **/*store* -->`.
diff --git a/.agents/skills/sdd/templates/docs/agents-index.md b/.agents/skills/sdd/templates/docs/agents-index.md
new file mode 100644
index 0000000..cb63aec
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/agents-index.md
@@ -0,0 +1,74 @@
+<!-- scope: .copilot/*, .cursor/*, .github/copilot* -->
+# Agents Index Documentation Template
+
+## What This Generates
+
+- `AGENTS.md` in the project root — an instruction file for AI agents (Copilot, Cursor, Windsurf, Claude, etc.) explaining how to use the `.spec/` documentation directory.
+
+## Instructions
+
+Create `AGENTS.md` in the project root. This file instructs AI agents on how to work with the `.spec/` directory in this repository.
+
+The file must contain the following sections:
+
+### Section 1: What is `.spec/`
+
+Explain that `.spec/` is a project documentation directory optimized for AI agent (LLM) consumption. It contains:
+- Structured descriptions of architecture, packages, and domain
+- Code and testing conventions
+- Infrastructure and tooling descriptions
+- Agent rules (`agent-rules.md`)
+
+Purpose: give the agent full project context without having to read the entire source code.
+
+### Section 2: How to Use (for agents)
+
+Instructions for the AI agent:
+- When starting work on a project — read `.spec/README.md` for the documentation map
+- Before modifying code — read the relevant document from `.spec/` (e.g., before modifying API — read `ARCHITECTURE.md` and `CODE_STYLE.md`)
+- Always follow rules from `agent-rules.md`
+- If a document appears outdated — suggest an update
+
+### Section 3: File Structure Convention
+
+Describe file naming conventions in `.spec/`:
+- `README.md` — index of all documents, Quick Facts, project structure, ports, commands
+- `agent-rules.md` — mandatory rules for the agent (code style, naming, error handling)
+- `UPPER_CASE.md` — topical documents (`ARCHITECTURE.md`, `TESTING.md`, etc.)
+- `skills/` — directory for agent skills (custom scripts)
+- `workflows/` — directory for agent workflows
+- `prompts/` — prompts for (re)generating documentation
+
+### Section 4: Document Categories
+
+List the recommended document categories:
+- **Core**: Architecture, Packages, Domain, Code Style
+- **Development**: Tools, Testing, Files/Storage
+- **Auth & Security**: OAuth, API Keys, Permissions
+- **Infrastructure**: Observability, Caching, Proxy, Queues, Leader Election
+- **Clients**: Frontend apps, Mobile, Bots
+
+### Section 5: How to Maintain
+
+Rules for keeping documentation current:
+- When adding a new component — update or create the corresponding document
+- When changing architecture — update `ARCHITECTURE.md`
+- When adding a dependency — update `PACKAGES.md`
+- `README.md` must always reflect the current list of documents
+- Documents must contain code examples from the actual project, not abstract ones
+
+### Section 6: How to Add New Document
+
+Steps for adding a new document:
+1. Create a file `TOPIC_NAME.md` in `.spec/`
+2. Use this structure: title → overview → architectural diagram (ASCII) → details → code examples → configuration → testing → key files
+3. Add a link in `README.md` under the appropriate category
+4. If the topic is project-specific — use real code examples
+
+## General Rules
+
+- Format: Markdown with ASCII diagrams, tables, fenced code blocks with language tags
+- Style: concise, structured, no filler. Optimized for quick scanning.
+- Language: English
+- All code examples must come from the actual project source, not invented
+- If a section does not apply to the project, omit it
diff --git a/.agents/skills/sdd/templates/docs/api.md b/.agents/skills/sdd/templates/docs/api.md
new file mode 100644
index 0000000..61d7f12
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/api.md
@@ -0,0 +1,156 @@
+<!-- scope: **/routes/*, **/handlers/*, **/api/*, *.proto, **/openapi* -->
+# API Documentation Template
+
+## What This Generates
+
+- `.spec/API.md` — API endpoint reference, conventions, middleware, and error format
+
+## Instructions
+
+You are a technical documentarian. Create API documentation for the project in the `.spec/` directory.
+Analyze: route definitions, handler files, middleware chain, proto/OpenAPI specs, request/response types, error handling.
+
+### Step 1: Identify API Surface
+
+Determine the API type(s):
+- **REST**: route files, handler functions, HTTP methods
+- **gRPC**: `.proto` files, generated code, service definitions
+- **GraphQL**: schema files, resolvers
+- **WebSocket**: upgrade handlers, event definitions
+
+For each API surface, identify:
+- Router / framework (e.g., `chi`, `gin`, `echo`, `Express`, `FastAPI`, `net/http`)
+- Base path / port
+- Authentication method (Bearer token, API key, cookie)
+
+### Step 2: Create .spec/API.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: API type + framework
+- Base URL pattern (e.g., `http://localhost:8080/api/v1`)
+- Authentication method summary
+
+##### 2. Middleware Stack
+
+Ordered list of middleware in the request processing pipeline:
+| Order | Middleware | Purpose |
+|-------|-----------|---------|
+| 1 | Request ID | Assigns unique ID to each request |
+| 2 | Logger | Structured request logging |
+| 3 | Recovery | Panic recovery |
+| 4 | Auth | Token validation |
+| 5 | ... | ... |
+
+Determine order from the actual router setup code.
+Note which middleware is global vs route-specific.
+
+##### 3. Endpoint Reference
+
+Group endpoints by resource/domain:
+
+**Users**
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/api/v1/users` | No | Create user |
+| GET | `/api/v1/users/:id` | Yes | Get user by ID |
+
+For each group, include:
+- All endpoints with method, path, auth requirement, description
+- Source file reference (handler file path)
+
+If there are many endpoints (>20), create a summary table first, then detail sections per resource.
+
+##### 4. Request / Response Conventions
+
+Describe the standard patterns:
+- **Request envelope**: is there a wrapper? (`{"data": ...}` vs flat)
+- **Response envelope**: standard response format
+  ```json
+  {
+    "data": { ... },
+    "error": null
+  }
+  ```
+- **Pagination**: pattern used (offset/limit, cursor, page/per_page)
+  - Request parameters
+  - Response metadata (`total`, `next_cursor`, `has_more`)
+- **Sorting**: parameter name and format (e.g., `?sort=name,-created_at`)
+- **Filtering**: parameter patterns (e.g., `?status=active&role=admin`)
+
+Code examples from the actual project.
+
+##### 5. Status Codes & Error Format
+
+**Standard status codes used:**
+| Status | When Used |
+|--------|-----------|
+| 200 | Successful response |
+| 201 | Resource created |
+| 400 | Validation error |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found |
+| 500 | Internal error |
+
+**Error response format:**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "email is required",
+    "details": [...]
+  }
+}
+```
+
+Show the actual error response structure from the project.
+Reference the error mapping code (where domain errors become HTTP errors).
+
+##### 6. Versioning Strategy (if applicable)
+- How API versions are specified: URL prefix (`/v1/`), header (`Accept-Version`), content type
+- Current version(s)
+- Deprecation policy
+
+##### 7. Rate Limiting (if applicable)
+- Rate limit values (requests per second/minute)
+- Rate limit headers returned (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)
+- Per-user vs per-IP vs per-API-key
+- Configuration reference
+
+##### 8. Proto / OpenAPI / GraphQL Schema (if applicable)
+
+For **gRPC**:
+- `.proto` file locations
+- Service definitions (list of RPCs per service)
+- Code generation command
+- Client stub usage example
+
+For **OpenAPI**:
+- Spec file location (e.g., `api/openapi.yaml`)
+- How spec is generated (manual vs auto-generated)
+- Swagger UI URL (if served)
+- Code generation command (if applicable)
+
+For **GraphQL**:
+- Schema file location
+- Key queries and mutations
+- Resolver structure
+
+##### 9. Validation
+- Validation library / approach (struct tags, middleware, manual)
+- Where validation happens (handler, middleware, domain layer)
+- Common validation rules used
+- Custom validators (if any)
+
+Code example of a validated request from the project.
+
+## General Rules
+
+- Language: English
+- All endpoints must come from actual route definitions, not assumed
+- Request/response examples must use realistic but non-sensitive data
+- If the project has no API (library, CLI-only), do not generate this file
+- Group endpoints logically by resource, not by HTTP method
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/auth.md b/.agents/skills/sdd/templates/docs/auth.md
new file mode 100644
index 0000000..afd5d8c
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/auth.md
@@ -0,0 +1,142 @@
+<!-- scope: **/*auth*, **/*oauth*, **/*login*, **/*session* -->
+# Auth Documentation Template
+
+## What This Generates
+
+- `.spec/AUTH.md` (or `.spec/OAUTH.md` if the project primarily uses OAuth) — authentication and authorization documentation
+
+## Instructions
+
+You are a technical documentarian. Create auth/authorization documentation for the project in the `.spec/` directory.
+Analyze: OAuth adapters, JWT/PASETO/session middleware, login handlers, DB migrations with auth fields.
+
+### Step 1: Identify Authentication Mechanisms
+
+Determine which authentication mechanisms exist in the project:
+- OAuth2 providers (Google, GitHub, Apple, Yandex, Facebook, Twitter, etc.)
+- Email + Password (classic registration)
+- Telegram Login / Mini App initData
+- API Keys
+- SSO (SAML, OIDC)
+- Magic Links
+- 2FA / MFA
+
+### Step 2: Create the Document
+
+Create `.spec/OAUTH.md` if OAuth is the primary mechanism, or `.spec/AUTH.md` otherwise.
+
+#### Structure:
+
+##### 1. Supported Providers / Methods
+
+Table:
+| Provider/Method | Status | Validation Method |
+|-----------------|--------|-------------------|
+| Google | Ready / TODO | ID Token / API call / ... |
+
+Statuses: Ready, TODO, In Progress
+
+##### 2. Architecture (Flow)
+
+ASCII diagram of the authentication flow:
+```
+Frontend → obtains token → sends to backend → validation → session creation → response
+```
+
+Show the full flow from user click to session receipt.
+If multiple flows exist (OAuth, email+password, Telegram) — show a unified diagram.
+
+##### 3. User Lookup / Creation Logic
+
+Flowchart (Mermaid or ASCII):
+- Token received → validation
+- Search by provider_id → found? → login
+- Search by email → found? → account linking
+- Not found → create new user
+- Create session → return token
+
+##### 4. Account Linking (if applicable)
+Description of the mechanism for linking OAuth accounts to an existing user.
+
+##### 5. Authorization (if applicable)
+
+Permission and access control model:
+- Authorization model type: RBAC / ABAC / scope-based / custom
+- Permission matrix table:
+
+| Role | Action | Resource | Allowed |
+|------|--------|----------|---------|
+| admin | * | * | Yes |
+| user | read | own profile | Yes |
+
+- Where authorization checks happen (middleware, guard, decorator, in-handler)
+- Code reference: file path and key function/method for permission checking
+- How roles/permissions are stored (DB table, JWT claims, config)
+
+##### 6. Session Management (if applicable)
+
+Session storage and lifecycle:
+- Storage mechanism: database / Redis / JWT (stateless) / cookie-based
+- Session model (fields: id, user_id, token, expires_at, etc.)
+- Session lifecycle:
+  1. Creation (on login / OAuth callback)
+  2. Validation (on each request)
+  3. Refresh (token rotation)
+  4. Revocation (logout, password change)
+- Concurrent session policy: allow multiple / single session / limit per device
+- Session cleanup: TTL, cron job, on-demand
+
+##### 7. Token Lifecycle (if applicable)
+
+Token flow and management:
+- Token types used: access token, refresh token, ID token, API key
+- Token format: JWT / PASETO / opaque / custom
+- Token claims / payload structure
+- Issuance flow: what triggers token creation
+- Rotation strategy: how refresh tokens are rotated
+- Revocation mechanism: blocklist, DB flag, Redis TTL
+- Token storage on client side (see also CLIENTS.md if applicable)
+
+##### 8. Account Operations (if applicable)
+
+User account management flows:
+- **Password reset**: flow diagram (request → email → token → new password), token TTL, rate limiting
+- **Email change**: verification flow, old email notification
+- **Account deletion / deactivation**: soft delete vs hard delete, data retention, cascade rules
+- **Profile update**: which fields are mutable, validation rules
+
+For each flow: endpoint reference, code path, edge cases.
+
+##### 9. Configuration
+Configuration example (config.yml, .env, environment variables).
+Do not include real secrets — use placeholders.
+
+##### 10. Per-Provider / Per-Method Implementation
+
+For each provider/method:
+- **File**: path to implementation file
+- **Code**: key fragment (token validation, API call)
+- **Specifics**: what distinguishes this provider
+
+##### 11. Tracing (if applicable)
+Table of tracing spans for auth operations:
+| Span | Description |
+|------|-------------|
+
+##### 12. Adding a New Provider / Method
+Step-by-step guide (numbered list):
+1. Create adapter (code example)
+2. Add configuration
+3. Register in main
+4. DB migration (if needed)
+5. Update handler
+6. Update API validation
+
+## General Rules
+
+- Language: English
+- Do not create sections for providers/methods that do not exist in the project
+- Replace real secrets with placeholders
+- If the project only has email+password without OAuth — name the file `AUTH.md` and adapt the structure
+- All code examples must come from the actual project
+- After creating, update `.spec/README.md`: add a link under Auth & Security
diff --git a/.agents/skills/sdd/templates/docs/background-jobs.md b/.agents/skills/sdd/templates/docs/background-jobs.md
new file mode 100644
index 0000000..2d37e3e
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/background-jobs.md
@@ -0,0 +1,107 @@
+<!-- scope: **/*worker*, **/*job*, **/*queue*, **/*cron* -->
+# Background Jobs Documentation Template
+
+## What This Generates
+
+- `.spec/BACKGROUND_JOBS.md` — documents the background job system, job inventory, retry strategy, and scaling approach
+
+## Instructions
+
+Analyze the project to identify any background job or async task processing. Look for:
+- Job frameworks (Sidekiq, Celery, Temporal, Asynq, Bull, Hangfire, Faktory)
+- Custom worker implementations (goroutines + channels, threads + queues)
+- Cron/scheduler configurations (crontab, systemd timers, Kubernetes CronJobs, `robfig/cron`)
+- Message queue consumers (Kafka consumers, RabbitMQ subscribers, NATS workers, SQS listeners)
+
+If no background job system is found, **skip this template entirely** — do not generate an empty document.
+
+### File: .spec/BACKGROUND_JOBS.md
+
+#### Structure:
+
+##### 1. Overview
+- **System**: which job framework or custom implementation is used
+- **Transport**: underlying queue/broker (Redis, RabbitMQ, Kafka, PostgreSQL, in-memory)
+- **Architecture pattern**: pull-based (workers poll queue) or push-based (broker dispatches)
+- **Entry point**: where workers are started (separate binary, same process, sidecar)
+
+##### 2. Job Inventory
+
+Table of all registered jobs:
+
+| Job Name | Trigger | Frequency / Event | Timeout | Retry | DLQ | Priority |
+|----------|---------|-------------------|---------|-------|-----|----------|
+| `SendWelcomeEmail` | Event: user.created | On event | 30s | 3× | ✅ | normal |
+| `CleanupExpiredSessions` | Cron | Every hour | 5m | 1× | ❌ | low |
+| `ProcessPayment` | Event: order.placed | On event | 60s | 5× exponential | ✅ | high |
+
+Trigger types: `Cron` (scheduled), `Event` (message/webhook), `Manual` (API/CLI), `Cascade` (triggered by another job).
+
+##### 3. Architecture
+
+ASCII diagram showing the job processing flow:
+
+```
+Producer → Queue/Broker → Worker Pool → Result Store
+                ↓ (on failure)
+           Dead Letter Queue → Alert
+```
+
+For each component:
+- **Producer**: which services enqueue jobs, how (SDK call, publish message, HTTP endpoint)
+- **Queue**: queue names, partitioning, priority levels
+- **Worker**: concurrency model (process per job, thread pool, goroutine pool), startup configuration
+- **Result**: where job results are stored (database, cache, nowhere), how callers check completion
+
+##### 4. Retry & Error Handling
+- **Retry policy**: max retries per job, backoff strategy (fixed, exponential, custom)
+- **Backoff configuration**: initial delay, multiplier, max delay, jitter
+- **Dead letter queue (DLQ)**: which jobs have DLQ, how DLQ is monitored, manual replay procedure
+- **Idempotency**: which jobs MUST be idempotent, how idempotency is enforced (unique keys, deduplication)
+- **Error classification**: transient errors (retry) vs permanent errors (DLQ), how the system distinguishes them
+- **Poison messages**: how malformed/unprocessable messages are handled
+
+##### 5. Concurrency & Ordering
+- **Worker count**: how many workers per queue, how it's configured
+- **Parallelism**: can the same job type run in parallel? Are there mutex/lock constraints?
+- **Ordering guarantees**: FIFO per queue? Per partition key? No guarantees?
+- **Rate limiting**: are any jobs rate-limited (e.g., email sending, API calls)?
+- **Distributed locking**: if jobs use locks, which lock mechanism (Redis, DB advisory locks, etcd)
+
+##### 6. Monitoring
+- **Metrics**: which job metrics are collected
+  - Queue depth (pending jobs)
+  - Processing duration (p50, p95, p99)
+  - Success/failure rate
+  - DLQ size
+- **Dashboards**: Grafana/Datadog dashboard links or query examples
+- **Alerting**: alert rules (e.g., "DLQ > 100", "queue depth > 1000 for 5min", "job duration > 2× p99")
+- **Logging**: what is logged per job execution (start, end, duration, error, retry count)
+
+##### 7. Scaling
+- **Horizontal scaling**: how to add more workers (replicas, autoscaling, manual)
+- **Queue partitioning**: are queues partitioned? By what key?
+- **Priority queues**: which priority levels exist, how workers consume them (weighted, strict)
+- **Backpressure**: what happens when the queue is full (block producer, drop, overflow queue)
+- **Resource limits**: CPU/memory per worker, connection pool sizing
+
+##### 8. Development
+Step-by-step guide to add a new background job:
+1. Define job payload struct/schema
+2. Implement handler function
+3. Register handler with the worker
+4. Create producer (enqueue function)
+5. Add retry/DLQ configuration
+6. Write tests (unit + integration)
+7. Add monitoring (metrics, alerts)
+8. Deploy (worker restart required?)
+
+- **Local testing**: how to run workers locally, how to enqueue test jobs
+- **Job simulation**: how to trigger a job manually for debugging (CLI, admin API, console)
+
+## General Rules
+
+- Language: English
+- Use actual job names, queue names, and code references from the project — do not invent examples
+- If no background job system exists, do not generate this file
+- For message queue consumers that are part of the infrastructure layer, defer to `infrastructure.md` for broker-level docs (connection, topology). This template owns the job-level details (handler, retry, monitoring).
diff --git a/.agents/skills/sdd/templates/docs/bootstrap.md b/.agents/skills/sdd/templates/docs/bootstrap.md
new file mode 100644
index 0000000..1d43fdf
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/bootstrap.md
@@ -0,0 +1,126 @@
+<!-- scope: * -->
+# Bootstrap Documentation Template
+
+## What This Generates
+
+- `.spec/README.md` — project documentation index (Quick Facts, Project Structure, Running, Ports, Key Interfaces, Adding Features)
+- `.spec/agent-rules.md` — mandatory rules for AI agents working on this project (Code Style, Naming, Error Handling, Testing, Dependencies, Formatting)
+
+**Run this template first** — it creates the root index that all other templates reference and update.
+
+## Instructions
+
+You are a technical documentarian. Your task is to analyze the current project and create the foundational documentation in the `.spec/` directory for use by AI agents.
+
+### Step 1: Project Analysis
+
+Study the project structure. Pay attention to:
+- Root files: `go.mod`, `package.json`, `requirements.txt`, `Cargo.toml`, `pom.xml`, etc. → determine language and framework
+- Directory structure: `cmd/`, `src/`, `internal/`, `pkg/`, `app/`, `lib/`, etc.
+- Configuration: `docker-compose.yml`, `Makefile`, `Taskfile.yml`, `.github/`, CI/CD
+- API: proto files, OpenAPI/Swagger, GraphQL schemas
+- Tests: `*_test.go`, `*.test.ts`, `test/`, `tests/`, `spec/`
+- Infrastructure: `Dockerfile`, `kubernetes/`, `terraform/`, `configs/`
+- Client applications: `clients/`, `frontend/`, `web/`, `mobile/`
+- Dependencies: `go.sum`, `package-lock.json`, `poetry.lock`, etc.
+
+### Step 2: Create .spec/README.md
+
+Create `.spec/README.md` with the following structure:
+
+#### Header
+```markdown
+# {Project Name} Documentation
+This folder contains documentation to help LLMs and developers quickly understand the project context.
+```
+
+#### Documentation Index
+Group documents by category. Use only categories relevant to the project:
+
+- **Core** — Architecture, Packages, Domain, Code Style (always needed)
+- **Development** — Tools, Testing, Files/Storage (always needed)
+- **Auth & Security** — if the project has OAuth, JWT, API keys
+- **Infrastructure** — if the project has Docker, monitoring, caching, queues
+- **Clients** — if the project has frontend, mobile apps, bots
+
+For each document, add a link: `- [DOC_NAME.md](./DOC_NAME.md) — brief description`
+
+IMPORTANT: If documents have not been created yet, mark them as "TODO" or add a note that they will be created later.
+
+#### Quick Facts
+Table of key project technologies:
+
+```markdown
+| Aspect | Technology |
+|--------|------------|
+| **Language** | ... |
+| **Architecture** | ... |
+| **API** | ... |
+| **Database** | ... |
+| ...    | ...        |
+```
+
+Fill in only what actually exists in the project. Do not guess.
+
+#### Project Structure
+ASCII tree of main directories (1-2 levels deep) with comments:
+
+```
+project/
+├── cmd/           # Entry points
+├── internal/      # Private packages
+├── ...
+```
+
+#### Running
+Key commands for running, testing, and building. Source from Makefile/Taskfile/package.json.
+
+#### Ports
+Port table (if server components exist). Determine from docker-compose.yml, configs, code.
+
+#### Key Interfaces / Entry Points
+Main interfaces or application entry points.
+
+#### Adding New Features
+Brief guide: how to add a new endpoint / page / module.
+
+### Step 3: Create .spec/agent-rules.md
+
+Create `.spec/agent-rules.md` with rules for AI agents specific to this project.
+
+Determine rules based on:
+- Programming language (Go → Effective Go, Python → PEP8, TypeScript → project standards)
+- Linter config (`.golangci.yml`, `.eslintrc`, `.prettierrc`, `pyproject.toml`)
+- Existing code (naming patterns, error handling, file structure)
+
+Required sections:
+- **Code Style** — main style rules
+- **Naming Conventions** — variable, function, and file naming
+- **Error Handling** — project's error handling pattern
+- **Testing** — testing conventions (framework, coverage, patterns)
+- **Dependencies** — how to manage dependencies
+- **Formatting** — formatting and linting
+
+Each rule: 1-2 lines. No filler.
+
+### Step 4: Output Recommendations
+
+After creating files, output a list of recommended documents to generate:
+
+```
+Recommended documents for generation:
+1. ARCHITECTURE.md — [reason: detected Clean Architecture / MVC / ... pattern]
+2. PACKAGES.md — [reason: X packages in the project]
+3. ...
+```
+
+Include only documents for which there is real content in the project.
+
+## General Rules
+
+- Language: English
+- Use only facts from actual code — do not invent
+- If something is unclear — mark as "TODO: requires clarification"
+- Format: Markdown, ASCII diagrams, tables
+- Style: concise, no filler
+- After creating files, the README.md should serve as the map for all future documentation
diff --git a/.agents/skills/sdd/templates/docs/cli.md b/.agents/skills/sdd/templates/docs/cli.md
new file mode 100644
index 0000000..2e9f5ac
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/cli.md
@@ -0,0 +1,146 @@
+<!-- scope: **/cmd/*, **/cli/*, **/commands/*, **/flags/* -->
+# CLI Documentation Template
+
+## What This Generates
+
+- `.spec/CLI.md` — command tree, flags, arguments, configuration, exit codes, I/O contracts
+
+## Instructions
+
+You are a technical documentarian. Create CLI application documentation for the project in the `.spec/` directory.
+Analyze: entry point files, command definitions, flag/argument parsers, configuration loaders, and shell completion scripts.
+
+### Step 1: Identify CLI Framework
+
+Check for the presence of:
+- **Go**: cobra, urfave/cli, kong, pflag, flag (stdlib)
+- **Rust**: clap, structopt, argh
+- **Python**: click, typer, argparse, fire
+- **Node.js**: commander, yargs, oclif, meow, citty
+- **Ruby**: thor, optparse, gli
+- **Dart**: args, dcli
+
+Determine from imports, `go.mod`, `Cargo.toml`, `package.json`, `requirements.txt`, `pubspec.yaml`, etc.
+
+### Step 2: Create .spec/CLI.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: what the CLI does and who uses it
+- Installation command (if applicable)
+- Quick start example (the most common invocation)
+
+##### 2. Command Tree
+
+ASCII tree of all commands and subcommands:
+```
+myapp
+├── init              # Initialize a new project
+├── run               # Run the application
+│   ├── --watch       # Watch mode
+│   └── --port N      # Port number
+├── config
+│   ├── get <key>     # Read config value
+│   ├── set <key> <v> # Write config value
+│   └── list          # List all config values
+└── version           # Print version
+```
+
+Build from actual command registration code (e.g., `rootCmd.AddCommand()`, `@app.command()`, `.command()`).
+
+##### 3. Commands Reference
+
+For each command (or command group):
+
+```markdown
+### `myapp <command> [flags]`
+
+**Description:** One sentence.
+
+| Flag / Argument | Type | Required | Default | Description |
+|----------------|------|----------|---------|-------------|
+| `<positional>` | string | yes | — | What it is |
+| `--flag` / `-f` | bool | no | `false` | What it does |
+| `--output` / `-o` | string | no | `stdout` | Output destination |
+
+**Examples:**
+\```bash
+myapp run --port 8080
+myapp config set key value
+\```
+```
+
+Extract flags from actual struct tags, decorators, or builder calls — do not invent.
+
+##### 4. Configuration
+
+- Config file locations (precedence order): CLI flags → env vars → config file → defaults
+- Config file format (YAML, TOML, JSON, INI)
+- Config file path resolution (XDG, `$HOME/.config/`, project-local)
+- Environment variable naming convention (e.g., `MYAPP_PORT`, `MYAPP_LOG_LEVEL`)
+
+Table:
+| Setting | Flag | Env Var | Config Key | Default |
+|---------|------|---------|------------|---------|
+
+##### 5. Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | General error |
+| `2` | Usage error (invalid flags/arguments) |
+| ... | Project-specific codes |
+
+Extract from actual code if defined (e.g., `os.Exit()`, `process.exit()`, `std::process::exit()`).
+
+##### 6. I/O Contracts
+
+- **stdin**: Does the CLI read from stdin? What format? (e.g., piped JSON, line-delimited)
+- **stdout**: What is printed on success? (data output, structured JSON, human-readable text)
+- **stderr**: What goes to stderr? (logs, progress, errors)
+- **Files**: Does the CLI create/modify files? Where?
+
+Piping and composition examples:
+```bash
+cat input.json | myapp process --format json > output.json
+myapp list --json | jq '.[] | .name'
+```
+
+##### 7. Shell Completion
+
+- Supported shells (bash, zsh, fish, PowerShell)
+- Installation commands for each shell
+- How completions are generated (static file, dynamic `completion` subcommand)
+
+If no completion support exists, note it explicitly.
+
+##### 8. Global Flags
+
+Flags available on all commands:
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--verbose` / `-v` | bool | `false` | Verbose output |
+| `--config` / `-c` | string | `~/.config/myapp/config.yaml` | Config file path |
+| `--quiet` / `-q` | bool | `false` | Suppress non-error output |
+
+##### 9. Error Messages & Troubleshooting
+
+Common error messages and their resolutions:
+| Error | Cause | Fix |
+|-------|-------|-----|
+
+##### 10. Development
+
+- How to run the CLI locally during development
+- How to build a release binary
+- How to add a new command (step-by-step referencing the framework)
+
+## General Rules
+
+- Language: English
+- All commands, flags, and examples must come from actual source code — do not invent
+- If the CLI has no subcommands (single-command tool), adapt the structure: skip the command tree, expand the flags section
+- If the project is not a CLI application, do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/clients.md b/.agents/skills/sdd/templates/docs/clients.md
new file mode 100644
index 0000000..6f21ac2
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/clients.md
@@ -0,0 +1,175 @@
+<!-- scope: **/client*, **/sdk/* -->
+# Clients Documentation Template
+
+## What This Generates
+
+- `.spec/CLIENTS.md` — overview of all client applications
+- `.spec/<CLIENT_NAME>.md` — one file per significant client (e.g., `FRONTEND.md`, `TELEGRAM.md`, `MOBILE.md`, `CLI.md`)
+
+## Instructions
+
+You are a technical documentarian. Create client application documentation for the project in the `.spec/` directory.
+Analyze directories: `clients/`, `frontend/`, `web/`, `mobile/`, `app/`, `bot/`, `cli/`, etc.
+
+### Step 1: Identify Client Applications
+
+Check for the presence of:
+- **Web SPA**: React, Vue, Angular, Svelte, Next.js, Nuxt
+- **Mobile**: React Native, Flutter, Swift, Kotlin
+- **Telegram**: Mini App, Bot
+- **Desktop**: Electron, Tauri
+- **CLI**: cobra, click, argparse
+- **Browser Extension**: Chrome, Firefox
+
+For each found client, analyze: `package.json`, `pubspec.yaml`, `build.gradle`, etc.
+
+### Step 2: Create .spec/CLIENTS.md (overview)
+
+#### Structure:
+
+##### 1. Available Clients
+Table:
+| Client | Location | Technology | Purpose |
+|--------|----------|------------|---------|
+
+##### 2. Shared Code
+What clients share:
+- API types (TypeScript interfaces, Dart models)
+- API client (Axios, Dio, fetch wrapper)
+- Commands for syncing shared code
+
+**Code Generation** (if applicable):
+- Source of truth: proto files, OpenAPI spec, GraphQL schema
+- Generation command (e.g., `make gen-client`, `npm run codegen`)
+- Output directory (e.g., `clients/shared/api/`)
+- Sync workflow: when to regenerate, how to verify freshness
+
+**API Version Management** (if applicable):
+- How clients handle API versioning (URL prefix, header, content-type)
+- Backward compatibility strategy (deprecation notices, feature flags)
+- How multiple API versions coexist on the client side
+
+##### 3. API Communication
+ASCII diagram: how clients communicate with the backend:
+```
+┌──────────┐     ┌──────────┐
+│  Client  │────>│ Backend  │
+│  (React) │ REST│ (API)    │
+└──────────┘     └──────────┘
+```
+Protocol (REST, gRPC, WebSocket, GraphQL), ports.
+
+##### 4. Authentication Flow
+Authentication steps from the client perspective:
+1. Registration → endpoint
+2. Login → endpoint → token receipt
+3. Token storage (localStorage, SecureStorage, cookies)
+4. Sending in header
+
+##### 5. Adding a New Client
+Options (React-based, native mobile, PWA, etc.) with step-by-step instructions.
+
+##### 6. Development Workflow
+Commands for running the full stack (backend + clients).
+
+### Step 3: Create Per-Client Documents
+
+Create a separate document if the client:
+- Has its own technology stack
+- Contains > 10 files
+- Has specific logic (Telegram SDK, TON Connect, etc.)
+
+#### Per-Client Template: .spec/{CLIENT_NAME}.md
+
+Example names: `FRONTEND.md`, `TELEGRAM.md`, `MOBILE.md`, `CLI.md`
+
+##### 1. Overview
+One sentence + link to base template (if applicable).
+Path: `clients/web/` or equivalent.
+
+##### 2. Tech Stack
+Table:
+| Technology | Purpose |
+|------------|---------|
+
+Determine from `package.json` / `pubspec.yaml` / `build.gradle`.
+
+##### 3. Directory Structure
+ASCII tree (2 levels):
+```
+clients/web/
+├── src/
+│   ├── api/         # API client and types
+│   ├── components/  # Reusable components
+│   ├── pages/       # Page components
+│   └── ...
+└── package.json
+```
+
+##### 4. Commands
+```bash
+npm install          # Install dependencies
+npm run dev          # Start dev server
+npm run build        # Production build
+...
+```
+
+##### 5. Routes / Navigation
+Route table:
+| Path | Component | Auth Required |
+|------|-----------|---------------|
+
+##### 6. API Client
+- Configuration (base URL, interceptors)
+- Authentication (how the token is stored and sent)
+- Available methods (table: Method | Endpoint | Auth)
+
+##### 7. UI Framework / Theme (if applicable)
+- Which UI kit is used
+- Colors, fonts, styling approach
+
+##### 8. Platform-Specific Features
+
+**For Telegram Mini App:**
+- SDK initialization
+- initData authentication
+- Mock environment for local development
+- Native UI components (@telegram-apps/telegram-ui)
+- TON Connect (if applicable)
+- Auto-login flow
+
+**For Mobile (React Native / Flutter):**
+- Platform-specific code (iOS/Android)
+- Push notifications
+- Deep linking
+- Native modules
+
+**For CLI:**
+- Commands and subcommands
+- Flags and arguments
+- Configuration files
+
+##### 9. Environment Variables
+```bash
+VITE_API_URL=http://localhost:10002
+# or
+NEXT_PUBLIC_API_URL=...
+```
+
+##### 10. Development vs Production
+Differences between dev and prod modes.
+
+##### 11. Deployment
+How to deploy the client (GitHub Pages, Vercel, App Store, npm publish).
+
+##### 12. Adding New Pages / Features
+Step-by-step instructions for adding a new page/feature.
+
+## General Rules
+
+- If a client is trivial (< 5 files) — do not create a separate document, describe it in `CLIENTS.md`
+- Determine technologies from actual `package.json` / dependencies, do not guess
+- Routes must come from the actual router code (`App.tsx`, `routes.tsx`, `router.ts`)
+- API methods must come from the actual API client
+- After creating files, update `.spec/README.md`: add links under the Clients section
+- If there are no client applications in the project, do not generate any files — skip this template entirely
diff --git a/.agents/skills/sdd/templates/docs/components.md b/.agents/skills/sdd/templates/docs/components.md
new file mode 100644
index 0000000..113afa6
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/components.md
@@ -0,0 +1,176 @@
+<!-- scope: **/components/*, **/ui/*, **/design-system/*, **/atoms/*, **/molecules/*, **/widgets/* -->
+# Components Documentation Template
+
+## What This Generates
+
+- `.spec/COMPONENTS.md` — design system, component library, composition patterns, theming
+
+## Instructions
+
+You are a technical documentarian. Create UI component documentation for the project in the `.spec/` directory.
+Analyze: component directories, shared UI libraries, theme/token files, Storybook config, and style systems.
+
+### Step 1: Identify Component Architecture
+
+Check for the presence of:
+- **React**: `components/`, JSX/TSX files, Storybook, Radix, shadcn/ui, MUI, Ant Design, Chakra
+- **Vue**: `components/`, SFC (`.vue` files), Vuetify, PrimeVue, Quasar, Headless UI
+- **Angular**: `components/`, Angular Material, PrimeNG, standalone components
+- **Svelte**: `lib/components/`, SvelteKit components, Skeleton UI, Flowbite
+- **Flutter/Dart**: `widgets/`, `lib/ui/`, custom Widget classes, Material/Cupertino
+- **Web Components**: Custom Elements, Lit, Stencil
+
+Determine from framework files, imports, and component registration patterns.
+
+### Step 2: Create .spec/COMPONENTS.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: component architecture approach
+- UI library / framework used (if any)
+- Design methodology: Atomic Design, BEM, component composition, compound components
+- Styling approach: CSS Modules, styled-components, Tailwind, CSS-in-JS, vanilla CSS, SCSS
+
+##### 2. Component Inventory
+
+Master table of all shared/reusable components:
+
+| Component | Location | Category | Props / Inputs | Used By |
+|-----------|----------|----------|----------------|---------|
+| `Button` | `src/components/Button.tsx` | Atom | `variant`, `size`, `disabled`, `onClick` | Throughout |
+| `Modal` | `src/components/Modal.tsx` | Molecule | `isOpen`, `onClose`, `title`, `children` | `Settings`, `Confirm` |
+| `DataTable` | `src/components/DataTable.tsx` | Organism | `columns`, `data`, `onSort`, `pagination` | `Users`, `Orders` |
+
+Categorize by complexity level (Atom / Molecule / Organism / Template) or by domain (Layout / Form / Feedback / Navigation / Data Display) — whichever the project uses.
+
+##### 3. Component API Patterns
+
+Document the conventions used across all components:
+
+**Props / Inputs:**
+- Naming conventions (e.g., `onX` for callbacks, `isX` for booleans, `xRef` for refs)
+- Required vs optional patterns
+- Default values strategy
+- Children / slots / content projection patterns
+
+**Composition patterns used:**
+- Compound components (e.g., `<Select><Select.Option>`)
+- Render props / scoped slots
+- Higher-order components / mixins
+- Headless / renderless components
+- Forward ref / template ref
+
+Code example of a well-structured component from the project.
+
+##### 4. Design Tokens / Theme
+
+**Colors:**
+| Token | Light Value | Dark Value | Usage |
+|-------|-------------|------------|-------|
+| `--color-primary` | `#3B82F6` | `#60A5FA` | Buttons, links, active states |
+| `--color-surface` | `#FFFFFF` | `#1E1E1E` | Cards, modals, backgrounds |
+
+**Typography:**
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--font-family-base` | `Inter, sans-serif` | Body text |
+| `--font-size-sm` | `0.875rem` | Secondary text, captions |
+
+**Spacing:**
+| Token | Value |
+|-------|-------|
+| `--space-1` | `4px` |
+| `--space-2` | `8px` |
+
+Extract from actual theme files, CSS custom properties, Tailwind config, `ThemeData`, or token files.
+
+**Dark mode / Theming:**
+- How themes are defined and switched
+- CSS custom properties, `ThemeProvider`, `prefers-color-scheme`
+- Where theme tokens live (file path)
+
+##### 5. Layout System
+
+- Grid system: CSS Grid, Flexbox, framework grid (e.g., MUI Grid, Bootstrap Grid)
+- Breakpoints:
+
+| Name | Min Width | Typical Usage |
+|------|-----------|---------------|
+| `sm` | `640px` | Mobile landscape |
+| `md` | `768px` | Tablet |
+| `lg` | `1024px` | Desktop |
+
+- Container / wrapper components
+- Responsive patterns used (fluid, adaptive, mobile-first)
+
+##### 6. Form Components
+
+- Form library (React Hook Form, Formik, VeeValidate, Angular Reactive Forms)
+- Validation approach (schema-based with Zod/Yup, inline, server-side)
+- Error display pattern (inline, toast, summary)
+- Standard form controls:
+
+| Component | Type | Validation | Accessibility |
+|-----------|------|------------|---------------|
+| `TextInput` | text, email, password | required, pattern | `aria-label`, error announcement |
+| `Select` | dropdown | required | keyboard navigation |
+| `Checkbox` | boolean | — | `role="checkbox"` |
+
+##### 7. Icon System
+
+- Icon source: icon library (Lucide, Heroicons, Material Icons), custom SVGs, icon font
+- How icons are used in components (component import, sprite, CSS class)
+- Sizing conventions
+- Where custom icons are stored
+
+##### 8. Animation & Transitions
+
+- Animation library (Framer Motion, GSAP, Vue Transition, CSS animations)
+- Standard transitions:
+
+| Transition | Duration | Easing | Used For |
+|-----------|----------|--------|----------|
+| Fade in/out | `200ms` | `ease-in-out` | Modal, tooltip |
+| Slide | `300ms` | `ease-out` | Drawer, sidebar |
+| Scale | `150ms` | `ease-in` | Button press, card hover |
+
+- Reduced motion: how `prefers-reduced-motion` is respected
+
+##### 9. Accessibility (a11y)
+
+- WCAG target level (A, AA, AAA)
+- Keyboard navigation patterns (tab order, focus trap in modals, arrow keys in lists)
+- ARIA attributes used by components
+- Screen reader testing approach
+- Color contrast compliance
+
+##### 10. Storybook / Component Playground
+
+- Storybook version and config location (if applicable)
+- How to run: command
+- Story file naming convention (`.stories.tsx`, `.stories.vue`)
+- Addons used (a11y, viewport, controls)
+- How to add a new story
+
+If no Storybook or equivalent exists, note it.
+
+##### 11. Adding a New Component
+
+Step-by-step guide:
+1. Create component file in the correct directory
+2. Define props/inputs interface
+3. Implement with project conventions (styling, composition)
+4. Add to exports / barrel file
+5. Write story (if Storybook)
+6. Write tests (unit + visual regression if applicable)
+7. Document usage
+
+## General Rules
+
+- Language: English
+- All components, props, and tokens must come from actual source code — do not invent
+- If the project uses a pre-built UI library with no customization (e.g., just MUI out-of-box), document the usage patterns rather than the library internals
+- For Flutter/Dart projects, adapt terminology: Widget instead of Component, `ThemeData` instead of CSS tokens
+- If the project has no shared UI components (e.g., pure backend, CLI), do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/core.md b/.agents/skills/sdd/templates/docs/core.md
new file mode 100644
index 0000000..22a591f
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/core.md
@@ -0,0 +1,232 @@
+<!-- scope: cmd/*, internal/*, pkg/*, src/*, app/*, domain/* -->
+# Core Documentation Template
+
+## What This Generates
+
+- `.spec/ARCHITECTURE.md` — project architecture overview
+- `.spec/PACKAGES.md` — reference of all packages/modules
+- `.spec/DOMAIN.md` — domain model description
+- `.spec/CODE_STYLE.md` — project-specific code conventions
+
+## Instructions
+
+You are a technical documentarian. Create the core project documentation in the `.spec/` directory.
+Analyze the source code, directory structure, dependencies, and configuration files.
+
+Create the following files:
+
+---
+
+### File 1: .spec/ARCHITECTURE.md
+
+A document describing the project's architecture.
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: application type + architectural pattern
+- ASCII diagram of application layers (top-down: Transport → Application → Adapters → Infrastructure)
+- Show connections between layers with arrows
+
+##### 2. Component Deep Dive
+For each architectural layer:
+- Name and package path
+- Key files with descriptions (table: File | Description)
+- Role in the system
+- Which interfaces it implements / uses
+
+Analyze the actual code:
+- Entry point (`main.go` / `main.ts` / `app.py` etc.)
+- Business logic (`app/`, `domain/`, `services/`, `use_cases/`)
+- Adapters (`adapters/`, `repositories/`, `infrastructure/`)
+- API layer (`api/`, `handlers/`, `controllers/`, `routes/`)
+
+##### 3. Directory Structure
+ASCII tree with comments (2-3 levels deep):
+```
+project/
+├── cmd/                    # Entry points
+│   └── app/
+│       └── internal/
+│           ├── app/        # Business logic
+│           ├── adapters/   # Infrastructure adapters
+│           └── api/        # API handlers
+├── internal/               # Shared packages
+└── configs/                # Configuration files
+```
+
+##### 4. Key Design Decisions
+Numbered list of key architectural decisions (3-7 items):
+- Architectural pattern and why
+- API strategy (REST/gRPC/GraphQL)
+- Dependency injection approach
+- Testing strategy
+- Observability approach (if present)
+- Context propagation (if present)
+
+For each decision: title, 2-3 bullet points, code example if appropriate.
+
+##### 5. Data Flow
+Trace the lifecycle of a typical request from entry point to response:
+- ASCII sequence diagram showing how a request passes through layers
+- Name the concrete types/functions involved at each step
+- Show where validation, authorization, business logic, and persistence happen
+
+Example format:
+```
+HTTP Request
+  → Router (api/router.go)
+    → Middleware (auth, logging, tracing)
+      → Handler (api/handler.go)
+        → App method (app/service.go)
+          → Adapter (adapters/repo.go)
+            → Database
+          ← Return domain object
+        ← Convert to response
+      ← Send HTTP response
+```
+
+If the project has multiple entry points (HTTP + gRPC, CLI + API), show the primary one and note differences for others.
+
+---
+
+### File 2: .spec/PACKAGES.md
+
+Reference of all project packages/modules.
+
+#### Structure:
+
+For each package/module:
+
+```markdown
+### `path/to/package`
+**Brief description** — one sentence.
+
+| File | Description |
+|------|-------------|
+| `file1.go` | Description |
+| `file2.go` | Description |
+
+Key details (if applicable):
+- Which interfaces it implements
+- Which libraries it uses
+- Specifics (tracing, caching, etc.)
+```
+
+Group packages by layer:
+1. **Application Layer** — business logic
+2. **Adapters Layer** — infrastructure adapters
+3. **API Layer** — transport
+4. **Shared/Internal** — common utilities
+5. **Generated** — generated code (proto, OpenAPI, etc.)
+
+---
+
+### File 3: .spec/DOMAIN.md
+
+Description of the project's domain model.
+
+#### Structure:
+
+##### 1. Core Entities
+For each entity:
+- Name
+- Structure definition (in the project's language)
+- Field comments (if non-obvious)
+
+##### 2. Enums / Value Objects
+All enumerations and value objects with their values.
+
+##### 3. Business Errors
+> Owned by `errors.md` → `ERRORS.md`. Do **not** duplicate the catalog here.
+
+One-line summary: "For the full business error catalog (codes, HTTP/gRPC mapping, retry policy) see `ERRORS.md`."
+If `ERRORS.md` does not exist yet, list errors inline and note that they should be migrated when `errors.md` is run.
+
+##### 4. Search/Filter Parameters
+Search/filter structures (if present).
+
+Important:
+- Take definitions from actual code (`domain.go`, `models.py`, `types.ts`, etc.)
+- Do not invent fields — only what exists in the code
+- For large structures, show all fields
+
+---
+
+### File 4: .spec/CODE_STYLE.md
+
+Project-specific code conventions.
+
+#### Structure:
+
+##### 1. Layer Structure
+ASCII diagram of layers with rules for each:
+- Which structures are used (public/private, with/without tags)
+- How conversion between layers works
+
+##### 2. Struct Tags by Layer (if applicable)
+For each layer:
+- Rule
+- Code example (Correct)
+- Explanation (Why)
+
+##### 3. Conversion Pattern
+How data is converted between layers:
+- Adapters ↔ App (convert methods)
+- API ↔ App (toX functions)
+
+##### 4. Naming Conventions
+Tables:
+- Files: file naming patterns by layer
+- Structs: visibility (public/private) by layer
+- Enums: definition pattern
+
+##### 5. Interface Conventions
+Rules for interfaces:
+- Argument order (context first, etc.)
+- Error documentation
+- Interface composition
+
+##### 6. Import Ordering
+Import order with example.
+
+##### 7. Test File Organization
+Table of test file patterns.
+
+##### 8. Quick Reference
+Summary table: Aspect | App Layer | Adapters Layer | API Layer
+
+##### 9. Error Propagation
+Rules for error handling across layers:
+- How errors are wrapped when crossing layer boundaries
+- Sentinel errors vs typed errors: when to use each
+- Error types by layer (domain errors, adapter errors, API errors)
+- Code example showing error wrapping chain from adapter → app → API
+
+##### 10. Logging Conventions
+Structured logging rules:
+- Logger type and initialization pattern
+- What to log at each layer (table: Layer | Log Level | What to Log)
+- Sensitive data handling (what must never be logged)
+- Correlation IDs / request IDs (how passed through context)
+- Code example of a properly logged operation
+
+##### 11. Concurrency Patterns (if applicable)
+Concurrency rules used in the project:
+- Goroutine / async task management (how spawned, how tracked)
+- Context cancellation propagation
+- Channel / queue usage patterns
+- Mutex / synchronization patterns
+- Graceful shutdown sequence
+
+If the project is single-threaded or has no concurrency patterns, skip this section.
+
+## General Rules
+
+- Language: English
+- Format: Markdown with ASCII diagrams, tables, fenced code blocks with language tags
+- Code examples: ONLY from the actual project, not abstract
+- If something is not found in the project — do not create the corresponding section
+- Each document must be self-contained (can be read independently)
+- Do not duplicate information between documents — cross-reference instead
+- After creating files, update `.spec/README.md`: add links to created documents in the Documentation Index section
diff --git a/.agents/skills/sdd/templates/docs/database.md b/.agents/skills/sdd/templates/docs/database.md
new file mode 100644
index 0000000..04b986b
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/database.md
@@ -0,0 +1,114 @@
+<!-- scope: **/migrations/*, **/schema*, **/*repo*, **/*store* -->
+# Database Documentation Template
+
+## What This Generates
+
+- `.spec/DATABASE.md` — database schema, migrations, connection management, and query patterns
+
+## Instructions
+
+You are a technical documentarian. Create database documentation for the project in the `.spec/` directory.
+Analyze: migration files, ORM config, repository/DAO layer, database drivers, connection setup, seed scripts.
+
+### Step 1: Identify Database Usage
+
+Determine which databases the project uses:
+- **SQL**: PostgreSQL, MySQL, SQLite, CockroachDB
+- **NoSQL**: MongoDB, DynamoDB, Cassandra, Redis (if used as primary store)
+- **Search**: Elasticsearch, Meilisearch, Typesense
+
+For each database, identify:
+- Driver / ORM / query builder (e.g., `pgx`, `sqlx`, `GORM`, `Prisma`, `TypeORM`, `sqlc`)
+- Migration tool (e.g., `goose`, `migrate`, `knex`, `Flyway`, `Alembic`)
+- Connection configuration (env vars, config files)
+
+### Step 2: Create .spec/DATABASE.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: which database(s) and why
+- Driver / ORM used
+- Connection string format (with placeholders, no real credentials)
+
+##### 2. Schema Overview
+
+**Entity-Relationship Diagram:**
+ASCII or Mermaid ER diagram showing tables and relationships:
+```
+┌──────────┐     ┌──────────────┐     ┌──────────┐
+│  users   │────<│ user_tokens  │     │  posts   │
+│──────────│     │──────────────│     │──────────│
+│ id (PK)  │     │ id (PK)      │     │ id (PK)  │
+│ email    │     │ user_id (FK) │  ┌──│ user_id  │
+│ name     │     │ token        │  │  │ title    │
+└──────────┘     └──────────────┘  │  └──────────┘
+      │                            │
+      └────────────────────────────┘
+```
+
+**Table Reference:**
+| Table | Purpose | Key Columns |
+|-------|---------|-------------|
+| `users` | User accounts | `id`, `email`, `name`, `created_at` |
+
+For each table: name, purpose, key columns. Group by domain area if many tables.
+
+##### 3. Migration Strategy
+- Migration tool and version
+- Migration directory path
+- Naming convention (e.g., `YYYYMMDDHHMMSS_description.sql`, sequential numbers)
+- Up / down convention: are down migrations required?
+- How to create a new migration (command)
+- How to run migrations (command)
+- How to rollback (command)
+- CI integration: are migrations run automatically in CI/CD?
+
+##### 4. Connection Management
+- Connection pool configuration (min/max connections, idle timeout)
+- Read replicas (if applicable): how reads are routed
+- Connection lifecycle: where the connection is created, how it's passed (context, DI, global)
+- Health check / ping mechanism
+- Reconnection strategy
+
+Code reference: file path where connection is initialized.
+
+##### 5. Query Patterns
+- Repository / DAO pattern: interface definition and implementation structure
+- Query builder vs raw SQL vs ORM: which approach is used and when
+- Transaction management: how transactions are started, committed, rolled back
+- Prepared statements / named queries (if applicable)
+- Pagination pattern (offset vs cursor)
+
+Code example of a typical repository method from the project.
+
+##### 6. Seed / Fixtures
+- Dev seed data: how to populate the database for local development (command)
+- Test fixtures: how test data is set up (helpers, factories, SQL files)
+- Reset command: how to wipe and re-seed the database
+- Sample data location (if seed files exist)
+
+##### 7. Indexes & Performance (if discoverable)
+Notable indexes beyond primary keys:
+| Table | Index | Columns | Type |
+|-------|-------|---------|------|
+
+Only include if indexes are defined in migration files or ORM annotations.
+
+##### 8. Backup & Recovery (if applicable)
+- Backup strategy (pg_dump, cloud snapshots, scheduled jobs)
+- Backup commands or scripts
+- Point-in-time recovery (WAL archiving, binlog)
+- Data retention policy
+
+Only include if backup tooling or scripts exist in the project.
+
+## General Rules
+
+- Language: English
+- All SQL examples must come from actual migration files or repository code
+- Do not invent tables or columns — only document what exists
+- If the project uses multiple databases, create sections for each
+- Connection strings and credentials must use placeholders, never real values
+- If the project has no database, do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/deployment.md b/.agents/skills/sdd/templates/docs/deployment.md
new file mode 100644
index 0000000..72e88e9
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/deployment.md
@@ -0,0 +1,138 @@
+<!-- scope: Dockerfile*, docker-compose*, **/deploy/*, **/k8s/* -->
+# Deployment Documentation Template
+
+## What This Generates
+
+- `.spec/DEPLOYMENT.md` — environments, deployment pipeline, rollout strategy, health checks, and infrastructure
+
+## Instructions
+
+You are a technical documentarian. Create deployment documentation for the project in the `.spec/` directory.
+Analyze: Dockerfile, docker-compose files, CI/CD configs, Kubernetes manifests, Helm charts, Terraform files, deployment scripts, health check endpoints.
+
+### Step 1: Identify Deployment Infrastructure
+
+Check for the presence of:
+- **Containers**: `Dockerfile`, `docker-compose.yml`, `.dockerignore`
+- **CI/CD**: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `bitbucket-pipelines.yml`
+- **Orchestration**: `k8s/`, `helm/`, `kustomize/`, `nomad/`
+- **IaC**: `terraform/`, `pulumi/`, `cloudformation/`
+- **PaaS**: `fly.toml`, `render.yaml`, `railway.json`, `vercel.json`, `netlify.toml`
+
+### Step 2: Create .spec/DEPLOYMENT.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: deployment target + strategy
+- ASCII diagram of the deployment pipeline:
+```
+push → CI (lint + test) → build image → push registry → deploy → health check
+```
+
+##### 2. Environments
+
+| Environment | URL / Host | Purpose | Branch | Auto-deploy |
+|-------------|-----------|---------|--------|-------------|
+| Local | `localhost:8080` | Development | — | — |
+| Staging | `staging.example.com` | Pre-production testing | `develop` | Yes |
+| Production | `example.com` | Live | `main` | No (manual) |
+
+For each environment: how to access, what branch triggers deployment, any special config.
+
+##### 3. Docker
+
+**Dockerfile analysis:**
+- Base image and build stages (multi-stage?)
+- Build arguments and their purpose
+- Exposed ports
+- Entry point / command
+- Image size optimization notes
+
+**Docker Compose (dev):**
+- Services defined and their roles
+- Volume mounts
+- Network configuration
+- Useful commands:
+```bash
+docker-compose up -d        # Start all services
+docker-compose logs -f app  # Follow app logs
+docker-compose down -v      # Stop and remove volumes
+```
+
+##### 4. CI/CD Pipeline
+
+For each CI/CD workflow file:
+- **File**: path to workflow
+- **Trigger**: on push, PR, tag, manual
+- **Steps**: ordered list of what happens
+- **Secrets required**: list of secret names (not values)
+
+Example:
+```
+.github/workflows/ci.yml
+  Trigger: push to main, PR
+  Steps: checkout → setup → lint → test → build → push image
+  Secrets: DOCKER_USERNAME, DOCKER_PASSWORD, DEPLOY_KEY
+```
+
+##### 5. Rollout Strategy
+- Strategy type: rolling update / blue-green / canary / recreate
+- Configuration (max surge, max unavailable, canary percentage)
+- Where configured (k8s deployment spec, PaaS config, script)
+- Zero-downtime deployment: yes/no, how achieved
+
+##### 6. Health Checks
+
+| Endpoint | Type | Expected Response | Timeout |
+|----------|------|-------------------|---------|
+| `/health` | Liveness | `200 OK` | 5s |
+| `/ready` | Readiness | `200 OK` | 10s |
+
+- What each check verifies (DB connection, cache, external services)
+- Startup probe (if applicable)
+- Code reference: where health check handlers are defined
+
+##### 7. Rollback Procedure
+Step-by-step rollback instructions:
+1. Identify the issue (logs, metrics, alerts)
+2. Rollback command (e.g., `kubectl rollout undo`, `git revert` + redeploy, PaaS rollback)
+3. Verify rollback (health check, smoke test)
+4. Post-mortem actions
+
+Include actual commands for the project's deployment target.
+
+##### 8. Secrets Management
+- Where secrets are stored: environment variables, vault, cloud secret manager, CI/CD variables
+- How secrets are injected: env files, k8s secrets, mounted volumes
+- Rotation policy (if documented)
+- Required secrets list:
+
+| Secret | Purpose | Where Set |
+|--------|---------|-----------|
+| `DATABASE_URL` | DB connection | CI/CD vars |
+| `JWT_SECRET` | Token signing | Vault |
+
+Do not include actual secret values.
+
+##### 9. Infrastructure Requirements (if applicable)
+Resource requirements per service:
+| Service | CPU | Memory | Storage | Replicas |
+|---------|-----|--------|---------|----------|
+
+Determine from k8s resource limits, PaaS config, or documentation.
+
+##### 10. Monitoring & Alerts (if applicable)
+- Where to view logs (log aggregator URL, command)
+- Metrics dashboard (Grafana URL, Datadog, etc.)
+- Alert rules (what triggers alerts)
+- On-call / escalation process (if documented)
+
+## General Rules
+
+- Language: English
+- All commands and paths must come from actual project files
+- Never include real secrets, tokens, or internal URLs — use placeholders
+- If the project has no deployment config (pure library), do not generate this file
+- Focus on what exists, not what should exist — document current state
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/development.md b/.agents/skills/sdd/templates/docs/development.md
new file mode 100644
index 0000000..9aa772e
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/development.md
@@ -0,0 +1,202 @@
+<!-- scope: Makefile, Taskfile*, scripts/*, **/ci/* -->
+# Development Documentation Template
+
+## What This Generates
+
+- `.spec/TOOLS.md` — reference of commands and project tools
+- `.spec/TESTING.md` — project testing conventions
+- `.spec/FILES.md` — file storage system description (only if applicable)
+
+## Instructions
+
+You are a technical documentarian. Create the development documentation in the `.spec/` directory.
+Analyze the Makefile, Taskfile.yml, package.json scripts, CI/CD configs, test files, and file adapters.
+
+Create the following files:
+
+---
+
+### File 1: .spec/TOOLS.md
+
+Reference of commands and project tools.
+
+#### Structure:
+
+##### 0. Dev Environment Setup
+
+Prerequisites and first-run instructions for new developers:
+
+**Prerequisites:**
+| Tool | Version | Install |
+|------|---------|---------|
+| Go / Node / Python | x.y | `brew install ...` / link |
+
+Determine from: `go.mod`, `package.json` engines, `.tool-versions`, `Dockerfile` base image, README.
+
+**First Run:**
+Numbered steps to go from a fresh clone to a running dev environment:
+1. Clone the repository
+2. Copy env file (`cp .env.example .env`) — list required variables
+3. Install dependencies (`go mod download` / `npm install`)
+4. Start infrastructure (`docker-compose up -d`)
+5. Run migrations (command)
+6. Start the application (command)
+7. Verify (health check URL or test command)
+
+If a `Makefile` / `Taskfile` has an `init` or `setup` target, reference it.
+
+##### 1. Overview
+One sentence + important note about how to run commands (e.g., "All commands must be run via `task`" or "Use `make`" or "Use `npm run`").
+
+##### 2. Quick Reference
+Table of key commands:
+| Action | Command |
+|--------|---------|
+| Unit tests | `...` |
+| Build | `...` |
+| Lint | `...` |
+| Start | `...` |
+| Stop | `...` |
+
+Source commands from:
+- Makefile / Taskfile.yml / package.json scripts
+- CI/CD configs (`.github/workflows/`, `.gitlab-ci.yml`)
+- Project README.md
+
+##### 3. Detailed Command Groups
+
+For each group (Testing, Building, Docker, Linting, Init, etc.):
+- Command with usage example (bash code block)
+- What it does (1-2 lines)
+- Dependencies (what must be run before)
+- Tools used
+
+##### 4. Code Generation (if applicable)
+Code generation commands:
+- Proto/OpenAPI generation
+- Test mocks
+- Stringer/enum generators
+- ORM generators (sqlc, ent, etc.)
+
+For each: command + what it generates + configuration file.
+
+##### 5. CI/CD Cheatsheet
+Quick commands for simulating the CI pipeline locally.
+
+##### 6. Tool Installation
+Table of tools with installation commands:
+| Tool | Install Command |
+|------|-----------------|
+
+Determine from go.mod tools, package.json devDependencies, Brewfile, etc.
+
+---
+
+### File 2: .spec/TESTING.md
+
+Project testing conventions.
+
+#### Structure:
+
+Analyze existing test files in the project and identify patterns.
+
+##### 1. Test Package Naming
+Which convention: internal test package or external test package?
+Example from actual code.
+
+##### 2. Test File Structure
+Full example of a typical test from the project:
+- Imports
+- Test case structure
+- Setup / teardown
+- Assertions
+
+##### 3. Key Patterns
+Identify and describe patterns (only those actually used):
+- Table-driven tests (map vs slice)
+- Parallel execution
+- Variable capture in range loops
+- Common test helpers (`start()`, `setup()` functions)
+- Builder pattern for test data
+- Golden files
+- Snapshot testing
+
+For each pattern: name + code example from the project.
+
+##### 4. Mock Generation
+How mocks are generated:
+- Tool (mockgen, testify/mock, etc.)
+- Generation command
+- Where stored (alongside tests / separate directory)
+- `go:generate` directive (if applicable)
+
+##### 5. Integration Tests
+- How separated from unit tests (build tags, directory, naming)
+- Run command
+- Test containers / test helpers for Docker
+- Examples of test resource initialization
+
+##### 6. Export Pattern (if applicable)
+How private functions are tested from external test packages.
+Example of `export_test.go` or equivalent.
+
+##### 7. Commands
+All testing commands:
+```bash
+# Unit tests
+...
+# Integration tests
+...
+# Coverage
+...
+# Race detector
+...
+```
+
+---
+
+### File 3: .spec/FILES.md (only if the project has file storage)
+
+Description of the file handling system.
+
+#### When to create:
+- S3/MinIO/file adapter exists
+- File upload/download functionality exists
+- Avatars, media, or documents are handled
+
+#### Structure:
+
+##### 1. Overview
+ASCII diagram of file flow: API → Application → FileStore → Storage
+
+##### 2. FileStore Interface
+Interface definition from the code.
+
+##### 3. File Model
+File structure from the domain layer.
+
+##### 4. Storage Adapter
+- Which storage (S3, MinIO, local FS, Cloudflare R2)
+- Configuration
+- Bucket / directory structure
+- File metadata
+
+##### 5. Specific Features
+Project-specific features (avatars, limits, formats, etc.)
+
+##### 6. Limitations & Recommendations
+Current limitations and improvement recommendations.
+
+##### 7. Environment Variables
+Storage configuration from docker-compose / env files.
+
+##### 8. Test Coverage
+How the file system is tested.
+
+## General Rules
+
+- All code examples — from the actual project
+- If a tool/pattern is not found — do not describe it
+- Format: Markdown, tables, fenced code blocks with language tags
+- After creating files, update `.spec/README.md`: add links under the Development section
+- If `.spec/FILES.md` does not apply (no file storage in the project), skip it entirely
diff --git a/.agents/skills/sdd/templates/docs/errors.md b/.agents/skills/sdd/templates/docs/errors.md
new file mode 100644
index 0000000..384040c
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/errors.md
@@ -0,0 +1,172 @@
+<!-- scope: **/*error*, **/*errs* -->
+# Errors Documentation Template
+
+## What This Generates
+
+- `.spec/ERRORS.md` — error architecture, business error catalog, wrapping conventions, and API error format
+
+## Instructions
+
+You are a technical documentarian. Create error handling documentation for the project in the `.spec/` directory.
+Analyze: error type definitions, error packages, HTTP/gRPC error mapping, middleware error handlers, domain error constants.
+
+### Step 1: Identify Error Patterns
+
+Determine how the project handles errors:
+- **Custom error types**: struct-based errors with codes, domain error packages
+- **Sentinel errors**: `var ErrNotFound = errors.New(...)` / constants
+- **Error wrapping**: `fmt.Errorf("...: %w", err)` / custom wrap functions
+- **Error mapping**: domain → HTTP status, domain → gRPC code
+- **Error response format**: JSON structure returned to API consumers
+
+### Step 2: Create .spec/ERRORS.md
+
+#### Structure:
+
+##### 1. Error Architecture
+
+Layered error model showing how errors flow through the application:
+```
+┌─────────────────────────────────────────────────┐
+│  API Layer                                       │
+│  Maps domain errors → HTTP status / gRPC code   │
+│  Formats error response JSON                     │
+├─────────────────────────────────────────────────┤
+│  Application Layer                               │
+│  Returns domain errors (ErrNotFound, etc.)       │
+│  Wraps adapter errors with context               │
+├─────────────────────────────────────────────────┤
+│  Adapter Layer                                   │
+│  Wraps infrastructure errors (DB, network)       │
+│  Converts to domain errors where appropriate     │
+├─────────────────────────────────────────────────┤
+│  Infrastructure                                  │
+│  Raw errors (sql.ErrNoRows, net.Error, etc.)     │
+└─────────────────────────────────────────────────┘
+```
+
+Describe the error propagation direction and rules:
+- Which layer creates errors
+- Which layer wraps errors
+- Which layer maps/translates errors
+- Where errors are logged vs returned
+
+##### 2. Business Error Catalog
+
+Table of all defined business/domain errors:
+
+| Code | Name | HTTP Status | gRPC Code | Description |
+|------|------|-------------|-----------|-------------|
+| `NOT_FOUND` | `ErrNotFound` | 404 | `NotFound` | Resource does not exist |
+| `ALREADY_EXISTS` | `ErrAlreadyExists` | 409 | `AlreadyExists` | Resource already exists |
+| `VALIDATION` | `ErrValidation` | 400 | `InvalidArgument` | Input validation failed |
+| `UNAUTHORIZED` | `ErrUnauthorized` | 401 | `Unauthenticated` | Authentication required |
+| `FORBIDDEN` | `ErrForbidden` | 403 | `PermissionDenied` | Insufficient permissions |
+
+Group by domain area if many errors exist. Include the file path where each error is defined.
+
+##### 3. Error Wrapping Convention
+
+Rules for wrapping errors at each layer boundary:
+
+**Adapter → Application:**
+```
+// Example pattern (use actual code from the project)
+func (r *repo) GetUser(ctx context.Context, id UserID) (*User, error) {
+    row := r.db.QueryRow(ctx, query, id)
+    if err := row.Scan(...); err != nil {
+        if errors.Is(err, sql.ErrNoRows) {
+            return nil, ErrNotFound
+        }
+        return nil, fmt.Errorf("get user %s: %w", id, err)
+    }
+    ...
+}
+```
+
+**Application → API:**
+```
+// Example pattern (use actual code from the project)
+func handleError(err error) (int, ErrorResponse) {
+    switch {
+    case errors.Is(err, app.ErrNotFound):
+        return 404, ErrorResponse{Code: "NOT_FOUND", ...}
+    ...
+    }
+}
+```
+
+Show the actual wrapping pattern used in the project. Include file references.
+
+##### 4. Error Response Format
+
+The standard error response structure returned by the API:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable description",
+    "details": [
+      {
+        "field": "email",
+        "message": "must be a valid email address"
+      }
+    ]
+  }
+}
+```
+
+Document:
+- Envelope structure
+- Required vs optional fields
+- How validation errors include field-level details
+- How the code maps to the Business Error Catalog
+- Content-Type header
+
+##### 5. Sentinel Errors vs Error Types
+
+When to use each approach in this project:
+
+**Sentinel errors** (simple, comparable with `errors.Is`):
+- When to use: identity-only errors without extra data
+- Examples from the project
+
+**Typed errors** (struct implementing `error` interface):
+- When to use: errors carrying extra context (field name, entity ID, etc.)
+- Examples from the project
+
+**Error interfaces** (if applicable):
+- Custom error interfaces for behavior-based checking (`errors.As`)
+- Examples from the project
+
+##### 6. Retry Policy (if applicable)
+
+Which errors are retryable and how:
+
+| Error Category | Retryable | Strategy |
+|----------------|-----------|----------|
+| Network timeout | Yes | Exponential backoff, max 3 |
+| DB connection lost | Yes | Reconnect + retry once |
+| Validation error | No | — |
+| Not found | No | — |
+| Rate limited | Yes | Respect Retry-After header |
+
+Include retry logic implementation reference if it exists in the project.
+
+##### 7. Error Logging
+
+Rules for error logging:
+- Which errors are logged and at which level (error, warn, info)
+- What context is included (request ID, user ID, stack trace)
+- Where errors are logged (handler layer, middleware, or both)
+- How to avoid double-logging (log at the top, wrap at the bottom)
+
+## General Rules
+
+- Language: English
+- All error types and codes must come from actual code — do not invent errors
+- Code examples must be from the project, showing real wrapping and mapping patterns
+- If the project has no custom error handling (uses raw errors only), document that and keep the file minimal
+- Do not duplicate the full error catalog if it already exists in `DOMAIN.md` §3 — cross-reference instead, but add HTTP/gRPC mapping columns
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/events.md b/.agents/skills/sdd/templates/docs/events.md
new file mode 100644
index 0000000..99627f4
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/events.md
@@ -0,0 +1,159 @@
+<!-- scope: **/events/*, **/messaging/*, **/pubsub/*, **/subscribers/*, **/producers/*, **/consumers/* -->
+# Events Documentation Template
+
+## What This Generates
+
+- `.spec/EVENTS.md` — event catalog, schemas, producers/consumers, delivery guarantees, error handling
+
+## Instructions
+
+You are a technical documentarian. Create event-driven architecture documentation for the project in the `.spec/` directory.
+Analyze: event definitions, message schemas, producer/publisher implementations, consumer/subscriber handlers, queue/topic configuration, and retry/DLQ logic.
+
+### Step 1: Identify Event System
+
+Check for the presence of:
+- **Message Brokers**: Kafka, RabbitMQ, NATS, Redis Pub/Sub, AWS SQS/SNS, Google Pub/Sub, Azure Service Bus
+- **In-Process Event Bus**: EventEmitter (Node.js), mediator pattern, domain events (DDD), Spring Events
+- **Streaming**: Kafka Streams, NATS JetStream, Redis Streams, Flink
+- **Browser/Frontend**: CustomEvent, EventTarget, RxJS Subject, Vue EventBus, React event callbacks
+- **Mobile**: Flutter Streams, BroadcastChannel, NotificationCenter (iOS), LocalBroadcastManager (Android)
+- **Webhooks**: outbound event delivery over HTTP (see also `webhooks.md` if you create a separate template)
+
+For each system found, identify: client library, connection config, serialization format (JSON, Protobuf, Avro, MessagePack).
+
+### Step 2: Create .spec/EVENTS.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: which event system(s) and why
+- Architecture pattern: event-driven, CQRS, event sourcing, pub/sub, saga/choreography
+- ASCII diagram of the event flow:
+
+```
+Producer A ──→ [Topic/Queue] ──→ Consumer X
+Producer B ──→ [Topic/Queue] ──→ Consumer Y
+                    ↓
+              [Dead Letter Queue]
+```
+
+##### 2. Event Catalog
+
+Master table of all events in the system:
+
+| Event Name | Topic / Channel | Producer | Consumer(s) | Schema | Idempotent |
+|------------|----------------|----------|-------------|--------|------------|
+| `user.created` | `users` | `UserService` | `EmailService`, `AnalyticsService` | `UserCreatedEvent` | Yes (by user_id) |
+| `order.paid` | `orders` | `PaymentGateway` | `FulfillmentService` | `OrderPaidEvent` | Yes (by order_id) |
+| `cart.updated` | in-process | `CartStore` | `CartBadge`, `CartSummary` | `CartState` | N/A |
+
+Extract from actual event publishing and subscription code — do not invent events.
+
+##### 3. Event Schemas
+
+For each event (or event group), document the payload:
+
+```typescript
+// user.created
+interface UserCreatedEvent {
+  event_id: string;        // Unique event identifier (UUID)
+  event_type: "user.created";
+  timestamp: string;       // ISO 8601
+  data: {
+    user_id: string;
+    email: string;
+    registered_via: "email" | "oauth";
+  };
+  metadata: {
+    correlation_id: string;  // Request trace ID
+    source: string;          // Producing service name
+  };
+}
+```
+
+Use the project's actual language and types. Note which fields are required vs optional.
+
+##### 4. Topics / Channels / Queues
+
+| Topic / Queue | Partitions | Retention | Consumer Group(s) | Purpose |
+|--------------|------------|-----------|-------------------|---------|
+| `users` | 3 | 7 days | `email-svc`, `analytics-svc` | User lifecycle events |
+| `orders` | 6 | 30 days | `fulfillment-svc` | Order processing |
+
+Include configuration source (env vars, config files, IaC definitions).
+
+##### 5. Producers
+
+For each producer:
+- **Location**: file path and function/method
+- **Trigger**: what causes the event to be published
+- **Serialization**: how the event is serialized before sending
+- **Error handling**: what happens if publishing fails (retry, circuit breaker, outbox pattern)
+- **Transactional outbox**: if used, describe the pattern (DB transaction + outbox table + poller)
+
+Code example of a typical producer from the project.
+
+##### 6. Consumers
+
+For each consumer:
+- **Location**: file path and function/method
+- **Concurrency**: how many concurrent consumers (worker count, partition assignment)
+- **Processing guarantee**: at-least-once, at-most-once, exactly-once
+- **Idempotency strategy**: how duplicate events are handled (idempotency key, deduplication window, upsert)
+- **Error handling**: what happens on processing failure
+- **Ordering**: does processing depend on event order? How is it guaranteed?
+
+Code example of a typical consumer from the project.
+
+##### 7. Delivery Guarantees
+
+| Guarantee | Strategy | Implementation |
+|-----------|----------|----------------|
+| At-least-once | Manual ack after processing | Consumer commits offset after handler returns |
+| Ordering | Per-key ordering | Partition key = entity ID |
+| Idempotency | Dedup by event_id | Check processed_events table before handling |
+| Exactly-once | Transactional outbox | DB transaction + outbox poller |
+
+##### 8. Dead Letter Queue (DLQ)
+
+- DLQ topic/queue name and configuration
+- When events are sent to DLQ (max retries exceeded, deserialization failure, handler exception)
+- Retry policy before DLQ: count, backoff strategy (fixed, exponential, jitter)
+- How DLQ events are monitored and reprocessed
+- Manual replay mechanism (if available)
+
+If no DLQ exists, note it explicitly and flag as a risk.
+
+##### 9. Event Versioning & Evolution
+
+- How event schemas evolve (backward-compatible additions, schema registry, version field)
+- Breaking change process: how old consumers handle new event versions
+- Schema validation: compile-time (Protobuf, Avro) or runtime (JSON Schema)
+- If no versioning strategy exists, note it and flag as a risk.
+
+##### 10. Monitoring & Observability
+
+- Consumer lag monitoring (Kafka consumer group lag, queue depth)
+- Event throughput metrics
+- Failed event alerting
+- Correlation ID / trace propagation through events
+- Dashboard links (if applicable)
+
+##### 11. Testing Events
+
+- How to test producers (unit test: event published with correct payload)
+- How to test consumers (unit test: handler processes event correctly)
+- Integration testing: in-memory broker, test containers, embedded broker
+- How to publish test events manually (CLI tool, admin endpoint, script)
+
+Code example of an event test from the project.
+
+## General Rules
+
+- Language: English
+- All events, topics, and schemas must come from actual source code — do not invent
+- If the project uses multiple event systems (e.g., Kafka for inter-service + in-process for domain events), document all and explain boundaries
+- For frontend-only event systems (CustomEvent, RxJS), adapt the template: skip DLQ, delivery guarantees, and monitoring sections
+- If the project has no event-driven patterns, do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/feature-flags.md b/.agents/skills/sdd/templates/docs/feature-flags.md
new file mode 100644
index 0000000..45c2245
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/feature-flags.md
@@ -0,0 +1,91 @@
+<!-- scope: **/*flag*, **/*toggle*, **/*feature* -->
+# Feature Flags Documentation Template
+
+## What This Generates
+
+- `.spec/FEATURE_FLAGS.md` — documents the feature flag system, flag inventory, lifecycle, and rollout strategy
+
+## Instructions
+
+Analyze the project to identify any feature flag or feature toggle system. Look for:
+- SDK imports (LaunchDarkly, Unleash, Flagsmith, Split.io)
+- Custom flag implementations (config-based, env var-based, database-based)
+- Flag evaluation calls in application code
+- A/B testing or experimentation frameworks
+
+If no feature flag system is found, **skip this template entirely** — do not generate an empty document.
+
+### File: .spec/FEATURE_FLAGS.md
+
+#### Structure:
+
+##### 1. Overview
+- **System**: which flag provider or custom implementation is used
+- **Architecture**: how flags are loaded (SDK init, config file, env vars, database table)
+- **Evaluation flow**: where in the request lifecycle flags are checked (middleware, service layer, per-handler)
+- **Default behavior**: what happens when the flag service is unavailable (fail open / fail closed)
+
+##### 2. Flag Inventory
+
+Table of all active feature flags:
+
+| Flag Name | Type | Description | Owner | Created | Expiry | Default |
+|-----------|------|-------------|-------|---------|--------|---------|
+| `enable_new_checkout` | boolean | New checkout flow | @payments | 2025-01-15 | 2025-04-15 | false |
+| `search_algorithm` | multivariate | A/B test for search | @search | 2025-02-01 | — | `v1` |
+
+Types: `boolean`, `multivariate` (string/number variants), `percentage` (0–100).
+
+Mark flags as: 🟢 Active, 🟡 Rolling out, 🔴 Scheduled for removal.
+
+##### 3. Lifecycle
+Document the flag lifecycle in this project:
+1. **Creation** — who can create flags, where they are defined, naming conventions
+2. **Rollout** — gradual rollout strategy (percentage, user segments, regions)
+3. **Stabilization** — when a flag is considered stable (metrics period, error rate threshold)
+4. **Permanent or removal** — decision criteria: does the flag become permanent config or get removed?
+5. **Removal process** — code cleanup steps, how to find all evaluation points
+
+##### 4. Implementation Pattern
+Show the code pattern used to evaluate flags in this project:
+- **Evaluation call**: actual code example from the project (e.g., `flags.IsEnabled("feature_x", user)`)
+- **Context passing**: how user/request context reaches the flag evaluation
+- **Type safety**: is there a typed wrapper or raw string keys?
+- **Fallback**: what value is returned if evaluation fails
+
+##### 5. Testing with Flags
+- **Unit tests**: how to override flag values in tests (mock, test config, env var)
+- **Integration tests**: how to test both sides of a flag (enabled and disabled)
+- **Test matrix**: which flag combinations are tested together
+- **CI behavior**: are flags forced to a specific value in CI?
+
+##### 6. Rollout Strategy
+- **Percentage rollout**: how to do gradual rollout (1% → 10% → 50% → 100%)
+- **User targeting**: can flags be enabled per user, per org, per region?
+- **Kill switch**: how to instantly disable a flag in production
+- **Monitoring**: what metrics to watch during rollout (error rate, latency, conversion)
+- **Rollback**: how to roll back a flag without a code deploy
+
+##### 7. Cleanup Policy
+- **Stale flag detection**: how to find flags that are 100% rolled out but not removed from code
+- **Linting / static analysis**: any tooling to detect dead flag references
+- **Cleanup cadence**: how often the team reviews and removes old flags
+- **Technical debt tracking**: how stale flags are tracked (issues, labels, dashboards)
+
+##### 8. Configuration
+How flags are configured per environment:
+
+| Environment | Source | Sync | Notes |
+|-------------|--------|------|-------|
+| Development | `.env` / config file | Manual | All flags enabled by default |
+| Staging | Flag service | Real-time | Mirrors production targeting |
+| Production | Flag service | Real-time | Gradual rollout rules apply |
+
+- **Local override**: how developers enable/disable flags locally
+
+## General Rules
+
+- Language: English
+- Use actual flag names and code from the project — do not invent examples
+- If no feature flag system exists, do not generate this file
+- Mark flags scheduled for removal — this document should help cleanup efforts
diff --git a/.agents/skills/sdd/templates/docs/infrastructure.md b/.agents/skills/sdd/templates/docs/infrastructure.md
new file mode 100644
index 0000000..8597407
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/infrastructure.md
@@ -0,0 +1,157 @@
+<!-- scope: **/infra/*, **/redis*, **/kafka*, **/nats* -->
+# Infrastructure Documentation Template
+
+## What This Generates
+
+One `.spec/<COMPONENT>.md` file per significant infrastructure component discovered in the project. Examples:
+- `.spec/OBSERVABILITY.md` — OpenTelemetry, Prometheus, Grafana, Jaeger, etc.
+- `.spec/REDIS.md` — Redis caching, sessions, leader election
+- `.spec/TRAEFIK.md` / `.spec/NGINX.md` — reverse proxy
+- `.spec/QUEUES.md` / `.spec/KAFKA.md` — message queues
+- `.spec/LEADER_ELECTION.md` — distributed coordination
+- `.spec/SEARCH.md` — Elasticsearch, Meilisearch, etc.
+
+## Instructions
+
+You are a technical documentarian. Create infrastructure documentation for the project in the `.spec/` directory.
+Analyze: `docker-compose.yml`, `configs/`, caching adapters, monitoring setup, proxy config, and other infrastructure components.
+
+### Step 1: Identify Infrastructure Components
+
+Check for the presence of:
+- **Observability**: OpenTelemetry, Prometheus, Grafana, Jaeger, Tempo, Loki, Datadog, New Relic, Sentry, Pyroscope
+- **Caching**: Redis, Memcached, in-memory cache
+- **Message Queues**: Kafka, RabbitMQ, NATS, Redis Pub/Sub
+- **Reverse Proxy**: Traefik, Nginx, Caddy, Envoy
+- **Search**: Elasticsearch, Meilisearch, Typesense
+- **Distributed Coordination**: Leader election, distributed locks, service discovery
+- **CDN / Object Storage**: CloudFront, Cloudflare, S3
+
+For each discovered component, create a separate `.spec/COMPONENT_NAME.md` file.
+
+### Step 2: Create Documents
+
+For each infrastructure component, use the following template:
+
+---
+
+#### Section 1: Overview
+- One sentence: what it is and why it's used
+- ASCII diagram: how the component connects to the rest of the system
+
+#### Section 2: Architecture / Components
+If the component has multiple parts (e.g., Grafana stack = Tempo + Loki + Mimir + Alloy):
+- For each part: role, configuration file, endpoints (ports)
+
+If the component is standalone (e.g., Redis):
+- Usage diagram (which services connect, what data they store)
+
+#### Section 3: Use Cases (for general-purpose components like Redis)
+Table:
+| Use Case | Key Pattern | TTL | Purpose |
+|----------|-------------|-----|---------|
+
+#### Section 4: File Structure
+```
+path/to/adapter/
+├── file1.go    # Description
+├── file2.go    # Description
+└── ...
+```
+
+#### Section 5: Interfaces
+Interface definitions from the code (contracts.go, interfaces, etc.).
+Show the full interface code.
+
+#### Section 6: Implementation Details
+
+For each use case / method:
+- Name
+- Usage example (code)
+- Configuration
+- Key parameters (TTL, retry policy, etc.)
+
+**Type-specific sections:**
+
+**For Observability (OBSERVABILITY.md):**
+- Backend Integration: how tracing/metrics are initialized in code
+- Instrumentation Layers: table (Layer | Package | Technology | Span Names)
+- Trace-Log Correlation: how trace_id gets into logs
+- Span Hierarchy Example: span tree for a typical request
+- Grafana / Dashboard access and key queries
+
+**For Cache/Redis (REDIS.md):**
+- Generic Cache API (Set/Get/Del)
+- Session Storage: keys, TTL, format
+- Cache-Aside / Read-Through pattern
+- Invalidation strategy
+- Algorithm (for leader election and similar): steps + Lua scripts
+
+**For Reverse Proxy (TRAEFIK.md / NGINX.md):**
+- Service URLs table
+- How to customize (prefixes, domains)
+- Configuration (labels, config files)
+- Ports exposed to host
+- Troubleshooting
+
+**For Message Queues (QUEUES.md / KAFKA.md):**
+- Topics / Exchanges / Subjects
+- Producer / Consumer pattern
+- Retry / DLQ policy
+- Serialization format
+
+**For Leader Election (LEADER_ELECTION.md):**
+- Algorithm (SETNX, Consul, etcd)
+- Failover scenarios
+- Heartbeat mechanism
+- Parameters table (TTL, heartbeat interval, namespace)
+
+#### Section 7: Configuration
+
+Docker Compose fragment:
+```yaml
+service_name:
+  image: ...
+  ports: ...
+  environment: ...
+  volumes: ...
+```
+
+Application config (config.yml / .env):
+```yaml
+component:
+  url: "..."
+  option: "..."
+```
+
+#### Section 8: Testing
+- How the component is tested (integration tests, test containers)
+- Test example
+
+#### Section 9: Observability (for non-tracing components)
+- How the component is traced (redisotel, otelhttp, etc.)
+- Health check
+
+#### Section 10: Verification Commands
+```bash
+# Check connection
+docker exec container_name ...
+# View data
+...
+# Monitoring
+...
+```
+
+#### Section 11: Key Files
+Table:
+| File | Description |
+|------|-------------|
+
+## General Rules
+
+- Create a separate file for each significant infrastructure component
+- If a component is trivial (1 config, no code) — do not create a separate file, mention it in `ARCHITECTURE.md`
+- All code examples and configs — from the actual project
+- Docker Compose fragments — from the actual `docker-compose.yml`
+- After creating files, update `.spec/README.md`: add links under the Infrastructure section
+- If no infrastructure components are found, do not generate any files — skip this template entirely
diff --git a/.agents/skills/sdd/templates/docs/routing.md b/.agents/skills/sdd/templates/docs/routing.md
new file mode 100644
index 0000000..614214c
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/routing.md
@@ -0,0 +1,198 @@
+<!-- scope: **/routes/*, **/router/*, **/pages/*, **/screens/*, **/navigation/* -->
+# Routing Documentation Template
+
+## What This Generates
+
+- `.spec/ROUTING.md` — route definitions, guards, layouts, navigation patterns, SSR/SSG strategy
+
+## Instructions
+
+You are a technical documentarian. Create routing and navigation documentation for the project in the `.spec/` directory.
+Analyze: router configuration, route definitions, page/screen components, navigation guards/middleware, layout wrappers, and deep link configuration.
+
+### Step 1: Identify Routing Framework
+
+Check for the presence of:
+- **React**: React Router, TanStack Router, Next.js App Router / Pages Router, Remix, Wouter
+- **Vue**: Vue Router, Nuxt routing (file-based)
+- **Angular**: Angular Router (@angular/router)
+- **Svelte**: SvelteKit file-based routing
+- **Flutter/Dart**: GoRouter, Navigator 2.0, auto_route, Beamer
+- **React Native**: React Navigation, Expo Router
+- **Solid**: Solid Router, SolidStart file-based routing
+
+Determine from imports, configuration files, and directory structure (file-based routing uses `pages/`, `app/`, `routes/`).
+
+### Step 2: Create .spec/ROUTING.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: routing framework and approach
+- Routing type: code-based, file-based, or hybrid
+- Rendering strategy: CSR, SSR, SSG, ISR, or mixed
+- ASCII diagram of the route tree (high-level):
+
+```
+/
+├── / (home)                    [public]
+├── /auth
+│   ├── /login                  [public]
+│   └── /register               [public]
+├── /dashboard                  [auth required]
+│   ├── /settings               [auth required]
+│   └── /profile                [auth required]
+├── /admin/*                    [admin role]
+└── /api/* (API routes)         [server only]
+```
+
+##### 2. Route Table
+
+Complete table of all routes:
+
+| Path | Component / Page | Auth | Roles | Layout | Method | Notes |
+|------|-----------------|------|-------|--------|--------|-------|
+| `/` | `HomePage` | No | — | `MainLayout` | GET | Landing page |
+| `/login` | `LoginPage` | No | — | `AuthLayout` | GET | Redirects if authenticated |
+| `/dashboard` | `DashboardPage` | Yes | `user` | `DashboardLayout` | GET | — |
+| `/admin/users` | `AdminUsersPage` | Yes | `admin` | `AdminLayout` | GET | — |
+| `/api/users` | — | Yes | — | — | GET, POST | API route (server only) |
+
+Extract from actual router configuration, file-based route directories, or route decorators.
+
+##### 3. Route Parameters & Query Strings
+
+| Route Pattern | Param | Type | Validation | Example |
+|--------------|-------|------|------------|---------|
+| `/users/:id` | `id` | UUID | Regex / Zod | `/users/abc-123` |
+| `/posts/:slug` | `slug` | string | — | `/posts/hello-world` |
+| `/search?q=` | `q` | string | URL encoded | `/search?q=hello` |
+
+Document how params are parsed and validated (middleware, loader, schema).
+
+##### 4. Guards / Middleware / Interceptors
+
+Navigation guards that run before route access:
+
+| Guard | Applied To | Check | On Failure |
+|-------|-----------|-------|------------|
+| `authGuard` | `/dashboard/*`, `/admin/*` | Token exists and valid | Redirect to `/login` |
+| `roleGuard` | `/admin/*` | User has `admin` role | Redirect to `/403` |
+| `onboardingGuard` | `/dashboard/*` | Profile is complete | Redirect to `/onboarding` |
+
+For each guard:
+- **Location**: file path
+- **Execution order**: in what order do guards run
+- **How applied**: route meta, middleware chain, HOC wrapper, per-route config
+
+Code example of a typical guard from the project.
+
+##### 5. Layouts & Nesting
+
+Layout hierarchy:
+
+```
+RootLayout (html, body, providers)
+├── MainLayout (header, footer, nav)
+│   ├── HomePage
+│   └── AboutPage
+├── AuthLayout (centered card, no nav)
+│   ├── LoginPage
+│   └── RegisterPage
+├── DashboardLayout (sidebar, topbar)
+│   ├── DashboardPage
+│   └── SettingsPage
+└── AdminLayout (admin sidebar)
+    └── AdminPages
+```
+
+For each layout:
+- **Location**: file path
+- **Provides**: what UI chrome it adds (header, sidebar, footer)
+- **Context / Providers**: what data it fetches or provides to children (user, theme, permissions)
+
+##### 6. Data Loading
+
+How data is loaded for routes:
+
+| Pattern | Framework Feature | When |
+|---------|-------------------|------|
+| Server loader | `loader()` (Remix), `getServerSideProps` (Next), `load()` (SvelteKit) | Before render, server-side |
+| Client fetch | `useEffect`, `onMounted`, `initState` | After mount, client-side |
+| Suspense / streaming | React Suspense, deferred data | Progressive loading |
+| Static generation | `getStaticProps`, `prerender` | Build time |
+
+For each significant route, document:
+- What data is loaded and from where (API endpoint, database, cache)
+- Loading state handling (skeleton, spinner, placeholder)
+- Error state handling (error boundary, fallback component)
+
+##### 7. Navigation Patterns
+
+How navigation is triggered:
+
+| Pattern | Implementation | Example |
+|---------|---------------|---------|
+| Declarative link | `<Link to="/about">` | Menu items, breadcrumbs |
+| Programmatic | `router.push("/dashboard")` | After form submit, auth redirect |
+| Back / history | `router.back()`, `history.back()` | Cancel buttons |
+| Replace (no history entry) | `router.replace("/login")` | Auth redirects |
+| External | `window.open(url)` | Third-party links |
+
+##### 8. Deep Links & Universal Links (Mobile / PWA)
+
+If the project supports deep linking:
+- URL scheme: `myapp://path` or `https://myapp.com/path`
+- Configuration file: `AndroidManifest.xml`, `Info.plist`, `apple-app-site-association`, `assetlinks.json`
+- Route-to-screen mapping
+- Deferred deep links (install → open at correct screen)
+- Testing: how to test deep links locally
+
+If not applicable, skip this section.
+
+##### 9. Error & Special Routes
+
+| Route | Purpose | Component |
+|-------|---------|-----------|
+| `404` / `*` | Not found | `NotFoundPage` |
+| `403` | Forbidden | `ForbiddenPage` |
+| `500` | Server error | `ErrorPage` |
+| `/maintenance` | Maintenance mode | `MaintenancePage` |
+
+How errors are caught: error boundaries, `errorElement` (React Router), `+error.svelte`, `error.tsx`.
+
+##### 10. SEO & Metadata
+
+- How page titles and meta descriptions are set per route (Head component, `generateMetadata`, `useMeta`)
+- Open Graph / social sharing meta tags
+- Canonical URLs
+- Sitemap generation (static, dynamic, `sitemap.xml`)
+- `robots.txt` configuration
+
+##### 11. Route Testing
+
+- How routes are tested (navigation tests, guard tests, loader tests)
+- Testing framework and utilities (Testing Library, Playwright, Cypress)
+- How to test protected routes (mock auth, test tokens)
+- Code example from the project
+
+##### 12. Adding a New Route
+
+Step-by-step guide:
+1. Create page/screen component
+2. Add route definition (config entry or file in `pages/`)
+3. Apply guard/middleware if needed
+4. Assign layout
+5. Add data loader (if SSR/SSG)
+6. Set page metadata (title, description)
+7. Add to navigation (menu, breadcrumbs)
+8. Write tests
+
+## General Rules
+
+- Language: English
+- All routes, guards, and layouts must come from actual source code — do not invent
+- If the project uses file-based routing, document the directory structure as the primary route definition source
+- For API-only projects (no pages/screens), do not generate this file — skip entirely
+- For Flutter/Dart, adapt terminology: Screen instead of Page, Navigator/GoRouter instead of React Router
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/security.md b/.agents/skills/sdd/templates/docs/security.md
new file mode 100644
index 0000000..6b93b0d
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/security.md
@@ -0,0 +1,209 @@
+<!-- scope: **/*security*, **/*crypto*, **/*cert* -->
+# Security Documentation Template
+
+## What This Generates
+
+- `.spec/SECURITY.md` — security model, threat boundaries, input validation, secrets management, and OWASP Top 10 mapping
+
+## Instructions
+
+You are a technical documentarian with a security focus. Create security documentation for the project in the `.spec/` directory.
+Analyze: input validation logic, authentication/authorization middleware, CORS/CSP config, rate limiting, TLS setup, secrets handling, dependency manifests, security headers.
+
+**Important**: This template focuses on the **security perspective** of the project. It cross-references `AUTH.md` (if it exists) for detailed auth flows and `DEPLOYMENT.md` for infrastructure security, but does not duplicate them. Instead, it audits and evaluates security posture.
+
+### Step 1: Identify Security Surface
+
+Map the project's security surface:
+- **Entry points**: HTTP endpoints, gRPC services, WebSocket handlers, CLI commands, message consumers
+- **Trust boundaries**: external → API gateway → backend → database, user input → validation → business logic
+- **Sensitive data**: PII fields, credentials, tokens, financial data
+- **Third-party integrations**: OAuth providers, payment systems, external APIs
+
+### Step 2: Create .spec/SECURITY.md
+
+#### Structure:
+
+##### 1. Security Overview
+
+High-level security posture:
+- One sentence: security model summary (e.g., "Token-based auth with RBAC, TLS everywhere, secrets in Vault")
+- Trust boundary diagram (ASCII):
+```
+┌─────────────────────────────────────────────┐
+│  External (untrusted)                        │
+│  ┌─────────┐    ┌──────────┐                │
+│  │ Browser │    │ Mobile   │                │
+│  └────┬────┘    └────┬─────┘                │
+│       └──────┬───────┘                       │
+├──────────────┼───────────────────────────────┤
+│  DMZ         │                               │
+│  ┌───────────▼──────────┐                   │
+│  │  Reverse Proxy / LB  │                   │
+│  └───────────┬──────────┘                   │
+├──────────────┼───────────────────────────────┤
+│  Internal (trusted)                          │
+│  ┌───────────▼──────────┐  ┌─────────────┐ │
+│  │  Application Server  │──│  Database    │ │
+│  └──────────────────────┘  └─────────────┘ │
+└─────────────────────────────────────────────┘
+```
+- List of security-critical components with file references
+
+##### 2. Input Validation
+
+Input sanitization strategy:
+- **Validation layer**: where validation happens (handler, middleware, domain, or all)
+- **Validation approach**: struct tags, validation library, manual checks
+- **Injection prevention**:
+  - SQL injection: parameterized queries? ORM? raw SQL audit
+  - XSS: output encoding, template escaping, CSP
+  - Command injection: any `exec` / `os.Command` usage? input sanitization
+  - Path traversal: file path validation
+- **Validation rules**: table of key validated inputs:
+
+| Input | Location | Validation | Sanitization |
+|-------|----------|------------|--------------|
+| email | POST /users | format, length | lowercase, trim |
+| file upload | POST /files | size, mime type | rename, virus scan |
+
+Code reference: file path where validation is implemented.
+
+##### 3. Authentication & Authorization Audit
+
+Security-focused review of auth (cross-references `AUTH.md` if it exists):
+- **Authentication strength**: password policy (min length, complexity), brute force protection (rate limit, lockout)
+- **Token security**: token type, signing algorithm, expiry times, rotation policy
+- **Session security**: HttpOnly cookies, Secure flag, SameSite, session fixation prevention
+- **Privilege escalation prevention**: horizontal (user A accessing user B's data) and vertical (user → admin)
+- **Known weaknesses or TODOs**: any `// TODO: security` comments, missing auth checks
+
+If `AUTH.md` exists, reference it for flow details and focus here on security audit findings.
+
+##### 4. Transport Security
+
+TLS and network security:
+- **TLS configuration**: version (1.2/1.3), cipher suites, certificate source (Let's Encrypt, self-signed, CA)
+- **Internal communication**: mTLS between services? plain HTTP internally?
+- **Certificate management**: how certificates are provisioned and rotated
+- **Redirect policy**: HTTP → HTTPS redirect enforced?
+
+Code/config reference for TLS setup.
+
+##### 5. CORS & CSP
+
+Cross-origin and content security policies:
+- **CORS configuration**:
+  - Allowed origins (exact list or pattern)
+  - Allowed methods and headers
+  - Credentials policy
+  - Preflight cache duration
+  - Code reference: where CORS is configured
+- **Content Security Policy** (if applicable):
+  - CSP directives (script-src, style-src, connect-src, etc.)
+  - Report-only vs enforced
+  - Where CSP header is set
+
+##### 6. Rate Limiting & Abuse Prevention
+
+- **Rate limits**: table of limits per endpoint or operation:
+
+| Scope | Limit | Window | Action |
+|-------|-------|--------|--------|
+| Login | 5 req | 1 min | 429 + lockout |
+| API global | 100 req | 1 min | 429 |
+| File upload | 10 req | 1 hour | 429 |
+
+- **Rate limit implementation**: middleware, reverse proxy, cloud WAF
+- **Headers returned**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`
+- **DDoS mitigation**: Cloudflare, AWS Shield, or application-level measures
+- **Bot protection**: CAPTCHA, proof-of-work, behavioral analysis
+
+##### 7. Secrets Management (audit only)
+
+> Operational details (inventory, storage, rotation, local dev) are owned by `deployment.md` → `DEPLOYMENT.md §8 Secrets`.
+> This section focuses on **security audit**: anti-patterns, gaps, and recommendations.
+
+- **Anti-patterns to flag**: secrets in code, secrets in git history, secrets in logs, unencrypted config files
+- **Gaps**: any secrets without rotation, any secrets accessible beyond need-to-know
+- **Recommendations**: concrete next steps to improve secrets hygiene
+
+##### 8. Data Protection
+
+Data handling and privacy:
+- **Encryption at rest**: database encryption, file storage encryption
+- **Encryption in transit**: TLS (see §4)
+- **PII handling**: which fields are PII, how they are stored, access controls
+- **Data retention**: retention periods, deletion policy, right to erasure
+- **Backup encryption**: are backups encrypted?
+- **Compliance**: GDPR, HIPAA, SOC2, PCI-DSS — which apply and how addressed
+
+If no compliance requirements exist, note that and skip the compliance subsection.
+
+##### 9. Security Headers
+
+HTTP security headers:
+
+| Header | Value | Purpose |
+|--------|-------|---------|
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` | Force HTTPS |
+| `X-Content-Type-Options` | `nosniff` | Prevent MIME sniffing |
+| `X-Frame-Options` | `DENY` | Prevent clickjacking |
+| `X-XSS-Protection` | `0` | Disable legacy XSS filter |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` | Control referrer |
+| `Permissions-Policy` | `camera=(), microphone=()` | Restrict browser features |
+
+Identify which headers are set and which are missing. Note where they are configured.
+
+##### 10. Dependency Security
+
+Third-party dependency audit:
+- **Audit tool**: `npm audit`, `govulncheck`, `pip-audit`, `cargo audit`, Snyk, Dependabot
+- **Audit command**: how to run a vulnerability scan
+- **Update policy**: how often dependencies are updated, who reviews
+- **Known vulnerabilities**: any current advisories (from the latest audit)
+- **Lock file**: is a lock file committed (`go.sum`, `package-lock.json`, `poetry.lock`)?
+- **Supply chain**: pinned versions, integrity hashes, trusted registries
+
+##### 11. OWASP Top 10 Mapping
+
+Map each OWASP Top 10 (2021) category to the project's mitigations:
+
+| # | OWASP Category | Project Mitigation | Status |
+|---|----------------|-------------------|--------|
+| A01 | Broken Access Control | RBAC middleware, ownership checks | ✅ Mitigated |
+| A02 | Cryptographic Failures | TLS 1.3, bcrypt passwords, JWT RS256 | ✅ Mitigated |
+| A03 | Injection | Parameterized queries, input validation | ✅ Mitigated |
+| A04 | Insecure Design | Threat modeling, code review | ⚠️ Partial |
+| A05 | Security Misconfiguration | Hardened defaults, no debug in prod | ✅ Mitigated |
+| A06 | Vulnerable Components | Dependabot, weekly audit | ✅ Mitigated |
+| A07 | Auth Failures | Rate limiting, MFA, strong passwords | ⚠️ Partial |
+| A08 | Data Integrity Failures | Signed deployments, CI/CD gates | ✅ Mitigated |
+| A09 | Logging & Monitoring | Structured logging, alerting | ⚠️ Partial |
+| A10 | SSRF | No user-controlled URLs / URL allowlist | ✅ Mitigated |
+
+Statuses: ✅ Mitigated, ⚠️ Partial, ❌ Not Addressed, N/A
+
+For each "Partial" or "Not Addressed": note what's missing and recommend next steps.
+
+##### 12. Incident Response (if applicable)
+
+If the project has incident response procedures or documentation:
+- **Detection**: how security incidents are detected (alerts, logs, user reports)
+- **Containment**: immediate steps (revoke tokens, block IPs, disable accounts)
+- **Communication**: who to notify, disclosure timeline
+- **Recovery**: restore from backup, re-deploy, rotate secrets
+- **Post-mortem**: how lessons learned are documented
+
+If no incident response exists, note this as a gap and suggest creating one.
+
+## General Rules
+
+- Language: English
+- This is a **security audit** template — focus on findings, gaps, and recommendations
+- Cross-reference `AUTH.md` for detailed auth flows, `DEPLOYMENT.md` for infra security — do not duplicate
+- All code references must point to actual project files
+- Never include real secrets, tokens, keys, or internal URLs — use placeholders
+- Flag security anti-patterns explicitly (e.g., "⚠️ JWT secret is hardcoded in config file")
+- If a section is not applicable (e.g., no CORS because no browser clients), state "N/A — [reason]" and skip
+- After creating, update `.spec/README.md`: add a link under the Security section
diff --git a/.agents/skills/sdd/templates/docs/state-management.md b/.agents/skills/sdd/templates/docs/state-management.md
new file mode 100644
index 0000000..4b3be82
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/state-management.md
@@ -0,0 +1,151 @@
+<!-- scope: **/store/*, **/stores/*, **/state/*, **/redux/*, **/bloc/*, **/providers/* -->
+# State Management Documentation Template
+
+## What This Generates
+
+- `.spec/STATE.md` — state management architecture, store structure, data flow, side effects
+
+## Instructions
+
+You are a technical documentarian. Create state management documentation for the project in the `.spec/` directory.
+Analyze: store definitions, reducers, actions, selectors, providers, BLoC classes, signals, and reactive state primitives.
+
+### Step 1: Identify State Management Approach
+
+Check for the presence of:
+- **React**: Redux (Toolkit), Zustand, MobX, Jotai, Recoil, Valtio, XState, React Context + useReducer
+- **Vue**: Pinia, Vuex
+- **Angular**: NgRx, Akita, Elf, simple services with RxJS
+- **Svelte**: Svelte stores (writable, readable, derived)
+- **Solid**: Solid signals, createStore
+- **Flutter/Dart**: BLoC, Provider, Riverpod, GetX, MobX
+- **Mobile (RN)**: Redux, Zustand, MobX-State-Tree
+
+Determine from `package.json`, `pubspec.yaml`, imports in source files.
+
+### Step 2: Create .spec/STATE.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: which state management solution and why
+- Architecture pattern name (Flux, CQRS, reactive, signal-based)
+- ASCII diagram of the data flow:
+
+```
+User Action → Dispatch → Store/Reducer → New State → UI Re-render
+                           ↓
+                      Side Effects (API calls, persistence)
+```
+
+Adapt the diagram to the actual pattern used (BLoC: Event → Bloc → State → Widget; Signals: Signal → Effect → Derived).
+
+##### 2. Store Structure
+
+Map of all stores / slices / blocs / atoms:
+
+| Store / Slice | Location | Purpose | Persistence |
+|---------------|----------|---------|-------------|
+| `authStore` | `src/stores/auth.ts` | User session, tokens | localStorage |
+| `cartSlice` | `src/store/cart.ts` | Shopping cart items | None (memory) |
+
+For each store, note whether it is:
+- **Global** (app-wide singleton)
+- **Scoped** (per-route, per-component tree, per-feature)
+- **Local** (component-level, not shared)
+
+##### 3. State Shape
+
+For each significant store, document the state type/interface:
+
+```typescript
+// authStore state
+interface AuthState {
+  user: User | null;       // Current authenticated user
+  token: string | null;    // JWT access token
+  isLoading: boolean;      // Auth operation in progress
+  error: string | null;    // Last auth error message
+}
+```
+
+Use the project's actual language and type definitions. Include initial/default values.
+
+##### 4. Actions / Events / Mutations
+
+For each store, list the actions that modify state:
+
+| Action / Event | Payload | Effect on State | Side Effects |
+|----------------|---------|-----------------|--------------|
+| `login` | `{email, password}` | Sets `isLoading: true` | API call to `/auth/login` |
+| `loginSuccess` | `{user, token}` | Sets `user`, `token`, `isLoading: false` | Persists token |
+| `logout` | — | Clears `user`, `token` | Removes token from storage |
+
+##### 5. Selectors / Derived State / Computed
+
+| Selector / Computed | Source | Returns | Used By |
+|---------------------|--------|---------|---------|
+| `isAuthenticated` | `authStore` | `boolean` | `ProtectedRoute`, `Header` |
+| `cartTotal` | `cartStore` | `number` | `CartSummary`, `Checkout` |
+
+##### 6. Side Effects
+
+How async operations and side effects are handled:
+- **Pattern**: thunks, sagas, epics, effects, listeners, BLoC events, async actions
+- **API integration**: how API calls are dispatched and results handled
+- **Error handling**: how API errors flow back to state
+- **Optimistic updates**: are they used? Where?
+- **Cancellation**: how in-flight requests are cancelled (e.g., route change, unmount)
+
+Code example of a typical side effect from the project.
+
+##### 7. Persistence
+
+Which parts of state are persisted and how:
+
+| Store | Medium | Key | Serialization | Hydration |
+|-------|--------|-----|---------------|-----------|
+| `auth` | localStorage | `auth_token` | JSON | On app init |
+| `settings` | AsyncStorage | `user_prefs` | JSON | On app init |
+| `cart` | sessionStorage | `cart_items` | JSON | On tab restore |
+
+If no persistence is used, state it explicitly.
+
+##### 8. Subscriptions / Reactivity
+
+How components subscribe to state changes:
+- **React**: `useSelector`, `useStore`, `useSnapshot`, custom hooks
+- **Vue**: `storeToRefs`, computed properties
+- **Flutter**: `BlocBuilder`, `Consumer`, `Watch`
+- **Svelte**: `$store` auto-subscription
+
+Performance considerations:
+- Selector memoization
+- Render optimization (shallow compare, structural sharing)
+- Common pitfalls in the project
+
+##### 9. Testing State
+
+- How stores/slices/blocs are unit tested
+- How to create test state (factories, fixtures, initial state overrides)
+- How to mock stores in component tests
+- Code example of a store test from the project
+
+##### 10. Adding a New Store
+
+Step-by-step guide for adding a new store/slice/bloc:
+1. Create the state type
+2. Define actions/events
+3. Implement reducer/handler
+4. Add selectors
+5. Connect to components
+6. Add tests
+
+Reference existing stores as examples.
+
+## General Rules
+
+- Language: English
+- All state shapes, actions, and selectors must come from actual source code
+- If the project uses multiple state management solutions (e.g., Redux for global + useState for local), document all of them and explain the boundary
+- If the project has no state management beyond component-local state, do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/explore.md b/.agents/skills/sdd/templates/explore.md
new file mode 100644
index 0000000..97ac82d
--- /dev/null
+++ b/.agents/skills/sdd/templates/explore.md
@@ -0,0 +1,212 @@
+# Phase 1: Exploration
+
+## Role
+
+You are a **Research Partner**. Your task: investigate the problem space, analyze the existing codebase, compare approaches, and help the user clarify what they actually need before committing to formal requirements.
+
+You do **NOT** write requirements documents.
+You do **NOT** design solutions or write code.
+You **explore**: ask questions, read code, compare options, surface constraints and risks.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.explore`
+- **Input artifacts:** none (this is the first phase)
+- **Output:** `.spec/features/<feature-name>/explore.md`
+
+---
+
+### Fast-track mode
+
+When the user describes a bug with a known reproduction or a small scoped change:
+
+- **Intent:** 1 paragraph (not 3–5). State the problem and the expected fix direction.
+- **Investigation (Root Cause):** confirm the bug exists AND identify root cause. Follow these steps:
+  1. **Read errors** — read the full stack trace / error log, not just the last line. Note the originating call site.
+  2. **Reproduce** — run the failing test or command yourself. Capture actual output.
+  3. **Check recent changes** — `git log --oneline -10 <affected-files>` (if git is available). Look for the commit that introduced the regression.
+  4. **Trace data flow** — follow the data path from input → processing → failure point. Cite each file and line in the chain.
+  
+  If root cause remains unclear after these steps, mark it as `[ROOT CAUSE: unknown]` and include it in Open Questions. Do NOT skip to a fix direction based on symptoms alone.
+- **Options:** single recommended approach. Skip multi-option comparison unless two genuinely different strategies exist.
+- **Scope boundaries:** list only must-have (v1). Omit deferred/spike unless the user raised them.
+- **Assumptions:** 2–3 critical assumptions max.
+- **Open questions:** omit if none. Do not fabricate questions.
+- **Build Tooling:** still required (later phases depend on it).
+
+Target artifact size: **≤ 1 page**.
+
+IMPORTANT: For bug fixes, DO NOT propose a fix direction in "Recommended Direction" until root cause is identified. A symptom-level recommendation ("the error is on line 42, let's fix it") without understanding WHY it fails leads to patches that mask the real problem.
+
+---
+
+## Language
+
+Write the entire exploration document in the **user's language** (detected from their first message). This includes:
+- Section headers (e.g., translate "Intent", "Investigation", "Options Considered", etc.)
+- All prose: problem descriptions, findings, trade-off analysis, recommendations
+- Scope boundary labels (translate "Must-have (v1)", "Deferred (v2)", "Needs spike")
+- Assumption tags: keep the marker format `[ASSUMPTION: ...]` but write the assumption text in the user's language
+
+Keep in English (do not translate):
+- Code identifiers, file paths, import paths
+- Shell commands and their output
+- Build Tooling commands (the command values — labels like "Orchestrator", "Test", "Build" may be translated)
+
+---
+
+## What To Do
+
+### Step 1: Understand Intent
+
+Ask the user:
+- What problem are they trying to solve?
+- What triggered this — a bug report, user feedback, tech debt, new feature request?
+- Is this new functionality (greenfield) or modifying existing behavior (brownfield)?
+- Is there prior art or inspiration (other tools, competitors, RFCs)?
+
+### Step 2: Investigate the Codebase
+
+Without waiting for all answers:
+
+**Project documentation shortcut:** If the project documentation directory exists (default: `.spec/`, configurable via `docs_dir` in `config.yaml`), read `README.md` first for the documentation map, then read relevant docs (`ARCHITECTURE.md`, `PACKAGES.md`, `DOMAIN.md`) before scanning source code. This provides pre-verified context and significantly reduces file-read budget consumption. If docs exist, you may need fewer than 20 raw file reads.
+
+> **Directory reminder:** You READ project documentation from `<docs_dir>/` (default: `.spec/`). You WRITE phase artifacts to `.spec/features/<feature>/`. These are separate directories — do not mix them.
+
+- Read relevant source code, configs, and tests
+- Identify existing patterns, conventions, and constraints
+
+**Budget:** Limit initial investigation to ~20 file reads. If the codebase is large and you haven't found enough context, summarize what you've learned so far and ask the user which areas to investigate deeper. This prevents context window exhaustion.
+- Find related functionality that might be affected
+- Note technical debt or risks in the affected area
+
+**If modifying existing code (brownfield):**
+- What behavior must NOT change? Identify preservation constraints.
+- What tests cover current behavior? These must keep passing.
+- What's the migration path if data structures change?
+
+**If building new (greenfield):**
+- What similar patterns already exist in the codebase? Follow them.
+- Are there shared abstractions (interfaces, base classes) to reuse?
+
+**Testing patterns (brownfield and greenfield):**
+- Identify the project's testing framework and assertion library.
+- Where do test files live? What naming convention is used?
+- Note representative test files for later phases to follow as style references.
+
+**Build tooling discovery (brownfield and greenfield):**
+- Identify the project's command orchestrator: check for `Makefile`, `Taskfile.yml` (`taskfile.yml`), `package.json` scripts section, `Justfile`, or similar.
+- Extract key commands for: **test**, **build**, **lint**, **generate** (code generation), **start**, **stop**.
+- If a `Makefile` or `Taskfile` exists, read it and list the relevant targets.
+- If `package.json` exists, read the `scripts` section.
+- Note code generation commands (proto, OpenAPI, mocks, ORM generators) — these must run before tests.
+- Document the orchestrator and commands in the exploration output (see Build Tooling section in Output Format).
+
+### Step 3: Compare Approaches
+
+If multiple solutions exist:
+- List 2–4 realistic options
+- For each: brief description, pros, cons, estimated complexity
+- Highlight trade-offs explicitly (e.g., "simpler but less extensible")
+
+### Step 4: Surface Constraints
+
+Proactively identify:
+- Breaking changes or backward compatibility concerns
+- Performance implications
+- Security considerations
+- Dependencies that would be added or affected
+- Edge cases that aren't obvious
+
+### Step 5: Recommend Direction
+
+Based on investigation, suggest:
+- Which approach seems best and why
+- What questions remain unanswered
+- **What assumptions your recommendation depends on** — list them explicitly and ask the user to confirm or correct before proceeding
+
+**Scope Boundaries** — explicitly categorize:
+- **Must-have (v1):** essential for the feature to be useful
+- **Deferred (v2):** valuable but not required for initial delivery
+- **Needs spike:** risky or unknown, requires investigation before committing
+
+---
+
+## Output Format
+
+Generate an exploration document with this structure:
+
+```markdown
+# Exploration: <Feature Name>
+
+## Intent
+What problem we're solving and why.
+
+## Investigation
+What was examined in the codebase. Key findings about existing code, patterns, constraints.
+
+## Root Cause
+<!-- Bug fixes only. Omit for pure features. -->
+Identified root cause of the defect: what is broken and why. Cite the originating file, line, and commit (if found).
+If unknown: `[ROOT CAUSE: unknown]` — explain what was investigated and why cause remains unclear.
+
+## Build Tooling
+- **Orchestrator:** make / task / npm scripts / custom scripts / none
+- **Test:** `<command>`
+- **Build:** `<command>`
+- **Lint:** `<command>`
+- **Generate:** `<command>` (if applicable — proto, mocks, ORM, etc.)
+- **Source:** Makefile / Taskfile.yml / package.json / CI config / ...
+
+## Options Considered
+### Option A: ...
+- Description, pros, cons, complexity.
+### Option B: ...
+- Description, pros, cons, complexity.
+
+## Constraints & Risks
+- Breaking changes, security, performance, dependencies.
+
+## Recommended Direction
+Which option and why.
+
+## Scope Boundaries
+- **Must-have (v1):** ...
+- **Deferred (v2):** ...
+- **Needs spike:** ...
+
+## Assumptions & Open Questions
+Explicit assumptions behind the recommendation. Open questions that need clarification before requirements.
+```
+
+---
+
+## Quality Checklist
+
+Before presenting to the user:
+- [ ] Codebase was actually read (not just guessed about)
+- [ ] At least 2 options were considered (unless truly only one path exists)
+- [ ] Trade-offs are explicit, not hidden
+- [ ] Scope boundaries are suggested
+- [ ] Assumptions behind the recommendation are stated explicitly
+- [ ] Open questions are listed (if any)
+- [ ] For bug fixes: root cause is identified and cited, or explicitly marked `[ROOT CAUSE: unknown]`
+- [ ] Build Tooling section is present with orchestrator and key commands (test, build, lint; generate if applicable)
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Codebase was actually read — file paths and findings are cited, not guessed.
+2. At least 2 options were compared (or a single-path justification is documented).
+3. Scope boundaries are explicitly categorized: **Must-have (v1)**, **Deferred (v2)**, **Needs spike**.
+4. Every assumption behind the recommendation is tagged with `[ASSUMPTION: ...]`.
+5. Open questions section is present (even if the answer is "None identified").
+6. For bug fixes: root cause is documented — either identified with file/line citation, or explicitly marked `[ROOT CAUSE: unknown]` with investigation summary.
+7. Build Tooling section is present — orchestrator identified, key commands (test, build, lint) documented.
+8. Artifact is registered via `pipeline.sh artifact <path>`.
+
+## Antipatterns
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Explore.
diff --git a/.agents/skills/sdd/templates/implementation.md b/.agents/skills/sdd/templates/implementation.md
new file mode 100644
index 0000000..078e19a
--- /dev/null
+++ b/.agents/skills/sdd/templates/implementation.md
@@ -0,0 +1,280 @@
+# Phase 5: Implementation
+
+> **For AI agents (Cursor, Claude Code, Windsurf, etc.):**
+> Read this file in full before starting. Follow every instruction exactly.
+> Your role is to execute the approved task plan — write tests, write code, run, iterate.
+
+---
+
+## Role
+
+You are a **TDD Implementation Executor**. Your task: take the approved task plan and execute it — write real tests, write real production code, run the suite, and iterate until everything is green.
+
+You do **NOT** create new tasks or modify the plan. You **execute** the tasks exactly as specified.
+You do **NOT** skip tasks. You do **NOT** reorder tasks (unless a dependency requires it and you document why).
+You **write code** and **run tests** for every task.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.implementation`
+- **Input artifacts:** read `history[0..3].artifact` (exploration, requirements, design, task plan). Read the **task plan** (`history[3]`) carefully — it defines the exact sequence of tasks to execute.
+- **Output:** `.spec/features/<feature-name>/implementation.md`
+
+---
+
+### Fast-track mode
+
+When the task plan contains 4–5 tasks for a small bug fix:
+
+- **Summary:** 1 paragraph (bug description + fix approach).
+- **Task Execution:** 1–2 lines per task — status and brief note only. Skip detailed iteration logs unless a task required retry.
+- **Final Verification:** still required — actual stdout from test, build, lint commands. No shortcuts here.
+- **Files Changed:** list of modified/created files (typically 1–3).
+
+Target artifact size: **≤ 0.5 page** (excluding stdout).
+
+---
+
+## Language
+
+Write the implementation report in the **user's language** (detected from their first message). This includes:
+- Section headers, task status descriptions, notes on issues found
+- Summary of what was done
+
+Keep in English (do not translate):
+- Code identifiers, file paths, shell commands
+- Test names, assertion messages
+- Task IDs: `T-N`
+- Instruction keywords: `CRITICAL`, `IMPORTANT`, `NOTE`, `DO NOT`, `GOAL`
+
+---
+
+## What To Do
+
+### Step 1: Read the Task Plan
+
+Read the approved task plan artifact. Extract:
+- **Commands** block — the exact commands for test, build, lint, generate
+- **Test Style Source** — the test style reference files
+- **Task list** — the ordered sequence of tasks (`T-1`, `T-2`, etc.)
+
+**Resume check:** Run `pipeline.sh status`. If `Last task` is shown (e.g., `T-4`), skip all tasks up to and including that task — they were completed in a previous session. Resume from the next task.
+
+### Step 1.5: Evaluate Execution Strategy
+
+After reading the task plan, decide whether to use **sequential mode** (default) or **subagent mode**.
+
+**Consider subagent mode when ALL three conditions are true:**
+1. The plan contains **6+ top-level tasks**
+2. At least one task has `Complexity: complex`
+3. Your platform supports **dispatching isolated subagents** (e.g., Claude Code `Task` tool, Cursor Composer, or equivalent)
+
+If any condition is not met — use sequential mode (Step 2 as-is). Sequential is always safe.
+
+**Subagent mode architecture:**
+
+You become a **controller**. For each task `T-N` in order:
+1. **Build a context package** — extract from the task plan:
+   - The single task `T-N` with all subtasks, `_Requirements_`, `_Preservation_`, `_Complexity_`
+   - Commands block and Test Style Source (copied verbatim)
+   - File paths referenced in subtasks
+   - One-line summary of each previously completed task (not full reports)
+2. **Dispatch a subagent** with this context package as input
+3. **Receive the subagent's report** — changed files, test stdout, any issues
+4. **Verify** — run the full test suite yourself. If tests fail, fix or escalate (same rules as Step 4)
+5. **Mark done** — `pipeline.sh task T-N`, update the implementation report
+
+**Subagent rules:**
+- One subagent per task — never bundle multiple `T-N` into one dispatch
+- Subagent does NOT interact with `pipeline.sh` — only the controller does
+- Task order remains strict (RED → GREEN → CODE → VERIFY → GATE) — parallelize only if tasks have zero shared files and no `_Preservation_` overlap
+- GATE task is always executed by the controller, never delegated
+- If a subagent fails after 3 attempts, apply the same rollback rules as Step 4
+
+NOTE: If you are unsure whether your platform supports subagents, use sequential mode. The output is identical — only the execution strategy differs.
+
+### Step 2: Execute Each Task
+
+For each task in order:
+
+#### 2.1 Exploration Tests (RED)
+
+If the task is an exploration test:
+1. Write the test exactly as described in the task
+2. Run the test command — confirm it **fails** (RED)
+3. If it passes instead of failing, the problem may already be fixed — note this and proceed
+4. Mark the task as done in the artifact (see Step 3)
+
+#### 2.2 Preservation Tests (GREEN)
+
+If the task is a preservation test:
+1. Write the test exactly as described in the task
+2. Run the test command — confirm it **passes** (GREEN)
+3. If it fails, there's a pre-existing bug — note this and ask the user before proceeding
+4. Mark the task as done in the artifact
+
+#### 2.3 Implementation Tasks (Code Changes)
+
+If the task is an implementation task:
+1. Read the task's `GOAL`, instructions, and `_Preservation_` list
+2. Make the minimal atomic change described
+3. Run the full test suite — confirm:
+   - The exploration test now **passes** (GREEN)
+   - All preservation tests still **pass** (GREEN)
+   - No other tests broke
+4. If tests fail, iterate:
+   - Diagnose the failure
+   - Adjust the implementation (not the tests, unless the test is wrong)
+   - Re-run until green
+5. Mark the task as done in the artifact
+
+#### 2.4 Re-test / Checkpoint Tasks
+
+If the task is a re-test or checkpoint:
+1. Run the specified commands
+2. Verify the expected outcome
+3. Mark the task as done in the artifact
+
+### Step 3: Mark Tasks Done
+
+After completing each task, update the implementation report artifact by marking the task as completed:
+
+```markdown
+- [x] **T-1** Exploration test: verify current behavior — RED confirmed
+- [x] **T-2** Preservation test: lock auth flow — GREEN confirmed
+- [x] **T-3** Implement token refresh — GREEN (all tests pass)
+- [ ] **T-4** Re-test full suite — (next)
+```
+
+**Rules for marking:**
+- Use `[x]` for completed tasks, `[ ]` for pending
+- Add a brief status note after the task title (e.g., "RED confirmed", "GREEN (3 tests pass)", "needed adjustment — see notes")
+- If a task required iteration (fix → re-run), note what was adjusted
+- After writing `[x]`, register in this order:
+  1. `sh ./scripts/pipeline.sh artifact` — saves the updated report
+  2. `sh ./scripts/pipeline.sh task T-N` — records last completed task for resume
+
+### Step 4: Handle Failures
+
+If a task cannot be completed:
+- **Test won't compile** — check imports, dependencies, code generation. Run `generate` command if available.
+- **Exploration test passes when it should fail** — the behavior may already be correct. Note it and proceed.
+- **Preservation test fails** — pre-existing bug. Note it and ask the user: "Preservation test T-N fails on existing code. This is a pre-existing issue. Proceed or fix first?"
+- **Implementation breaks other tests** — iterate on the implementation. Do NOT modify preservation tests.
+- **Blocked by dependency** — note the blocker, skip the task, continue with independent tasks. Return to blocked task when unblocked.
+
+#### Task rollback on repeated failure
+
+If an implementation task fails after **3 attempts** (3 iterations of adjust → re-run without reaching green):
+
+1. **Stop** — do not continue iterating.
+2. **Document** the situation in the implementation report:
+   - Task ID and title
+   - What was attempted (3 approaches tried)
+   - Which files were modified during attempts
+   - Current state: which tests pass, which fail
+3. **Present the user** with options:
+   - **(a) Revert this task's files** — `git checkout HEAD -- <file1> <file2> ...` to undo changes from the failed task only. Then continue with the next independent task.
+   - **(b) Debug together** — the user helps investigate the issue. Provide the failing test output and relevant code context.
+   - **(c) Full rollback** — `git checkout <review_base_commit> -- .` to restore the entire working tree to the state before implementation started. This undoes ALL tasks, not just the failed one.
+4. **Wait** for the user's decision before proceeding.
+
+CRITICAL: Do NOT silently leave the project in a broken state. If tests are failing after implementation attempts, the user must be informed and given control.
+
+### Step 5: Final Verification
+
+After all tasks are complete:
+1. Run the **full test suite** — all tests must pass
+2. Run the **build** command — must succeed
+3. Run the **lint** command — must pass (or only pre-existing warnings)
+4. Run **generate** command if applicable — ensure generated code is up to date
+5. Update the implementation report with final results
+
+---
+
+## Output Format
+
+Generate an implementation report with this structure:
+
+```markdown
+# Implementation Report: <Feature Name>
+
+## Summary
+Brief description of what was implemented. Number of tasks completed.
+
+## Commands Used
+- **Test:** `<command>`
+- **Build:** `<command>`
+- **Lint:** `<command>`
+- **Generate:** `<command>` (if applicable)
+
+## Task Execution
+
+- [x] **T-1** <task title> — <status>
+- [x] **T-2** <task title> — <status>
+- [x] **T-3** <task title> — <status>
+  - Note: <any adjustments or iteration notes>
+- [x] **T-4** <task title> — <status>
+...
+
+## Final Verification
+
+Include the actual (possibly truncated) stdout of each command below. Do NOT replace real output with status assertions like "All pass".
+
+```
+- **Tests:**
+\`\`\`
+<paste last 20 lines of test command output>
+\`\`\`
+- **Build:**
+\`\`\`
+<paste last 10 lines of build command output>
+\`\`\`
+- **Lint:**
+\`\`\`
+<paste last 10 lines of lint command output>
+\`\`\`
+- **Generate:** (if applicable)
+\`\`\`
+<paste last 10 lines of generate command output>
+\`\`\`
+```
+
+## Files Changed
+List of files created or modified during implementation.
+
+## Notes
+Any observations, pre-existing issues found, or deviations from the plan.
+```
+
+---
+
+## Quality Checklist
+
+Before presenting to the user:
+- [ ] Every task from the plan is marked (completed or explicitly skipped with reason)
+- [ ] All exploration tests confirmed RED before implementation
+- [ ] All preservation tests confirmed GREEN before and after implementation
+- [ ] Full test suite passes after all tasks
+- [ ] Build succeeds
+- [ ] Lint passes (or only pre-existing warnings)
+- [ ] Implementation report artifact is registered via `pipeline.sh artifact`
+- [ ] No tasks were silently skipped
+- [ ] Final Verification section contains actual command output (stdout), not just status assertions
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Every task from the approved plan is executed and marked in the artifact.
+2. Full test suite passes — zero new failures.
+3. Build command succeeds.
+4. Lint command passes (pre-existing warnings are acceptable, new ones are not).
+5. Implementation report lists all files changed.
+6. Artifact is registered via `pipeline.sh artifact`.
+7. Final Verification section contains real command output (stdout) for test, build, and lint.
+
+## Antipatterns
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Implementation.
diff --git a/.agents/skills/sdd/templates/reference/antipatterns.md b/.agents/skills/sdd/templates/reference/antipatterns.md
new file mode 100644
index 0000000..09f89cd
--- /dev/null
+++ b/.agents/skills/sdd/templates/reference/antipatterns.md
@@ -0,0 +1,103 @@
+# Antipatterns Reference
+
+Antipattern tables for each pipeline phase. Referenced from the corresponding phase template.
+
+---
+
+## Explore
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| Premature requirements | "WHEN token expires, system SHALL refresh" | "One option is to auto-refresh tokens" | WHEN/SHALL belongs in requirements phase |
+| Solution attachment | "We should use Redis" | "Option A: Redis, Option B: in-memory — trade-offs:..." | Must show alternatives before committing |
+| Ignoring existing code | "I suggest adding a new auth module" | "Existing `src/auth` uses X pattern; we can extend it" | Always read codebase first |
+| Scope creep | "We should also add rate limiting and logging" | "Rate limiting could be v2; focus on core auth first" | Help user narrow, not expand |
+| Analysis paralysis | 5 options with no recommendation | "Option B is best because...; A is fallback if..." | Recommend clearly when path is evident |
+| Symptom-level fix | "Bug confirmed at line 42, let's fix it" | "Root cause: `validate()` skips nil check added in commit abc123; line 42 fails because input is nil" | Without root cause, fix may mask the real problem |
+
+---
+
+## Requirements
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| Architectural solution | "Use a Redis cache for token storage" | "WHEN cache miss occurs, SHALL return fresh data within 100ms" | Prescribes HOW, not WHAT |
+| Code or pseudocode | `if token.expired { refresh() }` | "WHEN token is expired, SHALL attempt refresh" | Implementation detail |
+| Diagram | Mermaid sequence diagram | Prose description of the flow | Belongs in design phase |
+| Vague wording | "The system should handle errors gracefully" | "WHEN refresh fails, SHALL return 401 with error code" | Not verifiable |
+| Combined SHALLs | "…SHALL refresh the token and log the event" | Two REQs: one for refresh, one for logging | Must be one SHALL per REQ |
+| Unconfirmed requirement | Agent adds REQ-3.1 user never mentioned | Only requirements confirmed by user in interview | Hallucinated scope |
+| Technology lock-in | "Use JWT with RS256 signing" | "WHEN issuing tokens, SHALL use cryptographic signing" | Constrains design without user mandate |
+
+---
+
+## Design
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| Function bodies | `func refresh() { cache.Get(key)... }` | `func refresh(token Token) (Token, error)` | Interfaces show signatures only |
+| Task lists | "Step 1: create file, Step 2: add tests" | Architecture + interfaces + properties | This is design, not work breakdown |
+| Skipping unchanged files | "Files NOT Requiring Changes" table is empty | Explicitly list files in scope that won't change | Omission suggests scope not fully considered |
+| Existential properties | "There exists a case where refresh works" | "For all expired tokens, refresh returns valid token" | Properties must use universal quantifier |
+| Unlinked properties | "Property 3: tokens are secure" | "Property 3: ... Validates: REQ-1.2" | Every property must trace to a requirement |
+| Vague modification scope | `[MODIFIED]` — "various authentication changes" | `[MODIFIED]` — "adds refreshToken(), modifies authenticate() return type" | Must state what exactly changes |
+| Scope creep | Designing rate limiting not in requirements | Only design what requirements specify | Stay within approved requirements |
+| Silent assumption | Choosing a caching strategy without stating why | `[ASSUMPTION: write-through preferred]` — ask user or mark explicitly | Unstated beliefs cause surprises during implementation |
+| Ignoring existing test patterns | Agent invents new test structure (e.g., flat assertions) | Agent follows existing pattern: `auth/token_test.go:TestRefresh` uses table-driven subtests | Tests must be consistent with the project's existing style |
+
+---
+
+## Task Plan
+
+| Antipattern | Why it's harmful |
+|---|---|
+| Writing code in the plan | The plan is instructions for an agent, not the implementation itself |
+| Designing architecture in the plan | Architecture is fixed in the approved design document — do not revise it here |
+| Skipping exploration tests for bug fixes | Without a failing test, you cannot prove the bug existed or was fixed |
+| Tasks without `*_Requirements:_*` | Untraced tasks cannot be reviewed or rejected with precision |
+| Multi-file subtasks | Atomic subtasks are the unit of change — mixing files makes review and fixing harder |
+| Forgetting re-test tasks | A fix without a passing re-test is unverified |
+| Placing the checkpoint before all tasks complete | The checkpoint is a gate, not a milestone |
+| Vague task descriptions | "Update the code" is not a task. "Add null check to `parseToken` in auth module" is a task |
+| Inventing test style | When adjacent tests use table-driven subtests, do not write flat assertions. Follow existing project test patterns discovered in Test Infrastructure Discovery |
+
+---
+
+## Implementation
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| Skipping exploration test | Write code first, then test | Write test first (RED), then code (GREEN) | TDD requires RED→GREEN cycle |
+| Modifying preservation tests | Change test to match new code | Change code to satisfy both old and new tests | Preservation tests lock correct behavior |
+| Bulk implementation | Implement all tasks at once, test at the end | Implement one task, test, mark done, repeat | Atomic execution finds issues early |
+| Silent skip | Skip a failing task without noting it | Note the issue, ask user, document decision | Transparency over speed |
+| Plan modification | "This task doesn't make sense, I'll do it differently" | Execute as planned; note concerns for review phase | The plan was approved — execute it faithfully |
+| Silently leaving broken state | Continue to next task while tests are failing | Stop after 3 failed attempts, document state, ask user to decide | User must stay in control when implementation is stuck |
+| Unsupervised subagent | Dispatch subagent, accept its output without running tests | Dispatch subagent, then run full test suite yourself before marking task done | Subagent output must be verified — trust but verify |
+
+---
+
+## Review
+
+| Antipattern | Why it's harmful |
+|---|---|
+| Skipping the implementation report | The implementation report (history[4]) shows which tasks were completed — always verify against it |
+| Reviewing the entire codebase | Scope is limited to files changed since `review_base_commit` |
+| Approving with `major` findings open | Major findings must be resolved before `PASS` verdict |
+| Changing the design in the review | Design is locked in the approved design document — open a new pipeline for design changes |
+| Skipping the traceability matrix | Without it, requirements coverage cannot be verified |
+| Inventing requirements during review | Review checks against approved requirements only — new requirements need a new pipeline |
+| Flagging style preferences as `major` | Style preferences are `nit` at most; reserve `major` for real issues |
+| Auto-fixing without user direction | Review is for presenting findings to the user, not for autonomous code changes. Wait for explicit user instructions before modifying code |
+
+---
+
+## Documentation (Standalone Workflow)
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| All templates in one window | Generate `core.md` + `development.md` + `auth.md` + ... back-to-back in a single chat | Use `pipeline.sh docs-init` + queue; one template per iteration (sequential) or up to 3 parallel subagents | Single-chat batch generation exhausts context; agent starts hallucinating, dropping rules, and truncating output |
+| Sequential when subagent available | Loop `docs-next` / `docs-done` in one chat when your toolset has Task/Composer/dispatch tool | Use SUBAGENT mode — dispatch up to 3 templates in parallel; controller verifies metadata after each | Subagent dispatch isolates per-template context, prevents controller bloat, and parallelizes independent work |
+| Bundled subagent dispatch | "Subagent, generate `core.md`, `development.md`, and `auth.md`" | One subagent = one template; dispatch 3 separate subagents in parallel | Bundling defeats isolation; subagent context fills up the same way single-chat batch does |
+| Skipping metadata verification | Call `docs-done <template>` immediately after subagent reports success | After subagent finishes, controller verifies file exists, line 1 matches `<!-- generated: YYYY-MM-DD, template: <name>.md -->`, and file is non-trivial (≥ 50 lines) — only then `docs-done` | `docs-check` silently skips files with malformed metadata; missed verification = stale detection broken forever |
+| Running `init <feature>` for docs request | User says "обнови документацию" → agent runs `pipeline.sh init update-docs` | Run `pipeline.sh docs-init --update` (or `--all` for bootstrap) — the standalone workflow is independent from feature pipelines | Documentation generation does not need 6 phases, approval gates, or `.spec/features/<feature>/` — it is a separate state machine |
diff --git a/.agents/skills/sdd/templates/reference/correctness-properties-examples.md b/.agents/skills/sdd/templates/reference/correctness-properties-examples.md
new file mode 100644
index 0000000..421df84
--- /dev/null
+++ b/.agents/skills/sdd/templates/reference/correctness-properties-examples.md
@@ -0,0 +1,120 @@
+# Correctness Properties — Worked Examples
+
+Worked examples for each Correctness Property category. Referenced from `design.md` §2.6.
+
+Each example shows (1) a requirement, (2) the §2.6 property definition, (3) the §2.8 property-based test table entry, and (4) what the generator does.
+
+---
+
+## Equivalence
+
+Suppose REQ-1.1 says: *WHEN the system receives a valid token, it SHALL return the corresponding user profile.*
+
+**§2.6 definition:**
+
+```
+Property 1: Token-to-profile resolution
+Category: Equivalence
+Statement: For all valid tokens T issued for user U, resolveProfile(T) = profile(U)
+Validates: Requirements 1.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_token_resolves_to_owner_profile` | Property 1 | Generate random valid User, issue a token for that user, resolve profile via token | `Property/1` |
+
+The generator creates a random user, issues a token, and asserts that resolving the token returns the same user's profile. This verifies the equivalence property across many random inputs.
+
+---
+
+## Absence
+
+Suppose REQ-2.1 says: *WHEN processing a payment, the system SHALL never charge the user twice for the same order.*
+
+**§2.6 definition:**
+
+```
+Property 2: No duplicate charges
+Category: Absence
+Statement: For all orders O processed concurrently, chargeCount(O) = 1
+Validates: Requirements 2.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_no_duplicate_charges` | Property 2 | Generate random Order, simulate N concurrent payment attempts for that order, count successful charges | `Property/2` |
+
+The generator creates a random order, fires multiple concurrent payment requests, and asserts the total charge count is exactly 1. This verifies the absence of duplicate charges under concurrency.
+
+---
+
+## Round-trip
+
+Suppose REQ-3.1 says: *WHEN the system serializes a configuration, it SHALL be able to deserialize it back to an identical value.*
+
+**§2.6 definition:**
+
+```
+Property 3: Config serialization round-trip
+Category: Round-trip
+Statement: For all valid configurations C, deserialize(serialize(C)) = C
+Validates: Requirements 3.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_config_roundtrip` | Property 3 | Generate random valid Config with varied field types, serialize to storage format, deserialize back | `Property/3` |
+
+The generator creates a random valid configuration, serializes it, deserializes the result, and asserts structural equality with the original. This verifies no data loss or mutation during the round-trip.
+
+---
+
+## Propagation
+
+Suppose REQ-4.1 says: *WHEN a user changes their email, the system SHALL update the email in all notification subscriptions.*
+
+**§2.6 definition:**
+
+```
+Property 4: Email propagation to subscriptions
+Category: Propagation
+Statement: For all users U and new emails E, after updateEmail(U, E), every subscription of U has email = E
+Validates: Requirements 4.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_email_propagates_to_subscriptions` | Property 4 | Generate random User with 1–10 subscriptions, update email to a new random value, inspect all subscriptions | `Property/4` |
+
+The generator creates a user with multiple subscriptions, changes the user's email, and asserts every subscription reflects the new address. This verifies the change propagates to all dependent records.
+
+---
+
+## Exclusion
+
+Suppose REQ-5.1 says: *WHEN an account is suspended, the system SHALL reject all login attempts.*
+
+**§2.6 definition:**
+
+```
+Property 5: Suspended accounts cannot be active
+Category: Exclusion
+Statement: For all accounts A, suspended(A) and activeSession(A) are never both true
+Validates: Requirements 5.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_suspended_blocks_login` | Property 5 | Generate random Account, suspend it, attempt login, inspect account state and session | `Property/5` |
+
+The generator creates a random account, suspends it, attempts a login, and asserts that login fails and no active session exists. This verifies the two states are mutually exclusive.
diff --git a/.agents/skills/sdd/templates/reference/review-reference.md b/.agents/skills/sdd/templates/reference/review-reference.md
new file mode 100644
index 0000000..45b90f1
--- /dev/null
+++ b/.agents/skills/sdd/templates/reference/review-reference.md
@@ -0,0 +1,14 @@
+# Review Phase — Extended Reference
+
+Severity definitions for the Review phase. Referenced from `review.md`.
+
+---
+
+## Severity Definitions
+
+| Severity | Meaning |
+|----------|---------|
+| `critical` | Must fix before merge — security hole, data loss risk, core requirement unmet |
+| `major` | Must fix before merge — missing test, design deviation, significant quality issue |
+| `minor` | Should fix — naming, minor style issue, missing edge case test |
+| `nit` | Optional — cosmetic, preference-based suggestion |
diff --git a/.agents/skills/sdd/templates/reference/task-types.md b/.agents/skills/sdd/templates/reference/task-types.md
new file mode 100644
index 0000000..b5edba7
--- /dev/null
+++ b/.agents/skills/sdd/templates/reference/task-types.md
@@ -0,0 +1,123 @@
+# Task Type Templates
+
+Templates for each task type in the TDD implementation plan. Referenced from `task-plan.md`.
+
+---
+
+## RED: Exploration Test (for bug fixes)
+
+> GOAL: Demonstrate the defect exists before any fix is applied.
+
+```
+### Task: Write exploration test for <defect description>
+
+*_Requirements: X.Y_*
+*_Bug_Condition: <condition that triggers the bug>_*
+*_Expected_Behavior: <what should happen instead>_*
+
+CRITICAL: This test MUST FAIL when run against the unmodified codebase.
+IMPORTANT: Do not fix anything yet. The test exists only to confirm the bug is reproducible.
+IMPORTANT: Follow the test style identified in Test Infrastructure Discovery. Match naming, structure, assertion patterns, and helpers from the reference tests.
+DO NOT: Write more than one test in this task. One defect = one exploration test.
+
+Instructions:
+1. Using the testing framework, write a test that directly exercises the defective path.
+2. Run: `<test command>`
+3. Confirm the test fails with the expected failure message.
+4. Commit the failing test as evidence of the defect.
+```
+
+---
+
+## GREEN: Preservation Test
+
+> GOAL: Lock correct behavior in areas adjacent to the change so it cannot be accidentally broken.
+
+NOTE: For **pure new features** with no existing code in the affected area, GREEN tasks test that existing system behavior (e.g., other endpoints, unrelated modules) is NOT broken by the introduction of new code. If no existing behavior is affected, this step may produce zero tasks — document this explicitly in the plan with a note: "No preservation tests needed — feature is fully additive with no adjacent behavior to protect."
+
+```
+### Task: Write preservation tests for <component or behavior>
+
+*_Requirements: X.Y_*
+
+IMPORTANT: These tests must pass BEFORE any implementation changes are made.
+IMPORTANT: Follow the test style identified in Test Infrastructure Discovery. Match naming, structure, assertion patterns, and helpers from the reference tests.
+NOTE: Preservation tests cover behavior where the bug does NOT manifest — they define the "safe zone" around your change.
+DO NOT: Modify production code during this task.
+
+Instructions:
+1. Identify all behaviors in the affected component that must remain unchanged.
+2. For each behavior, write a test using the testing framework.
+3. Run: `<test command>`
+4. All preservation tests must pass (GREEN). If any fail, stop and investigate.
+5. Commit the preservation tests before touching production code.
+```
+
+---
+
+## CODE: Implementation Task
+
+> GOAL: Make the minimal atomic change that satisfies the failing exploration test without breaking preservation tests.
+
+```
+### Task: Implement <specific change>
+
+*_Requirements: X.Y_*
+*_Preservation: <list of correctness properties that must hold>_*
+
+CRITICAL: Change only the file specified in this subtask. One subtask = one file.
+IMPORTANT: After each subtask, run `<test command>` to confirm no preservation tests regress.
+IMPORTANT: If Command Discovery identified code generation commands, add a subtask to run the generate command BEFORE any compilation or test subtasks when the task modifies files that are inputs to code generation (e.g., proto files, OpenAPI specs, SQL schemas, interface definitions for mock generation).
+DO NOT: Refactor unrelated code. DO NOT introduce new abstractions not in the design document.
+
+Subtasks:
+- [ ] 1. <Action in file A> — `<test command>`
+- [ ] 2. <Action in file B> — `<test command>`
+- [ ] 3. <Action in file C> — `<test command>`
+
+After all subtasks: Run `<build command>` and `<lint command>` to confirm no compilation or style errors.
+```
+
+---
+
+## VERIFY: Re-test
+
+> GOAL: Confirm the exploration test now passes after the implementation.
+
+```
+### Task: Re-run exploration test for <defect description>
+
+*_Requirements: X.Y_*
+
+CRITICAL: This is the SAME test written in RED. Do not modify it.
+GOAL: The test must now pass (GREEN). If it still fails, the implementation is incomplete.
+
+Instructions:
+1. Run: `<test command> <exploration-test-name>`
+2. Confirm the test passes.
+3. Run the full suite: `<test command>`
+4. Confirm all preservation tests still pass.
+```
+
+---
+
+## GATE: Checkpoint
+
+> GOAL: Verify the entire implementation is complete, all tests pass, and all requirements are covered.
+
+```
+### Task: Checkpoint — verify full coverage
+
+*_Requirements: ALL_*
+
+CRITICAL: This task must be the LAST task in the plan. Do not add it before all other tasks are complete.
+
+Instructions:
+1. Run the full test suite: `<test command>`
+2. Confirm 100% of tests pass (GREEN).
+3. Run: `<build command>` — confirm no errors.
+4. Run: `<lint command>` — confirm no violations.
+5. Review the coverage matrix and confirm every requirement has at least one passing test.
+6. Confirm no orphan tasks remain (every task traceable to a requirement).
+7. If any check fails, return to the appropriate task — do not mark this checkpoint complete.
+```
diff --git a/.agents/skills/sdd/templates/requirements.md b/.agents/skills/sdd/templates/requirements.md
new file mode 100644
index 0000000..4fbd7ff
--- /dev/null
+++ b/.agents/skills/sdd/templates/requirements.md
@@ -0,0 +1,302 @@
+# Phase 2: Requirements
+
+> **For AI agents (Cursor, Claude Code, Windsurf, etc.):**
+> Read this file in full before interacting with the user. Follow every instruction exactly.
+> Your role is to collect requirements — not to design solutions or write code.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.requirements`
+- **Input artifacts:** read `history[0].artifact` (exploration document) for context on what was investigated
+- **Output:** `.spec/features/<feature-name>/requirements.md`
+
+---
+
+### Fast-track mode
+
+When the exploration artifact indicates a small bug fix with known reproduction:
+
+- **Interview:** skip if the bug reproduction and expected behavior are already clear from exploration. If anything is ambiguous, ask 1–2 targeted questions (not the full interview).
+- **Overview:** 2–3 sentences.
+- **Requirements:** 1–2 REQs only (e.g., fix behavior + error case). Each still uses `WHEN/SHALL` format.
+- **Glossary:** omit unless a new domain term was introduced.
+- **User Stories:** omit (bug fix = no end-user role change).
+- **Topological Order:** omit.
+
+Target artifact size: **≤ 1 page**.
+
+---
+
+## Language
+
+Write the requirements document and conduct the interview in the **user's language** (detected from their first message). This includes:
+- Section headers (translate "Overview", "Glossary", "User Stories", etc.)
+- All prose: overview, user stories, interview questions and summaries, open design questions, conflict resolutions
+- Glossary term names (may be in user's language); the **Code Artifact** column always references real code identifiers
+- The conditions and outcomes inside `WHEN/SHALL` sentences (e.g., `**REQ-1.1** WHEN срок действия токена истёк, the system SHALL выполнить одну попытку обновления перед возвратом ошибки.`)
+
+Keep in English (do not translate):
+- `WHEN` and `SHALL` keywords — they are formal grammar identifiers
+- `the system` phrase between condition and outcome
+- Requirement IDs: `REQ-X.Y`
+- Verification Commands table: action labels (`Test`, `Build`, `Lint`, `Generate`) may be translated, but commands must be verbatim
+- Code identifiers, file paths, shell commands
+
+---
+
+## Role
+
+You are a **Requirements Engineer**. Your task: through a structured interview with the user, gather the full context of a feature or task and transform it into a formal requirements document.
+
+- You do **NOT** design solutions.
+- You do **NOT** write code or pseudocode.
+- You capture **WHAT** must be done, not **HOW**.
+
+---
+
+## Step 1: Feature Interview (Context Gathering)
+
+### Questioning Strategy
+
+Before generating the document, you **MUST** conduct a structured interview. Ask questions in groups of **3–5**, progressing through the layers below. Do not ask all layers at once — wait for the user's response before moving to the next layer.
+
+After each round, summarize your understanding:
+
+> "My understanding: [summary]. Correct?"
+
+Only proceed to Phase 2 once the user confirms the summary.
+
+---
+
+### Layer 1: Context and Motivation
+
+- What project or repository is this for?
+- What currently works incorrectly or is missing? *(current behavior)*
+- What should work after this change? *(desired behavior)*
+- Are there external users or downstream systems affected by this change?
+- Is a breaking change acceptable?
+
+### Layer 2: Scope Boundaries
+
+- Which components, modules, or files are expected to be affected?
+- Which components **must not** change?
+- Are there dependencies between parts of this task?
+- Can this task be split into independent deliverables?
+
+### Layer 3: Constraints and Edge Cases
+
+- What errors or failure modes are possible?
+- How should each error be handled?
+- Are there any conflicting requirements?
+- What are the default values for configurable parameters?
+- What does "not set" or "empty" mean in this context?
+- Are there technology, platform, or environment constraints?
+- Are there latency, throughput, memory, or resource usage constraints?
+- Are there rate limits or quotas to respect?
+
+### Layer 4: Verification
+
+- How will you verify the task is complete?
+- What tests already exist that must keep passing?
+- What commands are used to run the build, linter, and test suite?
+- Is there a `Makefile`, `Taskfile`, or `package.json` scripts section that defines these commands?
+- Are there code generation steps that must run before tests (proto, mocks, ORM generators)?
+
+> **Important:** Capture the exact commands from the user or from the exploration document's Build Tooling section. These will be used verbatim in the design and implementation phases.
+
+---
+
+### Interview Rules
+
+1. **Skip obvious questions.** Do not ask for information the user has already provided.
+2. **Proceed directly if exhaustive.** If the user's initial description is complete, confirm your understanding and move to generation without a full interview.
+3. **Group questions thematically.** Never ask questions one at a time across multiple messages when they belong to the same layer.
+4. **Summarize after each round.** State your current understanding and ask the user to confirm or correct it before continuing.
+5. **No solution proposals.** If the user drifts toward solutions, acknowledge and redirect: *"Noted — let's make sure I have the full requirements first."*
+
+---
+
+## Step 2: Requirements Document Generation
+
+Once the interview is complete and the user has confirmed the summary, generate the requirements document using the structure below.
+
+---
+
+### 2.1 Title and Overview
+
+```
+# [Feature Name] — Requirements
+
+**Status:** Draft | In Review | Approved
+**Author:** [agent or user name]
+**Date:** YYYY-MM-DD
+
+## Overview
+One-paragraph summary of the feature, its motivation, and the affected area of the system.
+```
+
+---
+
+### 2.2 Glossary
+
+Include this section only if the feature introduces domain-specific or project-specific terms. Every term listed here must appear in at least one requirement (§2.4).
+
+| Term | Definition | Code Artifact |
+|------|------------|---------------|
+| `TokenCache` | In-memory store for short-lived authentication tokens | `src/auth/cache` |
+| `RefreshPolicy` | Rules that govern when a token is considered stale | `src/auth/policy` |
+
+> **Code Artifact** column: reference the relevant file, module, package, class, or directory — whatever is most precise for the project's language and structure.
+
+---
+
+### 2.3 User Stories
+
+Include this section only if the feature has an end-user or operator perspective. Use standard format:
+
+```
+As a [role], I want [capability] so that [benefit].
+```
+
+Examples:
+- As an **API consumer**, I want token refresh to happen automatically so that my requests are not interrupted by expiry errors.
+- As a **system operator**, I want all authentication failures to be logged with a correlation ID so that I can trace incidents.
+
+---
+
+### 2.4 Requirements
+
+Use **WHEN/SHALL** grammar. Each requirement must:
+
+- Contain **exactly one SHALL**
+- Have a **verifiable WHEN** condition
+- Cover both the happy path and at least one negative/error case
+- Be numbered with continuous `X.Y` notation
+
+**Format:**
+```
+**REQ-1.1** WHEN [verifiable condition], the system SHALL [observable, testable outcome].
+```
+
+**Example block:**
+```
+**REQ-1.1** WHEN a request arrives with an expired token, the system SHALL attempt one silent refresh before returning an error to the caller.
+
+**REQ-1.2** WHEN the refresh attempt fails, the system SHALL return HTTP 401 with error code `TOKEN_REFRESH_FAILED` and log the failure at ERROR level.
+
+**REQ-1.3** WHEN the refresh succeeds, the system SHALL update the token cache at `src/auth/cache` and transparently retry the original request.
+
+**REQ-2.1** WHEN the token TTL configuration is not set, the system SHALL default to 3600 seconds.
+```
+
+**Rules:**
+- One SHALL per requirement — split combined behaviors into separate REQs.
+- No architectural decisions, data structures, or implementation hints.
+- Negative cases (errors, missing values, timeouts) must be explicitly covered.
+- All numbering must be continuous — no gaps.
+
+---
+
+### 2.5 Topological Order
+
+Include this section only if requirements have dependencies (i.e., one cannot be verified until another is in place).
+
+List the required implementation order and state the reason:
+
+```
+REQ-1.1 → REQ-1.2 → REQ-1.3
+Reason: Refresh logic (1.1) must exist before failure handling (1.2) and retry behavior (1.3) can be verified.
+
+REQ-2.1 (independent — can be implemented in parallel)
+```
+
+---
+
+### 2.6 Conflict Priority
+
+Include this section only if two or more requirements are in tension with each other.
+
+State the conflict and the resolution rule:
+
+```
+REQ-1.2 (fail fast on refresh error) conflicts with REQ-1.1 (attempt silent refresh).
+Resolution: Silent refresh (REQ-1.1) takes priority; fail-fast applies only after the single retry is exhausted.
+```
+
+---
+
+### 2.7 Open Design Questions [IF APPLICABLE]
+
+Include this section if the requirements surface questions that cannot be answered without architectural decisions. Do **not** answer these questions — flag them for the design phase.
+
+| Question | Why It Matters | Impacted Requirements |
+|----------|---------------|----------------------|
+| Should token cache be distributed or in-memory? | Affects scalability and deployment | REQ-1.1, REQ-1.3 |
+| Per-request or per-session authentication? | Affects security model and UX | REQ-2.1 |
+
+**Rules:**
+- Only include questions that genuinely require design-level decisions
+- Do not propose answers — that's the designer's job
+- Link each question to the requirements it affects
+
+---
+
+### 2.8 Verification Commands [REQUIRED]
+
+Capture the exact commands used to verify the implementation. Source these from the exploration document's Build Tooling section, the user's answers in Layer 4, or directly from project files (`Makefile`, `Taskfile.yml`, `package.json` scripts).
+
+```
+## Verification Commands
+
+| Action   | Command          | Source                     |
+|----------|------------------|----------------------------|
+| Test     | `<command>`      | Makefile / Taskfile / ...  |
+| Build    | `<command>`      | Makefile / Taskfile / ...  |
+| Lint     | `<command>`      | Makefile / Taskfile / ...  |
+| Generate | `<command>`      | Makefile / Taskfile / ...  |
+```
+
+**Rules:**
+- The **Generate** row is required only if the project uses code generation (proto, mocks, ORM, etc.).
+- Commands must be exact and runnable — not descriptions.
+- If the exploration document contains a Build Tooling section, prefer those commands.
+- If commands are unknown, ask the user explicitly during the Layer 4 interview.
+
+---
+
+## Quality Control Checklist
+
+Before delivering the document to the user, verify every item:
+
+- [ ] Every glossary term is used in at least one requirement
+- [ ] Every requirement contains exactly one SHALL
+- [ ] Every WHEN condition is observable and verifiable
+- [ ] Every SHALL outcome is observable and verifiable
+- [ ] Negative cases and error paths are covered
+- [ ] Requirement numbering is continuous with no gaps
+- [ ] If dependencies exist, §2.5 Topological Order is present
+- [ ] If conflicts exist, §2.6 Conflict Priority is present
+- [ ] If design questions exist, §2.7 Open Design Questions is present
+- [ ] The document is self-contained — no unexplained terms or dangling references
+- [ ] No implementation decisions, code, or pseudocode appear anywhere in the document
+- [ ] §2.8 Verification Commands contains exact, runnable commands for test, build, and lint
+
+---
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Every requirement uses `WHEN/SHALL` grammar with exactly one `SHALL`.
+2. Negative and error cases are covered for each functional group.
+3. Requirement numbering is continuous — no gaps in `X.Y` sequence.
+4. Every glossary term appears in at least one requirement (or glossary is omitted).
+5. User confirmed the interview summary before the document was generated.
+6. Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Antipatterns — What This Document Must Never Contain
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Requirements.
diff --git a/.agents/skills/sdd/templates/review.md b/.agents/skills/sdd/templates/review.md
new file mode 100644
index 0000000..d57a0e8
--- /dev/null
+++ b/.agents/skills/sdd/templates/review.md
@@ -0,0 +1,351 @@
+# Phase 6: Code Review
+
+## Role
+
+You are a **Code Reviewer**. Your task: accept all five approved artifacts (exploration, requirements, design, task plan, implementation report) and review the **written code** against them — verifying requirements traceability, design conformance, code quality, and security.
+
+You produce a review document with findings and a verdict. You do **NOT** fix code autonomously. Present findings to the user and wait for instructions — the same approval model as all other phases.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.review`
+- **Input artifacts:** read `history[0..4].artifact` (exploration, requirements, design, task plan, implementation report). Also read `review_base_commit` — git commit hash recorded when task plan was approved (the baseline for `git diff`).
+- **Output:** `.spec/features/<feature-name>/review.md`
+
+---
+
+### Fast-track mode
+
+When reviewing a small bug fix (1–2 REQs, 1–3 changed files):
+
+- **Change Set Discovery:** 1–3 rows (mostly ✅ Planned).
+- **Requirements Traceability:** 1–2 rows (1–2 REQs).
+- **Design Conformance:** brief per subsection. "No changes" for subsections with no impact.
+- **Code Quality & Security:** brief. If the fix is internal logic only: "No new endpoints, no user input changes."
+- **Findings:** 0–2 expected.
+- **Verification Evidence:** still required — **agent must re-run commands**, not copy from implementation report.
+
+Target artifact size: **≤ 1 page** (excluding stdout).
+
+---
+
+## Language
+
+Write the review document in the **user's language** (detected from their first message). This includes:
+- Section headers (translate "Change Set Discovery", "Requirements Traceability Audit", etc.)
+- Finding descriptions and recommendations
+- Verdict explanation
+
+Keep in English (do not translate):
+- Instruction keywords: `CRITICAL`, `IMPORTANT`, `NOTE`, `DO NOT`, `GOAL`
+- Requirement IDs: `REQ-X.Y`, Task IDs: `T-N`, Finding IDs: `F-N`
+- Correctness Property IDs: `CP-N`
+- Code identifiers, file paths, shell commands
+- Verdict labels: `PASS`, `NEEDS_CHANGES`, `BLOCK`
+- Severity labels: `critical`, `major`, `minor`, `nit`
+
+---
+
+## Step 0: Fresh Verification
+
+Before analyzing any code, **re-run test, build, and lint yourself** to establish a ground-truth baseline.
+
+1. Read the `Commands` block from the task plan (history[3].artifact).
+2. Execute each command (test, build, lint) and capture stdout.
+3. Record the results — these become the Verification Evidence baseline.
+
+NOTE: The Verification Evidence section in the final review document uses this same stdout. You do not re-run commands a second time — Step 0 output IS the Verification Evidence.
+4. If any command **fails**, record an immediate `critical` finding (`F-0: Pre-review verification failure`) and include the failure output. Continue the review — do NOT stop — but the verdict cannot be `PASS` until this is resolved.
+
+CRITICAL: You MUST run the commands yourself during this review session. DO NOT copy or reuse stdout from the implementation report (history[4]). The implementation report is the agent's self-assessment; the review must independently verify.
+
+---
+
+## Step 1: Change Set Discovery
+
+Determine which files were changed during implementation.
+
+### Primary source: git diff
+
+If `review_base_commit` is present in `pipeline.json`:
+
+```sh
+git diff --name-only <review_base_commit>..HEAD
+git diff --stat <review_base_commit>..HEAD
+```
+
+IMPORTANT: If `review_base_commit` is empty or git is unavailable, fall back to the secondary source.
+
+### Secondary source: task plan
+
+Extract the list of files from the task plan (CODE subtasks) and the design document §2.3 ("Files Requiring Changes").
+
+### Cross-reference
+
+1. **Planned vs Actual** — compare the file list from the task plan with the actual changed files.
+2. **Unexpected files** — files changed but NOT in the plan. For each, determine: is it a justified dependency, scope creep, or accidental change?
+3. **Not changed** — files in the plan that were NOT changed. For each, determine: was the task skipped, was it unnecessary, or is it an omission?
+
+Output a table:
+
+| File | Status | Notes |
+|------|--------|-------|
+| `path/to/file.go` | ✅ Planned | — |
+| `path/to/other.go` | ⚠️ Unexpected | Explain why |
+| `path/to/skipped.go` | ❌ Not Changed | Explain impact |
+
+Also cross-reference with the implementation report (history[4]) to verify that all tasks marked `[x]` actually produced the expected file changes.
+
+---
+
+## Step 2: Requirements Traceability Audit
+
+For each requirement in the requirements document, verify implementation:
+
+1. **Read each `REQ-X.Y`** from the approved requirements document.
+2. **Locate the test(s)** — find the test(s) that exercise this requirement (cross-reference with task plan task annotations `*_Requirements: X.Y_*`).
+3. **Locate the code** — find the production code that implements this requirement.
+4. **Verify correctness property** — check that the corresponding correctness property from the design document §2.6 holds in the implementation.
+
+Output a traceability matrix:
+
+| Requirement | Test(s) | Code | CP | Verdict |
+|-------------|---------|------|----|---------|
+| REQ-1.1 | `test_login_success` | `auth/handler.go:45` | CP-1 | ✅ |
+| REQ-1.2 | (none found) | `auth/handler.go:78` | CP-2 | ❌ Missing test |
+| REQ-2.1 | `test_token_refresh` | `auth/token.go:12` | CP-3 | ⚠️ Partial |
+
+CRITICAL: Every requirement MUST appear in the matrix. A requirement without a corresponding test is a finding.
+
+---
+
+## Step 3: Design Conformance
+
+Verify the implementation matches the approved design document:
+
+### 3.1 Architectural Boundaries
+
+- Do new components reside in the correct layers/packages as specified in the design?
+- Are dependencies between components flowing in the correct direction?
+- Are there any unauthorized cross-layer imports?
+
+### 3.2 Data Models
+
+- Do struct/class definitions match the data models in the design document §2.5?
+- Are field names, types, and constraints consistent?
+- Are database migrations (if any) consistent with the schema in the design?
+
+### 3.3 API Contracts
+
+- Do endpoint signatures match the design document §2.3?
+- Are request/response formats consistent?
+- Are error codes and error formats as specified?
+
+### 3.4 Error Handling
+
+- Does the implementation follow the error handling strategy from the design document?
+- Are errors wrapped/propagated as specified?
+- Are all error paths from the design covered?
+
+### 3.5 Correctness Properties
+
+For each correctness property in the design document §2.6:
+- **Equivalence** — are bidirectional transformations inverse?
+- **Absence** — are negative conditions properly rejected?
+- **Round-trip** — does serialize→deserialize (or similar) preserve data?
+- **Propagation** — do changes propagate through the expected chain?
+- **Exclusion** — are mutually exclusive states enforced?
+
+NOTE: Not all categories apply to every feature. Only review properties listed in the design.
+
+### 3.6 Documentation Consistency
+
+- Do Mermaid diagrams in the design document (§2.2) match the actual code structure?
+- Are component/package names in diagrams consistent with actual names in the codebase?
+- If the design document describes data flows, do they match actual function calls / message passing?
+- Are any new components introduced during implementation missing from diagrams?
+
+---
+
+## Step 4: Code Quality
+
+Review the changed files for quality issues. Focus on the diff, not the entire codebase.
+
+### 4.1 Naming & Clarity
+
+- Do new identifiers follow project naming conventions?
+- Are names descriptive and consistent with the existing codebase?
+
+### 4.2 Dead Code & Debug Artifacts
+
+- Are there commented-out code blocks, `TODO`s without tickets, or debug `print`/`log` statements?
+- Are there unused imports, variables, or functions?
+
+### 4.3 Scope Creep
+
+- Does the implementation contain changes beyond what was specified in the requirements and design?
+- Are there refactors, feature additions, or "improvements" not in the plan?
+
+### 4.4 Test Quality
+
+- Do tests actually assert the correct behavior (not just "no error")?
+- Are test names descriptive?
+- Do tests follow the patterns from Test Infrastructure Discovery (task plan)?
+- Are edge cases from the requirements document covered?
+
+---
+
+## Step 5: Security Scan
+
+IMPORTANT: Scope this scan to **changed files + the full request handling chain for any new public API endpoints** exposed by the changed code. This is NOT a full security audit — but new endpoints must be traced from routing through middleware, authentication, authorization, handler, and response.
+
+Review changes against common vulnerability categories:
+
+| Category | What to check |
+|----------|---------------|
+| Input validation | Are all external inputs validated/sanitized? |
+| Authentication | Are auth checks present on new endpoints? |
+| Authorization | Are permission checks correct for the user's role? |
+| Injection | SQL injection, command injection, XSS in templates? |
+| Secrets | Are secrets, tokens, or credentials hardcoded? |
+| Data exposure | Are sensitive fields excluded from API responses/logs? |
+| Error leakage | Do error messages expose internal details? |
+| API chain audit | For new endpoints: verify the full routing → middleware → auth → handler → response chain is secure |
+
+NOTE: For existing code, only flag issues present in changed files. For **new endpoints**, audit the full request chain even if some files in the chain were not modified (e.g., verify middleware applies to the new route).
+
+---
+
+## Review Document Structure
+
+The final artifact must contain these sections:
+
+```markdown
+# Code Review: <feature-name>
+
+## Verdict: <PASS | NEEDS_CHANGES | BLOCK>
+
+<One-paragraph summary explaining the verdict.>
+
+## Change Set
+
+<Table from Phase 1>
+
+## Requirements Traceability
+
+<Matrix from Phase 2>
+
+## Design Conformance
+
+<Findings from Phase 3, organized by subsection>
+
+## Code Quality
+
+<Findings from Phase 4>
+
+## Security
+
+<Findings from Phase 5, or "No security issues found in changed files.">
+
+## Verification Evidence
+
+Actual (truncated) output of commands **re-run by the reviewer during this review session**. DO NOT reuse stdout from the implementation report (history[4]). DO NOT replace with status assertions.
+
+- **Tests:**
+\`\`\`
+<paste last 20 lines of test command output>
+\`\`\`
+- **Build:**
+\`\`\`
+<paste last 10 lines of build command output>
+\`\`\`
+- **Lint:**
+\`\`\`
+<paste last 10 lines of lint command output>
+\`\`\`
+
+## Findings
+
+| ID | Severity | File | Description | Requirement |
+|----|----------|------|-------------|-------------|
+| F-1 | critical | `path/file.go:42` | Description | REQ-1.1 |
+| F-2 | major | `path/other.go:15` | Description | REQ-2.1 |
+| F-3 | minor | `path/util.go:88` | Description | — |
+
+## Recommendations
+
+<Ordered list of recommended changes, grouped by severity.>
+```
+
+---
+
+## Verdict Rules
+
+| Verdict | Condition |
+|---------|-----------|
+| `PASS` | Zero `critical` or `major` findings. All requirements traced to tests and code. |
+| `NEEDS_CHANGES` | One or more `major` findings, OR requirements with missing tests/code. No `critical` findings. |
+| `BLOCK` | One or more `critical` findings (security vulnerability, missing core requirement, architectural violation). |
+
+### Severity Definitions
+
+Severity definitions: read `./templates/reference/review-reference.md`.
+
+---
+
+## When Verdict ≠ PASS
+
+If the verdict is `NEEDS_CHANGES` or `BLOCK`:
+
+1. **Present the review document** to the user with the findings table and recommendations.
+2. **Wait for user instructions.** The user may:
+   - Ask you to fix specific findings → fix them → generate a new review → present again
+   - Approve as-is with known issues → `pipeline.sh approve`
+   - Discuss findings before deciding
+3. **If the user asks you to fix findings:** apply changes, then re-execute Steps 0–5 and generate a new review document. Register the new revision: `pipeline.sh artifact <path>`. Present to the user again.
+4. Each iteration is saved as a revision. Use `pipeline.sh revisions review` to see past iterations.
+
+CRITICAL: Do NOT fix code without explicit user instruction.
+CRITICAL: Do NOT auto-approve. Wait for the user to say "approve".
+
+---
+
+## Quality Control Checklist
+
+Before delivering the review, verify:
+
+- [ ] Change Set Discovery is complete — all changed files are listed with planned/unexpected/missing status.
+- [ ] Requirements Traceability matrix is complete — every `REQ-X.Y` from the requirements document has an entry.
+- [ ] Every requirement has at least one test linked. Missing tests are flagged as findings.
+- [ ] Design conformance is checked: architectural boundaries, data models, API contracts, error handling, correctness properties.
+- [ ] Code quality is reviewed: naming, dead code, scope creep, test quality.
+- [ ] Security scan covers changed files for input validation, auth, injection, secrets, data exposure, error leakage. New endpoint chains are audited end-to-end.
+- [ ] All findings have an ID (`F-N`), severity, file reference, and description.
+- [ ] Verdict is correct per the verdict rules.
+- [ ] If verdict ≠ `PASS`: findings and recommendations are clearly presented for user decision.
+- [ ] Each revision is saved via `pipeline.sh artifact <path>`.
+- [ ] Verification Evidence section contains actual command output (stdout), not assertions.
+- [ ] Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Change set is fully documented (planned, unexpected, missing files).
+2. Requirements traceability matrix covers all `REQ-X.Y` entries.
+3. Design conformance review is complete for all applicable subsections (§3.1–§3.6).
+4. Code quality review is complete.
+5. Security scan of changed files is complete.
+6. Findings table lists all issues with ID, severity, file, and description.
+7. Verdict is determined per Verdict Rules.
+8. Verification Evidence section contains real command output (stdout) for test, build, and lint.
+9. Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Antipatterns — Never Do These
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Review.
diff --git a/.agents/skills/sdd/templates/task-plan.md b/.agents/skills/sdd/templates/task-plan.md
new file mode 100644
index 0000000..2b2d9e2
--- /dev/null
+++ b/.agents/skills/sdd/templates/task-plan.md
@@ -0,0 +1,296 @@
+# Phase 4: Task Plan
+
+## Role
+
+You are a TDD Implementation Planner. Your task: accept the approved requirements and design documents and transform them into a step-by-step implementation plan following Test-Driven Development methodology.
+
+You do **NOT** write code. You do **NOT** design architecture. You create a sequence of atomic tasks, each linked to requirements and correctness properties.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.task-plan`
+- **Input artifacts:** read `history[0..2].artifact` (exploration, requirements, design). Read all before generating the plan.
+- **Output:** `.spec/features/<feature-name>/task-plan.md`
+
+---
+
+### Fast-track mode
+
+When the design artifact covers a small bug fix (1–2 REQs, 2–3 CPs):
+
+- **Coverage matrix:** 1–2 rows (maps directly from the 1–2 REQs).
+- **Work type:** always "Bug fix — known reproduction".
+- **Task order:** follow bug-fix sequence: RED → GREEN → CODE → VERIFY → GATE.
+- **Task count:** 4–5 top-level tasks: 1 exploration test, 0–1 preservation tests, 1–2 code tasks, 1 verify, 1 gate.
+- **Subtask granularity:** 2–4 subtasks per top-level task (vs. typical 4–6).
+- **Test Style Source + Commands:** still required (keep brief).
+
+Target artifact size: **≤ 1 page**.
+
+---
+
+## Language
+
+Write the implementation plan in the **user's language** (detected from their first message). This includes:
+- Section headers (translate "Coverage Matrix", "Work Type Classification", etc.)
+- Task titles and descriptions (e.g., "Написать exploration-тест для сбоя авторизации")
+- Coverage matrix descriptions (Requirement IDs `REQ-X.Y` and Task IDs `T-N` stay as-is)
+- The text after instruction keywords (e.g., `CRITICAL: этот тест ДОЛЖЕН упасть при запуске на немодифицированной кодовой базе.`)
+
+Keep in English (do not translate):
+- Instruction keywords: `CRITICAL`, `IMPORTANT`, `NOTE`, `DO NOT`, `GOAL`
+- Requirement IDs: `REQ-X.Y`, Task IDs: `T-N`, Correctness Property IDs: `CP-N`
+- Commands block values (commands must be verbatim)
+- Code identifiers, file paths, test names
+- Task type labels: `RED`, `GREEN`, `CODE`, `VERIFY`, `GATE`
+- Test Style Source tier labels: `Tier 1`, `Tier 2`, `Tier 3`
+
+---
+
+## Step 1: Input Document Analysis
+
+Before generating any tasks, analyze both input documents:
+
+1. **Read correctness properties** — identify all invariants, contracts, and expected behaviors defined in the design document (§2.6).
+2. **Read the design document** — understand the architectural decisions, component boundaries, and data flows that implementation must respect.
+3. **Build a coverage matrix** — map every requirement to a task and a correctness property. Present the coverage matrix: `Requirement → Task → Correctness Property`.
+
+   Format the coverage matrix as a table:
+
+   | Requirement | Task(s) | Correctness Property |
+   |-------------|---------|----------------------|
+   | REQ-1.1     | T-1, T-3 | CP-1 (round-trip)   |
+   | REQ-1.2     | T-2     | CP-2 (absence)       |
+   | REQ-2.1     | T-4     | CP-3 (equivalence)   |
+
+   Every requirement must appear at least once. Every correctness property must be linked to at least one task.
+
+4. **Determine the work type** — classify the work before planning. If any requirement is ambiguous for task planning, list the ambiguity and ask the user for clarification before generating tasks:
+   - **Bug fix** — a defect in existing behavior that violates a correctness property.
+   - **Pure feature** — new behavior with no prior implementation to preserve.
+   - **Migration** — restructuring existing behavior without changing observable outputs.
+
+The work type determines the task order (see Task Order Rules below).
+
+> **Terminology note:** *Work type* (bug fix, pure feature, migration) classifies the OVERALL work and determines which task types appear and in what order. *Task types* (RED, GREEN, CODE, VERIFY, GATE) define WHAT each individual task does. These are orthogonal: e.g., a bug fix uses RED → GREEN → CODE → VERIFY → GATE; a pure feature uses GREEN → CODE → GREEN → GATE.
+
+**How to classify the work type:**
+- If requirements describe **existing behavior that is incorrect** or violates a correctness property → **Bug fix**.
+- If requirements describe **new capability with no prior implementation** → **Pure feature**.
+- If requirements describe **restructuring existing behavior** (changing data formats, API contracts, internal architecture) **without changing observable outputs** → **Migration**.
+- If the work type is unclear from the requirements and design documents, **ask the user to clarify** before proceeding. Do not silently default.
+
+5. **Test Infrastructure Discovery** — before generating ANY test tasks, determine the test style source:
+
+   **Priority cascade:**
+   1. **Dedicated test skill** — if `.spec/config.yaml` contains `test_skill: <name>`, delegate test generation to that skill. Pass Correctness Properties (§2.6 from design doc) and the Coverage Matrix as input. The skill owns test task creation; your plan references it instead of specifying test details.
+   2. **Adjacent existing tests** — if `config.yaml` contains `test_reference: <paths/glob>`, use those files. Otherwise, scan test files adjacent to affected modules (from design doc §2.3 file list). Read 2–3 representative tests and document:
+      - Framework and assertion library
+      - Naming convention (e.g., `TestXxx`, `test_xxx`, `describe/it`)
+      - Structure (table-driven, subtests, fixtures, setup/teardown)
+      - Helper functions and shared utilities
+      - Mock/stub strategy
+
+      **Fallback if no adjacent tests found:** broaden the search — check the parent directory, then project-wide test directories (e.g., `tests/`, `__tests__/`, `*_test.*`), then CI configuration files (`.github/workflows/*.yml`, `.gitlab-ci.yml`) for test commands and patterns. If tests are found at a broader scope, use them as the reference. Only fall through to Tier 3 if no tests exist anywhere in the project.
+   3. **From scratch** — only if no test skill is configured AND no adjacent tests exist. Document the absence explicitly and use the Testing Strategy from design doc §2.8 as the sole guide.
+
+   **Output:** Include a `Test Style Source` block as preamble to the implementation plan:
+
+   ```markdown
+   **Test Style Source:** Tier <1|2|3>
+   - <Evidence: skill name / reference test file paths / "no adjacent tests found">
+   - <Key patterns to follow, if Tier 2>
+   ```
+
+   All test tasks (RED, GREEN) MUST follow the patterns identified here.
+
+6. **Command Discovery** — before generating ANY tasks, resolve the concrete commands for test, build, lint, and code generation. Do NOT use generic placeholders (`<test command>`, `<build command>`, `<lint command>`) in the final plan — resolve them to real project commands.
+
+   **Priority cascade:**
+   1. **Design document §2.8** — if the design document contains a "Project Commands" table, use those commands verbatim.
+   2. **Requirements document §2.8** — if the design doc lacks commands, read the Verification Commands table from the requirements document.
+   3. **Exploration document** — read the "Build Tooling" section from the exploration document.
+   4. **Project documentation** — if `.spec/TOOLS.md` exists (or `<docs_dir>/TOOLS.md`), read the Quick Reference table for commands.
+   5. **Direct file discovery** — read the project's `Makefile`, `Taskfile.yml` (`taskfile.yml`), `package.json` scripts, or `Justfile` to extract commands.
+   6. **Ask the user** — only if none of the above sources provide the commands.
+
+   **Output:** Include a `Commands` block as preamble to the implementation plan (alongside the `Test Style Source` block):
+
+   ```markdown
+   **Commands:**
+   | Action   | Command          | Source                     |
+   |----------|------------------|----------------------------|
+   | Test     | `make test`      | Makefile                   |
+   | Build    | `make build`     | Makefile                   |
+   | Lint     | `make lint`      | Makefile                   |
+   | Generate | `make generate`  | Makefile                   |
+   ```
+
+   > The **Generate** row is required only if the project uses code generation (proto, mocks, ORM generators, etc.).
+
+   All tasks in the plan MUST use the resolved commands from this block — never generic placeholders.
+
+---
+
+## Step 2: Implementation Plan Generation
+
+Use the **Observation-First TDD** methodology:
+
+1. **Exploration test (RED)** — write a test that demonstrates the current broken or missing behavior. It must fail before any implementation change.
+2. **Preservation tests (GREEN)** — observe and lock existing correct behavior in areas adjacent to the change. These tests must pass before, during, and after implementation.
+3. **Implementation** — make atomic changes to satisfy the failing test without breaking preservation tests.
+4. **Re-test (GREEN)** — re-run the exploration test and confirm it now passes.
+5. **Checkpoint** — verify the entire test suite passes and all requirements are covered.
+
+---
+
+## Task Structure
+
+Every task must follow this structure:
+
+### Required Fields
+
+- **Title** — action-oriented: `<Verb> <Object>` (e.g., "Write exploration test for login failure", "Implement token validation middleware")
+- ***_Requirements: X.Y_*** — one or more requirement IDs from the requirements document that this task satisfies
+- ***_Preservation:_*** — (implementation tasks only) list of correctness properties that must remain unbroken
+
+### Optional Fields
+
+- ***_Bug_Condition:_*** — for bug fix tasks: describe the condition that triggers the defect
+- ***_Expected_Behavior:_*** — for bug fix tasks: describe what correct behavior looks like
+- ***_Test_Style:_*** — for test tasks (RED, GREEN): reference to the test style source — either the skill name (Tier 1) or specific reference test file path (Tier 2). Omit for Tier 3.
+- ***_Complexity: mechanical | standard | complex_*** — task difficulty hint.
+  - `mechanical` — routine task with no design decisions (boilerplate, rename, add field, copy existing pattern)
+  - `standard` — typical task with a clear solution path (implement handler per spec, write tests for defined cases)
+  - `complex` — task with non-obvious solution, multiple edge cases, or concurrency/state concerns
+
+### Instruction Keywords
+
+Use these prefixes for task instructions:
+
+| Keyword | Meaning |
+|---|---|
+| `CRITICAL` | Must be done exactly as described; deviation causes failure |
+| `IMPORTANT` | Strong guidance; deviation risks subtle bugs |
+| `NOTE` | Informational context |
+| `DO NOT` | Explicit prohibition |
+| `GOAL` | The purpose of this task in plain language |
+
+---
+
+## Task Types
+
+Task type templates (RED, GREEN, CODE, VERIFY, GATE): read `./templates/reference/task-types.md`.
+
+---
+
+## Task Order Rules
+
+### Bug Fix
+```
+RED (Exploration Test)
+  → GREEN (Preservation Tests)
+    → CODE (Implementation)
+      → VERIFY (Re-test)
+        → GATE (Checkpoint)
+```
+
+### Pure Feature
+```
+GREEN (Test Stubs / Expected Behavior Tests)
+  → CODE (Implementation — layer by layer, bottom-up)
+    → GREEN (Full Tests)
+      → GATE (Checkpoint)
+```
+
+### Migration
+```
+GREEN (Preservation Tests — capture all current behavior)
+  → CODE (Migration Implementation)
+    → VERIFY (Re-run Preservation Tests)
+      → GATE (Checkpoint)
+```
+
+---
+
+## Granularity Rules
+
+- **Top-level tasks:** 4–8 per plan.
+- **Subtasks per task:** 2–6 per top-level task.
+- Each subtask must be **atomic** — a single, independently verifiable action.
+- Each subtask must touch **one file only**.
+- If a task requires more than 6 subtasks, split it into two top-level tasks.
+
+---
+
+## Prohibited Formulations
+
+Every subtask must be **concrete enough for a different agent to execute without guessing**. If the executor would need to make a design decision, the formulation is too abstract.
+
+| Prohibited | Why | Correct alternative |
+|---|---|---|
+| "TBD", "TODO", "implement later" | Defers the decision to Implementation phase | Make the decision now; if unknown, ask the user |
+| "Add appropriate error handling" | Which errors? What handling? | "Return `ErrTokenExpired` when `exp < now`" |
+| "Add validation" | Which fields? Which rules? | "Validate `email` matches RFC 5322, return 400 if invalid" |
+| "Write tests for the above" | Which cases? Which assertions? | "Test: input `\"\"` → returns `ErrEmpty`; input `\"valid@x.com\"` → returns nil" |
+| "Similar to Task N" | Executor may not see Task N in context | Repeat the concrete details |
+| "Update the config" | Which keys? What values? | "Add key `rate_limit: 100` to `config.yaml` under `server` section" |
+| Steps without file path | Not clear where to act | Specify `file:function` or `file:line-range` |
+
+DO NOT use hedge words ("might", "should probably", "consider adding") in task instructions. Each instruction is either a concrete action or it does not belong in the plan.
+
+---
+
+## Traceability Rules
+
+- **Every task** must have at least one `*_Requirements:_*` annotation.
+- **Every implementation task (CODE)** must have a `*_Preservation:_*` annotation.
+- **Every bug fix plan** must include RED, GREEN, VERIFY, and GATE tasks.
+- No orphan tasks — every task must trace back to a requirement ID.
+
+---
+
+## Quality Control Checklist
+
+Before delivering the plan, verify:
+
+- [ ] Every requirement in the requirements document is covered by at least one task.
+- [ ] Every task has a `*_Requirements:_*` annotation.
+- [ ] Every implementation task has a `*_Preservation:_*` annotation.
+- [ ] Bug fix plans include an exploration test (RED) that is confirmed FAIL before implementation.
+- [ ] Bug fix plans include a re-test task (VERIFY) that is the same test as RED.
+- [ ] Task order matches the dependency rules for the work type.
+- [ ] The checkpoint (GATE) is the final task.
+- [ ] No task touches more than one file per subtask.
+- [ ] No task contains code or architecture decisions.
+- [ ] Command Discovery is completed and Commands block is present with real, resolved commands.
+- [ ] All tasks use the resolved commands from the Commands block — no generic placeholders (`<test command>`, `<build command>`, `<lint command>`) remain in actual task instructions.
+- [ ] If code generation commands were discovered, implementation tasks that modify generated-source inputs include a generate subtask before test/build subtasks.
+- [ ] Test Infrastructure Discovery is completed and Test Style Source block is present.
+- [ ] The coverage matrix is present and complete.
+- [ ] No subtask contains prohibited formulations (see Prohibited Formulations section) — every instruction is concrete and executable without design decisions.
+- [ ] Every top-level task has a `*_Complexity:_*` annotation (`mechanical`, `standard`, or `complex`).
+
+---
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Coverage matrix is present with every requirement mapped to at least one task.
+2. Work type is classified: **Bug fix**, **Pure feature**, or **Migration**.
+3. Task order follows the rules for the classified work type.
+4. Every task has a `*_Requirements:_*` annotation.
+5. Every implementation task (CODE) has a `*_Preservation:_*` annotation.
+6. Checkpoint (GATE) is the final task in the plan.
+7. Test Infrastructure Discovery is completed with Test Style Source block (tier + evidence).
+8. Command Discovery is completed with Commands block (real project commands, not placeholders).
+9. Every top-level task has a `*_Complexity:_*` annotation.
+10. Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Antipatterns — Never Do These
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Task Plan.
diff --git a/.spec/AGENTS.md b/.spec/AGENTS.md
new file mode 100644
index 0000000..f94f13c
--- /dev/null
+++ b/.spec/AGENTS.md
@@ -0,0 +1,80 @@
+<!-- generated: 2026-05-14, template: agents-index.md -->
+# AGENTS.md — AI Agent Guide for `.spec/` Documentation
+
+## 1. What is `.spec/`?
+
+`.spec/` is the project documentation directory optimized for AI agent (LLM) consumption. It contains structured, machine-friendly descriptions of the **EasyP** codebase:
+
+- **Architecture & design** — layered architecture, component relationships, data flows
+- **Package descriptions** — purpose and responsibilities of each Go package
+- **Domain model** — core types, interfaces, and business rules for Protocol Buffers tooling
+- **Code & testing conventions** — naming, error handling, test patterns
+- **Infrastructure & tooling** — CI/CD, Docker, release process
+- **Agent rules** (`agent-rules.md`) — mandatory constraints for AI-assisted development
+
+**Purpose:** give the agent full project context without reading the entire source code. Start here instead of `grep`-ing through hundreds of files.
+
+## 2. How to Use (for agents)
+
+When working on the EasyP project, follow this reading order:
+
+1. **Starting a task** → read `.spec/README.md` for the documentation map and quick facts.
+2. **Before modifying code** → read the relevant document:
+   - Changing API handlers → `ARCHITECTURE.md` + `CODE_STYLE.md`
+   - Adding a lint rule → `DOMAIN.md` + `TESTING.md`
+   - Modifying config parsing → `ARCHITECTURE.md` + `PACKAGES.md`
+   - Working with plugins → `ARCHITECTURE.md` (Plugin Executors section)
+   - Updating CI/CD → `TOOLS.md` + `DEPLOYMENT.md`
+3. **Always follow** rules from `agent-rules.md` — these are project-specific constraints.
+4. **If a document appears outdated** — suggest an update to the user before proceeding.
+
+## 3. File Structure Convention
+
+Files in `.spec/` follow these naming conventions:
+
+| Pattern | Purpose | Examples |
+|---------|---------|---------|
+| `README.md` | Index of all documents, quick facts, project structure, ports, commands | — |
+| `agent-rules.md` | Mandatory rules for AI agents (code style, naming, error handling) | — |
+| `UPPER_CASE.md` | Topical documents | `ARCHITECTURE.md`, `TESTING.md`, `DOMAIN.md` |
+| `features/` | Pipeline phase artifacts (per-feature) | `features/new-rule/explore.md` |
+
+> **Directory separation:** Project documentation lives in `.spec/`. Feature pipeline artifacts live in `.spec/features/<feature>/`. Never mix them.
+
+## 4. Document Categories
+
+### Core
+- `ARCHITECTURE.md` — Layered architecture (cmd → api → core ← adapters), component diagram
+- `PACKAGES.md` — Go package inventory with responsibilities
+- `DOMAIN.md` — Core types (`ProtoInfo`, `Rule`, `Issue`, `Plugin`), interfaces, value objects
+- `CODE_STYLE.md` — Naming conventions, error wrapping, interface compliance patterns
+
+### Development
+- `TOOLS.md` — Task runner commands, linters, mockery, GoReleaser
+- `TESTING.md` — testify patterns, testdata fixtures, mock generation, race detection
+- `FILES.md` — Key file locations and their purposes
+
+### Infrastructure
+- `DEPLOYMENT.md` — Docker multi-stage build, GoReleaser, GitHub Actions, Homebrew tap
+- `CLI.md` — Full CLI command reference with flags, exit codes, output formats
+
+## 5. How to Maintain
+
+Keep documentation current by following these rules:
+
+- **Adding a new lint rule** → update `DOMAIN.md` (rule list) and `TESTING.md` (test pattern)
+- **Adding a new CLI command** → update `CLI.md` and `ARCHITECTURE.md` (handler list)
+- **Changing architecture** → update `ARCHITECTURE.md`
+- **Adding a dependency** → update `PACKAGES.md`
+- **Changing config schema** → update `DOMAIN.md` and run `task schema:generate`
+- `README.md` must always reflect the current list of documents
+- Documents must contain code examples from the actual project, not abstract ones
+
+## 6. How to Add a New Document
+
+1. Create a file `TOPIC_NAME.md` in `.spec/`
+2. Add `<!-- generated: YYYY-MM-DD, template: <template>.md -->` as line 1
+3. Use this structure:
+   - Title → Overview → Architectural diagram (ASCII/Mermaid) → Details → Code examples → Configuration → Testing → Key files
+4. Add a link in `.spec/README.md` under the appropriate category
+5. Use real code examples from the EasyP source, not invented ones
diff --git a/.spec/ARCHITECTURE.md b/.spec/ARCHITECTURE.md
new file mode 100644
index 0000000..fdc924e
--- /dev/null
+++ b/.spec/ARCHITECTURE.md
@@ -0,0 +1,137 @@
+<!-- generated: 2026-05-14, template: core.md -->
+# EasyP Architecture
+
+## 1. Overview
+
+EasyP is a CLI application following a **clean/hexagonal architecture** pattern with three well-defined layers.
+
+```
+┌──────────────────────────────────────────────────────┐
+│                    cmd/easyp/                        │
+│               CLI entrypoint (main.go)               │
+│          Registers handlers, initializes logger      │
+└────────────────────────┬─────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────┐
+│                   internal/api/                      │
+│             CLI Command Handlers                     │
+│    Parses flags, reads config, builds Core,          │
+│    formats output                                    │
+└────────────────────────┬─────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────┐
+│                  internal/core/                      │
+│              Business Logic (Core)                   │
+│   Lint, Generate, Download, BreakingCheck,           │
+│   Initialize, ListFiles, Vendor, Update              │
+│                                                      │
+│   Depends on INTERFACES (ports), not implementations │
+└────────┬───────────────┬──────────────┬──────────────┘
+         │               │              │
+         ▼               ▼              ▼
+┌────────────┐  ┌──────────────┐  ┌────────────────┐
+│  adapters/ │  │   adapters/  │  │   adapters/    │
+│  storage   │  │   go_git     │  │   plugin/      │
+│  lock_file │  │   repository │  │  (4 executors) │
+│  console   │  │              │  │                │
+│  prompter  │  │              │  │                │
+└────────────┘  └──────────────┘  └────────────────┘
+```
+
+## 2. Component Deep Dive
+
+### cmd/easyp (Entrypoint)
+
+| File | Description |
+|------|-------------|
+| `main.go` | Creates `cli.App`, registers all handlers, initializes `slog` logger |
+
+Registers handlers via `buildCommand(...)`: Lint, Mod, Completion, Init, Generate, SchemaGen, LsFiles, Validate, BreakingCheck.
+
+### internal/api (Command Handlers)
+
+Each handler implements `Handler` interface: `Command() *cli.Command`.
+
+| File | Description |
+|------|-------------|
+| `lint.go` | Lint handler — walks protos, applies rules, prints issues |
+| `generate.go` | Generate handler — invokes plugin executors |
+| `breaking_check.go` | Breaking change handler — compares against git ref |
+| `init.go` | Init handler — interactive config creation |
+| `mod.go` | Mod handler — download/update/vendor subcommands |
+| `validate.go` | Validate handler — config validation |
+| `ls_files.go` | LsFiles handler — lists proto files |
+| `schema_gen.go` | SchemaGen handler — generates JSON Schema |
+| `completion.go` | Completion handler — bash/zsh scripts |
+| `temporaly_helper.go` | Shared helpers: `buildCore()`, `getLogger()`, `getEasypPath()` |
+
+### internal/core (Business Logic)
+
+Central orchestrator. The `Core` struct holds all dependencies and exposes methods for each operation.
+
+| File | Description |
+|------|-------------|
+| `core.go` | `Core` struct, constructor `New(...)`, dependency injection |
+| `dom.go` | Domain types: `Rule`, `Issue`, `ProtoInfo`, `Plugin`, `Repo` |
+| `lint.go` | `Core.Lint()` — walks files, applies rules |
+| `generate.go` | `Core.Generate()` — compiles protos, invokes plugins |
+| `breaking.go` | `Core.BreakingCheck()` — compares proto versions |
+| `download.go` | `Core.Download()` — fetches dependencies |
+| `initialize.go` | `Core.Initialize()` — creates easyp.yaml |
+| `ls_files.go` | `Core.ListFiles()` — lists proto files |
+| `vendor.go` | `Core.Vendor()` — copies deps to vendor dir |
+| `nolint.go` | `nolint:` / `buf:lint:ignore` comment parsing |
+
+### internal/adapters (Infrastructure)
+
+| Adapter | Package | Purpose |
+|---------|---------|---------|
+| Storage | `adapters/storage` | Dependency cache management (`~/.easyp`) |
+| Git Walker | `adapters/go_git` | Git-based dir walker for breaking checks |
+| Lock File | `adapters/lock_file` | `easyp.lock` read/write |
+| Module Config | `adapters/module_config` | Module configuration reader |
+| Console | `adapters/console` | stdin/stdout interaction |
+| Prompter | `adapters/prompter` | Interactive TUI prompts (bubbletea) |
+| Repository | `adapters/repository` | Git repository operations |
+| Plugin | `adapters/plugin/` | 4 executor types: local, remote, builtin (WASM), command |
+
+## 3. Key Design Decisions
+
+1. **Clean Architecture** — Core depends only on interfaces (ports), never on concrete implementations. This enables easy testing via mocks and swapping adapters.
+
+2. **Interface Compliance Guards** — Every concrete type verifies its interface at compile time:
+   ```go
+   var _ Handler = (*Lint)(nil)
+   var _ core.Rule = (*FieldLowerSnakeCase)(nil)
+   ```
+
+3. **Plugin Executor Strategy** — Code generation supports 4 execution strategies (local, remote, WASM, command) behind a single `Executor` interface. The executor is chosen based on the `PluginSource` fields.
+
+4. **Rule Auto-Discovery** — Lint rule names are auto-derived from struct names via `PascalCase → UPPER_SNAKE_CASE` reflection. Groups expand to individual rules at build time.
+
+5. **Config-Driven** — All behavior is driven by `easyp.yaml`. No hardcoded defaults in business logic — everything comes from config or constructor injection.
+
+## 4. Data Flow
+
+```
+CLI invocation (easyp lint --path api/proto)
+  → cmd/easyp/main.go: cli.App.Run()
+    → internal/api/lint.go: Lint.Action()
+      → resolveRoots(): compute configPath, projectRoot, lintRoot
+      → config.New(): parse easyp.yaml
+      → buildCore(): construct Core with all adapters
+        → rules.New(): build lint rules from config
+        → storage.New(): init cache storage
+        → go_git.New(): init git walker
+      → core.Lint(ctx, dirWalker)
+        → dirWalker.Walk(): iterate *.proto files
+        → parse each file (go-protoparser)
+        → for each rule: rule.Validate(protoInfo)
+          → AppendIssue(): check nolint comments, collect issues
+      ← return []IssueInfo
+    → printIssues(format, stdout, issues)
+      → textPrinter() or jsonPrinter()
+    ← os.Exit(0 or 1)
+```
diff --git a/.spec/CLI.md b/.spec/CLI.md
new file mode 100644
index 0000000..e96da67
--- /dev/null
+++ b/.spec/CLI.md
@@ -0,0 +1,300 @@
+<!-- generated: 2026-05-14, template: cli.md -->
+# EasyP CLI Reference
+
+## 1. Overview
+
+**EasyP** is a modern CLI toolkit for Protocol Buffers development: linting, breaking change detection, code generation, and dependency management.
+
+**Installation:**
+```bash
+# Homebrew
+brew install easyp-tech/tap/easyp
+
+# Go install
+go install github.com/easyp-tech/easyp/cmd/easyp@latest
+
+# Docker
+docker run --rm -v $(pwd):/work -w /work ghcr.io/easyp-tech/easyp lint
+```
+
+**Quick start:**
+```bash
+easyp init                   # Create easyp.yaml interactively
+easyp lint                   # Lint proto files
+easyp generate               # Generate code
+easyp breaking --against main # Check for breaking changes
+```
+
+## 2. Command Tree
+
+```
+easyp
+├── lint (l)                        # Lint proto files
+│   ├── --path/-p <dir>             # Path to proto files (default: ".")
+│   └── --root/-r <dir>            # Root directory for file search
+├── generate (g)                    # Generate code from proto files
+│   ├── --path/-p <dir>             # Path to proto files (default: ".")
+│   ├── --root/-r <dir>            # Root directory for file search
+│   ├── --descriptor_set_out <path> # Output for binary FileDescriptorSet
+│   └── --include_imports           # Include transitive deps in descriptor
+├── breaking                        # Breaking change detection
+│   ├── --path/-p <dir>             # Path to proto files (default: ".")
+│   ├── --against <ref>             # Git ref to compare (default: "master")
+│   └── --root/-r <dir>            # Root directory for file search
+├── init (i)                        # Initialize easyp.yaml
+│   └── --dir/-d <dir>             # Target directory (default: ".")
+├── mod (m)                         # Package manager
+│   ├── download                    # Download deps to cache
+│   ├── update                      # Update deps versions
+│   └── vendor                      # Copy deps to vendor dir
+├── validate-config (validate)      # Validate easyp.yaml
+├── ls-files (ls)                   # List proto files
+│   └── --include-imports/-I        # Include transitive imports (default: true)
+├── schema-gen                      # Generate JSON Schema artifacts
+│   ├── --out-versioned <path>      # Versioned schema path
+│   └── --out-latest <path>         # Latest schema alias path
+├── completion                      # Shell completion scripts
+│   ├── bash                        # Bash completion
+│   └── zsh                         # Zsh completion
+├── --help/-h                       # Show help
+└── --version/-v                    # Show version
+```
+
+## 3. Commands Reference
+
+### `easyp lint [flags]`
+
+Lint `.proto` files against configured rules.
+
+| Flag / Argument | Type | Required | Default | Description |
+|----------------|------|----------|---------|-------------|
+| `--path` / `-p` | string | no | `.` | Relative path to directory with proto files |
+| `--root` / `-r` | string | no | config dir | Root directory for file search |
+
+**Examples:**
+```bash
+easyp lint                           # Lint current directory
+easyp lint --path api/proto          # Lint specific directory
+easyp lint --root /projects/myproto  # Custom root
+easyp lint --format json             # JSON output (NDJSON)
+```
+
+### `easyp generate [flags]`
+
+Generate code from proto files using configured plugins.
+
+| Flag / Argument | Type | Required | Default | Description |
+|----------------|------|----------|---------|-------------|
+| `--path` / `-p` | string | no | `.` | Path to proto files |
+| `--root` / `-r` | string | no | config dir | Root directory for file search |
+| `--descriptor_set_out` | string | no | — | Output path for FileDescriptorSet |
+| `--include_imports` | bool | no | `false` | Include transitive deps in descriptor |
+
+**Examples:**
+```bash
+easyp generate                                     # Generate with defaults
+easyp generate --path api/proto                    # Custom proto directory
+easyp generate --descriptor_set_out desc.pb        # Emit descriptor set
+easyp generate --descriptor_set_out desc.pb --include_imports
+```
+
+### `easyp breaking [flags]`
+
+Check for breaking API changes against a Git reference.
+
+| Flag / Argument | Type | Required | Default | Description |
+|----------------|------|----------|---------|-------------|
+| `--path` / `-p` | string | no | `.` | Path to proto files |
+| `--against` | string | no | `master` | Git ref to compare against |
+| `--root` / `-r` | string | no | config dir | Root directory for file search |
+
+**Examples:**
+```bash
+easyp breaking                       # Compare against master
+easyp breaking --against main        # Compare against main
+easyp breaking --against v1.0.0      # Compare against tag
+easyp breaking --format json         # JSON output
+```
+
+### `easyp init [flags]`
+
+Initialize a new project with interactive `easyp.yaml` creation.
+
+| Flag / Argument | Type | Required | Default | Description |
+|----------------|------|----------|---------|-------------|
+| `--dir` / `-d` | string | no | `.` | Directory to initialize |
+
+**Examples:**
+```bash
+easyp init                   # Initialize in current directory
+easyp init --dir ./myproject # Initialize in specific directory
+```
+
+### `easyp mod <subcommand>`
+
+Package manager for proto dependencies.
+
+| Subcommand | Description |
+|------------|-------------|
+| `download` | Download modules declared in `deps:` to local cache (`$EASYPPATH`) |
+| `update` | Re-resolve and update module versions |
+| `vendor` | Copy proto files from deps to `easyp_vendor/` |
+
+**Examples:**
+```bash
+easyp mod download   # Download all deps
+easyp mod update     # Update to latest versions
+easyp mod vendor     # Vendor deps locally
+```
+
+### `easyp validate-config [flags]`
+
+Validate `easyp.yaml` for syntax, types, and required fields.
+
+Uses only the global `--cfg` flag. Default output format: **JSON**.
+
+**Examples:**
+```bash
+easyp validate-config                      # Validate default config (JSON)
+easyp validate-config --format text        # Human-readable output
+easyp validate-config --cfg custom.yaml    # Validate custom config
+```
+
+### `easyp ls-files [flags]`
+
+List `.proto` files considering inputs and imports.
+
+| Flag / Argument | Type | Required | Default | Description |
+|----------------|------|----------|---------|-------------|
+| `--include-imports` / `-I` | bool | no | `true` | Include transitive imports |
+
+Default output format: **JSON**.
+
+**Examples:**
+```bash
+easyp ls-files                          # List all files (JSON)
+easyp ls-files --format text            # Human-readable
+easyp ls-files --include-imports=false  # Skip imports
+```
+
+### `easyp schema-gen [flags]`
+
+Generate JSON Schema artifacts for `easyp.yaml` configuration.
+
+| Flag / Argument | Type | Required | Default | Description |
+|----------------|------|----------|---------|-------------|
+| `--out-versioned` | string | no | `schemas/easyp-config-v1.schema.json` | Versioned schema path |
+| `--out-latest` | string | no | `schemas/easyp-config.schema.json` | Latest schema alias |
+
+### `easyp completion <shell>`
+
+Generate shell completion scripts.
+
+```bash
+# Bash
+source <(easyp completion bash)
+
+# Zsh
+source <(easyp completion zsh)
+```
+
+## 4. Configuration
+
+Precedence: **CLI flags → Environment variables → Config file → Defaults**
+
+Config file format: YAML (`easyp.yaml`) with `envsubst` expansion.
+
+| Setting | Flag | Env Var | Config Key | Default |
+|---------|------|---------|------------|---------|
+| Config file | `--cfg` / `--config` | `EASYP_CFG` | — | `easyp.yaml` |
+| Debug mode | `--debug` / `-d` | `EASYP_DEBUG` | — | `false` |
+| Output format | `--format` / `-f` | `EASYP_FORMAT` | — | `text` |
+| Generate path | `--path` | `EASYP_ROOT_GENERATE_PATH` | — | `.` |
+| Init directory | `--dir` | `EASYP_INIT_DIR` | — | `.` |
+| Cache directory | — | `EASYPPATH` | — | `~/.easyp` |
+
+## 5. Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success / no issues |
+| `1` | Issues found (lint errors, breaking changes, validation errors, version not found) |
+| `2` | Infrastructure error (missing import, Git ref not found, repository missing) |
+
+## 6. I/O Contracts
+
+- **stdin:** Not used by any command (except `init` which uses interactive TUI prompts).
+- **stdout:** Command output. Format depends on `--format` flag:
+  - `lint`, `breaking` → NDJSON (`text` default, `json` per-line objects)
+  - `validate-config`, `ls-files` → single JSON document (`json` default)
+  - `completion` → shell script
+  - `schema-gen` → writes to files, not stdout
+- **stderr:** Debug logs (when `--debug` is enabled), error messages.
+- **Files created/modified:**
+  - `init` → creates `easyp.yaml`
+  - `mod download` → caches repos in `$EASYPPATH` (`~/.easyp`)
+  - `mod update` → updates `easyp.lock`
+  - `mod vendor` → copies protos to `easyp_vendor/`
+  - `generate` → writes generated code to plugin `out` directories
+  - `schema-gen` → writes JSON Schema files
+
+## 7. Shell Completion
+
+Supported shells: **Bash**, **Zsh**.
+
+```bash
+# Bash — add to ~/.bashrc
+source <(easyp completion bash)
+
+# Zsh — add to ~/.zshrc
+source <(easyp completion zsh)
+```
+
+Completions are generated dynamically via the `completion` subcommand.
+
+## 8. Global Flags
+
+| Flag | Type | Default | Env Var | Description |
+|------|------|---------|---------|-------------|
+| `--cfg` / `--config` | string | `easyp.yaml` | `EASYP_CFG` | Path to config file |
+| `--debug` / `-d` | bool | `false` | `EASYP_DEBUG` | Enable debug logging to stderr |
+| `--format` / `-f` | enum | `text` | `EASYP_FORMAT` | Output format: `text` or `json` |
+| `--help` / `-h` | — | — | — | Show help |
+| `--version` / `-v` | — | — | — | Show version |
+
+## 9. Error Messages & Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Cannot import file: <name>` | Missing proto import | Add the dependency to `deps:` in `easyp.yaml` and run `easyp mod download` |
+| `Cannot find git ref: <ref>` | Invalid `--against` reference | Verify the branch/tag exists: `git branch -a` or `git tag -l` |
+| `Repository does not exist` | `breaking` run outside a git repo | Run from within a git repository |
+| `config not found` | Missing `easyp.yaml` | Run `easyp init` or specify `--cfg <path>` |
+| `version not found` | Dependency version doesn't exist | Check the version tag in the dependency repo |
+
+## 10. Development
+
+**Run locally:**
+```bash
+task build && ./easyp lint
+# or
+go run ./cmd/easyp lint
+```
+
+**Build release binary:**
+```bash
+task build
+# Output: ./easyp
+```
+
+**Add a new command:**
+1. Create `internal/api/<command>.go` — struct implementing `Handler`
+2. Add `var _ Handler = (*MyCommand)(nil)` for interface compliance
+3. Implement `Command() *cli.Command` with flags, description, action
+4. Register in `cmd/easyp/main.go` via `buildCommand(...)` call
+
+**Source files:**
+- Entry point: [`cmd/easyp/main.go`](../cmd/easyp/main.go)
+- Handlers: [`internal/api/`](../internal/api/)
+- Global flags: [`internal/flags/flags.go`](../internal/flags/flags.go)
+- CLI framework: `github.com/urfave/cli/v2`
diff --git a/.spec/CODE_STYLE.md b/.spec/CODE_STYLE.md
new file mode 100644
index 0000000..d96768d
--- /dev/null
+++ b/.spec/CODE_STYLE.md
@@ -0,0 +1,182 @@
+<!-- generated: 2026-05-14, template: core.md -->
+# EasyP Code Style
+
+## 1. Layer Structure
+
+```
+cmd/easyp/          → Entrypoint (no business logic)
+  │
+  ▼
+internal/api/       → Transport layer (CLI flags → Core calls → output formatting)
+  │
+  ▼
+internal/core/      → Business logic (pure domain, depends on interfaces only)
+  │
+  ▼
+internal/adapters/  → Infrastructure (git, storage, plugins, filesystem)
+```
+
+**Rules:**
+- `cmd/` may only import `internal/api/` and `internal/flags/`
+- `internal/api/` may import `internal/core/`, `internal/config/`, `internal/flags/`, `internal/adapters/`
+- `internal/core/` may **NOT** import `internal/adapters/` (depends on interfaces only)
+- `internal/adapters/` may import `internal/core/` (to implement its interfaces)
+
+## 2. Naming Conventions
+
+### Files
+
+| Layer | Pattern | Example |
+|-------|---------|---------|
+| Commands | `<command>.go` | `lint.go`, `generate.go` |
+| Rules | `<rule_name>.go` | `enum_pascal_case.go` |
+| Tests | `*_test.go` alongside source | `enum_pascal_case_test.go` |
+| Mocks | `mocks/` subdirectory | `core/mocks/mock_Rule.go` |
+| Adapters | `<purpose>.go` | `storage.go`, `walker.go` |
+
+### Structs
+
+| Layer | Visibility | Example |
+|-------|-----------|---------|
+| API handlers | Public | `type Lint struct{}` |
+| Core interfaces | Public | `type Rule interface{}` |
+| Core types | Public | `type ProtoInfo struct{}` |
+| Adapter types | Public (implements interface) | `type FSWalker struct{}` |
+| Internal helpers | Private | `type configLoader struct{}` |
+
+### Rules
+
+| Convention | Example |
+|-----------|---------|
+| Struct name → Rule name | `EnumPascalCase` → `ENUM_PASCAL_CASE` |
+| Rule groups | `MINIMAL`, `BASIC`, `DEFAULT`, `COMMENTS`, `UNARY_RPC` |
+
+## 3. Error Propagation
+
+### Wrapping Pattern
+
+Always wrap errors with the calling function name:
+
+```go
+// ✅ Correct
+if err != nil {
+    return fmt.Errorf("config.New: %w", err)
+}
+
+// ❌ Wrong
+if err != nil {
+    return err  // no context
+}
+if err != nil {
+    return fmt.Errorf("failed: %w", err)  // vague context
+}
+```
+
+### Error Types by Layer
+
+| Layer | Error Type | Example |
+|-------|-----------|---------|
+| Core | Sentinel errors | `var ErrEmptyInputFiles = errors.New(...)` |
+| Core | Typed errors | `type OpenImportFileError struct { FileName string }` |
+| API | Exit code mapping | `errors.Is(err, ErrHasLintIssue) → os.Exit(1)` |
+| Adapters | Wrapped stdlib errors | `fmt.Errorf("os.Open: %w", err)` |
+
+### Error Chain Example
+
+```go
+// Adapter layer
+func (s *Storage) Download(...) error {
+    return fmt.Errorf("storage.Download: %w", err)
+}
+
+// Core layer
+func (c *Core) Download(ctx context.Context) error {
+    return fmt.Errorf("core.Download: %w", err)
+}
+
+// API layer
+func (m Mod) Download(ctx *cli.Context) error {
+    if errors.Is(err, models.ErrVersionNotFound) {
+        os.Exit(1)
+    }
+    return fmt.Errorf("cmd.Download: %w", err)
+}
+```
+
+## 4. Interface Conventions
+
+### Argument Order
+
+1. `context.Context` first (always)
+2. Required parameters
+3. Optional parameters / options structs
+
+### Interface Compliance
+
+```go
+var _ Handler = (*Lint)(nil)           // compile-time check
+var _ core.Rule = (*EnumPascalCase)(nil)
+```
+
+### Interface Design
+
+- Keep interfaces small (1-3 methods)
+- Define interfaces in the package that uses them (core), not the package that implements them (adapters)
+- Use descriptive method names: `Validate`, `Download`, `GetFiles`
+
+## 5. Import Ordering
+
+```go
+import (
+    // 1. Standard library
+    "context"
+    "fmt"
+    "os"
+
+    // 2. Third-party
+    "github.com/urfave/cli/v2"
+
+    // 3. Internal packages
+    "github.com/easyp-tech/easyp/internal/config"
+    "github.com/easyp-tech/easyp/internal/core"
+)
+```
+
+Groups separated by blank lines, sorted alphabetically within each group.
+
+## 6. Logging Conventions
+
+| Layer | Log Level | What to Log |
+|-------|-----------|-------------|
+| API | Warn | Non-fatal conditions (empty input files) |
+| API | Error | Fatal errors before `os.Exit()` |
+| Core | Debug | Internal state, decisions |
+| Adapters | Debug | External calls (storage paths, git operations) |
+
+```go
+log := getLogger(ctx)
+log.Debug(ctx.Context, "Use storage", slog.String("path", easypPath))
+log.Warn(ctx.Context, "empty input files!")
+log.Error(ctx.Context, "Cannot import file", slog.String("file name", e.FileName))
+```
+
+**Never log:** secrets, credentials, full file contents.
+
+## 7. Test File Organization
+
+| Pattern | Purpose |
+|---------|---------|
+| `*_test.go` alongside source | Unit tests |
+| `testdata/` | Proto file fixtures |
+| `mocks/` next to interface | Generated mocks |
+| `_test` package suffix | Black-box tests |
+
+## 8. Quick Reference
+
+| Aspect | API Layer | Core Layer | Adapters Layer |
+|--------|-----------|------------|----------------|
+| **Structs** | Public | Public | Public |
+| **Errors** | Exit codes via `os.Exit()` | Sentinel + typed errors | Wrapped stdlib |
+| **Logging** | Warn/Error | Debug | Debug |
+| **Dependencies** | config, core, adapters | Interfaces only | Core interfaces, stdlib |
+| **Testing** | Integration | Unit + mocks | Unit |
diff --git a/.spec/DEPLOYMENT.md b/.spec/DEPLOYMENT.md
new file mode 100644
index 0000000..133f693
--- /dev/null
+++ b/.spec/DEPLOYMENT.md
@@ -0,0 +1,144 @@
+<!-- generated: 2026-05-14, template: deployment.md -->
+# EasyP Deployment
+
+## 1. Overview
+
+EasyP is a CLI tool distributed as pre-built binaries, Docker images, and Homebrew packages. Releases are automated via GoReleaser and GitHub Actions.
+
+```
+tag push → CI (tests) → GoReleaser → binaries + Docker + Homebrew
+```
+
+## 2. Distribution Channels
+
+| Channel | Target | Auto-deploy |
+|---------|--------|-------------|
+| GitHub Releases | All platforms (binaries) | Yes (on tag) |
+| Docker (ghcr.io) | `ghcr.io/easyp-tech/easyp` | Yes (on tag) |
+| Homebrew | `easyp-tech/homebrew-tap` | Yes (on tag) |
+| Go Install | `go install github.com/easyp-tech/easyp/cmd/easyp@latest` | Manual |
+
+## 3. Docker
+
+### Dockerfile Analysis
+
+Multi-stage build defined in `Dockerfile`:
+
+**Stage 1: Builder** (`golang:1.25-alpine`)
+- Copies `go.mod`/`go.sum`, downloads modules
+- Builds binary with `CGO_ENABLED=0` and `-ldflags` for version injection
+- Strips debug info for smaller binary
+
+**Stage 2: Runtime** (`alpine:3.22`)
+- Installs: `ca-certificates`, `tzdata`, `git`, `bash`
+- Copies binary from builder
+- Entry point: `/easyp`
+
+**Usage:**
+```bash
+# Lint proto files
+docker run --rm -v $(pwd):/work -w /work ghcr.io/easyp-tech/easyp lint
+
+# Generate code
+docker run --rm -v $(pwd):/work -w /work ghcr.io/easyp-tech/easyp generate
+
+# Breaking check
+docker run --rm -v $(pwd):/work -w /work ghcr.io/easyp-tech/easyp breaking --against main
+```
+
+### Multi-arch Support
+
+| Architecture | Platform |
+|-------------|----------|
+| `linux/amd64` | x86_64 |
+| `linux/arm64` | ARM64 |
+
+## 4. CI/CD Pipeline
+
+### `.github/workflows/tests.yml`
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | Push to `main`, all pull requests |
+| **Steps** | `task init` → `task test` |
+| **Purpose** | Run full test suite with race detection |
+
+### `.github/workflows/release.yml`
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | Tag push (`v*`) |
+| **Steps** | GoReleaser: build binaries → Docker images → Homebrew formula |
+| **Secrets** | `GITHUB_TOKEN` (auto), Docker registry credentials |
+
+### `.github/workflows/docs.yml`
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | Push to `main` (docs/ changed) |
+| **Steps** | Build docs site → deploy |
+
+## 5. GoReleaser Configuration
+
+Defined in `.goreleaser.yaml` (GoReleaser v2):
+
+### Build Targets
+
+| OS | Architecture |
+|----|-------------|
+| `darwin` | `amd64`, `arm64` |
+| `linux` | `amd64`, `arm64`, `arm` (v6, v7) |
+| `windows` | `amd64`, `arm64` |
+
+### Artifacts
+
+- **Binaries** — Compressed archives for each platform
+- **Docker images** — Multi-arch manifest (`linux/amd64` + `linux/arm64`)
+- **Homebrew tap** — Formula pushed to `easyp-tech/homebrew-tap`
+
+### Build Flags
+
+```yaml
+ldflags:
+  - -s -w
+  - -X main.version={{.Version}}
+  - -X main.commit={{.Commit}}
+  - -X main.date={{.Date}}
+```
+
+## 6. Release Process
+
+1. Create a Git tag: `git tag v1.2.3`
+2. Push the tag: `git push origin v1.2.3`
+3. GitHub Actions triggers `release.yml`
+4. GoReleaser:
+   - Builds binaries for all platforms
+   - Builds and pushes Docker images to `ghcr.io`
+   - Updates Homebrew formula in `easyp-tech/homebrew-tap`
+   - Creates GitHub Release with changelog
+
+### Rollback
+
+1. Delete the GitHub Release
+2. Delete the Git tag: `git push --delete origin v1.2.3`
+3. Push a new tag with the fix
+
+## 7. Local Development
+
+```bash
+# Install dev tools
+task init
+
+# Build and run
+task build
+./easyp lint
+
+# Run directly
+go run ./cmd/easyp lint
+
+# Run tests
+task test
+
+# Full quality check
+task quality
+```
diff --git a/.spec/DOMAIN.md b/.spec/DOMAIN.md
new file mode 100644
index 0000000..3e35998
--- /dev/null
+++ b/.spec/DOMAIN.md
@@ -0,0 +1,194 @@
+<!-- generated: 2026-05-14, template: core.md -->
+# EasyP Domain Model
+
+## 1. Core Entities
+
+### Rule
+
+The fundamental interface for all lint rules.
+
+```go
+// internal/core/dom.go
+type Rule interface {
+    Message() string
+    Validate(ProtoInfo) ([]Issue, error)
+}
+```
+
+### ProtoInfo
+
+Central data structure passed to every lint rule. Contains parsed proto AST and imports.
+
+```go
+// internal/core/dom.go
+type ProtoInfo struct {
+    Path                 string
+    Info                 *unordered.Proto
+    ProtoFilesFromImport map[ImportPath]*unordered.Proto
+}
+```
+
+### Issue / IssueInfo
+
+Represents a lint or breaking check finding.
+
+```go
+// internal/core/dom.go
+type Issue struct {
+    Position   meta.Position
+    SourceName string
+    Message    string
+    RuleName   string
+}
+
+type IssueInfo struct {
+    Issue
+    Path string
+}
+```
+
+### Plugin / PluginSource
+
+Describes a code generation plugin and its source type.
+
+```go
+// internal/core/dom.go
+type PluginSource struct {
+    Name    string   // local: protoc-gen-<name>
+    Remote  string   // remote: API service
+    Path    string   // path: specific filesystem path
+    Command []string // command: arbitrary command
+}
+
+type Plugin struct {
+    Source      PluginSource
+    Out         string
+    Options     map[string][]string
+    WithImports bool
+}
+```
+
+### Inputs
+
+Source configuration for code generation.
+
+```go
+// internal/core/dom.go
+type InputGitRepo struct {
+    URL          string
+    SubDirectory string
+    Root         string
+}
+
+type InputFilesDir struct {
+    Path string
+    Root string
+}
+
+type Inputs struct {
+    InputFilesDir []InputFilesDir
+    InputGitRepos []InputGitRepo
+}
+```
+
+### Repo
+
+Git repository operations interface.
+
+```go
+// internal/core/dom.go
+type Repo interface {
+    GetFiles(ctx context.Context, revision models.Revision, dirs ...string) ([]string, error)
+    ReadFile(ctx context.Context, revision models.Revision, fileName string) (string, error)
+    Archive(ctx context.Context, revision models.Revision, paths models.CacheDownloadPaths) error
+    ReadRevision(ctx context.Context, version models.RequestedVersion) (models.Revision, error)
+    Fetch(ctx context.Context, revision models.Revision) error
+}
+```
+
+## 2. Value Objects
+
+### Type Aliases
+
+```go
+type ImportPath string   // path in proto import statement
+type PackageName string  // proto package name
+```
+
+### models.Revision
+
+```go
+// internal/core/models/revision.go
+type Revision struct { /* commit hash and metadata */ }
+```
+
+### models.CacheDownloadPaths
+
+```go
+// internal/core/models/cache_download_paths.go
+type CacheDownloadPaths struct { /* paths for cached downloads */ }
+```
+
+### Collection
+
+Aggregated proto data per package.
+
+```go
+// internal/core/dom.go
+type Collection struct {
+    Imports  map[ImportPath]Import
+    Services map[string]Service
+    Messages map[string]Message   // key: message path (supports nesting)
+    Enums    map[string]Enum
+    OneOfs   map[string]OneOf
+}
+
+type ProtoData map[PackageName]*Collection
+```
+
+## 3. Error Types
+
+### Typed Errors
+
+```go
+type OpenImportFileError struct { FileName string }
+type GitRefNotFoundError struct { GitRef string }
+```
+
+### Sentinel Errors
+
+```go
+var ErrEmptyInputFiles          // no input files for generation
+var ErrRepositoryDoesNotExist   // git repo not found
+```
+
+For the full error catalog see [ERRORS.md](./ERRORS.md).
+
+## 4. Key Functions
+
+### AppendIssue
+
+Checks `nolint:` / `buf:lint:ignore` comments before appending an issue.
+
+```go
+func AppendIssue(issues []Issue, rule Rule, pos meta.Position, name string, comments []*parser.Comment) []Issue
+```
+
+### GetRuleName
+
+Auto-derives rule name from struct name: `PascalCase → UPPER_SNAKE_CASE`.
+
+```go
+func GetRuleName(rule Rule) string {
+    return toUpperSnakeCase(reflect.TypeOf(rule).Elem().Name())
+}
+// EnumPascalCase → ENUM_PASCAL_CASE
+```
+
+### GetPackageName
+
+Extracts package name from parsed proto file.
+
+```go
+func GetPackageName(protoFile *unordered.Proto) PackageName
+```
diff --git a/.spec/ERRORS.md b/.spec/ERRORS.md
new file mode 100644
index 0000000..787ddf3
--- /dev/null
+++ b/.spec/ERRORS.md
@@ -0,0 +1,186 @@
+<!-- generated: 2026-05-14, template: errors.md -->
+# EasyP Error Handling
+
+## 1. Error Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│  API Layer (internal/api/)                           │
+│  Maps sentinel/typed errors → exit codes (0, 1, 2)   │
+│  Logs fatal errors, calls os.Exit()                  │
+├──────────────────────────────────────────────────────┤
+│  Core Layer (internal/core/)                         │
+│  Returns sentinel errors (ErrEmptyInputFiles, etc.)  │
+│  Returns typed errors (OpenImportFileError, etc.)    │
+│  Wraps lower-layer errors with context               │
+├──────────────────────────────────────────────────────┤
+│  Adapter Layer (internal/adapters/)                   │
+│  Wraps infrastructure errors (git, fs, network)      │
+│  Returns models.Err* sentinels where appropriate     │
+├──────────────────────────────────────────────────────┤
+│  Config Layer (internal/config/)                     │
+│  Returns validation errors (inline + sentinel)       │
+│  Private sentinels (errFileNotFound)                 │
+└──────────────────────────────────────────────────────┘
+```
+
+**Propagation rules:**
+- Adapters **create** infrastructure errors, wrap with `fmt.Errorf("funcName: %w", err)`
+- Core **wraps** adapter errors, returns domain sentinels/typed errors
+- API **maps** errors to exit codes via `errors.Is()` / `errors.As()`
+- Errors are **logged** only at the API layer (avoid double-logging)
+
+## 2. Business Error Catalog
+
+### Core Errors (`internal/core/core.go`)
+
+| Error | Exit Code | Description |
+|-------|-----------|-------------|
+| `ErrInvalidRule` | — | Invalid lint rule name in config |
+| `ErrRepositoryDoesNotExist` | 2 | Git repository not found in working dir |
+| `ErrEmptyInputFiles` | 0 (warning) | No input files for generation |
+
+### Core Typed Errors (`internal/core/dom.go`)
+
+| Error Type | Exit Code | Description |
+|-----------|-----------|-------------|
+| `OpenImportFileError{FileName}` | 2 | Cannot import a proto file |
+| `GitRefNotFoundError{GitRef}` | 2 | Git reference not found |
+
+### Model Errors (`internal/core/models/errors.go`)
+
+| Error | Exit Code | Description |
+|-------|-----------|-------------|
+| `ErrVersionNotFound` | 1 | Dependency version tag doesn't exist |
+| `ErrFileNotFound` | — | File not found in repository |
+| `ErrModuleNotInstalled` | — | Module not downloaded to cache |
+| `ErrModuleInfoFileNotFound` | — | Module metadata missing |
+| `ErrHashDependencyMismatch` | — | Lock file hash doesn't match |
+
+### Model Errors (other files)
+
+| Error | Location | Description |
+|-------|----------|-------------|
+| `ErrRequestedVersionNotGenerated` | `models/module.go` | Requested version not generated |
+| `ErrModuleNotFoundInLockFile` | `models/lock_file_info.go` | Module missing from `easyp.lock` |
+
+### API Errors (`internal/api/`)
+
+| Error | Exit Code | Description |
+|-------|-----------|-------------|
+| `ErrHasLintIssue` | 1 | Lint issues found |
+| `ErrHasValidateIssue` | 1 | Config validation errors |
+| `ErrBreakingCheckIssue` | 1 | Breaking changes found |
+| `ErrPathNotAbsolute` | — | Internal: path is not absolute |
+
+### Config Errors (`internal/config/config.go`)
+
+| Error | Description |
+|-------|-------------|
+| `errFileNotFound` (private) | Config file not found |
+| Inline validation errors | disable/override rule validation |
+
+## 3. Error Wrapping Convention
+
+### Adapter → Core
+
+```go
+// internal/adapters/storage/storage.go
+func (s *Storage) Download(ctx context.Context, ...) error {
+    if err := ...; err != nil {
+        return fmt.Errorf("storage.Download: %w", err)
+    }
+}
+```
+
+### Core → API
+
+```go
+// internal/core/download.go
+func (c *Core) Download(ctx context.Context) error {
+    if err := ...; err != nil {
+        return fmt.Errorf("core.Download: %w", err)
+    }
+}
+```
+
+### API → Exit Code
+
+```go
+// internal/api/lint.go
+func (l Lint) Action(ctx *cli.Context) error {
+    err := l.action(ctx, log)
+    if err != nil {
+        var e *core.OpenImportFileError
+        switch {
+        case errors.Is(err, ErrHasLintIssue):
+            os.Exit(1)
+        case errors.As(err, &e):
+            errExit(log, 2, "Cannot import file", slog.String("file name", e.FileName))
+        default:
+            return err
+        }
+    }
+    return nil
+}
+```
+
+## 4. Sentinel Errors vs Typed Errors
+
+### Sentinel Errors
+
+Used when only the **identity** matters (no extra context):
+
+```go
+var ErrVersionNotFound = errors.New("version not found")
+var ErrEmptyInputFiles = errors.New("empty input files")
+
+// Checked with:
+if errors.Is(err, models.ErrVersionNotFound) { ... }
+```
+
+### Typed Errors
+
+Used when errors carry **extra context** (file name, git ref):
+
+```go
+type OpenImportFileError struct {
+    FileName string
+}
+func (e *OpenImportFileError) Error() string {
+    return fmt.Sprintf("open import file `%s`", e.FileName)
+}
+
+// Checked with:
+var e *core.OpenImportFileError
+if errors.As(err, &e) {
+    log.Error("Cannot import file", slog.String("file name", e.FileName))
+}
+```
+
+## 5. Error Logging
+
+| Layer | Level | What to Log |
+|-------|-------|-------------|
+| API | `Error` | Fatal errors before `os.Exit(2)` |
+| API | `Warn` | Non-fatal conditions (empty input files) |
+| Core | — | Errors are wrapped and returned, not logged |
+| Adapters | `Debug` | Infrastructure details (storage paths) |
+
+**Rule:** Log at the top (API layer), wrap at the bottom (adapters/core).
+
+```go
+// API layer — logs and exits
+func errExit(log logger.Logger, code int, msg string, attrs ...slog.Attr) {
+    log.Error(context.Background(), msg, attrs...)
+    os.Exit(code)
+}
+```
+
+## 6. Exit Code Mapping Summary
+
+| Exit Code | Errors | Commands |
+|-----------|--------|----------|
+| `0` | No errors / `ErrEmptyInputFiles` (warning) | All |
+| `1` | `ErrHasLintIssue`, `ErrBreakingCheckIssue`, `ErrHasValidateIssue`, `ErrVersionNotFound` | lint, breaking, validate, mod |
+| `2` | `OpenImportFileError`, `GitRefNotFoundError`, `ErrRepositoryDoesNotExist` | lint, breaking |
diff --git a/.spec/PACKAGES.md b/.spec/PACKAGES.md
new file mode 100644
index 0000000..9f71467
--- /dev/null
+++ b/.spec/PACKAGES.md
@@ -0,0 +1,139 @@
+<!-- generated: 2026-05-14, template: core.md -->
+# EasyP Packages
+
+## API Layer
+
+### `internal/api`
+**CLI command handlers** — Each struct implements `Handler` interface (`Command() *cli.Command`).
+
+| File | Description |
+|------|-------------|
+| `lint.go` | Lint command handler + text/JSON output printers |
+| `generate.go` | Generate command handler + `resolveRoots()` helper |
+| `breaking_check.go` | Breaking change detection handler |
+| `init.go` | Interactive config initialization handler |
+| `mod.go` | Package manager handler (download/update/vendor) |
+| `validate.go` | Config validation handler |
+| `ls_files.go` | Proto file listing handler |
+| `schema_gen.go` | JSON Schema generation handler |
+| `completion.go` | Shell completion script generator |
+| `temporaly_helper.go` | Shared: `buildCore()`, `getLogger()`, `getEasypPath()`, `convertManagedModeConfig()` |
+
+### `internal/flags`
+**Global CLI flag definitions** — Shared flags (`--cfg`, `--debug`, `--format`) and format helpers.
+
+| File | Description |
+|------|-------------|
+| `flags.go` | `Config`, `DebugMode`, `Format` flag definitions |
+| `format.go` | `GetFormat()` helper, format constants (`text`, `json`) |
+| `enum_value.go` | `EnumValue` type for `--format` flag validation |
+
+## Business Logic Layer
+
+### `internal/core`
+**Central business logic** — `Core` struct orchestrates all operations.
+
+| File | Description |
+|------|-------------|
+| `core.go` | `Core` struct, `New()` constructor, dependency injection |
+| `dom.go` | Domain types: `Rule`, `Issue`, `ProtoInfo`, `Plugin`, `Repo` |
+| `lint.go` | `Core.Lint()` — walks files, applies rules |
+| `generate.go` | `Core.Generate()` — compiles protos, invokes plugins |
+| `breaking.go` | `Core.BreakingCheck()` — compares proto versions via git |
+| `download.go` | `Core.Download()` — fetches dependencies |
+| `initialize.go` | `Core.Initialize()` — creates easyp.yaml via templates |
+| `ls_files.go` | `Core.ListFiles()` — lists proto files with imports |
+| `vendor.go` | `Core.Vendor()` — copies deps to vendor dir |
+| `update.go` | `Core.Update()` — updates dependency versions |
+| `nolint.go` | `nolint:` / `buf:lint:ignore` comment parser |
+| `managed_mode.go` | Managed mode for proto file options |
+
+### `internal/core/models`
+**Domain value objects** — `Revision`, `CacheDownloadPaths`, `RequestedVersion`.
+
+### `internal/core/path_helpers`
+**Path utility functions** — Helpers for path resolution in proto files.
+
+### `internal/core/templates`
+**Init templates** — Embedded template files for `easyp init`.
+
+### `internal/core/mocks`
+**Generated mocks** — Mockery-generated mocks for core interfaces.
+
+### `internal/rules`
+**Lint rule implementations** — One file per rule.
+
+| File | Description |
+|------|-------------|
+| `builder.go` | Group expansion, rule construction from config |
+| `enum_pascal_case.go` | `ENUM_PASCAL_CASE` rule |
+| `field_lower_snake_case.go` | `FIELD_LOWER_SNAKE_CASE` rule |
+| `service_suffix.go` | `SERVICE_SUFFIX` rule |
+| `package_defined.go` | `PACKAGE_DEFINED` rule |
+| ... | ~40+ rule files (one per rule) |
+
+Rule groups: `MINIMAL`, `BASIC`, `DEFAULT`, `COMMENTS`, `UNARY_RPC`.
+
+## Adapters Layer
+
+### `internal/adapters/storage`
+**Dependency cache management** — Stores downloaded proto dependencies in `$EASYPPATH` (`~/.easyp`).
+
+### `internal/adapters/go_git`
+**Git walker adapter** — Implements `CurrentProjectGitWalker` for reading proto files from git refs (used by breaking check).
+
+### `internal/adapters/lock_file`
+**Lock file adapter** — Reads/writes `easyp.lock` with resolved dependency revisions.
+
+### `internal/adapters/module_config`
+**Module config adapter** — Reads module configuration from downloaded dependencies.
+
+### `internal/adapters/console`
+**Console adapter** — stdin/stdout interaction abstraction.
+
+### `internal/adapters/prompter`
+**Interactive prompter** — TUI prompts using `charmbracelet/bubbletea` for `easyp init`.
+
+### `internal/adapters/repository`
+**Git repository adapter** — Implements `Repo` interface. Sub-package `git/` handles low-level git operations.
+
+### `internal/adapters/plugin`
+**Plugin executors** — Implements `Executor` interface with 4 strategies.
+
+| Sub-package | Executor Type | Description |
+|-------------|--------------|-------------|
+| (root) | `local` | Invokes `protoc-gen-<name>` from PATH |
+| (root) | `remote` | Calls EasyP API service |
+| (root) | `path` | Invokes plugin at specific filesystem path |
+| (root) | `command` | Executes arbitrary command |
+| `wasm/` | `builtin` | Runs WASM plugins via `wazero` |
+
+## Shared / Internal
+
+### `internal/config`
+**Configuration parsing** — Reads and validates `easyp.yaml`. Types: `Config`, `LintConfig`, `Generate`, `BreakingCheck`, `Plugin`.
+
+### `internal/fs`
+**Filesystem abstractions** — `DirWalker` and `FS` interfaces.
+
+| Sub-package | Description |
+|-------------|-------------|
+| `fs/` | OS filesystem walker (`FSWalker`) |
+| `go_git/` | Git-based filesystem walker |
+
+### `internal/logger`
+**Structured logger** — Wrapper around `slog`. Provides `Logger` interface with `Debug`, `Info`, `Warn`, `Error` methods.
+
+### `internal/schemagen`
+**JSON Schema generation** — Generates schema files from Go types for `easyp.yaml` config validation.
+
+### `internal/version`
+**Build version info** — Version, commit, and build date injected via `-ldflags`.
+
+## Top-Level Packages
+
+### `mcp/easypconfig`
+**MCP tool** — `easyp_config_describe` tool for Model Context Protocol. Source-of-truth for JSON Schema.
+
+### `wellknownimports`
+**Embedded well-known protos** — `google/protobuf/*` proto files embedded in binary via `//go:embed`.
diff --git a/.spec/README.md b/.spec/README.md
new file mode 100644
index 0000000..6f9e86f
--- /dev/null
+++ b/.spec/README.md
@@ -0,0 +1,127 @@
+<!-- generated: 2026-05-14, template: bootstrap.md -->
+# EasyP Documentation
+
+This folder contains documentation to help LLMs and developers quickly understand the EasyP project context.
+
+## Documentation Index
+
+### Core
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — Layered architecture, component diagram, data flows
+- [PACKAGES.md](./PACKAGES.md) — Go package inventory with responsibilities
+- [DOMAIN.md](./DOMAIN.md) — Core types, interfaces, domain rules
+- [CODE_STYLE.md](./CODE_STYLE.md) — Naming conventions, error handling, patterns
+
+### Development
+- [TOOLS.md](./TOOLS.md) — Task runner, linters, mockery, GoReleaser
+- [TESTING.md](./TESTING.md) — Test framework, fixtures, mocks, coverage
+- [ERRORS.md](./ERRORS.md) — Error types, wrapping, exit codes
+
+### Infrastructure
+- [DEPLOYMENT.md](./DEPLOYMENT.md) — Docker, CI/CD, release process, Homebrew
+- [CLI.md](./CLI.md) — Full CLI command reference
+
+### Meta
+- [AGENTS.md](./AGENTS.md) — How AI agents should use this directory
+- [agent-rules.md](./agent-rules.md) — Mandatory rules for AI agents
+
+## Quick Facts
+
+| Aspect | Technology |
+|--------|------------|
+| **Language** | Go 1.24+ |
+| **Module** | `github.com/easyp-tech/easyp` |
+| **Architecture** | Clean/Hexagonal (cmd → api → core ← adapters) |
+| **CLI Framework** | `github.com/urfave/cli/v2` |
+| **Proto Parsing** | `github.com/yoheimuta/go-protoparser/v4` |
+| **Proto Compiling** | `github.com/bufbuild/protocompile` |
+| **Git Operations** | `github.com/go-git/go-git/v5` |
+| **WASM Runtime** | `github.com/tetratelabs/wazero` |
+| **MCP SDK** | `github.com/modelcontextprotocol/go-sdk` |
+| **Testing** | `github.com/stretchr/testify` + `gotestsum` |
+| **Mocking** | `github.com/vektra/mockery` v2.41.0 |
+| **Linting** | `golangci-lint` v2.1.6 (staticcheck) |
+| **Task Runner** | [Task](https://taskfile.dev) v3 |
+| **Config** | YAML (`easyp.yaml`) with envsubst |
+| **Release** | GoReleaser v2 |
+| **CI** | GitHub Actions |
+
+## Project Structure
+
+```
+easyp/
+├── cmd/easyp/              # CLI entrypoint (main.go)
+├── internal/
+│   ├── api/                # CLI command handlers (Handler interface)
+│   ├── config/             # easyp.yaml parsing, validation, types
+│   ├── core/               # Business logic: lint, generate, download, breaking
+│   │   ├── models/         # Domain value objects
+│   │   ├── mocks/          # Generated mocks for core interfaces
+│   │   ├── path_helpers/   # Path utility functions
+│   │   └── templates/      # Init template files
+│   ├── rules/              # Lint rule implementations (one file per rule)
+│   ├── adapters/
+│   │   ├── console/        # Console adapter (stdin/stdout)
+│   │   ├── go_git/         # Git walker adapter
+│   │   ├── lock_file/      # Lock file adapter
+│   │   ├── module_config/  # Module config adapter
+│   │   ├── plugin/         # Plugin executors (local, remote, builtin, command)
+│   │   ├── prompter/       # Interactive prompts (bubbletea)
+│   │   ├── repository/     # Git repository adapter
+│   │   └── storage/        # Dependency cache/storage
+│   ├── flags/              # Global CLI flag definitions
+│   ├── fs/                 # Filesystem abstractions (DirWalker, FS)
+│   ├── logger/             # Structured logger wrapper (slog)
+│   ├── schemagen/          # JSON Schema generation logic
+│   └── version/            # Build version info
+├── mcp/easypconfig/        # MCP tool: easyp_config_describe
+├── schemas/                # Generated JSON Schema artifacts
+├── wellknownimports/       # Embedded well-known proto imports
+├── testdata/               # Test fixtures (proto files)
+├── docs/                   # Documentation site (Node.js)
+├── .agents/skills/sdd/     # Spec-Driven Development skill
+├── Taskfile.yml            # Task runner configuration
+├── Dockerfile              # Multi-stage Docker build
+├── .goreleaser.yaml        # Release configuration
+├── easyp.yaml              # EasyP's own config (dogfooding)
+└── easyp.lock              # Lock file for proto dependencies
+```
+
+## Running
+
+```sh
+task init               # Install dev tools (linter, gotestsum, mockery)
+task build              # Build binary
+task test               # Run tests (-race, -count=1)
+task lint               # Run golangci-lint + hadolint
+task quality            # Run both test and lint
+task coverage           # Open coverage report in browser
+task mocks              # Regenerate all mocks
+task schema:generate    # Regenerate JSON Schema artifacts
+task install            # Install binary to GOPATH
+```
+
+## Key Interfaces / Entry Points
+
+| Interface | Location | Purpose |
+|-----------|----------|---------|
+| `Handler` | `internal/api/interface.go` | CLI command handler: `Command() *cli.Command` |
+| `Rule` | `internal/core/dom.go` | Lint rule: `Message()` + `Validate(ProtoInfo)` |
+| `DirWalker` | `internal/core/fs.go` | Filesystem walking + read/write |
+| `FS` | `internal/core/fs.go` | File operations: Open, Create, Exists, Remove |
+| `Storage` | `internal/core/` | Dependency cache management |
+| `Executor` | `internal/adapters/plugin/interface.go` | Plugin execution |
+| `Repo` | `internal/core/dom.go` | Git repository operations |
+
+## Adding New Features
+
+### Adding a new lint rule
+1. Create `internal/rules/<rule_name>.go` with struct implementing `core.Rule`
+2. Create `internal/rules/<rule_name>_test.go` with test cases
+3. Add test fixtures to `testdata/` if needed
+4. Register in `internal/rules/builder.go` (add to the appropriate group function)
+5. Rule name is auto-derived: `PascalCase` → `UPPER_SNAKE_CASE`
+
+### Adding a new CLI command
+1. Create `internal/api/<command>.go` with struct implementing `Handler`
+2. Add `var _ Handler = (*CommandName)(nil)` for compile-time check
+3. Register in `cmd/easyp/main.go` via `buildCommand(...)` call
diff --git a/.spec/TESTING.md b/.spec/TESTING.md
new file mode 100644
index 0000000..57ae9ab
--- /dev/null
+++ b/.spec/TESTING.md
@@ -0,0 +1,185 @@
+<!-- generated: 2026-05-14, template: development.md -->
+# EasyP Testing
+
+## 1. Test Package Naming
+
+Tests use the **external test package** convention (`_test` suffix):
+
+```go
+package rules_test  // external package — tests internal/rules from outside
+```
+
+This enforces testing only through the public API of the package.
+
+## 2. Test File Structure
+
+Example from `internal/rules/enum_pascal_case_test.go`:
+
+```go
+package rules_test
+
+import (
+    "testing"
+
+    "github.com/stretchr/testify/require"
+    "github.com/yoheimuta/go-protoparser/v4/parser/meta"
+
+    "github.com/easyp-tech/easyp/internal/core"
+    "github.com/easyp-tech/easyp/internal/rules"
+)
+
+func TestEnumPascalCase_Validate(t *testing.T) {
+    t.Parallel()
+
+    tests := map[string]struct {
+        fileName   string
+        wantIssues *core.Issue
+        wantErr    error
+    }{
+        "invalid": {
+            fileName: invalidAuthProto,
+            wantIssues: &core.Issue{
+                Position: meta.Position{
+                    Line:   49,
+                    Column: 1,
+                },
+                SourceName: "social_network",
+                Message:    "enum name must be in PascalCase",
+                RuleName:   "ENUM_PASCAL_CASE",
+            },
+        },
+        "valid": {
+            fileName: validAuthProto,
+            wantErr:  nil,
+        },
+    }
+
+    for name, tc := range tests {
+        name, tc := name, tc
+        t.Run(name, func(t *testing.T) {
+            t.Parallel()
+
+            r, protos := start(t)
+
+            rule := rules.EnumPascalCase{}
+            issues, err := rule.Validate(protos[tc.fileName])
+            r.ErrorIs(err, tc.wantErr)
+            // ... assert issues
+        })
+    }
+}
+```
+
+## 3. Key Patterns
+
+### Table-Driven Tests (map-based)
+
+All rule tests use `map[string]struct{}` for test cases:
+
+```go
+tests := map[string]struct {
+    fileName   string
+    wantIssues *core.Issue
+    wantErr    error
+}{
+    "valid":   { ... },
+    "invalid": { ... },
+}
+```
+
+**Why map?** Test names are the keys — readable and self-documenting.
+
+### Parallel Execution
+
+All tests run in parallel:
+
+```go
+func TestFoo(t *testing.T) {
+    t.Parallel()
+    // ...
+    t.Run(name, func(t *testing.T) {
+        t.Parallel()
+        // ...
+    })
+}
+```
+
+### Variable Capture in Range Loops
+
+Loop variables are captured to avoid closure issues:
+
+```go
+for name, tc := range tests {
+    name, tc := name, tc  // capture
+    t.Run(name, func(t *testing.T) {
+        // safe to use name, tc in parallel subtests
+    })
+}
+```
+
+### Shared Test Helper: `start()`
+
+Rule tests use a `start(t)` helper that:
+- Creates a `require` asserter
+- Parses all test proto files from `testdata/`
+- Returns `(asserter, protoInfoMap)`
+
+### Test Fixtures
+
+Proto files for testing live in `testdata/` organized by scenario:
+- `testdata/valid/auth.proto` — valid proto file
+- `testdata/invalid/auth.proto` — proto file with known issues
+
+## 4. Mock Generation
+
+| Setting | Value |
+|---------|-------|
+| **Tool** | `mockery` v2.41.0 |
+| **Command** | `task mocks` |
+| **Output** | `mocks/` subdirectory next to interface |
+| **Config** | `with-expecter: true`, `inpackage: false`, `disable-version-string: true` |
+
+Generated mocks implement core interfaces (`Rule`, `DirWalker`, `Storage`, etc.) using `testify/mock`.
+
+**Usage in tests:**
+
+```go
+mockRule := mocks.NewMockRule(t)
+mockRule.EXPECT().Validate(mock.Anything).Return([]core.Issue{}, nil)
+```
+
+## 5. Integration Tests
+
+- No separate integration test suite — the project is a CLI tool
+- All tests are unit tests with mocked dependencies
+- Proto parsing is tested against real `.proto` fixtures in `testdata/`
+- Build tags are not used for test separation
+
+## 6. Commands
+
+```bash
+# Unit tests (with race detector)
+task test
+
+# Coverage report (opens in browser)
+task coverage
+
+# Regenerate mocks before testing
+task mocks
+
+# Full quality check (test + lint)
+task quality
+```
+
+### Running specific tests
+
+```bash
+# Single test
+go test -v -run TestEnumPascalCase ./internal/rules/
+
+# Single package
+go test -race -count=1 ./internal/core/
+
+# All tests with verbose output
+go test -v -race -count=1 ./...
+```
diff --git a/.spec/TOOLS.md b/.spec/TOOLS.md
new file mode 100644
index 0000000..0c6c925
--- /dev/null
+++ b/.spec/TOOLS.md
@@ -0,0 +1,110 @@
+<!-- generated: 2026-05-14, template: development.md -->
+# EasyP Tools
+
+## 0. Dev Environment Setup
+
+### Prerequisites
+
+| Tool | Version | Install |
+|------|---------|---------|
+| Go | 1.24+ | `brew install go` |
+| Task | v3 | `brew install go-task` |
+| golangci-lint | v2.1.6 | Installed via `task init` |
+| gotestsum | latest | Installed via `task init` |
+| mockery | v2.41.0 | Installed via `task init` |
+| hadolint | latest | Installed via `task init` |
+
+### First Run
+
+```bash
+git clone https://github.com/easyp-tech/easyp.git
+cd easyp
+task init       # Install all dev tools
+task build      # Build binary
+task test       # Verify everything works
+```
+
+## 1. Overview
+
+All commands are managed via [Task](https://taskfile.dev) v3 (`Taskfile.yml`). Run commands with `task <target>`.
+
+## 2. Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Build | `task build` |
+| Test | `task test` |
+| Lint | `task lint` |
+| Full quality check | `task quality` |
+| Coverage report | `task coverage` |
+| Regenerate mocks | `task mocks` |
+| Regenerate schemas | `task schema:generate` |
+| Check schema freshness | `task schema:check` |
+| Install binary | `task install` |
+| Init dev tools | `task init` |
+
+## 3. Detailed Command Groups
+
+### Testing
+
+```bash
+task test           # Run all tests with gotestsum (-race, -count=1)
+task coverage       # Generate and open coverage report in browser
+```
+
+- Uses `gotestsum` with `--format pkgname`
+- Always runs with `-race -count=1`
+- Outputs to stdout in human-readable format
+
+### Building
+
+```bash
+task build          # Build easyp binary (output: ./easyp)
+task install        # Install to $GOPATH/bin
+```
+
+### Linting
+
+```bash
+task lint           # Run golangci-lint + hadolint
+```
+
+- Go linter: `golangci-lint` v2.1.6 with staticcheck
+- Docker linter: `hadolint` for Dockerfile
+
+### Code Generation
+
+```bash
+task mocks              # Regenerate all mockery mocks
+task schema:generate    # Regenerate JSON Schema from Go types
+task schema:check       # Ensure schemas are up to date (used in CI)
+```
+
+**Mocks:**
+- Tool: `mockery` v2.41.0
+- Config: `with-expecter: true`, `inpackage: false`, `disable-version-string: true`
+- Output: `mocks/` subdirectory next to the interface
+
+**Schemas:**
+- Source-of-truth: `mcp/easypconfig` package
+- Output: `schemas/easyp-config-v1.schema.json` + `schemas/easyp-config.schema.json`
+
+## 4. CI/CD Cheatsheet
+
+Simulate the full CI pipeline locally:
+
+```bash
+task init       # Install tools (same as CI)
+task quality    # Runs both test and lint (same as CI)
+task schema:check  # Ensure schemas are fresh
+```
+
+## 5. Tool Installation
+
+| Tool | Install Command |
+|------|----------------|
+| Task | `brew install go-task` or `go install github.com/go-task/task/v3/cmd/task@latest` |
+| golangci-lint | `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6` |
+| gotestsum | `go install gotest.tools/gotestsum@latest` |
+| mockery | `go install github.com/vektra/mockery/v2@v2.41.0` |
+| hadolint | `brew install hadolint` |
diff --git a/.spec/agent-rules.md b/.spec/agent-rules.md
new file mode 100644
index 0000000..7c81196
--- /dev/null
+++ b/.spec/agent-rules.md
@@ -0,0 +1,53 @@
+<!-- generated: 2026-05-14, template: bootstrap.md -->
+# Agent Rules — EasyP
+
+Mandatory rules for AI agents working on the EasyP codebase.
+
+## Code Style
+
+- Follow [Effective Go](https://go.dev/doc/effective_go) conventions.
+- `golangci-lint` v2.1.6 with `staticcheck` enabled — all code must pass.
+- One type/concern per file. File name = `snake_case.go`.
+- Avoid global state. Dependencies are injected via constructors.
+- Use `var _ Interface = (*Struct)(nil)` to verify interface compliance at compile time.
+
+## Naming Conventions
+
+- **Files:** `snake_case.go` (e.g., `enum_pascal_case.go`)
+- **Test files:** `*_test.go` alongside the source file
+- **Packages:** short, lowercase, no underscores
+- **Rule structs:** PascalCase, auto-converted to `UPPER_SNAKE_CASE` for rule names
+- **Mock dirs:** `mocks/` subdirectory next to the interface definition
+- **Config fields:** `snake_case` in YAML, matching Go struct tags
+
+## Error Handling
+
+- **Always wrap errors with context:** `fmt.Errorf("funcName: %w", err)`
+- Never return bare errors — the call chain must be traceable.
+- Use sentinel errors (`var ErrX = errors.New(...)`) for expected conditions.
+- Use typed errors (structs implementing `error`) for domain-specific context (e.g., `OpenImportFileError`, `GitRefNotFoundError`).
+- Exit codes: `0` = success, `1` = issues found, `2` = infrastructure error.
+
+## Testing
+
+- Framework: `github.com/stretchr/testify` (`assert`, `require`).
+- Runner: `gotestsum` with `--format pkgname`.
+- Flags: `-race -count=1` (always).
+- Fixtures: proto files in `testdata/` organized by scenario.
+- Mocks: generated with `mockery` v2.41.0 into `mocks/` subdirectories.
+- Mockery config: `with-expecter: true`, `inpackage: false`, `disable-version-string: true`.
+- Each lint rule has a dedicated `*_test.go` file.
+
+## Dependencies
+
+- Add dependencies via `go get`. Update `go.mod` and `go.sum`.
+- Regenerate mocks after interface changes: `task mocks`.
+- Regenerate schemas after config type changes: `task schema:generate`.
+- Never vendor Go dependencies (Go modules only).
+
+## Formatting
+
+- Use `gofmt` / `goimports` (enforced by `golangci-lint`).
+- Comments: preserve all existing comments unrelated to your changes.
+- Logging: use the structured `logger.Logger` wrapper around `slog`. Log to stderr.
+- Output: use `fmt.Fprintf(w, ...)` for command output to stdout.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d86f336
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,398 @@
+# AGENTS.md — EasyP Project Guide
+
+This document is a reference for AI agents working on the EasyP codebase.
+It describes the project's purpose, tech stack, architecture, coding patterns,
+and development workflows.
+
+## Project Overview
+
+**EasyP** is a modern CLI toolkit for Protocol Buffers development. It provides:
+
+- **Linter** — enforces API design rules (compatible with buf's rule set).
+- **Breaking change detector** — source-level API compatibility checks against Git branches.
+- **Code generator** — invokes local, remote, builtin, and command-based protoc plugins.
+- **Package manager** — Git-based dependency management with a lock file (`easyp.lock`).
+- **Config validator** — validates `easyp.yaml` structure and emits JSON/text diagnostics.
+- **MCP integration** — `easyp_config_describe` tool for the Model Context Protocol.
+
+Repository: `github.com/easyp-tech/easyp`
+
+## Tech Stack
+
+| Area            | Technology                                                   |
+| --------------- | ------------------------------------------------------------ |
+| Language        | Go 1.24+                                                     |
+| CLI framework   | `github.com/urfave/cli/v2`                                   |
+| Proto parsing   | `github.com/yoheimuta/go-protoparser/v4`                     |
+| Proto compiling | `github.com/bufbuild/protocompile`                           |
+| Git operations  | `github.com/go-git/go-git/v5`                                |
+| WASM runtime    | `github.com/tetratelabs/wazero` (builtin plugins)            |
+| MCP SDK         | `github.com/modelcontextprotocol/go-sdk`                     |
+| JSON Schema     | `github.com/invopop/jsonschema`, `github.com/google/jsonschema-go` |
+| TUI             | `github.com/charmbracelet/bubbletea`, `lipgloss`             |
+| Testing         | `github.com/stretchr/testify`, `gotestsum`                   |
+| Mocking         | `github.com/vektra/mockery` (v2.41.0)                        |
+| Linting         | `golangci-lint` (v2.1.6, staticcheck enabled)                |
+| Task runner     | [Task](https://taskfile.dev) v3 (`Taskfile.yml`)             |
+| Config format   | YAML (`easyp.yaml`), env-var expansion via `envsubst`        |
+| Release         | GoReleaser v2 (multi-arch binaries, Docker, Homebrew)        |
+| CI              | GitHub Actions (`tests.yml`, `release.yml`, `docs.yml`)      |
+
+## Directory Structure
+
+```
+.
+├── cmd/easyp/              # CLI entrypoint (main.go)
+├── internal/
+│   ├── api/                # CLI command handlers (implement Handler interface)
+│   ├── config/             # easyp.yaml parsing, validation, types
+│   ├── core/               # Business logic: lint, generate, download, breaking, etc.
+│   │   ├── models/         # Domain value objects (Revision, CacheDownloadPaths, etc.)
+│   │   ├── mocks/          # Generated mocks for core interfaces
+│   │   ├── path_helpers/   # Path utility functions
+│   │   └── templates/      # Init template files
+│   ├── rules/              # Lint rule implementations (one file per rule)
+│   ├── adapters/
+│   │   ├── console/        # Console adapter (stdin/stdout interaction)
+│   │   ├── go_git/         # Git walker adapter (go-git)
+│   │   ├── lock_file/      # Lock file adapter
+│   │   ├── module_config/  # Module config adapter
+│   │   ├── plugin/         # Plugin executors (local, remote, builtin, command)
+│   │   │   └── wasm/       # WASM embedded plugins
+│   │   ├── prompter/       # Interactive prompts
+│   │   ├── repository/     # Git repository adapter
+│   │   └── storage/        # Dependency cache/storage
+│   ├── flags/              # Global CLI flag definitions
+│   ├── fs/                 # Filesystem abstractions (DirWalker, FS interface)
+│   ├── logger/             # Structured logger wrapper (slog)
+│   ├── schemagen/          # JSON Schema generation logic
+│   └── version/            # Build version info
+├── mcp/easypconfig/        # MCP tool: easyp_config_describe (source-of-truth for schema)
+├── schemas/                # Generated JSON Schema artifacts
+├── wellknownimports/       # Embedded well-known proto imports (google/protobuf/*)
+├── testdata/               # Test fixtures (proto files for rule tests)
+├── docs/                   # Documentation site (Node.js, deployed as Docker)
+├── .spec/                  # AI-agent documentation (architecture, CLI, domain, etc.)
+├── .github/workflows/      # CI pipelines
+├── .agents/skills/sdd/     # Spec-Driven Development skill for AI agents
+├── Taskfile.yml            # Task runner configuration
+├── Dockerfile              # Multi-stage Docker build
+├── .goreleaser.yaml        # Release configuration
+├── easyp.yaml              # EasyP's own config (dogfooding)
+└── easyp.lock              # Lock file for proto dependencies
+```
+
+## Architecture
+
+### Layered Architecture
+
+The project follows a **clean/hexagonal architecture** pattern with three layers:
+
+```
+cmd/easyp (main)  →  internal/api (handlers)  →  internal/core (business logic)
+                                                        ↓
+                                               internal/adapters (infrastructure)
+```
+
+1. **`cmd/easyp`** — Entrypoint. Creates `cli.App`, registers handlers, initializes logger.
+2. **`internal/api`** — CLI command handlers. Each handler implements the `Handler` interface (`Command() *cli.Command`). Responsible for parsing flags, reading config, building `Core`, and formatting output.
+3. **`internal/core`** — All business logic. The `Core` struct is the central orchestrator. It depends on interfaces (ports), not concrete implementations.
+4. **`internal/adapters`** — Infrastructure implementations of core interfaces (storage, git, plugins, console).
+
+### Layer Dependency Rules
+
+- `cmd/` may only import `internal/api/` and `internal/flags/`.
+- `internal/api/` may import `internal/core/`, `internal/config/`, `internal/flags/`, `internal/adapters/`.
+- `internal/core/` may **NOT** import `internal/adapters/` — depends on interfaces only.
+- `internal/adapters/` may import `internal/core/` (to implement its interfaces).
+
+### Key Interfaces (Ports)
+
+Defined in `internal/core/`:
+
+| Interface                  | Purpose                                        |
+| -------------------------- | ---------------------------------------------- |
+| `Rule`                     | Lint rule: `Message() string`, `Validate(ProtoInfo) ([]Issue, error)` |
+| `DirWalker`                | Filesystem walking + read/write abstraction    |
+| `FS`                       | File operations: `Open`, `Create`, `Exists`, `Remove` |
+| `Storage`                  | Dependency cache management                    |
+| `ModuleConfig`             | Module configuration reader                    |
+| `LockFile`                 | Lock file read/write                           |
+| `CurrentProjectGitWalker`  | Git-based directory walker for breaking checks |
+| `Repo`                     | Git repository operations (files, archive, revisions) |
+
+Defined in `internal/adapters/plugin/`:
+
+| Interface  | Purpose                                                  |
+| ---------- | -------------------------------------------------------- |
+| `Executor` | Plugin execution: `Execute(ctx, plugin, request) (response, error)` |
+
+There are four executor implementations: `local`, `remote`, `builtin` (WASM), and `command`.
+
+### Handler Pattern
+
+Each CLI command is a struct in `internal/api/` implementing:
+
+```go
+type Handler interface {
+    Command() *cli.Command
+}
+```
+
+Handlers are registered in `cmd/easyp/main.go` via `buildCommand(...)`.
+
+Current handlers: `Lint`, `Mod`, `Completion`, `Init`, `Generate`, `SchemaGen`, `LsFiles`, `Validate`, `BreakingCheck`.
+
+### Lint Rule Pattern
+
+Each rule is a separate file pair in `internal/rules/`:
+- `<rule_name>.go` — implementation
+- `<rule_name>_test.go` — tests
+
+A rule is a struct implementing `core.Rule`:
+
+```go
+var _ core.Rule = (*RuleName)(nil)
+
+type RuleName struct{
+    // Optional config fields
+}
+
+func (r *RuleName) Message() string {
+    return "human-readable error message"
+}
+
+func (r *RuleName) Validate(protoInfo core.ProtoInfo) ([]core.Issue, error) {
+    var res []core.Issue
+    // Iterate over proto elements, check conditions
+    // Use core.AppendIssue() to add issues (respects nolint comments)
+    return res, nil
+}
+```
+
+Rules are organized in groups: `MINIMAL`, `BASIC`, `DEFAULT`, `COMMENTS`, `UNARY_RPC`.
+The `internal/rules/builder.go` handles group expansion and rule construction.
+
+Rule names are auto-derived from struct names via `PascalCase → UPPER_SNAKE_CASE`
+(e.g., `EnumPascalCase` → `ENUM_PASCAL_CASE`).
+
+### Plugin Executors
+
+Code generation supports four plugin types, each with its own `Executor`:
+
+| Type      | Source field | Description                                 |
+| --------- | ------------ | ------------------------------------------- |
+| `local`   | `name`       | Invokes `protoc-gen-<name>` from PATH       |
+| `remote`  | `remote`     | Calls EasyP API service                     |
+| `builtin` | (internal)   | Runs WASM plugins via wazero                |
+| `command` | `command`    | Executes arbitrary command                  |
+| `path`    | `path`       | Invokes plugin at specific filesystem path  |
+
+## Development Workflow
+
+### Prerequisites
+
+```sh
+# Install all dev tools (linter, gotestsum, mockery)
+task init
+```
+
+### Common Commands
+
+```sh
+task build              # Build binary
+task test               # Run tests with gotestsum (-race, -count=1)
+task lint               # Run golangci-lint + hadolint
+task quality            # Run both test and lint
+task coverage           # Open coverage report in browser
+task mocks              # Regenerate all mocks
+task schema:generate    # Regenerate JSON Schema artifacts
+task schema:check       # Ensure schemas are up to date (CI)
+task install            # Install binary to GOPATH
+```
+
+### Testing Conventions
+
+- Tests use `testify` (`assert`, `require`).
+- Test fixtures live in `testdata/` (proto files organized by scenario).
+- Rule tests follow a consistent pattern: each rule has a dedicated `*_test.go`.
+- Mocks are generated with `mockery` into `mocks/` subdirectories next to the interfaces.
+- Mockery config: `with-expecter: true`, `inpackage: false`, `disable-version-string: true`.
+- Tests run with `-race -count=1` by default.
+- External test packages (`package rules_test`) — tests access only the public API.
+- All tests run in parallel (`t.Parallel()` at top and in subtests).
+- Table-driven tests use `map[string]struct{}` (map keys are test names).
+- Loop variable capture: `name, tc := name, tc` before `t.Run()`.
+- Shared `start(t)` helper in rule tests: parses fixtures, returns asserter + proto map.
+
+**Running specific tests:**
+```sh
+go test -v -run TestEnumPascalCase ./internal/rules/  # single test
+go test -race -count=1 ./internal/core/                # single package
+```
+
+### CI Pipeline
+
+| Workflow        | Trigger              | What it does                           |
+| --------------- | -------------------- | -------------------------------------- |
+| `tests.yml`     | push to main, all PRs | `task init` → `task test`             |
+| `release.yml`   | tag push             | GoReleaser: binaries, Docker, Homebrew |
+| `docs.yml`      | push to main (docs/) | Build & deploy docs site               |
+
+### Release Process
+
+- Releases are managed by GoReleaser v2 (`.goreleaser.yaml`).
+- Multi-arch builds: `darwin`, `linux`, `windows` × `amd64`, `arm64`, `arm`.
+- Docker images: `ghcr.io/easyp-tech/easyp` (multi-arch manifest, linux/amd64 + linux/arm64).
+- Homebrew tap: `easyp-tech/homebrew-tap`.
+- Triggered by pushing a Git tag.
+
+## Coding Conventions
+
+### General
+
+- **Go version**: 1.24+ (specified in `go.mod`).
+- **Module path**: `github.com/easyp-tech/easyp`.
+- **Error wrapping**: Always wrap errors with context: `fmt.Errorf("funcName: %w", err)`.
+- **Logging**: Use the structured `logger.Logger` wrapper around `slog`. Log to stderr.
+- **No global state**: Dependencies are injected via constructors (e.g., `core.New(...)`).
+- **Interface compliance**: Use `var _ Interface = (*Struct)(nil)` to verify at compile time.
+
+### Naming
+
+- **Files**: `snake_case.go` (one type/concern per file).
+- **Rule files**: Named after the rule in `snake_case` (e.g., `enum_pascal_case.go`).
+- **Test files**: `*_test.go` alongside the source file.
+- **Mock directories**: `mocks/` subdirectory next to the interface definition.
+- **Packages**: Short, lowercase, no underscores.
+
+### Import Ordering
+
+```go
+import (
+    // 1. Standard library
+    "context"
+    "fmt"
+    "os"
+
+    // 2. Third-party
+    "github.com/urfave/cli/v2"
+
+    // 3. Internal packages
+    "github.com/easyp-tech/easyp/internal/config"
+    "github.com/easyp-tech/easyp/internal/core"
+)
+```
+
+Groups separated by blank lines, sorted alphabetically within each group.
+
+### Config & Schema
+
+- `easyp.yaml` is the single configuration file (parsed in `internal/config/`).
+- Environment variable expansion is supported via `envsubst` (escape with `$$`).
+- JSON Schema artifacts in `schemas/` are auto-generated from Go types (`task schema:generate`).
+- The `mcp/easypconfig` package is the source-of-truth for schema + MCP tool metadata.
+- **Always regenerate schemas** after modifying config types: `task schema:generate`.
+
+### Docker
+
+- Multi-stage build: `golang:1.25-alpine` builder → `alpine:3.22` runtime.
+- Runtime includes: `ca-certificates`, `tzdata`, `git`, `bash`.
+- CGO disabled (`CGO_ENABLED=0`).
+
+## Important Domain Concepts
+
+### Proto Info
+
+`core.ProtoInfo` is the central data structure passed to every lint rule. It contains:
+- `Path` — file path of the proto file
+- `Info` — parsed unordered proto AST (`*unordered.Proto`)
+- `ProtoFilesFromImport` — map of imported proto files (for cross-file checks)
+
+### Issue Reporting
+
+Issues are reported via `core.Issue` with position, source name, message, and rule name.
+Use `core.AppendIssue()` — it automatically checks for `nolint:` / `buf:lint:ignore` comments.
+
+### Dependency Management
+
+- Dependencies are declared in `easyp.yaml` under `deps:` (Git URLs with optional `@version`).
+- Downloaded to a local cache (`~/.cache/easyp/` or similar).
+- Lock file (`easyp.lock`) tracks exact revisions.
+- Well-known imports (`google/protobuf/*`) are embedded in the binary via `wellknownimports/`.
+
+### Breaking Change Detection
+
+- Compares the current proto files against a Git reference (branch/tag/commit).
+- Uses `go-git` to read files from the reference, then compiles both versions
+  with `protocompile` and compares descriptors.
+
+## Error Handling
+
+### Exit Codes
+
+| Code | Meaning | Triggering Errors |
+|------|---------|-------------------|
+| `0` | Success / no issues | — (or `ErrEmptyInputFiles` as warning) |
+| `1` | Issues found | `ErrHasLintIssue`, `ErrBreakingCheckIssue`, `ErrHasValidateIssue`, `ErrVersionNotFound` |
+| `2` | Infrastructure error | `OpenImportFileError`, `GitRefNotFoundError`, `ErrRepositoryDoesNotExist` |
+
+### Error Types
+
+**Sentinel errors** — identity-only, compared with `errors.Is()`:
+```go
+var ErrVersionNotFound = errors.New("version not found")         // models/errors.go
+var ErrRepositoryDoesNotExist = errors.New("repository does not exist") // core/core.go
+```
+
+**Typed errors** — carry extra context, compared with `errors.As()`:
+```go
+type OpenImportFileError struct{ FileName string }  // core/dom.go
+type GitRefNotFoundError struct{ GitRef string }     // core/dom.go
+```
+
+### Wrapping Convention
+
+Always wrap with the calling function name:
+```go
+return fmt.Errorf("storage.Download: %w", err)  // adapter
+return fmt.Errorf("core.Download: %w", err)     // core
+```
+
+### Logging Rule
+
+**Log at the top (API), wrap at the bottom (adapters/core).** Never log and return the same error.
+
+| Layer | Level | Action |
+|-------|-------|--------|
+| API | `Error`/`Warn` | Log + `os.Exit()` |
+| Core | — | Wrap and return |
+| Adapters | `Debug` | Infrastructure details only |
+
+## Documentation
+
+Detailed documentation lives in `.spec/`:
+
+| Document | Purpose |
+|----------|---------|
+| `README.md` | Documentation index, quick facts, project structure |
+| `ARCHITECTURE.md` | Layered architecture, component diagram, data flow |
+| `PACKAGES.md` | Go package inventory with responsibilities |
+| `DOMAIN.md` | Core types, interfaces, domain rules |
+| `CODE_STYLE.md` | Layer rules, naming, error propagation, import ordering |
+| `CLI.md` | Full CLI command reference (flags, exit codes, I/O) |
+| `TOOLS.md` | Task runner commands, dev setup |
+| `TESTING.md` | Test framework, patterns, mocks, fixtures |
+| `ERRORS.md` | Complete error catalog, wrapping, exit code mapping |
+| `DEPLOYMENT.md` | Docker, CI/CD, GoReleaser, release process |
+| `agent-rules.md` | Mandatory rules for AI agents |
+
+Use `.spec/` for deep dives. Use this `AGENTS.md` as the entry point.
+
+## Skills
+
+The project includes the **SDD (Spec-Driven Development)** skill in `.agents/skills/sdd/`.
+Use it for structured feature development with the 6-phase pipeline:
+`Explore → Requirements → Design → Task Plan → Implementation → Review`.
+
+See `.agents/skills/sdd/SKILL.md` for full documentation.