v60samurai/agent-skills

Prompt Compile

Define-do-verify for real tasks. Compile a brief (define), execute it in fresh context where possible (do), check the result against the brief (verify). The brief is the prompt an experienced operator would have hand-written before a big task - now generated in-session, every time.

When this runs

• Fired by the prompt-compile-gate.sh hook (medium and high bands), or invoked manually.
• Not for bug fixes: your debugging workflow owns those.
• Not for trivial one-file one-step edits: if the gate misfired, say "trivial, skipping brief" in one line and just do it.

Compile the brief

Seven sections. All required. Missing section = brief not done.

1. TASK + NON-GOALS

One paragraph: what changes, and what is explicitly preserved. Non-goals are the highest-value words in the brief ("polish pass, not a rebuild. Preserve data, routing, behavior. Change presentation only.").

2. TARGET

Concrete environment, not adjectives. "Latest iPhone Pro, ~402pt logical width, Dynamic Island, home-indicator safe area" - never "mobile-friendly". For non-UI work: runtime, versions, load shape, who consumes the output.

3. CONSTRAINT SOURCES

Files the executor must read before generating anything: design docs, design tokens, schema, project instructions (CLAUDE.md / AGENTS.md), style guides. Hard rule inherited by every brief: if a needed value or source does not exist, stop and flag - never invent one.

4. SKILL SEQUENCE

Scan available skills; name them in execution order, with register or mode where it matters. Example: /distill -> /adapt (product register) -> a craft/polish pass. Every stage that has a matching skill names it explicitly - the executor must not rediscover routing.

5. CHECKPOINTS

Where execution stops for the user's confirm: proposed cuts before restructure, variant pick before writing to source, destructive step before running. Input is just a link or pointer -> diagnostic pass is checkpoint zero. No checkpoint needed? Say "no checkpoints" explicitly.

6. VERIFY

Observable pass/fail criteria, checkable after execution: no horizontal overflow at target width, tap targets >= 44pt, all states handled (loading/error/empty), typecheck clean, tests green. E2E where the change has a runtime surface.

7. OUTPUT CONTRACT

The shape of the executor's final response, in order. Example: diagnostic -> proposed cuts -> 3 variants -> craft pass on winner -> diff summary + anything that couldn't be done within constraints.

Execute

• Medium band: show the compiled brief, non-blocking - start immediately, the user interrupts if it is wrong.
• High band: show the compiled brief and WAIT for explicit approval before executing.
• No checkpoints in the brief -> hand the brief verbatim to one fresh subagent. Verbatim means the brief is the entire prompt; no extra context smuggled in.
• Checkpoints in the brief -> subagents cannot talk to the user, so either run inline with the brief as the plan, or run one subagent per inter-checkpoint segment, returning to the user at each gate.
• Task depends on conversation state (builds on the last N minutes of this session) -> run inline.
• Subagent runs pay a cold-start tax: the segment must be meaty enough (roughly >5 minutes of work) to amortize it, else run inline.

Verify

• After execution, walk section 6 line by line. Each criterion: pass or fail, stated.
• Any deviation from the brief (constraint broken, section skipped, invented value) gets reported, not silently absorbed.
• Fail -> fix before reporting done. This is the loop's exit condition, not a formality.

Worked example

The brief below is the reference for register and completeness (a hand-written original, abridged):

Polish [SCREEN] for mobile. Polish pass on existing screen, not a rebuild. Preserve data, routing, behavior. Change presentation only. (1: task + non-goals) Target latest iPhone Pro ~402pt, Dynamic Island, home-indicator safe area; Pixel 9 Pro ~412dp. (2: target) Read DESIGN.md, PRODUCT.md, design tokens before generating. No new colors, radii, shadows, fonts, spacing. Value missing as token -> stop and tell me. (3: constraint sources) Step 1 declutter/distill, step 2 adapt for mobile in product register, step 3 craft pass on the winner. (4: skill sequence) Diagnostic first, I confirm. Show cuts, I confirm. 3 variants, I pick, no auto-accept. (5: checkpoints) Safe areas respected, tap targets >= 44pt, no horizontal overflow, invisible states handled. (6: verify) Diagnostic -> cuts -> variants -> craft pass -> diff summary; flag anything outside tokens. (7: output contract)

A brief that reads thinner than this is not compiled yet.