agentleFS
mariomilemariomile/builder-os/skills/delivery-discipline/SKILL.md

delivery-discipline

Skill2 starsChanged 50 days agoMITView on GitHub

Plans and runs a build: tracer-bullet slices and tickets, a plan accepted before code, red-green per criterion, fresh-context review, CI, a recorded demo. Use when breaking a spec into work or tickets, implementing, reviewing, or recording a demo.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

Delivery Discipline

Phase 5 turns a spec into working, tested, instrumented software and proves it: a plan a person accepts before any code, then a captured execution record the gate judges against the criteria, the change and the plan.

Mode. Standalone decomposition produces the plan (step 3) from the supplied spec and stops there. A standalone implementation plans first and waits for acceptance unless the request already authorized going straight to code; a standalone review applies the two axes and the severity scale of step 5. The lifecycle runs every step and gate 5. Both per operating modes.

Read the build method for Verify, review grading, run capture and status claims. Two modes also run alone, each with its procedure and marker: tickets (tickets, to-tickets by name) and demo, a video of a feature from a passing end-to-end test (feature demo). Load tracking-standards for instrumentation checks and gate-checks when completing a lifecycle build.

Procedure

  1. Read 04-spec.md, DESIGN.md, TECH.md. The build uses the spec's ## Stack and ## Architecture, and the tokens and kit in DESIGN.md → Visual direction, applied per the interface details. A layer the work needs that is still open, or a structural addition found later (a framework, a database, a hosted service, a paid API, a runtime), pauses the slice for a system-design (stack) card to the person. Utility libraries are listed in the review with their reason. Done when the spec exists and every layer the work touches is decided.
  2. Record the test baseline before any code: run TECH.md → Verify through run-check and note passes, failures and duration. A suite already red: list each failure under ## Pre-existing failures and in TECH.md → Known failing; gate 5.2 then compares the final run against this baseline. An empty Verify gets filled first; several commands get wrapped in one target; no suite means slice one creates it. What the baseline finds missing (no guardrail, no production) goes into the plan as slice zero (step 3). Work on the branch the plan names; a slow suite uses TECH.md → Test (fast) per slice (where the work lives). Done when the baseline capture exists and every failure in it is listed.
  3. Write the plan, reading only: spec, TECH.md, codebase, in the host's read-only planning mode where one exists; the baseline writes only evidence files. The plan holds the seams (each module this work creates or changes, its interface, what it hides, where its tests sit, per the build method), with the central module designed twice; slices with files, criteria and blocking edges, per the slice rules and tickets (expand–contract for a wide refactor); slice zero when the baseline found them missing: the cheapest guardrail running Verify with the automatic quality checks per Guardrails (gates 5.8, 5.10; where the CI belongs to someone else, the plan asks them), and production online behind a door with a preview per change per release-ops (production) (gate 5.16); the critical path; risks with mitigations; rejected alternatives with why each lost; a planned test for every numbered criterion. Slices are tracer bullets, each end to end, sized to one fresh session. Open it with **In plain words:**: what gets built, in what order, what the person can try after each slice, the riskiest step, and one line per seam a non-engineer can follow. Done when an engineer new to this conversation could build from it without asking.
  4. Get the plan accepted. Present **In plain words:** first. Quiz the person on the slices per tickets, section 3, until they approve the breakdown; then the riskiest step and what was rejected. Record **Accepted:** {who} · {ISO timestamp} from the person's own words, or quote an earlier standing instruction that named the build, with its date. Code starts after that line. Publish one ticket per slice per tickets, section 4, and name where under **Tickets:**. Done when the plan carries the person's acceptance and the tickets exist.
  5. Run the loop per slice, in order:

    1. Write the test first from the criterion, by number, at a seam the plan names; a test that reaches into internals is rewritten at the seam. An untestable criterion returns to phase 4.
    2. Watch it fail.
    3. Write the least code that passes it.
    4. Refactor with the test green.
    5. Verify the slice's instrumentation fires in a real environment with the tracking plan's properties.
    6. Review on two axes, tagging each finding standards (good code?) or spec conformance (the specified thing?): behavior against each criterion the slice claims, including phase 4's enumerated states, and the diff against the plan. The review runs in a fresh context holding spec, plan and diff and none of the build conversation; where the host cannot delegate, reread the diff from the start as someone else's. Important findings, per the severity scale (a threat-model mitigation violated counts too), are fixed now; list at most five nits and count the rest. A recurring finding becomes a check or a TECH.md convention (Guardrails).

    A bug found on the way runs bug-diagnosis. Fix the code, keep the test: a test changes only when it encodes behavior the spec does not require, as its own visible step citing the spec line. Done when Verify, captured after the slice's last change, is green on every criterion the slice owns and no important finding is open.

  6. Keep the plan true. A deviation (an unnamed file, a split slice, a risk that turned real) updates the plan in the same change, with the reason. Done when the plan describes the diff as it is.
  7. Check scope creep (gate 5.4): the diff against the phase 4 out-of-scope list, item by item. Anything built from it is removed, or promoted deliberately as a logged, visible override. Done when every out-of-scope item has a verdict.
  8. Verify instrumentation end to end (gate 5.3): per tracking-plan event, trigger the action, confirm arrival with its properties at the destination, record the evidence tagged by source. Done when every event in the tracking plan has its evidence.
  9. Look at what was built (gates 5.9, 5.12). Capture the six states of the primary flow (only empty and error on the change track) at the widest and the narrowest width the ICP uses, with ui.capture, and compare each with the chosen version and the tokens. A difference is fixed, or recorded in DESIGN.md with its reason. Then a craft critique from a fresh context (a separate agent given only DESIGN.md, the voice, the captures and the reference screens; inline, a person who did not build it) against the interface details, on the eight aspects of gate 5.12; each finding is fixed or recorded. Each message in DESIGN.md → Messages is sent to a test inbox or phone and captured under **Messages received:**. With no interface, **Interface review:** not applicable, {reason}. On the change track, steps 8 to 10c run only for what 04-spec.md → **Touches:** calls in (gate 5, Change track). Done when ## Interface review has an image or route per state and width, and ## Craft critique every aspect with what happened.
  10. Check security and speed (gates 5.13, 5.14). A fresh context given the diff, the threat model and TECH.md reviews the five areas of gate 5.13; each finding is fixed or recorded. Then measure every budget in the spec's quality bar on the built product through run-check (the primary action at p95; with an interface, the page load at the narrowest width), and fix what is over. Done when ## Security review has every area with what happened, and ## Performance has every budget measured and met. 10b. Put it in the person's hands (gate 5.17) per production setup step 7, recorded under ## Tried with their words quoted. Done when the person has tried it and every finding is fixed or recorded. 10c. Show it working (gate 5.15, feature demo) on the build the person's findings left, so the recording shows what ships. Done when ## Demo has its test, its passing run and its recording.
  11. Write, gate, and leave the code legible. Complete .builderos/initiatives/{initiative}/05-build-plan.md per the build-plan template, headings, bold labels and tables exact, with every status claim backed by a run-check capture from the final change. Run gate 5 and record it (scripts/bos.mjs record 5 --judged "{judge-id}=pass|fail,..." where commands run). Update TECH.md: Map (gate 5.11 checks every path), Verify, conventions, traps, recurring findings, and each must-always-hold rule with its deterministic check. Move the initiative to phase 6 in ROADMAP.md. Then run retro on the build sessions and list the changes under **Environment:**; a finding about AGENTS.md or CLAUDE.md runs agents-md. Done when gate 5 is recorded, TECH.md matches the code, and the retro's changes are listed.

A planning-only run produces the accepted plan and leaves gate 5 for later.

Watch for

DoInstead of
Capture the final run and have coverage judgedPasting green output
Test the criterion where its surface lives, or return it to phase 4Mapping it to "no test, reasoned exception"
Plan reading only, get acceptance, then buildCode before the **Accepted:** line

Capabilities

CapabilityUsed forFloor if absent
repo.readCodebase, tests, patternsPhase 5 needs it; say so and stop at the plan's questions
shell.execVerify through run-checkDeliver the plan, say what must run; gate 5.2 waits for a capture
analytics.events / analytics.queryEvents arriving with propertiesEmission log or code path, tagged weaker
ui.captureScreenshots of each state of the built interface (step 9)The person opens the routes and says what they see
subagent.dispatchThe fresh-context review, the loopRun it inline, slice by slice
files.read / files.writeArtifacts, stateRequired

Output Contract

## BUILD VERIFIED with the accepted plan, the criterion-to-test mapping, the test output, the instrumentation evidence, the scope-creep result, the interface review, the craft critique, the demo, the security review, the performance measured, the production check, who tried it and the gate result.

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.