@esoteric-logic/praxis-harness 2.1.1 → 2.3.0

package/base/CLAUDE.md

@@ -81,7 +81,13 @@ Registered via `claude mcp add`. Persist globally across sessions.
 | context7 | Live library/API docs | None |
 | github | Repo operations, PRs, issues | `GITHUB_PERSONAL_ACCESS_TOKEN` |
 
-Optional: `perplexity` (AI web search). Run `bash scripts/onboard-mcp.sh perplexity` to add.
+**Optional servers** — enhance but don't require Praxis:
+
+| Server | Purpose | Install | Degrades without |
+|--------|---------|---------|-----------------|
+| perplexity | AI web search | `bash scripts/onboard-mcp.sh perplexity` | No web research in `/discover` |
+| filesystem | Direct vault file access | `claude mcp add filesystem` | Uses shell for vault reads |
+| sequential-thinking | Multi-step reasoning | `claude mcp add sequential-thinking` | Standard reasoning only |
 
 Check: `claude mcp list` | Manage: `bash scripts/onboard-mcp.sh [server|all]`
 Missing servers are non-blocking — features degrade gracefully.
@@ -116,12 +122,15 @@ Kits activate via `/kit:<n>` slash command. Kits are idempotent — double-activ
 |-----|----------|--------|
 | web-designer | `/kit:web-designer` | Design system → components → accessibility → production lint |
 | infrastructure | `/kit:infrastructure` | Terraform → Azure → GitHub Actions → compliance |
+| api | `/kit:api` | RESTful conventions → OpenAPI specs → contract testing |
+| security | `/kit:security` | Threat modeling → IAM review → OWASP audit |
+| data | `/kit:data` | Schema design → migration planning → query optimization |
 
 Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 
 ## Rules Registry — Load on Demand Only
 
-### Universal — always active (6 rules)
+### Universal — always active (7 rules)
 | File | Purpose |
 |------|---------|
 | `~/.claude/rules/profile.md` | Who the user is, identities, working style |
@@ -130,6 +139,7 @@ Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 | `~/.claude/rules/git-workflow.md` | Commits, branches, identity verification, pre-commit checks |
 | `~/.claude/rules/vault.md` | Second brain integration — vault backend, file purposes |
 | `~/.claude/rules/context-management.md` | Context anti-rot, phase scoping, context reset protocol |
+| `~/.claude/rules/memory-boundary.md` | Auto-memory boundary, MEMORY.md cap, dream integration |
 
 ### Scoped — load only when paths match
 | File | Loads when |

package/base/rules/context-management.md

@@ -82,6 +82,18 @@ ls -la {vault_path}/plans/
 stat -f "%Sm" {vault_path}/status.md
 ```
 
+## Memory Hygiene — Conventions (WARN on violation)
+
+### Before starting a new kit or major task
+1. Run `/dream` (if available) to consolidate stale auto-memory
+2. Run `/sync-memory` to bridge durable insights to Obsidian vault
+3. Proceed with clean, consolidated context
+
+### MEMORY.md cap
+- Keep under 80 lines. Auto-dream and `/sync-memory` enforce this.
+- If MEMORY.md exceeds 80 lines: run `/sync-memory` before continuing.
+- See `~/.claude/rules/memory-boundary.md` for full boundary rules.
+
 ---
 
 ## Removal Condition

package/base/rules/memory-boundary.md

@@ -0,0 +1,56 @@
+# Memory Boundary — Rules
+# Scope: All projects, all sessions
+# Defines what goes where across CLAUDE.md, MEMORY.md, and Obsidian vault
+
+## Invariants — BLOCK on violation
+
+### CLAUDE.md rules always win
+- If a MEMORY.md entry conflicts with a CLAUDE.md rule or base/ rule, the rule wins.
+- Never override architectural decisions, coding standards, or workflow sequences via auto-memory.
+- Auto-memory supplements rules — it does not replace them.
+
+### No architectural decisions in MEMORY.md
+- Architecture decisions, design patterns, and system constraints belong in CLAUDE.md or Obsidian vault specs/.
+- If Claude discovers a decision-worthy pattern during a session, surface it to the user for CLAUDE.md or vault — do not write it to MEMORY.md.
+
+### MEMORY.md cap
+- Keep MEMORY.md under 80 lines. Use topic files for overflow.
+- Prefer linking to Obsidian vault notes over expanding MEMORY.md.
+- If MEMORY.md exceeds 80 lines: run `/sync-memory` before continuing.
+- The 200-line hard limit means lines beyond 200 are silently dropped — the 80-line cap leaves headroom for topic file index entries.
+
+## Conventions — WARN on violation
+
+### What belongs where
+
+| Content | Destination | Managed by |
+|---------|-------------|------------|
+| Coding standards, workflows, architecture | `CLAUDE.md` / `base/rules/` | User (Praxis) |
+| Build quirks, CLI flags, error patterns | `MEMORY.md` | Claude (auto-memory + auto-dream) |
+| Architecture decisions, project status, session summaries | Obsidian vault | User (via Praxis skills) |
+| Kit configs, path-scoped rules | `kits/` and `base/rules/` | User (Praxis) |
+| Stale or conflicting memory entries | Deleted | Auto-dream consolidation or `/sync-memory` |
+
+### Auto-memory territory (appropriate for MEMORY.md)
+- Build commands and environment quirks Claude discovers
+- Debugging insights specific to this working tree
+- API gotchas, error patterns, CLI flags that worked
+- User preferences Claude infers from corrections
+- Tool configuration that varies per machine
+
+### Not auto-memory territory (redirect elsewhere)
+- Decisions that affect system design → CLAUDE.md or vault specs/
+- Cross-project learnings → vault notes/learnings.md
+- Session summaries → vault notes/ (auto-documented by Stop hook)
+- Task tracking → vault tasks.md
+- Plans and milestones → vault plans/
+
+### Dream and consolidation
+- Run `/dream` (if available) between sessions to consolidate stale memory
+- Run `/sync-memory` to bridge durable insights from MEMORY.md to Obsidian vault
+- Auto-dream fires automatically after 24h + 5 sessions — the memory-boundary rules guide what it keeps vs prunes
+- After `/dream` or auto-dream runs: verify MEMORY.md is under 80 lines
+
+## Removal Condition
+Remove when Claude Code provides native memory scoping that respects rule hierarchies
+and vault integration without manual boundary enforcement.

package/base/skills/context-probe/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: context-probe
+disable-model-invocation: true
+description: "Assess current context health and recommend action. Reads session data and conversation signals to estimate context bracket (FRESH/MODERATE/DEPLETED/CRITICAL)."
+---
+
+# context-probe Skill
+
+You are assessing the current session's context health.
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`.
+
+---
+
+**Step 1 — Gather signals**
+
+Assess these indicators (do NOT read external files just for this — use what you already know):
+
+| Signal | How to assess |
+|--------|--------------|
+| Conversation length | Estimate from your sense of how much has been discussed |
+| Tool calls made | Rough count of reads, writes, bash calls this session |
+| Files touched | How many files have been read or edited |
+| Corrections received | How many times the user corrected your output |
+| Compaction occurred | Did you receive a compaction bootstrap? |
+| Active task complexity | Simple (1-2 files) vs complex (5+ files, multi-milestone) |
+
+**Step 2 — Estimate bracket**
+
+| Bracket | Signals | Action |
+|---------|---------|--------|
+| **FRESH** | <10 tool calls, <5 files, no corrections, no compaction | Full speed. Batch aggressively. Load full context. |
+| **MODERATE** | 10-30 tool calls, 5-15 files, 0-1 corrections | Re-read key requirements before decisions. Prefer concise output. |
+| **DEPLETED** | 30+ tool calls, 15+ files, 2+ corrections, OR scope drift detected | Checkpoint to vault NOW. Write milestone summaries. Suggest `/session-retro` + `/clear`. |
+| **CRITICAL** | Post-compaction, OR repeated corrections, OR instruction drift | STOP new work. Complete current milestone only. Write all state to vault. Start new session. |
+
+**Step 3 — Report**
+
+```
+CONTEXT PROBE
+━━━━━━━━━━━━━━━━━━━━━
+Bracket:  {FRESH | MODERATE | DEPLETED | CRITICAL}
+Signals:  {key indicators}
+Action:   {recommendation}
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Step 4 — Act on DEPLETED/CRITICAL**
+
+If DEPLETED or CRITICAL:
+1. Update `{vault_path}/status.md` with current state
+2. Write any in-progress decisions to the active plan file
+3. Suggest: "Context is [bracket name]. Recommend `/session-retro` then `/clear` for a fresh start."
+
+## Removal Condition
+Remove when Claude Code exposes token count or context utilization metrics natively.

package/base/skills/repair/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: repair
+disable-model-invocation: true
+description: "Structured repair phase for failed milestones. 3-attempt fix-and-verify loop with root cause analysis. Triggered by /verify failure or manually."
+---
+
+# repair Skill
+
+You are running a structured repair cycle for a failed milestone.
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`.
+
+## Acceptance
+- [ ] Failure captured with exact error, file, line
+- [ ] Root cause classified (flawed implementation vs flawed spec)
+- [ ] Fix applied with minimal diff
+- [ ] Validation passes after fix
+- [ ] Repair trace written to vault
+
+## Boundaries
+- No refactoring — fix the failure, nothing else
+- No scope expansion — do not add features or change behavior beyond the fix
+- No new files unless the fix requires them
+- Maximum 3 attempts before STOP
+
+---
+
+**Step 1 — Capture failure**
+- Read the failure output from `/verify` (or ask user for the error)
+- Extract: exact error message, file(s), line number(s), test name (if applicable)
+- State the failure in one sentence:
+  `Failure: {what failed} in {file}:{line} because {symptom}.`
+
+**Step 2 — Classify root cause**
+Determine whether this is:
+- **Flawed implementation** → the code doesn't match the spec. Fix forward.
+- **Flawed spec** → the spec itself is wrong or incomplete. STOP.
+  Report to user: "Spec issue detected: [describe the issue]. Run `/discuss` to re-spec before continuing."
+  Do not attempt to fix spec issues — that's a different phase.
+
+**Step 3 — Fix attempt (attempt {n}/3)**
+- State what you're changing and why in one sentence
+- Apply the minimal fix — smallest diff that addresses the root cause
+- Do not refactor surrounding code
+- Do not fix unrelated issues discovered during repair
+
+**Step 4 — Re-validate**
+Run the full validation sequence from `/verify` Step 1:
+1. Test suite
+2. Linter
+3. Typecheck (if applicable)
+4. Build (if applicable)
+
+**Step 5 — Evaluate result**
+- **PASS** → Milestone repaired. Commit the fix. Return to workflow.
+  Output: `Repaired: {what was fixed} in {file}. Next: continue with /execute or /verify.`
+- **FAIL (same error)** → Root cause was misidentified. Re-analyze in Step 2.
+- **FAIL (different error)** → Fix introduced a regression. Revert the fix, re-analyze.
+- Track attempt count. If attempt 3 fails → Step 6.
+
+**Step 6 — STOP after 3 failures**
+Do not attempt a 4th fix. Report:
+
+```
+REPAIR FAILED — 3 attempts exhausted
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What:    {original failure + all 3 attempt descriptions}
+So What: {root cause analysis — why 3 fixes didn't work}
+Now What: {recommended next step: re-spec, different approach, escalate}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Step 7 — Write repair trace to vault**
+Whether the repair succeeded or failed, write to `{vault_path}/notes/{YYYY-MM-DD}_repair-trace.md`:
+
+```markdown
+---
+tags: [repair, {project-slug}]
+date: {YYYY-MM-DD}
+source: agent
+---
+# Repair Trace — {short title}
+
+## Original Failure
+{error message, file, line}
+
+## Root Cause
+{classification: flawed implementation | flawed spec}
+{root cause statement}
+
+## Attempts
+### Attempt 1
+- Fix: {what was changed}
+- Result: {PASS | FAIL — error}
+
+### Attempt 2 (if applicable)
+- Fix: {what was changed}
+- Result: {PASS | FAIL — error}
+
+### Attempt 3 (if applicable)
+- Fix: {what was changed}
+- Result: {PASS | FAIL — error}
+
+## Resolution
+{Fixed in attempt N | FAILED — escalated}
+```
+
+**Step 8 — Write learning (if applicable)**
+If the repair reveals a recurring pattern, write a `[LEARN:bugfix]` entry to `{vault_path}/notes/learnings.md`.
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| No failure output provided | Ask user for error details |
+| Spec issue detected | STOP, redirect to `/discuss` |
+| Fix causes new failure | Revert fix, count as failed attempt |
+| Cannot identify root cause | Count as failed attempt, try different angle |
+
+## Callers
+
+| Caller | When |
+|--------|------|
+| `/verify` Step 4 | On FAIL — delegates to `/repair` |
+| Manual `/repair` | Any time a fix is needed |
+
+## Removal Condition
+Remove when an automated repair agent (e.g., SWE-agent) handles fix-and-verify loops with equivalent quality.

package/base/skills/review/SKILL.md

@@ -28,6 +28,7 @@ Ask: "Review staged changes, last commit, or specific SHA?"
   - Any file → `~/.claude/rules/coding.md`
 
 **Step 4 — Launch subagent review**
+Follow the subagent dispatch protocol (see `/subagent` skill for reference).
 Launch a subagent with ONLY these inputs (zero conversation history):
 - The diff
 - The SPEC (if available from Step 3)

package/base/skills/simplify/SKILL.md

@@ -35,6 +35,7 @@ Determine what to simplify:
 
 ## Phase 2 — Launch Subagent
 
+Follow the subagent dispatch protocol (see `/subagent` skill for reference).
 Launch a subagent with ONLY these inputs (zero conversation history):
 
 ```

package/base/skills/subagent/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: subagent
+disable-model-invocation: true
+description: "Reference protocol for subagent dispatch. Defines how to package context, spawn, interpret results, and escalate findings. Not invoked directly — referenced by review, simplify, verify-app, and verify skills."
+---
+
+# Subagent Dispatch Protocol
+
+This is a reference protocol, not a directly invocable skill. Skills that spawn subagents
+(review, simplify, verify-app, verify) follow this protocol for consistency.
+
+---
+
+## Step 1 — Package Context
+
+Subagents receive ONLY these inputs. Zero conversation history.
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Diff | `git diff` output scoped to the task | Yes |
+| SPEC | `## SPEC` section from the active plan file | If available |
+| Rules | Relevant `~/.claude/rules/*.md` based on file types in diff | Yes |
+| Project config | Project CLAUDE.md `## Commands` and `## Code Style` | If available |
+
+**Never include:**
+- Conversation history
+- User preferences or profile
+- Vault state or session notes
+- Full plan file (only SPEC section)
+
+## Step 2 — Define Role
+
+One sentence. The role constrains the subagent's perspective.
+
+Examples:
+- "You are a critical code reviewer."
+- "You are a code simplification expert."
+- "You are a regression analyst."
+- "You are a security auditor."
+
+## Step 3 — Define Task
+
+Specific questions or analysis to perform. Include:
+- What to look for (bugs, complexity, regressions, etc.)
+- What NOT to do (don't suggest features, don't change behavior)
+- Scope boundaries (only these files, only this diff)
+
+## Step 4 — Define Output Format
+
+All subagent findings use this structure:
+
+```
+{file}:{line} — {severity} — {category} — {description} — {fix}
+```
+
+**Severity levels** (consistent across all subagent types):
+- **Critical** — Must fix before proceeding. Blocks merge/ship.
+- **Major** — Should fix before merge. Recommend addressing.
+- **Minor** — Note for future cleanup. Does not block.
+
+**If the subagent finds nothing:** Output "No findings." (not an empty list)
+
+## Step 5 — Spawn
+
+Launch an Agent with:
+- `subagent_type`: use `general-purpose` for review/analysis tasks
+- `prompt`: role + task + inputs + output format
+- Description: short (3-5 words) summary of what the subagent does
+
+```
+Agent(
+  description: "Review diff for bugs",
+  prompt: "{role}\n\n{task}\n\n## Diff\n{diff}\n\n## SPEC\n{spec}\n\n## Rules\n{rules}\n\n{output format}"
+)
+```
+
+## Step 6 — Interpret Results
+
+Parse the subagent output:
+1. Group findings by severity (Critical → Major → Minor)
+2. Count findings per severity
+3. If output is unparseable: treat entire output as a single Minor finding
+
+## Step 7 — Escalate
+
+| Severity | Action |
+|----------|--------|
+| Critical (any) | Block. Address immediately before proceeding. |
+| Major (any) | Recommend fixing before merge. |
+| Minor only | Note for future cleanup. Proceed. |
+| No findings | "Clean." Proceed. |
+
+**Re-review threshold:** If >3 findings were addressed, re-run the subagent (max 3 rounds).
+
+---
+
+## Callers
+
+| Skill | Subagent Role | Spawned At |
+|-------|---------------|------------|
+| `/review` | Critical code reviewer | Step 4 |
+| `/simplify` | Code simplification expert | Phase 2 |
+| `/verify-app` | Regression analyst | Phase 3 |
+| `/verify` | Critical code reviewer (self-review) | Step 5 |
+| `/repair` | (uses /verify internally, which spawns subagent) | — |
+
+## Removal Condition
+Remove when Claude Code provides a native subagent dispatch API with
+structured input/output handling.

package/base/skills/sync-memory/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: sync-memory
+disable-model-invocation: true
+description: "Bridge auto-memory insights to Obsidian vault. Reads MEMORY.md and topic files, syncs durable entries to vault learnings, prunes stale content. Side-effect skill — never auto-triggers."
+---
+
+# sync-memory Skill
+
+You are syncing Claude's auto-memory to the Obsidian vault.
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`.
+
+## Acceptance
+- [ ] MEMORY.md and topic files read
+- [ ] Durable insights synced to vault
+- [ ] Stale entries pruned
+- [ ] MEMORY.md under 80 lines after sync
+
+---
+
+**Step 1 — Locate memory files**
+- Find the auto-memory directory for the current project:
+  `~/.claude/projects/-{escaped-cwd}/memory/`
+- Read `MEMORY.md` (the index file)
+- Read all topic files referenced by MEMORY.md (e.g., `user_preferences.md`, `feedback_testing.md`)
+- If no memory files exist: "No auto-memory to sync." Exit.
+
+**Step 2 — Classify each entry**
+
+For each entry in MEMORY.md and topic files, classify:
+
+| Classification | Action |
+|---------------|--------|
+| **Project-specific insight** (error pattern, build quirk, API gotcha) | Append to `vault/notes/learnings.md` as `[LEARN:memory-sync]` |
+| **Global preference** (coding style, tool preference) | Present to user: "Add to CLAUDE.md Error Learning? [entry]" |
+| **Architecture decision** | Present to user: "This belongs in vault specs/ or CLAUDE.md — not MEMORY.md" |
+| **Already in vault** | Skip — note as duplicate |
+| **Stale/outdated** (references deleted files, old versions, resolved bugs) | Mark for pruning |
+| **Machine-specific** (paths, env vars, tool locations) | Keep in MEMORY.md — appropriate for auto-memory |
+
+**Step 3 — Sync to vault**
+
+For project-specific insights, append to `vault/notes/learnings.md`:
+```markdown
+## [LEARN:memory-sync] [short title]
+- **What**: [the insight]
+- **So What**: [why it matters]
+- **Now What**: [how to apply it]
+- **Date**: [YYYY-MM-DD]
+- **Source**: auto-memory sync
+```
+
+**Step 4 — Prune MEMORY.md**
+
+After syncing:
+1. Remove entries that were synced to vault (they now live in the canonical store)
+2. Remove stale/outdated entries
+3. Keep machine-specific and active debugging entries
+4. Verify MEMORY.md is under 80 lines
+5. If still over 80 lines: consolidate further — merge similar entries, shorten descriptions
+
+**Step 5 — Report**
+
+```
+MEMORY SYNC
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Synced:    [n] entries → vault learnings
+Surfaced:  [n] entries for CLAUDE.md review
+Pruned:    [n] stale entries removed
+Kept:      [n] entries in MEMORY.md
+Lines:     [n] / 80 limit
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| No memory files found | Exit cleanly |
+| Vault path missing | Warn, skip vault sync, still prune |
+| MEMORY.md empty | "Nothing to sync." Exit. |
+| Cannot classify an entry | Keep it — don't prune what you don't understand |
+
+## When to Run
+
+- Before starting a new kit (`/kit:<name>`)
+- Before `/context-reset` or `/clear`
+- At session end (optional — Stop prompt handles most vault writes)
+- When MEMORY.md exceeds 80 lines
+
+## Removal Condition
+Remove when Claude Code provides native memory-to-vault sync or when
+auto-dream learns to respect vault integration boundaries natively.

package/base/skills/verify/SKILL.md

@@ -69,12 +69,11 @@ After self-review passes, write phase summary:
 - `/simplify` runs after UNIFY, before shipping. It is the quality gate between "it works" and "it's clean".
 
 **Step 4 — On FAIL (Stop-and-Fix)**
-1. Identify the failure: exact error, file, line
-2. Fix NOW. Do not proceed to the next milestone.
-3. Re-run the full validation sequence (Step 1)
-4. If still failing after 3 attempts: STOP.
-   Report: **What** (full error + 3 attempts) → **So What** (root cause) → **Now What** (next steps)
-5. Write failure details to the active plan file if >1 attempt was needed
+Run `/repair` — it handles the structured fix-and-verify loop:
+- Captures the failure, classifies root cause, attempts up to 3 fixes
+- Re-runs validation after each attempt
+- STOPs with What/So What/Now What after 3 failures
+- Writes repair trace and learnings to vault
 
 **Rules:**
 - Never say "tests pass" without showing output.

package/base/skills/verify-app/SKILL.md

@@ -76,6 +76,7 @@ For each item in the plan's `## Done When`:
 
 ## Phase 3 — Regression Check
 
+Follow the subagent dispatch protocol (see `/subagent` skill for reference).
 Launch a subagent with zero conversation history:
 
 ```

package/kits/api/KIT.md

@@ -0,0 +1,48 @@
+---
+name: api
+version: 1.0.0
+description: "API design — RESTful conventions, OpenAPI specs, contract testing, endpoint review"
+activation: /kit:api
+deactivation: /kit:off
+skills_chain:
+  - phase: spec
+    skills: []
+    status: planned
+  - phase: review
+    skills: []
+    status: planned
+  - phase: contract
+    skills: []
+    status: planned
+mcp_servers: []
+rules:
+  - api-design.md
+removal_condition: >
+  Remove when API design is fully handled by a dedicated API gateway or design tool
+  with no manual Claude-driven operations remaining.
+---
+
+# API Kit
+
+## Purpose
+Enforce API design best practices across RESTful and GraphQL endpoints.
+Covers spec generation, endpoint review, and contract test scaffolding.
+
+## Skills Chain
+
+| # | Phase | Command | What It Provides |
+|---|-------|---------|-----------------|
+| 1 | Spec | `/api:spec` | Generate or validate OpenAPI spec from code |
+| 2 | Review | `/api:review` | Endpoint naming, versioning, error codes, auth patterns |
+| 3 | Contract | `/api:contract` | Generate contract tests from OpenAPI spec |
+
+## Workflow Integration
+
+This kit operates WITHIN the Praxis workflow:
+- **Praxis** structures the work (discuss → plan → execute → verify → simplify → ship)
+- **This kit** adds API-specific rules and commands
+
+## Prerequisites
+
+Run `install.sh` in this directory to check for required CLI tools.
+Verify with `/kit:api` after install.

package/kits/api/commands/api-contract.md

@@ -0,0 +1,18 @@
+---
+description: "Generate contract tests from an OpenAPI spec or route definitions"
+---
+
+# api:contract
+
+## Steps
+
+1. **Locate spec** — read `docs/openapi.yaml` or detect routes from code
+2. **For each endpoint**, generate a contract test that verifies:
+   - Response status code matches expected
+   - Response body matches schema
+   - Required fields are present
+   - Error responses follow the standard format
+3. **Detect test framework** — Jest, pytest, Go testing, etc.
+4. **Write tests** to project test directory
+5. **Run tests** — execute and report results
+6. **Report** — tests generated, pass/fail counts

package/kits/api/commands/api-review.md

@@ -0,0 +1,19 @@
+---
+description: "Review API endpoints for naming, versioning, error handling, and auth patterns"
+---
+
+# api:review
+
+## Steps
+
+1. **Identify scope** — review all endpoints, or specific routes if user specifies
+2. **Launch subagent** (follow `/subagent` protocol) with role: "API design reviewer"
+3. **Check against api-design rules:**
+   - RESTful naming conventions
+   - HTTP status code usage
+   - Error response format consistency
+   - Authentication/authorization patterns
+   - Pagination implementation
+   - Versioning strategy
+4. **Present findings** by severity (Critical/Major/Minor)
+5. **Write review** to vault `specs/api-review-{date}.md`

package/kits/api/commands/api-spec.md

@@ -0,0 +1,19 @@
+---
+description: "Generate or validate an OpenAPI spec from the current codebase"
+---
+
+# api:spec
+
+## Steps
+
+1. **Detect API framework** — scan for route definitions (Express, FastAPI, Gin, etc.)
+2. **Extract endpoints** — list all routes with methods, paths, handlers
+3. **Generate OpenAPI 3.x spec** — for each endpoint:
+   - Path and method
+   - Request parameters (path, query, header)
+   - Request body schema (from types/models)
+   - Response schemas (success + error)
+   - Authentication requirements
+4. **Validate against api-design rules** — flag violations
+5. **Write spec** to `docs/openapi.yaml` (or project-configured location)
+6. **Report** — endpoints found, violations flagged, spec location