mirror of
https://github.com/Kpa-clawbot/meshcore-analyzer.git
synced 2026-08-27 22:54:05 +00:00
df28efaed9
## What Adds `docs/agents/` — an onboarding pack for external contributors using their own AI coding agent (Claude Code, Codex, Cursor, Aider, OpenClaw, etc.). ## Why Maintainers run an agent-driven workflow against this repo. External contributors using agents benefit from the same discipline (TDD red→green, PII preflight, parallel persona polish, three-axis merge readiness) but had nothing portable to point at. This documents the **process** and the **reusable building blocks** in an agent-agnostic way. ## Contents ``` docs/agents/ README.md WORKFLOW.md # pipeline + planning + PII preflight + force-push + worktrees RULES.md # 36 hard-won discipline rules TDD.md # red→green requirement, exemptions SUBAGENT-BRIEF-TEMPLATE.md skills/ # 14 task playbooks (intake, fix, polish, merge-gate, release, ops...) personas/ # 14 review voices (carmack, dijkstra, torvalds, meshcore, taleb, ...) ``` ## Scope Docs-only. No code changes. Existing `AGENTS.md` is unchanged. All committed text uses sanitized placeholders (`<workspace>`, `<repo>`, `YOUR_NAME`, `YOUR_HANDLE`, etc.) — no personal names, phones, IPs, keys, or absolute home/root paths. ## Verification - PII preflight grep on staged diff: only matches are the literal placeholders inside the documented sanitized example (`YOUR_NAME|YOUR_HANDLE|...|api[_-]?key|...`). - Off-topic skill grep on `docs/agents/`: clean (zero hits for the wrong-language/off-topic skill names that were scrubbed from the prior attempt). --------- Co-authored-by: meshcore-bot <bot@meshcore.local> Co-authored-by: Kpa-clawbot <bot@openclaw.local> Co-authored-by: efiten <erwin.fiten@gmail.com>
Personas
Personas are role prompts used in parallel review fan-out during pr-polish. Each one has a distinct voice and bias — perf, correctness, taste, simplicity, statistics, mesh-networking expertise, etc.
The pattern: when polishing a PR, spawn adversarial + 1–2 expert personas + Kent Beck simultaneously in one tool-call block. Each persona reviews the same diff independently, returns findings tagged BLOCKER / MAJOR / MINOR / NIT. Findings are deduped and addressed in a single follow-up commit.
Sequential persona chains are deprecated — they balloon context and serialize wall-time for no quality gain.
Roster
Adversarial / taste
- torvalds — taste, naming, structure; ruthless on bad abstractions.
- house — diagnostic skeptic; "everybody lies"; hunts for the symptom the PR is not explaining.
- djb — minimalism, correctness, no surprises; security-paranoid.
Engineering experts
- carmack — performance, data layout, simplicity over cleverness.
- dijkstra — correctness, invariants, proof-style reasoning.
- feynman — first-principles explanation; "if you can't explain it simply, you don't understand it."
Domain experts
- meshcore — MeshCore protocol expert; packet types, channel hashes, observer semantics.
- mesh-operator — operator perspective; what breaks at 3am, what config knobs are missing.
Analysis / statistics / risk
- tufte — data visualization; charts that mislead, ink/data ratio.
- taleb — fragility, fat tails, hidden risk; "what happens at 10×?"
- munger — mental models, invert-always-invert, second-order effects.
Process / spec
- orchestrator — pipeline discipline; verifies handoffs, three-axis merge readiness.
- spec-refiner — turns vague asks into precise acceptance criteria.
- doshi — UX / product discipline; user journey, edge cases users hit.
Tests
The Kent-Beck persona lives inside the pr-polish skill rather than as a standalone file because it's tightly coupled to the TDD red→green verification (see ../TDD.md). It always runs in the polish fan-out.
Picking personas for a PR
| PR shape | Personas to fan out |
|---|---|
| Backend perf / data-path change | carmack + dijkstra + (kent-beck) |
| Protocol / packet parsing | meshcore + djb + (kent-beck) |
| Frontend / UI / chart | tufte + doshi + (kent-beck) |
| Ops / staging / deploy | mesh-operator + taleb + (kent-beck) |
| Refactor / structure | torvalds + dijkstra + (kent-beck) |
| Spec / requirements unclear | spec-refiner + house + (kent-beck) |
| Risk / failure-mode analysis | taleb + munger + house |
Always include an adversarial voice (torvalds/house/djb) and the Kent-Beck TDD check.