gdd
Skill3 starsChanged 53 days agoMITView on GitHub
Land a written, machine-checkable increment in a repo end to end — one goal contract, one fresh authoring-agent run per stage, gates the operator re-runs, a scripted merge gate, and a durable stage ledger so a later session can resume in three commands. Use when an increment is delegated end to end, including the merge. Do not use for one-line fixes, exploration with no acceptance criteria, or work no machine can check (that is a conversation, not a delivery).
3 other projects use a version of this.
Adopted by
Most recently taken up by
- mementomori-co/maker-masterytheir own version, first seen Oct 25, 2026
- skealeye/ClaudeSkillstheir own version, first seen Oct 14, 2026
- CodePhobiia/claude-roblox-game-studiotheir own version, first seen Apr 16, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- CodePhobiia/claude-roblox-game-studio★ 9same name
- mementomori-co/maker-mastery★ 2same name
- skealeye/ClaudeSkills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-harness-settings-paritySkill
- agent-operating-contract-evolutionSkill
- ai-coding-agent-delegationSkill
- arch-improvement-planSkill
- contract-bound-deliverablesSkill
- cross-agent-repair-routingSkill
- define-goalSkill
- delegated-work-acceptanceSkill
- design-an-interfaceSkill
- design-mdSkill
- discord-rich-messageSkill
- dotnet-repo-workflowSkill
- evidence-backed-analytical-writingSkill
- evidence-boundary-disciplineSkill
- find-nearbySkill
- generated-runtime-repairsSkill
- ghc-searchSkill
- git-auto-sync-pipelinesSkill
- github-code-reviewSkill
- github-repo-managementSkill
- grounded-citationsSkill
- harness-engineeringSkill
- hermes-context-file-loadingSkill
- hermes-modelsSkill
- hermes-updatesSkill
- hoa-introspect-distillSkill
- hoa-introspectSkill
- hoa-skill-reviewSkill
- hoa-skill-workSkill
- html-artifactSkill
- jupyter-live-kernelSkill
- kanban-workflowsSkill
- m365-copilot-cdpSkill
- measurement-campaign-evidenceSkill
- microsoft-officeSkill
- notes-to-prdSkill
- ocr-and-documentsSkill
- official-document-verificationSkill
- omp-headless-orchestrationSkill
- ops-claim-verificationSkill
- package-release-verificationSkill
- plan-to-issuesSkill
- project-phase-closeoutSkill
- report-claim-auditSkill
- research-stream-consolidationSkill
- review-revision-candidatesSkill
- rss-feedsSkill
- skill-library-curationSkill
- skill-porting-and-publishingSkill
- spec-convergenceSkill
- structural-validity-gatesSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- teams-cdpSkill
- tmux-agent-controlSkill
- whisperSkill
- writing-plansSkill
- writingSkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
Not for: one-line fixes, exploratory poking with no acceptance criteria, or work whose result no machine can check.
- Very specific: line 76
Read references/run-failure-modes.md before adding a selftest case or believing a run's report of itself: a test can kill the process under …
- Very specific: line 117
Read references/transport.md before selecting or dispatching a launcher: it defines both routes, model/thinking mapping, artifact polling, …
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Goal-driven delivery
One written increment (a goal), authored by a coding agent, verified and landed by the operator, with the loop running end to end and no per-step approval. Done is merged and the next goal branched off the merged head — an open PR is not done.
When to Use
- "Start the next goal", "run the goal-driven flow", "finish this the usual way".
- 中文同义说法同样触发:
开始下一个 goal、推进 goal driven 流程、按老流程把这个做完。 - Any multi-hour repo increment: a feature, a research-feasibility study, a migration, a docs rewrite — anything with a written completion contract and machine-checkable gates.
- A repo where the operator delegates end to end, including the merge.
Not for: one-line fixes, exploratory poking with no acceptance criteria, or work whose result no machine can check.
Stage order — fixed, no skipping
contract → implement → verify → simplify-report → apply → code-review-report → fix
→ gates → PR → babysit → merge → resetBoth two-phase steps are mandatory: an unapplied report or an unfixed review does not close a stage.
Caps: implement 2 recovery attempts, simplify 2 rounds, review→fix 2 rounds. On a third round,
stop and report — do not burn budget in silence.
Roles — authoring vs inspection
- The agent authors: product code, tests, docs, evidence records, applying simplify/review fixes, re-running measurements. Dispatch it; never type it yourself, not even a two-line fix.
- The operator inspects: reading diffs, running gates read-only, grading findings, deciding to merge, and the mechanical git work (commit, push, PR, merge, cleanup).
- Why: a hand-edit from the wrong surface is an unaccounted write — the diff can no longer be attributed to the agent that owns the code, and the next review cannot reason about it.
Phase table — route, then read the detail
| Phase | Produces | Rules that must not be missed | Detail |
| 0 contract | a dispatchable goal contract | all six clauses: observable pass condition, judging artifact, failure control, out of scope, evidence plan, mergeable alone; one goal ≈ one run ≈ one PR; fix the contract, never dispatch and hope | references/phases/00-contract.md |
| 1 branch + dispatch | baseline snapshot and one implementation run | branch from origin/main and report the base SHA; report pre-existing dirty paths; gdd.py stage renders prompt, run name and ledger row from one template | references/phases/01-branch-dispatch.md |
| 2 verify | gate evidence and a clause→test map | exit 0 means the process ended, not the phase finished; re-run gates on the FINAL tree; a proof test must fail when the feature is deleted; a weak proof test is its own increment | references/phases/02-verify.md |
| 3 simplify → apply | accepted fixes | report only, never silent apply; name rejected numbers in the apply prompt; a dead-code finding needs mechanical evidence; re-derive changed counts from the tree | references/phases/03-simplify-apply.md |
| 4 review → fix | per-finding fixes | commit stage output before the next stage; reproduce every finding; classify regression vs pre-existing; a third same-class dispatch changes the mechanism | references/phases/04-review-fix.md |
| 5 gates → commit → PR | a sealed increment and its PR | overlapping_paths stops the commit; worktree-scope.py verify after committing; prove the branch is not behind main; every number is re-derived on the final tree | references/phases/05-gates-pr.md |
| 6 merge | a merge verdict, then the next branch | --verified-head is the SHA the gates ran on; bot marker status: completed with commit_sha matching the SAME head; no merge without the script's verdict | references/phases/06-merge.md |
| 7 ledger | one ledger row per stage | the operator writes it, never the agent; resume with show + git status + git log origin/main..HEAD; mid-flight status comes from live state | references/phases/07-ledger.md |
| 8 reset | a fresh base for the next goal | fresh run, never a resumed session; delete merged branches; fork from freshly fetched origin/main; report the base SHA | references/phases/07-ledger.md |
Before you dispatch, and before you believe a run
Two references decide most failures. Read
references/cross-platform-increments.md before writing a
verification plan for a repo that ships on more than one OS — a green local run is not evidence there.
Read references/run-failure-modes.md before adding a selftest case or
believing a run's report of itself: a test can kill the process under test, a stubbed test can pass for
the wrong reason, and an exit code can disagree with the artifact it produced.
Playbooks
Stage detail lives in references/phases/*.md (mapped in the Phase table above). Read the phase file
matching the current stage directly — do not create per-phase skills.
Stop conditions — when to stop and ask
- Red line touched: destructive/irreversible action, production, credentials, public release, or anything affecting a third party. Report impact + rollback + the exact action, then wait.
- Scope drift or write overlap: a non-empty
overlapping_paths, sealed-scope drift after commit, or work outside the contract stops the loop; the operator decides which writer owns the path. - Two attempts in one stage with no convergence (
BLOCKED:no_progress): stop, keep the evidence, present the choice (different model / narrower contract / abandon). - Unfair evidence: a "faster/cheaper" claim that does not survive
references/evidence-fairness.mdis not accepted as an outcome. - The contract itself is wrong (ambiguous or contradictory requirements discovered mid-flight): stop, amend it, then continue. Never ask an agent to satisfy an impossible clause.
Configuration
| Variable | Resolves | Default |
GDD_STATE_FILE | ledger path | ${XDG_STATE_HOME:-$HOME/.local/state}/gdd/ledger.tsv |
GDD_TASK_ROOT | task/state root | ${XDG_STATE_HOME:-$HOME/.local/state}/gdd/tasks |
GDD_RUN_ROOT | launcher run root | ${XDG_STATE_HOME:-$HOME/.local/state}/gdd/runs |
GDD_LAUNCHER | explicit launcher selection | bundled scripts/adapters/omp-run.py; opt in to native Paseo with scripts/adapters/paseo-run.py |
GDD_TEMPLATES | stage-template root | the bundled references/stage-templates |
GDD_GOAL_GLOB | goal-contract glob | docs/goals/*<goal>*.md |
| round caps | implement / simplify / review run at most 2x — enforced by gdd.py stage, override with --over-budget | scripts/gdd.py |
GDD_WORKTREE_SCOPE | worktree-scope.py path | ../delegated-work-acceptance/scripts/worktree-scope.py |
Resolution order and the config-file path are defined once in
skill-porting-and-publishing § Configuration.
gdd.py implements it through the vendored scripts/skill_config.py; the config-file keys are the
six names in the table. Nothing about one install lives in the protocol: a profile may point at its own
files, but no path is inlined.
Read references/transport.md before selecting or dispatching a launcher:
it defines both routes, model/thinking mapping, artifact polling, and platform-specific evidence.
Native stages are Paseo agents and require a reachable daemon; never substitute routes by reachability.
Missing state/agents and an unreachable daemon are unknown, never success; headless evidence is not native evidence.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

