-
Notifications
You must be signed in to change notification settings - Fork 0
consolidate: add project-agnostic multi-agent kit (.claude/EN/) #151
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,121 @@ | ||
| # Agent Pattern Cheat-Sheet (project-agnostic, English canonical) | ||
|
|
||
| Lookup-style add-on to your repo's `.claude/CLAUDE.md`. Read this before | ||
| prompting any multi-agent work. Companion knowledge files under | ||
| `.claude/EN/knowledge/` and `.claude/EN/agents/`. | ||
|
|
||
| > Source: distilled from `AdaWorldAPI/WoA` `.claude/CLAUDE.md` §3.5 + §3.6 | ||
| > as of 2026-05-17. Reference implementations: `WoA` (Python), `woa-rs` | ||
| > (Rust), `lance-graph` (Rust, most mature), `ndarray` (Rust, compact). | ||
|
|
||
| --- | ||
|
|
||
| ## 1. Compressed baseline | ||
|
|
||
| ``` | ||
| 12 workers + 1 coordinator · autoattended · full authorization · auto-resolve · log all issues | ||
| plan/preflight → review → correct → sprint → review code → fix P0 → commit → repeat | ||
| ``` | ||
|
|
||
| ## 2. Agent ensemble — Function · Activation · Card | ||
|
|
||
| | Function | Activation | Card | | ||
| |---|---|---| | ||
| | Worker-Impl | Sprint Phase 3 spawn out of `SPRINT-N-PLAN.md`-bundle row | `.claude/EN/agents/worker-template.md` | | ||
| | Meta-Agent (13th) | Phase 2 plan review + Phase 4 code review + continuous inbox-drain | `.claude/EN/agents/meta-agent.md` | | ||
| | PP-13 brutally-honest-tester | "about to commit" / "PR diff touches code" | `.claude/EN/agents/brutally-honest-tester.md` | | ||
| | PP-14 convergence-architect | PRE-PLAN divergent ideation (optional, see knowledge/autoattended-multi-agent-pattern.md §3) | — | | ||
| | PP-15 baton-handoff-auditor | "cross-crate types" / "DTO match" / "lib.rs / mod.rs touch" / "sprint handover" / "ID collision" | `.claude/EN/agents/baton-handoff-auditor.md` | | ||
| | PP-16 preflight-drift-auditor | "before sprint spawn" / "preflight check" / "verify spec against main" | `.claude/EN/agents/preflight-drift-auditor.md` | | ||
|
|
||
| Full specs in `.claude/EN/agents/<role>.md`. Pattern theory in | ||
| `.claude/EN/knowledge/autoattended-multi-agent-pattern.md`. Coordination | ||
| primitives in `.claude/EN/knowledge/a2a-workarounds.md`. | ||
|
|
||
| --- | ||
|
|
||
| ## 3. Reading-Depth-Ladder | ||
|
|
||
| Anti-skim discipline as a lookup. **Default bias: read too deep rather | ||
| than too shallow.** If in doubt, upgrade the depth; never downgrade. | ||
|
|
||
| | Depth | When appropriate | Guardrail / Proof-of-Depth | | ||
| |---|---|---| | ||
| | `grep` (anti) | **NEVER** as primary read. Only as a symbol locator AFTER or PARALLEL to a real read. | If you grepped: declare `depth=grep`, **never** `depth=full`. Grep is not a substitute for reading. | | ||
| | `sed -n` / `awk '/re/'` / `head` / `tail`-only (anti) | **NEVER** as primary read. Partial-range tools deliver lines without section context — hallucination trap. | If you used `sed -n '10,20p'`: declare `depth=sed-partial`, NOT `depth=full`. Use `Read(offset, limit)` with a clear anchor or read the whole file. Never claim a 5-line snippet means "file X read". | | ||
| | `skim` | Huge file, you need ONE section located | Find anchor → read that section in full. Never claim you know the whole file. Output: only claims about the read section. | | ||
| | `read` | File < ~500 lines, standard read | Top to bottom, no skips. For larger files: offset/limit chunks but actually read every chunk. | | ||
| | `thorough read` (twice-full) | Iron Rules, INVARIANTS, RFCs, schema migrations, patches before live-apply | Read twice: once for comprehension, once for verification. Self-check: can I name 3 sections? | | ||
| | `troubleshooting` | Known bug + error message | Error → grep symbol → READ function in full → READ caller(s). No spot-fix without call-site context. | | ||
| | `fan-out research` | Cross-file pattern, refactor planning, audit across >5 files | Spawn an Explore subagent OR write a suspect list, then read each file fully. Inventory file as output. Never trust in-context inference alone. | | ||
|
|
||
| ### When → minimum depth | ||
|
|
||
| | If you are about to… | …then at minimum | | ||
| |---|---| | ||
| | Read memory files (CONTEXT / JOURNAL / TODO) at session start | `thorough read` | | ||
| | Read `.claude/CLAUDE.md` / `BOOT.md` / RFCs / INVARIANTS | `thorough read` | | ||
| | Touch a schema / migration file | `thorough read` + check downstream drift detectors | | ||
| | Open an unknown file for the first time | at least `read`, preferably `thorough` | | ||
| | Pure symbol lookup ("where is `foo` defined?") | `grep` OK but then read the definition in full | | ||
| | Triage a bug report | `troubleshooting` (error → grep → read function + caller) | | ||
| | Plan a refactor / wave / audit | `fan-out research` (inventory file mandatory) | | ||
| | You are unsure which depth | upgrade one rung | | ||
|
|
||
| --- | ||
|
|
||
| ## 4. Lie-Detector — shallowness + drift detection | ||
|
|
||
| > **P0 rule:** No claims without thorough comprehension of the subject | ||
| > AND all adjacent context. | ||
| > | ||
| > **Cognitive frame (Kahneman/Tversky + Dunning-Kruger):** the problem is | ||
| > NOT vagueness ("about 60 lessons") — that is **honest uncertainty** | ||
| > (System 2 reporting in). The problem is **overconfidence**: a specific | ||
| > claim without the read that would support it. System-1 "easy-path" | ||
| > heuristic yields a plausible-sounding answer BEFORE System 2 verifies. | ||
| > | ||
| > **Trigger heuristic:** vague answer ("not sure") = honest → no trigger. | ||
| > Confident false answer = lie-detector fires. Confident correct answer | ||
| > without proof-of-read = also fires (luck vs. hallucination is | ||
| > distinguishable only via LD-1..5). | ||
|
|
||
| Five concrete tests, cheap to expensive: | ||
|
|
||
| | # | Test | How | Honest agent | Shallow agent | | ||
| |---|---|---|---|---| | ||
| | LD-1 | **Sentinel-Token** | Brief ends with: "If you have read this fully, begin your first reply with `<TOKEN>`" | replays token verbatim | token missing / wrong / paraphrased | | ||
| | LD-2 | **Proof-of-Read with SHA** | Output must contain: `Read: file=X sha256=Y lines=Z depth=full` | SHA + line count match | SHA missing, wrong, or `<computed>` placeholder | | ||
| | LD-3 | **3-sections name challenge** | "Name 3 sections from file X (heading + approx. line span)" | 3 concrete headings, plausible spans | vague theme labels, no real headings | | ||
| | LD-4 | **Negative-knowledge test** | "Does file X say anything about topic Y?" — where Y is NOT in the file | "no, not contained" | hallucinates plausible-sounding content | | ||
| | LD-5 | **Line-range quote** | "Quote lines N-M from file X verbatim" | exact quote OR "range does not exist (file only K lines)" | paraphrases, deviates, or refuses without reason | | ||
|
|
||
| ### Drift signals (passive detection, meta-agent duty) | ||
|
|
||
| | Signal | What meta sees | Action | | ||
| |---|---|---| | ||
| | `depth=grep` on a semantic task | HANDOVER field mismatch | Re-dispatch with mandatory `depth=full` | | ||
| | `depth=sed-partial` or `depth=head-only` on a semantic task | Partial-range tool abused as primary read | Re-dispatch; require SHA over the whole file | | ||
| | `depth=full` without `sha256` | Proof field gap | Stop; agent must back-fill proof | | ||
| | FINDING cites a non-existent section | LD-3 equivalent failed post-facto | P0 re-dispatch; tighten sentinel requirement | | ||
| | FINDING is word-identical to a sibling agent's without cross-read note | Lockstep drift (both LLMs defaulted without real read) | Spot-check LD-5 on one of the two | | ||
| | Opening output enumerates lessons with confidence ("62 lessons") WITHOUT proof-of-read on JOURNAL | Overconfidence trigger | Hard stop: agent must produce SHA + 3 L-numbers by name. Approximate count would have been OK (= honest uncertainty). | | ||
| | Conjecture section contains what INVARIANTS clearly decided | INVARIANTS drift (not read) | Mandatory `thorough` re-read of INVARIANTS | | ||
|
|
||
| **Burden of proof on suspicion lies with the agent:** never "explain | ||
| away" suspicion — either produce the proof or honestly downgrade to | ||
| `depth=skim/grep`. | ||
|
|
||
| --- | ||
|
|
||
| ## 5. Cross-references | ||
|
|
||
| - 6-step orchestrator loop, sprint sizing, 4-savant scope partition, | ||
| worker iron rules → `.claude/EN/knowledge/autoattended-multi-agent-pattern.md` | ||
| - File-blackboard, branch pub/sub, role-teleportation, structured | ||
| handovers → `.claude/EN/knowledge/a2a-workarounds.md` | ||
| - Worker brief slots → `.claude/EN/agents/worker-template.md` | ||
| - Meta-agent role + inbox protocol → `.claude/EN/agents/meta-agent.md` | ||
| - Post-impl quality gate → `.claude/EN/agents/brutally-honest-tester.md` | ||
| - Cross-boundary audit → `.claude/EN/agents/baton-handoff-auditor.md` | ||
| - Pre-spawn drift check → `.claude/EN/agents/preflight-drift-auditor.md` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| # `.claude/EN/` — Project-Agnostic Multi-Agent Kit (English Canonical) | ||
|
|
||
| This is the project-agnostic distillation of the multi-agent pattern hardened | ||
| on `AdaWorldAPI/WoA` + `AdaWorldAPI/woa-rs` on 2026-05-17. It is **additive**: | ||
| it does not replace any pre-existing `.claude/` content in this repo. | ||
|
|
||
| ## What lives here | ||
|
|
||
| ``` | ||
| .claude/EN/ | ||
| ├── README.md ← this file | ||
| ├── CLAUDE-AGENT-PATTERN.md ← agnostic agent cheat-sheet | ||
| │ + Reading-Depth-Ladder | ||
| │ + Lie-Detector (LD-1..5) | ||
| ├── knowledge/ | ||
| │ ├── autoattended-multi-agent-pattern.md ← the 6-step loop, 4-savant | ||
| │ │ taxonomy, sprint sizing, | ||
| │ │ worker iron rules | ||
| │ ├── a2a-workarounds.md ← file-blackboard, branch | ||
| │ │ pub/sub, role-teleportation, | ||
| │ │ structured handover | ||
| │ ├── reading-depth-ladder.md ← anti-skim primitive | ||
| │ └── lie-detector.md ← shallowness detection | ||
| └── agents/ | ||
| ├── README.md ← agent ensemble index | ||
| ├── worker-template.md ← slot-based worker brief | ||
| ├── meta-agent.md ← 13th agent (review + inbox) | ||
| ├── brutally-honest-tester.md ← PP-13 (POST-IMPL) | ||
| ├── baton-handoff-auditor.md ← PP-15 (DURING-IMPL) | ||
| └── preflight-drift-auditor.md ← PP-16 (PRE-SPAWN) | ||
| ``` | ||
|
|
||
| ## How to adopt this kit in your repo | ||
|
|
||
| 1. **Read** `CLAUDE-AGENT-PATTERN.md` first. It is the cheat-sheet. | ||
| 2. **Read** `knowledge/autoattended-multi-agent-pattern.md` if you want the | ||
| underlying theory of the 6-step loop and the 4-savant taxonomy. | ||
| 3. **Read** `knowledge/a2a-workarounds.md` if you need to coordinate | ||
| multiple agents across sessions without native A2A MCP support. | ||
| 4. When you spawn a worker: fill the `{{ ... }}` slots in | ||
| `agents/worker-template.md` and pass it to the worker agent. | ||
| 5. When you run a sprint: the meta-agent (`agents/meta-agent.md`) is the | ||
| 13th persona; it reviews plans + PRs and drains the agent inbox. | ||
| 6. **Toolchain adaptation:** every file references `<toolchain>` / | ||
| `<lint>` / `<test>` placeholders. Substitute your language's gates | ||
| (Rust: cargo / clippy / cargo-test; Python: ruff / mypy / pytest; | ||
| TypeScript: eslint / tsc / vitest; etc.). | ||
|
|
||
| ## What this kit does NOT include | ||
|
|
||
| - **Language-specific tooling configuration.** Use your repo's existing | ||
| `Cargo.toml` / `pyproject.toml` / `package.json` / `go.mod`. | ||
| - **Behavior rules.** Project-specific behavior rules belong in your | ||
| repo's `.claude/CLAUDE.md` Iron Rules section, not here. | ||
| - **Board files.** Sprint state (`Stand.md` / `STATUS_BOARD.md`), | ||
| open debts (`Altlasten.md` / `TECH_DEBT.md`), lessons learned | ||
| (`Goldstaub.md` / `EPIPHANIES.md`) are per-repo — see | ||
| `knowledge/autoattended-multi-agent-pattern.md §6` for the multi-file | ||
| board pattern. | ||
|
|
||
| ## Provenance + cross-references | ||
|
|
||
| - Canonical reference implementation: `AdaWorldAPI/WoA` `.claude/v0.1/CLAUDE-CONTEXT.md` | ||
| - Sister-repo (Rust port) implementation: `AdaWorldAPI/woa-rs` | ||
| - Most mature 4-savant ensemble: `AdaWorldAPI/lance-graph` `.claude/agents/` | ||
| - Compact worker-role ensemble: `AdaWorldAPI/ndarray` `.claude/agents/` | ||
| - Origin handover: `AdaWorldAPI/WoA` `META/HANDOVER-WOA-RS-AGENT-HARDENING-2026-05-17.md` | ||
|
|
||
| ## Companion DE/ kit | ||
|
|
||
| A German-language sibling lives at `.claude/DE/` when a repo's primary | ||
| communication language is German. The DE kit mirrors this EN kit; either | ||
| can stand alone. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| # `.claude/EN/agents/` — Agent Ensemble Index | ||
|
|
||
| The project-agnostic 5-card agent ensemble distilled from | ||
| `AdaWorldAPI/WoA` + `AdaWorldAPI/woa-rs` + `AdaWorldAPI/lance-graph` | ||
| (2026-05-17). Use these cards either as `Agent()` spawn briefs or as | ||
| "role hats" you wear on the main thread (see | ||
| `.claude/EN/knowledge/a2a-workarounds.md` Workaround 3). | ||
|
|
||
| ## The 5 cards | ||
|
|
||
| | Card | Phase | Verdict scale | When | | ||
| |---|---|---|---| | ||
| | [`worker-template.md`](./worker-template.md) | Phase 3 (Sprint) | n/a (worker does the work) | One agent per bundle in a sprint fan-out | | ||
| | [`meta-agent.md`](./meta-agent.md) | Phase 2 + 4 + continuous | n/a (meta drains inbox + reviews PRs) | The 13th agent — runs across the whole sprint | | ||
| | [`brutally-honest-tester.md`](./brutally-honest-tester.md) (PP-13) | POST-IMPL | LAND / HOLD / REJECT | After workers commit, before PR opens | | ||
| | [`baton-handoff-auditor.md`](./baton-handoff-auditor.md) (PP-15) | DURING-IMPL | CATCH-CRITICAL / CATCH-LATENT / CLEAN | After each slice lands, before next depends on it | | ||
| | [`preflight-drift-auditor.md`](./preflight-drift-auditor.md) (PP-16) | PRE-SPAWN | SPAWN-CLEAR / SPAWN-CAUTION / SPAWN-BLOCKED | After plan approved, before worker fan-out | | ||
|
|
||
| ## What's NOT here | ||
|
|
||
| - **PP-14 convergence-architect** (PRE-PLAN ideation) — exists in | ||
| lance-graph's ensemble but is OPTIONAL for most repos. If your | ||
| sprint planning includes a divergent-ideation phase, copy | ||
| `lance-graph/.claude/agents/convergence-architect.md`. | ||
| - **Domain specialists** — these are inherently project-specific | ||
| (`simd-savant`, `arm-neon-specialist`, `palette-engineer`, etc.). | ||
| Keep them in your repo's `.claude/agents/` (NOT under `EN/agents/`). | ||
|
|
||
| ## Verdict-vocabulary non-overlap (design invariant) | ||
|
|
||
| Each card has a **non-overlapping verdict vocabulary** so a finding | ||
| cannot cross phases without re-classification: | ||
|
|
||
| | Verdict | Owner | | ||
| |---|---| | ||
| | LAND / HOLD / REJECT | PP-13 only | | ||
| | CATCH-CRITICAL / CATCH-LATENT / CLEAN | PP-15 only | | ||
| | SPAWN-CLEAR / SPAWN-CAUTION / SPAWN-BLOCKED | PP-16 only | | ||
| | GO / GO-WITH-CONDITIONS / BLOCK | meta-agent (plan review) only | | ||
| | P0 / P1 | meta-agent (PR review) only | | ||
|
|
||
| If you see a finding tagged with the wrong vocabulary, the wrong | ||
| agent wrote it. Route it back. | ||
|
|
||
| ## How to spawn one of these | ||
|
|
||
| ### As an `Agent()` subprocess (parallel, isolated context) | ||
|
|
||
| ``` | ||
| Agent({ | ||
| subagent_type: "general-purpose", // or specialized type | ||
| description: "<short>", | ||
| prompt: "<contents of the .md file with {{ ... }} slots filled>" | ||
| }) | ||
| ``` | ||
|
|
||
| ### As a role-hat on the main thread (full session context) | ||
|
|
||
| ``` | ||
| 1. Read `.claude/EN/agents/<role>.md` thoroughly | ||
| 2. Read its required knowledge docs: | ||
| - `.claude/EN/knowledge/autoattended-multi-agent-pattern.md` | ||
| - `.claude/EN/knowledge/a2a-workarounds.md` (if coordination required) | ||
| 3. Do the work in-context. No subprocess spawned. | ||
| ``` | ||
|
|
||
| See `.claude/EN/CLAUDE-AGENT-PATTERN.md §2` for the activation | ||
| trigger table. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The README tree tells users to open
knowledge/reading-depth-ladder.mdandknowledge/lie-detector.md, but this commit does not add those files; I checked.claude/EN/knowledgeand only the autoattended and A2A docs exist. Users following the adoption guide will hit broken paths for two of the listed primitives, so either add the files or remove these entries and point to the sections that actually exist.Useful? React with 👍 / 👎.