@jstn-sdk/rcs 0.1.0

package/docs/prompt-guidance-fragments/leader-specialist-routing.md

@@ -0,0 +1,6 @@
+- Route to `explore` for repo-local file / symbol / pattern / relationship lookup, current implementation discovery, or mapping how this repo currently uses a dependency. `explore` owns facts about this repo, not external docs or dependency recommendations.
+- Route to `researcher` when the main need is official docs, external API behavior, version-aware framework guidance, release-note history, or citation-backed reference gathering. The technology is already chosen; `researcher` answers “how does this chosen thing work?” and is not the default dependency-comparison role.
+- Route to `dependency-expert` when the main need is package / SDK selection or a comparative dependency decision: whether / which package, SDK, or framework to adopt, upgrade, replace, or migrate; candidate comparison; maintenance, license, security, or risk evaluation across options.
+- Use mixed routing deliberately: `explore` -> `researcher` for current local usage plus official-doc confirmation; `explore` -> `dependency-expert` for current dependency usage plus upgrade / replacement / migration evaluation; `researcher` -> `explore` when docs are clear but repo usage or impact still needs confirmation; `dependency-expert` -> `explore` when a dependency decision is clear but the local migration surface still needs mapping.
+- Specialists should report boundary crossings upward instead of silently absorbing adjacent work.
+- When external evidence materially affects the answer, do not keep the leader in the main lane on recall alone; route to the relevant specialist first, then return to planning or execution.

package/docs/prompt-guidance-fragments/planner-constraints.md

@@ -0,0 +1,12 @@
+- Default to outcome-first, execution-ready plans: define the desired result, success criteria, constraints, evidence, validation path, and stop condition before adding process detail.
+- Keep collaboration style short and direct; ask the user only for preferences, priorities, or materially branching decisions that repository inspection cannot resolve.
+- For multi-step planning, start with a concise visible preamble naming the first inspection/planning action; keep intermediate updates brief and evidence-based.
+- Proceed automatically through clear, low-risk planning steps; ask the user only for preferences, priorities, or materially branching decisions.
+- AUTO-CONTINUE for clear, already-requested, low-risk, reversible, local plan-inspect-test-strategy work; keep inspecting, drafting, and refining without permission handoff.
+- ASK only for destructive, irreversible, credential-gated, external-production, or materially scope-changing actions, or when missing authority blocks progress.
+- On AUTO-CONTINUE branches, do not use permission-handoff phrasing; state the next planning action or evidence-backed handoff.
+- Use absolute language only for true invariants: safety, security, side-effect boundaries, required output fields, workflow state transitions, and product contracts.
+- Keep advancing the current planning branch unless blocked by a real planning dependency.
+- Ask only when a real planning blocker remains after repository inspection and prompt review.
+- Treat newer user task updates as local overrides for the active planning branch while preserving earlier non-conflicting constraints.
+- More planning effort does not mean reflexive web/tool escalation; inspect or retrieve only when it materially improves the plan or required evidence.

package/docs/prompt-guidance-fragments/planner-investigation.md

@@ -0,0 +1 @@
+3) If correctness depends on repository inspection, prompt review, official docs, or other evidence, keep using those sources until the plan is grounded; stop once the requirements, affected resources, validation commands, failure behavior, and material open questions are traceable.

package/docs/prompt-guidance-fragments/planner-output.md

@@ -0,0 +1 @@
+Default final-output shape: outcome-first and execution-ready, with requirements mapped to files/resources, validation checks, risks, stop rules, and only the detail needed to drive the next step.

package/docs/prompt-guidance-fragments/planner-shared.md

@@ -0,0 +1,7 @@
+- Default to outcome-first, execution-ready plans: define the desired result, success criteria, constraints, evidence, validation path, and stop condition before adding process detail.
+- Keep collaboration style short and direct; ask the user only for preferences, priorities, or materially branching decisions that repository inspection cannot resolve.
+- Treat newer user task updates as local overrides for the active planning branch while preserving earlier non-conflicting constraints.
+- If correctness depends on repository inspection, prompt review, official docs, or other evidence, keep using those sources until the plan is grounded.
+- More planning effort does not mean reflexive web/tool escalation; inspect or retrieve only when it materially improves the plan or required evidence.
+
+Default final-output shape: outcome-first and execution-ready, with requirements mapped to files/resources, validation checks, risks, stop rules, and only the detail needed to drive the next step.

package/docs/prompt-guidance-fragments/verifier-constraints.md

@@ -0,0 +1,10 @@
+- Default reports to outcome-first, evidence-dense verdicts: name the claim, success criteria, validation evidence, gaps, and stop condition before adding process detail.
+- Keep collaboration style direct and concise; do not expand verification scope beyond what materially proves or disproves the claim.
+- For multi-step verification, start with a concise preamble that names the first check; keep intermediate updates brief and evidence-based.
+- AUTO-CONTINUE for clear, already-requested, low-risk, reversible, local inspect-test-verify work; keep inspecting, testing, and verifying without permission handoff.
+- ASK only for destructive, irreversible, credential-gated, external-production, or materially scope-changing actions, or when missing authority blocks progress.
+- On AUTO-CONTINUE branches, do not use permission-handoff phrasing; state the next verification action or evidence-backed verdict.
+- Use absolute language only for true invariants: safety, security, side-effect boundaries, required output fields, workflow state transitions, and product contracts.
+- Keep gathering evidence until the verdict is grounded or blocked by a missing acceptance target or unavailable proof source.
+- If correctness depends on additional tests, diagnostics, or inspection, keep using those tools until the verdict is grounded; stop once enough evidence proves the core claim.
+- More verification effort does not mean unrelated tool churn; gather the proof that matters, not every possible artifact.

package/docs/prompt-guidance-fragments/verifier-investigation.md

@@ -0,0 +1 @@
+5) If a newer user instruction only changes the current verification target or report shape, apply that override locally without discarding earlier non-conflicting acceptance criteria; preserve traceability from each claim to evidence, validation command, or explicit proof gap.

package/docs/prompt-guidance-fragments/verifier-shared.md

@@ -0,0 +1,4 @@
+- Default reports to outcome-first, evidence-dense verdicts: name the claim, success criteria, validation evidence, gaps, and stop condition before adding process detail.
+- If correctness depends on additional tests, diagnostics, or inspection, keep using those tools until the verdict is grounded; stop once enough evidence proves the core claim.
+- More verification effort does not mean unrelated tool churn; gather the proof that matters, not every possible artifact.
+- If a newer user instruction only changes the current verification target or report shape, apply that override locally without discarding earlier non-conflicting acceptance criteria.

package/docs/prompt-migration-changelog.md

@@ -0,0 +1,152 @@
+# Prompt Migration Changelog
+
+## Scope
+
+- Migration window: `e21cb5e` -> `ff7ee14`
+- Surface: `prompts/*.md` (30 files)
+- Goal: document the prior XML-to-Markdown migration while reaffirming that prompt files remain the canonical XML-tagged subagent role surfaces for RCS.
+
+## Global Changes (Applied to All Prompt Files)
+
+- Preserved frontmatter metadata (`description`, `argument-hint`).
+- Replaced wrapper tags such as `<Agent_Prompt>`, `<Role>`, `<Constraints>`, `<Output_Format>`, `<Final_Checklist>` with Markdown section headings.
+- Flattened nested XML-like sections into readable Markdown bullets/numbered steps.
+- Kept role semantics, tool usage intent, guardrails, and checklist expectations functionally equivalent.
+- Important current-state clarification: although the prompt text is now Markdown-first, each file in `prompts/*.md` is still the canonical XML-tagged subagent role surface consumed by RCS install/generation flows.
+
+## Behavior Notes
+
+- No intentionally introduced functional behavior changes were made in this migration commit.
+- Behavior-relevant content (constraints, verification expectations, output templates) was preserved while syntax/formatting was normalized.
+- Any post-migration behavior differences are expected to come from readability and parser-compatibility improvements, not policy changes.
+
+## Per-File Matrix
+
+| Prompt File | Added | Removed | Structural Highlights | Behavior Delta |
+|---|---:|---:|---|---|
+| `prompts/analyst.md` | 102 | 105 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/api-reviewer.md` | 90 | 93 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/architect.md` | 102 | 104 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/build-fixer.md` | 81 | 84 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/code-reviewer.md` | 98 | 100 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/critic.md` | 79 | 82 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/debugger.md` | 85 | 88 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/deep-executor.md` | 105 | 107 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/dependency-expert.md` | 91 | 94 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/designer.md` | 96 | 98 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/executor.md` | 92 | 94 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/explore.md` | 104 | 107 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/git-master.md` | 84 | 87 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/information-architect.md` | 28 | 29 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/performance-reviewer.md` | 86 | 89 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/planner.md` | 108 | 111 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/product-analyst.md` | 28 | 29 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/product-manager.md` | 33 | 34 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/qa-tester.md` | 90 | 93 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/quality-reviewer.md` | 98 | 100 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/quality-strategist.md` | 33 | 34 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/researcher.md` | 88 | 91 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/scientist.md` | 84 | 87 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/security-reviewer.md` | 119 | 121 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/style-reviewer.md` | 79 | 82 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/test-engineer.md` | 96 | 98 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/ux-researcher.md` | 28 | 29 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/verifier.md` | 87 | 90 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/vision.md` | 67 | 70 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+| `prompts/writer.md` | 78 | 81 | XML-like wrapper blocks converted to Markdown section hierarchy; output/checklist sections normalized. | No intentional functional delta in migration commit. |
+
+## Validation
+
+- Commit diff summary: `30 files changed, 2439 insertions(+), 2511 deletions(-)`
+- Spot-checks performed on role-heavy prompts (`planner`, `executor`, `explore`) confirmed semantic parity with formatting normalization.
+
+---
+
+## Orchestration Brain Migration (`AGENTS.md`, `templates/AGENTS.md`)
+
+### Summary
+
+These files are the instruction root that RCS expects Codex to follow across a workspace.
+Changes here are primarily about aligning instructions with Codex CLI tool contracts.
+
+### Key Deltas
+
+- Updated child-agent delegation guidance to reflect the Codex `spawn_agent` API:
+  - Use `spawn_agent(message: "<role prompt>\n\nTask: ...")` conventions.
+  - Removed legacy "instructions" phrasing.
+- Expanded MCP tooling catalog and mode lifecycle expectations so orchestrators can use the full MCP surface correctly.
+- `templates/AGENTS.md` header normalized to match `AGENTS.md` and removed the non-compliant template opener.
+
+### Diff Stats
+
+| File | Added | Removed | Notes |
+|---|---:|---:|---|
+| `AGENTS.md` | 42 | 10 | Tooling + delegation guidance expanded; semantics preserved. |
+| `templates/AGENTS.md` | 7 | 7 | Header/tone normalized; still intended as a template copy. |
+
+### Unified Guidance Schema Follow-Up (AGENTS + Runtime/Worker Alignment)
+
+- Added canonical schema document: `docs/guidance-schema.md`.
+- Added explicit schema-contract sections to:
+  - `AGENTS.md`
+  - `templates/AGENTS.md`
+- Normalized worker task guidance in `AGENTS.md` runtime worker overlay:
+  - file path now uses `tasks/task-<id>.json`
+  - API id rule now explicitly requires bare id `task_id: "<id>"` (never `"task-<id>"`).
+- Marker contracts remain unchanged:
+  - `<!-- RCS:RUNTIME:START --> ... <!-- RCS:RUNTIME:END -->`
+  - `<!-- RCS:TEAM:WORKER:START --> ... <!-- RCS:TEAM:WORKER:END -->`
+
+Behavior note: this follow-up is additive and wording-focused; no task-state model or MCP API contract changes were introduced.
+
+---
+
+## Skill Prompt Migration (`skills/*/SKILL.md`)
+
+### Summary
+
+Skill docs are operational runbooks. The migration focused on:
+- Removing Claude-era paths/terminology
+- Aligning config guidance with Codex-first paths (`~/.codex/…`, `CODEX_HOME`)
+- Preserving each skill's contract/intent while improving correctness for Codex CLI users
+
+### Behavior Notes
+
+- These are documentation / instruction changes; they do not directly change runtime logic.
+- One meaningful correction was made: the "agent teams" enablement guidance in `skills/rcs-setup/SKILL.md` was updated to enable Codex features via `~/.codex/config.toml` rather than legacy `settings.json` env vars.
+
+### Per-File Matrix
+
+| Skill File | Added | Removed | Structural Highlights | Behavior Delta |
+|---|---:|---:|---|---|
+| `skills/analyze/SKILL.md` | 1 | 1 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/autopilot/SKILL.md` | 11 | 16 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/code-review/SKILL.md` | 1 | 1 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/configure-notifications/SKILL.md` | 0 | 0 | Canonical notification setup skill replacing standalone configure-* variants. | Catalog/install surface now converges on one entry point. |
+| `skills/doctor/SKILL.md` | 47 | 45 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/ecomode/SKILL.md` | 1 | 1 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/frontend-ui-ux/SKILL.md` | 2 | 2 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/help/SKILL.md` | 1 | 1 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/learner/SKILL.md` | 5 | 5 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/rcs-setup/SKILL.md` | 144 | 156 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/plan/SKILL.md` | 1 | 1 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/project-session-manager/SKILL.md` | 5 | 5 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/release/SKILL.md` | 3 | 3 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/research/SKILL.md` | 10 | 15 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/security-review/SKILL.md` | 1 | 1 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/skill/SKILL.md` | 20 | 20 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/tdd/SKILL.md` | 1 | 1 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/ultrapilot/SKILL.md` | 11 | 16 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+| `skills/writer-memory/SKILL.md` | 1 | 1 | Codex path/terminology normalization; examples updated to Codex-first conventions. | No direct runtime behavior change; instruction correctness improved. |
+
+### Hotspots Worth Reviewing
+
+- `skills/rcs-setup/SKILL.md`: largest edit surface; includes team enablement guidance (`~/.codex/config.toml` `[features]` flags) and teammate display preference storage (`~/.codex/.rcs-config.json`).
+- `skills/doctor/SKILL.md`: updated hook/config inspection language; still contains optional legacy remediation guidance.
+- `skills/autopilot/SKILL.md`, `skills/research/SKILL.md`, `skills/ultrapilot/SKILL.md`: config examples updated to TOML.
+
+## Follow-up Classification Notes
+
+- `prompts/*.md` should be treated as the canonical source set for XML-tagged subagent role prompts, even when install/runtime layers wrap them in TOML or other launcher-specific envelopes.
+- `prompts/sisyphus-lite.md` is intentionally classified as a specialized worker behavior prompt. It is not part of the primary public role catalog alongside prompts such as `executor`, `planner`, or `architect`.
+- Team worker/runtime overlays may borrow Sisyphus-lite behavior patterns, but that does not promote it to a first-class routed role.

package/docs/prs/dev-deprecate-team-ralph.md

@@ -0,0 +1,100 @@
+> Archive context: retained release and migration collateral from the pre-v0.1.0 fork-to-RCS transition. Links are normalized to the canonical JustineDevs repository, but historical chronology and contributor references may still describe pre-fork development.
+
+# PR Draft: Deprecate `rcs team ralph` and keep team standalone
+
+## Target branch
+`dev`
+
+## Title
+Deprecate `rcs team ralph` and remove linked team↔Ralph lifecycle machinery
+
+## Summary
+This PR removes the built-in linked `rcs team ralph` workflow and restores a clean separation between `team` and `ralph`.
+
+After this change:
+- `rcs team ...` / `$team ...` is the only supported team launch path
+- `rcs ralph ...` / `$ralph ...` remains available as a separate, explicit follow-up
+- team no longer creates, syncs, or depends on linked Ralph state
+- legacy `rcs team ralph ...` usage now fails with a clear deprecation error instead of being tolerated silently
+
+This matches the intended product model: team can own coordinated execution and verification itself, while Ralph remains an independent persistence loop that a leader or separate worker may choose to run later.
+
+## Why
+The old team↔Ralph linkage had become bloated orchestration glue:
+- bridge code between team and Ralph mode state
+- linked lifecycle/profile branching
+- notify-hook terminal sync behavior
+- cleanup/shutdown special-casing
+- extra tests and documentation for behavior that should be two separate tools
+
+That coupling made the runtime harder to reason about without providing enough value to justify the complexity.
+
+## What changed
+### Removed
+- linked team↔Ralph runtime bridge
+- linked notify-hook terminal sync
+- linked cleanup/shutdown policy behavior
+- `linked_ralph` lifecycle profile handling
+- advertised/generated `rcs team ralph ...` launch hints
+- linked-Ralph-specific tests and compatibility paths inside team runtime
+
+### Updated
+- team help/usage text now documents only `rcs team [N:agent-type] "<task>"`
+- planning, ralplan, team, and deep-interview guidance now describe a **team verification path** rather than a built-in `team -> ralph` lifecycle
+- follow-up planner and pipeline launch hints now generate plain `rcs team ...`
+- shutdown/resume/state flows now operate on standalone team semantics only
+
+### Behavior change
+- `rcs team ralph ...` is now rejected with an explicit deprecation error:
+  - use `rcs team ...` for coordinated team execution
+  - use `rcs ralph ...` separately if a later persistent follow-up loop is still needed
+
+## Notable implementation areas
+- `src/cli/team.ts`
+- `src/cli/index.ts`
+- `src/team/runtime.ts`
+- `src/team/runtime-cli.ts`
+- `src/team/api-interop.ts`
+- `src/team/state.ts`
+- `src/team/state/types.ts`
+- `src/scripts/notify-hook.ts`
+- `src/team/followup-planner.ts`
+- `src/pipeline/stages/team-exec.ts`
+
+## Deleted surfaces
+- `src/team/linked-ralph-bridge.ts`
+- `src/scripts/notify-hook/linked-sync.ts`
+- `src/cli/__tests__/team-linked-ralph.test.ts`
+- `src/team/__tests__/linked-ralph-bridge.test.ts`
+- `src/hooks/__tests__/notify-hook-linked-sync.test.ts`
+
+## Impact
+### Before
+- `rcs team ralph ...` had special runtime behavior
+- team state could carry linked Ralph metadata
+- notify-hook and shutdown logic had linked team↔Ralph branches
+- docs/planning artifacts promoted a built-in linked verification path
+
+### After
+- `rcs team ...` runs coordinated team execution only
+- team owns its own verification lanes and shutdown evidence
+- `rcs ralph ...` is separate and explicit
+- a leader or separate worker may still choose to run Ralph later
+- there is no built-in linked team+Ralph lifecycle anymore
+
+## Validation
+- [x] `npm run build`
+- [x] targeted tests covering CLI parsing, runtime/state behavior, team API interop, planner handoff generation, and hook/contract expectations
+
+Verification command:
+```bash
+npm run build && node --test   dist/cli/__tests__/team.test.js   dist/team/__tests__/followup-planner.test.js   dist/pipeline/__tests__/stages.test.js   dist/hooks/__tests__/keyword-detector.test.js   dist/hooks/__tests__/consensus-execution-handoff.test.js   dist/hooks/__tests__/deep-interview-contract.test.js   dist/team/__tests__/runtime.test.js   dist/team/__tests__/state.test.js   dist/team/__tests__/api-interop.test.js
+```
+
+Result:
+- `428 pass, 0 fail`
+
+## Risks / notes
+- This is an intentional CLI behavior break for users still invoking `rcs team ralph ...`
+- The break is now explicit and easier to understand than the previous silent compatibility path
+- Separate Ralph execution remains supported, but it must be initiated intentionally rather than being baked into team runtime semantics

package/docs/prs/dev-fix-ralph-live-pane-invariant.md

@@ -0,0 +1,34 @@
+> Archive context: retained release and migration collateral from the pre-v0.1.0 fork-to-RCS transition. Links are normalized to the canonical JustineDevs repository, but historical chronology and contributor references may still describe pre-fork development.
+
+# PR Draft: Preserve verified Ralph pane anchors and avoid tmux-hook target drift
+
+## Target branch
+`dev`
+
+## Summary
+This follow-up fixes pane rebinding drift in the managed tmux recovery paths that showed up during review of the Ralph resume / continue work.
+
+The main issue was stored-pane drift. Once a Ralph pane anchor had already been verified as part of the correct managed session, recovery could still rescan the whole tmux session and rebind to whichever Codex pane was currently focused, or fall back to a shell-degraded pane that only historically started as Codex. In multi-pane Codex sessions that could silently move future watcher or auto-nudge injections onto the wrong lane.
+
+On current `dev`, the pre-guard tmux-hook target drift path is already absent in production code. This branch keeps that invariant covered with a focused regression so the repo-scoped session target does not get rewritten on skipped turns.
+
+## Changes
+- split managed-pane heuristics so `TMUX_PANE` detection can stay permissive while stored-anchor retention stays strict
+- keep the verified anchor pane in `resolveManagedPaneFromAnchor()` only when it still looks like a live Codex-managed pane instead of a shell that merely started as Codex, while still retaining a verified anchor on transient command-state lookup failure
+- teach the Ralph continue watcher to re-resolve stored pane anchors against the current managed session before sending continue nudges
+- only rescan the tmux session when the anchor is gone or no longer looks agent-owned, and fail closed when no live managed sibling exists
+- add regressions for the direct managed-pane helper, watcher rebinding behavior, auto-nudge anchor retention / node-shell upgrade paths, and pre-guard config-drift handling
+
+## Why this is good
+- prevents Ralph continue / resume state from jumping between Codex panes just because focus changed
+- keeps watcher and auto-nudge behavior aligned with the stored managed anchor contract
+- keeps the current `dev` pre-guard skip invariant locked by test so repo-scoped session targets do not drift back to pane ids
+- makes watcher recovery follow the same live-anchor contract as notify-hook / auto-nudge
+
+## Validation
+- [x] `npx biome lint src/scripts/notify-hook/managed-tmux.ts src/scripts/notify-fallback-watcher.ts src/scripts/notify-hook/auto-nudge.ts src/hooks/__tests__/notify-hook-managed-tmux.test.ts src/hooks/__tests__/notify-hook-tmux-heal.test.ts src/hooks/__tests__/notify-fallback-watcher.test.ts src/hooks/__tests__/notify-hook-auto-nudge.test.ts docs/prs/dev-fix-ralph-live-pane-invariant.md`
+- [x] `npm run build`
+- [x] `node --test dist/hooks/__tests__/notify-fallback-watcher.test.js dist/hooks/__tests__/notify-hook-auto-nudge.test.js dist/hooks/__tests__/notify-hook-managed-tmux.test.js dist/hooks/__tests__/notify-hook-tmux-heal.test.js`
+
+## Related
+- follow-up to the Ralph resume / managed tmux healing review pass

package/docs/prs/dev-issue-715-team-brain-role-split.md

@@ -0,0 +1,22 @@
+> Archive context: retained release and migration collateral from the pre-v0.1.0 fork-to-RCS transition. Links are normalized to the canonical JustineDevs repository, but historical chronology and contributor references may still describe pre-fork development.
+
+# PR Draft: Fix issue #715 team brain / role split
+
+## Target branch
+`dev`
+
+## Summary
+This follow-up PR fixes issue #715 by separating team-mode execution defaults from the generic executor lane.
+
+I plan to fix #715 via this PR.
+
+## Changes
+- add a `team-executor` role prompt for supervised default team execution
+- register `team-executor` in the catalog/setup path so the prompt and native agent are actually installable for real team runs
+- keep explicit `N:agent-type` team launches unchanged
+- add a conservative fanout guard so weakly structured small team tasks do not over-split by default
+- add focused regression tests for role discovery and decomposition behavior
+
+## Validation
+- [x] `npm run lint`
+- [x] `npm test`

package/docs/prs/dev-team-ralph-workflow-positioning.md

@@ -0,0 +1,38 @@
+> Archive context: retained release and migration collateral from the pre-v0.1.0 fork-to-RCS transition. Links are normalized to the canonical JustineDevs repository, but historical chronology and contributor references may still describe pre-fork development.
+
+# PR Draft: Document the `ralplan -> team -> ralph` workflow
+
+## Target branch
+`dev`
+
+## Summary
+This PR documents one of RCS's strongest high-control workflows: `ralplan -> team -> ralph`. The goal is to make the README explain not only that team mode exists, but why it matters even when `$ultrawork` already provides parallel execution.
+
+The key point is that team mode is not just fanout. It is coordinated, inspectable, runtime-aware execution. Workers can share blocker awareness, execution stays visible through tmux panes plus durable state, and the leader retains stronger control over recovery and lifecycle commands. Pairing that with `ralplan` up front and `ralph` at the back creates a workflow that is both fast and operationally disciplined.
+
+## Changes
+- clarify the positioning difference between `$team` and `$ultrawork`
+- add README guidance for the recommended high-control workflow: `ralplan -> team -> ralph`
+- add an issue draft proposing stronger `ralplan` support for team follow-up planning, such as `--followup team`
+
+## Why this is good
+- Explains a real product strength more clearly to contributors and users.
+- Helps advanced users understand when to choose team mode over simpler parallel fanout.
+- Frames a credible design direction: planning output that already anticipates team staffing and follow-up execution.
+- Makes `autopilot` easier to explain too, because it can be described as an automatic chaining layer over the same underlying workflow.
+
+## Design direction
+The docs position `ralplan` as the place where team follow-up should become more explicit. In future work, `ralplan` can emit lane recommendations, role placement hints, and launch guidance for a direct `team` handoff, while `ralph` remains the persistence and verification layer.
+
+## Expected outcomes
+- Better onboarding for users evaluating RCS's orchestration model
+- Easier explanation of why team mode is distinct from ultrawork
+- Clearer path from planning to execution for future feature work
+- Better support for mixed-CLI teams and runtime-heavy edge-case work
+
+## Validation
+- [ ] `npm run build` *(TypeScript build)*
+- [ ] `npm test`
+
+## Related
+- Proposed issue: `docs/issues/team-ralph-followup-team.md`

package/docs/prs/experimental-dev-omx-sparkshell.md

@@ -0,0 +1,56 @@
+> Archive context: retained release and migration collateral from the pre-v0.1.0 fork-to-RCS transition. Links are normalized to the canonical JustineDevs repository, but historical chronology and contributor references may still describe pre-fork development.
+
+# PR Draft: Rebase `feat/rcs-sparkshell` onto `experimental/dev`
+
+## Target branch
+`experimental/dev`
+
+## Summary
+This PR rebases the `rcs sparkshell` feature line onto `experimental/dev` and preserves the follow-on team-status inspection work built on top of it.
+
+It adds the native Rust-backed `rcs sparkshell <command> [args...]` flow, plus a long sequence of `rcs team status` improvements that surface pane-aware inspection metadata and ready-to-run sparkshell commands for leader triage.
+
+## What’s included
+### `rcs sparkshell`
+- adds CLI dispatch/help for `rcs sparkshell`
+- adds `src/cli/sparkshell.ts` for native binary discovery and launch
+- adds the Rust crate under `native/rcs-sparkshell/`
+- adds packaging/build helpers:
+  - `scripts/build-sparkshell.mjs`
+  - `scripts/test-sparkshell.mjs`
+- stages the packaged native binary under `bin/native/linux-x64/rcs-sparkshell`
+- adds focused CLI + packaging tests
+
+### `rcs team status` inspection improvements
+- leader/hud/worker pane ids in text and JSON output
+- direct sparkshell inspection commands per pane
+- prioritized inspection queue and `inspect_next`
+- dead/non-reporting worker targeting
+- richer recommended inspection metadata, including:
+  - worker CLI, role, liveness, index, turn/activity context
+  - task id, subject, description, status, lifecycle, approvals, claims, dependencies
+  - worktree/runtime paths and team/worker state artifact paths
+  - structured `recommended_inspect_items` JSON payloads
+
+## Rebase / integration fixes included
+- merged `experimental/dev` CLI/explore surfaces with sparkshell command routing
+- excluded `native/rcs-sparkshell` from the root Cargo workspace so manifest-path cargo commands work again
+- refreshed/added missing compat doctor fixtures after the rebase
+- hardened MCP team-job cleanup to resolve the jobs directory from the current home directory dynamically
+- updated tests for newly surfaced claim-lock inspection metadata
+
+## Local verification
+- `npm run lint`
+- `npm run check:no-unused`
+- `npm run build:full`
+- `cargo test --manifest-path native/rcs-sparkshell/Cargo.toml`
+- `node scripts/build-sparkshell.mjs`
+- `node scripts/test-sparkshell.mjs`
+- `node bin/rcs.js sparkshell cargo --version`
+- `node bin/rcs.js sparkshell npm --version`
+- `node bin/rcs.js sparkshell git log --oneline -3`
+- `npm test`
+
+## Notes
+- `npm test` removes the staged packaged sparkshell binary as part of packaging cleanup; I restored the tracked binary afterward.
+- Native Rust build artifacts under `native/rcs-sparkshell/target/` were removed after verification.