engsys 1.0.0

package/core/commands/implement-project.md

@@ -0,0 +1,40 @@
+---
+description: Walk a tracker project phase-by-phase, opening one PR per phase. Pauses on material code-review findings, otherwise continues autonomously.
+argument-hint: <project-number>
+---
+
+Use the **isabelle** subagent, following the per-issue cycle in [/implement-issue](implement-issue.md) and the outer loop in [.claude/workflows/implement-project-workflow.md](.claude/workflows/implement-project-workflow.md).
+
+Board reads/writes (Phase/Priority/Owner/Status) go through the project's installed **issue-tracker skill** (`.claude/skills/issue-tracker-*/`) and its `query-board` / `set-board-field` operations — the same flow works whether the tracker is GitHub or Linear. PR creation and CI stay on `gh` / GitHub.
+
+Project: #$ARGUMENTS
+
+Isabelle should:
+
+1. **Read the board** — use the issue-tracker skill's `query-board` operation to fetch fields + items (GitHub: `gh api graphql`). The project **must** have a `Phase` single-select field with `P<n>: <name>` options. If missing, stop and tell the operator to run [/generate-project](generate-project.md) (Jody) first.
+2. **Pick the next batch** — lowest-numbered phase with open issues. Print the plan (phase name, issue list, remaining phases). Do not wait for approval; the slash command is the authorization.
+3. **Walk one phase** — follow the [/implement-issue](implement-issue.md) cycle end-to-end: claim issues (issue-tracker skill `update-issue`), create worktree `agent/project-$ARGUMENTS-phase-<n>-<slug>`, set Status=In Progress (skill `set-board-field`), one commit per issue with `(#<num>)` references, full pre-push gate, **run a local code review with the built-in `/code-review` skill before push** (fix Critical + Warning, re-run clean), push once, create the PR on `gh pr create` and link/close work items per the skill's `link-pr` operation (GitHub: `Closes #<num>` one per line), then persist the local review findings onto the work item with the skill's `comment-issue` operation.
+4. **Triage review findings** (done locally before push) — classify each:
+   - **Material** (real bug / security / behavior change) → fix, re-run review
+   - **Cosmetic** → fix if trivially safe, otherwise note in the findings comment
+   - **Wrong** → note why in the findings comment
+5. **Objective independent review (orchestrator — before any merge)** — once Isabelle's phase PR is open and her local review is clean, the **orchestrator** (not Isabelle) launches a *fresh, independent* reviewer subagent — general-purpose on **Opus**, with **no stake in the code** — to objectively review the PR. It must: re-run the full gate from scratch (confirm/refute the author's numbers), verify **each** issue's acceptance criteria against the diff, probe security/correctness, and hunt for regressions and reconciliation artifacts (duplicate/dead code, dropped work, stray exports). It ends with a decisive **`VERDICT: CLEAN`** (no Critical/Warning — safe to merge) or **`VERDICT: FINDINGS`** (severity-tagged, `file:line`). Never merge a phase PR that has not passed this gate.
+6. **Continue or pause** — after the objective review returns:
+   - **CLEAN** → merge the phase PR (the human, or the orchestrator only with explicit operator authorization), mark phase items Status=Done (skill `set-board-field`), loop back to step 2 for the next phase.
+     - ⚠️ **Status=Done can auto-close the linked issue _pre-merge_.** If the board has the built-in **"Auto-close issue"** workflow enabled, setting an item's **Status=Done** immediately **closes the linked issue — even while its PR is still an unmerged draft**. Only flip Status=Done **after** the phase PR has actually merged — or, better, **disable that board workflow** so issue-closed tracks the real merge. Phases that must stay open through review/sign-off (e.g. a security-gated phase) will otherwise need their issues reopened.
+   - **FINDINGS** (Critical/Warning) → route back to Isabelle to fix + re-review, or **stop** and report if it exposes a product/architecture decision
+   - Local *or* objective review errored / couldn't run → **stop** and report
+   - Three consecutive autonomous phases done → **courtesy pause**, report progress, ask operator before continuing
+7. **Done** — when every phase has Status=Done (or In Review), print the completion summary with PR links per phase.
+
+Hard rules:
+
+- **No merge without a `CLEAN` objective review** (step 5). The human merges every batch — or the orchestrator, only with explicit operator authorization.
+- Does **not** invent phases. If the `Phase` field is empty or missing, stop (no item may carry an empty Phase).
+- One phase = one branch = one worktree = one PR. Per `CLAUDE.md` § Git / PR conventions.
+- Work-item linking per the skill's `link-pr` operation (GitHub: one `Closes #<num>` per line — a comma-list only closes the first issue).
+- Use `tmp/` for commit messages and PR bodies — never HEREDOC.
+
+Reflection on pause: if the loop exposed a reusable failure or missing Jody field, update the relevant `CLAUDE.md` / `docs/agent-lessons/` before handoff.
+
+**When the project's LAST PR merges** (all phases done): run the full **Project Closeout Ceremony** — [/project-closeout $ARGUMENTS](project-closeout.md). Verify all PRs merged → clean up worktrees/branches → mine ALL local-review findings PR comments (+ any static-analysis alerts) across the project for recurring mistake families → memorialize durable lessons. Don't stop at the completion report.

package/core/commands/naturalize.md

@@ -0,0 +1,61 @@
+---
+description: Fill this project's CLAUDE.md PROJECT-FACTS and replace naturalize placeholders — project facts only, never folder/plumbing setup.
+argument-hint: (none)
+---
+
+You are naturalizing this project's engineering system. The installer has already
+created all directories, copied agents/commands/skills, and rendered the
+templates. **Your job is project facts only — do NOT create directories, move
+files, or re-do any plumbing.** If structure is missing, that's an installer bug;
+report it, don't paper over it.
+
+Do this:
+
+1. **Discover the project.** Read the repo: package manifests, build/test config,
+   CI workflows, IaC, README, existing docs. Identify: services/runtimes, the
+   build & verify toolchain, the cloud/stack, key paths, and any domain-specific
+   hard rules (the things that, if violated, break correctness or trust).
+
+2. **Fill the PROJECT-FACTS region of `CLAUDE.md`.** Edit ONLY between
+   `<!-- ENGSYS:PROJECT-FACTS:START -->` and `<!-- ENGSYS:PROJECT-FACTS:END -->`.
+   Write tight, high-signal facts: project shape, the exact pre-push/precheck
+   command, invariants, where architecture docs and ADRs live. Everything outside
+   that region is installer-owned and will be regenerated by `engsys update`.
+
+3. **Replace `<naturalize: ...>` placeholders.** Grep the installed tree
+   (`.mcp.json`, `.claude/hooks/*`, stack fragments echoed into CLAUDE.md) for
+   `<naturalize:` / `<proj>` / `<rg>` / `<env>` / `<suffix>` and substitute real
+   values. For iOS, that's the Xcode project path, scheme, simulator UDID, bundle
+   id; for cloud, the resource group / account / naming suffix.
+
+4. **Fold in imported AI config (if any).** If `docs/imported-ai-config/` exists,
+   the installer found pre-existing Copilot/Cursor/etc. config and snapshotted it.
+   Read each file and:
+   - **Rules / instructions** (`copilot-instructions.md`, `.cursor/rules/*.mdc`,
+     `.cursorrules`) → fold the durable, still-true rules into the PROJECT-FACTS
+     region (or a nested `CLAUDE.md`). Drop anything redundant with engsys or the
+     stack packs; don't blindly copy.
+   - **Agent definitions** (`.github/agents/*.agent.md`) → if a persona is worth
+     keeping and engsys has no equivalent, convert it to a `.claude/agents/<name>.md`
+     (engsys frontmatter: `name`, `description`, `model`; strip editor-specific tool
+     IDs). If engsys already covers it, note that and skip.
+   - When done, delete `docs/imported-ai-config/` and (with the human's OK) the
+     now-superseded originals.
+
+5. **Reconcile the project's own agents.** The install report lists any
+   pre-existing `.claude/agents/` (and commands/skills) the project already had —
+   engsys preserved them untouched. For each: keep it (distinct role), merge its
+   guidance into the matching engsys agent, or rename on a name conflict. Never
+   silently shadow one with the other.
+
+6. **Tune `naturalize.hook_patterns` if needed.** If discovery surfaced sensitive
+   files (schemas, specs, IaC entrypoints), make sure
+   `.claude/hooks/post-edit-reminders.sh` nudges on them — edit the project's
+   `engsys.config.yaml` and re-run `engsys update`, rather than hand-editing the
+   generated hook (which `update` regenerates).
+
+7. **Report** what you set, what you folded in or reconciled, and list anything you
+   couldn't determine so the human can confirm. Then suggest running
+   `engsys verify` to confirm no drift.
+
+Be factual. Don't invent stack details you didn't verify in the repo.

package/core/commands/pre-push.md

@@ -0,0 +1,29 @@
+---
+description: Run the project's full local pre-push gate (build/lint/format/test plus any path-gated checks for migrations, IaC, and containers)
+---
+
+Run the project's pre-push gate / precheck per `CLAUDE.md` § Pre-push gate. **Don't push if any step fails** — fix locally first.
+
+The exact gate commands are **defined by the project** (in `CLAUDE.md` and, where present, a `precheck`/`pre-push` task that the local pre-push hook runs). This command is the discipline; the project supplies the concrete commands.
+
+1. **Identify touched paths** since `origin/main`:
+
+   ```bash
+   git diff --name-only origin/main...HEAD
+   ```
+
+2. **Always run the core gate** (mirrors CI) — the project's:
+   - build / typecheck
+   - lint
+   - format check
+   - unit tests
+
+   Prefer the project's single precheck entrypoint if it has one (it is usually diff-driven and runs only the relevant gates).
+
+3. **If database migrations were touched** — additionally build the data layer and apply the migration against a local database to confirm the SQL/schema applies cleanly.
+
+4. **If infrastructure-as-code was touched** — run the project's IaC validation / synth / plan step (cloud-agnostic: whatever the active stack's skill pack defines).
+
+5. **If a container build file was touched** — smoke-build the image. A build failure (missing COPY, bad layer) blocks the push; runtime env/DB errors when running the image are expected and OK.
+
+Report green ✓ / red ✗ per step. If everything green, you're cleared to push.

package/core/commands/prep-review-collect.md

@@ -0,0 +1,130 @@
+---
+description: Pull the current Drive doc body back, render feedback.md, classify comments, force operator resolution on disagreements
+argument-hint: <slug>
+---
+
+Collect feedback on a published review. Full workflow reference: [.claude/workflows/review-workflow.md](.claude/workflows/review-workflow.md).
+
+Slug: $ARGUMENTS
+
+> Tooling: uses the project's configured **document-drive MCP**. Tool names are project-defined; the steps below are tool-agnostic.
+
+## Steps
+
+1. **Load state**: read `docs/reviews/<slug>/state.yaml`. Validate:
+   - Exists?
+   - `phase == published` or `feedback-collected` (latter = re-run; that's fine, idempotent).
+   - `drive.file_id` present.
+
+2. **Export the Drive doc as `.docx`** (preserves comments):
+   - Download/export the file as `.docx` (the export MIME type that preserves comments).
+   - Decode the returned base64 and write to `docs/reviews/<slug>/drive-export.docx`.
+   - Also pull a clean text/markdown rendering of the body (used for the diff in step 3 — cleaner than parsing .docx XML for body text).
+
+3. **Diff the body against `package.md`** (the snapshot we uploaded):
+   - Read `docs/reviews/<slug>/package.md`.
+   - Compute a section-level diff against the body text from step 2. For each H2/H3 section: classify as `unchanged | edited | added | removed`.
+   - For edited sections, capture both the original and current text.
+
+4. **Extract comments from the `.docx`**:
+   - Use a docx-parsing skill, or unzip directly — `word/comments.xml` for comment bodies + authors, `word/document.xml` for the anchors mapping comment-id → anchored text.
+   - For each comment, capture: id, author, anchored selection text, comment body, resolved state if present.
+   - **Caveat**: drive `.docx` exports typically include **open** comments; **resolved** comments may be missing. If the comment count looks lower than expected, surface this to the operator and offer the paste-fallback (step 5).
+
+5. **Fallback / supplement** — present what was extracted and ask:
+
+   > "I pulled N comments from the .docx export. If you've resolved any in the doc already (those may not be in the export), paste their text here and I'll include them. Otherwise reply 'continue' and I'll classify."
+
+6. **For each piece of feedback** (body change or comment), classify:
+   - **`clarification`** — a question or small ask; will be folded into the next draft.
+   - **`disagreement`** — pushback on a decision; needs an explicit operator call (accept / reject / explore-3rd-option).
+   - **`plus_one`** — endorsement, no action needed.
+   - **`side_discussion`** — adjacent thought, tracked as a follow-up, not blocking.
+
+7. **For every `disagreement`, force operator resolution**:
+   - Present the disagreement, the proposer (if known), and the surrounding context.
+   - Ask: "Accept and revise the proposal, reject (keep original), or explore a third option?"
+   - If "explore" → capture the operator's new direction.
+   - Record the resolution in `docs/reviews/<slug>/decisions.md` (create or append).
+   - Do **not** proceed to finalize until all disagreements have resolutions.
+
+8. **Render `docs/reviews/<slug>/feedback.md`**:
+
+   ```markdown
+   # Feedback — <slug>
+
+   Collected: <timestamp>
+   Source: <web_view_link>
+
+   ## Summary
+
+   - N clarifications
+   - M disagreements (X resolved, Y unresolved)
+   - K plus-ones
+   - L side discussions
+
+   ## Per-section feedback
+
+   ### <Section title>
+
+   **Status:** edited | commented | unchanged
+
+   **Original (excerpt):**
+
+   > ...
+
+   **Current (excerpt):**
+
+   > ...
+
+   **Comments:**
+
+   - [clarification] <text> — <author> — _operator note: ..._
+   - [disagreement] <text> — <author> — **resolved: accept** (see decisions.md)
+
+   ## Plus-ones
+
+   - <author>: <text or "👍 on announcement">
+
+   ## Side discussions (tracked as follow-ups)
+
+   - <text> — <author>
+   ```
+
+9. **Update `state.yaml`**:
+
+   ```yaml
+   phase: feedback-collected
+   feedback:
+     collected_at: <now ISO>
+     body_changed: true|false
+     comment_count: N
+     classification:
+       clarification: N
+       disagreement: M
+       plus_one: K
+       side_discussion: L
+     unresolved_disagreements: 0
+   ```
+
+10. **Report back**: brief summary (counts per category), highlight any unresolved disagreements, and the next step:
+    - All resolved → "Ready for `/prep-review-finalize <slug>`."
+    - Unresolved remain → "Resolve N disagreements before finalize. Re-run this command after."
+
+11. **Propose a commit message**:
+
+    ```text
+    docs(reviews): collect feedback for <slug>
+    ```
+
+## Tool notes
+
+- Drive: export as `.docx` (for comments) + a clean body-text read (for the diff). No writes to Drive.
+- No chat calls in this phase.
+- The classification step is judgment work — don't rubber-stamp. If a comment reads ambiguous, ask the operator before classifying.
+
+## Important
+
+- The `.docx` export typically gives you open comments. If the operator's review pattern resolves comments inline before collect runs, expect to need the paste-fallback. Note this in the announcement (workflow doc has the template).
+- `decisions.md` becomes part of the ADR context in finalize — it's the trail of "we considered X, chose Y."
+- Don't auto-commit.

package/core/commands/prep-review-finalize.md

@@ -0,0 +1,121 @@
+---
+description: Draft the ADR from a reviewed proposal, close the loop in chat, promote the final spec to docs/specs/
+argument-hint: <slug>
+---
+
+Close out a review: ADR + chat thread reply + promote the final spec. Full workflow reference: [.claude/workflows/review-workflow.md](.claude/workflows/review-workflow.md).
+
+Slug: $ARGUMENTS
+
+> Tooling: uses the project's configured **document-drive MCP** and **chat MCP**. Tool names are project-defined; the steps below are tool-agnostic.
+
+## Steps
+
+1. **Load state**: read `docs/reviews/<slug>/state.yaml`. Validate:
+   - `phase == feedback-collected`.
+   - `feedback.unresolved_disagreements == 0` (else bail: "Run `/prep-review-collect <slug>` again — N disagreements still unresolved.").
+   - `decisions.md` exists if any disagreements were recorded.
+   - `feedback.md` exists.
+
+2. **Gather all inputs**:
+   - `source.md` (original)
+   - `package.md` (what went to Drive)
+   - Current Drive body (read via the drive MCP using `drive.file_id`)
+   - `feedback.md` (classifications + per-section)
+   - `decisions.md` (operator's resolutions on disagreements)
+
+3. **Determine the next ADR number**:
+   - List `docs/architecture/adr/*.md`, parse the `NNN-` prefix, take max + 1.
+   - Watch for any existing collision pattern (e.g. two files sharing a number). Confirm with the operator if there's ambiguity.
+
+4. **Read 2–3 recent ADRs** for voice and structure. Match the format:
+   - `# ADR-NNN: <title>`
+   - Header table: Status | Date | Context | Related
+   - `## Context` (3–5 bullets)
+   - `## Decision N — <sub-title>` sections (often a table for enums/options)
+   - `## Consequences` (Easier / Harder bullets)
+   - Optional `## Follow-up` (out-of-scope side-discussions go here)
+
+5. **Draft the ADR** at `docs/architecture/adr/NNN-<slug>.md`:
+   - **Status:** `Accepted` by default (the operator has already reviewed feedback and resolved disagreements via `decisions.md`). Operator can manually downgrade to `Proposed` to leave the decision open for further input.
+   - **Date:** today.
+   - **Context:** 1–2 sentences citing `docs/specs/<slug>.md` (the final spec we're about to write) and any related ADRs.
+   - **Related:** prior ADRs that touch the same area, the source spec path, the Drive review link.
+   - **Decisions:** one per significant call. For each disagreement that landed in `decisions.md`, capture the decision + the rationale (why we chose accept/reject/explore).
+   - **Consequences:** honest trade-offs from the synthesis. Don't overstate the upside.
+   - **Follow-up:** the `side_discussion` items from `feedback.md`, listed as tracked but out-of-scope for this ADR.
+
+6. **Promote the final spec** to `docs/specs/<slug>.md`:
+   - This is the **post-review** version, not the original source.
+   - Start from the current Drive body — it includes accepted suggestions.
+   - Layer in any clarifications from `feedback.md` that weren't body-edited.
+   - Add a header block linking back to the ADR and the review trail:
+
+     ```markdown
+     # <Title>
+
+     > **Status:** Finalized after review · See [ADR-NNN](../architecture/adr/NNN-<slug>.md) · Review trail: [`docs/reviews/<slug>/`](../reviews/<slug>/)
+     ```
+
+   - If the source markdown was already at `docs/specs/<slug>.md`, **diff** the new content vs the old before overwriting and report the changes.
+
+7. **Gate on operator** — present:
+   - ADR draft (full text, inline)
+   - Final spec diff vs source
+   - Chat reply draft (next step)
+   - **Ask explicitly**: "Looks good? Reply 'post' to send the chat reply and finalize, 'iterate' to revise either, or 'abort'."
+
+8. **Chat: compose the thread reply** (template in the workflow doc):
+
+   ```text
+   ✅ *Decision recorded:* <ADR title>
+
+   <2–3 sentences: decision summary, key consequence>
+
+   📄 ADR: `docs/architecture/adr/NNN-<slug>.md` (in repo)
+   📄 Final spec: `docs/specs/<slug>.md`
+
+   Thanks for the feedback — N comments incorporated, M side-discussions tracked as follow-ups.
+   ```
+
+   - Reply **in-thread** on the original announcement (`thread_ts` = `chat.message_ts`).
+   - Optionally broadcast back to the main channel if the decision is worth re-surfacing (ask the operator).
+
+9. **Update `state.yaml`**:
+
+   ```yaml
+   phase: finalized
+   adr:
+     number: NNN
+     path: docs/architecture/adr/NNN-<slug>.md
+     drafted_at: <now ISO>
+   final_spec:
+     path: docs/specs/<slug>.md
+   chat:
+     finalize_reply_ts: <reply ts>
+     finalize_reply_permalink: ...
+   ```
+
+10. **Report back**: ADR path, final spec path, chat thread permalink, summary.
+
+11. **Propose commit message(s)** — suggest splitting into separate commits for clarity:
+
+    ```text
+    docs(adr): ADR-NNN <title>
+    docs(specs): finalize <slug> after review
+    docs(reviews): mark <slug> finalized
+    ```
+
+## Tool notes
+
+- Drive: only read the current body (to pull into the final spec). No writes to Drive.
+- Chat: reply in-thread. Use a draft first if the operator hasn't seen the wording.
+- Read recent ADRs from `docs/architecture/adr/` before drafting — don't invent the format.
+
+## Important
+
+- The ADR is durable. It will get cited for years. Take this draft seriously: clear context, sharp decisions, honest consequences. Read recent ADRs for voice — terse, tabular where it helps, no marketing language.
+- The Drive doc stays untouched. The review trail in `docs/reviews/<slug>/` is preserved as the audit log.
+- **Do not** delete `docs/reviews/<slug>/` after finalize. It's the receipts.
+- If the source markdown was outside `docs/specs/`, ask the operator where the final spec belongs — don't auto-relocate.
+- Don't auto-commit.

package/core/commands/prep-review-publish.md

@@ -0,0 +1,113 @@
+---
+description: Publish a staged review package to a shared drive (as native Doc/Slides) and announce in chat
+argument-hint: <slug> [--channel #name] [--republish]
+---
+
+Publish a review package previously staged by `/prep-review`. Full workflow reference: [.claude/workflows/review-workflow.md](.claude/workflows/review-workflow.md).
+
+Slug: $ARGUMENTS
+
+> Tooling: this command uses the project's configured **document-drive MCP** (e.g. Google Drive) and **chat MCP** (e.g. Slack). The exact tool names are project-defined; the steps below are tool-agnostic.
+
+## Steps
+
+1. **Parse args**: slug (required), `--channel <name>` (default = the project's review channel), `--republish` (delete + repost).
+
+2. **Load state**: read `docs/reviews/<slug>/state.yaml`. Validate:
+   - Exists? If not → "Run `/prep-review <path>` first."
+   - `phase == drafted` or `published` (latter is a no-op unless `--republish`).
+   - `package.md` exists.
+
+3. **Read `package.md`** — this is what gets uploaded.
+
+4. **Drive: locate the review folder** (the project's review folder in its shared drive):
+   - If `state.yaml` already has `drive.folder_id` → skip the search, use it directly.
+   - Otherwise search the drive for the review folder by name.
+   - **If the search returns nothing** (some drive MCPs don't include shared-drive content by default): ask the operator to paste the folder URL. The folder ID is the last path segment of the folder URL.
+   - Persist `drive.folder_id` (and `drive.shared_drive_id` if available from metadata) to `state.yaml`. Subsequent publishes skip the lookup.
+
+5. **Drive: generate the artifact with a descriptive filename, prompt drag-drop, detect via folder polling**:
+   - Verify the converter is on PATH (e.g. `which pandoc`; bail with install instructions if missing).
+   - **Derive the Drive filename from the source H1** (the drive uses the filename as the artifact's title in UI and chat):
+     - Take the H1 of `package.md`.
+     - Replace any `:` with `—` (filesystem-friendly, reads cleaner).
+     - Append the right extension. Example: `Proposal: Review workflow via Drive + chat` → `Proposal — Review workflow via Drive + chat.docx`.
+     - **Do not** use generic names like `package.docx` — those become ugly drive titles.
+   - **For Doc surface**: convert `package.md` → `.docx` (e.g. `pandoc -f gfm -t docx docs/reviews/<slug>/package.md -o "docs/reviews/<slug>/<Derived>.docx"`).
+   - **For Slides surface**: generate `.pptx` via the project's slide skill, same derived-filename pattern.
+   - **Baseline the drive folder** before prompting: list existing file IDs in the folder (`baseline_ids`).
+   - Print one clear instruction:
+     > "Drag `docs/reviews/<slug>/<Derived>.docx` into this folder: `<folder URL>`. I'll detect it automatically — no need to paste anything back. Note: the drive may not auto-prompt to convert .docx → native Doc; that's fine, .docx editing supports comments and suggesting natively."
+   - **Poll the folder** every ~7s for up to ~3 min: re-list the folder, diff against `baseline_ids`. New file → grab it.
+   - If polling times out: print the folder URL again and ask the operator to paste the new file's URL manually (fallback).
+   - Once detected: fetch metadata to capture `mimeType`, `title`, `web_view_link`.
+   - **Do not** attempt to create the file via base64 upload — the base64 round-trip through LLM context is impractically slow.
+
+6. **Persist Drive state**:
+
+   ```yaml
+   drive:
+     folder_id: ...
+     file_id: ...
+     web_view_link: ...
+     uploaded_at: <now ISO>
+   phase: published
+   ```
+
+7. **Chat: resolve channel**:
+   - Search the chat workspace for the channel name (strip leading `#`).
+   - If not found → ask the operator for a valid channel.
+   - Persist `chat.channel_id` and `chat.channel_name`.
+
+8. **Chat: compose the announcement** (use the template in the workflow doc):
+
+   ```text
+   📋 *Review needed:* <H1 title>
+
+   <2–4 sentence TL;DR from package.md>
+
+   *Review objective:* <review_objective from state.yaml>
+
+   *How to weigh in:* Open the doc and leave inline comments / suggestions. Reactions on this message also count.
+
+   📎 <web_view_link>
+   ```
+
+9. **Chat: send as a draft first** — use the draft-message tool so the operator reviews wording before it ships. Wait for operator approval, then send.
+
+10. **Persist chat state**:
+
+    ```yaml
+    chat:
+      channel_id: ...
+      channel_name: ...
+      message_ts: ...
+      permalink: ...
+      posted_at: <now ISO>
+    ```
+
+11. **Report back**: Drive link, chat permalink, summary of where to find things.
+
+12. **Propose a commit message**:
+
+    ```text
+    docs(reviews): publish <slug> review package (Drive + chat)
+    ```
+
+## `--republish` behavior
+
+- Confirm with the operator first: "This will delete the existing Drive doc (losing any comments / suggestions on it) and post a fresh chat message. Proceed?"
+- If the MCP can't delete, bail and ask the operator to delete in the UI, or skip deletion and overwrite content via a new upload.
+- Reset `drive` and `chat` fields in `state.yaml`, then run steps 4–11 fresh.
+
+## Failure modes
+
+- **Drive upload succeeds, chat post fails**: persist Drive state, bail with "Drive done. Re-run `/prep-review-publish <slug>` to retry chat only."
+- **Both fail**: no state changes beyond what already succeeded; the operator can re-run safely.
+- **Channel not found**: ask the operator to specify or create the channel; do not invent one.
+
+## Important
+
+- This is the first irreversible-ish action (humans will see the doc). Take the gate at step 9 seriously — chat messages can be deleted but the notification already fired.
+- Don't call Drive `delete` operations unless explicitly approved — losing comments is destructive.
+- Don't auto-commit.

package/core/commands/prep-review.md

@@ -0,0 +1,65 @@
+---
+description: Stage a markdown proposal for stakeholder review — generate a review-ready package, pick a surface (Doc/Slides), gate on operator
+argument-hint: <path-to-markdown> [--as doc|slides|auto] [--force]
+---
+
+Stage a review package for stakeholders who live outside the repo (no source access — reviewing via Docs/Slides + chat). Full workflow reference: [.claude/workflows/review-workflow.md](.claude/workflows/review-workflow.md).
+
+Source: $ARGUMENTS
+
+## Steps
+
+1. **Parse args**: source path (required), `--as doc|slides|auto` (default `auto`), `--force` (overwrite existing).
+
+2. **Read the source markdown.** If missing → bail clearly. Derive a slug from the filename (kebab-case, no extension).
+
+3. **Check `docs/reviews/<slug>/`**:
+   - Doesn't exist → proceed.
+   - Exists without `--force` → bail with: "Already drafted. Re-run with `--force` to overwrite, or `/prep-review-publish <slug>` to ship it, or `/prep-review-collect <slug>` if it's already published."
+   - `--force` → preserve `state.yaml` Drive/chat fields if present (so we don't lose IDs); only overwrite `source.md` and `package.md`.
+
+4. **Analyze the source** for surface recommendation (only if `--as auto`):
+   - Count `##`/`###` headings, list lines, paragraphs, tables, image refs.
+   - Look at filename + H1 for words like "deck", "pitch", "presentation" → tilt Slides.
+   - Length > 300 lines or heavy prose → tilt Doc.
+   - Decision-focused / spec-shaped → Doc.
+   - See the surface heuristic in the workflow doc.
+   - If `--as doc` or `--as slides` is explicit, skip analysis.
+
+5. **Extract the review objective.** Look for a `## Review objective` (or `## Decision needed` / `## What we need from you`) section in the source. If missing, **ask the operator** for a 1–3 sentence statement before proceeding — this is what stakeholders are being asked to decide.
+
+6. **Generate the review package** at `docs/reviews/<slug>/package.md`:
+   - Lead with a 3–5 sentence **TL;DR**, stakeholder-facing. If the source already has a TL;DR, **don't just copy it** — the source TL;DR is repo-facing ("here's what this doc is"); the package TL;DR is stakeholder-facing ("here's what we need from you"). End it with an explicit "What we need from you" clause if not already obvious.
+   - Then the **Review objective** verbatim.
+   - Then the full source content (lightly reformatted only if the surface is Slides — see below).
+   - Trailing **"How to leave feedback"** block: "Use suggesting mode for prose changes. Use inline comments for questions or disagreements. React 👍 on the announcement if you're aligned with no comments. **Please leave comments open** (don't resolve them) until you're told feedback has been collected — resolved comments may not survive the export."
+   - For **Slides**: restructure into slide-shaped chunks separated by `---`. One concept per slide. Move long prose to speaker-notes-style indented blocks. **Ask the operator to confirm the slide structure** before publish.
+
+7. **Snapshot the source** to `docs/reviews/<slug>/source.md` (raw copy, for diffing later).
+
+8. **Write `state.yaml`** with: slug, source path, created_at (ISO 8601), `phase: drafted`, `surface`, `surface_reasoning` (one-paragraph honest explanation — captures *why* this surface was picked, for audit and to force honesty when `--as auto` picks wrong), `review_objective`. No Drive/chat fields yet.
+
+9. **Gate on operator** — present:
+   - Surface choice + 1-line reasoning ("Recommended Doc because 480 lines, 12 sections, no deck signal in title")
+   - TL;DR you wrote
+   - Review objective
+   - File list staged
+   - **Ask explicitly**: "Look good? Reply 'publish' to run `/prep-review-publish <slug>`, 'iterate' to revise, or 'abort' to back out."
+
+10. **Propose a commit message** (do not run it):
+
+    ```text
+    docs(reviews): draft review package for <slug>
+    ```
+
+## Tool notes
+
+- Use `Read` for the source, `Write` for all generated files.
+- Don't call any Drive or chat tools — this phase is local only.
+- Don't auto-commit (`CLAUDE.md` rule).
+
+## Important
+
+- The package is what stakeholders will read. Quality matters — this isn't a mechanical conversion. Add a TL;DR, ensure section flow makes sense out of repo context, expand acronyms on first use.
+- The source markdown stays untouched. Only `docs/reviews/<slug>/` is written.
+- If the operator says "iterate", make the revision in `package.md` (not the source), then re-gate.

package/core/commands/project-closeout.md

@@ -0,0 +1,25 @@
+---
+description: Close out a finished project — verify all PRs merged, clean up worktrees/branches, close the project board once every issue is closed, mine all local code-review findings (+ static-analysis alerts) for recurring mistake families, and memorialize durable lessons.
+argument-hint: <project-number>
+---
+
+Run the **Project Closeout Ceremony** for project #$ARGUMENTS. Full reference: [.claude/workflows/project-closeout-ceremony.md](.claude/workflows/project-closeout-ceremony.md). Run this once the project's last PR has merged (or on a deliberate long pause).
+
+Work-item reads (board status, finding records) and closing the board go through the project's installed **issue-tracker skill** (`.claude/skills/issue-tracker-*/`) via `list-issues` / `get-issue` / `query-board` / `close-board`. PR state and CI alerts stay on `gh` / GitHub.
+
+Execute the ceremony's seven steps in order:
+
+1. **Verify everything merged** — `gh pr view <n> --json state` for every project + follow-up PR (all `MERGED`; squash-merge means `git branch --merged` lies — trust PR state). Board items all `Done`/`In Review` (skill `query-board`). If anything is still open/In Progress, stop and report — the project isn't closed.
+2. **Clean up** — remove ONLY this project's worktrees (`git worktree remove --force` + `prune`), delete merged local branches, delete dangling remote branches (`git push origin --delete` — UI merges don't auto-delete), restore the main checkout to `main`. Leave unrelated/locked worktrees.
+3. **Close the project board** — once Step 1 confirms the PRs merged, close the board **only if every issue on it is closed**, via the skill's `close-board` operation. The board's own status field is unreliable, so the skill gates on real issue state (intersect the board's issues with the still-open issues — the intersection must be empty). Any issue still open → do NOT close; stop and report (the project isn't done). Reversible.
+4. **Mine ALL local-review findings** — pull every local code-review findings record across the project into one corpus via the skill's `list-issues` / `get-issue` operations (on GitHub the findings live as the marked comment each PR posts — `gh pr view <n> --json comments`, all PR numbers; the skill handles where they live on other trackers), plus any static-analysis / security-scanning alerts still produced in CI. (Review is local-only — there are no cloud review threads to mine; the durable record is the findings comment each PR/work item posts.) Classify by mistake **family**, not individual fix. For each: recurrence count + distinct PRs (≥2 = a pattern); already in `docs/agent-lessons/` (or the engsys lessons-library)? (if yes but it still recurred → strengthen, don't just re-file); severity (prioritize families that produced real Critical/Major bugs over nitpicks).
+5. **Memorialize (team-facing, in the repo)** — new recurring family → new lesson under `docs/agent-lessons/`; documented-but-recurring → strengthen the existing lesson + its Start-of-PR check; workflow/agent/command gap → update the relevant `.claude/commands/*.md` / `.claude/agents/*.md` / `CLAUDE.md`. **Generalizable lessons** (not specific to this project's stack/domain) → also open a PR back to the engsys `lessons-library/` so other projects inherit them. Commit on `agent/project-$ARGUMENTS-reflection-lessons` → one docs PR.
+6. **Update personal memory** — orchestration/verification/tooling judgment that's about how YOU operate goes in your memory dir; append to existing feedback files, point at the repo checklist.
+7. **Final report** — PRs merged + lesson contributions, cleanup done, **whether the board was closed (or which issues block it)**, new/strengthened lessons (with the recurrence count justifying each), personal-memory updates, outstanding deferred/operator-gated work.
+
+Hard rules:
+
+- Repo-vs-personal split per `CLAUDE.md` § Memory & rules: anything that should change behavior for **anyone** in the repo goes in the repo (`docs/agent-lessons/` / workflow / `CLAUDE.md`), not personal memory. Anything generalizable beyond this project goes to the engsys `lessons-library/`.
+- Generalize the **family**, don't just confirm the inline fix — fixing a comment inline is not learning.
+- Issue bodies / commit messages / PR bodies via `tmp/` files, never HEREDOC.
+- Docs-only commits: if a local markdown-lint hook can't spawn, `--no-verify` is acceptable; the pre-push local review is the markdown backstop.