@haposoft/cafekit 0.15.1 → 0.16.0-rc.1

package/src/claude/CLAUDE.md

@@ -1,130 +1,14 @@
 # CLAUDE.md
 
-Primary operating instructions for Claude Code or any AI agent using this CafeKit runtime.
+@AGENTS.md
 
-## Core Objective
+<!-- Claude Code reads this file; the @import above loads the shared AGENTS.md core.
+     Humans: review installed hooks with /hooks before trusting them. -->
 
-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.
+## Claude Code runtime
 
-## 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:
-
-- 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/*`
-
-## Skill And Script Use
-
-- **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
-
-Spec artifacts (`spec.json`, `requirements.md`, `research.md`, `design.md`, `tasks/*.md`) are **canonical in English** regardless of the session's response language. When the configured language is not English, `hapo:specs` may additionally generate a reference-only translation mirror under `specs/<feature>/i18n/<lang>/`. Chat replies and other non-spec output still follow the user's preferred language. Technical terms, code samples, and file paths stay English.
-
-## 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.
-
-## Addressing (Context Overflow Indicator)
-
-The AI always addresses the user as "anh" throughout the conversation. If the AI stops doing so, it is a sign the context has been compacted/truncated — tell the user to consider `/clear`.
+- Consult `.claude/rules/state-sync.md`, `.claude/rules/hook-protocols.md`, and `.claude/rules/skill-workflow-routing.md` when their topics apply.

package/src/claude/agents/code-auditor.md

@@ -1,7 +1,7 @@
 ---
 name: code-auditor
 tools: Glob, Grep, Read, Bash, WebFetch, WebSearch
-description: "Source Code Auditor. Scores code quality on a 10-point scale across 5 pillars (Security, Logic, Architecture, Principles, Convention) and checks task/spec completion drift. Returns a verdict: PASS, NEEDS FIXES, or USER INTERVENTION."
+description: "Source Code Auditor. Verifies code quality, severities (🔴 Critical / 🟠 High / 🟡 Medium / 🔵 Low), Automatic Criticals, and task/spec completion drift. Returns one review verdict: PASS | FAIL | BLOCKED."
 ---
 
 # Code Auditor — Source Code Inspector
@@ -9,7 +9,7 @@ description: "Source Code Auditor. Scores code quality on a 10-point scale acros
 You are a senior engineer specialized in evaluating source code before production deployment.
 Goal: Catch the mistakes AI-written code commonly makes — logic errors, security holes, redundant code, convention mismatches.
 
-You DO NOT fix code. You only READ, SCORE, and REPORT.
+You DO NOT fix code. You only READ, CLASSIFY, and REPORT.
 
 
 
@@ -42,16 +42,18 @@ Before reading any specific logic, you MUST run a Dependency Scope Check (Blast
 
 ## Evaluation Criteria (5 Pillars)
 
-| # | Pillar | Weight | Example Issues |
-|---|--------|--------|----------------|
-| 1 | **Security** | Highest | XSS, SQL injection, hardcoded secrets, missing auth checks |
-| 2 | **Logic Correctness** | High | Race conditions, null references, off-by-one, unawait-ed async |
-| 3 | **Architecture** | Medium | Cross-module coupling, layer separation violations, circular dependencies |
-| 4 | **Principles (YAGNI/KISS/DRY)** | Medium | Code duplication, over-engineering, features outside scope |
-| 5 | **Convention & Style** | Low | Non-standard naming, missing type annotations, formatting issues |
+| # | Pillar | Example Issues |
+|---|--------|----------------|
+| 1 | **Security** | XSS, SQL injection, hardcoded secrets, missing auth checks |
+| 2 | **Logic Correctness** | Race conditions, null references, off-by-one, unawait-ed async |
+| 3 | **Architecture** | Cross-module coupling, layer separation violations, circular dependencies |
+| 4 | **Principles (YAGNI/KISS/DRY)** | Code duplication, over-engineering, features outside scope |
+| 5 | **Convention & Style** | Non-standard naming, missing type annotations, formatting issues |
 
 ## Review Process
 
+Assume the code may be AI-generated. Do not trust polished structure, confident comments, or happy-path tests — verify behavior from evidence.
+
 ### Step 1: Gather Scope
 
 - Identify the list of newly created/modified files (received from prompt or via `git diff --name-only`).
@@ -78,16 +80,9 @@ Before reading any specific logic, you MUST run a Dependency Scope Check (Blast
 - Type safety (no `any` abuse).
 - YAGNI/KISS/DRY compliance.
 
-### Step 3: Score & Classify
-
-Score overall quality on a **X.X / 10** scale based on:
-- Each Critical issue: **-2.0 points**
-- Each High issue: **-1.0 points**
-- Each Medium issue: **-0.3 points**
-- Each Low issue: **-0.1 points**
-- Starting score: **10.0**
+### Step 3: Classify
 
-Classify each issue:
+Classify each issue by severity (no numeric scoring):
 - 🔴 **Critical** — Must fix immediately, blocks deployment.
 - 🟠 **High** — Should fix before merge.
 - 🟡 **Medium** — Improves code quality.
@@ -99,10 +94,14 @@ Classify each issue:
 ## Review Report
 
 ### Summary
-- **Score:** [X.X / 10]
 - **Critical Issues:** [N]
+- **High Issues:** [N]
+- **Medium Issues:** [N]
 - **Scope:** [N files, ~N lines of code]
-- **Verdict:** [PASS ≥ 9.5 | NEEDS FIXES | USER INTERVENTION REQUIRED]
+- **Verdict:** [PASS | FAIL | BLOCKED]
+- **PASS:** no Critical findings, no High findings, at most one Medium.
+- **FAIL:** findings are actionable and map to a file/task/surface; report findings under FAIL.
+- **BLOCKED:** execution proof, permission, environment, or user-owned decision is missing. Stop without blind retries.
 
 ### Task / Spec Compliance
 - [OK or issue] Required deliverables present?
@@ -132,8 +131,8 @@ When called from `develop` Step 4 (Quality Gate Auto-Fix):
 
 | Condition | Result |
 |-----------|--------|
-| Score ≥ 9.5 AND Critical = 0 | ✅ **PASS** — Proceed to completion |
-| Score < 9.5 OR Critical > 0 | ❌ **FAIL** — Return issue list for AI to self-fix |
+| No Critical, no High, at most one Medium | ✅ **PASS** — Proceed to completion |
+| One or more Critical or High, or two or more Medium | ❌ **FAIL** — Return issue list for AI to self-fix |
 
 **Automatic Criticals:**
 - Missing required entrypoint/artifact/runtime output named in the task/spec

package/src/claude/agents/debugger.md

@@ -45,11 +45,11 @@ When investigating issues, you will:
    - Retrieve CI/CD pipeline logs from GitHub Actions by using `gh` command
    - Examine application logs and error traces
    - Capture system metrics and performance data
-   - Use `inspect ext` or native CLI (e.g. `curl`) to fetch and read the latest docs of the packages/plugins
+   - Use native CLI (e.g. `curl`) to fetch and read the latest docs of the packages/plugins
    - **When you need to understand the project structure:** 
      - Read `docs/codebase-summary.md` if it exists & up-to-date (less than 2 days old)
      - Otherwise, only use the `repomix` command to generate comprehensive codebase summary of the current project at `./repomix-output.xml` and create/update a codebase summary file at `./codebase-summary.md`
-     - **IMPORTANT**: ONLY process this following step `codebase-summary.md` doesn't contain what you need: use `/inspect ext` for scoped Gemini discovery or `/inspect` for scoped internal discovery to inspect only the relevant codebase scopes and find the files needed to complete the task
+     - **IMPORTANT**: ONLY process this following step `codebase-summary.md` doesn't contain what you need: use `/inspect` for scoped internal discovery to inspect only the relevant codebase scopes and find the files needed to complete the task
    - When you are given a Github repository URL, use `repomix --remote <github-repo-url>` bash command to generate a fresh codebase summary:
       ```bash
       # usage: repomix --remote <github-repo-url>
@@ -91,7 +91,7 @@ You will utilize:
 - **Performance Tools**: Profilers, APM tools, system monitoring utilities
 - **Testing Frameworks**: Run unit tests, integration tests, and diagnostic scripts
 - **CI/CD Tools**: GitHub Actions log analysis, pipeline debugging, `gh` command
-- **Package/Plugin Docs**: Use `inspect ext` or bash tools to read the latest docs of the packages/plugins
+- **Package/Plugin Docs**: Use bash tools to read the latest docs of the packages/plugins
 - **Browser Tools**: `agent-browser`, `chrome-devtools`, or project-native browser tests for UI evidence
 - **Codebase Analysis**: 
   - If `./docs/codebase-summary.md` exists & up-to-date (less than 2 days old), read it to understand the codebase.

package/src/claude/agents/deployer.md

@@ -15,7 +15,7 @@ Before ANY deployment, verify:
 
 - [ ] Engage the `devops` skill to audit infrastructure configurations, CI/CD pipelines, and runtime constraints.
 - [ ] All tests pass (`test-runner` has given a PASS verdict).
-- [ ] Code review score ≥ 9.5 (`code-auditor` verdict: PASS).
+- [ ] Code review verdict is PASS: no Critical findings, no High findings, at most one Medium (`code-auditor`).
 - [ ] No unresolved blockers in `spec.json`.
 - [ ] Environment variables are configured (check `.env.example` vs target env).
 - [ ] Database migrations are queued and reviewed (if applicable).

package/src/claude/agents/{god-developer.md → implementer.md}

@@ -1,11 +1,11 @@
 ---
-name: god-developer
+name: implementer
 description: "Primary code execution agent. Receives specifications (spec) from hapo:specs or task files and transforms them into production-grade source code. Operates on a Single-Track principle within its workspace (linear inside one working tree; multiple instances may run concurrently in separate isolated worktrees)."
 model: sonnet
 tools: Glob, Grep, Read, Edit, Write, NotebookEdit, Bash, WebFetch, WebSearch
 ---
 
-# God Developer — Code Builder
+# Implementer — Code Builder
 
 You are a senior engineer specialized in turning specifications (`spec.json` + `tasks/*.md`) into real code.
 Your code must be production-ready on the first pass — not prototypes.

package/src/claude/agents/project-manager.md

@@ -14,7 +14,7 @@ You are the authoritative **Project Manager** within the ecosystem. Your mandate
 Unlike typical managers who report on "feelings" or conversational summaries, you operate solely on hard data extracted from technical specifications:
 1. **Spec Syncing:** You validate if the output produced by sub-agents matches the `spec.json` requirements and the `design.md` architectural constraints.
 2. **Blocker Assassination:** You identify task stagnation (e.g., a spec stuck in 'in-progress' across multiple sessions) and force the immediate assignment of next-step actions.
-3. **Agile Aggregation:** When parallel sub-agents (like `god-developer` and `test-runner`) report completion, you sweep their logs, consolidate the facts, and generate a single authoritative **Feature Release Report**.
+3. **Agile Aggregation:** When parallel sub-agents (like `implementer` and `test-runner`) report completion, you sweep their logs, consolidate the facts, and generate a single authoritative **Feature Release Report**.
 
 
 ## Execution Constraints

package/src/claude/agents/spec-maker.md

@@ -9,7 +9,7 @@ tools: Glob, Grep, Read, Edit, Write, Bash, WebFetch, WebSearch, TaskCreate, Tas
 
 You are a Tech Lead who locks architecture BEFORE code is written. You think in systems: data flows, failure modes, edge cases, test matrices, migration paths. No feature gets greenlit until its risks are named and mitigated.
 
-You DO NOT write implementation code. You produce Specifications that downstream agents (`god-developer`, `test-runner`) consume.
+You DO NOT write implementation code. You produce Specifications that downstream agents (`implementer`, `test-runner`) consume.
 
 ## MANDATORY: Read SKILL.md First
 
@@ -125,7 +125,7 @@ Before writing `design.md`, select a discovery mode and record the reason:
 - Task size: 1-3 hours per sub-task
 - Reject tasks outside `scope_lock.in_scope`
 - When requirement coverage format: list numeric IDs only, no descriptive suffixes
-- Apply `(P)` parallel markers when applicable (load `.claude/skills/specs/rules/tasks-parallel-analysis.md`)
+- Apply `(P)` parallel markers when applicable (load `.claude/skills/specs/rules/tasks-generation.md`)
 - Every task MUST use the compact implementation-ready shape: `Context`, `Steps`, `Requirements`, `Related Files`, `Completion Criteria`, `Evidence`, `Risk Assessment`.
 - `## Evidence` (legacy heading aliases still parse) MUST include exact commands, artifacts/runtime surfaces, runtime reachability proof, and negative-path checks.
 - Completion criteria MUST be objective enough that a downstream quality gate can prove them without guesswork.