session-orchestrator 3.16.0

package/skills/write-executable-plan/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: write-executable-plan
+description: Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects "TBD", "TODO", "add error handling", "similar to Task N".
+model: inherit
+color: green
+tools: Read, Grep, Glob, Bash, Write
+---
+
+# Write Executable Plan
+
+> Bite-sized plans for parallel agents. No placeholders. No vague steps.
+
+## When to use
+
+- A PRD from `/plan feature` exists but you need a step-by-step implementation plan
+- A `/brainstorm` design is approved and you want to skip the PRD layer
+- Multiple agents will execute the plan in parallel and need conflict-free task boundaries
+- The work is complex enough that describing it to an agent loses fidelity
+
+## When NOT to use
+
+- Trivial 1-file changes (just do them; no plan needed)
+- Pure exploration (use `/brainstorm` instead)
+- Bug investigation (use `/debug` instead)
+- The source PRD is vague or unapproved (get PRD approval before planning execution)
+
+## Phase 0: Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.
+
+<HARD-GATE>
+Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints.
+</HARD-GATE>
+
+## Phase 1: Source Selection
+
+Accept ONE of the following inputs (in order of preference):
+
+1. **PRD path** — `docs/prd/YYYY-MM-DD-<feature>.md` produced by `/plan feature`
+2. **Design spec path** — `docs/specs/YYYY-MM-DD-<slug>-design.md` produced by `/brainstorm`
+3. **Inline description** — user provides a free-text description; prompt for elaboration via AUQ before proceeding
+
+If no source is provided and `$ARGUMENTS` is empty, ask via AUQ:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Which source should this plan be based on?",
+    header: "Plan Source",
+    options: [
+      { label: "Existing PRD (Recommended)", description: "Point me to docs/prd/YYYY-MM-DD-<feature>.md — most precise decomposition." },
+      { label: "Design spec from /brainstorm", description: "Point me to docs/specs/YYYY-MM-DD-<slug>-design.md — skips formal PRD." },
+      { label: "Describe inline", description: "Paste or describe the feature — I will ask follow-up questions before planning." }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+Read the source file and extract:
+- **Feature title** (for filename slug and plan header)
+- **Acceptance criteria** or equivalent (drives Task decomposition)
+- **Explicit out-of-scope items** (excludes from plan)
+- **File inventory** if present (seeds the whole-plan Files block)
+
+## Phase 2: Decomposition
+
+Break the source into Tasks. Each Task MUST satisfy all of these constraints:
+
+- **Single owner** — one agent role (e.g., `code-implementer`, `test-writer`), not "the team"
+- **Bounded file set** — lists every file it creates, modifies, or tests; no file appears in two Tasks
+- **Independently testable** — after Step 4 the task stands on its own; no cross-task dependencies in the test command
+- **2-5 minute wall-clock estimate** — if the estimate exceeds 5 minutes, split the Task; if two Tasks share a file, merge or re-scope
+
+Before writing Tasks, output a brief decomposition plan in plain text:
+
+```
+## Decomposition (draft)
+- Task 1: <title> — <owner> — ~<N> min — Files: <list>
+- Task 2: <title> — <owner> — ~<N> min — Files: <list>
+...
+```
+
+If any task's file set overlaps another, surface the conflict and resolve it before writing Steps.
+
+## Phase 3: Step Authoring (per Task)
+
+Each Task gets exactly 5 steps in this order. All 5 steps are mandatory.
+
+### Step 1: Write the failing test
+
+**EARS seam:** If the source PRD/spec carries an `## Acceptance Criteria (EARS)` (or `## 3.A`) section, apply the EARS→vitest 1:1 mapping below to emit per-clause test stubs. If no EARS section is present, fall back to manual derivation from prose.
+
+#### EARS → vitest mapping (1:1)
+
+| EARS pattern | vitest construct | example skeleton |
+|---|---|---|
+| **Ubiquitous** ("The S shall R.") | invariant `it()` — no setup branching | `it('S shall R', () => { /* assert invariant */ })` |
+| **State-driven** ("While P, the S shall R.") | `describe()` for state context, nested `it()` for assertion | `describe('while P', () => { it('S shall R', () => { /* enter P; expect R */ }) })` |
+| **Event-driven** ("When T, the S shall R.") | arrange/trigger/expect inside `it()` | `it('when T, S shall R', () => { /* arrange; trigger T; expect R */ })` |
+| **Optional feature** ("Where F, the S shall R.") | `it.skipIf(!F)` (vitest conditional) | `it.skipIf(!F)('where F, S shall R', () => { /* expect R */ })` |
+| **Unwanted behaviour** ("If C, then the S shall R.") | error-path `it()` with negative assertion or `toThrow()` | `it('if C, then S shall R', () => { /* induce C; expect R */ })` |
+
+Reference test exemplifying this pattern: `tests/lib/wave-executor/persona-gate-hook.test.mjs` (shipped at #481).
+
+Follow `.claude/rules/testing.md` § "Test Quality — False-Positive Prevention": one meaningful assertion per `it`, behaviour not implementation, no branching, hardcoded expected values.
+
+Provide:
+- Exact file path (absolute from project root)
+- Complete, runnable test code — no `// ...`, no placeholders, no `// implement later`
+- One sentence explaining why this test verifies the intended behavior
+
+The test MUST fail before Step 3 is applied. If the behavior already exists and cannot fail, pick a harder assertion or a new edge case.
+
+### Step 2: Run the test to confirm it fails
+
+Provide:
+- Exact command (e.g., `npm test -- tests/unit/my-module.test.mjs`)
+- Expected terminal output — the specific assertion failure line that proves the test exercises missing code (not a generic "FAIL" — copy the actual error shape)
+
+### Step 3: Implement the minimal code
+
+Provide:
+- Exact file paths labeled `Create:` or `Modify:`
+- Complete code — every function, every import, every export. No `// add appropriate logic`, no `// similar to above`, no `...`
+- DRY constraint: reuse existing utilities; do not duplicate logic that already exists in the codebase
+- YAGNI constraint: implement exactly what makes Step 2's test pass; no speculative features
+
+### Step 4: Run the test to verify it passes
+
+Provide:
+- Same command as Step 2 (copy verbatim)
+- Expected terminal output showing the test suite PASS line with the test name visible
+
+### Step 5: Commit
+
+Provide:
+- Exact commit message in Conventional Commits format: `type(scope): subject`
+- Scope: the primary module or directory affected by this Task
+- Subject: imperative mood, max 72 characters, no period
+- Files staged: only this Task's files (list them)
+
+## Phase 4: Placeholder Linter
+
+Before writing the plan to disk, scan every Step in every Task for forbidden strings. Any match is a rejection — fix before writing.
+
+**Forbidden strings (case-insensitive):**
+
+| Pattern | Why forbidden |
+|---------|---------------|
+| `TBD`, `TODO`, `FIXME`, `XXX` | Deferred decisions defeat the plan's purpose |
+| `add appropriate error handling` | Vague — specify the exact error type and handling code |
+| `add error handling` | Same — write the catch block |
+| `similar to Task N`, `same as above`, `like Task N` | Forces the executor to cross-reference; defeats file-disjoint execution |
+| `etc.` | Incomplete enumeration — list every item |
+| `[fill in]`, `<placeholder>`, `<YOUR_VALUE>` | Template leftovers — fill them in |
+| `...` inside a code block | Ellipsis in implementation code means incomplete code |
+
+Prose ellipsis (e.g., "Phase 1... Phase 2...") is acceptable. Only code-block ellipsis is forbidden.
+
+Any hit → surface to user via AUQ:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "The placeholder linter found forbidden strings in the draft plan:\n\n[list each hit with Task number, Step number, and matched text]\n\nHow do you want to proceed?",
+    header: "Placeholder Linter",
+    options: [
+      { label: "Fix automatically (Recommended)", description: "I will resolve each hit by filling in the missing specifics before writing the plan." },
+      { label: "Show me each hit interactively", description: "Walk me through each one so I can provide the missing detail." }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+Fix all hits before Phase 5.
+
+## Phase 5: Write Plan
+
+Ensure the target directory exists:
+
+```bash
+mkdir -p docs/plans
+```
+
+Generate today's date via `date +%Y-%m-%d`. Derive `<feature-slug>` from the feature title (lowercase, hyphens, no special characters, max 40 characters).
+
+Write to: `docs/plans/YYYY-MM-DD-<feature-slug>.md`
+
+Use the template in `plan-template.md` (same directory as this SKILL.md) as the structural guide. Fill every slot. The written plan must:
+
+- Open with `# Plan: <feature title>` and a `Source:` / `Created:` / `Status: draft` header block. The `Source:` line MUST carry the tracking Issue/Epic reference inline as `#NNN` (e.g. `Source: docs/prd/2026-07-09-foo.md (#786)`). This `#NNN` is load-bearing: it is the anchor the `archive-closed-plans` custom-phase reads (via `scripts/archive-closed-prds.mjs`) to detect that a plan's feature/Epic is closed and archive the plan into the Meta-Vault. A plan with no `#NNN` in its header is never archived (fail-closed `no-epic-ref`) — it lingers in `docs/plans/` indefinitely.
+- Include a whole-plan `## Files` section listing all Create / Modify / Test paths across all Tasks
+- Contain one `## Task N: <title>` section per Task, each with its per-task `### Files` block and Steps 1-5
+- Pass the Phase 4 linter with zero hits
+
+## Phase 6: Hand-off
+
+Present the plan path and task count to the user via AUQ:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Executable plan written to docs/plans/YYYY-MM-DD-<slug>.md ([N] tasks, ~[total] min estimated).\n\nHow do you want to execute it?",
+    header: "Plan Hand-off",
+    options: [
+      { label: "Dispatch via wave-executor (Recommended)", description: "Parallel agents execute all tasks simultaneously. Fastest for file-disjoint tasks." },
+      { label: "Execute coordinator-direct", description: "One task at a time in this session. Safer for tasks with shared state." },
+      { label: "Revise the plan first", description: "I have feedback — describe what to change and I will update the plan." },
+      { label: "Done for now", description: "Keep the plan as a reference; no immediate execution." }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+If the user selects "Revise the plan first", incorporate the feedback, update the plan file, re-run the Phase 4 linter, and re-present Phase 6.
+
+If the user selects "Dispatch via wave-executor", hand off to `skills/wave-executor/SKILL.md` with the plan path as input.
+
+## Anti-Patterns
+
+- **Steps that say "implement the feature"** without exact file paths and complete code — this is the most common failure mode; reject it at Phase 4
+- **Tasks with overlapping file scopes** — agents executing in parallel will conflict; the decomposition must be file-disjoint
+- **Plans without a per-Task Files block** — forces agents to grep the codebase to discover their scope, which loses the speed advantage of planning
+- **Skipping Phase 4** — placeholders in a plan silently cascade into every agent that executes it; one "TBD" can stall an entire wave
+- **Estimating tasks at >5 minutes** — if a task is that large, it contains multiple logical changes; split it
+- **Vague commit messages in Step 5** — `feat(core): update things` is not acceptable; the scope and subject must be derivable from the Task's file set without reading the diff
+
+## See Also
+
+- `skills/plan/SKILL.md` — produces the PRD this skill consumes
+- `skills/brainstorm/SKILL.md` — alternative source (design spec)
+- `skills/wave-executor/SKILL.md` — consumes the plan for parallel execution
+- `.claude/rules/testing.md` § "Test Quality — False-Positive Prevention" — test conventions to follow in Step 1
+- `skills/write-executable-plan/plan-template.md` — structural template used in Phase 5

package/skills/write-executable-plan/plan-template.md

@@ -0,0 +1,154 @@
+# Plan: <FEATURE_TITLE>
+Source: <SOURCE_PATH> (#<ISSUE_OR_EPIC_NUMBER>)
+Created: <ISO_TIMESTAMP>
+Status: draft
+
+## Summary
+
+<ONE_PARAGRAPH_SUMMARY_OF_WHAT_THIS_PLAN_IMPLEMENTS_AND_WHY>
+
+## Files (whole-plan)
+
+- Create:
+  - <PATH_TO_NEW_FILE_1>
+  - <PATH_TO_NEW_FILE_2>
+- Modify:
+  - <PATH_TO_EXISTING_FILE_1>
+  - <PATH_TO_EXISTING_FILE_2>
+- Test:
+  - <PATH_TO_TEST_FILE_1>
+  - <PATH_TO_TEST_FILE_2>
+
+---
+
+## Task 1: <TASK_1_TITLE>
+
+Owner: <AGENT_ROLE>
+Estimated: <MINUTES> min
+
+### Files
+
+- Create: <PATHS_OR_NONE>
+- Modify: <PATHS_OR_NONE>
+- Test: <PATHS_OR_NONE>
+
+### Step 1: Write the failing test
+
+File: `<TEST_FILE_PATH>`
+
+```<LANG>
+<COMPLETE_TEST_CODE>
+// All imports, describe blocks, and assertions included.
+// No placeholders. Runnable as-is.
+```
+
+Why: <ONE_SENTENCE_EXPLAINING_WHAT_BEHAVIOR_THIS_TEST_VERIFIES>
+
+**EARS seam:** if the source PRD/spec carries an EARS Acceptance Criteria section (`## 3.A` or `## Acceptance Criteria (EARS)`), apply the 5-pattern mapping from `SKILL.md § EARS → vitest mapping` to emit the test skeleton. Do not manually re-derive from prose when EARS is present — the mapping is deterministic.
+
+### Step 2: Run to confirm failure
+
+Command: `<EXACT_COMMAND>`
+
+Expected output:
+```
+<EXPECTED_FAILURE_OUTPUT>
+// The specific assertion error line that proves the test exercises missing code.
+// Example: AssertionError: expected undefined to equal 'value'
+```
+
+### Step 3: Implement
+
+Files:
+- Create: `<PATH>` / Modify: `<PATH>`
+
+```<LANG>
+<COMPLETE_IMPLEMENTATION_CODE>
+// All imports, exports, and logic included.
+// No placeholders. No "// add error handling". No "...".
+```
+
+### Step 4: Run to verify pass
+
+Command: `<EXACT_COMMAND>` (same as Step 2)
+
+Expected output:
+```
+<EXPECTED_PASS_OUTPUT>
+// Example: ✓ Task 1 description (12ms)
+// 1 passed
+```
+
+### Step 5: Commit
+
+Message:
+```
+<TYPE>(<SCOPE>): <SUBJECT_IN_IMPERATIVE_MOOD_MAX_72_CHARS>
+```
+
+Files staged: <LIST_ONLY_THIS_TASKS_FILES>
+
+---
+
+## Task 2: <TASK_2_TITLE>
+
+Owner: <AGENT_ROLE>
+Estimated: <MINUTES> min
+
+### Files
+
+- Create: <PATHS_OR_NONE>
+- Modify: <PATHS_OR_NONE>
+- Test: <PATHS_OR_NONE>
+
+### Step 1: Write the failing test
+
+File: `<TEST_FILE_PATH>`
+
+```<LANG>
+<COMPLETE_TEST_CODE>
+```
+
+Why: <ONE_SENTENCE_EXPLAINING_WHAT_BEHAVIOR_THIS_TEST_VERIFIES>
+
+### Step 2: Run to confirm failure
+
+Command: `<EXACT_COMMAND>`
+
+Expected output:
+```
+<EXPECTED_FAILURE_OUTPUT>
+```
+
+### Step 3: Implement
+
+Files:
+- Create: `<PATH>` / Modify: `<PATH>`
+
+```<LANG>
+<COMPLETE_IMPLEMENTATION_CODE>
+```
+
+### Step 4: Run to verify pass
+
+Command: `<EXACT_COMMAND>` (same as Step 2)
+
+Expected output:
+```
+<EXPECTED_PASS_OUTPUT>
+```
+
+### Step 5: Commit
+
+Message:
+```
+<TYPE>(<SCOPE>): <SUBJECT_IN_IMPERATIVE_MOOD_MAX_72_CHARS>
+```
+
+Files staged: <LIST_ONLY_THIS_TASKS_FILES>
+
+---
+
+<!-- Add Task N sections following the same structure as Task 1 and Task 2 above. -->
+<!-- Every task must have exactly 5 steps in the order: test → fail-run → implement → pass-run → commit. -->
+<!-- No task may share a file path with another task. -->

package/templates/_minimal/CLAUDE.md.tmpl

@@ -0,0 +1,41 @@
+<!-- source: session-orchestrator plugin (canonical: templates/_minimal/CLAUDE.md.tmpl) — customize freely; this header records provenance only -->
+# {{PROJECT_TITLE}}
+
+{{PROJECT_DESCRIPTION}}
+
+## Stack Defaults
+
+- Language / runtime: {{STACK_LANGUAGE}}
+- Package manager: {{STACK_PACKAGE_MANAGER}}
+- Test runner: {{STACK_TEST_RUNNER}}
+- Linter: {{STACK_LINTER}}
+
+## Commands
+
+- Dev: `{{CMD_DEV}}`
+- Test: `{{CMD_TEST}}`
+- Build: `{{CMD_BUILD}}`
+- Lint: `{{CMD_LINT}}`
+
+## Conventions
+
+{{CONVENTIONS}}
+
+## Harte Regeln
+
+{{HARD_RULES_TABLE}}
+
+## Session Config
+
+project-name: {{PROJECT_NAME}}
+vcs: {{VCS}}
+persistence: true
+enforcement: warn   # strict | warn | off
+waves: 5
+agents-per-wave: 6
+test-command: {{TEST_COMMAND}}
+typecheck-command: {{TYPECHECK_COMMAND}}
+lint-command: {{LINT_COMMAND}}
+plan-baseline-path: {{PLAN_BASELINE_PATH}}
+recent-commits: 20
+stale-branch-days: 7

package/templates/_minimal/README.md.tmpl

@@ -0,0 +1,15 @@
+# {{PROJECT_TITLE}}
+
+{{PROJECT_DESCRIPTION}}
+
+## Usage
+
+{{USAGE_INSTRUCTIONS}}
+
+## Development
+
+{{DEVELOPMENT_INSTRUCTIONS}}
+
+## License
+
+{{LICENSE}}

package/templates/_minimal/gitignore.tmpl

@@ -0,0 +1,47 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Build output
+dist/
+build/
+out/
+.next/
+.nuxt/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+env/
+.pytest_cache/
+*.egg-info/
+dist/
+*.dist-info/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+npm-debug.log*
+yarn-debug.log*
+pnpm-debug.log*
+
+# Testing
+coverage/
+.nyc_output/

package/templates/_shared/harte-regeln.md

@@ -0,0 +1,16 @@
+<!-- source: session-orchestrator plugin (canonical: templates/_shared/harte-regeln.md) -->
+## Harte Regeln
+
+Nicht verhandelbar — gilt unabhängig vom Wachstum dieses Repos, auch unterhalb
+der `.claude/rules/`-Graduationsschwelle (#730/H6):
+
+1. Keine Secrets/API-Keys committen (auch nicht in `.env.example`-Kommentaren).
+2. Kein `git push --force` auf den Default-Branch ohne explizite Rückfrage.
+3. Kein `git add -A` / `git add .` — Dateien einzeln stagen.
+4. Destruktive Kommandos (`rm -rf`, `git reset --hard`, `git checkout -- <file>`)
+   nur nach expliziter Bestätigung.
+5. Status-Dokumente (STATE.md, README-Status-Sections, Dashboards) sind INDEX,
+   nie HISTORIE — CCU-009 (see `skills/_shared/state-ownership.md` in the plugin).
+6. Test-/Typecheck-/Lint-Commands in Session Config müssen echte Checks sein,
+   keine Stubs (`echo`/`noop`).
+7. Kein `console.log`/`debugger` in committeten Production-Files.

package/templates/_shared/loop.md

@@ -0,0 +1,90 @@
+# Bare `/loop` — Maintenance Prompt
+
+> Vendored from session-orchestrator `templates/_shared/loop.md`. Bare `/loop`
+> (no prompt) picks this file up automatically as `.claude/loop.md` per
+> https://code.claude.com/docs/en/scheduled-tasks#customize-the-default-prompt-with-loop-md.
+> A user-level `~/.claude/loop.md` is the host-wide fallback; this project file
+> takes precedence when present.
+> Content beyond 25,000 bytes is truncated (scheduled-tasks#customize-the-default-prompt-with-loop-md).
+
+You are tending this working tree. Each iteration, walk through the checks below
+in order and report findings in **one short summary** at the end. Skip a check
+silently when it has nothing to surface — do **not** narrate empty sections. Do
+**not** start new initiatives outside this checklist; do **not** push, delete, or
+amend without explicit authorisation in the conversation transcript.
+
+## 1. Active-session check
+
+If a `STATE.md` exists under the platform state dir (`.claude/STATE.md` on Claude
+Code, `.codex/STATE.md` on Codex CLI):
+
+- Read its frontmatter `status`. If not `completed`, the session is live.
+- Inspect the `## Deviations` section. Surface **only entries added since the last
+  iteration that are not yet acknowledged in the transcript** — older or
+  already-discussed deviations stay silent.
+- If `status: active` and `current-wave` is set, mention current wave + total.
+
+If no `STATE.md` exists, skip this check silently.
+
+## 2. Branch / MR-PR babysitting
+
+If `git rev-parse --abbrev-ref HEAD` is not `main`:
+
+- Detect the host from `git remote -v`: a GitLab remote → use `glab`, a GitHub
+  remote → use `gh`. Let the CLI infer the project from the remote — do **not**
+  pass `-R`/owner flags.
+  - GitLab: `glab mr list --source-branch "$(git rev-parse --abbrev-ref HEAD)" --output json`
+  - GitHub: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)"`
+- For the matching MR/PR: pipeline status, unresolved review threads, merge conflicts.
+- If a pipeline is running, prefer **Monitor** over re-polling next iteration —
+  see `.claude/rules/loop-and-monitor.md` if the repo carries it.
+- If the CLI errors or is unavailable, skip this check silently — never fail the
+  iteration on a tooling error.
+
+If on `main`: list any commits ahead of `origin/main` via
+`git log origin/main..HEAD --oneline`. Mention only — do **not** push.
+
+## 3. Vault-mirror backlog
+
+Run this check **only** if the repo's CLAUDE.md (or AGENTS.md) `## Session Config`
+declares `vault-integration.enabled: true` with a `vault-dir`. If that key is
+absent, skip silently — do not assume any host path.
+
+- Resolve `vault-dir` from Session Config (expand `~` to `$HOME`).
+- If the directory exists, count uncommitted changes in its learnings/sessions
+  folders, e.g. `git -C "<vault-dir>" status --short | wc -l`.
+- If `> 0`, surface the count and remind that the session-end auto-commit and
+  `/evolve` handle catch-up. Do **not** commit the vault yourself.
+
+## 4. Top-3 priority:high backlog
+
+Detect the host from `git remote -v` (as in check 2) and query, without `-R`/owner flags:
+
+- GitLab: `glab issue list --label priority:high --state opened --per-page 3 --output json`
+- GitHub: `gh issue list --label priority:high --state open --limit 3`
+
+Surface the issue id + title — up to three lines. Skip silently when the query
+returns zero results or the CLI errors. Surface any `priority:high` issue that
+exists, even a single one.
+
+## 5. Idle path
+
+If checks 1–4 produced nothing: emit one line —
+`Everything quiet; no live session, no MRs/PRs, no vault backlog, no high-priority issues.`
+Then end.
+
+## Constraints
+
+- **No destructive actions.** No `git push`, `git reset`, `git stash`, `rm`,
+  `glab mr merge`, `glab issue close`, `gh pr merge`, `gh issue close` unless the
+  conversation transcript already authorised the specific action.
+- **Read-only by default.** When unsure, observe and report — let the operator decide.
+- **PSA-aware.** This file is loaded into a coordinator session that may run in
+  parallel with other sessions. Do not touch files you do not own.
+- **Token discipline.** One short summary per iteration. No headers, no bullet
+  lists in the output unless a check found ≥ 2 distinct items.
+
+## See also
+
+- `.claude/rules/loop-and-monitor.md` — when to use `/loop` vs `Monitor` vs `Routines` (if vendored)
+- `.claude/rules/parallel-sessions.md` — PSA discipline (if vendored)

package/templates/_shared/rules/parallel-sessions.md

@@ -0,0 +1,77 @@
+# Parallel Session Awareness (Always-on)
+
+Multiple Claude Code sessions may be active in the same working directory simultaneously. Another agent may be editing files, creating commits, or running builds right now. Treat the repo as a shared workspace, not a private sandbox.
+
+## PSA Scope Axes — Operator-Session vs In-Run
+
+PSA rules span two distinct axes. Naming them keeps the durable moat clear when
+native multi-agent primitives (the experimental `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`)
+overlap parts of this surface.
+
+- **Operator-session axis (the durable moat):** independent parallel operator /
+  Claude sessions in the **same working copy**. PSA-001..004, plus the per-repo
+  session lock (`scripts/lib/session-lock.mjs` `acquire()` / `session.lock`,
+  heartbeat-liveness schema v2), guard this domain. **Agent Teams structurally
+  cannot enter it** — Teams is per-process / in-run only ("one team per
+  session"), NOT per-repo. Its graduation to native affects **only the in-run
+  multi-agent coordination slice**, never the operator-session slice.
+- **In-run axis:** multiple agents coordinated inside a single session/run. Even
+  here our own machinery remains necessary because Agent Teams provides **no
+  automatic isolation**: file-scope deconfliction (`skills/session-plan/SKILL.md` —
+  "verify that NO two agents in the same wave modify the same file") plus
+  `withStateMdLock` STATE.md serialization still do the work Teams does not.
+
+PSA-005 spans **both** axes; only its session-lock half is purely
+operator-scoped. PSA-006 is **orthogonal** to both (Discovery grep-discipline).
+See ADR-0010 § Native-Overlap Refresh (Agent Teams = Adapter; PSA re-scoped).
+
+## Recognizing Parallel Work (PSA-001: Detect Before Acting)
+
+*Axis: operator-session safety — the durable moat Agent Teams structurally cannot enter (per-process / in-run only).*
+
+- **Unexpected git status changes:** Files modified or staged that are not part of your current task likely belong to another session.
+- **Unfamiliar commits:** New entries in `git log` that you did not create mean another agent (or the user manually) committed work.
+- **Spontaneous errors:** Build failures, type errors, or test failures in code you did not touch may be in-progress work from another session — not pre-existing bugs.
+- **Files changed between reads:** If a file's content differs from what you read moments ago, another session likely edited it.
+- **New untracked files:** Files appearing in `git status` that you did not create belong to someone else's work.
+
+## Behavioral Guidance (PSA-002: Ask, Don't Assume)
+
+*Axis: operator-session safety — the durable moat Agent Teams structurally cannot enter (per-process / in-run only).*
+
+- **When you detect signs of parallel work, stop and ask the user:** "I notice changes I didn't make (e.g., modified files in git status, new commits). Is another session active?"
+- **Never "fix" code outside your task scope.** Errors in files you are not working on may be intentional intermediate states from another session.
+- **Stay in your lane.** Only read, create, modify, and delete files directly relevant to your assigned task.
+- **If blocked by external changes, ask the user** rather than reverting, resetting, or working around them.
+- **Track your own footprint.** Be aware of which files you have created or modified. Your commits should contain only your changes.
+
+## Destructive Action Safeguards (PSA-003: Never Destroy What You Didn't Create)
+
+*Axis: operator-session safety — the durable moat Agent Teams structurally cannot enter (per-process / in-run only).*
+
+These commands require explicit user confirmation even in normal operation. When parallel work is suspected, they are **forbidden** without user approval:
+- **`git reset` (any form)** — destroys staged or committed work that may belong to another session.
+- **`git checkout -- <file>`** — discards uncommitted changes another session is actively building.
+- **`git clean -f`** — deletes untracked files another session created.
+- **`git stash`** — captures another session's changes into a stash they cannot find.
+- **`rm` / delete of files you did not create** — may remove work-in-progress from another session.
+- **`git revert` of commits you did not make** — undoes another session's completed work.
+- **`git push --force`** — rewrites shared history (dangerous even without parallel sessions).
+
+Before running any of the above, ask: "Did I create this file/commit/change? If not, it is not mine to touch."
+
+## Commit Discipline (PSA-004: Isolate Your Changes)
+
+*Axis: operator-session safety — the durable moat Agent Teams structurally cannot enter (per-process / in-run only).*
+
+- **Stage files individually** (`git add <file>`) rather than `git add .` or `git add -A`, which may sweep in another session's work.
+- **Review `git diff --cached` before committing** to verify every staged change is yours.
+- **If you see unfamiliar changes in the diff, unstage them** and ask the user.
+- **Never amend a commit you did not create.**
+
+## Anti-Patterns
+- Seeing unfamiliar changes and assuming they are "leftover mess" to clean up — they are likely active work.
+- Running `git reset --hard` to "start fresh" — this destroys all uncommitted work across all sessions.
+- Fixing type errors or lint issues in files outside your scope — the other session will handle their own files.
+- Using `git add .` in a shared workspace — you will commit another session's partial work.
+- Reverting "broken" commits without asking — another session may have intentionally pushed incremental progress.