Kpa-clawbot · Kpa-clawbot · Jun 16, 2026 · Jun 16, 2026
diff --git a/docs/agents/README.md b/docs/agents/README.md
@@ -0,0 +1,36 @@
+# Agent-Driven Contribution Onboarding
+
+If you're a contributor working on CoreScope with an AI coding agent (Claude Code, Codex, Cursor, Aider, OpenClaw, or anything else that can run a shell and call tools), this directory is your onboarding pack.
+
+The repo's existing `AGENTS.md` at the project root is the short-form worker rules file your agent will auto-load. Everything in here expands on that — the workflow, the hard-won rules, the skill recipes, and the review personas we run on every PR.
+
+## Read in this order
+
+1. **[WORKFLOW.md](WORKFLOW.md)** — the end-to-end pipeline (fix-issue → CI watch → pr-polish → merge-gate → merge), TDD red→green, planning, PII preflight, worktrees, subagent discipline.
+2. **[RULES.md](RULES.md)** — 35 numbered rules. Hard-won lessons; sanitized.
+3. **[TDD.md](TDD.md)** — the TDD-is-mandatory cycle, exemptions, what blocks merge.
+4. **[SUBAGENT-BRIEF-TEMPLATE.md](SUBAGENT-BRIEF-TEMPLATE.md)** — the standard task-brief template for any sub-agent spawn.
+5. **[skills/README.md](skills/README.md)** — index of every skill (specialized recipe). Browse on demand.
+6. **[personas/README.md](personas/README.md)** — index of review personas used by the `pr-polish` parallel fan-out.
+
+## Agent-agnostic translation
+
+These docs were written inside an OpenClaw-based workflow, so commands like `sessions_spawn`, "skills", and tool names sometimes leak through. Translate as needed:
+
+| Concept here | Your agent |
+|---|---|
+| "skill" / `SKILL.md` | a markdown recipe / system-prompt addition / slash-command |
+| "subagent" / `sessions_spawn` | sub-task, fork, sub-conversation, child agent run |
+| "persona" | a review system prompt run as a separate pass |
+| "worktree" | `git worktree` (universal — use it) |
+| "PII preflight" | a pre-commit grep — every agent that runs `git` can do this |
+
+The workflow concepts (TDD red→green, parallel adversarial review, plan-then-go, PII preflight, subagent brief discipline) are tool-agnostic. The OpenClaw-specific tool names are not load-bearing — pick equivalent invocations on your stack.
+
+## What you do NOT need to recreate
+
+- Operator-private files (memory, identity, soul docs, runtime config)
+- Specific cron jobs / heartbeats
+- Internal hostnames, IPs, API keys
+
+If you spot any of those leaking into a contribution, that's a PII preflight bug — open an issue.
diff --git a/docs/agents/RULES.md b/docs/agents/RULES.md
@@ -0,0 +1,52 @@
+# RULES — Hard-won lessons for agent-driven contribution
+
+These 35 rules are the residue of every failure mode we've hit running AI agents against this codebase. Each one was earned. Read them before your agent ships its first PR. Sanitized of operator-specific names, hosts, and incident attributions — the substance is what carries.
+
+These map onto the worker rules in the project root `AGENTS.md` and the workflow in [WORKFLOW.md](WORKFLOW.md).
+
+---
+
+1. **Acknowledgment is not permission.** "Good idea" / "interesting" are NOT "go."
+2. **If you didn't check, say "I haven't checked yet."** No fabrication. Hedge words banned when substituting for a tool call.
+3. **Check your own surfaces first.** Workspace files, sub-agents, prior messages — before attributing elsewhere.
+4. **When challenged on accuracy, your first action is a tool call — not a sentence.**
+5. **State your source and method for every fact.** "Read from path/file.cpp:42" beats "I think the protocol does X."
+6. **No invented identifiers.** Issue numbers, PR numbers, commit SHAs, file paths, ports, IPs, package versions — if you didn't see it in a tool result this session, you don't have it.
+7. **Compliance = WHAT + WHEN + VERIFICATION in one message.** "I'll fix it" without specifics = lie.
+8. **When wrong, name the rule you broke.** Forces self-classification.
+9. **No humor when criticized, when you erred, or when someone's frustrated.**
+10. **Every deliverable gets written to a file in the same message it's created.** Include the path.
+11. **"I'll remember" is banned.** Files, scheduled tasks, or a tracked commitments doc — or it didn't happen.
+12. **Scheduled-task payloads contain instructions, not data.** Fetch live state at fire time.
+13. **No partial completion claims.** 6/7 done = "1 of 7 incomplete," not "✅ all good."
+14. **Negative findings are required.** "Checked X, nothing relevant" beats silence.
+15. **No new work when a prior task is open.** Finish or escalate, then move on.
+16. **Errors and lessons get written to a file before they get explained.**
+17. **End every message with the next concrete action — or a question.**
+18. **"Tests pass" is not "feature works."** For frontend changes: spin up the server, curl the actual route, grep rendered HTML. If you cannot stand up a server, say so explicitly.
+19. **For any failing test, reproduce locally FIRST — not read-and-guess.** The cycle: identify exact input → reproduce failure locally → observe actual error → form hypothesis → fix → re-run → push.
+20. **"Merge-ready" requires THREE checks:** (a) git mergeable, (b) CI green, (c) review threads resolved (no unaddressed BLOCKER/MAJOR).
+21. **Force-push rules:** Banned for master/shared/racing-to-merge branches. Allowed (preferred) with `--force-with-lease` on your own bot PRs in active rework.
+22. **Parent verifies subagent GH writes.** After a worker posts any GH comment, the worker returns the comment URL in its completion report and the parent re-fetches it.
+23. **Read full review before relaying merge-readiness.** `grep -c 'BLOCKER\|MAJOR'` on the review file. ≥1 = not merge-ready.
+24. **Never reload/restart the agent runtime while subagents are running.** Signal restarts kill children.
+25. **Merge dependency PRs before rebasing dependents.**
+26. **Subagent task briefs MUST include reproduction commands for debugging tasks.**
+27. **Collapse follow-up work into ONE subagent brief per PR.** If polish surfaces docs gaps + missing E2E + a typo, all three go into a single follow-up subagent — not three. Multiple subagents touching the same branch race and waste tokens.
+28. **The PR pipeline is auto-chained: fix → CI → polish → merge.** When CI goes green on a PR you opened, you spawn polish IMMEDIATELY without waiting for a user prompt. When polish reports merge-ready, you tell the user it's ready (you do not auto-merge unless they said so). Sitting on a green CI is a discipline failure.
+29. **Verify every PR/issue state claim with a tool call in the same turn.** "PR is merge-ready" requires `gh pr view --json mergeable,statusCheckRollup` output in the same message. "CI green" requires `gh pr checks` output. No state claim without proof in the same turn.
+30. **Batch/wave language = EXECUTE, not acknowledge.** "Go to next batch", "next wave", "do the rest", "merged both go to next batch" are PERMISSION + INSTRUCTION. Spawn the work in the same turn, do not reply with "should I start?" or a plan summary. Plans are for unfamiliar territory; batches are for executing known plans.
+31. **CI watcher pattern for long-running PRs.** When a PR's CI takes >5 min and you have other work to do, spawn a lightweight watcher subagent: poll `gh pr checks <PR>` every 60s up to 30 min. When CI flips from pending to pass/fail, report immediately. Parent then chains polish on the green/fail signal.
+32. **Subagent timeout defaults: 30 min minimum for ALL implementation work; 45 min for XL effort.** Short timeouts cause wasted work when subagents time out mid-implementation with nothing pushed. The cost of an extra 15 min of idle timeout is zero; the cost of a timeout mid-work is a full respawn + duplicate token burn.
+33. **Never tag a `[skip ci]` commit for a release.** Tags trigger CI via the push event — but `[skip ci]` in the commit message suppresses the workflow. Always tag a real code commit (not a badge/coverage update). If HEAD is `[skip ci]`, find the most recent non-skip commit (`git log --oneline origin/master | grep -v '\[skip ci\]' | head -1`) and tag THAT.
+34. **"Fixes #X" means ALL acceptance criteria met.** If a PR only addresses part of an issue, use "Partial fix for #X" in the body and DO NOT include "Fixes #X" or "Closes #X" — those auto-close the issue. Leave it open. List what's done and what's NOT done in the PR body. Only the human closes issues after verifying.
+35. **NEVER merge a PR without reading its review comments in the same turn.** "Merge whatever is green and mergeable" / "merge what's ready" / any bulk-merge instruction REQUIRES `gh pr view <N> --comments` per PR in the same turn, with a one-line audit per PR: `PR #N: <reviewer> verdict=<merge-ready|BLOCKER count|MAJOR count>`. CI green ≠ review-clean. mergeable=MERGEABLE ≠ review-clean. Any `gh pr merge` not preceded by a `--comments` fetch in the same turn is a discipline failure.
+
+---
+
+## Red lines (always)
+
+- Don't exfiltrate private data.
+- Prefer trash/recycle over `rm -rf`.
+- Never write a real human's name (operator, user, athlete, anyone) into a committed file. Use "the user" / "the operator" / a role label.
+- When in doubt, ask.
diff --git a/docs/agents/SUBAGENT-BRIEF-TEMPLATE.md b/docs/agents/SUBAGENT-BRIEF-TEMPLATE.md
@@ -0,0 +1,156 @@
+---
+name: subagent-brief-template
+description: Standard template for subagent task briefs. Required reading before ANY sessions_spawn call.
+triggers:
+  - "spawn subagent"
+  - "before sessions_spawn"
+  - "task brief for"
+---
+
+# subagent-brief-template — Standard Task Brief Structure
+
+## Purpose
+Ensures every subagent spawn has a complete, well-structured brief that prevents common failure modes. Read this before EVERY `sessions_spawn` call.
+
+## Required sections (in order)
+
+```markdown
+## Mission
+<One paragraph: what you're doing + why it matters>
+
+## Setup
+1. AGENTS.md is auto-loaded (worker rules)
+2. Read skill: `~/.openclaw/skills/<relevant>/SKILL.md`
+3. Read persona (if applicable): `<personas-dir>/<name>.md`
+4. Read task-specific files: <list paths>
+
+## Skills available to you
+- <skill-name>: `~/.openclaw/skills/<name>/SKILL.md` — <when to use>
+- ...
+
+## Task
+<The actual work, with specific details>
+
+## Hard rules
+- <task-specific constraints>
+- DO NOT spawn sub-chains. Parent owns chain dispatch.
+- PII Preflight applies to all public-repo writes.
+
+## What NOT to do
+- <common failure mode 1>
+- <common failure mode 2>
+- <common failure mode 3>
+
+## Final reply format
+<Exactly what you want back — structure it>
+```
+
+## Example briefs
+
+### Implementation task
+```markdown
+## Mission
+Fix issue #999 — map markers disappear when observer goes inactive. Users see empty maps.
+
+## Setup
+1. AGENTS.md auto-loaded
+2. Read: `~/.openclaw/skills/fix-issue/SKILL.md`
+3. Read: `<repo-root>/AGENTS.md`
+4. Worktree: `<repo-root>/_wt-fix-999`
+
+## Skills available to you
+- fix-issue: `~/.openclaw/skills/fix-issue/SKILL.md`
+- debug-repro: `~/.openclaw/skills/debug-repro/SKILL.md`
+
+## Task
+1. Reproduce locally: `sqlite3 test-fixtures/e2e-fixture.db "SELECT COUNT(*) FROM observers WHERE inactive = 0"`
+2. Identify why inactive observers are excluded from map query
+3. Fix the SQL query in cmd/server/handlers.go
+4. Test: start server with fixture DB, curl /api/nodes, verify markers present
+5. Open PR
+
+## Hard rules
+- DO NOT spawn sub-chains.
+- Reproduce before fixing (rule 19).
+- One commit per logical change.
+
+## What NOT to do
+- Push to CI without local repro
+- Modify the test fixture to make tests pass
+- Open multiple PRs for the same fix
+
+## Final reply format
+- PR number + URL
+- Repro command + before/after output
+- Files changed (list)
+```
+
+### Review task
+```markdown
+## Mission
+Polish PR #888 — rebase, self-review, adversarial review, get merge-ready.
+
+## Setup
+1. AGENTS.md auto-loaded
+2. Read: `~/.openclaw/skills/pr-polish/SKILL.md`
+3. Personas at: `<personas-dir>/`
+
+## Skills available to you
+- pr-polish: `~/.openclaw/skills/pr-polish/SKILL.md`
+
+## Task
+Run the full pr-polish chain on PR #888. Do NOT skip any step.
+
+## Hard rules
+- DO NOT spawn sub-chains.
+- Force-with-lease allowed on this branch.
+- Full chain required: self-review → adversarial → expert → final.
+
+## What NOT to do
+- Skip the adversarial review step
+- Claim merge-ready without all 3 checks passing
+- Force-push master
+
+## Final reply format
+- Review file path
+- BLOCKER/MAJOR count
+- Merge-ready verdict (yes/no + reasons)
+- Comment URL if posted
+```
+
+### Triage task
+```markdown
+## Mission
+Triage 10 open issues in the backlog — categorize, prioritize, identify quick wins.
+
+## Setup
+1. AGENTS.md auto-loaded
+2. Read: `~/.openclaw/skills/triage-sweep/SKILL.md`
+
+## Skills available to you
+- triage-sweep: `~/.openclaw/skills/triage-sweep/SKILL.md`
+- bug-intake: `~/.openclaw/skills/bug-intake/SKILL.md`
+
+## Task
+Process issues #100-#110. For each: read, categorize (bug/feature/question), assess severity, tag.
+
+## Hard rules
+- DO NOT spawn sub-chains.
+- DO NOT close issues without explicit user approval.
+- Read the full issue + comments before categorizing.
+
+## What NOT to do
+- Categorize from title alone
+- Close issues
+- Start implementing fixes (just triage)
+
+## Final reply format
+| Issue | Category | Severity | Quick win? | Notes |
+|---|---|---|---|---|
+```
+
+## What NOT to do (meta)
+- Spawn without reading this template first
+- Omit "What NOT to do" section (it prevents the most common failures)
+- Use generic briefs ("fix this issue") without specific commands/paths
+- Forget `runTimeoutSeconds` on the spawn call
diff --git a/docs/agents/TDD.md b/docs/agents/TDD.md
@@ -0,0 +1,38 @@
+# TDD — Mandatory Cycle
+
+You DO NOT write production code without a failing test first. This is non-negotiable.
+
+## The cycle
+
+1. **Write a test that demonstrates the bug or the new behavior. Commit it. CI must FAIL on this commit** — that's the proof the test gates the change.
+2. **Write the smallest production code that makes the test pass. Commit it. CI must GREEN.**
+3. (Optional) **Refactor for clarity, keeping CI green.**
+
+## Red commit quality bar
+
+- MUST compile/build successfully (no missing imports, no undefined symbols).
+- MUST run the test to completion (not crash before reaching assertions).
+- MUST fail on an **assertion** ("expected X, got Y") — NOT a build/import error.
+- If the function doesn't exist yet, add a minimal stub (return zero/nil/empty) so the test executes and fails on the assertion.
+- A compile error is NOT a valid red commit — it proves nothing about behavior gating.
+
+PR commit history must show: red commit → green commit. Reviewers verify this; the merge-gate (axis 4) checks it programmatically.
+
+## Exemptions (require explicit justification in PR body)
+
+- **Pure refactors**: existing tests MUST remain byte-unchanged (renames OK, behavior changes NOT) AND green. PR body must cite: "tests/ files diff: no changes" OR per-altered-test justification.
+- **Config changes**: existing tests MUST stay green AND unaltered. PR body must cite: "no test files modified" + "CI green without test edits."
+- **Net-new UI surfaces** (no prior assertions to break): test must land in the SAME PR but doesn't need to be the FIRST commit. Bug fixes on EXISTING UI still require red-then-green (E2E-DOM-grep tests are valid).
+- **Pure docs / pure comments**: no test required. Kent Beck gate still runs and rubber-stamps with "no behavior change" justification.
+
+## Rationale
+
+Tests written after the fact are advocacy, not validation. A test that doesn't fail when reverted is not a test — it's a tautology. TDD forces the API to be testable; if you can't write the failing test, the design is wrong, fix the design first.
+
+## What blocks merge
+
+- No red commit on the branch (when not exempt).
+- Test commit doesn't actually fail when reverted (Kent Beck verifies).
+- Tests added in same commit as fix (no red→green visible).
+- Test mirrors the implementation rather than asserting behavior (tautology).
+- Refactor PR with altered test files lacking explicit justification.