skillpacks 0.1.0 → 0.1.1

package/packs/agent-work-admin/claude/spec-drift/archive/v0.1/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: spec-drift
+description: Audit specs against codebase — find unimplemented features, diverged implementations, and undocumented code
+type: analysis
+version: v0.1
+argument-hint: "[audit|fix] [spec-file|all]"
+---
+
+## Pack Availability Guard
+
+Before telling the user to run a skill from another project-local pack, check `.agents/project.json.enabled_packs`. If the target pack is not enabled, recommend `/pack install <pack>` instead of the target skill. Global skills are always valid. Skills from this same pack are valid because the current skill is already running from that pack.
+
+# Spec Drift — Spec-to-Code Conformance Audit
+
+Checks that specs and codebase tell the same story. Extracts verifiable claims from spec documents, checks each against the actual implementation, and flags divergence. Think of it as a linter for spec-to-code fidelity — complementary to `/reconcile-research` (business-discovery pack) (doc-to-doc) and `/expert-review` (broad code review).
+
+## Prerequisites
+
+At least one spec file must exist in `specs/` (or `specs/{app}/`, `docs/specifications/`). If no specs exist, display a message and exit — there's nothing to audit.
+
+## Process
+
+### 0. App Scope Resolution (Monorepo Support)
+
+Before checking prerequisites, detect the app structure:
+
+1. If `$ARGUMENTS` specifies an app name matching a subdirectory of `specs/`, use it.
+2. If `specs/` contains subdirectories (excluding files), list them and ask the user which app to target. If only one subdirectory exists, use it automatically.
+3. If no subdirectories exist, check `docs/specifications/` as an alternative spec location.
+4. If no subdirectories exist in any location, proceed with flat structure (single-product mode).
+
+When app scope `{app}` is active:
+- Read specs from `specs/{app}/` instead of `specs/`
+- Also check `docs/specifications/` for additional spec documents
+
+### 1. Determine Mode and Scope
+
+Parse `$ARGUMENTS`:
+
+- **Mode**: `audit` (default, read-only) or `fix` (update specs or flag code issues, write drift report)
+- **Scope**: specific spec file path, or `all` (default — scan all specs)
+
+### 2. Inventory Specs
+
+Scan `specs/` (or `specs/{app}/`, `docs/specifications/`) for `.md` files. Skip non-spec files (README, index, changelog, mvp-gap, scale-audit, and files matching `*-interview.md`).
+
+For each spec, record:
+- File path
+- Last-modified timestamp (via `stat`)
+- Title (first `#` heading)
+
+**Stop condition**: If no spec files are found, display a message suggesting `/research-roadmap` (research-admin pack) and exit.
+
+### 3. Extract Claims Per Spec
+
+Launch a **subagent per spec** to extract verifiable claims. Each subagent reads one spec and returns structured claims:
+
+| Claim type | What to look for | How to verify |
+|------------|-----------------|---------------|
+| **Routes/endpoints** | API paths, HTTP methods, request/response shapes | Grep routes, check handlers |
+| **Data models/schema** | Field names, types, relations, constraints | Read schema files, model definitions |
+| **Feature behaviors** | "When X happens, Y occurs", business logic rules | Read implementation, check conditionals |
+| **Config/env vars** | Named config values, feature flags, env vars | Grep for usage |
+| **UI flows** | Screen names, navigation paths, component structure | Check components/pages |
+| **Commands/CLI** | Command names, arguments, behavior | Check command handlers |
+| **Pricing/limits** | Tier names, limits, gates | Check config, middleware, constants |
+| **Integration points** | External service calls, webhooks, events | Grep for client calls |
+
+Each claim includes:
+- **Source spec**: file path
+- **Section heading**: the `##`/`###` heading the claim appears under
+- **Direct quote**: the exact text making the claim
+- **Claim type**: one of the types above
+
+### 4. Verify Claims Against Codebase
+
+Launch **subagents per claim group** (grouped by claim type or by spec, whichever produces fewer groups) to verify each claim against the codebase:
+
+For each claim:
+1. Search the codebase for evidence (grep, glob, read relevant files)
+2. Classify the claim:
+
+| Status | Meaning | Evidence required |
+|--------|---------|-------------------|
+| **Verified** | Code matches spec | File:line where behavior is implemented |
+| **Diverged** | Code exists but behaves differently than spec says | Spec quote + code quote showing the difference |
+| **Unimplemented** | Spec describes it but code doesn't have it | Search terms used + confirmation of absence |
+| **Removed** | Spec describes it but evidence suggests intentional removal | Git log showing removal, or TODO/deprecated markers |
+
+For **Diverged** and **Unimplemented** findings, include the specific file:line references (or search terms used) as evidence.
+
+### 5. Detect Undocumented Code
+
+Scan for significant code patterns not covered by any spec claim:
+
+- Routes/endpoints with no spec coverage
+- Data models not mentioned in specs
+- Feature flags/config not documented
+- Public API endpoints without spec descriptions
+
+This is a **lighter scan** — only flag things that look like they *should* have spec coverage (public API, user-facing features, documented config). Do not flag internal utilities, helper functions, or infrastructure code.
+
+### 6. Classify and Report Findings
+
+Group all findings by severity:
+
+| Severity | Meaning | Example |
+|----------|---------|---------|
+| **Error** | Spec actively contradicts code behavior | Spec says "free tier: 10 projects" but code enforces limit of 5 |
+| **Warning** | Drift — spec may be stale or incomplete | Spec describes 3 API endpoints but code has 5 |
+| **Info** | Undocumented code that probably should have spec coverage | New route `/api/v2/export` exists with no spec |
+
+Classification rules:
+- **Diverged** claims → Error (spec and code disagree on behavior)
+- **Unimplemented** claims → Warning (spec describes something code doesn't have yet)
+- **Removed** claims → Warning (spec describes something that was intentionally removed)
+- **Undocumented code** → Info (code exists without spec coverage)
+- If uncertain whether something is a real divergence, classify as Info, not Error.
+
+### 7. Fix Mode (if `fix` was specified)
+
+If mode is `fix`:
+
+1. **Present all Errors** to the user. For each Error, show the spec claim and code reality side-by-side with direct quotes. Ask: **is the code right or the spec right?**
+   - **Code is right** → archive the existing spec, then update the canonical spec section to match the implementation
+   - **Spec is right** → add concrete implementation bugs to `tasks/todo.md` with the spec reference
+2. **Present Warnings** — ask user whether to archive then update spec (remove unimplemented/removed claims), add concrete work to `tasks/todo.md`, or add non-blocking condition-gated validation to `tasks/record-todo.md`.
+3. **Skip Info items** — these are suggestions only.
+4. Apply approved archive-first changes.
+5. Write `specs/drift-report.md` (or `specs/{app}/drift-report.md`) as audit trail:
+
+```markdown
+# Spec Drift Report — [date]
+
+## Resolved
+- [Error description] — resolved by archiving and updating [spec file] to match code
+- [Error description] — resolved by adding implementation task to tasks/todo.md
+
+## Deferred
+- [Warning/Info description] — no action taken
+
+## Remaining
+- [Any Errors the user chose to defer]
+```
+
+6. Re-run the audit to confirm fixes resolved the flagged issues.
+
+**Downstream Impact Check** — after fix mode, check if spec updates affect:
+
+| File | What to check | Impact if affected |
+|------|---------------|-------------------|
+| `research/journey-map.md` | Journey stages referenced by changed spec sections | Journey map may describe flows that no longer match |
+| `research/metrics.md` | Metrics tied to features that drifted | Metrics may track behaviors that changed |
+| `tasks/roadmap.md` | Roadmap items that reference changed specs | Roadmap priorities may need re-evaluation |
+
+Classify impact as **None**, **Minor** (cosmetic references), or **Major** (core assumptions affected). If any impact is Major, recommend running `/reconcile-research` (business-discovery pack) to propagate changes.
+
+## Output
+
+**Audit mode** (default): Display directly to the user. No files written.
+
+```
+## Spec Drift Report — [scope]
+
+### Errors (X)
+- **specs/feature-a.md § Pricing** → `src/config/limits.ts:42` — Spec says "10 project limit" but code enforces 5
+
+### Warnings (X)
+- **specs/feature-a.md § API Endpoints** → code has 2 undocumented endpoints: `/api/v2/export`, `/api/v2/import`
+- **specs/feature-b.md § Auth Flow** → spec describes OAuth2 PKCE but no implementation found
+
+### Info (X)
+- **Undocumented**: `src/routes/webhooks.ts` — webhook handler with no spec coverage
+
+### Verified (X of Y claims)
+- specs/feature-a.md: 15/18 claims verified
+- specs/feature-b.md: 8/12 claims verified
+
+### Summary
+- Specs scanned: 4
+- Claims extracted: 72
+- Verified: 58, Diverged: 6, Unimplemented: 3, Undocumented: 5
+```
+
+**Fix mode**: Same report format, with a `### Fixed` section prepended and `specs/drift-report.md` written as audit trail.
+
+## 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.
+- **Read-only by default.** Only modify files when explicitly invoked with `fix` mode.
+- **Never auto-resolve Errors.** Errors always require user input on whether the code or spec is correct.
+- **Show evidence.** Every finding must include the spec quote + code reference (file:line).
+- **No false positives.** If uncertain whether something is a real divergence, classify it as Info, not Error.
+- **Skip absent specs gracefully.** If no specs exist, display a message and exit.
+- **Respect monorepo structure.** Use app-scoped paths when monorepo is detected.
+- **Use subagents** for claim extraction (one per spec) and verification (one per claim group) to parallelize work.
+- **Idempotent.** Running audit twice with no changes between should produce identical output.
+- **Do not make code changes.** In fix mode, only update spec documents, `tasks/todo.md`, and `tasks/record-todo.md` — never modify source code. Archive existing specs before replacement per the Archive-First Replacement Policy.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/agent-work-admin/codex/plan-phase/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.2 - 2026-06-10
+
+- Added npm-aware install-route alternatives to cross-pack handoff guidance while preserving Codex `$pack install` syntax.
+
 ## v0.0
 
 - Archived previous skill contract.

package/packs/agent-work-admin/codex/plan-phase/SKILL.md

@@ -2,7 +2,7 @@
 name: plan-phase
 description: Decompose a single roadmap phase into implementation steps, tests, and file-level detail
 type: planning
-version: v0.1
+version: v0.2
 invocation: sub-skill
 parent: exec
 ---
@@ -355,11 +355,11 @@ Rules:
 - 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.
 - Inference defaults:
   - Codex skill invocation (`$plan-phase`, `$exec`) → recommend the matching `$...` command.
-  - 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`.
-  - Claude slash invocation (`/plan-phase`, `/exec`, `/delegate`) or orchestration-heavy work → check `.agents/project.json.enabled_packs` for `exec-loop` — if `exec-loop` is not enabled, recommend `$pack install exec-loop` first; if `exec-loop` is enabled, recommend the matching `/...` route.
-  - 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`.
-- 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.
+  - Hybrid execution handoff → check `.agents/project.json.enabled_packs` for `agent-bridge` — if `agent-bridge` is not enabled, recommend `$pack install agent-bridge` inside Codex, or `npx skillpacks install agent-bridge` from the project shell, first; if `agent-bridge` is enabled, recommend `$delegate $exec`.
+  - Claude slash invocation (`/plan-phase`, `/exec`, `/delegate`) or orchestration-heavy work → check `.agents/project.json.enabled_packs` for `exec-loop` — if `exec-loop` is not enabled, recommend `$pack install exec-loop` inside Codex, or `npx skillpacks install exec-loop` from the project shell, first; if `exec-loop` is enabled, recommend the matching `/...` route.
+  - 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 Codex, 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 Codex, 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`.
+- 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 Codex, or `npx skillpacks install <pack-name>` from the project shell, as the install prerequisite before the recommendation.
 - 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.
 
 ## Constraints

package/packs/agent-work-admin/codex/plan-phase/archive/v0.1/SKILL.md

@@ -0,0 +1,387 @@
+---
+name: plan-phase
+description: Decompose a single roadmap phase into implementation steps, tests, and file-level detail
+type: planning
+version: v0.1
+invocation: sub-skill
+parent: exec
+---
+
+# Plan Phase
+
+Invoke as `$plan-phase`.
+
+Fill in the implementation detail for **one** phase of `tasks/roadmap.md`. Invoked just-in-time — either manually, by `$roadmap` (to seed Phase 1), or by `$ship` and `$exec` when a new phase begins. Implementation detail is generated when a phase starts, not upfront, because context from earlier phases informs later decisions.
+
+## Prerequisites
+
+- `tasks/roadmap.md` must exist. If it does not, stop and tell the user to run `$roadmap` (or `$research-roadmap` (research-admin pack) → `$roadmap` if no spec exists).
+- The target phase must already have a Goal, Scope, and Acceptance Criteria in the roadmap.
+
+## Input
+
+Read arguments:
+
+- If arguments contain a phase number (e.g., `2`), plan that phase.
+- If arguments are empty, plan the **first phase that has acceptance criteria but no implementation steps** (no `### Tests First` or `### Implementation` section yet).
+- If arguments contain `--no-tdd`, use `tests-after` for this phase regardless of other signals.
+
+Read:
+
+- `tasks/roadmap.md` for the target phase's Goal, Scope, and Acceptance Criteria.
+- `specs/` (or `spec.md`) for the detailed requirements referenced by the phase's scope.
+- The codebase as needed to understand existing code, patterns, and which files to modify.
+- The roadmap phase's `Parallelization` and `Coordination Notes` fields, if present.
+
+## Planning Process
+
+### Determine Test Strategy
+
+Check in order:
+
+1. If arguments contain `--no-tdd`, use `tests-after`.
+2. If `AGENTS.md` or `CLAUDE.md` has a `## Test Strategy` section, follow the project default.
+3. Otherwise, classify the phase:
+   - **`tdd`**: stable interfaces, APIs, data models, business logic with known contracts, payment/auth flows
+   - **`tests-after`**: UI components, prototyping, exploratory features, design-in-flux work
+   - **`none`**: pure config, docs, scaffolding, infra setup, CI/CD changes
+
+Annotate the phase with `> Test strategy: tdd|tests-after|none`.
+
+### Determine Execution Profile
+
+Expand the roadmap's strategic parallelization mode into a concrete execution profile for this phase. If the roadmap has no `Parallelization` field, default to `serial`.
+
+Use these modes:
+
+- **`serial`**: one main agent does the work; use when ownership is coupled or unclear.
+- **`research-only`**: read-only subagents may gather context before implementation; main agent implements.
+- **`review-only`**: main agent implements; subagents review before final validation.
+- **`implementation-safe`**: write subagents may work only on disjoint owned paths; main agent integrates.
+- **`agent-team`**: work is too broad or cross-cutting for one shared local tree; write lanes must use separate GitHub branches and a consolidation/PR review gate before final integration.
+
+Downgrade `implementation-safe` to `research-only` or `serial` if path ownership overlaps, shared chokepoints dominate, or the likely integration surface is unclear.
+
+Add this section before implementation steps:
+
+```markdown
+### Execution Profile
+**Parallel mode:** serial | research-only | review-only | implementation-safe | agent-team
+**Integration owner:** main agent
+**Conflict risk:** low | medium | high
+**Review gates:** correctness, tests, security, performance, docs/API conformance, UX, or none
+
+**Subagent lanes:**
+- Lane: [lane-name]
+  - Agent: explorer | worker | default
+  - Role: explorer | implementer | reviewer | docs-researcher | test-reviewer
+  - Mode: read-only | write | review
+  - Scope: [bounded task]
+  - Owns: `path/or/glob` (write lanes only)
+  - Must not edit: `path/or/glob` (write lanes only)
+  - Branch: `agent-team/phase-N-lane-name` (agent-team write lanes only)
+  - Depends on: [lane, step, or none]
+  - Deliverable: [findings, patch summary, changed paths, tests, branch + commit SHA + PR URL, or review report]
+```
+
+For `serial`, use `**Subagent lanes:** none`. For `research-only` and `review-only`, lanes must not have write mode. For `implementation-safe`, every write lane must have non-overlapping `Owns` paths and explicit `Must not edit` boundaries.
+For `agent-team`, every write lane must have a deterministic `Branch:` value that is not `main` or `master`, and the phase steps must include a consolidation/PR review step after all write lanes complete and before final validation or shipping. If GitHub branch push or PR review is unavailable, downgrade to `implementation-safe`, `research-only`, or `serial`, or stop and document the blocker.
+
+### Break the Phase into Steps
+
+Define ordered steps beneath the existing Goal/Scope/Acceptance Criteria. The structure depends on the test strategy:
+
+For new user-facing product, SaaS, marketplace, dashboard, internal tool, or product-experience phases, apply a prototype-first planning gate before writing steps:
+
+- If there is no accepted clickable journey yet and the current roadmap phase combines prototype exploration with production implementation, stop and re-scope the current work into a distinct prototype/experiment phase before writing implementation steps. Prefer `Phase 0: Prototype Experiments` when the project convention allows it; otherwise make the next phase explicitly prototype-only and push production implementation later.
+- If the roadmap/spec does not explicitly approve durable database/storage, auth, payments, analytics, deployment, admin tooling, multi-tenancy, or production observability for the current phase, keep those items in a later "eventual production infrastructure" backlog and plan the current phase as a clickable local/static prototype with fake, fixture, or in-memory data.
+- For new feature prototypes or uncertain product surfaces, plan multiple small experiments on separate clickable routes such as `/experiments/<variant>` or project-native equivalents. Each route should test a distinct workflow, layout, density, copy, navigation, or interaction hypothesis without sharing hidden production infrastructure.
+- Include a calibration step before any infrastructure promotion: the user must be able to try one journey and record what felt wrong, slow, generic, too dense, too sparse, off-brand, or workflow-breaking.
+- Promote infrastructure into the current phase only when the phase is explicitly production hardening, the user has approved that infrastructure, or the core prototype cannot test the primary interaction without it. State the evidence in the phase notes.
+
+**For `tdd` phases:**
+```
+## Phase N: [Title]
+> Test strategy: tdd
+
+### Execution Profile
+**Parallel mode:** serial | research-only | review-only | implementation-safe | agent-team
+**Integration owner:** main agent
+**Conflict risk:** low | medium | high
+**Review gates:** correctness, tests, security, performance, docs/API conformance, UX, or none
+
+**Subagent lanes:**
+- Lane: [lane-name or none]
+  - Agent: explorer | worker | default
+  - Role: explorer | implementer | reviewer | docs-researcher | test-reviewer
+  - Mode: read-only | write | review
+  - Scope: [bounded task]
+  - Owns: `path/or/glob` (write lanes only)
+  - Must not edit: `path/or/glob` (write lanes only)
+  - Branch: `agent-team/phase-N-lane-name` (agent-team write lanes only)
+  - Depends on: [lane, step, or none]
+  - Deliverable: [expected output, including branch + commit SHA + PR URL for agent-team write lanes]
+
+### Tests First
+- Step N.1: Write failing tests for this phase's acceptance criteria
+  - List specific test cases to write
+  - Tests should cover happy path, edge cases, and error cases
+  - Tests MUST fail at this point (red)
+
+### Implementation
+- Step N.2: [First implementation task]
+  - Files: create `path/to/new.ts`, modify `path/to/existing.ts`
+- Step N.3: [Next implementation task]
+  - Files: modify `path/to/file.ts`
+- ...
+
+### Green
+- Step N.X: Run tests, verify all pass, and perform only concrete cleanup found by validation
+
+### Milestone: [Phase N Milestone Name]
+**Acceptance Criteria:** (preserve from roadmap — do not rewrite)
+- [ ] [criterion 1]
+- [ ] All phase tests pass
+- [ ] No regressions in previous phase tests
+```
+
+**For `tests-after` phases:**
+```
+## Phase N: [Title]
+> Test strategy: tests-after
+
+### Execution Profile
+**Parallel mode:** serial | research-only | review-only | implementation-safe | agent-team
+**Integration owner:** main agent
+**Conflict risk:** low | medium | high
+**Review gates:** correctness, tests, security, performance, docs/API conformance, UX, or none
+
+**Subagent lanes:**
+- Lane: [lane-name or none]
+  - Agent: explorer | worker | default
+  - Role: explorer | implementer | reviewer | docs-researcher | test-reviewer
+  - Mode: read-only | write | review
+  - Scope: [bounded task]
+  - Owns: `path/or/glob` (write lanes only)
+  - Must not edit: `path/or/glob` (write lanes only)
+  - Branch: `agent-team/phase-N-lane-name` (agent-team write lanes only)
+  - Depends on: [lane, step, or none]
+  - Deliverable: [expected output, including branch + commit SHA + PR URL for agent-team write lanes]
+
+### Implementation
+- Step N.1: [First implementation task]
+  - Files: create `path/to/new.ts`, modify `path/to/existing.ts`
+- ...
+
+### Green
+- Step N.X: Write regression tests covering acceptance criteria
+- Step N.Y: Run all tests, verify they pass, and perform only concrete cleanup found by validation
+
+### Milestone: [Phase N Milestone Name]
+**Acceptance Criteria:** (preserve from roadmap)
+- [ ] [criterion 1]
+- [ ] All phase tests pass
+- [ ] No regressions in previous phase tests
+```
+
+**For `none` phases:**
+```
+## Phase N: [Title]
+> Test strategy: none
+
+### Execution Profile
+**Parallel mode:** serial | research-only | review-only | implementation-safe | agent-team
+**Integration owner:** main agent
+**Conflict risk:** low | medium | high
+**Review gates:** correctness, tests, security, performance, docs/API conformance, UX, or none
+
+**Subagent lanes:**
+- Lane: [lane-name or none]
+  - Agent: explorer | worker | default
+  - Role: explorer | implementer | reviewer | docs-researcher | test-reviewer
+  - Mode: read-only | write | review
+  - Scope: [bounded task]
+  - Owns: `path/or/glob` (write lanes only)
+  - Must not edit: `path/or/glob` (write lanes only)
+  - Branch: `agent-team/phase-N-lane-name` (agent-team write lanes only)
+  - Depends on: [lane, step, or none]
+  - Deliverable: [expected output, including branch + commit SHA + PR URL for agent-team write lanes]
+
+### Implementation
+- Step N.1: [First implementation task]
+  - Files: create `path/to/new.ts`, modify `path/to/existing.ts`
+- ...
+
+### Milestone: [Phase N Milestone Name]
+**Acceptance Criteria:** (preserve from roadmap)
+- [ ] [criterion 1]
+```
+
+**On Completion** (fill in when phase is done — all strategies):
+- Deviations from plan: [none, or describe]
+- Tech debt / follow-ups: [none, or list]
+- Ready for next phase: yes/no
+
+### Test Requirements
+
+- **`tdd` phases**: start with writing tests BEFORE implementation. Tests tied to acceptance criteria. Include test file paths.
+- **`tests-after` phases**: implementation comes first. The Green step writes regression tests covering the acceptance criteria.
+- **`none` phases**: no test steps. Milestone omits "All phase tests pass".
+- All `tdd` and `tests-after` milestones must include "All phase tests pass" and "No regressions in previous phase tests".
+- If the project has no test framework yet, the first phase's first step should set it up.
+
+### File-Level Granularity
+
+- Every implementation step lists the specific files to create, modify, or delete.
+- This gives the executing agent clear scope and prevents steps from becoming unbounded.
+- Write-capable subagent lanes must have disjoint owned paths. If they do not, keep implementation serial and use research or review lanes only.
+- Agent-team phases must include a final automated consolidation/PR review step that inspects each lane's branch/PR, verifies changed paths against `Owns` and `Must not edit`, records blocker/advisory findings, integrates only approved lane work, and then runs the phase validation gate.
+
+### Task Classification
+
+Classify each step or follow-up as exactly one of:
+
+- **automated** — the agent executes it as implementation or verification work in `tasks/todo.md`.
+- **manual** — a human-only external action tied to an automated step in `tasks/manual-todo.md`.
+- **record** — a one-time, non-blocking record or measurement that should happen only after a condition becomes true in `tasks/record-todo.md`.
+- **recurring** — cadence-based operational, research, or maintenance work in `tasks/recurring-todo.md`.
+
+Use the narrowest classification that can execute without losing context:
+
+- If the agent can do it by editing repo files, running local commands, using an approved CLI/MCP/API integration, or writing a script with already-available credentials, classify it as **automated**.
+- If the work is blocked only because a secret, account, payment method, approval, hardware device, or human judgment/evidence is missing, classify only that missing prerequisite as **manual**.
+- If one item mixes human and automatable work, split it: the human-gated prerequisite goes to `tasks/manual-todo.md`; the repo/code/config/test follow-up stays in `tasks/todo.md`.
+
+Manual tasks include only human-gated work such as:
+
+- DNS configuration, domain setup, SSL certificates
+- Browser/device testing or visual QA that requires a real account, real device, production environment, or subjective human sign-off
+- OAuth/API credential setup with third-party services when no authenticated CLI/API path is available
+- Deployment approvals, paid environment provisioning, quota/billing approval, or account ownership decisions
+- Signing up for services, billing setup
+- Any step requiring a GUI, physical device, or human judgment that cannot be scripted
+
+Do not classify these as manual:
+
+- Editing source, docs, `.env.example`, config templates, or task docs
+- Installing or wiring SDKs/packages, creating adapters, writing scripts, or updating metadata contracts
+- Running builds, unit tests, local smoke tests, Lighthouse, Playwright, linters, or repo audits
+- Setting local environment variables when the required non-secret values are known or the user has already provided the secret values
+- Running provider CLIs or API calls when authentication is already present or can be requested through the normal approval flow
+
+Manual tasks MUST NOT appear in `tasks/todo.md`. They go in `tasks/manual-todo.md`.
+Agent-executable tasks MUST NOT appear in `tasks/manual-todo.md`. If found there, promote them to `tasks/todo.md` or route a reconciliation fix.
+
+Record tasks MUST NOT appear in `tasks/todo.md` unless they are launch gates or current execution work. They go in `tasks/record-todo.md` with source, condition, non-blocking reason, required data/access, measurement/query, target note, revisit cadence/date, completion evidence, and promotion rule.
+
+Recurring tasks MUST NOT appear in `tasks/todo.md` unless the current run is explicitly in scope for this phase. They go in `tasks/recurring-todo.md` with task, cadence, owner/agent, scope, trigger, last run, next due, command/skill, evidence/output path, and escalation conditions.
+
+## Output
+
+1. **Update `tasks/roadmap.md`** — insert the implementation structure (Tests First / Implementation / Green / Milestone, per strategy) into the target phase, beneath the existing Goal/Scope/Acceptance Criteria. Do NOT modify other phases. Do NOT rewrite the Goal, Scope, or Acceptance Criteria.
+
+2. **Write `tasks/todo.md`** — extract the target phase as a standalone working document, including the `### Execution Profile`. Include enough context (project name, current phase number, total phases) so a fresh session can orient itself without reading `tasks/roadmap.md`. If `tasks/todo.md` already has in-progress work for a different phase, ask the user before overwriting.
+
+3. **Write `tasks/manual-todo.md`** (only if this phase has manual tasks):
+   ```markdown
+   # Manual Tasks — [Project Name]
+
+   > Phase: N — [Phase Title]
+   > These tasks require human-only external action. Do not put repo edits, local commands, CLI/API work, tests, audits, or implementation follow-ups here.
+   > Check them off as you complete them.
+
+   ## Pre-Phase / Setup
+   - [ ] [task] _(blocks: Step N.X)_
+
+   ## During Phase
+   - [ ] [task] _(after: Step N.X)_
+
+   ## Post-Phase / Verification
+   - [ ] [task]
+   ```
+   - `_(blocks: Step N.X)_` = must be done before that automated step
+   - `_(after: Step N.X)_` = should be done after that automated step
+   - No annotation = do anytime during the phase
+   - Only create this file when manual tasks exist — no empty files.
+
+4. **Write `tasks/record-todo.md`** (only if this phase identifies non-blocking condition-gated records):
+   ```markdown
+   # Record Tasks — [Project Name]
+
+   > These tasks are non-blocking records or measurements. Do not execute them through `$exec` unless promoted to `tasks/todo.md`.
+
+   - [ ] [task]
+     - Source: [phase/spec/criterion]
+     - Condition: [when this becomes eligible]
+     - Non-blocking reason: [why this is not a launch gate or current step]
+     - Required data/access: [data, portal, aggregate, credential, or user-provided output]
+     - Measurement/query: [how to collect evidence]
+     - Target/acceptance note: [threshold or expected record]
+     - Revisit: [date or cadence]
+     - Completion evidence: [where to record the result]
+     - Promotion rule: [when to move this into `tasks/todo.md`]
+   ```
+
+5. **Write `tasks/recurring-todo.md`** (only if this phase identifies recurring obligations):
+   ```markdown
+   # Recurring Tasks — [Project Name]
+
+   > These tasks recur on a cadence. Do not execute them through `$exec` unless a due run is promoted to `tasks/todo.md`.
+
+   - [ ] [task]
+     - Cadence: [daily/weekly/monthly/quarterly/on release/etc.]
+     - Owner/agent: [human, `$skill`, or agent role]
+     - Scope: [project/app/area]
+     - Trigger: [time, release, data threshold, user request]
+     - Last run: [date or never]
+     - Next due: [date or rule]
+     - Command/skill: [command or skill to run]
+     - Evidence/output path: [where results are recorded]
+     - Escalation conditions: [when it becomes executable or blocking 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 first step, manual blocker, or verification gap for the planned phase>
+- **Recommended next command:** <one command or route>
+
+Rules:
+
+- Make the next work item primary. Derive it from the first executable step in `tasks/todo.md`, any matching blocker in `tasks/manual-todo.md`, or the phase's verification/setup gap. 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.
+- Inference defaults:
+  - Codex skill invocation (`$plan-phase`, `$exec`) → recommend the matching `$...` command.
+  - 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`.
+  - Claude slash invocation (`/plan-phase`, `/exec`, `/delegate`) or orchestration-heavy work → check `.agents/project.json.enabled_packs` for `exec-loop` — if `exec-loop` is not enabled, recommend `$pack install exec-loop` first; if `exec-loop` is enabled, recommend the matching `/...` route.
+  - 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`.
+- 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.
+- 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.
+
+## Constraints
+
+- **One phase per invocation.** Do not decompose multiple phases ahead of time.
+- **Require `tasks/roadmap.md`.** If it's missing, stop and direct the user to `$roadmap`.
+- **Preserve the roadmap's Goal, Scope, and Acceptance Criteria exactly.** Those are `$roadmap`'s decisions. Only add implementation detail beneath them.
+- **Phase headers must use `## Phase N: [Title]` format** and steps must use `- Step N.X:` format — this is required by `$exec` and `$ship`.
+- Every milestone must have specific, checkable acceptance criteria — not vague statements like "works correctly" but concrete conditions like "POST /api/items returns 201 with valid payload and persists to database."
+- Every `tdd` phase must start with writing failing tests. `tests-after` phases write tests in the Green step.
+- Do not generate standalone cleanup/refactor steps that are conditional on validation finding drift. Fold those checks into the Green validation step and only create a separate follow-up when there is known concrete remediation work.
+- Do not include implementation code — describe what to build and what to test.
+- Note what already exists in the codebase vs. what needs to be created.
+- The `### Execution Profile` must be decision-complete enough for `$exec` to decide whether to use serial execution, read-only subagents, review subagents, or disjoint write subagents after presenting the plan and proceeding under implicit approval.
+- Subagents must not own task docs, roadmap/history updates, shipping, or deploy steps. Those stay with the main agent.
+- Agent-team write lanes must not target `main` or `master`; each lane gets its own GitHub branch and must return branch, commit SHA, validation evidence, and PR URL before consolidation.
+- Manual tasks MUST NOT appear in `tasks/todo.md` — they go in `tasks/manual-todo.md` only.
+- Agent-executable work MUST NOT appear in `tasks/manual-todo.md` — it goes in `tasks/todo.md` or an implementation skill.
+- Non-blocking record tasks MUST NOT appear in `tasks/todo.md` — they go in `tasks/record-todo.md` unless explicitly promoted.
+- Recurring obligations MUST NOT appear in `tasks/todo.md` by default — they go in `tasks/recurring-todo.md` unless a due run is current execution work.
+- Do NOT put plans in `AGENTS.md`, `CLAUDE.md`, or `docs/plan.md`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/agent-work-admin/codex/roadmap/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v0.9 - 2026-06-11
+
+- Updated the inline alignment-page response model to use one bottom `Compile Responses` control with local section feedback YAML hidden until a section feedback choice is selected.
+
+## v0.8 - 2026-06-10
+
+- Added npm-aware install-route alternatives to pack availability guidance while preserving Codex `$pack install` syntax.
+
 ## v0.7 - 2026-06-06
 
 - Add `user-flow-map`, requirements-only UI interview, and layout-mode UX variations to the user-facing design-gate queue.