aw-ecc 1.4.32 → 1.4.48

package/skills/aw-design/references/stitch-workflow.md

@@ -0,0 +1,127 @@
+# Stitch MCP Workflow
+
+Stitch MCP is the primary generation path. Tools live on the `user-ghl-ai` server.
+
+## Tool reference
+
+| Tool | Purpose |
+|---|---|
+| `stitch_create-project` | One project per feature |
+| `stitch_create-design-system` | Create Highrise token set |
+| `stitch_apply-design-system` | Apply tokens to screens (multi-select pass) |
+| `stitch_generate-screen` | Generate screen from prompt |
+| `stitch_edit-screens` | Refine with instructions |
+| `stitch_generate-variants` | Explore alternative layouts |
+| `stitch_get-screen` | Get screenshot + HTML URLs |
+| `stitch_get-project` | Get project details + theme |
+| `stitch_list-screens` | List all screens in a project |
+| `stitch_list-projects` | List all projects |
+
+## Generation steps
+
+1. **Create project:** `stitch_create-project` with a descriptive title. Save the numeric project ID.
+
+2. **Create design system:**
+   ```
+   stitch_create-design-system:
+     displayName: "Highrise - <feature>"
+     theme:
+       colorMode: "LIGHT"
+       headlineFont: "INTER"
+       bodyFont: "INTER"
+       labelFont: "INTER"
+       roundness: "ROUND_EIGHT"
+       customColor: "#155EEF"
+       colorVariant: "TONAL_SPOT"
+   ```
+
+3. **Batch screens in groups of 3–4.** Don't send all screens in one prompt — Stitch drops quality beyond 3 per batch. Use `designs/SCREEN_PLAN.md` to group by flow (e.g., onboarding batch, list+detail batch, settings batch).
+
+4. **Generate primary screen first** using the full prompt template (`references/prompt-template.md`). Use `deviceType: "DESKTOP"` and `modelId: "GEMINI_3_FLASH"` — it's the default because Pro regularly exceeds the ~70s MCP timeout. Flash returns in ~20–40s with quality that is more than good enough for the Highrise token set. Only switch to `GEMINI_3_1_PRO` for a specific screen if Flash output is visibly weak after one edit pass.
+
+5. **Extract theme** via `stitch_get-project`. Document exact hex values returned — feed them into all remaining prompts.
+
+6. **Generate remaining screens** in batches, using the extracted theme.
+
+7. **Multi-select theme pass.** Once all screens exist, select all and apply `stitch_apply-design-system` with the asset ID from step 2. This is the single most important step for visual consistency — a single prompt fixes what would otherwise take dozens of edits.
+
+8. **Generate state variants** using the prompt additions in `references/prompt-template.md`.
+
+9. **Download HTML + screenshots** for each screen via `stitch_get-screen`.
+
+## Responsive generation strategy
+
+Stitch's `deviceType` parameter is the canvas the AI designs for (MOBILE / TABLET / DESKTOP / AGNOSTIC), but the generated HTML can and must include CSS media queries for all four breakpoints.
+
+**Default: generate at `DESKTOP`.** The prompt template already demands mobile-first media queries inside the HTML, so a single DESKTOP generation typically produces all breakpoints when the prompt is followed.
+
+**Generate a separate MOBILE screen** when the mobile UX is genuinely different — not just reflowed. Common triggers:
+
+- Data tables that should collapse to card-per-row rather than scroll horizontally
+- Multi-step flows where desktop uses a sidebar but mobile uses a full-screen wizard
+- Dashboards where mobile needs a totally different information hierarchy
+
+When generating the MOBILE variant, prompt Stitch explicitly: "This is the mobile companion to [desktop screen]. Use the same tokens and design system. [describe the mobile-specific layout]."
+
+**Verify responsive in QA**, not just accept it:
+
+1. Open the generated HTML in a browser
+2. Resize the viewport through all four breakpoints (320, 768, 1024, 1440)
+3. Confirm:
+   - Sidebar collapses/hides at the right widths
+   - Tables don't overflow the viewport
+   - Modals go full-screen on mobile
+   - Touch targets are ≥44×44px at mobile size
+   - No horizontal scroll on the body at any width
+
+If any breakpoint is broken, use `stitch_edit-screens` with an explicit fix instruction like "Add mobile breakpoint: at max-width 767px, hide sidebar and replace with hamburger drawer. Stack metric cards vertically." Do NOT regenerate — that wastes quota.
+
+## Model selection
+
+Two models are available:
+
+| Model | Typical time | When to use |
+|---|---|---|
+| `GEMINI_3_FLASH` (default) | 20–40s | All screens and state variants — fits comfortably inside the ~70s MCP timeout |
+| `GEMINI_3_1_PRO` | 30–90s+ | Only when a specific Flash screen comes out visibly weak and an edit pass didn't fix it. Expect timeouts — follow the polling procedure below. |
+
+Pro regularly exceeds the client timeout and rarely delivers a visible quality gain for Highrise-constrained output. Default to Flash; escalate per-screen only when needed.
+
+## Timeouts
+
+Even on Flash, occasional screens take longer than the client timeout. Treat a timeout as "still running, not failed" — don't fall back to HTML until you've actually confirmed failure.
+
+### When a `stitch_generate-screen` call times out
+
+1. **Wait and poll** — the screen is likely still generating server-side. Do NOT retry the generate call (that wastes a request from the 350/month quota). Instead:
+   - Call `stitch_list-screens` with the `projectId` to see if the screen appeared
+   - If present, call `stitch_get-screen` to fetch the result
+   - Poll every 20–30s for up to 2 minutes on Flash, or 3 minutes on Pro, before treating it as a real failure
+
+2. **If still not present after the poll window** — retry once with the same model. If that also times out, retry with a simpler prompt (drop non-essential sections) on Flash.
+
+3. **If the simplified retry also errors** — document the failure (include the prompt and error), then fall back to the HTML path for that specific screen. Other screens in the batch can still use Stitch.
+
+### Rate limit reminder
+
+350 generate requests/month across the workspace. Timeouts still consume quota on the server side even if your client times out. Prefer `stitch_edit-screens` over regenerating for small changes.
+
+## HTML fallback path
+
+Only when Stitch is truly unavailable (tools missing, confirmed failure, or user opts out):
+
+- Write self-contained HTML files with embedded `<style>` block
+- Use CSS custom properties in `:root` for all tokens (enables `.dark` class swap)
+- Include the full micro-interactions CSS from `references/micro-interactions.md`
+- Include responsive media queries at 768px, 1024px, 1280px
+- Same prompt template shapes the structure — you're implementing it directly instead of sending it to Stitch
+
+## Iterating on feedback
+
+| Feedback type | Stitch action | HTML action |
+|---|---|---|
+| Targeted fix ("make sidebar narrower") | `stitch_edit-screens` with specific instructions | Edit the HTML/CSS directly |
+| Want alternatives | `stitch_generate-variants` from the source screen | Generate a second version |
+| Major rethink | `stitch_generate-screen` with revised prompt | Rewrite from scratch |
+
+After edits, re-enter step 6 of the skill (`references/self-review.md`) — do not just spot-check. Any change can regress a Track A deterministic gate. Update affected state variants if layout changed.

package/skills/aw-feature/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: aw-feature
+description: Phase-by-phase feature development orchestrator. Guides users through 18 SDLC phases from repo setup to production, composing existing AW stage skills. Pauses at each phase for user direction.
+trigger: User invokes /aw:feature or asks for guided feature development, step-by-step feature workflow, or phase-by-phase development.
+---
+
+# AW Feature — Guided SDLC Orchestrator
+
+## Overview
+
+`aw-feature` is a **guided orchestrator** that walks users through 18 SDLC phases. Unlike `aw-yolo` (autonomous end-to-end), this skill pauses at every phase boundary to ask the user whether to proceed, refine, or skip. It composes existing stage skills — it never reimplements their logic.
+
+The primary audience is **PMs, designers, and engineers** who want a structured workflow without needing to know which `/aw:*` commands to invoke in which order.
+
+## When to Use
+
+- User wants to develop a feature end-to-end with guidance
+- User is non-technical and needs the system to guide them through SDLC stages
+- User wants a structured checklist that prevents skipping important phases
+- User says "feature", "guided flow", "step by step", "walk me through"
+
+## When Not to Use
+
+- User knows exactly which stage they need → use the specific `/aw:*` command
+- User wants autonomous end-to-end execution → use `aw-yolo` internally
+- User is doing a bug fix (too lightweight for 18 phases) → use `/aw:investigate` + `/aw:build`
+- User only needs one phase (e.g., just planning) → use `/aw:plan` directly
+
+## Workflow
+
+### Step 1: Show the roadmap and stop
+
+The very first response after invocation is always the 18-phase roadmap, a note on which phases would be auto-skipped (with reasons), and a suggested starting phase. Nothing else — no file creation, no code, no planning. Wait for the user to say where to start.
+
+### Step 2: Initialize (after user confirms)
+
+1. Parse `$ARGUMENTS` to derive a feature title and slug
+2. Create `.aw_docs/features/<slug>/` directory
+3. Create `state.json` with all 18 phases set to `pending` (mark auto-skipped ones as `skipped`)
+
+### Step 3: Smart Entry Detection
+
+Auto-skip signals (always announce each one):
+- Already in a git repo → skip Phase 1
+- Onboarding artifact exists (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, or `.codex/AGENTS.md`) → skip Phase 2
+- Planning artifacts exist → skip relevant planning phases
+- Implementation exists → suggest starting at testing phase
+- PR exists → suggest starting at PR checks phase
+
+### Step 4: Execute Current Phase
+
+For each phase:
+
+1. **Announce** — Show phase header with plain-language explanation
+2. **Load backing skill** — Read the SKILL.md for the delegated skill
+3. **Execute** — Run the skill's workflow within its contract
+4. **Update state.json** — Write the phase status immediately. This is the only way to resume across sessions. Do this BEFORE showing the completion message.
+5. **Show output** — Summarize what was produced
+6. **Pause** — Ask user to proceed, refine, or skip
+
+When the backing stage writes a canonical Markdown artifact, include the generated `.aw_docs/features/<feature_slug>/<artifact_basename>.html` companion in the output summary. Markdown-only is allowed only when the user explicitly requests it for this run.
+
+### Step 4: Handle User Navigation
+
+| User says | Action |
+|---|---|
+| "next" | Mark current phase done, advance to next pending phase |
+| "skip" | Ask for reason, log it, mark as skipped, advance |
+| "refine" | Re-enter current phase with additional context |
+| "phase N" | Jump to Phase N (mark intervening phases as skipped with note) |
+| "status" | Show progress tracker |
+| "back to N" | Re-enter Phase N (mark as in_progress again) |
+| "pause" / "stop" | Save state, show how to resume later |
+
+### Step 5: Phase Completion
+
+After each phase completes:
+- Update `state.json`
+- Show progress tracker (brief version — just the bar and current position)
+- Prompt for next action
+
+### Step 6: Feature Completion
+
+When Phase 18 completes (or user says "done"):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ AW ► FEATURE COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Feature: <title>
+Phases completed: <N>/18 (skipped: <M>)
+
+Artifacts:
+  - PRD: .aw_docs/features/<slug>/prd.md
+  - Spec: .aw_docs/features/<slug>/spec.md
+  - PR: <PR URL>
+  - Staging: <staging URL>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Phase Definitions
+
+### Phase 1: Repo Setup
+**What:** Clone the right repo from a screenshot or URL.
+**Skill:** `local-ghl-setup-from-screenshot`
+**Plain language:** "First, let's make sure you have the right code on your machine."
+**Auto-skip when:** Already inside a git repository.
+
+### Phase 2: Codebase Onboarding
+**What:** Understand the repo's architecture, conventions, and entry points.
+**Skill:** `codebase-onboarding`
+**Plain language:** "Let me quickly understand how this codebase is organized."
+**Auto-skip when:** A harness-level onboarding artifact already exists (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, or `.codex/AGENTS.md`).
+
+### Phase 3: Requirements
+**What:** A conversation to understand the feature before writing anything.
+**Skill:** `aw-plan` (product mode — requirements gathering only)
+**Plain language:** "Let's nail down exactly what this feature needs to do."
+**Behavior:** This phase is a back-and-forth dialogue. Ask about scope, users, success criteria, edge cases, and constraints. Listen to the answers, then follow up on anything unclear. Keep the conversation going until you genuinely understand what to build and how you'd know it's done — then write `requirements.md`.
+
+### Phase 4: PRD
+**What:** Write a structured product requirements document from Phase 3 outputs.
+**Skill:** `aw-plan` (product mode — document generation)
+**Plain language:** "Now I'll write up the requirements so everyone's on the same page."
+**Auto-skip when:** `prd.md` already exists for this feature.
+
+### Phase 5: Design
+**What:** Explore design options, make UX/UI decisions. Generate HTML prototype screens for frontend features.
+**Skill:** `aw-design`
+**Plain language:** "Let's figure out how this should look and work for users."
+**Suggest skip when:** Backend-only feature with no UI component.
+
+### Phase 6: Technical Spec
+**What:** Architecture decisions, API impact, data model changes.
+**Skill:** `aw-plan` (technical mode)
+**Plain language:** "Time to plan the technical approach — what to build and how."
+**Auto-skip when:** `spec.md` already exists for this feature.
+
+### Phase 7: Task Breakdown
+**What:** Break implementation into ordered, phased tasks.
+**Skill:** `aw-plan` (tasks mode)
+**Plain language:** "Breaking the work into small, manageable steps."
+**Auto-skip when:** `tasks.md` already exists for this feature.
+
+### Phase 8: Build
+**What:** Implement code in thin, reversible slices.
+**Skill:** `aw-build` (code mode) + `incremental-implementation`
+**Plain language:** "Building the feature, one piece at a time."
+**Behavior:** After each meaningful slice, pause and show progress. This is the longest phase.
+
+### Phase 9: Tests
+**What:** Write and run unit/integration tests.
+**Skill:** `aw-test` (feature mode) + `tdd-workflow`
+**Plain language:** "Writing tests to make sure everything works correctly."
+
+### Phase 10: Self-Review
+**What:** Automated code quality, correctness, and architecture review.
+**Skill:** `aw-review` (findings mode)
+**Plain language:** "Reviewing the code for quality, bugs, and best practices."
+
+### Phase 11: Debug & Fix
+**What:** Fix issues found in tests or review.
+**Skill:** `aw-investigate` + `aw-build`
+**Plain language:** "Fixing the issues we found in testing and review."
+**Auto-skip when:** Phase 9 and Phase 10 found no issues.
+
+### Phase 12: Docs & i18n
+**What:** Update documentation and add translation strings.
+**Skill:** `aw-build` (docs mode)
+**Plain language:** "Updating docs and making sure text is translatable."
+**Suggest skip when:** No user-facing strings changed and no public API changed.
+
+### Phase 13: Platform Specialists
+**What:** Security, performance, accessibility, and domain-specific reviews.
+**Skill:** `aw-review` (governance mode) + `using-platform-skills`
+**Plain language:** "Getting specialist reviews — security, performance, accessibility."
+
+### Phase 14: Setup Audit (HARD GATE)
+**What:** Verify lint, types, build, and full test suite pass.
+**Skill:** `aw-test` (release mode) + `verification-loop`
+**Plain language:** "Final check — making sure everything compiles and all tests pass."
+**Hard gate:** Must pass before PR creation. Cannot be skipped.
+
+### Phase 15: PR Creation
+**What:** Create a pull request with summary and test plan.
+**Skill:** `aw-deploy` (pr mode)
+**Plain language:** "Creating a pull request so the team can review your changes."
+
+### Phase 16: PR Checks & Fixes (AUTOMATIC)
+**What:** Resolve merge conflicts, fix CI warnings, lint errors, and type issues.
+**Skill:** `aw-build` + `aw-review`
+**Plain language:** "Checking the PR for merge conflicts and warnings, then fixing them automatically."
+**Hard gate:** Cannot be skipped.
+
+**Three-step automatic sequence:**
+
+1. **Merge Conflict Detection & Resolution**
+   - Fetch and attempt merge with target branch (detect base from PR, default to `main`)
+   - If conflicts exist: identify conflicting files, resolve intelligently, show each resolution to user, commit
+   - If conflict involves business logic (not just formatting/imports): pause and ask user for the correct resolution
+
+2. **CI / Lint / Type Fixes**
+   - Check PR status for failing checks, lint warnings, type errors
+   - Fix automatically, push to PR branch
+
+3. **Final Verification**
+   - Confirm no remaining conflicts, all checks passing
+   - If still failing after fixes, report what's left and ask user for direction
+
+### Phase 17: Staging Deploy
+**What:** Deploy to staging environment and provide staging link.
+**Skill:** `aw-deploy` (staging mode)
+**Plain language:** "Deploying to staging so you can test it in a real environment."
+
+### Phase 18: Production & Closeout
+**What:** Production deployment, rollback readiness, release notes.
+**Skill:** `aw-ship`
+**Plain language:** "Final step — deploying to production and closing out the release."
+
+## State File Contract (MANDATORY — write at every phase boundary)
+
+**You MUST update this file after every phase transition.** This is the only way to resume across sessions. If you skip this, the user loses all progress.
+
+**Keep it minimal** — do not add extra fields. The format is intentionally small so it's fast to write and survives context window limits:
+
+```json
+{
+  "feature_slug": "contacts-export-button",
+  "feature_title": "Build a contacts export button",
+  "command": "aw:feature",
+  "current_phase": 5,
+  "phases": {
+    "1": "done",
+    "2": "done",
+    "3": "done",
+    "4": "done",
+    "5": "in_progress"
+  }
+}
+```
+
+Phase values: `"done"`, `"in_progress"`, `"skipped"`, `"pending"`
+
+**Write trigger:** Immediately after a phase completes or is skipped, before showing the pause prompt. Use the Write tool — do not defer or batch.
+
+## Human HTML Companion
+
+`aw-feature` delegates HTML generation to the backing stage skills.
+Markdown remains canonical for agents, while TeamOfOne-readable HTML companions are produced by the `aw:echo` subagent for planning, build, test, review, deploy, and ship artifacts when output mode is `dual` or `html`.
+HTML sidecars are required phase outputs, not advisory metadata. Invoking `/aw:feature` in default `dual` mode is explicit authorization to spawn exactly one `aw:echo` subagent per artifact-producing phase for HTML companion generation.
+Each artifact-producing phase must produce the colocated `.html` sidecar before its final phase handoff unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn using the `aw:echo` safety and design contract, record `generated_fallback` plus the blocker, and keep Markdown canonical.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The user said next so I can rush through" | "Next" means advance ONE phase, then pause again |
+| "This phase doesn't apply, I'll skip silently" | Always announce skips with a reason |
+| "I'll do phases 8-10 in one go since they're related" | Each phase gets its own announcement, execution, and pause |
+| "The user is technical, they don't need the plain-language explanation" | Always show the explanation — it costs nothing and helps tracking |
+| "Phase 16 needs user input for each fix" | Phase 16 is automatic — fix and push without asking unless a decision is needed |
+| "I can skip the progress tracker, the user knows where we are" | Always show progress at phase boundaries |
+
+## Red Flags
+
+- Advancing to the next phase without the user saying "next" or equivalent
+- Skipping a phase without announcing it
+- Running more than one phase in a single response without pausing between them
+- Reimplementing logic that belongs in a backing skill (e.g., writing test code instead of loading `aw-test`)
+- Showing the progress tracker without phase status symbols
+- Letting Phase 15 (PR Creation) proceed when Phase 14 (Setup Audit) hasn't passed
+
+## Verification
+
+- [ ] All 18 phases are defined with backing skills
+- [ ] Every phase pauses for user input before advancing
+- [ ] Auto-skips are announced with reasons
+- [ ] Hard gates (Phase 14, 16) cannot be bypassed
+- [ ] Progress tracker uses correct status symbols (✓ ► ○ ⊘)
+- [ ] State.json is updated after every phase transition
+- [ ] Plain-language descriptions are shown for every phase
+- [ ] HTML companion status is shown when a phase produced a stage artifact
+
+## Final Output Shape
+
+At each phase boundary, always include:
+- `Phase` — current phase number and name
+- `Status` — what was produced or decided
+- `Progress` — visual progress bar + X/18
+- `HTML Companion` — generated path when the phase produced a stage artifact, or explicit Markdown-only skip
+- `Next` — what the next phase is and a plain-language description
+- `Prompt` — ask user to proceed, refine, or skip

package/skills/aw-investigate/SKILL.md

@@ -26,6 +26,7 @@ Do not use once the cause is already clear and implementation is ready.
    Record the trigger, expected behavior, actual behavior, and current blast radius.
 2. Reproduce or isolate.
    Use `aw-debug` and `../../references/debug-triage.md`.
+   Load `diagnose` when the failure is unclear, hard to reproduce, performance-related, or has already attracted speculative fixes.
    For browser-visible issues, load `browser-testing-with-devtools`.
    Prefer the smallest confirming probe over speculative patching.
 3. Load the right org-standard context.
@@ -82,9 +83,23 @@ Every investigation handoff must make these things obvious:
 - commands run
 - likely fault surface
 - open questions
+- `html_companion_artifacts`
 - blockers
 - recommended next commands
 
+## Human HTML Companion
+
+Markdown `investigation.md` remains canonical for agents.
+When investigate writes or materially updates `investigation.md`, also create or refresh `.aw_docs/features/<feature_slug>/investigation.html`. HTML sidecars are required stage outputs, not advisory metadata.
+
+Delegate to the `aw:echo` subagent with the `investigation-report` profile.
+Invoking `/aw:investigate` in default `dual` mode is explicit authorization to spawn exactly one `aw:echo` subagent for HTML companion generation; do not skip HTML only because no direct command is available.
+Resolve output mode as: explicit user request for Markdown-only -> otherwise `dual`. `.aw_docs/config.json` and `AW_DOCS_OUTPUT_MODE` may request `dual` or `html`, but must not silently suppress required SDLC HTML sidecars.
+
+Pass expected vs actual behavior, probes, evidence, fault surface, confidence, blockers, and next probe or repair path as the source bundle.
+Record the colocated sidecar in `state.json` `html_companion_artifacts` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
+Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar before the final handoff unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn using the `aw:echo` safety and design contract, record `generated_fallback` plus the blocker, and keep Markdown canonical.
+
 ## Verification
 
 Before leaving investigate, confirm:
@@ -94,6 +109,7 @@ Before leaving investigate, confirm:
 - [ ] the likely fault surface is concrete enough to guide build
 - [ ] the next stage is clear: build, more investigation, or blocked
 - [ ] `investigation.md` and `state.json` are updated
+- [ ] the HTML companion file exists, or the user explicitly requested Markdown-only
 
 ## Final Output Shape
 
@@ -105,5 +121,6 @@ Always end with:
 - `Evidence`
 - `Completed Probes`
 - `Likely Fault Surface`
+- `HTML Companion`
 - `Open Questions`
 - `Next`

package/skills/aw-plan/SKILL.md

@@ -38,9 +38,11 @@ This legacy heading maps to the detailed planning process below.
 2. Identify the feature and current artifact state.
    Infer or honor the feature slug.
    Detect which planning artifacts already exist and which are actually missing.
-3. Choose the smallest internal route.
-   Decide whether the request is already clear enough for direct planning or needs discovery first.
+3. Understand the problem before planning it.
+   In `product` mode, start by having a conversation with the user. Think of it like a PM sitting down with a stakeholder — ask about scope, target users, success criteria, edge cases, and constraints. Listen to the answers. Follow up on anything vague. Keep going until the problem is genuinely clear. Only then move to writing artifacts.
+   In other modes, decide whether the request is already clear enough for direct planning or needs discovery first.
    For raw concepts or product-shaping work, load `idea-refine` before freezing the direction.
+   Use `grill-with-docs` when the request is fuzzy, domain-language-heavy, high-impact, or likely to hide edge cases. It is a precision tool, not a mandatory prelude for every plan.
 4. Plan in dependency order.
    Perform an explicit architecture review before freezing the technical path.
    Name the key assumptions, constraints, risks, and mitigations instead of leaving them implied.
@@ -50,6 +52,7 @@ This legacy heading maps to the detailed planning process below.
    For major architectural or public-behavior decisions, load `documentation-and-adrs`.
 5. Slice vertically where possible.
    Prefer end-to-end feature slices and concrete checkpoints over horizontal batch plans.
+   When a task plan needs a slice model before `tasks.md`, load `to-issues` and feed its vertical slices into `aw-tasks`; do not publish remote tracker issues unless the user explicitly requests that.
 6. Write only the missing artifacts.
    When technical uncertainty exists, route through `aw-spec` before `aw-tasks`.
    Do not let task planning invent or silently repair an unresolved contract.
@@ -66,7 +69,10 @@ Use the smallest correct internal route:
 
 - raw idea or under-shaped concept -> `idea-refine`, then `aw-brainstorm` when deeper repo-aware exploration is still needed
 - fuzzy request, open design question, or overscoped feature -> `aw-brainstorm`
+- domain-language-heavy or edge-case-heavy planning -> `grill-with-docs`
+- product/full mode or missing product assumptions -> `to-prd`
 - approved direction but missing technical contract -> `aw-spec`
+- PRD/spec needs implementation-ready vertical slices -> `to-issues`, then `aw-tasks`
 - approved spec but missing execution recipe -> `aw-tasks`
 - already execution-ready tasks -> stop and recommend `aw-build`
 
@@ -76,7 +82,7 @@ Do not collapse all of these responsibilities back into one vague planning pass.
 
 | Mode | Use when | Primary outputs |
 |---|---|---|
-| `product` | problem, scope, or acceptance criteria are unclear | `prd.md`, `state.json` |
+| `product` | problem, scope, or acceptance criteria are unclear — start with a conversation to understand the user's needs before writing anything | `requirements.md`, `prd.md`, `state.json` |
 | `design` | UX behavior or interface design must be defined | `design.md`, `designs/`, `state.json` |
 | `technical` | implementation approach or architecture must be defined | `spec.md`, `state.json` |
 | `tasks` | implementation work needs to be broken into steps | `tasks.md`, `state.json` |
@@ -95,6 +101,28 @@ Do not collapse all of these responsibilities back into one vague planning pass.
 - do not write planning artifacts to `docs/plans/`
 - do not create random filenames
 - do not write implementation code
+- do not require `prd.md` for a technical request that is already clear enough for `spec.md`
+- do not publish tracker issues from `to-issues` unless explicitly requested
+
+## Human HTML Companion
+
+Markdown planning artifacts remain canonical for agents.
+When planning writes or materially updates `prd.md`, `design.md`, `spec.md`, or `tasks.md`, also create or refresh a human-readable HTML companion. HTML sidecars are required stage outputs, not advisory metadata.
+
+Delegate to the `aw:echo` subagent for the companion instead of hand-rolling stage-local HTML.
+`aw:echo` is not a slash command or direct tool. Invoking `/aw:plan` in default `dual` mode is explicit authorization to spawn exactly one `aw:echo` subagent for HTML companion generation; do not skip HTML only because no direct command is available.
+Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar before the final handoff unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn using the `aw:echo` safety and design contract, record `generated_fallback` plus the blocker, and keep Markdown canonical.
+Resolve output mode as: explicit user request for Markdown-only -> otherwise `dual`. `.aw_docs/config.json` and `AW_DOCS_OUTPUT_MODE` may request `dual` or `html`, but must not silently suppress required SDLC HTML sidecars.
+
+Write each planning companion beside its canonical source: `prd.md` -> `prd.html`, `design.md` -> `design.html`, `spec.md` -> `spec.html`, and `tasks.md` -> `tasks.html`.
+Choose the smallest correct profile for the dominant planning output:
+
+- `prd` for product requirements
+- `technical-spec` for technical `spec.md` or architecture-heavy `design.md`
+- `implementation-plan` for `tasks.md` or full planning packets
+- `impact-analysis-report` when the plan is primarily blast radius, impact, or tradeoff analysis
+
+Pass every canonical source path that shaped each companion, then record colocated sidecars in `state.json` `html_companion_artifacts` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
 
 ## Plan Document Template
 
@@ -347,6 +375,7 @@ Before ending the planning stage:
 6. check that file paths, type names, helper names, and commands stay consistent
 7. confirm behavior-changing slices use explicit `RED -> GREEN -> REFACTOR` wording or explicitly justify why test-first is not meaningful
 8. confirm the next stage can route directly to `/aw:build` and that execution mode plus review mode are clear when they can be known safely
+9. confirm every written planning Markdown artifact has a colocated HTML sidecar, or the user explicitly requested Markdown-only
 
 Treat this as the planning verification pass.
 If the plan cannot survive this self-review, it is not ready for execution handoff.
@@ -382,6 +411,7 @@ When `tasks.md` is ready:
 - assumptions or constraints that materially shape execution
 - planned save-point commit policy
 - parallel build policy and cap when parallel execution is planned
+- `html_companion_artifacts`
 - recommended next commands
 
 ## Final Output Shape
@@ -395,5 +425,6 @@ Always end with:
 - `Phases`
 - `Execution Readiness`
 - `Execution Mode`
+- `HTML Companion`
 - `Missing`
 - `Next`