skillpacks 0.1.0

package/packs/exec-loop/claude/exec/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: exec
+description: Plan the next incomplete step (or full phase with --phase flag) from the plan, then enter plan mode for user approval before executing
+type: execution
+version: v0.3
+argument-hint: "[--phase]"
+invocation: orchestrator
+---
+
+# Exec
+
+Identify the next incomplete unit of work from the phased plan, build an execution plan, and enter plan mode for user approval before implementing. By default, plans **only the next single incomplete step**. If `$ARGUMENTS` contains `--phase`, plans the **entire next phase**.
+
+## Process
+
+1. **Migration check:** If `tasks/roadmap.md` does not exist but `tasks/todo.md` contains multiple `## Phase` headers, migrate: copy `tasks/todo.md` -> `tasks/roadmap.md`, then trim `tasks/todo.md` to just the current phase (first phase with unchecked steps). Stop after the migration and tell the user to run `/ship` to package and push the task-doc split. Do **not** commit or push from `/exec`.
+2. **Read `tasks/todo.md`** — this contains the current phase's steps. Reference `tasks/roadmap.md` only if cross-phase context is needed.
+3. **Read CLAUDE.md** for project conventions.
+3b. If `tasks/record-todo.md` or `tasks/recurring-todo.md` exists, count unchecked advisory items for status only. Do not select them as next work.
+4. **Find the next incomplete item:**
+   - Look for the next phase with an unchecked milestone.
+   - If `--phase` mode: scope the entire phase.
+   - Otherwise (default): find only the next unchecked `- [ ]` step within that phase.
+   - **If the phase has acceptance criteria but no implementation steps** (no `### Tests First` or `### Implementation` section): this phase needs just-in-time planning. **You MUST invoke `/plan-phase` for this phase** to generate implementation steps and file-level detail before proceeding. Do NOT tell the user the phase is "deferred" or that they need to run `/plan-phase` manually — this auto-invocation is the designed workflow. A phase without implementation steps is NOT deferred; it simply hasn't been decomposed yet. Only items under the `## Deferred / Future Work` heading in the roadmap are actually deferred.
+5. **Check `tasks/manual-todo.md`** (if it exists) for blocking manual tasks:
+   - Look for unchecked items with `_(blocks: Step N.X)_` annotations matching the step about to be executed.
+   - If a blocking external human-only manual task is found, stop and ask the user how to proceed: "**Manual task blocking this step:** [task]. Complete it before proceeding, or run `/guide` (guided-walkthrough pack) for step-by-step instructions." Do NOT execute the step unless the manual task is completed or the user explicitly overrides the blocker.
+   - If the unchecked item is task-doc bookkeeping, reconciliation, or agent-executable work (repo edits, SDK wiring, local commands, tests, audits, generated assets, or authenticated CLI/API work), do not route it to `/guide` (guided-walkthrough pack); route it to `/reconcile-dev-docs fix tasks` (docs-health pack), promote it to `tasks/todo.md`, or handle it as a direct dev-doc audit.
+6. **Research what's needed** — read only the files relevant to the step/phase to understand existing code, patterns, and dependencies.
+6a. **Prototype-first product gate** — for user-facing product, SaaS, marketplace, dashboard, internal tool, product-experience work, or substantial new feature work, check whether the selected step would introduce durable database/storage, auth, payments, analytics, deployment, admin tooling, multi-tenancy, or production observability before clickable prototype experiments have calibrated one journey. If the current plan or user instruction does not explicitly authorize that infrastructure, stop and re-plan the step around a separate prototype/experiment phase using fake, fixture, local, or in-memory data. When multiple workflows, layouts, densities, copy approaches, navigation models, or interaction patterns remain plausible, prefer multiple small experiment routes such as `/experiments/<variant>` over one merged implementation. Record the deferred infrastructure and the evidence needed to promote it later.
+6b. **Read the execution profile** — read the current phase's `### Execution Profile` from `tasks/todo.md` if present:
+   - If missing, treat the phase as `serial`.
+   - Use the profile only for the current step or scoped phase; do not plan ahead.
+   - If the profile's `Parallel mode` is `agent-team`:
+     - Parse all lanes. If any lane is missing `Mode:` or `Depends on:`, still contains placeholder text, write lanes have overlapping `Owns`, or write lanes are missing a concrete non-primary `Branch:`, **auto-invoke `/patch-exec-profile`** for this phase (same pattern as step 4's auto-invocation of `/plan-phase`). Re-read `tasks/todo.md` after it returns. Do not tell the user to run `/patch-exec-profile` manually — this auto-invocation is the designed workflow.
+     - Build the lane DAG from each lane's `Depends on:` field. Compute topological waves. Include the DAG and wave structure in the plan-mode presentation at step 8.
+     - Confirm the plan includes a consolidation/PR review step after all write lanes and before final validation or shipping. If not, stop and patch the phase plan before dispatch.
+7. **Enter plan mode** using the EnterPlanMode tool.
+8. **Present the execution plan** to the user:
+   - What the step/phase requires
+   - Which files will be created or modified
+   - The approach (e.g., what tests to write, what code to change)
+   - Whether the execution profile will run serially, use read-only research lanes, use review lanes, or use disjoint write lanes
+   - For `agent-team`: the planned lane branches and the consolidation/PR review gate
+   - Any decisions or trade-offs the user should weigh in on
+9. **Wait for user approval.** Do NOT write any code until the user approves.
+10. **After approval, execute the approved plan.** If Claude Code already returned to normal mode after approval, do not call ExitPlanMode again; continue directly with implementation. Only use the plan-mode exit tool when the session is still visibly in plan mode.
+
+### Execution Profile Handling
+
+After approval, apply the current phase's `### Execution Profile`:
+
+- `serial`: execute normally.
+- `research-only`: launch read-only subagent lanes first when the active environment permits subagents, synthesize their findings, then implement in the main agent.
+- `review-only`: implement in the main agent, then launch review subagent lanes before final validation.
+- `implementation-safe`: launch write subagent lanes only when every write lane has disjoint `Owns` paths and explicit `Must not edit` boundaries; otherwise downgrade to `research-only` or `serial` and report the downgrade.
+- `agent-team`: auto-dispatch lanes via `Agent` tool calls with `isolation: "worktree"` (see **Agent-Team Dispatch** below). Each write lane must run on its declared separate GitHub branch and return branch, commit SHA, validation evidence, and PR URL. This is the current policy — **do not stop** merely because the profile says `agent-team` or because the phase/step body contains legacy advisory text like *"do not implement in a single `/exec`"*, *"requires isolated worktrees or a dedicated agent team"*, or *"use `/delegate` (agent-bridge pack) instead"*. That guidance predates agent-team dispatch and is now stale. Trust the `### Execution Profile` metadata (after `/patch-exec-profile` fills it) and proceed. Only stop if `/patch-exec-profile` returns with unresolvable ambiguity (overlapping `Owns`, cyclic `Depends on`, missing lane specs that cannot be inferred, or missing branch/PR review requirements).
+
+The main agent owns integration, conflict resolution, task doc updates, history updates, shipping handoff, and deploy handoff. If a subagent touches files outside its owned paths or returns conflicting changes, stop and reconcile before validation.
+
+#### Agent-Team Dispatch
+
+When the profile is `agent-team`:
+
+- Execute lane waves in topological order (computed from `Depends on:` in step 6b).
+- For each wave of **write** lanes: dispatch one `Agent` call per lane, in a single message (parallel execution), with:
+  - `isolation: "worktree"`
+  - The lane's declared `Branch:` value, created from the current primary branch (`main` when present, otherwise `master`) and never named `main` or `master`
+  - `subagent_type: "general-purpose"` unless the lane spec names another agent
+  - Prompt scoped to the lane's `Scope`, `Owns`, `Must not edit`, and `Deliverable`
+  - Explicit instruction in the prompt: "Work only on your assigned branch. Before returning, commit all your changes, push the branch to GitHub, open or update a draft PR, and include the branch name, final commit SHA, validation evidence, and PR URL."
+- If the repository has no GitHub remote, branch push is unavailable, or PR creation/review cannot be performed, stop before dispatch and report the blocker instead of downgrading silently.
+- When each lane returns:
+  1. **Verify branch evidence:** confirm the returned branch matches the lane's `Branch:`, the commit exists on that branch, and a PR URL was returned. If not, stop.
+  2. **Validate write boundaries:** fetch the lane branch, then run `git diff --name-only <primary>...origin/<lane-branch>` (or the reviewed remote branch ref). Every changed path must be a subset of the lane's declared `Owns`. If any file falls outside (including matches against `Must not edit`), abort integration for that lane and surface the violation. Do not attempt partial integration.
+  3. **Consolidation/PR review:** inspect the PR diff, test evidence, and lane summary. Record findings as `blocker` or `advisory` with file path and line references. Do not integrate a branch with blocker findings.
+  4. **Integrate approved branch work into the shared tree:** `git restore --source=origin/<lane-branch> --staged --worktree -- <owns-path-1> <owns-path-2> …`. This captures modifications, additions, and deletions. Do not use `git checkout <branch> -- <paths>` — it silently drops deletions. Do not create a merge commit; the result is a dirty working tree for `/ship`.
+  5. **Clean up local worktrees only after integration:** `git worktree remove <worktree-path>` then delete the local lane branch when safe. Leave the remote branch/PR available until consolidation status is documented or the project explicitly closes/merges it.
+- After all write waves integrate, dispatch any additional **review** lanes as non-worktree `Agent` calls (no `isolation`) against the integrated dirty tree. Their deliverable contract: return findings as a list, each classified `blocker` or `advisory`, with file path and line references.
+- Write a `### Review Findings` block under the step in `tasks/todo.md`:
+  - If any finding is `blocker`: leave the step unchecked, stop `/exec`, and surface the findings in the final report.
+  - Else: record the findings, check off the step, and continue normal `/exec` flow.
+- Exec the phase's test strategy against the integrated state before checking off the step.
+
+### Single Step Mode (default)
+
+- If the step creates, deletes, renames, or changes behavior/metadata in any tracked `SKILL.md` or `PACK.md`, refresh the Skills Showcase before handing off to `/ship`: run `node apps/skills-showcase/scripts/generate-skills-showcase-data.mjs`, `node apps/skills-showcase/scripts/generate-skills-showcase-github-data.mjs`, and `apps/skills-showcase/scripts/validate-skills-showcase-data.sh`; include changed generated assets in the dirty tree. Review curated showcase copy, catalog grouping, workflow animation text, and proof receipts; update affected site files or record why no curated website copy changed.
+- If it's a "Tests First" step: write the failing tests, run them to confirm they fail (red). Stop.
+- If it's an implementation step: implement it, run existing tests to check for regressions. Stop.
+- If it's a "Green" step: run all tests. For `tests-after` phases, also write regression tests covering acceptance criteria. Fix any failures. If validation is clean and a following cleanup/refactor step is explicitly conditional on validation findings or says no source changes are expected, complete that no-op cleanup in the same execution by recording the no-op result instead of leaving it for a separate plan-mode handoff. Stop.
+- **Mark the step as done** in `tasks/todo.md` (check it off).
+
+### Full Phase Mode (`--phase`)
+
+- Execute the entire phase, step by step:
+  - Start with the "Tests First" steps — write the failing tests.
+  - Exec the tests to confirm they fail (red).
+  - Implement each step in order.
+  - Run tests after implementation to confirm they pass (green).
+  - Refactor only when validation exposes concrete drift or cleanup work; do not create or preserve separate no-op refactor steps after a clean validation gate.
+- **Verify the milestone**:
+  - Check each acceptance criterion.
+  - Exec the full test suite to confirm no regressions.
+  - Check off completed criteria in `tasks/todo.md`.
+
+## After Execution (both modes)
+
+**Report concisely:**
+- Phase/step completed
+- Files modified
+- Test results (if tests were run) — **explicitly state whether any failures are expected (red phase: tests written before implementation) or unexpected (regressions/bugs that need fixing)**
+- Manual tasks — if `tasks/manual-todo.md` exists, report count of pending manual tasks for this phase
+- Advisory tasks — pending record/recurring counts from `tasks/record-todo.md` and `tasks/recurring-todo.md` if they exist
+- **Next work:** the next concrete shipping, validation, blocker, or follow-up task
+- **Recommended next command:** one command or route for that work
+
+## Next-Step Routing
+
+Before handing back, identify the next concrete work item from project state, then recommend the executor and invocation.
+
+Output exactly two lines beyond the normal report:
+
+- **Next work:** <specific shipping, validation, blocker, or follow-up task>
+- **Recommended next command:** <one command or route>
+
+Rules:
+
+- Make the next work item primary. Derive it from `tasks/todo.md`, validation results, manual blockers, deploy/smoke-test gaps, or the absence of remaining work. Do not use agent mode itself as the next work item.
+- Use `./scripts/agent-mode.sh` only to choose command text. If it is missing, unset, or non-zero, infer routing from the current invocation and task type instead of asking the user to select a mode by default.
+- Normalize copied task routes to Claude syntax before final output. If `tasks/todo.md`, `tasks/roadmap.md`, benchmark reports, or prior handoffs contain Codex dollar commands for global skills (for example `$exec`, `$ship`, `$roadmap`, `$guide`, `$reconcile-dev-docs`), treat them as task identifiers, not final command text. Convert the final `Recommended next command` to the equivalent Claude `/...` route unless the next action is explicitly a Codex handoff such as `/delegate $ship`.
+- Inference defaults:
+  - Hybrid execution handoff after Claude `/exec` → recommend `/delegate` (agent-bridge pack) `$ship`.
+  - Claude-only or manual/orchestration-heavy work → recommend `/ship` or `/guide` (guided-walkthrough pack).
+  - Codex-only execution → recommend `$ship`.
+- Do **not** recommend `/delegate` (agent-bridge pack) as a workaround for an `agent-team` profile. `/exec` now auto-dispatches agent-team lanes itself via isolated worktrees; `/delegate` (agent-bridge pack) is for Claude↔Codex handoff, not for lane parallelism.
+- Only present multiple commands when the ambiguity materially changes execution safety or there are equally valid next work items. Otherwise choose the best route and mention degraded mode lookup inline.
+
+## What NOT to do
+
+- Do NOT write code before entering plan mode and getting user approval.
+- Do NOT call ExitPlanMode from normal mode. If Claude Code reports "You are not in plan mode" after approval, treat approval as complete and continue implementation.
+- Do NOT execute more than one step (or more than one phase in `--phase` mode).
+- Do NOT read unnecessary files — only what's needed for the current work.
+- Do NOT plan ahead or analyze future phases/steps.
+- Do NOT refactor unrelated code.
+- Do NOT update CLAUDE.md.
+- Do NOT commit or push. `/exec` is the Claude execution step; `/ship` owns packaging, task-history updates, commits, pushes, deploys, and next-step planning.
+- Do NOT execute external human-action items from `tasks/manual-todo.md`. Bookkeeping or agent-executable items that were misfiled there should be reconciled through `/reconcile-dev-docs` (docs-health pack) or promoted into `tasks/todo.md`, not routed to `/guide` (guided-walkthrough pack).
+- Do NOT execute items from `tasks/record-todo.md` or `tasks/recurring-todo.md` unless the item has first been promoted into `tasks/todo.md`.
+
+## Flow
+
+```
+/exec                  → plans one step, enters plan mode, executes after approval
+/exec --phase          → plans the next full phase, enters plan mode, executes after approval
+/ship                 → commits, pushes, plans next, enters plan mode
+                      → select "clear context and implement"
+                      → fresh context reads tasks/todo.md and implements
+```
+
+
+## Constraints
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `/pack install <pack-name>` to the recommendation.
+- **One step (or one phase). That's it.** Then stop and let the user decide what's next.
+- **Always enter plan mode before executing.** The user must approve the approach first.
+- Keep context footprint minimal — don't read the entire codebase, only files relevant to this work.
+- If the work can't be completed due to a blocker, document the blocker in `tasks/todo.md` and stop.
+- Follow the test strategy annotated on each phase (`tdd`, `tests-after`, or `none`). Do not skip test steps for `tdd` phases.
+- Follow the `### Execution Profile` annotated on each phase. If subagents are unavailable in the active environment, execute serially and report the downgrade.
+- Do not let subagents update `tasks/todo.md`, `tasks/roadmap.md`, `tasks/history.md`, shipping commits, or deploy steps. Those remain main-agent responsibilities.
+- Do not run parallel write lanes unless their `Owns` paths are disjoint. When in doubt, downgrade to `research-only` or `serial`.
+- Do not invoke `/commit-and-push-by-feature` or push shipping commits from the main `/exec` tree. A dirty tracked tree after successful `/exec` is expected and is the handoff to `/ship`. The narrow exception is `agent-team` lane work: lane agents must commit and push their assigned non-primary GitHub branches for PR review.
+- For `agent-team` phases: do not integrate a lane whose diff contains files outside its declared `Owns` — surface the violation and stop instead. Lane agent prompts must require branch-backed commit, push, and PR evidence before return; do not integrate from an uncommitted worktree, unpushed branch, or unreviewed PR. Clean up local worktrees after every integration, but preserve remote branches/PRs until consolidation status is documented.
+- Each execution must be self-contained — read the plan fresh, don't rely on prior context.
+
+## Execution Handoff Contract
+
+- `/exec` deliberately leaves completed tracked changes uncommitted so `/ship` can validate, update `tasks/history.md`, commit, push, deploy, plan the next step, and enter plan mode in one coherent shipping pass.
+- If the user explicitly asks `/exec` to commit or push, stop and redirect them to `/ship` or `/commit-and-push-by-feature`; do not reinterpret `/exec` as a shipping command.
+- Report the exact next command as `/ship` unless a blocker prevents shipping.

package/packs/exec-loop/claude/exec/archive/v0.0/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: run
+description: Plan the next incomplete step (or full phase with --phase flag) from the plan, then enter plan mode for user approval before executing
+type: execution
+version: v0.0
+argument-hint: "[--phase]"
+---
+
+# Run
+
+Identify the next incomplete unit of work from the phased plan, build an execution plan, and enter plan mode for user approval before implementing. By default, plans **only the next single incomplete step**. If `$ARGUMENTS` contains `--phase`, plans the **entire next phase**.
+
+## Protocol
+
+1. **Migration check:** If `tasks/roadmap.md` does not exist but `tasks/todo.md` contains multiple `## Phase` headers, migrate: copy `tasks/todo.md` -> `tasks/roadmap.md`, then trim `tasks/todo.md` to just the current phase (first phase with unchecked steps). Stop after the migration and tell the user to run `/ship` to package and push the task-doc split. Do **not** commit or push from `/run`.
+2. **Read `tasks/todo.md`** — this contains the current phase's steps. Reference `tasks/roadmap.md` only if cross-phase context is needed.
+3. **Read CLAUDE.md** for project conventions.
+3b. If `tasks/record-todo.md` or `tasks/recurring-todo.md` exists, count unchecked advisory items for status only. Do not select them as next work.
+4. **Find the next incomplete item:**
+   - Look for the next phase with an unchecked milestone.
+   - If `--phase` mode: scope the entire phase.
+   - Otherwise (default): find only the next unchecked `- [ ]` step within that phase.
+   - **If the phase has acceptance criteria but no implementation steps** (no `### Tests First` or `### Implementation` section): this phase needs just-in-time planning. **You MUST invoke `/plan-phase` for this phase** to generate implementation steps and file-level detail before proceeding. Do NOT tell the user the phase is "deferred" or that they need to run `/plan-phase` manually — this auto-invocation is the designed workflow. A phase without implementation steps is NOT deferred; it simply hasn't been decomposed yet. Only items under the `## Deferred / Future Work` heading in the roadmap are actually deferred.
+5. **Check `tasks/manual-todo.md`** (if it exists) for blocking manual tasks:
+   - Look for unchecked items with `_(blocks: Step N.X)_` annotations matching the step about to be executed.
+   - If a blocking external human-only manual task is found, stop and ask the user how to proceed: "**Manual task blocking this step:** [task]. Complete it before proceeding, or run `/guide` (guided-walkthrough pack) for step-by-step instructions." Do NOT execute the step unless the manual task is completed or the user explicitly overrides the blocker.
+   - If the unchecked item is task-doc bookkeeping, reconciliation, or agent-executable work (repo edits, SDK wiring, local commands, tests, audits, generated assets, or authenticated CLI/API work), do not route it to `/guide` (guided-walkthrough pack); route it to `/reconcile-dev-docs fix tasks` (docs-health pack), promote it to `tasks/todo.md`, or handle it as a direct dev-doc audit.
+6. **Research what's needed** — read only the files relevant to the step/phase to understand existing code, patterns, and dependencies.
+6a. **Prototype-first product gate** — for user-facing product, SaaS, marketplace, dashboard, internal tool, product-experience work, or substantial new feature work, check whether the selected step would introduce durable database/storage, auth, payments, analytics, deployment, admin tooling, multi-tenancy, or production observability before clickable prototype experiments have calibrated one journey. If the current plan or user instruction does not explicitly authorize that infrastructure, stop and re-plan the step around a separate prototype/experiment phase using fake, fixture, local, or in-memory data. When multiple workflows, layouts, densities, copy approaches, navigation models, or interaction patterns remain plausible, prefer multiple small experiment routes such as `/experiments/<variant>` over one merged implementation. Record the deferred infrastructure and the evidence needed to promote it later.
+6b. **Read the execution profile** — read the current phase's `### Execution Profile` from `tasks/todo.md` if present:
+   - If missing, treat the phase as `serial`.
+   - Use the profile only for the current step or scoped phase; do not plan ahead.
+   - If the profile's `Parallel mode` is `agent-team`:
+     - Parse all lanes. If any lane is missing `Mode:` or `Depends on:`, still contains placeholder text, write lanes have overlapping `Owns`, or write lanes are missing a concrete non-primary `Branch:`, **auto-invoke `/patch-exec-profile`** for this phase (same pattern as step 4's auto-invocation of `/plan-phase`). Re-read `tasks/todo.md` after it returns. Do not tell the user to run `/patch-exec-profile` manually — this auto-invocation is the designed workflow.
+     - Build the lane DAG from each lane's `Depends on:` field. Compute topological waves. Include the DAG and wave structure in the plan-mode presentation at step 8.
+     - Confirm the plan includes a consolidation/PR review step after all write lanes and before final validation or shipping. If not, stop and patch the phase plan before dispatch.
+7. **Enter plan mode** using the EnterPlanMode tool.
+8. **Present the execution plan** to the user:
+   - What the step/phase requires
+   - Which files will be created or modified
+   - The approach (e.g., what tests to write, what code to change)
+   - Whether the execution profile will run serially, use read-only research lanes, use review lanes, or use disjoint write lanes
+   - For `agent-team`: the planned lane branches and the consolidation/PR review gate
+   - Any decisions or trade-offs the user should weigh in on
+9. **Wait for user approval.** Do NOT write any code until the user approves.
+10. **After approval, execute the approved plan.** If Claude Code already returned to normal mode after approval, do not call ExitPlanMode again; continue directly with implementation. Only use the plan-mode exit tool when the session is still visibly in plan mode.
+
+### Execution Profile Handling
+
+After approval, apply the current phase's `### Execution Profile`:
+
+- `serial`: execute normally.
+- `research-only`: launch read-only subagent lanes first when the active environment permits subagents, synthesize their findings, then implement in the main agent.
+- `review-only`: implement in the main agent, then launch review subagent lanes before final validation.
+- `implementation-safe`: launch write subagent lanes only when every write lane has disjoint `Owns` paths and explicit `Must not edit` boundaries; otherwise downgrade to `research-only` or `serial` and report the downgrade.
+- `agent-team`: auto-dispatch lanes via `Agent` tool calls with `isolation: "worktree"` (see **Agent-Team Dispatch** below). Each write lane must run on its declared separate GitHub branch and return branch, commit SHA, validation evidence, and PR URL. This is the current policy — **do not stop** merely because the profile says `agent-team` or because the phase/step body contains legacy advisory text like *"do not implement in a single `/run`"*, *"requires isolated worktrees or a dedicated agent team"*, or *"use `/delegate` (agent-bridge pack) instead"*. That guidance predates agent-team dispatch and is now stale. Trust the `### Execution Profile` metadata (after `/patch-exec-profile` fills it) and proceed. Only stop if `/patch-exec-profile` returns with unresolvable ambiguity (overlapping `Owns`, cyclic `Depends on`, missing lane specs that cannot be inferred, or missing branch/PR review requirements).
+
+The main agent owns integration, conflict resolution, task doc updates, history updates, shipping handoff, and deploy handoff. If a subagent touches files outside its owned paths or returns conflicting changes, stop and reconcile before validation.
+
+#### Agent-Team Dispatch
+
+When the profile is `agent-team`:
+
+- Execute lane waves in topological order (computed from `Depends on:` in step 6b).
+- For each wave of **write** lanes: dispatch one `Agent` call per lane, in a single message (parallel execution), with:
+  - `isolation: "worktree"`
+  - The lane's declared `Branch:` value, created from the current primary branch (`main` when present, otherwise `master`) and never named `main` or `master`
+  - `subagent_type: "general-purpose"` unless the lane spec names another agent
+  - Prompt scoped to the lane's `Scope`, `Owns`, `Must not edit`, and `Deliverable`
+  - Explicit instruction in the prompt: "Work only on your assigned branch. Before returning, commit all your changes, push the branch to GitHub, open or update a draft PR, and include the branch name, final commit SHA, validation evidence, and PR URL."
+- If the repository has no GitHub remote, branch push is unavailable, or PR creation/review cannot be performed, stop before dispatch and report the blocker instead of downgrading silently.
+- When each lane returns:
+  1. **Verify branch evidence:** confirm the returned branch matches the lane's `Branch:`, the commit exists on that branch, and a PR URL was returned. If not, stop.
+  2. **Validate write boundaries:** fetch the lane branch, then run `git diff --name-only <primary>...origin/<lane-branch>` (or the reviewed remote branch ref). Every changed path must be a subset of the lane's declared `Owns`. If any file falls outside (including matches against `Must not edit`), abort integration for that lane and surface the violation. Do not attempt partial integration.
+  3. **Consolidation/PR review:** inspect the PR diff, test evidence, and lane summary. Record findings as `blocker` or `advisory` with file path and line references. Do not integrate a branch with blocker findings.
+  4. **Integrate approved branch work into the shared tree:** `git restore --source=origin/<lane-branch> --staged --worktree -- <owns-path-1> <owns-path-2> …`. This captures modifications, additions, and deletions. Do not use `git checkout <branch> -- <paths>` — it silently drops deletions. Do not create a merge commit; the result is a dirty working tree for `/ship`.
+  5. **Clean up local worktrees only after integration:** `git worktree remove <worktree-path>` then delete the local lane branch when safe. Leave the remote branch/PR available until consolidation status is documented or the project explicitly closes/merges it.
+- After all write waves integrate, dispatch any additional **review** lanes as non-worktree `Agent` calls (no `isolation`) against the integrated dirty tree. Their deliverable contract: return findings as a list, each classified `blocker` or `advisory`, with file path and line references.
+- Write a `### Review Findings` block under the step in `tasks/todo.md`:
+  - If any finding is `blocker`: leave the step unchecked, stop `/run`, and surface the findings in the final report.
+  - Else: record the findings, check off the step, and continue normal `/run` flow.
+- Run the phase's test strategy against the integrated state before checking off the step.
+
+### Single Step Mode (default)
+
+- If the step creates, deletes, renames, or changes behavior/metadata in any tracked `SKILL.md` or `PACK.md`, refresh the Skills Showcase before handing off to `/ship`: run `node scripts/generate-skills-showcase-data.mjs`, `node scripts/generate-skills-showcase-github-data.mjs`, and `scripts/validate-skills-showcase-data.sh`; include changed generated assets in the dirty tree. Review curated showcase copy, catalog grouping, workflow animation text, and proof receipts; update affected site files or record why no curated website copy changed.
+- If it's a "Tests First" step: write the failing tests, run them to confirm they fail (red). Stop.
+- If it's an implementation step: implement it, run existing tests to check for regressions. Stop.
+- If it's a "Green" step: run all tests. For `tests-after` phases, also write regression tests covering acceptance criteria. Fix any failures. If validation is clean and a following cleanup/refactor step is explicitly conditional on validation findings or says no source changes are expected, complete that no-op cleanup in the same run by recording the no-op result instead of leaving it for a separate plan-mode handoff. Stop.
+- **Mark the step as done** in `tasks/todo.md` (check it off).
+
+### Full Phase Mode (`--phase`)
+
+- Execute the entire phase, step by step:
+  - Start with the "Tests First" steps — write the failing tests.
+  - Run the tests to confirm they fail (red).
+  - Implement each step in order.
+  - Run tests after implementation to confirm they pass (green).
+  - Refactor only when validation exposes concrete drift or cleanup work; do not create or preserve separate no-op refactor steps after a clean validation gate.
+- **Verify the milestone**:
+  - Check each acceptance criterion.
+  - Run the full test suite to confirm no regressions.
+  - Check off completed criteria in `tasks/todo.md`.
+
+## After Execution (both modes)
+
+**Report concisely:**
+- Phase/step completed
+- Files modified
+- Test results (if tests were run) — **explicitly state whether any failures are expected (red phase: tests written before implementation) or unexpected (regressions/bugs that need fixing)**
+- Manual tasks — if `tasks/manual-todo.md` exists, report count of pending manual tasks for this phase
+- Advisory tasks — pending record/recurring counts from `tasks/record-todo.md` and `tasks/recurring-todo.md` if they exist
+- **Next work:** the next concrete shipping, validation, blocker, or follow-up task
+- **Recommended next command:** one command or route for that work
+
+## Next-Step Routing
+
+Before handing back, identify the next concrete work item from project state, then recommend the executor and invocation.
+
+Output exactly two lines beyond the normal report:
+
+- **Next work:** <specific shipping, validation, blocker, or follow-up task>
+- **Recommended next command:** <one command or route>
+
+Rules:
+
+- Make the next work item primary. Derive it from `tasks/todo.md`, validation results, manual blockers, deploy/smoke-test gaps, or the absence of remaining work. Do not use agent mode itself as the next work item.
+- Use `./scripts/agent-mode.sh` only to choose command text. If it is missing, unset, or non-zero, infer routing from the current invocation and task type instead of asking the user to select a mode by default.
+- Normalize copied task routes to Claude syntax before final output. If `tasks/todo.md`, `tasks/roadmap.md`, benchmark reports, or prior handoffs contain Codex dollar commands for global skills (for example `$run`, `$ship`, `$roadmap`, `$guide`, `$reconcile-dev-docs`), treat them as task identifiers, not final command text. Convert the final `Recommended next command` to the equivalent Claude `/...` route unless the next action is explicitly a Codex handoff such as `/delegate $ship`.
+- Inference defaults:
+  - Hybrid execution handoff after Claude `/run` → recommend `/delegate` (agent-bridge pack) `$ship`.
+  - Claude-only or manual/orchestration-heavy work → recommend `/ship` or `/guide` (guided-walkthrough pack).
+  - Codex-only execution → recommend `$ship`.
+- Do **not** recommend `/delegate` (agent-bridge pack) as a workaround for an `agent-team` profile. `/run` now auto-dispatches agent-team lanes itself via isolated worktrees; `/delegate` (agent-bridge pack) is for Claude↔Codex handoff, not for lane parallelism.
+- Only present multiple commands when the ambiguity materially changes execution safety or there are equally valid next work items. Otherwise choose the best route and mention degraded mode lookup inline.
+
+## What NOT to do
+
+- Do NOT write code before entering plan mode and getting user approval.
+- Do NOT call ExitPlanMode from normal mode. If Claude Code reports "You are not in plan mode" after approval, treat approval as complete and continue implementation.
+- Do NOT execute more than one step (or more than one phase in `--phase` mode).
+- Do NOT read unnecessary files — only what's needed for the current work.
+- Do NOT plan ahead or analyze future phases/steps.
+- Do NOT refactor unrelated code.
+- Do NOT update CLAUDE.md.
+- Do NOT commit or push. `/run` is the Claude execution step; `/ship` owns packaging, task-history updates, commits, pushes, deploys, and next-step planning.
+- Do NOT execute external human-action items from `tasks/manual-todo.md`. Bookkeeping or agent-executable items that were misfiled there should be reconciled through `/reconcile-dev-docs` (docs-health pack) or promoted into `tasks/todo.md`, not routed to `/guide` (guided-walkthrough pack).
+- Do NOT execute items from `tasks/record-todo.md` or `tasks/recurring-todo.md` unless the item has first been promoted into `tasks/todo.md`.
+
+## Workflow
+
+```
+/run                  → plans one step, enters plan mode, executes after approval
+/run --phase          → plans the next full phase, enters plan mode, executes after approval
+/ship                 → commits, pushes, plans next, enters plan mode
+                      → select "clear context and implement"
+                      → fresh context reads tasks/todo.md and implements
+```
+
+
+## Constraints
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `/pack install <pack-name>` to the recommendation.
+- **One step (or one phase). That's it.** Then stop and let the user decide what's next.
+- **Always enter plan mode before executing.** The user must approve the approach first.
+- Keep context footprint minimal — don't read the entire codebase, only files relevant to this work.
+- If the work can't be completed due to a blocker, document the blocker in `tasks/todo.md` and stop.
+- Follow the test strategy annotated on each phase (`tdd`, `tests-after`, or `none`). Do not skip test steps for `tdd` phases.
+- Follow the `### Execution Profile` annotated on each phase. If subagents are unavailable in the active environment, execute serially and report the downgrade.
+- Do not let subagents update `tasks/todo.md`, `tasks/roadmap.md`, `tasks/history.md`, shipping commits, or deploy steps. Those remain main-agent responsibilities.
+- Do not run parallel write lanes unless their `Owns` paths are disjoint. When in doubt, downgrade to `research-only` or `serial`.
+- Do not invoke `/commit-and-push-by-feature` or push shipping commits from the main `/run` tree. A dirty tracked tree after successful `/run` is expected and is the handoff to `/ship`. The narrow exception is `agent-team` lane work: lane agents must commit and push their assigned non-primary GitHub branches for PR review.
+- For `agent-team` phases: do not integrate a lane whose diff contains files outside its declared `Owns` — surface the violation and stop instead. Lane agent prompts must require branch-backed commit, push, and PR evidence before return; do not integrate from an uncommitted worktree, unpushed branch, or unreviewed PR. Clean up local worktrees after every integration, but preserve remote branches/PRs until consolidation status is documented.
+- Each execution must be self-contained — read the plan fresh, don't rely on prior context.
+
+## Execution Handoff Contract
+
+- `/run` deliberately leaves completed tracked changes uncommitted so `/ship` can validate, update `tasks/history.md`, commit, push, deploy, plan the next step, and enter plan mode in one coherent shipping pass.
+- If the user explicitly asks `/run` to commit or push, stop and redirect them to `/ship` or `/commit-and-push-by-feature`; do not reinterpret `/run` as a shipping command.
+- Report the exact next command as `/ship` unless a blocker prevents shipping.

package/packs/exec-loop/claude/exec/archive/v0.1/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: exec
+description: Plan the next incomplete step (or full phase with --phase flag) from the plan, then enter plan mode for user approval before executing
+type: execution
+version: v0.1
+argument-hint: "[--phase]"
+invocation: orchestrator
+---
+
+# Exec
+
+Identify the next incomplete unit of work from the phased plan, build an execution plan, and enter plan mode for user approval before implementing. By default, plans **only the next single incomplete step**. If `$ARGUMENTS` contains `--phase`, plans the **entire next phase**.
+
+## Process
+
+1. **Migration check:** If `tasks/roadmap.md` does not exist but `tasks/todo.md` contains multiple `## Phase` headers, migrate: copy `tasks/todo.md` -> `tasks/roadmap.md`, then trim `tasks/todo.md` to just the current phase (first phase with unchecked steps). Stop after the migration and tell the user to run `/ship` to package and push the task-doc split. Do **not** commit or push from `/exec`.
+2. **Read `tasks/todo.md`** — this contains the current phase's steps. Reference `tasks/roadmap.md` only if cross-phase context is needed.
+3. **Read CLAUDE.md** for project conventions.
+3b. If `tasks/record-todo.md` or `tasks/recurring-todo.md` exists, count unchecked advisory items for status only. Do not select them as next work.
+4. **Find the next incomplete item:**
+   - Look for the next phase with an unchecked milestone.
+   - If `--phase` mode: scope the entire phase.
+   - Otherwise (default): find only the next unchecked `- [ ]` step within that phase.
+   - **If the phase has acceptance criteria but no implementation steps** (no `### Tests First` or `### Implementation` section): this phase needs just-in-time planning. **You MUST invoke `/plan-phase` for this phase** to generate implementation steps and file-level detail before proceeding. Do NOT tell the user the phase is "deferred" or that they need to run `/plan-phase` manually — this auto-invocation is the designed workflow. A phase without implementation steps is NOT deferred; it simply hasn't been decomposed yet. Only items under the `## Deferred / Future Work` heading in the roadmap are actually deferred.
+5. **Check `tasks/manual-todo.md`** (if it exists) for blocking manual tasks:
+   - Look for unchecked items with `_(blocks: Step N.X)_` annotations matching the step about to be executed.
+   - If a blocking external human-only manual task is found, stop and ask the user how to proceed: "**Manual task blocking this step:** [task]. Complete it before proceeding, or run `/guide` (guided-walkthrough pack) for step-by-step instructions." Do NOT execute the step unless the manual task is completed or the user explicitly overrides the blocker.
+   - If the unchecked item is task-doc bookkeeping, reconciliation, or agent-executable work (repo edits, SDK wiring, local commands, tests, audits, generated assets, or authenticated CLI/API work), do not route it to `/guide` (guided-walkthrough pack); route it to `/reconcile-dev-docs fix tasks` (docs-health pack), promote it to `tasks/todo.md`, or handle it as a direct dev-doc audit.
+6. **Research what's needed** — read only the files relevant to the step/phase to understand existing code, patterns, and dependencies.
+6a. **Prototype-first product gate** — for user-facing product, SaaS, marketplace, dashboard, internal tool, product-experience work, or substantial new feature work, check whether the selected step would introduce durable database/storage, auth, payments, analytics, deployment, admin tooling, multi-tenancy, or production observability before clickable prototype experiments have calibrated one journey. If the current plan or user instruction does not explicitly authorize that infrastructure, stop and re-plan the step around a separate prototype/experiment phase using fake, fixture, local, or in-memory data. When multiple workflows, layouts, densities, copy approaches, navigation models, or interaction patterns remain plausible, prefer multiple small experiment routes such as `/experiments/<variant>` over one merged implementation. Record the deferred infrastructure and the evidence needed to promote it later.
+6b. **Read the execution profile** — read the current phase's `### Execution Profile` from `tasks/todo.md` if present:
+   - If missing, treat the phase as `serial`.
+   - Use the profile only for the current step or scoped phase; do not plan ahead.
+   - If the profile's `Parallel mode` is `agent-team`:
+     - Parse all lanes. If any lane is missing `Mode:` or `Depends on:`, still contains placeholder text, write lanes have overlapping `Owns`, or write lanes are missing a concrete non-primary `Branch:`, **auto-invoke `/patch-exec-profile`** for this phase (same pattern as step 4's auto-invocation of `/plan-phase`). Re-read `tasks/todo.md` after it returns. Do not tell the user to run `/patch-exec-profile` manually — this auto-invocation is the designed workflow.
+     - Build the lane DAG from each lane's `Depends on:` field. Compute topological waves. Include the DAG and wave structure in the plan-mode presentation at step 8.
+     - Confirm the plan includes a consolidation/PR review step after all write lanes and before final validation or shipping. If not, stop and patch the phase plan before dispatch.
+7. **Enter plan mode** using the EnterPlanMode tool.
+8. **Present the execution plan** to the user:
+   - What the step/phase requires
+   - Which files will be created or modified
+   - The approach (e.g., what tests to write, what code to change)
+   - Whether the execution profile will run serially, use read-only research lanes, use review lanes, or use disjoint write lanes
+   - For `agent-team`: the planned lane branches and the consolidation/PR review gate
+   - Any decisions or trade-offs the user should weigh in on
+9. **Wait for user approval.** Do NOT write any code until the user approves.
+10. **After approval, execute the approved plan.** If Claude Code already returned to normal mode after approval, do not call ExitPlanMode again; continue directly with implementation. Only use the plan-mode exit tool when the session is still visibly in plan mode.
+
+### Execution Profile Handling
+
+After approval, apply the current phase's `### Execution Profile`:
+
+- `serial`: execute normally.
+- `research-only`: launch read-only subagent lanes first when the active environment permits subagents, synthesize their findings, then implement in the main agent.
+- `review-only`: implement in the main agent, then launch review subagent lanes before final validation.
+- `implementation-safe`: launch write subagent lanes only when every write lane has disjoint `Owns` paths and explicit `Must not edit` boundaries; otherwise downgrade to `research-only` or `serial` and report the downgrade.
+- `agent-team`: auto-dispatch lanes via `Agent` tool calls with `isolation: "worktree"` (see **Agent-Team Dispatch** below). Each write lane must run on its declared separate GitHub branch and return branch, commit SHA, validation evidence, and PR URL. This is the current policy — **do not stop** merely because the profile says `agent-team` or because the phase/step body contains legacy advisory text like *"do not implement in a single `/exec`"*, *"requires isolated worktrees or a dedicated agent team"*, or *"use `/delegate` (agent-bridge pack) instead"*. That guidance predates agent-team dispatch and is now stale. Trust the `### Execution Profile` metadata (after `/patch-exec-profile` fills it) and proceed. Only stop if `/patch-exec-profile` returns with unresolvable ambiguity (overlapping `Owns`, cyclic `Depends on`, missing lane specs that cannot be inferred, or missing branch/PR review requirements).
+
+The main agent owns integration, conflict resolution, task doc updates, history updates, shipping handoff, and deploy handoff. If a subagent touches files outside its owned paths or returns conflicting changes, stop and reconcile before validation.
+
+#### Agent-Team Dispatch
+
+When the profile is `agent-team`:
+
+- Execute lane waves in topological order (computed from `Depends on:` in step 6b).
+- For each wave of **write** lanes: dispatch one `Agent` call per lane, in a single message (parallel execution), with:
+  - `isolation: "worktree"`
+  - The lane's declared `Branch:` value, created from the current primary branch (`main` when present, otherwise `master`) and never named `main` or `master`
+  - `subagent_type: "general-purpose"` unless the lane spec names another agent
+  - Prompt scoped to the lane's `Scope`, `Owns`, `Must not edit`, and `Deliverable`
+  - Explicit instruction in the prompt: "Work only on your assigned branch. Before returning, commit all your changes, push the branch to GitHub, open or update a draft PR, and include the branch name, final commit SHA, validation evidence, and PR URL."
+- If the repository has no GitHub remote, branch push is unavailable, or PR creation/review cannot be performed, stop before dispatch and report the blocker instead of downgrading silently.
+- When each lane returns:
+  1. **Verify branch evidence:** confirm the returned branch matches the lane's `Branch:`, the commit exists on that branch, and a PR URL was returned. If not, stop.
+  2. **Validate write boundaries:** fetch the lane branch, then run `git diff --name-only <primary>...origin/<lane-branch>` (or the reviewed remote branch ref). Every changed path must be a subset of the lane's declared `Owns`. If any file falls outside (including matches against `Must not edit`), abort integration for that lane and surface the violation. Do not attempt partial integration.
+  3. **Consolidation/PR review:** inspect the PR diff, test evidence, and lane summary. Record findings as `blocker` or `advisory` with file path and line references. Do not integrate a branch with blocker findings.
+  4. **Integrate approved branch work into the shared tree:** `git restore --source=origin/<lane-branch> --staged --worktree -- <owns-path-1> <owns-path-2> …`. This captures modifications, additions, and deletions. Do not use `git checkout <branch> -- <paths>` — it silently drops deletions. Do not create a merge commit; the result is a dirty working tree for `/ship`.
+  5. **Clean up local worktrees only after integration:** `git worktree remove <worktree-path>` then delete the local lane branch when safe. Leave the remote branch/PR available until consolidation status is documented or the project explicitly closes/merges it.
+- After all write waves integrate, dispatch any additional **review** lanes as non-worktree `Agent` calls (no `isolation`) against the integrated dirty tree. Their deliverable contract: return findings as a list, each classified `blocker` or `advisory`, with file path and line references.
+- Write a `### Review Findings` block under the step in `tasks/todo.md`:
+  - If any finding is `blocker`: leave the step unchecked, stop `/exec`, and surface the findings in the final report.
+  - Else: record the findings, check off the step, and continue normal `/exec` flow.
+- Exec the phase's test strategy against the integrated state before checking off the step.
+
+### Single Step Mode (default)
+
+- If the step creates, deletes, renames, or changes behavior/metadata in any tracked `SKILL.md` or `PACK.md`, refresh the Skills Showcase before handing off to `/ship`: run `node scripts/generate-skills-showcase-data.mjs`, `node scripts/generate-skills-showcase-github-data.mjs`, and `scripts/validate-skills-showcase-data.sh`; include changed generated assets in the dirty tree. Review curated showcase copy, catalog grouping, workflow animation text, and proof receipts; update affected site files or record why no curated website copy changed.
+- If it's a "Tests First" step: write the failing tests, run them to confirm they fail (red). Stop.
+- If it's an implementation step: implement it, run existing tests to check for regressions. Stop.
+- If it's a "Green" step: run all tests. For `tests-after` phases, also write regression tests covering acceptance criteria. Fix any failures. If validation is clean and a following cleanup/refactor step is explicitly conditional on validation findings or says no source changes are expected, complete that no-op cleanup in the same execution by recording the no-op result instead of leaving it for a separate plan-mode handoff. Stop.
+- **Mark the step as done** in `tasks/todo.md` (check it off).
+
+### Full Phase Mode (`--phase`)
+
+- Execute the entire phase, step by step:
+  - Start with the "Tests First" steps — write the failing tests.
+  - Exec the tests to confirm they fail (red).
+  - Implement each step in order.
+  - Run tests after implementation to confirm they pass (green).
+  - Refactor only when validation exposes concrete drift or cleanup work; do not create or preserve separate no-op refactor steps after a clean validation gate.
+- **Verify the milestone**:
+  - Check each acceptance criterion.
+  - Exec the full test suite to confirm no regressions.
+  - Check off completed criteria in `tasks/todo.md`.
+
+## After Execution (both modes)
+
+**Report concisely:**
+- Phase/step completed
+- Files modified
+- Test results (if tests were run) — **explicitly state whether any failures are expected (red phase: tests written before implementation) or unexpected (regressions/bugs that need fixing)**
+- Manual tasks — if `tasks/manual-todo.md` exists, report count of pending manual tasks for this phase
+- Advisory tasks — pending record/recurring counts from `tasks/record-todo.md` and `tasks/recurring-todo.md` if they exist
+- **Next work:** the next concrete shipping, validation, blocker, or follow-up task
+- **Recommended next command:** one command or route for that work
+
+## Next-Step Routing
+
+Before handing back, identify the next concrete work item from project state, then recommend the executor and invocation.
+
+Output exactly two lines beyond the normal report:
+
+- **Next work:** <specific shipping, validation, blocker, or follow-up task>
+- **Recommended next command:** <one command or route>
+
+Rules:
+
+- Make the next work item primary. Derive it from `tasks/todo.md`, validation results, manual blockers, deploy/smoke-test gaps, or the absence of remaining work. Do not use agent mode itself as the next work item.
+- Use `./scripts/agent-mode.sh` only to choose command text. If it is missing, unset, or non-zero, infer routing from the current invocation and task type instead of asking the user to select a mode by default.
+- Normalize copied task routes to Claude syntax before final output. If `tasks/todo.md`, `tasks/roadmap.md`, benchmark reports, or prior handoffs contain Codex dollar commands for global skills (for example `$exec`, `$ship`, `$roadmap`, `$guide`, `$reconcile-dev-docs`), treat them as task identifiers, not final command text. Convert the final `Recommended next command` to the equivalent Claude `/...` route unless the next action is explicitly a Codex handoff such as `/delegate $ship`.
+- Inference defaults:
+  - Hybrid execution handoff after Claude `/exec` → recommend `/delegate` (agent-bridge pack) `$ship`.
+  - Claude-only or manual/orchestration-heavy work → recommend `/ship` or `/guide` (guided-walkthrough pack).
+  - Codex-only execution → recommend `$ship`.
+- Do **not** recommend `/delegate` (agent-bridge pack) as a workaround for an `agent-team` profile. `/exec` now auto-dispatches agent-team lanes itself via isolated worktrees; `/delegate` (agent-bridge pack) is for Claude↔Codex handoff, not for lane parallelism.
+- Only present multiple commands when the ambiguity materially changes execution safety or there are equally valid next work items. Otherwise choose the best route and mention degraded mode lookup inline.
+
+## What NOT to do
+
+- Do NOT write code before entering plan mode and getting user approval.
+- Do NOT call ExitPlanMode from normal mode. If Claude Code reports "You are not in plan mode" after approval, treat approval as complete and continue implementation.
+- Do NOT execute more than one step (or more than one phase in `--phase` mode).
+- Do NOT read unnecessary files — only what's needed for the current work.
+- Do NOT plan ahead or analyze future phases/steps.
+- Do NOT refactor unrelated code.
+- Do NOT update CLAUDE.md.
+- Do NOT commit or push. `/exec` is the Claude execution step; `/ship` owns packaging, task-history updates, commits, pushes, deploys, and next-step planning.
+- Do NOT execute external human-action items from `tasks/manual-todo.md`. Bookkeeping or agent-executable items that were misfiled there should be reconciled through `/reconcile-dev-docs` (docs-health pack) or promoted into `tasks/todo.md`, not routed to `/guide` (guided-walkthrough pack).
+- Do NOT execute items from `tasks/record-todo.md` or `tasks/recurring-todo.md` unless the item has first been promoted into `tasks/todo.md`.
+
+## Flow
+
+```
+/exec                  → plans one step, enters plan mode, executes after approval
+/exec --phase          → plans the next full phase, enters plan mode, executes after approval
+/ship                 → commits, pushes, plans next, enters plan mode
+                      → select "clear context and implement"
+                      → fresh context reads tasks/todo.md and implements
+```
+
+
+## Constraints
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `/pack install <pack-name>` to the recommendation.
+- **One step (or one phase). That's it.** Then stop and let the user decide what's next.
+- **Always enter plan mode before executing.** The user must approve the approach first.
+- Keep context footprint minimal — don't read the entire codebase, only files relevant to this work.
+- If the work can't be completed due to a blocker, document the blocker in `tasks/todo.md` and stop.
+- Follow the test strategy annotated on each phase (`tdd`, `tests-after`, or `none`). Do not skip test steps for `tdd` phases.
+- Follow the `### Execution Profile` annotated on each phase. If subagents are unavailable in the active environment, execute serially and report the downgrade.
+- Do not let subagents update `tasks/todo.md`, `tasks/roadmap.md`, `tasks/history.md`, shipping commits, or deploy steps. Those remain main-agent responsibilities.
+- Do not run parallel write lanes unless their `Owns` paths are disjoint. When in doubt, downgrade to `research-only` or `serial`.
+- Do not invoke `/commit-and-push-by-feature` or push shipping commits from the main `/exec` tree. A dirty tracked tree after successful `/exec` is expected and is the handoff to `/ship`. The narrow exception is `agent-team` lane work: lane agents must commit and push their assigned non-primary GitHub branches for PR review.
+- For `agent-team` phases: do not integrate a lane whose diff contains files outside its declared `Owns` — surface the violation and stop instead. Lane agent prompts must require branch-backed commit, push, and PR evidence before return; do not integrate from an uncommitted worktree, unpushed branch, or unreviewed PR. Clean up local worktrees after every integration, but preserve remote branches/PRs until consolidation status is documented.
+- Each execution must be self-contained — read the plan fresh, don't rely on prior context.
+
+## Execution Handoff Contract
+
+- `/exec` deliberately leaves completed tracked changes uncommitted so `/ship` can validate, update `tasks/history.md`, commit, push, deploy, plan the next step, and enter plan mode in one coherent shipping pass.
+- If the user explicitly asks `/exec` to commit or push, stop and redirect them to `/ship` or `/commit-and-push-by-feature`; do not reinterpret `/exec` as a shipping command.
+- Report the exact next command as `/ship` unless a blocker prevents shipping.