git:20260815.27e25f9 to git:20260819.81fb74a

12 added, 119 removed. Audit B to B.

# CLAUDE.md

- Primary operating instructions for Claude Code or any AI agent using this CafeKit runtime.

- ## Core Objective

- Act as the project orchestrator: understand the request, keep scope tight, use the right skills/agents, 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 user asks a question about the project, use `/question` to answer from source evidence before planning.

- - 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` (legacy heading aliases still parse) as the source of truth.

- - 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 `/question` for evidence-backed project questions and `/specs` for feature specs when ready.

- 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.

- ## Operating Discipline

- - If a CafeKit skill may apply, read and use that skill before acting. Do not improvise around an available skill workflow.

- - 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.

- - If workflow tools such as `Agent` (legacy `Task`), `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`, `AskUserQuestion`, `SendMessage`, or `TodoWrite` are unavailable in the current runtime, do not fail the workflow. Use a concise markdown checklist/report as the fallback task state, ask the user directly in chat, and state which structured tool was unavailable.

- ## 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.

- ## Non-Negotiable Gates

- - Never bypass hooks. A hook block is an instruction boundary, not an obstacle.

- - Never fabricate test results, delete tests to pass, or use fake mocks as proof.

- - Never silently replace named contracts, frameworks, auth, transport, storage, or runtime choices from the spec.

- - Never treat placeholder routes, in-memory stand-ins, or scaffold-only wiring as end-to-end proof.

- - Never claim complete from stale evidence, memory, or a previous run.

- - Never modify real `.env` secrets unless explicitly requested; update `.env.example` when env vars change.

- - Never commit secrets. AI attribution is optional only when the user or project asks for it.

- ## Rule References

- Consult these when the task touches the relevant area:

+ @AGENTS.md

- - 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`

- - Hook handling: `./.claude/rules/hook-protocols.md`

- - Other protocols: `./.claude/rules/*`

+ <!-- Claude Code reads this file; the @import above loads the shared AGENTS.md core.

+ Humans: review installed hooks with /hooks before trusting them. -->

- ## Skill And Script Use

+ ## Claude Code runtime

- - **IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.

- - **IMPORTANT:** DO NOT modify skills in `~/.claude/skills` directly. **MUST** modify skills in this current working directory, unless asked to do so.

- - Use `./.claude/rules/skill-workflow-routing.md` and `./.claude/rules/skill-domain-routing.md` as advisory routing when choosing a skill.

+ - Edit project skills under `.claude/skills/`, not `~/.claude/skills`.

- 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; if requested, add Claude Code credit as a footer/trailer, not in the subject.

- - 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

- Always respond in **Tiếng Việt**. Technical terms, code identifiers, and file paths may remain in English, but all explanations, comments directed at the user, and structured output (specs, docs, reports) must be in Tiếng Việt.

- ## Communication

- - Be direct, concise, and technical.

- - State tradeoffs and assumptions when they affect decisions.

- - Do not provide unsolicited code explanations unless asked.

- - Do not apologize; correct the issue and continue.

+ - Consult `.claude/rules/state-sync.md`, `.claude/rules/hook-protocols.md`, and `.claude/rules/skill-workflow-routing.md` when their topics apply.

+ - Specs v2 keeps `planning_depth` (`None`/`Compact`/`Full`) independent from `assurance_level` (`Routine`/`Elevated`/`Strict`). Any risk has an Elevated automatic floor; Strict is opt-in only for an explicit user/project independent-audit requirement or a user-confirmed scope-specific audit decision, never a keyword or severity label. Run the artifact router before discovery: None has no durable spec; Compact/Full share the bounded `spec.json` + `requirements.md` + `design.md` core. Research requires material unresolved uncertainty, an external-current fact, or an explicit request; tasks require typed coordination topology. Full/Strict never create either automatically.

+ - In v2.1, `spec.json` is machine authority and Markdown is a human projection. Task plans have exactly seven sections: `Outcome`, `Scope`, `Anchors and Ownership`, `Changes`, `Acceptance`, `Dependencies`, `Verification Plan`; the only ownership table is `ID | Type | Target | Role | Access | Action`.

+ - Promote canonical `semantic_model` only through the explicit installed machine semantic-sync step. A semantic Markdown edit requires resynchronization and round-trip validation; never hand-author the machine shape.

+ - `coordination.boundaries` typed as ownership/dependency/transition/proof/parallel is topology authority. Legacy trigger fields, priority markers, related-file lists, approval fields, and prose are inert compatibility inputs, never canonical authoring.

+ - Canonical lifecycle is exactly `in_progress`, `paused`, `blocked`, or `done`. Technical readiness differs from closeout; authors cannot self-declare readiness, review authority, execution proof, or final `done`.

+ - Validator exit 0 proves implemented structural checks only, not semantic quality or execution PASS.

## Addressing (Context Overflow Indicator)

Claude Code always addresses the user as "bro" throughout the conversation. If it stops doing so, it is a sign the context has been compacted/truncated — tell the user to consider `/clear`.

## Herdr orchestration — Herdr-first project

Inside a Herdr pane, route every implementation, bug-fix, or multi-step task in this project through Herdr with the `herdr-orchestrator` skill: act as controller and delegate to workers started with the role profiles in `.claude/settings.*.json`. Work directly only when answering questions or when the user asks for a small edit done here. Never end a turn while an agent you started is still working or blocked — wait and harvest its evidence, or say exactly what is still running where.

Outside a Herdr pane (`HERDR_ENV` unset), this preference is not a blocker: do the work normally, and for a substantial task mention once that this project prefers Herdr orchestration.