From 06eaf5820a84ca64b162cb9eb51ecbc917a8fc99 Mon Sep 17 00:00:00 2001 From: richsak Date: Sun, 26 Apr 2026 15:54:59 -0700 Subject: [PATCH 1/2] feat: add webster-weekly-council library skill Library-shape conversion of prompts/second-wbs-session.md so operators run the weekly council pass via /webster-weekly-council. SKILL.md is a slim phase index; nine references/ files hold per-phase bash blocks loaded on demand; two skill-local scripts/ extract the reusable polling helper and the planner-JSON parser. The 662-line single-page prompt remains intact as the locked source-of-truth runbook. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/webster-weekly-council/SKILL.md | 66 +++++++++++ .../references/branch.md | 25 ++++ .../references/failure-modes.md | 29 +++++ .../references/fan-out.md | 86 ++++++++++++++ .../references/genealogy.md | 76 ++++++++++++ .../references/planner.md | 108 +++++++++++++++++ .../references/preflight.md | 98 ++++++++++++++++ .../references/publish.md | 109 ++++++++++++++++++ .../references/redesign.md | 63 ++++++++++ .../references/seed-history.md | 74 ++++++++++++ .../references/verify.md | 63 ++++++++++ .../scripts/extract-planner-json.py | 26 +++++ .../scripts/run-agent-session.sh | 85 ++++++++++++++ 13 files changed, 908 insertions(+) create mode 100644 skills/webster-weekly-council/SKILL.md create mode 100644 skills/webster-weekly-council/references/branch.md create mode 100644 skills/webster-weekly-council/references/failure-modes.md create mode 100644 skills/webster-weekly-council/references/fan-out.md create mode 100644 skills/webster-weekly-council/references/genealogy.md create mode 100644 skills/webster-weekly-council/references/planner.md create mode 100644 skills/webster-weekly-council/references/preflight.md create mode 100644 skills/webster-weekly-council/references/publish.md create mode 100644 skills/webster-weekly-council/references/redesign.md create mode 100644 skills/webster-weekly-council/references/seed-history.md create mode 100644 skills/webster-weekly-council/references/verify.md create mode 100755 skills/webster-weekly-council/scripts/extract-planner-json.py create mode 100755 skills/webster-weekly-council/scripts/run-agent-session.sh diff --git a/skills/webster-weekly-council/SKILL.md b/skills/webster-weekly-council/SKILL.md new file mode 100644 index 0000000..b016e3e --- /dev/null +++ b/skills/webster-weekly-council/SKILL.md @@ -0,0 +1,66 @@ +--- +name: webster-weekly-council +description: Run one full Webster weekly landing-page council pass — pre-flight, planner, 6 parallel managed-agent critics, genealogy gap-detection, redesigner synthesis, and draft PR. Use when the operator runs /webster-weekly-council or asks for the weekly Webster council run. Replaces `wbs @prompts/second-wbs-session.md` as the primary operator path; the prompt remains the readable single-page fallback runbook. +--- + +# Webster Weekly Council (Library) + +One full council pass: planner → 6 parallel critics → genealogy → redesigner → draft PR. **30–50 min wall-clock. ~$0.16–0.25 in API tokens per run.** + +> **Override default Operating Loop.** This is a council-run session. Execute the phases below end-to-end. Do NOT call `forge isolation list`, do NOT scan `FEATURES.md` for `todo` rows, do NOT enter a feature-implementation loop. The phases are sequential; do not skip ahead. + +## Phase index — load on demand + +Read `references/preflight.md` first. After that, load only the reference for the phase you're executing. Do not load all references up front. + +| # | Phase | Wall-clock | Reference | +| --- | ---------------------------------------------------- | ---------- | ----------------------------- | +| 0 | Pre-flight + session constants | <1 min | `references/preflight.md` | +| 1 | Seed 10-week mock analytics history (idempotent) | 2 min | `references/seed-history.md` | +| 2 | Prepare shared `council/` branch | 1 min | `references/branch.md` | +| 3 | Run planner (Opus 4.7) → `plan.md` + memory event | 3–5 min | `references/planner.md` | +| 4 | Fan-out 6 parallel managed-agent sessions | 15–20 min | `references/fan-out.md` | +| 5 | Verify findings (gate before redesigner) | 2 min | `references/verify.md` | +| 5.5 | Critic Genealogy gap-detection (fail-open) | 0–10 min | `references/genealogy.md` | +| 6 | Redesigner session → `proposal.md` + `decision.json` | 5–10 min | `references/redesign.md` | +| 7+8 | Open draft PR + write checkpoint | 1 min | `references/publish.md` | +| — | If a step fails | — | `references/failure-modes.md` | + +## Always-true invariants + +These hold across every phase. Do not break them. + +1. **`ANTHROPIC_API_KEY` is fetched from macOS keychain into a scoped bash variable.** Never read it from the operator's shell env — that would bill `claude -p` and any Forge call against API credits instead of the Max sub. +2. **Registration artifacts must exist before fan-out.** `environments/webster-council-env.id`, `context/monitor/id.txt`, `context/redesigner/id.txt`, and the 5 critic id files. If missing, run `prompts/first-wbs-session.md` first. +3. **All writes go to `council/$WEEK_DATE`.** Local working tree and remote committers (critics + redesigner via GitHub MCP) all target the same branch. The orchestrator only creates the branch locally; critics' system prompts handle remote create-or-skip. +4. **Phase 3 (planner) is fail-closed.** If planner errors, halt before fan-out. Redesigner has no findings to synthesize without it. +5. **Phase 5.5 (genealogy) is fail-open.** Errors log and continue. Redesigner runs against the 5 original critic findings if genealogy fails. +6. **Phase 5 (verify) is the redesigner gate.** If <3 critics produced non-stub findings, abort before spending redesigner tokens. +7. **Findings are sovereign over planner direction_hint.** Critics report what they find regardless of plan; redesigner uses the hint as a weighting input but CRITICAL/HIGH critic evidence overrides. +8. **Don't merge the PR.** It opens as a draft. Human review = approval. The operator's job ends at PR-open + checkpoint. + +## Helper scripts ("unlocked tools") + +These are reusable across phases. Each is a self-contained CLI; pass args from the bash blocks in references. + +- **`scripts/run-agent-session.sh`** — create a managed-agent session, send a `user.message`, poll until idle/completed/timeout. Used 7× across phases 4 and 6 (monitor + 5 critics + redesigner). Exit code: `0` ok, `1` failed, `2` timeout. +- **`scripts/extract-planner-json.py`** — pull the JSON block out of `history//plan.md` for the optional `new_critic_request` extraction in phase 3. + +Both scripts are skill-local under `skills/webster-weekly-council/scripts/`. Repo-level helpers (`scripts/planner-invoke.ts`, `scripts/planner-context.ts`, `scripts/critic-genealogy.ts`, `scripts/validate-findings.ts`) are unchanged and still called by reference bash blocks. + +## Production invariant — `prompts/second-wbs-session.md` + +The 662-line bash-in-markdown prompt is the immutable production runbook. This skill is the operator surface; the prompt is the source-of-truth runbook. They produce the same artifacts. + +- The prompt is locked by `scripts/__tests__/sim-council.test.ts:75` — `git diff prompts/second-wbs-session.md` must be empty. +- Nicolette's live council on `main` runs the prompt via `wbs @prompts/second-wbs-session.md`. +- If the skill drifts from the prompt, **fix the skill** — never the prompt. + +## Quick start + +1. Load `references/preflight.md` → run pre-flight + session constants. +2. Load each phase reference in order (1 → 2 → 3 → 4 → 5 → 5.5 → 6 → 7+8). +3. If any phase fails, load `references/failure-modes.md` and follow the named recovery. +4. Final state: draft PR open, checkpoint committed under `.claude/checkpoints/`. + +If a phase genuinely cannot be expressed as a skill instruction, surface `[STUCK]` per `AGENTS.md` and stop. Visible struggle > invisible corner-cutting. diff --git a/skills/webster-weekly-council/references/branch.md b/skills/webster-weekly-council/references/branch.md new file mode 100644 index 0000000..2cb582d --- /dev/null +++ b/skills/webster-weekly-council/references/branch.md @@ -0,0 +1,25 @@ +# Phase 2 — Prepare shared `council/` branch + +**~1 min.** + +All 6 parallel workers + the redesigner commit to `$BRANCH` via GitHub MCP. The critics' system prompts already create-or-skip the branch via `create_branch` MCP (422-on-exists is treated as success), so this local setup is about keeping your working tree consistent — not about creating the branch remotely. + +```bash +git checkout main +git pull +git fetch origin +if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then + echo "Branch $BRANCH already exists on origin — reusing" + git checkout -B "$BRANCH" "origin/$BRANCH" +else + git checkout -B "$BRANCH" main + git push -u origin "$BRANCH" +fi +``` + +## Why both branches are valid + +- **Branch already exists**: a prior attempt this week (failed mid-run, or genealogy/redesigner re-run). Reuse so the new orchestrator-side commits land alongside the existing critic findings. +- **Branch missing**: fresh weekly run. Create from `main` and push so MCP-side critic commits don't race local creation. + +The local working tree must match `origin/$BRANCH` before phase 3, otherwise the planner commit in phase 3 would diverge from the branch the critics will read. diff --git a/skills/webster-weekly-council/references/failure-modes.md b/skills/webster-weekly-council/references/failure-modes.md new file mode 100644 index 0000000..27fcc24 --- /dev/null +++ b/skills/webster-weekly-council/references/failure-modes.md @@ -0,0 +1,29 @@ +# Failure modes — recovery guide + +The skill is idempotent end-to-end. Any phase can be re-run after fixing the named cause. + +| Failure | Recovery | +| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Pre-flight abort** (key/keychain/registration artifacts) | Fix the named prerequisite. Re-run the whole skill — preflight is idempotent and every later phase checks for its own outputs before running. | +| **Planner fails (phase 3)** | Run halts before fan-out. Read `tmp/logs/planner.log`, fix the named context/API/JSON problem, re-run from phase 3. Do not continue without `history/$WEEK_DATE/plan.md`. | +| **One critic times out (phase 4)** | Re-run only that critic: `bash skills/webster-weekly-council/scripts/run-agent-session.sh