@erclx/aitk 0.8.0

package/claude/skills/claude-memory-capture/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: claude-memory-capture
+description: Extracts durable patterns from the current session and writes them to `.claude/memory/` as feedback, project, user, or reference memory files. Use when asked to "capture memory", "capture lessons", "wrap up the session", "end of session memory", or as the final step in autoship. Do NOT use to curate existing memory. Use `claude-memory-review` for that.
+---
+
+# Claude memory capture
+
+Scan the current session for patterns worth persisting, write them as memory files, and update the index. Pair with `claude-memory-review` for later curation.
+
+## Guards
+
+- All `.claude/memory/` reads and writes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
+- If `.claude/memory/` does not exist at the main worktree root, create it.
+- If the session produced no user corrections, confirmations, or context disclosures worth persisting, stop: `✅ Nothing worth capturing.`
+
+## Step 1: read context
+
+Read in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: Memory section rules, including save thresholds and file format overrides
+- `.claude/memory/MEMORY.md`: existing index, to avoid duplicates
+- `.claude/standards/prose.md`: prose conventions applied to memory file bodies
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+## Step 2: classify candidates
+
+Scan the session and group candidate patterns into four types:
+
+- **feedback**: explicit user corrections, stated preferences, or non-obvious confirmations
+- **project**: decisions, initiatives, deadlines, or motivations not derivable from git or code
+- **user**: role, expertise, responsibilities, or working preferences
+- **reference**: pointers to external systems (dashboards, trackers, channels)
+
+Apply the save threshold: a feedback memory only fires on explicit user correction, or on a pattern that repeated twice in the session. First-occurrence slips are noise. Project, user, and reference memories fire on first disclosure.
+
+## Step 3: dedupe
+
+For each candidate, grep `.claude/memory/` for an existing file on the same topic. If one exists, update it in place rather than create a new file.
+
+## Step 4: write
+
+For each new memory, write to `.claude/memory/<type>-<slug>.md` with this frontmatter:
+
+```markdown
+---
+name: <memory name>
+description: <one-line description per .claude/standards/prose.md § Frontmatter descriptions>
+type: <feedback|project|user|reference>
+---
+
+<memory body>
+```
+
+Feedback and project bodies must be three lines: the rule or fact on one line, a `**Why:**` line naming the session signal, and a `**How to apply:**` line for when the rule fires next. Keep each line tight. No narrative.
+
+User and reference bodies are a single sentence each.
+
+Then append a row to the matching table in `.claude/memory/MEMORY.md`:
+
+```markdown
+| <name> | <file> | <description> |
+```
+
+## Output
+
+Respond with one line per memory written or updated:
+
+- `✅ Wrote: .claude/memory/<file> (<type>)`
+- `✏️ Updated: .claude/memory/<file> (<type>)`
+
+When at least one entry was written or updated, add a closing line so the standalone caller proposes fixes while context is fresh:
+
+`→ Run /claude-memory-review to propose fixes for the pen before the session ends.`
+
+The ship skills run review Propose themselves, so this line is for the standalone `/claude-memory-capture` path.
+
+If nothing was captured, output:
+
+`✅ Nothing worth capturing.`

package/claude/skills/claude-memory-review/REQUIREMENT.md

@@ -0,0 +1,37 @@
+---
+name: claude-memory-review
+description: What memory review is for, the gaps it closes, and why every action waits on approval
+---
+
+# Claude memory review requirement
+
+## Gap
+
+Without this skill, the memory folder grows and never drains. Entries pile up restating rules a durable surface already carries, nothing decides which memory has earned a place in one, and a rule that does get promoted arrives verbatim in a file whose voice it does not match. The folder then reads as a second source of truth that no surface points at.
+
+## Must
+
+- Treat the folder as a holding pen, so every entry in scope leaves it as a promotion, a handoff, or a deletion rather than surviving by default
+- Verify the rule is not already stated or implied in the target before proposing a promotion, by reading the target rather than trusting the memory's claim about it
+- Rewrite a rule into the destination's voice instead of moving it unchanged
+- Write the proposal to a receipt on disk and take no action until the user decides per item
+- Keep a promotion on its own commit, since a change to how the agent operates should not ride inside a feature a reviewer is vetting for something else
+
+## Must not
+
+- Apply anything the user has not approved by item
+- Author a governance rule inline. Coding-standards rules have an owner and a scaffolding path, and a rule written here bypasses both.
+- Mutate tracked files from the main worktree
+- Answer a question raised in a decision slot while applying. Discussion and application are separate passes so an approval is never inferred from a reply.
+
+## Guards
+
+- No memory folder at the main root: stop
+- The folder holds only its index: stop with a pass, not an error
+- Apply invoked from the main worktree: stop and name the worktree command
+
+## Out of scope
+
+- Writing memories, which `claude-memory-capture` owns
+- Judging whether an entry should have been captured. That is a gate at capture time, and re-deciding it here would delete evidence the capture rule is wrong.
+- Editing the governance rules a handoff points at

package/claude/skills/claude-memory-review/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: claude-memory-review
+description: Reviews `.claude/memory/` and proposes per-entry actions (promote to `CLAUDE.md`, move into a skill body, hand off to governance, or delete as stale). Also runs the discuss, challenge, apply, and cleanup phases on an existing review file. Use when asked to "review memory", "discuss memory questions", "challenge the promotes", "apply memory decisions", "cleanup memory review", "promote memory", or "consolidate memories". Do NOT auto-apply. Output a grouped proposal and wait for block-by-block approval.
+---
+
+# Claude memory review
+
+This skill drives the full memory review lifecycle in five phases. Pick the phase from what the user said and whether a review receipt already exists at `<main-root>/.claude/review/memory-review-*.md`.
+
+| User intent                                    | Phase     | Mutates                      |
+| ---------------------------------------------- | --------- | ---------------------------- |
+| "review memory", "promote memory" (no receipt) | Propose   | review file only             |
+| "challenge the promotes" (receipt exists)      | Challenge | review file only             |
+| "discuss", "respond to questions"              | Discuss   | review file only             |
+| "apply decisions", "commit", "ship the review" | Apply     | tracked files + memory files |
+| "cleanup", "sweep stale", "delete the receipt" | Cleanup   | memory files + review file   |
+
+If the user just re-pings the skill with no new phrase and a receipt exists, default to Discuss when any `Decision:` contains `?`, otherwise Apply.
+
+## Guards
+
+- All `.claude/memory/` reads, edits, and deletes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
+- If no `.claude/memory/` directory exists at the main worktree root, stop: `❌ No .claude/memory/ directory found.`
+- If `.claude/memory/` contains no `*.md` entries other than `MEMORY.md`, stop: `✅ No memory entries to review.`
+- Resolve the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. All review and memory reads anchor here.
+
+## Propose phase
+
+Propose is the ship-time entry point. The ship skills run it right after capture, so the fix is written while session context is fresh.
+
+### Scope
+
+- **Ship-scoped:** when a ship caller (`git-ship`, `claude-autoship`) names the entries captured this session, classify only those entries. Read the full pen for merge and absorbed comparison, but do not propose actions on carried entries the captures do not touch. Each carried entry was already proposed on in its own ship cycle.
+- **Full sweep:** when invoked standalone with no named set, classify every entry in the pen, including entries carried from earlier sessions, so cross-session duplicates merge into one rule.
+
+### Step 1: read the memory folder
+
+Read in parallel from the project root:
+
+- `.claude/memory/MEMORY.md`: the index
+- every other `*.md` file under `.claude/memory/`: individual entries with frontmatter (`name`, `description`, `type`)
+
+### Step 2: read promotion targets
+
+Read in parallel from the project root. Skip any file or folder that does not exist.
+
+- `CLAUDE.md`: project behavior rules and Content ownership section
+- every `SKILL.md` under `.claude/skills/`: domain-scoped internal skill bodies
+- every `SKILL.md` under `claude/skills/`: plugin skill bodies
+- every `*.md` under `.claude/standards/`: authoring references
+- every `*.md` under `governance/rules/` in the toolkit repo, or `.claude/rules/` in a target project: coding-standards rules
+
+Read any authoring reference the project does not have from `${CLAUDE_SKILL_DIR}/../../standards/` instead.
+
+### Step 3: classify each entry
+
+`.claude/memory/` is a holding pen. Default every entry to promote or delete on review. Skip is the rare exception, reserved for active task overlap or user-type memories with no in-repo target.
+
+For each in-scope entry (see Scope), pick one action:
+
+- **Promote to `CLAUDE.md`**: the rule is cross-domain behavior or a design principle applied across the whole project.
+- **Promote to a skill body**: the rule fires only when editing a specific path-scoped domain. Name the target skill.
+- **Promote to a standards file**: the rule is an authoring reference that belongs in `.claude/standards/<domain>.md`.
+- **Hand off to governance**: the rule is coding-standards class (typescript, testing, naming, error-handling, performance, logging, concurrency, planning). Do not author the rule file inline. In the toolkit repo, point the user at `aitk-governance` and `.claude/standards/rule.md`, which own the source-of-truth rules under `governance/rules/`. In a target project, point the user at the `create-rule` skill, which scaffolds a project-local rule under `.claude/rules/`. Never edit the synced `.claude/rules/` copies of toolkit rules, because `aitk gov sync` overwrites them. Stop at handoff.
+- **Delete**: the rule is stale, already absorbed into a durable surface, too vague to phrase as a rule, or a one-time incident narrative.
+
+When two or more memories collapse into one rule on the same target, propose them as a single merged edit under the matching promote category. The consolidate case is a variant of promote, not a separate action.
+
+#### Absorbed-already check
+
+Before proposing promote, grep the target surface for the rule's keywords. If the rule is already stated there, the action is **Delete**, not promote. Do not rely on memory-file claims that a rule is documented elsewhere. Verify.
+
+The check covers implication, not only keyword match. If an adjacent bullet in the target section already implies the rule, merge into that bullet rather than append a second.
+
+#### Crispness check
+
+Rules that resist crisp one-line phrasing default to **Delete** over promote. Never promote a memory unchanged. Rewrite to match the destination surface's tone. Use terser phrasing for `CLAUDE.md` and imperative phrasing for skill bodies.
+
+### Step 4: write the proposal to the review file
+
+Derive a slug from the current git branch: run `git branch --show-current` and replace `/` with `-`. Fall back to `latest` on empty output.
+
+Write the full proposal to `.claude/review/memory-review-<slug>.md` at the main worktree root. Do not print it inline.
+
+Structure: a summary block at the top, a legend, then one H2 per numbered item. Number items across all actions so the user can reference them by number. Fuse the status, action, and target into each H2. Put the memory filename on its own line, a one-line Why, the rewritten rule inline in a fenced `diff` block prefixed with `+` so reviewers see the additions in green, and a `Decision:` slot for the user. Do not include a `Take:` slot in the template. Discuss inserts one directly under `Decision:` only when responding to a question item. Status starts as 📝 pending for every item at proposal time.
+
+````plaintext
+# Memory review: <slug>
+
+**Pending:** <all numbers>
+
+Legend: ✅ applied · ⏭ skipped · 🗑 deleted · 🤝 handed off · 📝 pending
+
+How to respond: fill in `Decision:` per item (`apply`, `skip`, `defer`, or a question with `?`), then re-ping the skill. Say "discuss" for question rounds, "apply" to commit. Chat shortcut: `all`, `none`, or a list of numbers.
+
+## 1. 📝 Promote → `<target>`
+
+`<memory-file>`
+
+Why: <one-line pulled from the memory's Why>
+
+```diff
++ <rewritten rule text>
+```
+
+Decision:
+
+## 2. 📝 Delete
+
+`<memory-file>`
+
+Reason: <one-line reason>
+
+Decision:
+````
+
+For Hand off items, the body is a pointer to the governance target instead of a rewritten rule: `aitk-governance` and `.claude/standards/rule.md` in the toolkit repo, or the `create-rule` skill in a target project. For Delete items, skip the rewrite block. Every item gets a `Decision:` slot regardless of action. `Take:` is added only when a question response is needed.
+
+Tell the user `✅ Wrote proposal to .claude/review/memory-review-<slug>.md`. Ask them to fill in `Decision:` per item, then re-ping with "discuss" for question rounds or "apply" to commit.
+
+Rewrite the review file in place whenever the proposal changes mid-review. The file stays the source of truth for the current decisions.
+
+## Challenge phase
+
+Trigger: user says "challenge the promotes", "challenge before apply", or asks for a high-bar pass. Run before Apply. No mutations to memory files or promotion targets. Review file only.
+
+1. Read the latest `.claude/review/memory-review-*.md` at the main root.
+2. For each promote item, apply three tests:
+   - **Absorbed**: grep the target surface for the rule's keywords. If already stated or implied, flip to delete.
+   - **Delta**: if the rule is a nice-to-have next to existing bullets, flip to delete.
+   - **Generality**: if the rule fires only on one literal trigger phrase, rewrite broader or flip to delete.
+3. Rewrite the review file in place with the updated actions and a one-line reason under each flip.
+
+## Discuss phase
+
+Trigger: user says "discuss", "respond to questions", or any `Decision:` value contains `?` or an unrecognized verb. No mutations to memory files or targets. Review file only. Multi-round.
+
+1. Read the latest `.claude/review/memory-review-*.md` at the main root.
+2. For each item whose `Decision:` contains `?` or any unrecognized verb (anything other than `apply`, `skip`, `defer`):
+   - Write a `Take:` line under `Decision:`, separated by exactly one blank line. If a `Take:` line already exists, overwrite it.
+   - Format: pick + one-line reason. Max 2 sentences. Decision-help style. State the recommendation (`apply` / `skip` / `delete` / specific alternative) first, then the reason. Do not enumerate tradeoffs unless one changes the call.
+   - Leave the H2 emoji as 📝 pending.
+3. Skip items whose `Decision:` is `apply`, `skip`, `defer`, or empty.
+4. End with: `💬 Discussed: <nums> | ⏩ Skipped (committed or empty): <nums>`. Remind the user to refine `Decision:` lines and re-ping with "discuss" for another round, or "apply" when ready to commit.
+
+Do not act on any item. Do not delete memory files. Do not edit MEMORY.md. Do not edit promotion targets. Discuss only.
+
+## Apply phase
+
+Trigger: user says "apply", "commit", "ship the review", or re-pings with no question items remaining. Mutates tracked files (target surfaces, memory files, `MEMORY.md`).
+
+Before applying any item, check the worktree state:
+
+```bash
+[ "$(git rev-parse --git-dir 2>/dev/null)" = "$(git rev-parse --git-common-dir 2>/dev/null)" ] && echo "MAIN" || echo "LINKED"
+```
+
+If the result is `MAIN`, stop and tell the user: `❌ Apply phase mutates tracked files. Run /claude-worktree first.` Discuss and Challenge phases only touch `.claude/review/` scratch and run from anywhere.
+
+Before applying a promote to root `CLAUDE.md`, load `aitk-claude` so its seed-mirror rule fires on the edit.
+
+Promotions are a separate concern from any feature in flight. Keep the promoted edits on their own commit. Do not fold a `CLAUDE.md` or skill-body change into a feature's commits, because a feature reviewer should not have to vet a change to how the agent operates.
+
+For each item, parse the `Decision:` line:
+
+- `apply` (or affirmative): run the proposed action, flip emoji to ✅.
+- `skip`: leave the memory in place, flip emoji to ⏭.
+- `defer` or empty: leave 📝 pending, take no action.
+- Contains `?` or unrecognized verb: leave 📝 pending, take no action. Do not respond. Discussion is the Discuss phase's job.
+
+Free-form text after the verb is a reason. Capture it in the receipt but do not let it change the action. When committing an item, strip any empty `Take:` line so the receipt stays clean. `Take:` lines with content stay as discussion history.
+
+Action by action type:
+
+- **Promote**: use `Edit` to insert the rewritten rule into the target surface. Then delete the memory file and remove its row from `.claude/memory/MEMORY.md`.
+- **Hand off**: do not edit governance. Delete the memory file only if the user confirmed the handoff explicitly. Otherwise leave it in place.
+- **Delete**: remove the memory file and its row from `.claude/memory/MEMORY.md`.
+
+Apply edits one at a time via `Edit`. Claude Code's tool permission dialog is the confirmation gate per edit. Never rewrite a whole file.
+
+As each item resolves, update its status in the review file: flip the H2 emoji from 📝 to ✅ for applied, ⏭ for skipped, 🗑 for deleted, or 🤝 for handed off. Refresh the summary block counts at the top. Do not delete the review file. It stays as a receipt until Cleanup runs or the next Propose pass overwrites it.
+
+**Chat shortcut:** the user replies with `all`, `none`, or a comma-separated list of numbers. Apply only the numbered items.
+
+End with: `✅ Applied: <nums> | ⏭ Skipped: <nums> | 📝 Pending: <nums>`. Omit empty buckets. If anything is pending, remind the user they can refine `Decision:` lines and re-ping, run "discuss" for question items, or commit a skip with `skip <nums>` in chat.
+
+## Cleanup phase
+
+Trigger: user says "cleanup", "sweep stale memories", or "delete the receipt" after Apply has run.
+
+1. Read the latest `.claude/review/memory-review-*.md` to see which entries were skipped.
+2. Treat a `Skip` decision as terminal. Do not delete a memory just because it would Skip again next review. Target only entries whose decision value is exhausted: already-applied promotions and stale receipts.
+3. Delete the review file itself.
+4. Leave applied promotions, governance handoffs, and user-type memories alone.
+
+Do not promote or rewrite. Cleanup only.
+
+## After completion
+
+Output one line per action taken in the most recent phase:
+
+- `✅ Promoted: .claude/memory/<memory-file> → <target>`
+- `✅ Handed off: .claude/memory/<memory-file> → governance`
+- `🗑  Deleted: .claude/memory/<memory-file>`
+
+If the user accepted nothing, output: `✅ No changes applied.`

package/claude/skills/claude-orchestrate/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: claude-orchestrate
+description: Asserts the orchestrator role for the current session, holds the build loop and the queue-refill sweep, and dispatches to the roadmap, feature, review, and worktree skills. Use when asked to "be the orchestrator", "run the orchestrator", "orchestrate this project", or to set up the control session for parallel feature builds. Do NOT build features or merge PRs in this session.
+disable-model-invocation: true
+---
+
+# Claude orchestrate
+
+This session is the orchestrator: the one warm session that holds the
+cross-feature picture. It plans and reviews. It does not build, and it does not
+merge. Building happens in cold worker sessions the human launches. Merging is
+the human's gate.
+
+This skill holds the framing, the board procedure, and the dispatch. Every step
+that builds something runs an existing skill. The queue rules below decide which
+one runs and when.
+
+Run `aitk docs operating-model` for the model this skill enacts: the two roles
+and what each owns, the loop end to end, why the worker's self-review and this
+session's review are different passes, and how a feature is sized.
+
+## On invocation
+
+Read the board in parallel, resolving the paths at the main worktree root per Worktrees in `CLAUDE.md`:
+
+- `.claude/tasks/priority.md`: execution order and what each task is waiting on
+- `.claude/tasks/index.md`: what is queued
+- `.claude/plans/*.md`: features already planned and ready to hand off
+- `.claude/ROADMAP.md`: sequencing rationale, when the file exists
+- open PRs via `gh pr list --json number,title,headRefName,isDraft`
+
+Then output the state of play so the human knows what to launch, review, and merge.
+
+`priority.md` is the ordering source. `index.md` sorts by filename and says nothing about order, so read the sequence from the first and never infer it from the second. When `priority.md` is absent, report the queue and say the order is unrecorded.
+
+The roadmap is optional and this skill does not require it. It carries why a sequence is what it is, changes only when strategy changes, and is absent in a project whose scope has already shipped. Report what it says and name it as the source. Never assert an active version the file does not state, and say nothing about one when the file is missing.
+
+## Output
+
+```plaintext
+Orchestrator ready.
+
+Roadmap: vX.Y, <the Now row's outcome>, as of <date>.
+
+Ready to build (hand each to its own worker):
+
+<feature>
+  plan: .claude/plans/feature-<slug>.md
+  → /claude-autoship
+
+<feature>
+  no plan yet. A handoff without a plan has no scope
+  → /claude-feature here first
+
+In review (your turn):
+
+PR #<n> <title>
+  → /claude-pr-review
+
+Merge order: #<a> before #<b> (shared seam: <files>).
+
+Next: <the single most useful action>
+```
+
+Omit any section with nothing in it. Recommend a handoff only for a plan whose file set is disjoint from every track already in flight, per Parallelism below.
+
+Omit the `Roadmap` line when `.claude/ROADMAP.md` is absent. Quote the `Now` row rather than restating it, and date the line from `git log -1 --format=%ad --date=short -- .claude/ROADMAP.md` so an old sequence reads as old instead of as the state of play.
+
+That command returns nothing for a roadmap that exists but has never been committed, which is the state `claude-roadmap` leaves behind when it writes the file and declines to stage it. Write `uncommitted` as the date in that case. A blank there would read as a formatting slip rather than as the newest possible sequence.
+
+## The loop
+
+1. Own the roadmap while a scope exists to sequence. Run `claude-roadmap` to draft or resequence `.claude/ROADMAP.md` from the MVP list in `.claude/REQUIREMENTS.md`, and skip it once that list has shipped, since later work then arrives as discrete items rather than as versions. Capture a needed resequence in the plan or a task file for a worker to apply in its branch, so the tracked edit ships in a PR rather than dirtying main.
+2. Plan the next feature. Run `claude-feature` here, with the cross-feature context, to write a plan to `.claude/plans/`. Planning stays in this warm session so the plan front-loads reasoning a cold worker would otherwise re-derive.
+3. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
+4. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
+5. Hand off. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The orchestrator does not spawn workers.
+6. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
+7. Close the loop. After the worker runs `claude-address-review`, re-review if needed, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
+
+## Boundaries
+
+- Run one orchestrator at a time. The board is gitignored, so a second session sees none of this one's writes: two task files land minutes apart under different labels for the same work, one session archives a task mid-sweep in the other, and each archives a plan the other had retargeted. An Owner column does not fix this, since neither session can read the other's rows.
+- Do not implement features in this session. Hand the plan to a worker.
+- Do not merge. Recommend merge or changes. The human merges.
+- Do not spawn worker sessions with agents. The human launches each worktree so every build is an independent, steerable stream with its own PR.
+- Do not edit tracked files from this session. Record a change identified while orchestrating against the task that owns it, so it ships from that task's branch and lands in a pull request.
+- Do not hand a worker anything but a plan, since scope lives there. A plan carries exact diffs only when they are already known, otherwise it states the scope and the open questions and lets the worker write the diff.
+
+## Refilling the ready queue
+
+Keep enough planned, non-conflicting tasks available that a free worker never waits, and place the findings the last merge produced before promoting anything new. Run this after every merge and whenever the ready list thins.
+
+1. Run `gh pr list --state open` and `git log --oneline -8`. Report any pull request whose review has not been posted and stop for that one first.
+2. For each pull request merged since the last sweep, place every finding it produced. Route a finding that changes a rule to the standard or rule that states it, one that changes another task to that task's Findings, and one that overturns a groundwork lean to that folder marked answered. Never leave a finding in a pull request thread alone.
+3. Archive what closed. A task whose outcomes are all `[x]` runs `claude-docs` for the plan sweep, then `claude-tasks` to archive. A task whose outcomes describe standing policy rather than a deliverable never closes on its own, so hand it to a worker to encode the policy where it is enforced, then cut the outcomes with the reason recorded and archive once that branch merges. Encoding it from this session would write a tracked file, which Boundaries forbids.
+4. Read `.claude/tasks/priority.md` and count entries under its `## Run now` heading that carry a written plan. Keep one in reserve beyond what is running.
+5. Promote by whether a task establishes functionality rather than by age. Prefer a task that adds or proves a mechanism over one that trims, tidies, or audits an existing surface.
+6. Before promoting a candidate, list the files it touches against every task already running, per Parallelism below. Name the overlap and serialize when the sets are not disjoint.
+7. Write a plan for each newly promoted task with `claude-feature`, then report:
+
+```plaintext
+Findings placed: <finding> → <destination>
+Archived: <task>
+Promoted: <task>, touches <surfaces>, parallel with <task> because <disjoint sets>
+Serialized: <task> behind <task>, both write <file>
+Ready now: <tasks with plans, and what each waits on>
+```
+
+Treat a task that edits `.claude/context/` entries wholesale as conflicting with every other task, because the root instruction file requires each task to update its own domain entry as it lands.
+
+Do not promote a task to fill the queue when nothing qualifies. A thin queue is a real answer and it beats a plan nobody needed.
+
+## Parallelism
+
+No fixed number caps worker tracks. Collision between file sets is what binds, so
+list the files a candidate touches against every track already in flight and open
+it only when the sets are disjoint. What thins as tracks multiply is the review
+attention each output gets, so add a track while you can still review every one
+properly and stop when you cannot. Serialize any track that touches a shared
+wiring seam with another in flight. Merge the branch with the smallest
+shared-file footprint first, and merge a branch touching `CLAUDE.md`, a Claude
+context entry, or a regenerated `index.md` last. Have every sibling rebase on
+the new `main` before the next merge. Assign a distinct port per track when two
+workers run a server, since each session spawns its own process.

package/claude/skills/claude-pr-review/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: claude-pr-review
+description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass under `## Review`, and a close-out under `## Review closed` that reads only the commits added since. Reads project docs and the roadmap for cross-feature context a self-review lacks. Use when asked to "review the PR", "review this feature's PR", "post a PR review", "re-review the PR", "close out the review", "confirm the findings are fixed", or acting as the orchestrator reviewing a worker's PR. Do NOT use to review local uncommitted changes. That is `claude-review`.
+---
+
+# Claude PR review
+
+This is the orchestrator's independent review, distinct from `claude-review`.
+`claude-review` reviews local changes for the session that wrote them and writes
+to disk. This one reviews an open PR the session did not write and posts the
+findings to the PR, so the vantage is independent and the output is durable.
+
+It posts twice over a pull request's life. A first pass opens the review against
+the whole change. A close-out confirms the findings are closed and reads only
+the commits added since. Both are this skill, and the pass is detected from the
+thread rather than named by the caller.
+
+## Guards
+
+- If no open PR resolves for the target branch via `gh pr view`, stop: `❌ No open PR to review. Open one first, or use /claude-review for local changes.`
+- Review and post. Do not merge. Merging is the human's gate.
+
+## Step 1: resolve the PR and read context
+
+Resolve the PR: `gh pr view --json number,headRefName,headRefOid,title` for the current branch, or use a PR number the user names. The first seven characters of `headRefOid` are `<short-sha>`, which names the body file in Step 4.
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: project type, conventions, and commands
+- `.claude/REQUIREMENTS.md`: feature scope and non-goals
+- `.claude/ARCHITECTURE.md`: technical design decisions
+- `.claude/ROADMAP.md`: where this feature sits and what depends on it
+- `.claude/plans/feature-<slug>.md` for the branch, when present: the intent the PR should satisfy
+
+Coding standards from `.claude/rules/` are auto-loaded by Claude Code.
+
+## Step 2: scope the read
+
+Find the commit the last pass covered:
+
+```bash
+gh pr view <number> --json reviews --jq '[.reviews[] | select(.body // "" | split("\n")[0] | rtrimstr("\r") | . == "## Review" or . == "## Review closed")] | last | .commit.oid'
+```
+
+Match the first line for equality against the two headings this skill posts. A prefix test also matches `## Review response` and any heading merely starting with those words, which would scope the close-out to whatever commit that comment carried. The `\r` trim covers a body composed in the GitHub web editor, which stores CRLF.
+
+An empty result is a first pass. Read the whole change:
+
+```bash
+gh pr diff <number>
+```
+
+```bash
+gh pr diff <number> --name-only
+```
+
+A commit is a close-out. Fetch the pull request head so both commits are local:
+
+```bash
+git fetch -q origin pull/<number>/head
+```
+
+A failed fetch stops the skill: `❌ Could not fetch the PR head. Retry once the remote is reachable.` Do not fall through to the full pass. A fetch failure and a rebase both leave the prior commit unreachable, and the fallback below states a rebase as fact on the pull request, so conflating the two publishes a claim the skill never checked.
+
+Then test that the prior commit still reaches the head:
+
+```bash
+git merge-base --is-ancestor <prior-oid> <headRefOid>
+```
+
+On exit zero, review `<prior-oid>..<headRefOid>` and nothing else. `git diff` and `git log --oneline` over that range are the whole read, because the first pass already covered everything behind it. A non-zero exit means the branch was rebased or force-pushed, so the delta is undefined rather than empty. Fall back to the full pass above and say so in the body.
+
+Read each changed file in scope. Skip deleted files. Run reads in parallel.
+
+## Step 3: review
+
+Review the diff and files for the same axes as `claude-review` (bugs, edge cases, error handling, logic flaws, security, rule violations), then add the three lenses a self-review structurally cannot apply:
+
+- Integration: does this fit the roadmap sequence, the shared wiring seam, and any sibling PR in flight?
+- Contract: does a contract downstream features depend on land correctly, and should the plan itself be questioned?
+- Consumers: when the change touches a resource with more than one consumer, enumerate them and check the rule against each. A rule written for the consumer the change targets can be wrong for a sibling that writes.
+
+Apply the high-signal filter: flag only what will cause incorrect behavior, break a documented rule, or mislead a downstream feature. If uncertain, do not flag.
+
+A close-out applies the same axes to the delta, and adds one check the first pass cannot make: did each prior finding land, and did the fix regress anything it touched. Findings of its own are normal findings, stated at the same severity and counted the same way.
+
+Use severity: `critical` (blocks merge), `should-fix` (fix before merge), `minor` (visibility only).
+
+## Step 4: post to the PR
+
+Write the comment to `.claude/.tmp/pr-review/body-<number>-<short-sha>.md`. The PR number stops two sessions reviewing different pull requests from overwriting each other between the write and the post. The head commit stops a second pass overwriting the first one's body, and leaves the folder a record of which commit each review covered. Derive both segments from Step 1. Never pick a suffix by hand, and never reuse a name the folder already holds.
+
+The comment is a rendered-for-human GitHub surface, so follow `.claude/standards/prose.md` for voice, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it: cut editorializing, and keep every sentence load-bearing. Match this shape on a first pass:
+
+```markdown
+## Review
+
+X critical, Y should-fix, Z minor. Reviewed against project docs and roadmap.
+
+**`path/to/file.ext`**
+
+- **should-fix**: what breaks and the fix, in two or three sentences.
+- **minor**: finding.
+
+**What is right**
+
+- bounded confirmation.
+
+🤖 Reviewed by Claude Code
+```
+
+A close-out keeps that shape and changes the heading and the summary line:
+
+```markdown
+## Review closed
+
+Re-reviewed `<short-sha>`, N commits since the prior pass. X critical, Y should-fix, Z minor.
+
+**`path/to/file.ext`**
+
+- **should-fix**: what breaks and the fix, in two or three sentences.
+
+🤖 Reviewed by Claude Code
+```
+
+Open a first pass with `## Review` and a close-out with `## Review closed`, so a reader scanning the thread can tell an open review from a confirmation that its findings are closed without opening either. Both anchor as a section distinct from human threads. Do not invent a third heading, and do not append the PR number, which GitHub already renders above the comment.
+
+Name the scope in the close-out summary line, since a reader cannot otherwise tell a narrow read from a full one. When the fallback in Step 2 fired, replace the commit count with `Re-reviewed the full change, the prior pass's commit is no longer on the branch`. Budget the body. State each finding as the failure and the fix in two or three sentences, not a paragraph of reasoning. Omit files with no findings. Do not lecture on process. The integration, contract, and consumer lenses stay, but as findings, not asides.
+
+The `What is right` section is optional, capped at three bullets, and included only when it changes the merge decision. Drop it otherwise and let the summary line carry the approval.
+
+Close the body with `🤖 Reviewed by Claude Code` on its own line so the review reads as an independent machine pass, not a human sign-off.
+
+Before posting, scan the body for em dashes and semicolons and rewrite each, splitting into two sentences or using a comma. The standards-audit hook skips `.claude/.tmp/`, so this scan is the only gate on the published comment.
+
+```bash
+gh pr review <number> --comment --body-file .claude/.tmp/pr-review/body-<number>-<short-sha>.md
+```
+
+If a first pass has no findings, post this body instead, under the same `## Review` heading and with the footer included: `✅ No blocking findings. Reviewed against project docs and roadmap.` followed by the footer line.
+
+If a close-out has no findings, post `✅ Prior findings addressed. Re-reviewed <short-sha>, N commits since the prior pass.` under `## Review closed`, again with the footer. Post it even when there is nothing to report. A first pass left with no closing comment reads as a review nobody answered.
+
+## Step 5: output
+
+```plaintext
+X critical, Y should-fix, Z minor. Posted to PR #<number>.
+```
+
+Report the merge decision as a plain recommendation in chat (merge, or address findings first). Do not merge.