workflow · diff

git:20261008.0e07558 to git:20261008.f553434

34 added, 4 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: workflow
description: The operating pipeline for all development work — 6 phases (Brief, Plan, Build, Verify, Ship, Learn) with risk tiers that decide how much process a task gets. Use at the start of any development task to pick the tier and execution mode, when unsure whether a task needs a plan/tests/review, or when another skill needs the phase and tier vocabulary. This skill overrides any process embedded in other skills.
---
# 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 | Short plan (a few bullets, in-chat OK) → build inline → tests on the affected path → one review pass → evidence. |
+ | **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.
- Gate: user says "yes, that's what I want."
+ (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/T3): user approves the plan.
+ 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.
## Precedence
This pipeline outranks process instructions embedded in any other skill. Other
skills contribute technique (how to debug, how to write tests); this skill owns
sequencing, tiering, and how much ceremony a task deserves.