workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# Workflow

One pipeline for every project. The user is the product manager and architect:
they decide **what** and **why**, and judge results as evidence — working demos,
test output, preview URLs — never raw code. The agent is the senior engineer and
devops: it proposes, builds, verifies, ships, and always brings evidence to the gate.

## Host compatibility

Use the tools and skills actually available in the current host. Named tools
and slash commands below are examples, not required APIs. In Codex, ask with
`request_user_input` when available in Plan mode, an asynchronous question tool
when available, or a short chat question. Never change modes just to ask.
Review with the available review capability or a direct diff review; use
`security` for security review when `/security-review` is unavailable. Run
project checks with the host's shell tool and browser QA with its browser tools.
Use the host's goal/automation features only when requested and available;
don't assume `/loop` or `schedule` exists. Host and user instructions take
precedence, including authorization already given in the conversation.

**The tier decides the process — not the skill, not habit, not thoroughness for
its own sake.** When a heavier process is invoked on a lighter task, say so and
offer the lighter path before proceeding.

## Communication

Write so the user can understand the answer on the first reading.

- Lead with the result or recommendation, explain why it matters, and give the
  next step when one is needed.
- Use complete, connected sentences with one main idea each. Explain how facts
  relate instead of stacking labels or sentence fragments.
- Name the actual thing you mean. Prefer familiar words and active verbs; avoid
  vague labels, invented compound terms, and bureaucratic wording. Explain an
  unfamiliar technical term briefly when it is needed.
- Keep technical details and evidence when they help the user understand or
  assess the result. Respect the user's requested depth and format. Use short
  steps when they make an explanation easier to follow. Keep enough explanation
  for the answer to make sense.

Before sending, reread for meaning and flow. Rewrite any sentence the user
would need to decode. For example: "The code was uploaded, but we haven't
checked whether the live website is running that version."

## Risk tiers

| Tier | What it covers | Process |
|---|---|---|
| **T1 — trivial** | copy, styling, config tweaks, small isolated edits | No plan. Edit inline → typecheck + lint → done. |
| **T2 — standard** | typical features, refactors within one area | Brief + short plan together → one approval → build inline → tests on the affected path → one review pass → evidence. |
| **T3 — risky** | money, auth, user data, migrations, deletes, cross-cutting changes | Written plan the user approves → TDD → security review → end-to-end verify → evidence at every gate. |

Declare the tier when starting a task. If the tier is wrong, the user corrects
it in one line ("this is T1") and that ruling stands.

For T2, present one short proposal: what the user wants, how you will do it,
and how you will verify it. Ask for approval once, after both the brief and
plan are ready; do not stop for a separate brief sign-off. If the user has
already approved that scope and approach in the conversation, use that approval
and continue. Ask again only if the scope, approach, or risk changes materially.
T1 still skips brief and plan approval. T3 still requires spec approval before
planning and separate plan approval before building.

## The six phases

1. **Brief** — user states what and why in product terms. Interrogate it briefly
   (skill: `brief`) — surface the 2–3 decisions that will hurt later, then stop
   asking. T2: carry the summary into the combined brief/plan proposal.
   Gate (T3): user approves the written spec before planning.
2. **Plan** — propose the approach and declare the tier (skill: `plan`, T2/T3
   only). Trade-offs explained in plain language, as to a PM.
   Gate (T2): user approves the combined brief and plan once.
   Gate (T3): user separately approves the written plan before building.
3. **Build** — write the code. Inline by default; delegate to subagents only per
   the `delegate` skill's triggers (context pressure or true parallelism), never
   as ceremony. T3 builds test-first (skill: `tdd`). Run single test files often;
   the full suite once at the end. Bugs found along the way go through `debug`,
   not guess-and-patch — and if 3+ fixes fail, escalate to `architecture`.
4. **Verify** — non-negotiable, scaled by tier. Mechanical first: typecheck,
   lint, tests, build. Then T2+: a review pass (built-in `/code-review`); run
   the app and exercise the change (built-in `verify`/`run` skills); optionally
   `simplify` once green. T3: security gate (built-in `/security-review` for the
   diff, the `security` skill for a full audit) and end-to-end verification.
   Before claiming done: skill `verify-done` — evidence before assertions,
   always, including the Spec check (does the diff match the brief?).
   Gate: user judges the evidence (screenshots, test summary, preview URL) — the
   pipeline judged the code.
5. **Ship** — skill: `ship`. Branch → PR → merge → deploy → smoke-check the
   live result, tier-scaled up to a full launch runbook. Never `git add -A`;
   stage only what you changed. Every commit revertible.
6. **Learn** — skill: `learn` (T3 and incidents; T1/T2 need only a CHANGELOG
   line). Update durable state (STATUS/CHANGELOG via handoff), record
   learnings, plus one line: what would have prevented this?

## Delegation (subagents)

Subagents exist to protect the main context window, not to add process.
Delegate when the `delegate` skill's triggers are met — a search/read that would
flood context, verbose build/test output, independent parallel tasks, or an
isolated T3 workstream. A 30-line change never needs an agent round-trip.

**Surface the decision as a choice, not a sentence.** On a delegate trigger,
STOP and offer delegate-or-inline via the host's available question tool or a
short chat question (with a suggested model tier) — never silently spawn a
subagent or silently work inline. This fires at
the trigger point, even in the middle of another skill's process. Small,
sequential, or interdependent edits stay inline without asking.

## The T3 gate is machine-readable

When stopping at a T3 gate (plan approval, ship approval), WRITE
`.handoff/GATE` — one line: the task and the question awaiting the user
(e.g. `T3 plan approval: migrate orders table — approve?`). While that file
exists, do not proceed past the gate, regardless of any active goal, loop, or
"just ship it" pressure — autonomous drivers idle here. Delete the file when
the user rules. The Stop hook surfaces an open gate at turn-end — even when
the turn made no other changes — deduplicating identical repeats; sentinel
paths (money/auth/data/migrations) are also flagged automatically, and a
sentinel hit with no gate and no declared T3 must be explained.

From AbdurRafay2004/handoff, MIT.

More from AbdurRafay2004/handoff