project-brain

Manage the assigned_to list on a thread. Supports --add (append handles), --remove (delete handles), --set (replace list), and --clear (remove field entirely). Appends an audit-trail line to the thread body recording who made the change, when, and why. Rebuilds thread-index.md and current-state.md. Use when the user says "assign this thread to <handles>", "add <name> to assigned_to", "unassign from <name>", "clear all assignments", or when managing thread ownership.

Revert a promote PR back to active so the thread becomes editable again. Handles both cases — PR was closed by reviewers (rejected/abandoned), or the user wants to cancel a still-OPEN PR mid-review to keep editing the thread. For OPEN PRs, the skill runs `gh pr close --delete-branch` itself before reverting; for already-closed PRs it just verifies state and reverts. Reverts thread on main from in-review back to active/refining without touching tree_prs (the closed URL stays as audit per CONVENTIONS section 4.1). Does NOT flip any leaf status since leaves never reached main. Use when the user says "discard this promotion", "cancel the promotion", "I want to edit the in-review thread", or after observing a promote PR close without a merge commit.

Kill an active or parked thread before it was ever promoted. Flips status to archived, writes archived_at plus archived_by plus discard_reason, git mv's the thread directory from threads/ to archive/, removes the thread's row from Active or Parked sections of thread-index.md and adds it to Archived, and commits. Refuses if tree_prs is non-empty (route to discard-promotion or finalize-promotion instead) or if the thread is in-review. Use when the user says "discard this thread", "drop this idea", "kill this thread", "abandon <slug>", or "archive this — it was never promoted".

Close out a merged promotion PR. Verifies the PR is merged via gh, flips each landed leaf from in-review to decided on main, appends one entry to promoted_to plus one to promoted_at per leaf, and either returns the thread to active/refining for further work or archives it to project-brain/archive/. Updates thread-index.md and current-state.md to reflect the new state. Use when the user says "finalize the promotion", "close out the PR", "the promotion merged", "archive this thread", or after observing a promote PR go green.

One-time scaffold of the project-brain skeleton into the host environment's project directory. Default invocation runs with **zero interactive questions in the common case** — the skill detects the host project root (Cowork workspace folder, Codex project root, Claude Code cwd, or the nearest git repo root) and scaffolds `project-brain/` inside it. A confirmation is printed showing which source the root came from. The skill only prompts if detection falls all the way through to raw cwd with no git signal, OR if an existing brain is already scaffolded at the target (overwrite vs cancel). Alias and title are derived from the detected home's last-path-component. Owner is written as the literal placeholder `TODO@example.com` with a TODO marker in CONVENTIONS.md § 10 — the user replaces it on their first commit, or leaves it until promote-time. If an existing `project-brain/` is already scaffolded, the skill prompts "overwrite (backup and replace) or cancel?" — it never silently clobbers. Creates project-brain/ wi

Run a structured multi-agent review round against either a leaf (hardening) or a thread (refinement). Creates debate/round-NN/ under the artifact per § 7, writes feedback-in.md, spawns per-persona reviewer subagents in parallel (count controlled by --reviewers=N; personas from § 10.2 or ad-hoc via --persona=name:charter), runs a defender that issues CONCEDE / CONCEDE-IN-PART / DEFER / REJECT verdicts, optionally runs a synthesizer, and emits proposed-patches.md plus open-issues.md. Supports --review-mode=full (default) or --review-mode=delta (review only changes since the prior round). On leaf scope, flips status decided|specified ↔ hardening. On thread scope, updates last_debate_round but leaves status/maturity unchanged, enabling multiple review rounds during thread refinement. Use when the user says "run multi-agent review", "review this thread", "harden this leaf", "open a debate round", "close the debate", "round-NN results", or "finish the review cycle".

Scaffold a new private thought thread in the project brain. Creates the thread directory under project-brain/threads/, populates thread.md plus decisions-candidates.md and open-questions.md from templates, and registers the thread in thread-index.md and current-state.md. Use when the user says "start a new thread", "capture an idea", "new thought", "begin thinking about something", or similar.

Pause or resume an active thread without archiving it. Park flips status from active to parked, preserves the current maturity, captures parked_at plus parked_by plus parked_reason (and optionally unpark_trigger), and moves the thread row from Active to Parked in thread-index.md. Unpark (via --unpark) reverses it, restoring the preserved maturity and clearing the park metadata. Thread stays at its original threads/<slug>/ path — no file move. Use when the user says "park this thread", "pause this", "shelve this for now", "resume <slug>", "unpark this", or "bring <slug> back active".

Promote one or more leaves from a thread into the shared tree/. Supports four modes — local (no git, no PR), git:pr (full PR flow), git:branch (branch+commit+push, user opens PR manually), git:manual (stage only, user runs git commands). Default is git:pr if gh is authed, else ask the user. Use when the user says 'promote this thread', 'land these decisions', 'finalize this decision locally', or similar.

Capture intermediate outputs (debate rationales, benchmarks, analyses, sketches, reference files) into a thread. Default mode writes each input as a separate file under project-brain/threads/<slug>/artifacts/ (markdown, indexed) or attachments/ (raw/binary), with a breadcrumb line appended to transcript.md. Append mode writes content directly into transcript.md under a timestamped header. Use when the user says "log this", "save this as an artifact", "record the debate result", "attach this file to the thread", "add this to the transcript".

Bring an archived thread back to active. Inverse of discard-thread. Moves archive/<slug>/ back to threads/<slug>/, flips status archived→active, restores maturity (default refining), strips archive metadata, rebuilds indexes. Use when the user says "restore this thread", "unarchive <slug>", "I want to keep working on the discarded thread", or "bring back <slug>".

Print a read-only summary of a thread — status/maturity, open questions, decisions-candidates counts, artifacts list, attachments list, and recent transcript entries. Pass --full to dump the entire transcript, --last=N for the last N entries, --since=<ISO8601> to filter by date. Use when the user says "review this thread", "show me the transcript", "what's in thread X", "read the log".

Apply a structured update to an active or parked thread without flipping its status. Supports bumping maturity (exploring to refining to locking and back), adding or renaming or removing candidate-decision leaves under decisions-candidates.md, editing soft_links on thread.md, and committing pending freeform edits to thread.md or companion files with a conventional message. Keeps thread-index.md and current-state.md in sync. Use when the user says "update the thread", "bump maturity to locking", "add a candidate", "rename this option", "drop this candidate", "refresh soft_links", or "commit my edits to this thread". Does NOT flip thread status — use park-thread, discard-thread, promote-thread-to-tree, or finalize-promotion for status transitions.

Read-only validator for the project-brain tree. Walks project-brain/ and checks invariants V-01..V-22 covering artifact frontmatter consistency, lifecycle states, soft_links resolution and DAG acyclicity, NODE.md listings, promoted-list uniqueness/monotonicity, debate round sequentiality, source-reference resolution, filesystem-safe filenames (Unicode-friendly per CONVENTIONS § 11.1 — no whitespace, no FS-reserved chars, no controls; Unicode letters/digits in any script accepted), and per-thread artifact ownership. Also checks section 11 naming and reserved-filename rules. Reports violations with file and line references, exits non-zero on any error. Can run in standard verify mode (read-only) or in --rebuild-index mode to regenerate thread-index.md and current-state.md from source-of-truth thread frontmatter. Never touches git, never makes network calls. Use when the user says "verify the brain", "validate the tree", "lint the thoughts folder", or as a precondition/postcondition from other skills. Pass --reb

Read-only discovery skill that queries per-thread frontmatter ad-hoc with rich filters (status, assignment, maturity, domain, review requirement, stale-thread detection, PR state) and returns filtered views on demand. Works even if thread-index.md is stale. Supports table, JSON, CSV, YAML, and path-only output formats. Use when the user says "what threads are assigned to me", "what parked threads are blocking promotion", "what stale threads in <some-domain>", "threads requiring two-human review", or needs a machine-readable feed for downstream tooling.

Read-only periodic audit of parked threads. Surfaces three categories of action-worthy parked threads — actionable (unpark_trigger set; human decides if condition fired), stale (parked ≥N days; candidates for unpark or archive), and hygiene warnings (no unpark_trigger; need explicit reason for return). Use when the user says "review parked threads", "what parked threads need attention", "audit the park queue", or as a weekly/monthly cadence check. Complements list-threads --status=parked with automatic age and trigger analysis.

Read-only skill that walks the soft_links of a thread, leaf, NODE.md, or impl-spec, resolves each URI per § 5.1 (project aliases, tree-internal paths, file://, http(s)://, mcp://), filters and budgets the resolved content per § 5.2 role semantics, and emits an aggregated context.md ready to hand to a subagent, reviewer, or author. Defaults to ephemeral scratch output; --persist writes inside the artifact dir for audit snapshots. --detect-stale walks refs without materializing to surface broken or drifted links. Use when the user says "materialize context for this thread", "pull in all linked specs", "build a reviewer packet", "check for stale links on <leaf>", or when another skill (multi-agent-debate, promote-thread-to-tree, derive-impl-spec) needs resolved content behind soft_links without re-implementing URI resolution.