mirror of
https://github.com/Kpa-clawbot/meshcore-analyzer.git
synced 2026-07-28 01:31:08 +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>
1.9 KiB
1.9 KiB
name, description, triggers
| name | description | triggers | |||||
|---|---|---|---|---|---|---|---|
| debug-repro | Reproduce bugs locally against fixture/staging before fixing. Ensures repro commands are concrete and tested. |
|
debug-repro — Local Bug Reproduction
Purpose
Reproduce reported bugs LOCALLY against fixture data, synthesized data, or live read-only staging before attempting any fix. Eliminates guess-and-check CI cycles.
Scope
- Local reproduction using project fixtures (
test-fixtures/in repo) - SQLite queries against fixture/staging DBs
- curl against locally-running server
- Read-only SSH to staging (connection details in MEMORY.md)
Process
- Identify the EXACT failing assertion/behavior
- Find the fixture/DB/state the test uses
- Write the literal repro command (sqlite3/curl/node)
- Run it locally — observe actual error
- Only THEN form a hypothesis
- Fix → re-run repro → confirm fixed → push
Hard rules
- Every task brief for a debugging subagent MUST include the literal repro command
- Never push a fix without local repro confirming the fix works
- Read-only on staging — no writes without explicit user permission
- Reference connection details from MEMORY.md, not hardcoded here
What NOT to do
- Push hypothesis to CI without local repro ("push-and-pray")
- Read code and guess without running anything
- Skip fixture identification ("just use the default DB")
- Claim "can't reproduce" without trying the exact input the failing test uses
Output format
## Reproduction
- Command: `<exact command>`
- Result: <what happened>
- Root cause: <1 sentence>
## Fix
- File: <path>
- Change: <description>
- Verification: `<re-run command>` → <expected output>
History
This skill exists because of the 6-PR map-markers cascade (PRs #956→#961). See LESSONS.md "Sequential guess-and-check via CI."