wtk-lean

Tech Lead's Club - Spec, Lean

Run a decided feature through four moves: PLAN → CHECKS → BUILD → VERIFY. A human reviews the feature shape before checks freeze its obligations; builders choose reversible implementation detail; one fresh Verifier proves the complete feature. There is no task breakdown or component catalogue.

At execution or verification start, read execution metrics; include the assigned stage receipt with session identity, interval and baseline/snapshot counters after its source checks, using the normal handoff format.

Before environment setup or handoff, apply runtime lifecycle to the checkout's application/test services.

For explicit reuse, construction-order or approval requirements, apply construction constraints at Plan, Checks, Build and Verify. At phase boundaries or context recovery, use context handoff.

When implementing a selected image or design, freeze the UI contract before coding and carry its source and evidence requirements through build and independent verification. Use the ui profile for binding interface sources.

At Plan, Checks, Build and Verify, apply project requirements, including for checks-only features. The phase references carry its entry points; profiles never waive inherited requirements.

Core contract

1. Every check is one observable claim with a concrete value and a proof whose exit code settles it.
2. Tests come from the approved checks, never from the implementation. Do not weaken, skip, or

delete a test to pass a gate; a wrong or impossible check stops for user renegotiation.

1. Approved checks.md and Test policy rows are fixed. New Landing, Relations, and Surface

rows may be added when building discovers a door, entity, or route; approved rows are never rewritten. Keep Flow and Impact current when the path changes.

1. The coordinator dispatches one fresh Verifier over <feature base>..HEAD with every check in

the same turn after the feature's last commit. The builder reports and stops; verification is never optional, delayed for another prompt, or self-authored.

1. The declared profile is a floor. Its report names the profile and validate_verification.py must

exit 0. An approved spec authorizes local edits and commits only; push, deploy, and production data changes require explicit authorization.

Profile

AGENTS.md or the feature snapshot declares the profile. The resolver defaults to standard; light, standard, and ui remain valid upstream levels. The profile is a floor, not a preference, and checks.md plus the verification report must name the same value.

## wtk-lean

profile: standard
budget: 150k

An empty input costs a recorded line, not a skipped step. validate_verification.py rejects a profile mismatch and missing sections required by standard or ui. If the declared floor is too thin, ask the user to raise it rather than silently changing the profile.

Artifacts

.specs/
├── STATE.md                    # Decisions log (AD-NNN) + Handoff snapshot
├── LESSONS.md                  # rendered by scripts/lessons.py - never hand-edit
├── lessons.json                # machine-owned
└── features/<feature>/
    ├── plan.md                 # problem, flow, impact, remaining shape, criteria, then audit tables
    ├── checks.md               # claims + proofs, the coverage join, test policy, swept
    └── verification.md         # the Verifier's report

Create each file when its phase produces content. For a change under roughly three files with no one-way door, write only checks.md with an ## Intent paragraph and skip plan.md - one bounded escape, not a sizing matrix.

The plan is the human review boundary. Write the problem, walk the surfaces, write criteria, then record the shape that implements them. File order serves the reviewer: Problem, Flow, Impact, Relations, Surface, Landing, Criteria, Traceability, Out of scope, Assumptions, Observable, and Sources. Flow is the path, Relations the entities and one-way constraints, Surface the route/signature/statuses, Landing the literal irreversible choices and rejected alternatives, and Impact what existing terms or data change. Placement and reversible implementation detail stay in the diff.

checks.md derives proof-backed checks from the plan and joins every enumerated route, entity, status, and door to a check. plan.md, checks.md, and verification.md therefore stay distinct: the first freezes reviewed shape, the second freezes obligations, and the third is the independent evidence. An unresolved architecture choice needs its own ADR/RFC/spike before it can be recorded as a Landing decision.

Phase references

• Plan: human review of EARS criteria, boundary, surfaces, nine implicit dimensions, and the

five shape sections. Ask only genuine decisions; use n/a - <reason> where a dimension does not apply. Full procedure and closure gate: plan.md.

• Checks: derive proof-backed claims, join every enumerated set member, record swept landings,

and close with ## Handoff arithmetic: checks.md.

• Build: after the size gate resolves the execution mechanism, tests come from checks and

implementation decomposition is yours. Keep new Landing, Relations, and Surface rows additive before closing code, then use the scope guardrail and handoff procedure: build.md.

• Verify: in the same turn after the feature's last commit, the coordinator sends one fresh

Verifier over the full range with every check; procedure and report schema: verify.md.

• Memory: decisions, handoff, and lessons live in memory.md.

Scripts

Resolve <skill-dir> as the directory containing this SKILL.md and invoke python3 <skill-dir>/scripts/<name>.py. Project data under .specs/ stays relative to the project root; pass --root when cwd differs. A non-zero exit stops the phase.

The validators own structural detail: validate_plan.py closes the human-reviewed shape, validate_checks.py catches missing proofs, coverage, swept rows, and profile, and validate_verification.py requires evidence, no surviving mutant, no Unproven member, and a non-author Verifier. Run selftest.py only after changing a validator or template. If execution is unavailable, perform the same checks by inspection and report the degraded path.

Execution selection

Before delegated work, follow agent selection for the task-specific proposal, human confirmation, overrides and host limits. Skills supply stage responsibilities; native role files are optional and remain untouched. When a feature needs a persisted route, freeze its confirmed selection:

python3 .agents/skills/wtk-lean/scripts/workflow_route.py \
  --root . --feature <feature-slug> --selection-file <confirmed-selection.json>

The version 2 route records approved stage/model/effort choices and approval evidence scoped to the feature and current checkout. It derives the approved verification profile, keeps Deep Review on demand and the Lean builder sequential. It neither reads nor writes .wtk.toml or native role files. Unchanged retries and resume reuse the accepted selection through the same helper.

Sub-agents and handoff

Estimate the files each slice touches from wc -c / 4, and record the arithmetic under ## Handoff after checks exist and before Build. When the cumulative estimate fits the declared budget (default 150k tokens), one builder owns all whole slices sequentially; do not ask or offer a transfer. When it exceeds the budget, stop before code and ask the user to choose the execution mechanism: sequential whole-slice handoff at the recorded surface boundary, or one builder with accepted compaction/context-loss risk. The coordinator chooses the cut, records the user's mechanism choice, and uses the host's supported handoff mechanism with the accepted stage selection in the current checkout.

Handoffs occur only between slices and only after every proof in the batch is green. The outgoing builder records closed checks, user decisions, and abandoned approaches. The next builder reads the artifact and landed diff, not a narrative. Never split a slice or create a task DAG. The coordinator owns checkpoint synchronization and dispatches the final full-range Verifier in the same turn after the last batch returns green; builders report and stop.

Knowledge chain

Use existing code and conventions, project docs, library docs (Context7 where available), then web search; mark anything still uncertain. Never invent an API, flag, command, or behaviour.

Output

Produce the artifact, lead with the verdict, and keep schema headings and identifiers unchanged. For a concrete feature path, .specs/features/lockfile-v2/plan.md is reviewed before its checks; the route then validates checks, builds, and dispatches the fresh full-range Verifier.