AGENT SKILL

phased-plan

Ceremony rules for shipping a phase of a phased plan — when to release, when to emit a handoff prompt, how far to go on type-strengthening, when to fold or split phases, and the hero-exit rule that prevents plans from becoming open-ended. Load when shipping a phase of a docs/*-plan.md (or equivalent) plan. Use when this named workflow matches the task.

License 许可
Apache-2.0
最近更新
2026-11-15
Stars
★ 48
Forks
16

01 前言 Front Matter

name
phased-plan
metadata
{ "opencode": "agent-permission" }
description
Ceremony rules for shipping a phase of a phased plan — when to release, when to emit a handoff prompt, how far to go on type-strengthening, when to fold or split phases, and the hero-exit rule that prevents plans from becoming open-ended. Load when shipping a phase of a docs/*-plan.md (or equivalent) plan. Use when this named workflow matches the task.
allowed-tools
Read, Edit, Bash
user-invocable
false
disable-model-invocation
true

03 SKILL.md 正文

Phased-Plan Ceremony

Load this skill when you finish (or are about to finish) a phase of a phased plan. It governs four things: handoff prompts, releases, plan-shape rules (hero-exit, phase-split, hygiene-queue), type-strengthening. "The project's release skill" referenced below is this repo's own /release.

Git authorization. Loading this skill is the user's explicit authorization to run fak commit (or explicit-path git commit) for the phase-ship commit and for any Phase-0 baseline snapshot the ceremony spells out. The "never commit unless asked" default does NOT apply here — committing the phase artifact IS the skill's job. The skill does NOT authorize git push or git tag directly — those happen via the project's release skill (which has its own authorization), or require explicit user confirmation if invoked outside it. Force-push, history rewrites, branch deletion, and git reset --hard always require explicit user confirmation. Use targeted pathspecs only — never git add -A/-u/..

Handoff prompts — session-boundary only

Emit a copy-paste handoff prompt only at a session boundary — when the user signals they are wrapping up, clearing context, or otherwise ending the session ("wrapping up", "/clear next", "done for the day", compaction imminent). Do NOT emit one after every phase completion within a live session; the plan doc + issue tracker already carry continuation context for in-session work. Format when you do emit:

--- NEXT-STEP PROMPT (copy into new session) ---
Continue <plan-id> (<doc path>). Just shipped: <one-line summary of completed phase>.
Next phase: <next phase id + title>. Goal: <1-sentence goal>. Key files/refs: <paths>.
Start by reading <doc path> and the listed files, then propose a short implementation plan before editing.
--- END ---

≤6 lines, self-contained, includes plan doc path + next phase id.

Releases — only on shippable code change

Run the project's release skill only when the phase produced a user-visible behavior change or modifies shipped code paths. The commit still lands either way — the release ceremony (version bump, changelog entry, tag, push, release artifact) is reserved for code that will be visible to the operator running the tool.

Do NOT release for:

  • Docs-only edits to in-flight plans (plan flesh-out, phase re-sequencing, prose tightening)
  • Proposal / baseline-snapshot / measurement-checkpoint phases that add no runtime code
  • Observation-only / shadow-soak / instrumentation-only phases
  • Single-checkbox issue ticks with no code diff
  • Memory-file or roadmap-index updates

Do release for: new/changed CLI flag or subcommand, new/changed handler or API endpoint, behavior change in core pipelines, schema changes, bug fixes that affect runtime, new skill or meaningful skill-logic change.

When in doubt, skip the release and batch with the next shippable phase. Version numbers should carry signal — raise the bar, not the cadence.

Pre-release 3-question gate

Before invoking the release skill, answer:

  1. Does the release window contain at least one runtime code-path edit?
  2. Could an operator trigger something from CLI/UI and see different output?
  3. Is the headline a behavior name (not "plan-doc refresh", "phase X captured", "ceremony", "rollup")?

Three "no"s → docs-only commit on the working branch with no version bump, no tag, no archive, no release entry.

Progress state — report movement without weakening claims

Use docs/progress-state-defaults.md as the canonical vocabulary. In every plan's Current state, report product, evidence, and queue independently; include the next movement. Do not use one overall KEEP, REJECT, or HOLD label as current state.

  • A failed or missing runtime receipt changes the evidence axis, not delivered product scope.
  • Mark a validator or correctness slice as BOUNDED_ACCEPTANCE only when that named boundary is fully witnessed; state the broader evidence still missing.
  • Award delivery credit for witnessed shipped scope, prepared packets, removed dependencies, launched runs, and reproduced evidence. Award performance credit only after the full applicable claim gate passes.
  • For fak-native performance, preserve exact artifact and quantization identity, engine=fak-native, fallback 0, strict quality, inclusive request-boundary accounting, and a one-variable matched comparison. llama.cpp and MLX remain explicit reference/comparison arms only.
  • Apply the native-tuning default in AGENTS.md: record candidate source/configuration/workload identity and the full configuration delta in the plan. Refresh incompatible reference measurements when objective or load changes; reassess compatible history for SLO-only changes. Justify inseparable bundles and credit only the bundle. Record independent validity/budget review before an expensive run, bound to the exact candidate, objective, load, SLO, and planned cost. Candidate changes reopen only affected review and witnesses; existing user authorization, budget, and security limits remain in force.
  • Keep at most three ACTIVE_PROBE items. Prefer READY_TO_RUN, DEPENDENCY_ADVANCING, QUEUED_BEHIND <issue>, or reversible PARKED_LOW_VALUE over indefinite HOLD. Reserve EXTERNAL_BLOCK for exhausted local, fleet, and dependency-clearing routes.
  • Preserve dated historical campaign decisions in Execution log even when current state moves to a more actionable queue label.

Hero-exit rule — close the plan when the hero metric is met

Every phased plan has a single 1-hop hero metric in its header. When that metric reaches its target, the next phase queued is the close-out — not another sub-phase, not a refactor of an adjacent surface, not "while we're in here."

Before queuing the next phase of a plan whose hero metric you just moved, re-read the metric:

  1. Hero met? Next phase = plan close-out. In the same close-out commit: tombstone the plan-doc, close the umbrella issue, move pending sub-phases to PARK with a "remaining tail" label.
  2. Hero not met? Continue per the plan's sequencing.

Plans without hero-exit become open-ended consolidation projects that consume slot budget without delivering closure. If work past the hero looks legitimately load-bearing, that means the plan named the wrong hero — fix the metric first (one PR, header only), then continue. Don't ship past a stated hero without auditing it.

TOMB-at-impl-plus-monitor — soak gates are a lane, not a phase

A plan is tombstone-eligible the moment implementation ships and a monitor is attached. "Monitor" = either a registered soak watch or a CI invariant that fires on regression. The 100%-phases criterion conflates engineering work with passive evidence-gathering and produces the "85-95% stuck for weeks" portfolio pattern.

Rules:

  1. Last phase is never "soak gate + tomb." Those are separate kinds of work. Final engineering phase ships code; soak goes to the soak registry; tomb is administrative.
  2. TOMB-with-soak-attached is a recognized terminal state. Plan exits the active queue, soak continues, memory anchor preserves the decision trail.
  3. A failing soak keeps the plan active. If a soak's current metric is below its pass-criterion, the plan is not tomb-eligible — the risk is real, not theoretical.
  4. Soak pass-criterion shape: prefer event-count gates over calendar gates when the system runs hot (e.g. ≥5 events beats 7d when traffic is bursty); use composite gates (metric ≥ X for N consecutive periods) for noise-prone metrics.

Phase-split test — fold phases that don't produce intermediate evidence

Before splitting work into two phases, ask: "does phase N+1 need evidence that phase N produces?"

  • No (N+1 is just code chained off N's API surface) → fold them. One phase, one ship-stamp.
  • Yes (N+1 reads telemetry, soak result, or measurement that only exists after N ships) → split is justified.

Splitting on operator-fatigue lines is a major producer of fragmentation. The historical default ("each phase fits one agent session") is wrong when phase N and N+1 are reversible code chains the same agent could ship together.

Anti-pattern: observability-before-guard splits ("observe" then "act"). When the change is low-risk, bake telemetry into the implementation phase and let the soak prove it.

Hygiene-umbrella plans are queues, not roadmaps

Hygiene-umbrella plans (cleanup, deprecation, tech-debt collections) accumulate open-ended cleanup. Convention:

  • One substrate phase at the top (baseline) — fine.
  • Everything after is a queue, not pre-numbered phases. Track inflight items + closed in last 7d count.
  • Drop % complete from the plan-doc header (it forces inventing new phase numbers when sibling cleanups surface mid-session).
  • Sibling items batch into one dispatch when they chain on the same substrate.

Distinguishing test: if you can answer "does the new sub-task need evidence the prior sub-task produces?" with "no, it's just more cleanup of the same shape" → it's a queue item, not a phase.

One investigation is one plan — do not split it into a series

A single investigation with several suspected causes is one plan with phases (Phase 0 baseline → Phase 1..N each a measured fix), not N sibling plans. Sibling plans are justified only when the causes are already proven independent and each has its own hero metric.

Rule: no new plan doc until a Phase-0 baseline names a metric that no existing plan can host. Before opening any new plan, check whether an existing active or hygiene plan can host the work. Prefer a phase/queue-item on an existing plan; open a new doc only when that genuinely fails.

Phase 0 baselines — register-or-delete invariant

Optional for low-blast-radius edits. A phase may skip the Phase 0 baseline freeze when all three hold: change is ≤50 LOC, rollback is a single revert, and failure mode is observable post-hoc from existing telemetry. The plan still names the metric and expected direction; it just doesn't pre-freeze a numeric. The measure-then-change axiom is load-bearing for risky changes — wiring substrate, changing dispatch behaviour, touching a hot path — and remains mandatory for those.

When a phase DOES produce a measure-then-change baseline, it must land in git the same way every time: same commit, registry row (in whatever baseline-tracking file the project uses), no exceptions. Skipping the registry row is the producer for orphan baselines that survive plan-aborts and pile up.

# Atomic — one commit, both assets. Never just the dir, never just the row.
fak sync check
fak commit \
  --path <baseline-dir>/ --path <baseline-registry-file> \
  -m "<plan>: <phase> — baseline snapshot (measure-then-change)"

The registry row encodes "this baseline exists, here's what it measures, here's its rebaseline cadence." Without it, future tools can't audit the on-disk dir against ground truth — only the operator's memory ties them.

If the plan aborts: keep the baseline dir + registry row in git as historical evidence. Annotate the registry row's notes with the abort reason. Deletion is a separate operator decision after the plan has been tombstoned.

No release ceremony, no version bump — Phase 0 is observation-only by definition (per "Releases — only on shippable code change" above).

Issue-tracker conventions

If the project uses GitHub/Linear/etc. for umbrella issues:

  • Each active phased plan has one umbrella issue. Tombstoned/parked plans do not.
  • Pending phases are rendered as - [ ] task-list checkboxes inside the issue body so the issue card shows X-of-N progress automatically.
  • When you ship a phase: tick its checkbox.
  • When a plan completes: close the umbrella issue. If the plan tombstones, link the tombstone in the closing comment.
  • When proposing a new plan: create a new umbrella issue, add a link in the plan-doc header.

The project's CLAUDE.md / AGENTS.md should name the issue-tracker URL and label conventions.

Type-strengthening — payload-only scope

Type the new payload/struct/enum/config-key the phase itself adds. Do not scope-creep into surrounding untyped code — that's a separate cleanup, not part of the phase.

  • Python: Pydantic model (or dataclass) for any new structured payload crossing a module boundary; Literal/Enum for closed string sets the phase introduces; return-type annotations on new functions.
  • Go: named struct for any new payload crossing a package boundary; typed enum (type Foo string + consts) for any new closed string set; concrete error type when callers of new code will branch on it.
  • Contract lockstep: if the phase adds a new config key or event-payload field, add/update the matching struct in the same commit.

Skip silently when the new thing is genuinely dynamic (third-party shape) or typing would force a breaking change outside the phase's scope.

04 同仓库更多 Skills