Skip to content

Commit 1dacc3e

Browse files
AdaWorldAPIAdaWorldAPI
authored
Merge pull request #151 from AdaWorldAPI/claude/consolidate-knowledge-files-HLPME
consolidate: add project-agnostic multi-agent kit (.claude/EN/)
2 parents 9f3cf22 + 982c9f2 commit 1dacc3e

11 files changed

Lines changed: 1808 additions & 0 deletions

‎.claude/EN/CLAUDE-AGENT-PATTERN.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Agent Pattern Cheat-Sheet (project-agnostic, English canonical)
2+
3+
Lookup-style add-on to your repo's `.claude/CLAUDE.md`. Read this before
4+
prompting any multi-agent work. Companion knowledge files under
5+
`.claude/EN/knowledge/` and `.claude/EN/agents/`.
6+
7+
> Source: distilled from `AdaWorldAPI/WoA` `.claude/CLAUDE.md` §3.5 + §3.6
8+
> as of 2026-05-17. Reference implementations: `WoA` (Python), `woa-rs`
9+
> (Rust), `lance-graph` (Rust, most mature), `ndarray` (Rust, compact).
10+
11+
---
12+
13+
## 1. Compressed baseline
14+
15+
```
16+
12 workers + 1 coordinator · autoattended · full authorization · auto-resolve · log all issues
17+
plan/preflight → review → correct → sprint → review code → fix P0 → commit → repeat
18+
```
19+
20+
## 2. Agent ensemble — Function · Activation · Card
21+
22+
| Function | Activation | Card |
23+
|---|---|---|
24+
| Worker-Impl | Sprint Phase 3 spawn out of `SPRINT-N-PLAN.md`-bundle row | `.claude/EN/agents/worker-template.md` |
25+
| Meta-Agent (13th) | Phase 2 plan review + Phase 4 code review + continuous inbox-drain | `.claude/EN/agents/meta-agent.md` |
26+
| PP-13 brutally-honest-tester | "about to commit" / "PR diff touches code" | `.claude/EN/agents/brutally-honest-tester.md` |
27+
| PP-14 convergence-architect | PRE-PLAN divergent ideation (optional, see knowledge/autoattended-multi-agent-pattern.md §3) | — |
28+
| 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` |
29+
| PP-16 preflight-drift-auditor | "before sprint spawn" / "preflight check" / "verify spec against main" | `.claude/EN/agents/preflight-drift-auditor.md` |
30+
31+
Full specs in `.claude/EN/agents/<role>.md`. Pattern theory in
32+
`.claude/EN/knowledge/autoattended-multi-agent-pattern.md`. Coordination
33+
primitives in `.claude/EN/knowledge/a2a-workarounds.md`.
34+
35+
---
36+
37+
## 3. Reading-Depth-Ladder
38+
39+
Anti-skim discipline as a lookup. **Default bias: read too deep rather
40+
than too shallow.** If in doubt, upgrade the depth; never downgrade.
41+
42+
| Depth | When appropriate | Guardrail / Proof-of-Depth |
43+
|---|---|---|
44+
| `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. |
45+
| `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". |
46+
| `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. |
47+
| `read` | File < ~500 lines, standard read | Top to bottom, no skips. For larger files: offset/limit chunks but actually read every chunk. |
48+
| `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? |
49+
| `troubleshooting` | Known bug + error message | Error → grep symbol → READ function in full → READ caller(s). No spot-fix without call-site context. |
50+
| `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. |
51+
52+
### When → minimum depth
53+
54+
| If you are about to… | …then at minimum |
55+
|---|---|
56+
| Read memory files (CONTEXT / JOURNAL / TODO) at session start | `thorough read` |
57+
| Read `.claude/CLAUDE.md` / `BOOT.md` / RFCs / INVARIANTS | `thorough read` |
58+
| Touch a schema / migration file | `thorough read` + check downstream drift detectors |
59+
| Open an unknown file for the first time | at least `read`, preferably `thorough` |
60+
| Pure symbol lookup ("where is `foo` defined?") | `grep` OK but then read the definition in full |
61+
| Triage a bug report | `troubleshooting` (error → grep → read function + caller) |
62+
| Plan a refactor / wave / audit | `fan-out research` (inventory file mandatory) |
63+
| You are unsure which depth | upgrade one rung |
64+
65+
---
66+
67+
## 4. Lie-Detector — shallowness + drift detection
68+
69+
> **P0 rule:** No claims without thorough comprehension of the subject
70+
> AND all adjacent context.
71+
>
72+
> **Cognitive frame (Kahneman/Tversky + Dunning-Kruger):** the problem is
73+
> NOT vagueness ("about 60 lessons") — that is **honest uncertainty**
74+
> (System 2 reporting in). The problem is **overconfidence**: a specific
75+
> claim without the read that would support it. System-1 "easy-path"
76+
> heuristic yields a plausible-sounding answer BEFORE System 2 verifies.
77+
>
78+
> **Trigger heuristic:** vague answer ("not sure") = honest → no trigger.
79+
> Confident false answer = lie-detector fires. Confident correct answer
80+
> without proof-of-read = also fires (luck vs. hallucination is
81+
> distinguishable only via LD-1..5).
82+
83+
Five concrete tests, cheap to expensive:
84+
85+
| # | Test | How | Honest agent | Shallow agent |
86+
|---|---|---|---|---|
87+
| 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 |
88+
| 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 |
89+
| 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 |
90+
| 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 |
91+
| 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 |
92+
93+
### Drift signals (passive detection, meta-agent duty)
94+
95+
| Signal | What meta sees | Action |
96+
|---|---|---|
97+
| `depth=grep` on a semantic task | HANDOVER field mismatch | Re-dispatch with mandatory `depth=full` |
98+
| `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 |
99+
| `depth=full` without `sha256` | Proof field gap | Stop; agent must back-fill proof |
100+
| FINDING cites a non-existent section | LD-3 equivalent failed post-facto | P0 re-dispatch; tighten sentinel requirement |
101+
| 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 |
102+
| 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). |
103+
| Conjecture section contains what INVARIANTS clearly decided | INVARIANTS drift (not read) | Mandatory `thorough` re-read of INVARIANTS |
104+
105+
**Burden of proof on suspicion lies with the agent:** never "explain
106+
away" suspicion — either produce the proof or honestly downgrade to
107+
`depth=skim/grep`.
108+
109+
---
110+
111+
## 5. Cross-references
112+
113+
- 6-step orchestrator loop, sprint sizing, 4-savant scope partition,
114+
worker iron rules → `.claude/EN/knowledge/autoattended-multi-agent-pattern.md`
115+
- File-blackboard, branch pub/sub, role-teleportation, structured
116+
handovers → `.claude/EN/knowledge/a2a-workarounds.md`
117+
- Worker brief slots → `.claude/EN/agents/worker-template.md`
118+
- Meta-agent role + inbox protocol → `.claude/EN/agents/meta-agent.md`
119+
- Post-impl quality gate → `.claude/EN/agents/brutally-honest-tester.md`
120+
- Cross-boundary audit → `.claude/EN/agents/baton-handoff-auditor.md`
121+
- Pre-spawn drift check → `.claude/EN/agents/preflight-drift-auditor.md`

‎.claude/EN/README.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# `.claude/EN/` — Project-Agnostic Multi-Agent Kit (English Canonical)
2+
3+
This is the project-agnostic distillation of the multi-agent pattern hardened
4+
on `AdaWorldAPI/WoA` + `AdaWorldAPI/woa-rs` on 2026-05-17. It is **additive**:
5+
it does not replace any pre-existing `.claude/` content in this repo.
6+
7+
## What lives here
8+
9+
```
10+
.claude/EN/
11+
├── README.md ← this file
12+
├── CLAUDE-AGENT-PATTERN.md ← agnostic agent cheat-sheet
13+
│ + Reading-Depth-Ladder
14+
│ + Lie-Detector (LD-1..5)
15+
├── knowledge/
16+
│ ├── autoattended-multi-agent-pattern.md ← the 6-step loop, 4-savant
17+
│ │ taxonomy, sprint sizing,
18+
│ │ worker iron rules
19+
│ ├── a2a-workarounds.md ← file-blackboard, branch
20+
│ │ pub/sub, role-teleportation,
21+
│ │ structured handover
22+
│ ├── reading-depth-ladder.md ← anti-skim primitive
23+
│ └── lie-detector.md ← shallowness detection
24+
└── agents/
25+
├── README.md ← agent ensemble index
26+
├── worker-template.md ← slot-based worker brief
27+
├── meta-agent.md ← 13th agent (review + inbox)
28+
├── brutally-honest-tester.md ← PP-13 (POST-IMPL)
29+
├── baton-handoff-auditor.md ← PP-15 (DURING-IMPL)
30+
└── preflight-drift-auditor.md ← PP-16 (PRE-SPAWN)
31+
```
32+
33+
## How to adopt this kit in your repo
34+
35+
1. **Read** `CLAUDE-AGENT-PATTERN.md` first. It is the cheat-sheet.
36+
2. **Read** `knowledge/autoattended-multi-agent-pattern.md` if you want the
37+
underlying theory of the 6-step loop and the 4-savant taxonomy.
38+
3. **Read** `knowledge/a2a-workarounds.md` if you need to coordinate
39+
multiple agents across sessions without native A2A MCP support.
40+
4. When you spawn a worker: fill the `{{ ... }}` slots in
41+
`agents/worker-template.md` and pass it to the worker agent.
42+
5. When you run a sprint: the meta-agent (`agents/meta-agent.md`) is the
43+
13th persona; it reviews plans + PRs and drains the agent inbox.
44+
6. **Toolchain adaptation:** every file references `<toolchain>` /
45+
`<lint>` / `<test>` placeholders. Substitute your language's gates
46+
(Rust: cargo / clippy / cargo-test; Python: ruff / mypy / pytest;
47+
TypeScript: eslint / tsc / vitest; etc.).
48+
49+
## What this kit does NOT include
50+
51+
- **Language-specific tooling configuration.** Use your repo's existing
52+
`Cargo.toml` / `pyproject.toml` / `package.json` / `go.mod`.
53+
- **Behavior rules.** Project-specific behavior rules belong in your
54+
repo's `.claude/CLAUDE.md` Iron Rules section, not here.
55+
- **Board files.** Sprint state (`Stand.md` / `STATUS_BOARD.md`),
56+
open debts (`Altlasten.md` / `TECH_DEBT.md`), lessons learned
57+
(`Goldstaub.md` / `EPIPHANIES.md`) are per-repo — see
58+
`knowledge/autoattended-multi-agent-pattern.md §6` for the multi-file
59+
board pattern.
60+
61+
## Provenance + cross-references
62+
63+
- Canonical reference implementation: `AdaWorldAPI/WoA` `.claude/v0.1/CLAUDE-CONTEXT.md`
64+
- Sister-repo (Rust port) implementation: `AdaWorldAPI/woa-rs`
65+
- Most mature 4-savant ensemble: `AdaWorldAPI/lance-graph` `.claude/agents/`
66+
- Compact worker-role ensemble: `AdaWorldAPI/ndarray` `.claude/agents/`
67+
- Origin handover: `AdaWorldAPI/WoA` `META/HANDOVER-WOA-RS-AGENT-HARDENING-2026-05-17.md`
68+
69+
## Companion DE/ kit
70+
71+
A German-language sibling lives at `.claude/DE/` when a repo's primary
72+
communication language is German. The DE kit mirrors this EN kit; either
73+
can stand alone.

‎.claude/EN/agents/README.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# `.claude/EN/agents/` — Agent Ensemble Index
2+
3+
The project-agnostic 5-card agent ensemble distilled from
4+
`AdaWorldAPI/WoA` + `AdaWorldAPI/woa-rs` + `AdaWorldAPI/lance-graph`
5+
(2026-05-17). Use these cards either as `Agent()` spawn briefs or as
6+
"role hats" you wear on the main thread (see
7+
`.claude/EN/knowledge/a2a-workarounds.md` Workaround 3).
8+
9+
## The 5 cards
10+
11+
| Card | Phase | Verdict scale | When |
12+
|---|---|---|---|
13+
| [`worker-template.md`](./worker-template.md) | Phase 3 (Sprint) | n/a (worker does the work) | One agent per bundle in a sprint fan-out |
14+
| [`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 |
15+
| [`brutally-honest-tester.md`](./brutally-honest-tester.md) (PP-13) | POST-IMPL | LAND / HOLD / REJECT | After workers commit, before PR opens |
16+
| [`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 |
17+
| [`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 |
18+
19+
## What's NOT here
20+
21+
- **PP-14 convergence-architect** (PRE-PLAN ideation) — exists in
22+
lance-graph's ensemble but is OPTIONAL for most repos. If your
23+
sprint planning includes a divergent-ideation phase, copy
24+
`lance-graph/.claude/agents/convergence-architect.md`.
25+
- **Domain specialists** — these are inherently project-specific
26+
(`simd-savant`, `arm-neon-specialist`, `palette-engineer`, etc.).
27+
Keep them in your repo's `.claude/agents/` (NOT under `EN/agents/`).
28+
29+
## Verdict-vocabulary non-overlap (design invariant)
30+
31+
Each card has a **non-overlapping verdict vocabulary** so a finding
32+
cannot cross phases without re-classification:
33+
34+
| Verdict | Owner |
35+
|---|---|
36+
| LAND / HOLD / REJECT | PP-13 only |
37+
| CATCH-CRITICAL / CATCH-LATENT / CLEAN | PP-15 only |
38+
| SPAWN-CLEAR / SPAWN-CAUTION / SPAWN-BLOCKED | PP-16 only |
39+
| GO / GO-WITH-CONDITIONS / BLOCK | meta-agent (plan review) only |
40+
| P0 / P1 | meta-agent (PR review) only |
41+
42+
If you see a finding tagged with the wrong vocabulary, the wrong
43+
agent wrote it. Route it back.
44+
45+
## How to spawn one of these
46+
47+
### As an `Agent()` subprocess (parallel, isolated context)
48+
49+
```
50+
Agent({
51+
subagent_type: "general-purpose", // or specialized type
52+
description: "<short>",
53+
prompt: "<contents of the .md file with {{ ... }} slots filled>"
54+
})
55+
```
56+
57+
### As a role-hat on the main thread (full session context)
58+
59+
```
60+
1. Read `.claude/EN/agents/<role>.md` thoroughly
61+
2. Read its required knowledge docs:
62+
- `.claude/EN/knowledge/autoattended-multi-agent-pattern.md`
63+
- `.claude/EN/knowledge/a2a-workarounds.md` (if coordination required)
64+
3. Do the work in-context. No subprocess spawned.
65+
```
66+
67+
See `.claude/EN/CLAUDE-AGENT-PATTERN.md §2` for the activation
68+
trigger table.

0 commit comments

Comments
 (0)