agentleFS
wxxb789wxxb789/hoa/skills/gdd/SKILL.md

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

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
  1. Distinctive:

    Not for: one-line fixes, exploratory poking with no acceptance criteria, or work whose result no machine can check.

    line 34
  2. Very specific:

    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 …

    line 76
  3. Very specific:

    Read references/transport.md before selecting or dispatching a launcher: it defines both routes, model/thinking mapping, artifact polling, …

    line 117

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 → reset

Both 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

PhaseProducesRules that must not be missedDetail
0 contracta dispatchable goal contractall 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 hopereferences/phases/00-contract.md
1 branch + dispatchbaseline snapshot and one implementation runbranch 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 templatereferences/phases/01-branch-dispatch.md
2 verifygate evidence and a clause→test mapexit 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 incrementreferences/phases/02-verify.md
3 simplify → applyaccepted fixesreport only, never silent apply; name rejected numbers in the apply prompt; a dead-code finding needs mechanical evidence; re-derive changed counts from the treereferences/phases/03-simplify-apply.md
4 review → fixper-finding fixescommit stage output before the next stage; reproduce every finding; classify regression vs pre-existing; a third same-class dispatch changes the mechanismreferences/phases/04-review-fix.md
5 gates → commit → PRa sealed increment and its PRoverlapping_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 treereferences/phases/05-gates-pr.md
6 mergea 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 verdictreferences/phases/06-merge.md
7 ledgerone ledger row per stagethe operator writes it, never the agent; resume with show + git status + git log origin/main..HEAD; mid-flight status comes from live statereferences/phases/07-ledger.md
8 reseta fresh base for the next goalfresh run, never a resumed session; delete merged branches; fork from freshly fetched origin/main; report the base SHAreferences/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.md is 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

VariableResolvesDefault
GDD_STATE_FILEledger path${XDG_STATE_HOME:-$HOME/.local/state}/gdd/ledger.tsv
GDD_TASK_ROOTtask/state root${XDG_STATE_HOME:-$HOME/.local/state}/gdd/tasks
GDD_RUN_ROOTlauncher run root${XDG_STATE_HOME:-$HOME/.local/state}/gdd/runs
GDD_LAUNCHERexplicit launcher selectionbundled scripts/adapters/omp-run.py; opt in to native Paseo with scripts/adapters/paseo-run.py
GDD_TEMPLATESstage-template rootthe bundled references/stage-templates
GDD_GOAL_GLOBgoal-contract globdocs/goals/*<goal>*.md
round capsimplement / simplify / review run at most 2x — enforced by gdd.py stage, override with --over-budgetscripts/gdd.py
GDD_WORKTREE_SCOPEworktree-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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.