mirror of https://github.com/Kpa-clawbot/meshcore-analyzer.git synced 2026-07-02 16:31:40 +00:00

Files

T

Kpa-clawbot df28efaed9 docs(agents): contributor onboarding pack for AI-driven workflows (#1734 )

## 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>

2026-06-19 11:37:10 -07:00

2.5 KiB

Raw Blame History

TDD.md — Test-Driven Development is mandatory

You DO NOT write production code without a failing test first. This is non-negotiable.

The cycle

Red. 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.
Green. Write the smallest production code that makes the test pass. Commit it. CI must go GREEN.
Refactor. (Optional.) Improve 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 skill 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): a 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. The Kent-Beck persona 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 persona verifies).
Tests added in the same commit as the fix (no red→green visible).
Test mirrors the implementation rather than asserting behavior (tautology).
Refactor PR with altered test files lacking explicit justification.

2.5 KiB Raw Blame History