skillpacks 0.1.0 → 0.1.1

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

@@ -0,0 +1,380 @@
+---
+name: plan-phase
+description: Decompose a single roadmap phase into implementation steps, tests, and file-level detail
+type: planning
+version: v0.1
+argument-hint: "[phase-number] [--no-tdd]"
+invocation: sub-skill
+parent: exec
+---
+
+# 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` (exec-loop pack) and `/exec` (exec-loop pack) 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` is a phase number (e.g., `2`), plan that phase.
+- If `$ARGUMENTS` is empty, plan the **first phase that has acceptance criteria but no implementation steps** (no `### Tests First` or `### Implementation` section yet).
+- If `$ARGUMENTS` contains `--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.
+- `prototypes/*/consolidated/` when present as a visual reference alongside written specs.
+- 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` contains `--no-tdd`, use `tests-after`.
+2. If `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: explore | general-purpose
+  - 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` profiles, every lane **must** have `Mode:` and `Depends on:` filled in with concrete values (not placeholders). Write lanes must have disjoint `Owns:` paths, explicit `Must not edit:` boundaries, and deterministic `Branch:` values that are not `main` or `master` — `/exec` (exec-loop pack) auto-dispatches agent-team lanes via isolated worktrees and uses those fields to build the lane DAG, push lane branches, open PRs, and enforce write-boundary integration. 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 `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: explore | general-purpose
+  - 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: explore | general-purpose
+  - 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: explore | general-purpose
+  - 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** — Claude 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 Claude 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` (exec-loop pack) 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` (exec-loop pack) 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:
+  - 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-only 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 `/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`.
+- 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
+
+- 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 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` (exec-loop pack) and `/ship` (exec-loop pack).
+- 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` (exec-loop pack) to decide whether to use serial execution, read-only subagents, review subagents, or disjoint write subagents after the normal approval gate.
+- 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 `CLAUDE.md` or `docs/plan.md`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/agent-work-admin/claude/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 Claude `/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.

package/packs/agent-work-admin/claude/roadmap/SKILL.md

@@ -2,13 +2,13 @@
 name: roadmap
 description: Scan task pipeline health, build or update the project roadmap, and maintain a priority task queue
 type: planning
-version: v0.7
+version: v0.9
 argument-hint: "[--existing] [path-to-spec]"
 ---
 
 ## 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.
+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>` inside Claude Code, or `npx skillpacks install <pack>` from the project shell, 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.
 
 # Roadmap - Task Pipeline Manager
 
@@ -226,7 +226,7 @@ User-facing specs exist, but one or more required design-planning artifacts are
 - `specs/ux-variations-*.md` — run `/ux-variations --layout-mode` (product-design pack) after user-flow and UI requirements to compare layout approaches.
 - `specs/ui-*.md` — run `/ui-interview` (product-design pack) only when a full UI specification is still needed after layout selection.
 
-For `/journey-map` (customer-lifecycle pack), `/user-flow-map` (product-design pack), `/ui-interview` (product-design pack), and `/ux-variations` (product-design pack), apply the Pack Availability Guard — if the target skill's pack is not in `.agents/project.json` `enabled_packs`, recommend `/pack install <pack>` before the skill.
+For `/journey-map` (customer-lifecycle pack), `/user-flow-map` (product-design pack), `/ui-interview` (product-design pack), and `/ux-variations` (product-design pack), apply the Pack Availability Guard — if the target skill's pack is not in `.agents/project.json` `enabled_packs`, recommend `/pack install <pack>` inside Claude Code, or `npx skillpacks install <pack>` from the project shell, before the skill.
 
 Only flag this for user-facing product work. Skip for pure backend, CLI, library, infrastructure, or internal automation specs unless they include a meaningful human workflow or interface.
 
@@ -438,17 +438,17 @@ Build and attempt to open `alignment/roadmap-{topic}.html` before writing or rep
 
 **Required inline questions.** Ask whether the evidence is sufficient for the roadmap, whether any assumptions or confidence levels are wrong, whether phase sequencing and manual-task classification are acceptable, whether the proposed canonical file changes are approved, and whether downstream route emission should remain blocked.
 
-**Section feedback controls.** Add lightweight section-feedback controls to every major section of the page: emphasize, reject or flag a concern, and clarification needed. Selecting a control reveals a multi-line section-feedback textarea placed directly under or beside the emphasize/down/clarify controls. This textarea is separate from gate-question text inputs, so it still appears near the feedback controls even when the same section also has required gate questions with their own text boxes. These controls are optional for final approval and do not replace required gate questions. They also power the separate feedback-only YAML path so the user can send emphasis requests, concerns, or clarification requests before answering every required gate question.
+**Section feedback controls.** Add lightweight section-feedback controls to every major section of the page: emphasize, reject or flag a concern, and clarification needed. The section feedback textarea, local compile/copy controls, and local read-only YAML output are hidden by default. Selecting a control reveals a multi-line section-feedback textarea plus local "Compile Feedback YAML", "Copy YAML", and read-only YAML controls placed directly under or beside the emphasize/down/clarify controls; deselecting the active control hides the textarea, local compile/copy controls, and local read-only YAML output again and omits that section from compiled responses. This textarea is separate from gate-question text inputs, so it still appears near the feedback controls even when the same section also has required gate questions with their own text boxes. These controls are optional for final approval and do not replace required gate questions. They contribute `section_feedback` entries to the unified response payload so the user can send emphasis requests, concerns, or clarification requests before answering every required gate question.
 
-**Feedback-only YAML contract.** Provide feedback-only YAML in two places: locally under each selected section-feedback textarea, and globally in the bottom compile section. When a section-feedback control is selected, show local "Compile Feedback YAML" and "Copy YAML" controls plus a read-only YAML textarea directly under that section's feedback textarea. The local feedback compile generates YAML with `alignment_page: alignment/{skill-name}-{topic}.html`, `feedback_status: revision-request`, `approval_status: not-approved`, `unanswered_required_questions`, and a `section_feedback` list containing the single selected section-feedback entry for that local control. The bottom "Compile Feedback YAML" control generates the same YAML shape but aggregates every selected section-feedback entry on the page. Enable both local and bottom feedback compile controls as soon as at least one section-feedback control is set, even if required inline gate questions are unanswered. Populate `alignment_page` from the known repo-relative output path used to write the HTML page, not from the page title, browser URL, window location, or any display label. Each feedback entry uses `section`, `feedback` (`emphasize`, `down`, or `needs-clarification`), optional `notes` from that section's feedback textarea, and `requested_agent_action` (`add-weight-to-section`, `investigate-and-revise`, or `clarify-before-approval`). For `emphasize` feedback, the YAML must tell the agent to add more weight, prominence, evidence, detail, or recommendation emphasis to that section or to the specific point named in the notes; this is a revision request, not approval of the section as-is. For `down` and `needs-clarification` feedback, the YAML must tell the agent to evaluate the feedback, investigate further when needed, and contextually amend the HTML alignment page before asking again for final approval answers. Copy and display feedback YAML locally or at the bottom with the same clipboard retry and textarea fallback behavior as final gate YAML. Do not render the bottom feedback compile controls as a sticky or fixed banner.
+**Section feedback YAML contract.** Provide local section-feedback YAML only under each selected section-feedback textarea. When a section-feedback control is selected, show local "Compile Feedback YAML" and "Copy YAML" controls plus a read-only YAML textarea directly under that section's feedback textarea; when the control is deselected, hide those local controls and output again. The local feedback compile generates YAML with `alignment_page: alignment/roadmap-{topic}.html`, `feedback_status: revision-request`, `approval_status: not-approved`, `unanswered_required_questions`, and a `section_feedback` list containing the single selected section-feedback entry for that local control. Enable local feedback compile controls as soon as that section-feedback control is set, even if required inline gate questions are unanswered. Populate `alignment_page` from the known repo-relative output path used to write the HTML page, not from the page title, browser URL, window location, or any display label. Each feedback entry uses `section`, `feedback` (`emphasize`, `down`, or `needs-clarification`), optional `notes` from that section's feedback textarea, and `requested_agent_action` (`add-weight-to-section`, `investigate-and-revise`, or `clarify-before-approval`). For `emphasize` feedback, the YAML must tell the agent to add more weight, prominence, evidence, detail, or recommendation emphasis to that section or to the specific point named in the notes; this is a revision request, not approval of the section as-is. For `down` and `needs-clarification` feedback, the YAML must tell the agent to evaluate the feedback, investigate further when needed, and contextually amend the HTML alignment page before asking again for final approval responses. Copy and display local feedback YAML with the same clipboard retry and textarea fallback behavior as response YAML.
 
-**Gate YAML contract.** At the bottom of the page, include an ordinary in-flow compile section with a "Compile Feedback YAML" button for selected section feedback and a separate "Compile Answers" button for final approval answers. The bottom compile section must not be sticky, fixed, floating, or styled as a persistent banner. The "Compile Answers" button compiles final approval answers into YAML with `alignment_page: alignment/{skill-name}-{topic}.html`, `approval_status: ready-for-agent-review`, `section`, `gate_type`, `status`, `decision`, `notes`, and `approved_file_changes` fields. Populate `alignment_page` from the known repo-relative output path used to write the HTML page, not from the page title, browser URL, window location, or any display label. The final approval button remains disabled until every required question has a selection. The final YAML may also include any section feedback the user set, using the feedback-only YAML `section_feedback` shape. The page must automatically attempt to copy the YAML to the clipboard, provide an explicit "Copy YAML" button, and fall back to selecting the textarea contents.
+**Response YAML contract.** At the bottom of the page, include an ordinary in-flow compile section with a single "Compile Responses" button. The bottom compile section must not be sticky, fixed, floating, or styled as a persistent banner. "Compile Responses" aggregates answered inline gate questions, including free-text notes, plus every selected section-feedback entry. Enable it as soon as at least one gate question has an answer or at least one section-feedback control is selected; do not require every required gate question to be answered before compiling partial responses. The compiled YAML is a mixed response payload with `alignment_page: alignment/roadmap-{topic}.html`, `response_status` (`partial` or `complete`), `approval_status` (`not-approved` or `ready-for-agent-review`), `required_gate_status` (`incomplete` or `complete`), and `unanswered_required_questions`. It may include a `gate_answers` list where each answered gate item uses `section`, `gate_type`, `status`, `decision`, optional `notes`, and optional `approved_file_changes` fields. It may also include a `section_feedback` list using the section feedback YAML shape. Set `approval_status: ready-for-agent-review` only when every required gate is answered and there are no unresolved `down`, unresolved `needs-clarification`, or other unresolved negative feedback items; otherwise set `approval_status: not-approved` and keep the response in review. Populate `alignment_page` from the known repo-relative output path used to write the HTML page, not from the page title, browser URL, window location, or any display label. The page must automatically attempt to copy the YAML to the clipboard, provide an explicit "Copy YAML" button, and fall back to selecting the textarea contents.
 
-**Pre-approval stop.** Before user approval, the next action is review of the HTML alignment page. Ask the user to review the page and provide either local or bottom feedback-only YAML for emphasis requests, concerns, or clarification, or final compiled YAML answers when ready. Do not require the user to answer every gate before sending emphasis requests, negative feedback, or clarification needs. When feedback-only YAML is provided, treat it as a revision request: evaluate the feedback, investigate further when needed, archive and amend the HTML alignment page contextually, highlight the changes, and ask again for review. Do not include `Recommended next skill`, `Recommended next command`, or downstream routing language until after final compiled YAML has been provided and the approved artifacts have been written or updated.
+**Pre-approval stop.** Before user approval, the next action is review of the HTML alignment page. Ask the user to review the page and provide either local section-feedback YAML for one section or bottom compiled response YAML for gate answers and/or selected section feedback. Do not require the user to answer every gate before sending emphasis requests, negative feedback, clarification needs, or other partial responses. When compiled response YAML is partial or has `approval_status: not-approved`, treat it as a revision request: evaluate the feedback, investigate further when needed, archive and amend the HTML alignment page contextually, highlight the changes, and ask again for review. Do not include `Recommended next skill`, `Recommended next command`, or downstream routing language until after final compiled response YAML with `approval_status: ready-for-agent-review` has been provided and the approved artifacts have been written or updated.
 
 ## 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 `/pack install <pack-name>` inside Claude Code, or `npx skillpacks install <pack-name>` from the project shell, as the install prerequisite before the recommendation.
 - **Always interview for new roadmaps.** Do not produce a roadmap without user input on priorities and sequencing when building one from scratch (State B).
 - **Respect existing specs.** Do not modify files in `specs/` (or `spec.md`) — the roadmap references specs, it doesn't rewrite them.
 - **Phase headers must use `## Phase N: [Title]` format** for compatibility with `/exec` (exec-loop pack), `/ship` (exec-loop pack), and phase transition logic.