agentleFS
nhattrung0911nhattrung0911/shipwright/skills/disciplined-delivery/SKILL.md

disciplined-delivery

Skill0 starsChanged 5 months agoMITView on GitHub

Use at the start of and throughout any non-trivial build — web app, API, LLM app, ML/data pipeline, CLI, or library. Triggers on "build/create/implement X", new project or feature, multi-step work, or before claiming work complete. Enforces plan-first, phase/slice gating, per-slice testing, and evidence-based "done". Stack- and agent-agnostic (Claude Code, Codex, Gemini CLI).

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write acceptance criteria in testable form: "WHEN [trigger], system SHALL [observable behavior]." Each becomes a check later.

    line 27
  2. Distinctive:

    If pressured to "skip planning / just ship it": do NOT silently comply, and do NOT refuse outright.

    line 37
  3. Distinctive:

    Only now → next slice.

    line 47
  4. Distinctive:

    Do NOT report done until ALL hold, each with evidence attached:

    line 50

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “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

Disciplined Delivery

Overview

A universal engine for shipping any project correctly without skipping steps. Distilled from canonical 50k+ star engineering repos (see Essence Sources).

Two core laws:

  1. No phase skipped. Frame → Plan → Slice → Verify, in order. Violating the letter violates the spirit — "I'll just start coding" is a skip.
  2. "Done" requires evidence, never assertion. A claim of complete must carry the command output / test result / eval score that proves it. "Should work" is not done.

Announce at start: "Using disciplined-delivery: framing and planning before building."

When to Use / Not

  • Use: any new project, feature, or multi-step change; before saying "done/fixed/complete".
  • Skip: one-line edits, trivial throwaway scripts, pure questions.

The Loop

Phase 0 — Frame (before any code)

  • Capture: who/what/why, scale assumptions (load, data size, users), hard constraints.
  • Write acceptance criteria in testable form: "WHEN [trigger], system SHALL [observable behavior]." Each becomes a check later.
  • Clarify gate: kill ambiguity now. If two readings exist, ask — don't guess. (Unattended/CI run that can't ask: record the assumption explicitly in writing, then proceed.)
  • State trade-offs explicitly (consistency vs availability, speed vs cost). No silent defaults.

Phase 1 — Plan (break into slices)

  • Decompose into vertical slices, each independently testable and shippable, ordered by dependency.
  • A slice cuts end-to-end (data → logic → interface), not by technical layer.
  • Emit a written plan artifact (the spec is the source of truth; the plan references it).
  • Big system = split into sub-plans, one per subsystem.

If pressured to "skip planning / just ship it": do NOT silently comply, and do NOT refuse outright. Flex the size of the plan, never its existence. Respond, then produce inline before coding:

"Keeping it lightweight — 3 lines: (1) what done looks like, (2) the slices, (3) the check per slice — then I build."

The plan's existence is non-negotiable; only its length flexes under pressure.

Phase 2 — Build each slice (loop per slice)

Repeat for every slice, fully, before the next:

  1. RED — write the failing check first (test / eval / fixture). Run it and paste the failure output before writing any code.
  2. GREEN — minimal code to pass. No speculative extras (YAGNI).
  3. VERIFY — run the slice's acceptance checks; confirm pass with output.
  4. Only now → next slice.

Phase 3 — Definition of Done gate (before reporting complete)

Do NOT report done until ALL hold, each with evidence attached:

  • Every acceptance criterion has a passing check
  • Tests/evals run fresh and green (paste the result)
  • Errors handled at boundaries; inputs validated; no swallowed failures
  • Observable: logs/metrics/health where the project type needs them
  • Security gate: authz, input sanitization, secrets out of source — depth via securing-applications skill, or an equivalent OWASP Top 10:2025 checklist if that skill is absent

Mandatory final step — Grader ≠ Doer (do not skip): the agent that built it cannot be the sole judge (same misread that wrote the bug writes the test). Independent check:

  • Multi-agent platform → a fresh sub-agent/session sees ONLY the diff + acceptance criteria, never the build reasoning, and rules PASS/FAIL per criterion.
  • Single-agent platform → re-read ONLY the criteria + final diff (not your earlier reasoning).

The grader MUST emit a per-criterion table: criterion | PASS/FAIL | exact evidence string (the command output / test line / file:line that proves it). Faking then requires fabricating output, not just asserting. Report done only when every row is PASS with real evidence quoted.

"Tested" by project type (universality)

What clears the VERIFY gate differs — pick the row(s) that apply:

Project type"Tested / done" means
Web app / APIunit + integration + 1 e2e happy path; input validation; auth path; status/error contract; a11y basics (contrast, labels, keyboard); performance budget (Core Web Vitals); runs in CI
LLM app (incl. RAG)golden set (input→approved output) regression baseline; eval score ≥ threshold as blocking gate; score correctness, groundedness/faithfulness, format; for RAG: retrieval quality — recall@k, context relevance, hallucination rate vs retrieved context; versioned prompts
ML / data pipelinemetric defined BEFORE building; validate on held-out data; schema + distribution checks on inputs; reproducible from pinned data+seed+config; sliced metrics not just global
Mobile appunit + UI tests; offline/permission/lifecycle states; tested on real device or emulator matrix; store-compliance basics
Infra / IaCplan/dry-run reviewed before apply; idempotent; state isolated per env; secrets managed; destroy-and-recreate tested in non-prod
CLI / libraryunit tests on public API; edge/error cases; example usage runs; exit codes correct
Data migrationreversible; tested on a copy; backup verified restorable before apply

For web, pull the deeper 14-pillar checklist from the shipping-production-websites skill if installed (Claude Code); off-platform, the web row above is the floor.

Anti-False-Done Enforcement

Instruction alone ("don't cheat") barely works — enforcement must be structural. Use the evidence gate and separate grader above. Counter these rationalizations:

RationalizationReality
"Should work / probably fine"Confidence isn't evidence. Run it, paste output.
"Too small to test"Small code breaks. The check takes seconds. No exceptions.
"Linter/build passed"Linter ≠ behavior. A green build proves nothing about correctness.
"I'll test at the end"Per-slice verify is the discipline. End-only testing hides which slice broke.
"I already manually checked"Manual once ≠ repeatable. Encode it as a check.
"I'll just start coding, plan later"Unplanned edits = rework churn. Frame and plan first.

Red flags — STOP, you are about to skip or fake done:

  • Hedging words: "should", "probably", "I think it works"
  • Premature "Done! / Perfect! / All set!" with no command output shown
  • Writing code before the failing check
  • Skipping Frame/Plan because the task "seems clear"

Portability (Claude Code / Codex / Gemini)

This skill uses neutral prose deliberately. Map to your platform:

  • "Failing check" = your test/eval runner.
  • "Fresh-context grader" = a separate agent/sub-agent if supported, else a new clean session reviewing only the diff + criteria.
  • "Delegate verbose work" = use your platform's sub-agent/helper mechanism to keep main context lean.

Companion skills (use if installed)

  • Requirements depth → brainstorming
  • Plan authoring → writing-plans
  • Per-slice TDD → test-driven-development
  • Final evidence gate → verification-before-completion
  • Web specifics → shipping-production-websites
  • Security gate depth → securing-applications (OWASP Top 10:2025)
  • Runtime controls + Day-2 ops/maintenance → operating-production-services (rate limiting, retries, backups, monitoring, on-call)
  • Token economy throughout → token-frugal-engineering

Essence Sources (verified 50k+ stars)

system-design-primer (~300k): scale-estimate + trade-offs + bottlenecks. developer-roadmap (~310k): "done" = data→API→UI→deploy→monitor + tests/security. nodebestpractices (~103k): fail-fast, error handling, observability. clean-code-javascript (~94k): small single-purpose units, DRY, no dead code. generative-ai-for-beginners (~90k) & ML-For-Beginners (~86k): metric-first, reproducibility, eval harness over vibe-check. awesome-scalability (~69k): decouple, cache deliberately, isolate failure.

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.