@gtrabanco/pi-agentic-workflow 0.13.2 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -9
- package/dist/routing/catalogue.d.ts +1 -1
- package/dist/routing/catalogue.js +1 -1
- package/dist/runtime.d.ts +45 -0
- package/dist/runtime.js +62 -0
- package/package.json +10 -8
- package/skills/audit-docs/SKILL.md +6 -5
- package/skills/audit-pr/SKILL.md +1 -1
- package/skills/audit-pr/references/PORTABILITY.md +1 -1
- package/skills/execute-phase/SKILL.md +207 -116
- package/skills/execute-phase/references/DESCOPE.md +22 -18
- package/skills/execute-phase/references/EXECUTION_CONTRACT.md +69 -77
- package/skills/execute-phase/references/FOLDING.md +34 -47
- package/skills/execute-phase/references/PREFLIGHT.md +103 -114
- package/skills/execute-phase/references/PRE_EXECUTION_GATE.md +53 -60
- package/skills/init-workspace/SKILL.md +52 -16
- package/skills/init-workspace/references/BOOTSTRAP_DISCOVERY.md +6 -6
- package/skills/init-workspace/references/BOOTSTRAP_WRITE.md +17 -10
- package/skills/init-workspace/references/PORTABILITY.md +1 -1
- package/skills/init-workspace/references/UPGRADE.md +50 -15
- package/skills/log-session/SKILL.md +4 -3
- package/skills/orchestration-envelope/references/TURN_CONTRACT.md +1 -1
- package/skills/pre-execution-review/references/LEDGERS.md +39 -39
- package/skills/pre-execution-review/references/POLICY.md +1 -0
- package/skills/product-audit/SKILL.md +4 -4
- package/skills/product-audit/references/AUDIT_PROCESS.md +3 -3
- package/skills/review-change/SKILL.md +1 -1
- package/skills/review-change/references/PORTABILITY.md +1 -1
- package/skills/unit-lane/SKILL.md +154 -0
- package/skills/unit-lane/references/DESIGN.md +35 -0
- package/skills/unit-lane/references/DOCS.md +36 -0
- package/skills/unit-lane/references/EVIDENCE.md +34 -0
- package/skills/unit-lane/references/IMPLEMENT.md +45 -0
- package/skills/unit-lane/references/PLAN.md +38 -0
- package/skills/unit-lane/references/RELEASE.md +45 -0
- package/skills/unit-lane/references/RESEARCH.md +37 -0
- package/skills/unit-lane/references/REVIEW.md +45 -0
- package/skills/unit-lane/references/STEPS.md +23 -0
- package/skills/unit-lane/references/TESTS.md +32 -0
- package/skills/workflow-status/references/ENVELOPE_FIELDS.md +5 -6
- package/skills/workflow-status/references/SENSOR_CORE.md +16 -20
- package/skills/workflow-status/references/SENSOR_SIGNALS.md +5 -7
- package/skills/design-feature/SKILL.md +0 -231
- package/skills/design-feature/references/INTERVIEW.md +0 -74
- package/skills/design-feature/references/PORTABILITY.md +0 -15
- package/skills/design-feature/references/REPAIR.md +0 -88
- package/skills/design-feature/references/UPSERT_EXAMPLE.md +0 -8
- package/skills/design-feature/references/WRITE_AND_UPSERT.md +0 -115
- package/skills/evidence-grounding/SKILL.md +0 -174
- package/skills/evidence-grounding/references/DELEGATION.md +0 -131
- package/skills/evidence-grounding/references/READINESS.md +0 -130
- package/skills/evidence-grounding/references/ROWS.md +0 -93
- package/skills/execute-phase/references/BATCH_AND_PORTABILITY.md +0 -57
- package/skills/execute-phase/references/CLOSEOUT.md +0 -77
- package/skills/execute-phase/references/HANDOFF.md +0 -21
- package/skills/execute-phase/references/OPPORTUNISTIC_FINDING.md +0 -45
- package/skills/execute-phase/references/UNIT_LOOP.md +0 -88
- package/skills/execute-phase/references/WORKFLOWS_FEATURE.md +0 -37
- package/skills/execute-phase/references/WORKFLOWS_FIX.md +0 -43
- package/skills/execute-phase/references/WORKFLOWS_LEGACY.md +0 -26
- package/skills/execute-phase/references/WORKFLOWS_SMALL_PHASED.md +0 -38
- package/skills/generate-docs/SKILL.md +0 -145
- package/skills/generate-docs/references/ADAPTERS.md +0 -15
- package/skills/generate-docs/references/ADAPTER_DISCOVERY.md +0 -33
- package/skills/generate-docs/references/GENERATION_PROCESS.md +0 -90
- package/skills/implementation-discovery/SKILL.md +0 -209
- package/skills/plan-feature/SKILL.md +0 -208
- package/skills/plan-feature/references/ROUTING.md +0 -155
- package/skills/plan-feature-from-issue/SKILL.md +0 -162
- package/skills/plan-feature-scaffold/SKILL.md +0 -112
- package/skills/plan-feature-scaffold/references/SCAFFOLD_PROCESS.md +0 -122
- package/skills/plan-fix/SKILL.md +0 -161
- package/skills/plan-fix/references/PLANNING_PROCESS.md +0 -148
- package/skills/plan-fix/references/SPEC_CONTRACT.md +0 -22
- package/skills/planning-preflight/SKILL.md +0 -130
- package/skills/replan-findings/SKILL.md +0 -131
- package/skills/replan-findings/references/PHASE_APPEND.md +0 -89
- package/skills/review-plan/SKILL.md +0 -154
- package/skills/review-plan/references/CHECKS.md +0 -111
- package/skills/review-plan/references/ENG-CHECKS.md +0 -30
- package/skills/review-plan/references/OUTPUT.md +0 -166
- package/skills/review-spec/SKILL.md +0 -145
- package/skills/review-spec/references/CHECKS.md +0 -108
- package/skills/review-spec/references/OUTPUT.md +0 -160
- package/skills/ship-roadmap/SKILL.md +0 -120
- package/skills/ship-roadmap/references/ADVANCE.md +0 -117
- package/skills/ship-roadmap/references/AUDIT_AND_MERGE.md +0 -64
- package/skills/ship-roadmap/references/CLOSEOUT_AND_LOG.md +0 -27
- package/skills/ship-roadmap/references/FOUNDING.md +0 -101
- package/skills/ship-roadmap/references/GUARDRAILS.md +0 -56
- package/skills/ship-roadmap/references/MODEL_ROUTING.md +0 -16
- package/skills/ship-roadmap/references/PORTABILITY.md +0 -34
- package/skills/ship-roadmap/references/RECOVERY_AND_SELECTION.md +0 -94
- package/skills/ship-roadmap/references/STOP_CONDITIONS.md +0 -9
- package/skills/ship-roadmap/references/TERMINAL_REPORT.md +0 -34
|
@@ -1,101 +0,0 @@
|
|
|
1
|
-
## Process
|
|
2
|
-
|
|
3
|
-
### Mode A — Found & launch (interactive): `/ship-roadmap [--fullauto]`
|
|
4
|
-
|
|
5
|
-
**1. The interview — all questions up front, then silence.** Small batched
|
|
6
|
-
rounds; recommended defaults on every question; skip what discovery already
|
|
7
|
-
answered. After Round 6 locks, **no further questions for the entire run** —
|
|
8
|
-
every later decision is made silently and logged with a one-line rationale.
|
|
9
|
-
|
|
10
|
-
| Round | Covers |
|
|
11
|
-
|---|---|
|
|
12
|
-
| 1 — Product | What it is, for whom; scale ceiling (solo / team / thousands of customers); lifespan & ambition (throwaway, internal, long-lived production). Calibrates every ceremony decision downstream. |
|
|
13
|
-
| 2 — Features | The feature list (or "elicit" → draft one from the goal); must-have vs can-wait; ordering constraints; explicit out-of-scope. |
|
|
14
|
-
| 3 — Stack & architecture | Stack decided? else recommend from features/constraints. Architecture chosen? else recommend the **lightest structure proportional to Round 1** — a solo tool gets a flat modular layout, a thousands-of-customers system gets enforced boundaries; never default to DDD, hexagonal, or any named pattern. Platform/runtime constraints, library vetoes. |
|
|
15
|
-
| 4 — Quality & ops | Test depth (smoke / workflow default / strict); whether a11y, SEO, i18n, perf budgets apply (proposed from platform type); deploy target + scaffold CI?; secrets posture; **confirm the proposed verification gate commands** — they become the gate every phase must pass. |
|
|
16
|
-
| 5 — Workflow & autonomy | Docs language (default English); forge + CLI (**verify with a real authenticated call now**, e.g. `gh auth status` — not mid-loop); **git workflow** (default `branches`: one active unit, sequential, no worktrees — `worktrees` only if the user declares it and their tooling manages them; recorded in the Workflow conventions and honored by every stage); merge policy (default human-merge vs `--fullauto`); the sensitive-area list (defaults: auth, payments, destructive migrations/data deletion, secrets, CI config — **seeded with every integration named in rounds 2–4**, e.g. the payment processor or auth provider the user mentioned); budget caps (default: max iterations = 4× roadmap feature count; 2 retries per red gate; 2 review-fix and 2 audit-fix cycles; optional "pause after N shipped features" checkpoint and milestone stop lines); model-routing confirmation; recommend enabling `ultracode` for the loop. |
|
|
17
|
-
| 6 — Confirm & launch | The drafted roadmap (numbers, order, deps, sizes) and the full decision record, presented for **one last edit**. Then: founding artifacts written, exact `/loop` command printed. |
|
|
18
|
-
|
|
19
|
-
**2. Founding (only what's missing).** Compose `init-workspace`'s process
|
|
20
|
-
in-turn (both opus/high — within the ≥ rule), **pre-fed with the interview
|
|
21
|
-
answers** so it asks nothing. Branch discipline:
|
|
22
|
-
|
|
23
|
-
- **Empty repo:** the scaffold (CLAUDE.md, docs/, .github/, completed
|
|
24
|
-
ROADMAP.md, decision record) is the repo's **initial commit on the default
|
|
25
|
-
branch** — there is no history to protect and no base for a PR yet.
|
|
26
|
-
- **Existing repo:** founding goes on a `docs/ship-founding` branch as a PR.
|
|
27
|
-
Default mode: **stop after the interview** — print the PR and require it
|
|
28
|
-
merged before the loop starts (building features against an unmerged
|
|
29
|
-
substrate would stack PRs). `--fullauto`: gate the founding PR with
|
|
30
|
-
`audit-pr` like every other PR, then merge it.
|
|
31
|
-
|
|
32
|
-
**3. The roadmap — founding IS batch design.** The interview's rounds 2–4
|
|
33
|
-
(features, quality/ops, workflow) already collected every product-definition
|
|
34
|
-
answer a `design-feature` capability closure would ask — founding is design
|
|
35
|
-
for every feature it names, not a shortcut around it. Adopt existing entries
|
|
36
|
-
(never renumber), fill gaps the interview surfaced, append elicited features.
|
|
37
|
-
If absent, write the complete table: NN in dependency-respecting order, slug,
|
|
38
|
-
**status `idea`** (the locked founding decisions are the design record, but
|
|
39
|
-
no per-feature `SPEC.md`/capability-closure artifact exists yet — that gets
|
|
40
|
-
written JIT per feature, see ADVANCE → DESIGN below), depends-on, one-line
|
|
41
|
-
summary with a **provisional XS/S/M/L size in the summary text** (the
|
|
42
|
-
template's five-state legend and column schema stay exactly as they are —
|
|
43
|
-
`plan-feature`/`plan-feature-scaffold` re-size authoritatively at planning
|
|
44
|
-
time; a size change is logged silently). Greenfield: **feature 01 is always
|
|
45
|
-
the project skeleton** (stack init, gate wiring, CI if requested), sized S —
|
|
46
|
-
founding scaffolds it immediately (composing `design-feature` +
|
|
47
|
-
`plan-feature-scaffold` in-turn, pre-fed from the interview, no questions) so
|
|
48
|
-
it lands directly at **status `planned`**, never left at `idea` — and **every
|
|
49
|
-
other feature's depends-on closure must include 01** (directly or
|
|
50
|
-
transitively), so SELECT can never start a feature on a default branch that
|
|
51
|
-
lacks the skeleton.
|
|
52
|
-
|
|
53
|
-
**4. The run state — two artifacts, deliberately split:**
|
|
54
|
-
|
|
55
|
-
- `docs/features/SHIP_DECISIONS.md` — **committed** (rides the founding
|
|
56
|
-
commit/PR): run mode, safety floors, sensitive-area list, budget caps, stop
|
|
57
|
-
lines, model routing, docs language, and a digest of every locked interview
|
|
58
|
-
answer. It is the durable, auditable policy: a crash, another machine, or a
|
|
59
|
-
fresh clone recovers the full run policy without re-interviewing.
|
|
60
|
-
- `docs/features/.ship-run.log` — **untracked** (founding appends it to
|
|
61
|
-
`.gitignore`): the append-only iteration log — one line per iteration
|
|
62
|
-
(`date | NN-slug | stage | outcome | evidence: SHA / PR# / verdict`), silent
|
|
63
|
-
decisions with rationale, partial-stage markers, verdict↔SHA bindings.
|
|
64
|
-
Machine-local mechanics; committing it would conflict across every open PR.
|
|
65
|
-
|
|
66
|
-
**5. Print the launch contract** — detect which driver this environment has
|
|
67
|
-
and print the matching command. **Three equivalent drivers** (the loop is the
|
|
68
|
-
contract; who re-invokes it is an implementation detail):
|
|
69
|
-
|
|
70
|
-
| Driver | When | Launch |
|
|
71
|
-
|---|---|---|
|
|
72
|
-
| **`/loop`** (Claude Code) | The agent has a self-re-invoking loop primitive | `/loop /ship-roadmap --continue` |
|
|
73
|
-
| **External orchestrator** | Any agent invocable headless (a shell loop, CI, your own program) | loop: invoke `/ship-roadmap --continue`, parse its native `SHIP:`/`→ Next:` contract, and re-invoke while the turn is non-terminal — see `docs/workflow/ORCHESTRATION.md` |
|
|
74
|
-
| **Manual** | Neither of the above | re-run `/ship-roadmap --continue` yourself after each iteration; each ends with the exact next command |
|
|
75
|
-
|
|
76
|
-
Default launch contract text (adapt the first line to the detected driver):
|
|
77
|
-
|
|
78
|
-
```
|
|
79
|
-
Founded. Start the autopilot with:
|
|
80
|
-
|
|
81
|
-
/loop /ship-roadmap --continue (Claude Code)
|
|
82
|
-
— or loop `/ship-roadmap --continue` from your orchestrator/by hand;
|
|
83
|
-
parse the native `SHIP:` banner and `→ Next:` block, then re-invoke
|
|
84
|
-
while the turn is non-terminal (see docs/workflow/ORCHESTRATION.md)
|
|
85
|
-
|
|
86
|
-
Stop when an iteration's first line is SHIP: COMPLETE, SHIP: BLOCKED, or
|
|
87
|
-
SHIP: STOPPED (envelope state OK, BLOCKED, or FAILED). Iterations are
|
|
88
|
-
idempotent and resume cleanly; stopping at any time is safe.
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
For a fullauto run the command is `/ship-roadmap --continue --fullauto` (under
|
|
92
|
-
whichever driver) — the flag must ride every iteration, because auto-merge is
|
|
93
|
-
dual-keyed: the flag on the running command **and** `merge: fullauto` in the
|
|
94
|
-
committed decision record (see Merge policy). One key without the other runs
|
|
95
|
-
in default mode.
|
|
96
|
-
|
|
97
|
-
Each firing is a fresh `/ship-roadmap --continue` turn (on Claude Code's
|
|
98
|
-
`#claude` branch, at this skill's pinned tier; elsewhere, at whatever tier the
|
|
99
|
-
driver chose — judgment iterations deserve your strongest model). Iterations
|
|
100
|
-
after a terminal banner are cheap no-ops that re-print the same banner — so a
|
|
101
|
-
missed stop costs tokens, never correctness.
|
|
@@ -1,56 +0,0 @@
|
|
|
1
|
-
## Guardrails
|
|
2
|
-
|
|
3
|
-
- **Never work on the default branch** — the empty-repo initial scaffold commit
|
|
4
|
-
is the single exception. One PR per unit, never stacked; roadmap status flips
|
|
5
|
-
ride PR-bound commits only.
|
|
6
|
-
- **Forge bodies are Markdown, not shell — never hand-escape.** Every explicitly
|
|
7
|
-
authorized issue, PR, or comment the run creates (subagent PRs, triage
|
|
8
|
-
comments) carries a body of **real Markdown**: backticks / `*` / `_` are
|
|
9
|
-
formatting, and a `\` before them renders literally (`` \`code\` `` instead
|
|
10
|
-
of `` `code` ``). Write the body to a file and pass **`--body-file <path>`**
|
|
11
|
-
to `gh issue create` / `gh pr create` / `gh issue comment` (or the declared
|
|
12
|
-
forge's equivalent) — never inline `--body "…"` or a quoted heredoc. Verify
|
|
13
|
-
with `gh … --json body` that no literal `` \` `` survived. (execute-phase
|
|
14
|
-
subagents already follow this; the conductor must too.)
|
|
15
|
-
- **Never commit red; never merge red.** The gate and the floors are
|
|
16
|
-
unconditional — no flag, mode, or interview answer disables them.
|
|
17
|
-
- **Never request or retain a direct-merge permission.** Fullauto calls only
|
|
18
|
-
the repository wrapper with command-scoped variables; a missing wrapper or
|
|
19
|
-
active guard blocks the run and routes to `init-workspace` upgrade.
|
|
20
|
-
- **No stage ends dirty or unpushed.** The clean close-out check (Mode B
|
|
21
|
-
step 5) is part of every stage: tracked modifications — docs included — are
|
|
22
|
-
committed with the stage, and a PR-backed branch is pushed before the
|
|
23
|
-
iteration logs the stage complete. Merging while anything is uncommitted,
|
|
24
|
-
unpushed, or unpulled is forbidden: push, wait for CI, re-audit, then merge.
|
|
25
|
-
- **The conductor never writes application code.** All implementation flows
|
|
26
|
-
through fresh cheap-tier `execute-phase` workers, one phase per context —
|
|
27
|
-
that keeps the cost model honest and `execute-phase` the single pathway.
|
|
28
|
-
- **Tier discipline.** Compose in-turn only skills at ≤ opus/high;
|
|
29
|
-
implementation goes below the turn tier via explicit subagent model
|
|
30
|
-
overrides; `product-audit` is never run by this skill. `ultracode` is a
|
|
31
|
-
user-owned session setting — recommended, never claimed.
|
|
32
|
-
- **Interview once, then silence.** Mid-run gaps — including a mid-run
|
|
33
|
-
`idea`/`defined` unit's product-half gaps in the DESIGN stage — are resolved
|
|
34
|
-
from the decision record and logged; contradictions park the feature with
|
|
35
|
-
the evidence recorded. Re-interviewing mid-run is forbidden, in DESIGN as in
|
|
36
|
-
every other stage: an undesignable unit is parked (`NEEDS_INPUT` on that
|
|
37
|
-
unit, `state: CONTINUE` on the run), never asked about. The recovery from a
|
|
38
|
-
wrong founding call is a reported stop and a human-restarted run.
|
|
39
|
-
- **Scope discipline.** Defects and ideas discovered mid-run become report
|
|
40
|
-
proposals — never automatically-created issues or in-run side quests. Only
|
|
41
|
-
existing user/forge issues enter the issue sweep.
|
|
42
|
-
- **Stack/architecture/forge agnostic; English artifacts** regardless of the
|
|
43
|
-
interview language; recommendations proportional to the interviewed scale,
|
|
44
|
-
recorded in the project's own docs so every sub-skill discovers them through
|
|
45
|
-
its normal Step 0.
|
|
46
|
-
|
|
47
|
-
**Known limits (stated, not hidden):** subagent overrides pin the model but
|
|
48
|
-
not the effort, so execution subagents inherit the session's effort — cost can
|
|
49
|
-
drift if the session runs high. `/loop`'s stop-on-banner matching should be
|
|
50
|
-
treated as a convenience, not a guarantee — iterations after a terminal banner
|
|
51
|
-
are idempotent no-ops, and the loop can always be stopped manually. Budget caps
|
|
52
|
-
count iterations, not tokens — and the count lives in the machine-local log, so
|
|
53
|
-
it bounds each machine's run, not the run's lifetime across machines. Verdicts
|
|
54
|
-
persist in the run log and feature docs,
|
|
55
|
-
but a crash between PR close-out and review may re-run one receipt check —
|
|
56
|
-
accepted cost, never a correctness risk.
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
### Model routing
|
|
2
|
-
|
|
3
|
-
| Stage | Tier | Mechanism |
|
|
4
|
-
|---|---|---|
|
|
5
|
-
| Interview, founding, roadmap creation | opus/high | this skill's frontmatter; composes `init-workspace` (equal tier), answers pre-fed |
|
|
6
|
-
| Recovery, routing, logging | opus/high | in-turn (tiny token volume; a subagent would add cost, not save it) |
|
|
7
|
-
| JIT feature design (mid-run `idea`/`defined` unit) | opus/high | compose `design-feature` + `plan-feature-scaffold` in-turn (equal tier, deriving only from `SHIP_DECISIONS.md` — no new questions) |
|
|
8
|
-
| JIT feature planning | opus/high | compose `plan-feature` in-turn (its internals are opus/high–medium: ≥ holds) |
|
|
9
|
-
| Product review (REVIEW-SPEC) | opus/high | `review-spec` in a **clean context** (fresh subagent or outside headless call) — never the turn that wrote the product half; tier equals or exceeds the author's, so the ≥ rule holds |
|
|
10
|
-
| Plan review (REVIEW-PLAN) | opus/high | `review-plan` in a **clean context**, same rule; it judges the plan the previous stage froze |
|
|
11
|
-
| Phase execution, single-pass, fixes | **cheap worker** | fresh context per phase following `execute-phase`; Claude branch maps this role to `sonnet`, portable drivers use their validated worker tier |
|
|
12
|
-
| Final review/correction loop | opus/high | compose the manual path `/review-change`, then `/fold-findings` (only on `REVIEW-FAIL`), then re-run `/review-change`; it reuses a current exact-SHA receipt or reviews context-clean, and routes unresolved findings to `triage-issue --prioritize-now` |
|
|
13
|
-
| Merge gate | opus/high | compose `audit-pr` in-turn (the highest-stakes automated verdict; must share one turn with the floor checks) |
|
|
14
|
-
| Forge/git mechanics | — | Bash tool calls; no model judgment involved |
|
|
15
|
-
| Final-report evidence gathering | haiku (optional) | fan-out subagents for grep-shaped per-feature log collection when ultracode is on; synthesis stays opus |
|
|
16
|
-
| `product-audit` | opus/max | **never composed, never imitated by a subagent** — its effort (max) exceeds the conductor's (high) and a subagent override cannot carry `effort: max`. Hand-off only: the report prescribes when to run it. |
|
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
## Portability (agents other than Claude Code)
|
|
2
|
-
|
|
3
|
-
The workflow is the contract; Claude Code features are conveniences. This skill
|
|
4
|
-
leans on them harder than any other — here is the manual equivalent of each:
|
|
5
|
-
|
|
6
|
-
- **No `/loop`** — two equivalent replacements, both vendor-neutral: (a) an
|
|
7
|
-
**external orchestrator** loops `/ship-roadmap --continue` headless and
|
|
8
|
-
routes its native fixed `SHIP:` banner plus closing `→ Next:` block (full
|
|
9
|
-
protocol + driver skeleton in `docs/workflow/ORCHESTRATION.md`); (b) manual
|
|
10
|
-
re-invocation after each iteration. Iterations are
|
|
11
|
-
stateless-by-reconstruction, so any driver is exactly equivalent; stop when
|
|
12
|
-
the first line is a terminal `SHIP:` banner. **Every iteration ending is
|
|
13
|
-
announced** — "iteration complete (normal; re-invoke to continue)" vs a
|
|
14
|
-
parked/terminal reason — so a stop is never ambiguous.
|
|
15
|
-
- **No subagents** — execute phases sequentially: for each phase, one **fresh
|
|
16
|
-
headless invocation (or conversation) on a cheaper model** following the
|
|
17
|
-
installed `execute-phase` SKILL.md for exactly one phase (same two autopilot
|
|
18
|
-
overrides) — the external-driver pattern in `docs/workflow/ORCHESTRATION.md`
|
|
19
|
-
does exactly this. The conductor stages (recover/plan/PR/review/audit) stay
|
|
20
|
-
on your strongest model.
|
|
21
|
-
- **No slash-command menu** — where this skill says `/<skill>`, open that
|
|
22
|
-
skill's `SKILL.md` (wherever your agent installed the skills) and follow it
|
|
23
|
-
literally in the conversation the routing table assigns it (in-turn = this
|
|
24
|
-
conversation; subagent/hand-off = a fresh one).
|
|
25
|
-
- **No per-skill `model:`/`effort:`** — the `#claude` branch's routing table pins these tiers; here, pick tiers yourself:
|
|
26
|
-
judgment stages on your **strongest** model, implementation on a cheaper one,
|
|
27
|
-
and `product-audit` always as its own maximum-effort run.
|
|
28
|
-
- **Provider concurrency limits** — when spawning parallel subagents (or
|
|
29
|
-
parallel headless invocations), cap concurrency at the provider's documented
|
|
30
|
-
parallel-request limit per API key, leaving one slot free for the conductor
|
|
31
|
-
(e.g. a provider allowing 5 concurrent requests → at most 3–4 parallel
|
|
32
|
-
executors). An agentic loop spends one request per tool round-trip, so
|
|
33
|
-
parallel executors also eat the per-minute request budget fast; on a 429,
|
|
34
|
-
reduce parallelism before retrying rather than hammering the limit.
|
|
@@ -1,94 +0,0 @@
|
|
|
1
|
-
### Mode B — One loop iteration: `/ship-roadmap --continue [--fullauto]`
|
|
2
|
-
|
|
3
|
-
Every iteration is stateless-by-reconstruction — no memory is assumed between
|
|
4
|
-
turns:
|
|
5
|
-
|
|
6
|
-
1. **RECOVER.** Read `SHIP_DECISIONS.md` (missing → `SHIP: STOPPED — no run
|
|
7
|
-
policy; run /ship-roadmap first`) and `.ship-run.log` (missing on this
|
|
8
|
-
machine → recreate empty; policy lives in the committed record). **Verify
|
|
9
|
-
the substrate landed:** `SHIP_DECISIONS.md` must exist on the default
|
|
10
|
-
branch — an open `docs/ship-founding` PR means the substrate isn't merged
|
|
11
|
-
yet → `SHIP: BLOCKED` with "merge the founding PR" as the unblock map.
|
|
12
|
-
Read ROADMAP.md; query the forge for open/merged PRs on `feat/*`, `fix/*`,
|
|
13
|
-
`docs/ship-founding` and `docs/ship-report` heads; check git state.
|
|
14
|
-
Reconcile: a feature flips to `done` when its **PR opens** (built, not merged
|
|
15
|
-
— see the PR stage), so a `done` row with an open PR is awaiting a human merge
|
|
16
|
-
(default mode), not finished shipping. A **merged** PR needs no status change
|
|
17
|
-
(already `done`) — it means *shipped*, and **unblocks its dependents** + counts
|
|
18
|
-
toward `SHIP: COMPLETE`. The done-flip rides the PR-bound commit, never a lone
|
|
19
|
-
commit on the default branch. A dirty feature branch from a crashed phase
|
|
20
|
-
is handed to the next phase subagent to finish or restart (counts against
|
|
21
|
-
the red-gate retry cap). Uncommitted changes on the default branch confined
|
|
22
|
-
to `docs/features/<NN-slug>/` + ROADMAP.md that match an in-flight roadmap
|
|
23
|
-
row are the loop's own planning output — resume that feature; the
|
|
24
|
-
dirty-default stop fires only for changes matching no roadmap unit.
|
|
25
|
-
2. **STOP-CHECK.** Evaluate the stop conditions (below). Terminal → write or
|
|
26
|
-
refresh the final report, open the report PR, print the `SHIP:` banner +
|
|
27
|
-
status table, end the turn.
|
|
28
|
-
3. **SELECT one unit.** Priority order, first match wins:
|
|
29
|
-
1. **Urgency labels first (feature 15, injection-safe).** Read
|
|
30
|
-
`workflow-status`'s `detail.urgent` (labels-only, presence-only —
|
|
31
|
-
never derived from issue text; see `skills/triage-issue/SKILL.md`, the
|
|
32
|
-
sole owner of the `urgent`/`fix-next` vocabulary):
|
|
33
|
-
- Any open issue labeled **`fix-next`** → its fix jumps to the head of
|
|
34
|
-
the queue exactly like a blocking fix below (`plan-fix` →
|
|
35
|
-
`execute-phase --fix`), **no interrupt** of the in-flight unit — it
|
|
36
|
-
waits for the current stage to finish this iteration, then is
|
|
37
|
-
SELECTed next.
|
|
38
|
-
- Any open issue labeled **`urgent`** → run the canonical pause-vs-finish
|
|
39
|
-
rubric in `docs/workflow/ORCHESTRATION.md` **by reference, never
|
|
40
|
-
forked here** — feed it the issue content plus `detail.urgent
|
|
41
|
-
.interruptibility` for the current in-flight unit.
|
|
42
|
-
`INTERRUPT_NOW` → park the in-flight unit (WIP commit + `progress.md`
|
|
43
|
-
note, same as any voluntary park) and SELECT the urgent issue's fix as
|
|
44
|
-
this iteration's unit instead. `FINISH_FIRST` → this iteration
|
|
45
|
-
proceeds normally (steps below); the urgent fix is queued head-of-line
|
|
46
|
-
for the **next** iteration, same as `fix-next`.
|
|
47
|
-
- No `urgent`/`fix-next` issues in `detail.urgent` → fall through to the
|
|
48
|
-
normal priority order below.
|
|
49
|
-
2. **Blocking fixes first.** A fix-index entry classified fix-now whose
|
|
50
|
-
subject blocks the next startable feature (same module, a dependency's
|
|
51
|
-
defect, or a red gate cause) → its fix is the selected unit
|
|
52
|
-
(`plan-fix` → `execute-phase --fix` through the normal stages). Fixes
|
|
53
|
-
that block nothing wait for the report's triage batch.
|
|
54
|
-
3. An in-progress feature's next pending stage.
|
|
55
|
-
4. The next feature at status `idea` **or** `planned` whose depends-on rows
|
|
56
|
-
are all **merged** (forge state, not merely `done` — a `done` dep with
|
|
57
|
-
an open PR isn't on the default branch yet, so a dependent cut from it
|
|
58
|
-
would lack its code). A `defined`-but-not-`planned` row is treated the
|
|
59
|
-
same as `idea` here — its design exists but its planning artifacts
|
|
60
|
-
don't, so it still needs a scaffold pass before PLAN.
|
|
61
|
-
**Verify the closure transitively:** a dep row marked merged whose own
|
|
62
|
-
dependencies aren't merged means the roadmap's statuses are inconsistent
|
|
63
|
-
→ `SHIP: STOPPED` (substrate invariant broken), never build on top of it.
|
|
64
|
-
→ `idea`/`defined`: DESIGN first (see ADVANCE). `planned`: → REVIEW-SPEC/
|
|
65
|
-
REVIEW-PLAN if its receipt for that stage is missing or stale, else PLAN/EXECUTE
|
|
66
|
-
directly.
|
|
67
|
-
5. **Issue sweep — features exhausted, run NOT over.** Every roadmap feature
|
|
68
|
-
is `done` **and merged** but the sweep hasn't completed → the run
|
|
69
|
-
continues with issues; finishing the features is not finishing the run:
|
|
70
|
-
1. **INVENTORY (once per run, its own iteration).** Enumerate (a) every
|
|
71
|
-
open forge issue and fix-index entry; (b) every *documented residue*
|
|
72
|
-
the run itself generated — each feature's `known-issues.md`, the
|
|
73
|
-
trade-offs in `decisions.md`, and every review report's
|
|
74
|
-
proposals/trade-offs. Residue without an existing issue remains a
|
|
75
|
-
deduplicated **proposal** in the report; the run never creates backlog
|
|
76
|
-
to make inventory look complete. Log existing issue numbers and
|
|
77
|
-
proposal sources separately.
|
|
78
|
-
2. **TRIAGE (compose `triage-issue` in-turn, equal tier).** Classify
|
|
79
|
-
each existing inventoried issue against the CURRENT codebase. fix-now → it
|
|
80
|
-
becomes a selectable unit; postpone / wontfix / promote-to-feature →
|
|
81
|
-
the dated verdict is recorded on the issue and carried into the
|
|
82
|
-
report (promotions and untracked residue become report proposals,
|
|
83
|
-
never in-run scope or automatically-created issues).
|
|
84
|
-
3. **SHIP the fix-now issues** one unit at a time through the normal
|
|
85
|
-
stages (`plan-fix` → REVIEW-PLAN → EXECUTE (`--fix`) → PR → REVIEW → AUDIT), same
|
|
86
|
-
budget caps, floors, and merge policy as features.
|
|
87
|
-
6. Nothing startable → `SHIP: BLOCKED` with the **unblock map** ("merging
|
|
88
|
-
issue `#<n>` unblocks features `05` and `07`") and the resume command.
|
|
89
|
-
|
|
90
|
-
`execute-phase`'s own dependency gate stays active inside every subagent —
|
|
91
|
-
it's the belt to this braces. **The autopilot never passes `--force`:** a
|
|
92
|
-
gate stop inside a subagent parks the feature with the unmet chain recorded;
|
|
93
|
-
forcing through unmet dependencies is a human-only decision, made outside
|
|
94
|
-
the loop.
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
### Stop conditions
|
|
2
|
-
|
|
3
|
-
| Banner | Fires when |
|
|
4
|
-
|---|---|
|
|
5
|
-
| `SHIP: COMPLETE` | Every roadmap feature is `done` **and its PR merged** (default mode: the human merged them all; `--fullauto`: merged under the floors) — `done` alone is not enough, since it only means *built + PR open* — **AND the issue sweep ran to completion**: existing issues inventoried/triaged, every fix-now issue shipped or parked, and untracked residue deduplicated as report proposals without creating backlog. Features merged but sweep pending → the run is NOT complete. Report written, report PR open. |
|
|
6
|
-
| `SHIP: BLOCKED` | Everything remaining is `done`-but-pr-open awaiting human merges, or planned with unmerged deps (default mode); or a parked feature transitively blocks the rest. Always includes the unblock map. |
|
|
7
|
-
| `SHIP: STOPPED` | Budget/iteration cap; a Round-5 milestone stop line; substrate invariant broken (gate unrunnable, roadmap unparseable, unexplained dirty default branch, decision record missing); forge unavailable (no stage that depends on PR state may proceed on guesses). |
|
|
8
|
-
| (feature parked, run continues) | Repeated red gate (retry cap), review ping-pong (2 cycles), audit ping-pong (2 cycles), capacity guard (3 partials), planning contradiction, **undesignable-from-record** (DESIGN stage `NEEDS_INPUT` — the recorded gap is a human-only unpark, never a mid-run re-ask). |
|
|
9
|
-
| **Systemic drift stop** | `review-change` flags SPEC drift on **two consecutive features** → the locked founding assumptions are probably stale; the whole run stops rather than auto-merging a compounding error. |
|
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
### Final report
|
|
2
|
-
|
|
3
|
-
Written by the terminal iteration to `docs/features/SHIP_REPORT_<date>.md` on a
|
|
4
|
-
`docs/ship-report` branch as a docs-only PR (default: human merges; `--fullauto`:
|
|
5
|
-
audit-gated like any PR), and printed in full under the banner:
|
|
6
|
-
|
|
7
|
-
1. **Run summary** — mode, iterations used vs cap, stop reason, feature counts
|
|
8
|
-
(merged / `done`-awaiting-merge / parked / not started).
|
|
9
|
-
2. **Per-feature outcomes** — size planned vs final, phases, gate history,
|
|
10
|
-
review findings folded vs postponed, audit verdict + SHA, PR + final state,
|
|
11
|
-
merged by human or autopilot.
|
|
12
|
-
3. **Issues** — the sweep's existing-issue inventory and outcomes: fix-now issues
|
|
13
|
-
shipped (PR links), postponed/wontfix verdicts with the trigger that
|
|
14
|
-
should reopen each (feeds `triage-issue`'s verification model), and
|
|
15
|
-
anything the sweep could not finish (budget/parked) as the explicit
|
|
16
|
-
remaining triage batch. Untracked residue is listed separately as proposals;
|
|
17
|
-
the run created no backlog for it.
|
|
18
|
-
4. **New feature proposals** — capabilities discovered during the build that
|
|
19
|
-
serve the product goal (Round 1 quoted as the yardstick), each sized with a
|
|
20
|
-
suggested roadmap slot. Recommend-only.
|
|
21
|
-
5. **Residual risks** — weak test areas, `--fullauto` merges deserving a second
|
|
22
|
-
look, parked features and why, silent decisions with outsized consequences.
|
|
23
|
-
6. **Manual-verification checklist** — the deduplicated union of every review
|
|
24
|
-
checkpoint's manual checks plus audit notes: what no gate proved.
|
|
25
|
-
7. **Going forward** — concrete `product-audit` cadence for this project
|
|
26
|
-
(first one now if ≥2–3 features merged; then ~every 5 or pre-release), and
|
|
27
|
-
the suggested command sequence to continue, closed with the canonical block:
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
→ Next: <merge the open PRs | /triage-issue <batch> | /plan-feature --next>
|
|
31
|
-
· accepted proposals → /plan-feature · product-audit due → /product-audit
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
Closing line, verbatim policy: **this report recommends; the human decides.**
|