skillpacks 0.1.0 → 0.1.2

package/packs/exec-loop/claude/exec/archive/v0.3/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.4/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.4
+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, include `/pack install <pack-name>` inside Claude Code or `npx skillpacks install <pack-name>` from the project shell as the prerequisite.
+- **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/ship/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v0.7 - 2026-06-12
+
+- Standardized active pack and skill install guidance on `npx skillpacks install <pack-or-skill>` instead of agent-native `/pack install` or `$pack install` recommendations.
+
+## v0.6 - 2026-06-11
+
+- Added npm CLI install alternatives to cross-pack next-step routing fallback wording while preserving Claude `/pack install` recommendations.
+
 ## v0.5 - 2026-06-09
 
 - Updated Skills Showcase refresh commands to use app-owned generator and validator paths after the workspace split.

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

@@ -2,7 +2,7 @@
 name: ship
 description: Ship current work (update docs, commit, push, deploy) and optionally plan the next step
 type: shipping
-version: v0.5
+version: v0.7
 argument-hint: "[--no-plan] [--no-deploy] [--save-conversation] [--save-all-conversations]"
 invocation: orchestrator
 ---
@@ -118,8 +118,6 @@ d) Write a **self-contained** implementation plan for the next step into `tasks/
 e) Ship `tasks/todo.md`, `tasks/roadmap.md`, `tasks/manual-todo.md`, `tasks/record-todo.md`, `tasks/recurring-todo.md` (when they exist), and `tasks/phases/` (if created) via `/commit-and-push-by-feature`, landing them on `main` or `master`.
 
 ### 5. Enter plan mode (skip if `--no-plan`)
-**Before entering plan mode**, read `.claude/settings.local.json` and ensure `"showClearContextOnPlanAccept": true` and `"defaultMode": "acceptEdits"` are set. If the file doesn't exist, create it with `{ "showClearContextOnPlanAccept": true, "defaultMode": "acceptEdits" }`. If it exists but lacks either key, add the missing key (preserve existing settings). `defaultMode: "acceptEdits"` is the Claude Code setting that makes newly opened sessions prefer accept-edits mode when startup settings are honored; there is no separate known setting that only controls the clear-context launch.
-
 **YOU MUST run the full plan-mode approval sequence.** This is not optional. A next-step plan being written or already present is not a completed `/ship` unless `--no-plan` is set or the approval UI is presented successfully.
 
 1. Call `EnterPlanMode`. This enters plan mode.
@@ -128,8 +126,6 @@ e) Ship `tasks/todo.md`, `tasks/roadmap.md`, `tasks/manual-todo.md`, `tasks/reco
 
 `EnterPlanMode` alone does not present the approval UI. `ExitPlanMode` must only be called after `EnterPlanMode` has succeeded and the session is visibly in plan mode. If Claude Code reports "You are not in plan mode", do not retry `ExitPlanMode`; call `EnterPlanMode` first, then write the brief pass-through plan and call `ExitPlanMode`.
 
-If `EnterPlanMode` is denied because Auto mode or the active permission mode requires an explicit user request to enter plan mode, stop. Report that the next plan is written and the user must explicitly request plan mode, for example: `/plan <next step name>` or "enter plan mode for <next step name>". Do not attempt `ExitPlanMode`, do not summarize as shipped into plan mode, and do not implement the following step.
-
 There is no normal final-answer checkpoint between writing/finding the next plan and presenting the approval UI. If the prior tool call was interrupted after the plan was written, resume by calling `EnterPlanMode` rather than summarizing and stopping, unless the session is already visibly in plan mode.
 
 ### 6. Plan-mode approval content (skip if `--no-plan`)
@@ -160,20 +156,20 @@ Rules:
 
 - Make the next work item primary. Derive it from the next-step plan, `tasks/todo.md`, `tasks/manual-todo.md`, deploy status, validation gaps, smoke-test gaps, or the absence of remaining work. Do not use agent mode itself as the next work item.
 - If no remaining work exists — no unchecked steps in `tasks/todo.md`, no phases remaining in `tasks/roadmap.md`, no pending manual blockers, no validation gaps, and no deploy failures — emit `**Next work:** none` and `**Recommended next command:** none — all planned work is complete`. Do not force a route to `/exec` when there is genuinely nothing to execute.
-- Never recommend `/ship`, `/ship --no-deploy`, or `/ship --no-plan` as the routine next command from a completed `/ship` run. `/ship` packages current work; after it completes, hand off to the next executable route such as `/exec`, check `.agents/project.json.enabled_packs` for `agent-work-admin` — if `agent-work-admin` is not enabled, recommend `/pack install agent-work-admin` first; if `agent-work-admin` is enabled, recommend `/roadmap`, check `.agents/project.json.enabled_packs` for `guided-walkthrough` — if `guided-walkthrough` is not enabled, recommend `/pack install guided-walkthrough` first; if `guided-walkthrough` is enabled, recommend `/guide`, or check `.agents/project.json.enabled_packs` for `docs-health` — if `docs-health` is not enabled, recommend `/pack install docs-health` first; if `docs-health` is enabled, recommend `/reconcile-dev-docs fix tasks` based on project state. Recommend `/ship` again only when shipping failed before commit/push or when the next concrete work is explicitly to retry an incomplete shipping operation.
+- Never recommend `/ship`, `/ship --no-deploy`, or `/ship --no-plan` as the routine next command from a completed `/ship` run. `/ship` packages current work; after it completes, hand off to the next executable route such as `/exec`, check `.agents/project.json.enabled_packs` for `agent-work-admin` — if `agent-work-admin` is not enabled, recommend `npx skillpacks install agent-work-admin` from the project shell first; if `agent-work-admin` is enabled, recommend `/roadmap`, check `.agents/project.json.enabled_packs` for `guided-walkthrough` — if `guided-walkthrough` is not enabled, recommend `npx skillpacks install guided-walkthrough` from the project shell first; if `guided-walkthrough` is enabled, recommend `/guide`, or check `.agents/project.json.enabled_packs` for `docs-health` — if `docs-health` is not enabled, recommend `npx skillpacks install docs-health` from the project shell first; if `docs-health` is enabled, recommend `/reconcile-dev-docs fix tasks` based on project state. Recommend `/ship` again only when shipping failed before commit/push or when the next concrete work is explicitly to retry an incomplete shipping operation.
 - 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 — check `.agents/project.json.enabled_packs` for `agent-bridge` — if `agent-bridge` is not enabled, recommend `/pack install agent-bridge` first; if `agent-bridge` is enabled, recommend `/delegate $exec`.
+- 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 base 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 — check `.agents/project.json.enabled_packs` for `agent-bridge` — if `agent-bridge` is not enabled, recommend `npx skillpacks install agent-bridge` from the project shell first; if `agent-bridge` is enabled, recommend `/delegate $exec`.
 - Inference defaults:
-  - Hybrid execution handoff → check `.agents/project.json.enabled_packs` for `agent-bridge` — if `agent-bridge` is not enabled, recommend `/pack install agent-bridge` first; if `agent-bridge` is enabled, recommend `/delegate $exec`.
+  - Hybrid execution handoff → check `.agents/project.json.enabled_packs` for `agent-bridge` — if `agent-bridge` is not enabled, recommend `npx skillpacks install agent-bridge` from the project shell first; if `agent-bridge` is enabled, recommend `/delegate $exec`.
   - Claude-only or orchestration-heavy work → recommend `/exec`.
   - Codex-only execution → recommend `$exec`.
-  - External human-only manual work (browser/auth/DNS/service dashboard work with no reliable authenticated CLI/API path, paid account setup, real-device checks, or production smoke-test work needing human sign-off) → check `.agents/project.json.enabled_packs` for `guided-walkthrough` — if `guided-walkthrough` is not enabled, recommend `/pack install guided-walkthrough` first; if `guided-walkthrough` is enabled, recommend `/guide` — or a Claude-guided manual step rather than `/exec`.
-  - Agent-executable work misfiled in `tasks/manual-todo.md`, task-doc bookkeeping, stale `tasks/manual-todo.md` cleanup, or reconciliation against repo/history reality → check `.agents/project.json.enabled_packs` for `docs-health` — if `docs-health` is not enabled, recommend `/pack install docs-health` first; if `docs-health` is enabled, recommend `/reconcile-dev-docs fix tasks` — promotion to `tasks/todo.md`, or a direct dev-doc audit, not `/guide`.
+  - External human-only manual work (browser/auth/DNS/service dashboard work with no reliable authenticated CLI/API path, paid account setup, real-device checks, or production smoke-test work needing human sign-off) → check `.agents/project.json.enabled_packs` for `guided-walkthrough` — if `guided-walkthrough` is not enabled, recommend `npx skillpacks install guided-walkthrough` from the project shell first; if `guided-walkthrough` is enabled, recommend `/guide` — or a Claude-guided manual step rather than `/exec`.
+  - Agent-executable work misfiled in `tasks/manual-todo.md`, task-doc bookkeeping, stale `tasks/manual-todo.md` cleanup, or reconciliation against repo/history reality → check `.agents/project.json.enabled_packs` for `docs-health` — if `docs-health` is not enabled, recommend `npx skillpacks install docs-health` from the project shell first; if `docs-health` is enabled, recommend `/reconcile-dev-docs fix tasks` — promotion to `tasks/todo.md`, or a direct dev-doc audit, not `/guide`.
 - 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.
 - Final route contract: completed `/ship` runs must not self-route back to `/ship`; route to `/exec` or a more specific next actionable skill unless shipping itself failed before commit/push, or emit `none` when all planned work is genuinely complete.
 
 ## 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.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, include `npx skillpacks install <pack-name>` from the project shell as the prerequisite.
 - **Fix unrelated issues:** If any step surfaces errors, warnings, or lint issues — even ones unrelated to the current work — investigate and fix them before continuing. Commit these fixes separately with a descriptive message (e.g., `fix: resolve unused import warning in auth.ts`).
 - Do NOT write plans into CLAUDE.md. CLAUDE.md is for project conventions and config only.
 - `tasks/roadmap.md` is the source of truth for the full phased plan. `tasks/todo.md` holds only the current phase.
@@ -182,7 +178,7 @@ Rules:
 - Do NOT explore the codebase extensively for planning. Keep context footprint minimal.
 - If the tree is clean and the next step plan already exists in `tasks/todo.md`, skip straight to step 5.
 - Do not enter plan mode solely for verification-only/no-op-only work whose commands already passed in the current session and whose expected source changes are none. Record the completed verification/no-op result and advance to the next substantive item.
-- Unless `--no-plan` is set or a documented blocker stops planning, do not end the turn after writing, finding, or shipping the next-step plan; ensure `defaultMode: "acceptEdits"` is set, then run the full `EnterPlanMode` -> pass-through plan -> `ExitPlanMode` approval sequence. If `EnterPlanMode` is denied because an explicit user request is required, stop with that blocker instead of attempting `ExitPlanMode`.
+- Unless `--no-plan` is set or a documented blocker stops planning, do not end the turn after writing, finding, or shipping the next-step plan; run the full `EnterPlanMode` -> pass-through plan -> `ExitPlanMode` approval sequence.
 - The plan shown to the clear-context implementation session must include the ship-one-step handoff: "implement only this step, validate it, then run `/ship` when done." The plan-mode prompt is the human approval boundary that prevents a runaway loop.
 - The plan must be actionable, not vague. Include specific file paths, technical details, and the current phase's `### Execution Profile`.
 - Do not execute or plan from `tasks/record-todo.md` or `tasks/recurring-todo.md`; report their counts only unless an item has been promoted into `tasks/todo.md`.