{"id":51670901,"url":"https://github.com/scottconverse/coder-tdd-qa","last_synced_at":"2026-07-15T00:03:44.356Z","repository":{"id":368906345,"uuid":"1287442275","full_name":"scottconverse/coder-tdd-qa","owner":"scottconverse","description":"Portable TDD/QA standards skill for AI coding agents (Claude Code, Codex, any AGENTS.md) — watch-it-fail-first TDD, anti-fabrication evidence rules, falsification pass, size-gated release checklist","archived":false,"fork":false,"pushed_at":"2026-07-02T18:15:59.000Z","size":51,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T19:27:11.302Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scottconverse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-02T17:33:32.000Z","updated_at":"2026-07-02T18:16:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scottconverse/coder-tdd-qa","commit_stats":null,"previous_names":["scottconverse/coder-tdd-qa"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/scottconverse/coder-tdd-qa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fcoder-tdd-qa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fcoder-tdd-qa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fcoder-tdd-qa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fcoder-tdd-qa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scottconverse","download_url":"https://codeload.github.com/scottconverse/coder-tdd-qa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottconverse%2Fcoder-tdd-qa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35483861,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-14T02:00:06.603Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-15T00:03:43.610Z","updated_at":"2026-07-15T00:03:44.346Z","avatar_url":"https://github.com/scottconverse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# coder-tdd-qa\n\nA portable rulebook for AI coding agents: test-driven development, honest\nverification, and a size-gated release checklist — plain markdown that works in\nClaude Code, Codex, or any agent that reads instructions. Ships in two forms:\n[SKILL.md](SKILL.md) (full standards) and [SKILL-LITE.md](SKILL-LITE.md) (the\ncondensed contract for small tasks, with a tripwire back to full).\n\n**Landing page:** https://scottconverse.github.io/coder-tdd-qa/\n\n## What this is (plain English)\n\nAI coding assistants have a bad habit: they write code, say \"done, it works,\" and\nmove on — without ever proving it. Sometimes the tests they wrote don't actually\ntest anything. Sometimes they summarize a test run in a way that hides failures.\n\nThis project is a set of written rules you hand to your AI assistant that closes\nthose loopholes. The core idea is simple: **a test only counts if the assistant\nwatched it fail first.** A test that has never failed might be testing nothing at\nall. So the rules force the assistant to write the test, watch it fail, then write\nthe code that makes it pass — and to show you the raw, uneditable proof at each\nstep. Before calling anything done, the assistant must also try to *break* its own\nwork and tell you what happened.\n\nYou don't need to understand the rules to benefit from them. Install the file,\nand your assistant follows them.\n\n## Install (technical)\n\n**Claude Code** — copy [SKILL.md](SKILL.md) into a skills directory:\n\n```\n# personal (all projects)\n~/.claude/skills/coder-tdd-qa/SKILL.md\n\n# or per-project\n\u003crepo\u003e/.claude/skills/coder-tdd-qa/SKILL.md\n```\n\n**Codex / other agents** — paste everything below the YAML frontmatter of\n[SKILL.md](SKILL.md) into the repo's `AGENTS.md` (or the agent's system prompt).\nThe body is harness-agnostic by construction: no tool names, no skill-loader\nfeatures, no file-layout assumptions.\n\n**Lite** — for quick fixes, small scripts, or a small project's `AGENTS.md`,\ninstall [SKILL-LITE.md](SKILL-LITE.md) the same way (as\n`~/.claude/skills/coder-tdd-qa-lite/SKILL.md` in Claude Code). Same\nnon-negotiable rules, Evidence Format, and TDD loop — enforced identical to the\nfull document by `check_sync.py` in CI — minus workflow and release ceremony.\nIts escalation tripwire sends the agent back to the full standards when a change\noutgrows lite: more than one file or ~50 lines, any public interface, untrusted\ninput/auth/secrets/deserialization, or anything being pushed or released. The\nhuman picks the tier; the agent only escalates, never downgrades.\n\n## What's inside\n\n| Section | What it does |\n|---|---|\n| Hard Rules | 9 rules; 1–5 non-negotiable (read-before-write, baseline-before-change, run-before-done, TDD, no secrets), 6–9 overridable with acknowledgment (challenge bad specs, checkpoint before risk, stay in scope, no wasteful operations) |\n| Evidence Format | Anti-fabrication: exact command + verbatim counts line + all failures in full; only per-test PASS spam may be collapsed |\n| The TDD Loop | Red → watch it fail on the assertion → minimal green → refactor → widen against the baseline. Bug fixes start with a failing reproduction test |\n| Roles | Engineer / UI designer / QA lenses, applied only where the task involves them |\n| Workflow | Numbered before-building checklist, build discipline (stdlib-first, doc sync), communication rules, task-type-switch rule |\n| Verification Report | Scaled report: files read, baseline vs. end state, TDD evidence, a falsification pass (try to break your own change), commit evidence, a security checklist with per-item answers |\n| Release Gate | Push = release event. Three tiers so a weekend utility doesn't get flagship ceremony |\n\n## Design principles\n\n- **Written for the weakest agent that might read it.** The document assumes the\n  host harness provides no other guidance — a bare local model gets the same\n  scaffolding a flagship one does. Rules come with reporting hooks (you must\n  *list* what you read) because a rule a model can't be caught violating is a\n  wish. Nothing is redundant by accident.\n- **Tests must be real, not merely present.** \"Write a test\" is a rule an agent can\n  satisfy with a test that asserts nothing. Watching it fail on its assertion is\n  the only cheap guarantee it's wired to the behavior. That's why TDD is the core,\n  not an add-on.\n- **Evidence, not assertions.** Verbatim counts and complete failures are an\n  anti-fraud forcing function — summarized output is where fake greens hide.\n- **Falsify before sign-off.** A self-report only surfaces the gaps the\n  self-reporter looks for. The rules require an adversarial pass against the\n  agent's own change.\n- **Baseline first.** Red→green is meaningless if the suite was already red when\n  the agent arrived. Pre-existing failures are recorded and tracked separately.\n- **Ceremony scales with stakes.** Every public repo gets a secrets scan and\n  hygiene files; only published packages get packaging checks; only flagship\n  projects get manuals and landing pages, and only when asked.\n- **Each rule stated once.** No duplication between sections — later sections\n  reference, never restate. The one sanctioned duplication — lite's copy of the\n  core — is machine-enforced: `check_sync.py` fails CI if the copies drift, if a\n  required block goes missing, if a new rule is added without deciding its lite\n  fate, or if lite's safety tripwire is deleted.\n\n## Requirements\n\nNone. It's a markdown file. Any agent that reads instructions can use it.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottconverse%2Fcoder-tdd-qa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscottconverse%2Fcoder-tdd-qa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottconverse%2Fcoder-tdd-qa/lists"}