@haposoft/cafekit 0.8.15 → 0.8.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.15",
+  "version": "0.8.17",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/CLAUDE.md

@@ -88,6 +88,8 @@ Consult these when the task touches the relevant area:
 
 - Primary workflow: `./.claude/rules/workflow.md`
 - Development rules: `./.claude/rules/ai-dev-rules.md`
+- Skill workflow routing: `./.claude/rules/skill-workflow-routing.md`
+- Skill domain routing: `./.claude/rules/skill-domain-routing.md`
 - Subagent coordination: `./.claude/rules/orchestrator.md`
 - Docs maintenance: `./.claude/rules/manage-docs.md`
 - State sync: `./.claude/rules/state-sync.md`
@@ -97,6 +99,8 @@ Consult these when the task touches the relevant area:
 ## Skill And Script Use
 
 - Evaluate the available skills catalog before work and activate the relevant skill(s).
+- Use `./.claude/rules/skill-workflow-routing.md` and `./.claude/rules/skill-domain-routing.md` to choose skills. CafeKit does not auto-route prompts through a scoring hook.
+- When needed, run `node .claude/scripts/generate-skill-catalog.cjs --skills` to inspect the installed skill catalog.
 - If there is a reasonable chance a skill applies, prefer the skill workflow over ad hoc execution.
 - If modifying skills, edit the current project/runtime files, not `~/.claude/skills` directly.
 - Run Python skill scripts with the skill venv:

package/src/claude/hooks/lib/config.cjs

@@ -64,7 +64,6 @@ const DEFAULT_CONFIG = {
     'session-init': true,
     'subagent-init': true,
     'dev-rules-reminder': true,
-    'skill-router': true,
     'usage': true,
     'context-tracking': true,
     'scout-block': true,

package/src/claude/hooks/lib/context.cjs

@@ -358,7 +358,7 @@ function buildRulesSection({ devRulesPath, catalogScript, skillsVenv, plansPath,
   lines.push(`- **IMPORTANT:** DO NOT create markdown files outside of "${plansRef}" or "${docsRef}" UNLESS the user explicitly requests it.`);
 
   if (catalogScript) {
-    lines.push(`- Activate skills: Run \`python ${catalogScript} --skills\` to generate a skills catalog and analyze it, then activate the relevant skills that are needed for the task during the process.`);
+    lines.push(`- Activate skills: Use \`.claude/rules/skill-workflow-routing.md\` and \`.claude/rules/skill-domain-routing.md\`; run \`node ${catalogScript} --skills\` when you need a generated skills catalog.`);
   }
 
   if (skillsVenv) {
@@ -525,7 +525,7 @@ function buildReminderContext({ sessionId, config, staticEnv, configDirName = '.
 
   // Resolve paths
   const devRulesPath = resolveRulesPath('ai-dev-rules.md', configDirName);
-  const catalogScript = resolveScriptPath('generate_catalogs.py', configDirName);
+  const catalogScript = resolveScriptPath('generate-skill-catalog.cjs', configDirName);
   const skillsVenv = resolveSkillsVenv(configDirName);
 
   // Build plan context

package/src/claude/hooks/rules.cjs

@@ -91,6 +91,13 @@ try {
   lines.push('- Ensure token efficiency while maintaining high quality.');
   lines.push('');
 
+  // Skill routing: advisory rule docs, no automatic prompt router.
+  lines.push('## Skill Routing');
+  lines.push('- Choose skills from intent using `.claude/rules/skill-workflow-routing.md` and `.claude/rules/skill-domain-routing.md`.');
+  lines.push('- If needed, run `node .claude/scripts/generate-skill-catalog.cjs --skills` to inspect installed skills.');
+  lines.push('- Explicit user commands and direct-answer requests override routing suggestions.');
+  lines.push('');
+
   // Modularization
   lines.push('## [IMPORTANT] Consider Modularization:');
   lines.push('- If a file exceeds 200 lines, consider splitting it');

package/src/claude/migration-manifest.json

@@ -58,6 +58,7 @@
     "required": [
       "validate-docs.cjs",
       "validate-docs-reconstruct.cjs",
+      "generate-skill-catalog.cjs",
       "browser-tool.cjs",
       "validate-spec-output.cjs"
     ]
@@ -68,6 +69,15 @@
   "hooks": {
     "assumed": []
   },
+  "obsolete": {
+    "runtimeFiles": [
+      "hooks/skill-router.cjs",
+      "hooks/lib/skill-router-routes.cjs"
+    ],
+    "settingsHookCommandSubstrings": [
+      "hooks/skill-router.cjs"
+    ]
+  },
   "runtime": {
     "files": [
       "gitignore",
@@ -80,7 +90,6 @@
       "hooks/privacy-block.cjs",
       "hooks/inspect-block.cjs",
       "hooks/rules.cjs",
-      "hooks/skill-router.cjs",
       "hooks/spec-state.cjs",
       "hooks/state.cjs",
       "hooks/lib/color.cjs",
@@ -89,8 +98,7 @@
       "hooks/lib/git.cjs",
       "hooks/lib/config.cjs",
       "hooks/lib/context.cjs",
-      "hooks/lib/detect.cjs",
-      "hooks/lib/skill-router-routes.cjs"
+      "hooks/lib/detect.cjs"
     ]
   },
   "settings": {

package/src/claude/rules/skill-domain-routing.md

@@ -0,0 +1,87 @@
+# Skill Domain Routing
+
+Use this decision tree to choose domain skills from the installed CafeKit skill set. This is advisory routing, not an automatic hook.
+
+## Frontend And UI
+
+```text
+User wants to...
+├── choose style, color, layout, UX, design system       -> /hapo:frontend-design
+├── build React/TypeScript UI components                 -> /hapo:frontend-development
+├── optimize React/Next.js performance or rerenders      -> /hapo:react-best-practices
+├── apply deep UI/UX intelligence, visual polish         -> /hapo:ui-ux-pro-max
+└── test UI in browser                                   -> /hapo:web-testing or /hapo:agent-browser
+```
+
+Use `/hapo:react-best-practices` for performance/re-render patterns. Use `/hapo:frontend-development` for normal implementation.
+
+## Backend, Data, And Infrastructure
+
+```text
+User wants to...
+├── API, service, auth, database-backed feature          -> /hapo:backend-development
+├── deployment, Docker, Kubernetes, Cloudflare, CI/CD     -> /hapo:devops
+├── mobile apps, iOS, Android, React Native, Flutter     -> /hapo:mobile-development
+└── impact of changing existing behavior                 -> /hapo:impact-analysis
+```
+
+## Codebase Understanding
+
+```text
+User wants to...
+├── find files, locate code, scan project structure       -> /hapo:inspect
+├── diagnose an error or failing check                    -> /hapo:debug
+├── understand possible side effects                      -> /hapo:impact-analysis
+└── compare external approaches or best practices         -> /hapo:research
+```
+
+Local source truth comes from `/hapo:inspect`; external/current knowledge comes from `/hapo:research`.
+
+## Documentation
+
+```text
+User wants to...
+├── create missing project docs                           -> /hapo:docs --init
+├── update docs after source changes                      -> /hapo:docs --update
+├── summarize codebase quickly                            -> /hapo:docs --summarize
+├── reconstruct as-is docs from legacy source code        -> /hapo:docs --reconstruct <scope>
+└── create a future feature spec                          -> /hapo:specs
+```
+
+Keep as-is reconstruction separate from future requirements. Reconstructed docs document current behavior; specs define requested changes.
+
+## Testing And Browser
+
+```text
+User wants to...
+├── run test suites, coverage, scoped verification        -> /hapo:test
+├── E2E/unit/integration/load/security/a11y strategy      -> /hapo:web-testing
+├── drive a browser with snapshots or Browserbase         -> /hapo:agent-browser
+└── Chrome DevTools/Puppeteer evidence                    -> /hapo:chrome-devtools
+```
+
+## Documents And Media
+
+```text
+User wants to...
+├── PowerPoint/slides                                     -> /hapo:pptx
+├── Word documents                                        -> /hapo:docx
+├── PDFs                                                  -> /hapo:pdf
+├── spreadsheets/CSV/XLSX                                 -> /hapo:xlsx
+└── image/audio/video/document multimodal analysis        -> /hapo:ai-multimodal
+```
+
+## Git And Release
+
+```text
+User wants to...
+├── commit, branch, tag, push, release prep               -> /hapo:git
+└── review before release                                 -> /hapo:code-review
+```
+
+## Usage Notes
+
+- Read the selected skill's `SKILL.md` before acting.
+- Do not activate a skill only because one keyword appears. Use the whole user intent.
+- If a task spans multiple domains, name the primary skill and mention the secondary skill in the plan.
+- If no domain skill fits, use the core CafeKit workflow in `skill-workflow-routing.md`.

package/src/claude/rules/skill-workflow-routing.md

@@ -0,0 +1,84 @@
+# Skill Workflow Routing
+
+Use this rule instead of automatic prompt routing. Read the user's intent, choose the primary CafeKit workflow, then load the relevant `.claude/skills/<skill>/SKILL.md`.
+
+Do not inject or force a skill when the user explicitly asks for a direct answer, a specific command, or a different workflow.
+
+## Core Specification Workflow
+
+```text
+/hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
+```
+
+| User intent | Suggested start |
+|---|---|
+| unclear idea, possible approaches, scope tradeoffs | `/hapo:brainstorm` |
+| create requirements, design, task breakdown, validate spec | `/hapo:specs` |
+| implement an approved spec or a specific task file | `/hapo:develop` |
+| run tests, QA, runtime verification | `/hapo:test` |
+| review code quality, security, regressions, maintainability | `/hapo:code-review` |
+| commit, tag, push, branch, release prep | `/hapo:git` |
+
+## Bug And Incident Workflow
+
+```text
+/hapo:debug -> /hapo:hotfix -> /hapo:test -> /hapo:code-review
+```
+
+| User intent | Suggested start |
+|---|---|
+| diagnose why something fails, find root cause, inspect CI/logs | `/hapo:debug` |
+| fix a known bug after diagnosis, urgent regression, production issue | `/hapo:hotfix` |
+| verify the fix and affected behavior | `/hapo:test` |
+| check side effects before closeout | `/hapo:code-review` |
+
+`/hapo:debug` is diagnostic-only. Do not edit product code there. Use `/hapo:hotfix` when the user asks to fix.
+
+## Existing System Documentation Workflow
+
+```text
+/hapo:inspect -> /hapo:docs --reconstruct -> human review -> /hapo:specs -> /hapo:develop
+```
+
+| User intent | Suggested start |
+|---|---|
+| understand source structure or locate implementation areas | `/hapo:inspect` |
+| rebuild as-is docs/requirements from a legacy codebase | `/hapo:docs --reconstruct <scope>` |
+| update normal project docs | `/hapo:docs --update` |
+| initialize missing docs | `/hapo:docs --init` |
+| summarize a codebase without full docs work | `/hapo:docs --summarize` |
+
+Do not turn reconstructed docs directly into implementation. Human review must approve the as-is docs before `/hapo:specs` defines future changes.
+
+## Research And Analysis Workflow
+
+```text
+/hapo:inspect -> /hapo:impact-analysis -> /hapo:research
+```
+
+| User intent | Suggested start |
+|---|---|
+| file discovery, codebase structure, source scouting | `/hapo:inspect` |
+| affected files, blast radius, dependency impact, side effects | `/hapo:impact-analysis` |
+| external best practices, tool comparison, technical investigation | `/hapo:research` |
+
+Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local source truth.
+
+## Output Artifact Workflow
+
+| User intent | Suggested skill |
+|---|---|
+| diagrams, architecture maps, Mermaid/SVG/PNG graph output | `/hapo:generate-graph` |
+| PowerPoint or slide deck creation/editing | `/hapo:pptx` |
+| Word documents | `/hapo:docx` |
+| PDF processing | `/hapo:pdf` |
+| spreadsheets | `/hapo:xlsx` |
+| screenshots, images, audio, video, OCR, multimodal understanding | `/hapo:ai-multimodal` |
+
+## Selection Rules
+
+- Pick one primary workflow first.
+- Add a secondary skill only when it materially changes execution.
+- Prefer explicit user commands over this table.
+- If two workflows conflict, ask one concise clarification.
+- If the user asks to "fix" and root cause is unknown, start with `/hapo:debug` unless the issue is trivial and local.

package/src/claude/scripts/generate-skill-catalog.cjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * CafeKit skill catalog scanner.
+ *
+ * This mirrors the Research/.claude approach: expose the installed skill set as
+ * a readable catalog so the model can choose skills from rules, not from an
+ * automatic prompt-scoring hook.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function usage() {
+  console.log(`Usage:
+  node .claude/scripts/generate-skill-catalog.cjs [--skills] [--json] [--root <skills-dir>]
+
+Examples:
+  node .claude/scripts/generate-skill-catalog.cjs --skills
+  node .claude/scripts/generate-skill-catalog.cjs --json --root .claude/skills`);
+}
+
+function parseArgs(argv) {
+  const args = { json: false, help: false, root: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--json') args.json = true;
+    else if (arg === '--skills') continue;
+    else if (arg === '--root') {
+      args.root = argv[i + 1] || null;
+      i += 1;
+    } else {
+      args.root = args.root || arg;
+    }
+  }
+  return args;
+}
+
+function defaultSkillsRoot() {
+  const installed = path.resolve(process.cwd(), '.claude', 'skills');
+  if (fs.existsSync(installed)) return installed;
+  return path.resolve(__dirname, '..', 'skills');
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+  if (!match) return {};
+  const frontmatter = {};
+  const lines = match[1].split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    let value = kv[2].trim();
+    if (value === '>' || value === '>-' || value === '|' || value === '|-') {
+      const block = [];
+      i += 1;
+      while (i < lines.length && /^\s+/.test(lines[i])) {
+        block.push(lines[i].trim());
+        i += 1;
+      }
+      i -= 1;
+      value = block.join(' ');
+    }
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    frontmatter[key] = value;
+  }
+  return frontmatter;
+}
+
+function firstParagraph(content) {
+  const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, '');
+  const paragraph = [];
+  for (const rawLine of body.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      if (paragraph.length > 0) break;
+      continue;
+    }
+    paragraph.push(line);
+    if (paragraph.join(' ').length > 160) break;
+  }
+  return paragraph.join(' ').slice(0, 360);
+}
+
+function categorize(name, description) {
+  const text = `${name} ${description}`.toLowerCase();
+  if (/spec|brainstorm|develop|sync/.test(text)) return 'workflow';
+  if (/debug|hotfix|inspect|impact|review|test|agent-browser|chrome/.test(text)) return 'quality';
+  if (/frontend|react|ui|ux|mobile/.test(text)) return 'frontend-mobile';
+  if (/pdf|docx|pptx|xlsx|multimodal/.test(text)) return 'artifacts-tools';
+  if (/backend|devops|api|database|deploy/.test(text)) return 'backend-infra';
+  if (/docs|research|graph/.test(text)) return 'knowledge';
+  if (/git/.test(text)) return 'git';
+  return 'other';
+}
+
+function scanSkills(root) {
+  if (!fs.existsSync(root)) {
+    throw new Error(`skills root not found: ${root}`);
+  }
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const skillPath = path.join(root, entry.name, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) continue;
+    const content = readText(skillPath);
+    const frontmatter = extractFrontmatter(content);
+    const name = frontmatter.name || entry.name;
+    const description = frontmatter.description || firstParagraph(content);
+    skills.push({
+      name,
+      directory: entry.name,
+      description,
+      category: categorize(name, description),
+      has_references: fs.existsSync(path.join(root, entry.name, 'references')),
+      has_scripts: fs.existsSync(path.join(root, entry.name, 'scripts')),
+    });
+  }
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function renderMarkdown(skills, root) {
+  const lines = [
+    '# CafeKit Skills Catalog',
+    '',
+    `Skills root: \`${root}\``,
+    `Total skills: ${skills.length}`,
+    '',
+  ];
+  const categories = [...new Set(skills.map((skill) => skill.category))].sort();
+  for (const category of categories) {
+    lines.push(`## ${category}`, '');
+    for (const skill of skills.filter((item) => item.category === category)) {
+      const badges = [
+        skill.has_references ? 'refs' : null,
+        skill.has_scripts ? 'scripts' : null,
+      ].filter(Boolean);
+      lines.push(
+        `- \`${skill.name}\` (${skill.directory})${badges.length ? ` [${badges.join(', ')}]` : ''}: ${skill.description}`
+      );
+    }
+    lines.push('');
+  }
+  return lines.join('\n').trim() + '\n';
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    usage();
+    return;
+  }
+
+  const root = path.resolve(process.cwd(), args.root || defaultSkillsRoot());
+  const skills = scanSkills(root);
+  if (args.json) {
+    console.log(JSON.stringify({ root, total: skills.length, skills }, null, 2));
+    return;
+  }
+  console.log(renderMarkdown(skills, root));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`[skill-catalog] ${error.message}`);
+  process.exit(1);
+}

package/src/claude/settings/settings.json

@@ -42,10 +42,6 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/rules.cjs\""
           },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.cjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-state.cjs\""

package/src/opencode/AGENTS.md

@@ -0,0 +1,140 @@
+# AGENTS.md
+
+Primary operating instructions for OpenCode using the CafeKit runtime.
+
+## OpenCode Runtime Mapping
+
+- Project instructions live in `AGENTS.md`.
+- CafeKit commands live in `.opencode/commands/` and use OpenCode-native slash names without the `hapo:` prefix.
+- CafeKit subagents live in `.opencode/agents/` using OpenCode frontmatter.
+- CafeKit skills intentionally live in `.claude/skills/` because OpenCode reads Claude-compatible skills natively.
+- Shared CafeKit support files live in `.claude/rules/`, `.claude/scripts/`, `.claude/references/`, and `.claude/runtime.json`.
+- OpenCode config is merged into `opencode.json`; keep project-specific model/provider choices there.
+
+## Command Surface
+
+Use these OpenCode commands:
+
+- `/brainstorm <idea-or-problem>`: scout and narrow an unclear idea before specs.
+- `/specs <feature-or-spec-command>`: create, update, validate, or approve specs.
+- `/develop <feature> [task-file] [--flash]`: implement approved spec tasks.
+- `/test [scope|--full]`: verify implementation and collect evidence.
+- `/code-review [scope|--pending]`: review for correctness, regressions, and scope drift.
+- `/debug <issue>`: diagnose root cause without product-code edits.
+- `/hotfix <issue>`: apply a narrow, scout-first production fix.
+- `/docs [--init|--update|--summarize|--reconstruct]`: maintain or reconstruct project docs.
+- `/inspect <target>`: inspect source, artifacts, or external context.
+- `/generate-graph <request>`: generate technical diagrams.
+
+The underlying CafeKit skills are still named `hapo:*` in their documentation. In OpenCode, use the commands above; each command reads the matching skill from `.claude/skills/<skill>/SKILL.md`.
+
+## Core Objective
+
+Act as the project orchestrator: understand the request, keep scope tight, use the right CafeKit skill/agent, and deliver verified work that follows the project's architecture.
+
+## Core Behavior
+
+These rules reduce common agent coding failures: hidden assumptions, overbuilt solutions, unrelated edits, and unverified completion claims. They take priority over speed-oriented shortcuts.
+
+### 1. Think Before Coding
+
+- Do not assume silently. State assumptions when they affect the work.
+- If multiple interpretations are plausible, surface them before implementation.
+- If the simpler option is likely better, say so and push back.
+- If the task/spec is too vague to verify, stop and ask or route back to spec correction.
+- Before feature planning or coding, read `./README.md` for project context.
+
+### 2. Simplicity First
+
+- Solve the requested problem with the smallest maintainable change.
+- Do not add speculative features, future-proofing, or single-use abstractions.
+- Reuse existing modules before creating new ones.
+- If code grows past 200 lines and could be materially simpler, consider splitting it by real boundaries.
+- Prefer YAGNI, KISS, and DRY in that order.
+
+### 3. Surgical Changes
+
+- Touch only files required by the task.
+- Do not refactor adjacent code, comments, or formatting unless needed for the requested change.
+- Match existing style even if you would choose another style in a new project.
+- Remove only dead code/imports created by your own change.
+- Mention unrelated issues instead of fixing them opportunistically.
+
+### 4. Goal-Driven Execution
+
+- Convert requests into verifiable success criteria.
+- For spec tasks, use `Completion Criteria` and `Evidence` as the source of truth. Existing task files may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`.
+- For bugs, reproduce with a failing test or concrete evidence when feasible before fixing.
+- Loop until verification passes or a real blocker is recorded.
+
+## CafeKit Operating Loop
+
+Use this loop for non-trivial work:
+
+1. Understand: read README, relevant docs, active spec/task, and existing code.
+2. Plan: choose the smallest coherent path; use `/specs` for feature specs when needed.
+3. Execute: implement only the active task/scope; no placeholder completion.
+4. Verify: run exact task commands first, then repo-level lint/test/build as needed.
+5. Sync: mark task state only after proof exists.
+
+## OpenCode Runtime Limits And Replacements
+
+- Claude Code hooks/statusline/settings do not run in OpenCode.
+- Treat `.claude/rules/*` as explicit reference material, not injected hook context.
+- When a skill says to use unavailable Claude-specific tools such as `Task`, `TodoWrite`, or `AskUserQuestion`, use OpenCode's agent/subtask flow, a concise markdown checklist, or ask the user directly.
+- Privacy and inspect gates are instruction-level gates in OpenCode unless a project-specific OpenCode plugin adds hard enforcement.
+
+## Operating Discipline
+
+- If a CafeKit skill may apply, read and use that skill before acting.
+- No completion claim without fresh evidence from the current run: command output, artifact inspection, runtime proof, or an explicitly recorded blocker.
+- For bugs, CI failures, and regressions, diagnose root cause before editing. Symptom patches are not completion.
+- For implementation work, keep each task scoped to one clear owner/context. Reviewers should receive task files, diffs, and acceptance criteria, not chat history.
+- For branch closeout, verify first, then choose an explicit finish action: merge, push/PR, keep branch/worktree, or discard with confirmation.
+
+## Definition Of Done
+
+A task is done only when all apply:
+
+- implementation satisfies `Completion Criteria`
+- `Evidence` is satisfied with concrete proof
+- preflight/build/test outcomes are passing or an explicit blocker is recorded
+- code review has no critical issues
+- a verification receipt exists before task state is synced to `done`
+
+`NO_TESTS` and `0 tests + exit 0` are not passing outcomes when the task requires automated tests.
+
+## Rule References
+
+Consult these when the task touches the relevant area:
+
+- Primary workflow: `./.claude/rules/workflow.md`
+- Development rules: `./.claude/rules/ai-dev-rules.md`
+- Subagent coordination: `./.claude/rules/orchestrator.md`
+- Docs maintenance: `./.claude/rules/manage-docs.md`
+- State sync: `./.claude/rules/state-sync.md`
+- Hook handling reference: `./.claude/rules/hook-protocols.md`
+- Other protocols: `./.claude/rules/*`
+
+## Skill And Script Use
+
+- Evaluate the installed skill catalog before work and activate the relevant skill(s).
+- If there is a reasonable chance a skill applies, prefer the skill workflow over ad hoc execution.
+- If modifying skills, edit the current project/runtime files, not `~/.claude/skills` directly.
+- Run Python skill scripts with the skill venv:
+  - macOS/Linux: `.claude/skills/.venv/bin/python3 scripts/<script>.py`
+  - Windows: `.claude\skills\.venv\Scripts\python.exe scripts\<script>.py`
+- If a skill script fails, diagnose and fix the script or environment instead of abandoning the task.
+
+## Git And Reporting
+
+- Use conventional commits.
+- Do not add AI attribution by default.
+- Lint before commit and run the full required verification before push.
+- Keep commits focused on actual changes.
+- Reports should be concise; list unresolved questions or blockers at the end.
+
+## Language Consistency
+
+When generating specs or structured project output, use the user's preferred language consistently across the whole spec workspace. Technical terms, code samples, and file paths may remain English.
+