skillpacks 0.1.1 → 0.1.2

package/packs/docs-health/codex/reconcile-dev-docs/archive/v0.1/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: reconcile-dev-docs
+description: Reconcile development docs by auditing roadmap, todo, history, phase archives, specs, git history, and code reality
+type: analysis
+version: v0.1
+argument-hint: "[audit|fix] [tasks|specs|all]"
+---
+
+# Reconcile Dev Docs
+
+Invoke as `$reconcile-dev-docs`.
+
+Audit or repair development documentation so the roadmap, current work, history, specs, and evidence from git/code all tell the same story.
+
+## Process
+
+### 1. Determine Mode and Scope
+
+Parse `$ARGUMENTS`:
+
+- **Mode**: `audit` (default, read-only) or `fix` (update development docs only)
+- **Scope**: `all` (default), `tasks`, or `specs`
+
+Resolve the canonical development docs:
+
+- `tasks/roadmap.md`
+- `tasks/todo.md`
+- `tasks/manual-todo.md` (if it exists)
+- `tasks/record-todo.md` (if it exists)
+- `tasks/recurring-todo.md` (if it exists)
+- `tasks/history.md`
+- `tasks/phases/*.md`
+- `tasks/ideas.md` (if it exists)
+- `specs/*.md` and `specs/*/*.md`
+- `docs/specifications/*.md` (fallback specs location)
+
+If no task docs exist, report that there is nothing to reconcile and recommend `$roadmap` or `$plan-phase` based on available specs.
+
+### 2. Gather Evidence
+
+Read the development docs and collect:
+
+- Roadmap phases, milestone checkboxes, acceptance criteria, manual tasks, record tasks, recurring tasks, and deferred items
+- Current todo phase, checked/unchecked steps, blockers, and review/results sections
+- Manual task blockers and `_(blocks: ...)_` / `_(after: ...)_` annotations
+- Record task conditions, non-blocking reasons, evidence paths, and promotion rules
+- Recurring task cadence, last run, next due, evidence paths, and escalation conditions
+- History entries with dates, completed phases/steps, commit SHAs, and claimed outcomes
+- Phase archives and their completion summaries
+- Spec titles, statuses, acceptance criteria, and major implementation claims
+
+Read git/code evidence:
+
+- `git status --short`
+- `git log --oneline -50`
+- `git log --name-only --since=<latest relevant doc date>` when timestamps suggest docs may be stale
+- Targeted file existence and `rg` checks for claims marked complete
+
+### 3. Reconcile Rules
+
+Classify findings:
+
+| Severity | Examples |
+|----------|----------|
+| **Error** | Docs contradict each other: roadmap marks a phase done while todo has unchecked required steps; history claims completion but no matching roadmap/todo/archive/git evidence exists |
+| **Warning** | Likely drift: recent commits changed areas covered by specs but history/todo were not updated; completed phase has no archive; manual blockers remain for completed steps |
+| **Info** | Cleanup opportunities: stale handoff notes, missing links between history entries and commits, specs that should be checked by `$spec-drift` |
+
+Use these specific checks:
+
+- `tasks/todo.md` checked steps should be reflected in `tasks/history.md` after shipping.
+- Completed roadmap phases should have corresponding `tasks/phases/phase-N.md` archives.
+- The active `tasks/todo.md` phase should match the first incomplete roadmap phase.
+- `tasks/manual-todo.md` should not contain unchecked blockers for completed todo steps unless the user explicitly overrode them.
+- `tasks/todo.md` should not contain condition-gated baseline measurements or future records unless they are current execution work; move clear cases to `tasks/record-todo.md`.
+- `tasks/manual-todo.md` should not contain non-blocking records unless they require human-only external action tied to a `blocks` or `after` step; move clear cases to `tasks/record-todo.md`.
+- `tasks/manual-todo.md` should not contain agent-executable work such as repo edits, SDK wiring, generated assets, local commands, tests, audits, or authenticated CLI/API operations; move clear cases to `tasks/todo.md`.
+- `tasks/recurring-todo.md` due items should remain advisory unless explicitly promoted into `tasks/todo.md`.
+- Recent commits that complete user-facing work should have a matching history entry.
+- Specs whose described areas changed after their last modification date should be flagged for `$spec-drift`.
+- Claimed completed work should have either git evidence, file evidence, test evidence, or an explicit note explaining why evidence is unavailable.
+
+### 4. Fix Mode
+
+In `fix` mode, apply only unambiguous development-doc changes:
+
+- Append missing factual entries to `tasks/history.md`.
+- Check roadmap milestones only when todo/archive/git evidence all support completion.
+- Create missing `tasks/phases/phase-N.md` archives from completed `tasks/todo.md` content.
+- Move the next roadmap phase into `tasks/todo.md` only when the current phase is clearly complete.
+- Move clearly misclassified non-blocking condition-gated records from `tasks/todo.md` or `tasks/manual-todo.md` into `tasks/record-todo.md`.
+- Move clearly misclassified cadence-based obligations from `tasks/todo.md` or `tasks/manual-todo.md` into `tasks/recurring-todo.md`.
+- Move clearly misclassified agent-executable work from `tasks/manual-todo.md` into `tasks/todo.md` with enough file/command detail for `$exec`.
+- Add unresolved contradictions to `tasks/todo.md` under `## Development Docs Reconciliation`.
+- Archive existing `specs/` or `docs/specifications/` files before replacing or substantively rewriting them.
+- Write `tasks/reconciliation-report.md` with resolved, deferred, and remaining findings.
+
+Ask before applying any ambiguous change. If already in Plan mode and there are 2-3 concrete choices, prefer `request_user_input`; otherwise ask plainly in chat.
+
+## Output
+
+### Audit Mode
+
+```
+## Dev Docs Reconciliation
+
+### Errors (N)
+- **tasks/todo.md** - [problem]. Evidence: [roadmap/history/git reference].
+
+### Warnings (N)
+- **specs/foo.md** - [problem]. Recommended action: $spec-drift.
+
+### Info (N)
+- **tasks/history.md** - [cleanup opportunity].
+
+### Summary
+- Roadmap/todo alignment: [ok|issues]
+- History coverage: [ok|issues]
+- Phase archives: [ok|issues]
+- Spec freshness: [ok|issues]
+- Recommended next action: [specific skill or fix plan]
+```
+
+### Fix Mode
+
+Report the same sections plus:
+
+```
+### Fixed
+- [x] [file] - [change made]
+
+### Deferred
+- [ ] [finding requiring user judgment]
+```
+
+## Constraints
+
+- Read-only by default.
+- In `fix` mode, modify only development docs under `tasks/`, `specs/`, or `docs/specifications/`; archive existing spec documents before replacement per the Archive-First Replacement Policy.
+- Do not modify code, research docs, kanban cards, git history, or deployment state.
+- Do not rewrite or delete old `tasks/history.md` entries; append corrections or superseding notes.
+- Do not uncheck completed work automatically. Report unsupported completion claims unless the user approves the correction.
+- Treat `tasks/roadmap.md` as the strategic source of truth, `tasks/todo.md` as the active execution contract, `tasks/manual-todo.md` as human-only external step-linked work, `tasks/record-todo.md` and `tasks/recurring-todo.md` as advisory surfaces, and `tasks/history.md` as append-only evidence.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/reconcile-dev-docs-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

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

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.5 - 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.4 - 2026-06-11
 
 - Added the npm CLI install alternative to cross-pack recommendation fallback wording while preserving the Claude `/pack install` route.

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

@@ -2,7 +2,7 @@
 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
+version: v0.5
 argument-hint: "[--phase]"
 invocation: orchestrator
 ---
@@ -127,7 +127,7 @@ 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`.
+- 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 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).
@@ -160,7 +160,7 @@ Rules:
 
 
 ## 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.
+- 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.
 - **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.

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,9 @@
 # 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.

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.6
+version: v0.7
 argument-hint: "[--no-plan] [--no-deploy] [--save-conversation] [--save-all-conversations]"
 invocation: orchestrator
 ---
@@ -156,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` inside Claude Code or `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 `/pack install guided-walkthrough` inside Claude Code or `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 `/pack install docs-health` inside Claude Code or `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.
+- 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` inside Claude Code or `npx skillpacks install agent-bridge` from the project shell 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` inside Claude Code or `npx skillpacks install agent-bridge` from the project shell 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` inside Claude Code or `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 `/pack install docs-health` inside Claude Code or `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`.
+  - 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, include `/pack install <pack-name>` inside Claude Code or `npx skillpacks install <pack-name>` from the project shell as the prerequisite.
+- 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.