aw-ecc 1.4.31 → 1.4.47

package/README.md

@@ -9,18 +9,18 @@
 The current catalog exposed by this repo is:
 
 - 28 agents
-- 158 skills
-- 69 commands
+- 173 skills
+- 72 commands
 
 ## Quick Start Snapshot
 
-Installing `aw-ecc` gives your workspace access to 28 agents, 158 skills, and 69 commands through the repo-local AW command surface plus GHL-specific skill and policy layers.
+Installing `aw-ecc` gives your workspace access to 28 agents, 173 skills, and 72 commands through the repo-local AW command surface plus GHL-specific skill and policy layers.
 
 | Surface | Availability |
 | --- | --- |
 | Agents | ✅ 28 agents |
-| Skills | ✅ 158 skills |
-| Commands | ✅ 69 commands |
+| Skills | ✅ 173 skills |
+| Commands | ✅ 72 commands |
 
 These catalog counts are validated in CI so the published docs stay aligned with the repo contents.
 

package/commands/adk.md

@@ -0,0 +1,52 @@
+---
+name: aw:adk
+description: "Agent Development Kit — create, improve, fix, delete, score, comply, audit, or health-check any CASRE artifact (Command, Agent, Skill, Rule, Eval). Use /aw:adk to author registry content."
+argument-hint: "[type] [mode] [target] — e.g., 'agent create', 'skill score my-skill', 'rule audit all', 'agent delete my-agent'"
+status: active
+stage: build
+internal_skill: aw-adk
+---
+
+# ADK — Agent Development Kit
+
+Use `/aw:adk` to author, score, fix, delete, or audit any artifact in the AW registry.
+
+## Usage
+
+```
+/aw:adk                          → interactive: ask type, then mode
+/aw:adk agent create             → create a new agent (guided)
+/aw:adk skill improve my-skill   → enrich an existing skill
+/aw:adk agent fix my-agent       → resolve lint failures
+/aw:adk skill score my-skill     → score against rubric
+/aw:adk rule audit all           → audit all rules
+/aw:adk eval create my-agent     → create evals for existing agent
+/aw:adk agent delete my-agent    → remove agent + evals + clean references
+```
+
+## Arguments
+
+| Position | Values | Default |
+|---|---|---|
+| type | `command` · `agent` · `skill` · `rule` · `eval` | interactive (ask) |
+| mode | `create` · `improve` · `fix` · `delete` · `score` · `comply` · `audit` · `health` | interactive (ask) |
+| target | artifact name or `all` (for audit/health) | interactive (ask) |
+
+## Execution
+
+**Step 1: Read the skill file.** Open and read `~/.aw-ecc/skills/aw-adk/SKILL.md` before doing anything else. Do not skip this — the skill contains the full flow, templates, rubrics, and scripts. All reference files are relative to that skill directory.
+
+**Step 2: Follow the create flow steps in order.** Every type (command, agent, skill, rule, eval) goes through the same pipeline. Here are the steps you must not skip:
+
+1. CLASSIFY → 2. INTERVIEW → 3. RESOLVE PATH → 4. SCAFFOLD → 5. CHECKPOINT (output remaining steps to user) → 6. LINT → 7. SCORE → 8. EVAL GATE (2+ evals) → 9. TEST RUNS → 10. ITERATE → 11. DESCRIPTION OPT → 12. CROSS-IDE → 13. REGISTRY UPDATES → 14. SYNC
+
+If you find yourself writing the artifact and then jumping to "done" — you skipped steps 5-14. Go back.
+
+## When No Arguments
+
+If invoked without arguments, ask the user:
+1. What type of artifact? (with the quick classifier table from the skill)
+2. What mode? (with brief descriptions of each)
+3. What target? (name or path)
+
+Then proceed with the skill's flow for that combination.

package/commands/build.md

@@ -42,6 +42,16 @@ Implement approved work in thin, reversible slices, continue until the approved
 - tests or validation changes where applicable
 - `.aw_docs/features/<feature_slug>/execution.md`
 - updated `.aw_docs/features/<feature_slug>/state.json`
+- `.aw_docs/features/<feature_slug>/execution.html` when docs output mode is `dual` or `html`
+
+## Human HTML Companion
+
+Markdown `execution.md` remains canonical for agents.
+When `/aw:build` writes or materially updates execution evidence, delegate to the `aw:echo` subagent with the `implementation-plan` profile. Markdown-only is allowed only when the user explicitly requests it for this run.
+Subagent authorization: invoking `/aw:build` in `dual` or `html` output mode is an explicit user request to delegate the human-facing HTML companion to exactly one background `aw:echo` subagent. This authorization is scoped only to HTML companion generation; do not spawn unrelated subagents.
+HTML sidecars are required before the final handoff. Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar 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, record `generated_fallback` with the blocker, and keep Markdown canonical.
+
+Record `html_companion_artifacts` in `state.json` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
 
 ## Execution Rules
 
@@ -51,15 +61,17 @@ Implement approved work in thin, reversible slices, continue until the approved
 4. Default to sequential execution unless the approved plan marks disjoint `parallel_candidate` slices with explicit write scopes.
 5. If parallel fan-out is approved, respect the plan’s `max_parallel_subagents` cap, defaulting to `3` when no stricter or larger value is justified.
 6. Break non-trivial work into thin, rollback-friendly slices or bounded parallel waves.
-7. Validate each slice or completed wave before expanding scope.
-8. Keep moving through approved slices until the current build scope is complete or explicitly blocked.
-9. For bug work, require a failing signal or reproduction before broad fixes.
-10. For frontend work, inherit HighRise, accessibility, responsive, and runtime-verification expectations.
-11. Record what changed, what remains, whether execution stayed sequential or ran in bounded parallel waves, and what was intentionally not touched.
-12. If the approved tasks are phased, record each completed phase and name the next phase before handoff.
-13. Create save-point commits for meaningful completed slices.
-14. If a proposed slice cannot support a clean save-point commit, treat that as a slicing problem instead of normalizing a no-commit checkpoint.
-15. Hand off to `/aw:test` or `/aw:review` with the exact next command instead of claiming readiness without evidence.
+7. For each slice that changes observable behavior, load `tdd-workflow` and follow RED-GREEN-REFACTOR; use the `tdd` companion skill when deeper behavior-test, mocking, or tracer-bullet guidance is needed.
+8. Validate each slice or completed wave before expanding scope.
+9. Keep moving through approved slices until the current build scope is complete or explicitly blocked.
+10. For bug work, require a failing signal or reproduction before broad fixes.
+11. For frontend work, inherit HighRise, accessibility, responsive, and runtime-verification expectations.
+12. Record what changed, what remains, whether execution stayed sequential or ran in bounded parallel waves, and what was intentionally not touched.
+13. If the approved tasks are phased, record each completed phase and name the next phase before handoff.
+14. Create save-point commits for meaningful completed slices.
+15. If a proposed slice cannot support a clean save-point commit, treat that as a slicing problem instead of normalizing a no-commit checkpoint.
+16. Hand off to `/aw:test` or `/aw:review` with the exact next command instead of claiming readiness without evidence.
+17. Generate or explicitly record the HTML companion status before handoff.
 
 ## Must Not Do
 
@@ -87,5 +99,6 @@ Always end with:
 - `Changes`
 - `Validation`
 - `Save Points`
+- `HTML Companion`
 - `Blockers`
 - `Next`

package/commands/deploy.md

@@ -35,6 +35,7 @@ Perform one explicit release action with the correct GHL provider and mechanism
 
 - `.aw_docs/features/<feature_slug>/release.md`
 - updated `.aw_docs/features/<feature_slug>/state.json`
+- `.aw_docs/features/<feature_slug>/release.html` when docs output mode is `dual` or `html`
 - one concrete release outcome artifact:
   - PR URL
   - branch name
@@ -43,6 +44,15 @@ Perform one explicit release action with the correct GHL provider and mechanism
   - build links
   - status summary
 
+## Human HTML Companion
+
+Markdown `release.md` remains canonical for agents.
+When `/aw:deploy` writes or materially updates release evidence, delegate to the `aw:echo` subagent with the `release-report` profile. Markdown-only is allowed only when the user explicitly requests it for this run.
+Subagent authorization: invoking `/aw:deploy` in `dual` or `html` output mode is an explicit user request to delegate the human-facing HTML companion to exactly one background `aw:echo` subagent. This authorization is scoped only to HTML companion generation; do not spawn unrelated subagents.
+HTML sidecars are required before the final handoff. Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar 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, record `generated_fallback` with the blocker, and keep Markdown canonical.
+
+Record `html_companion_artifacts` in `state.json` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
+
 ## Deploy Rules
 
 1. Do one release action at a time.
@@ -50,6 +60,7 @@ Perform one explicit release action with the correct GHL provider and mechanism
 3. Finish the selected release action for the chosen mode or record the blocker explicitly.
 4. Record deterministic evidence even when external execution is blocked.
 5. Hand off to `/aw:ship` when launch, rollout, rollback readiness, or release closeout is requested after deploy.
+6. Generate or explicitly record the HTML companion status before handoff.
 
 ## Must Not Do
 
@@ -72,4 +83,5 @@ Always end with:
 - `Execution Evidence`
 - `Rollback Path`
 - `Outcome`
+- `HTML Companion`
 - `Next`

package/commands/execute.md

@@ -29,6 +29,14 @@ This entrypoint inherits the same rule that build should finish the approved bui
 - implementation changes
 - `.aw_docs/features/<feature_slug>/execution.md`
 - updated `.aw_docs/features/<feature_slug>/state.json`
+- `.aw_docs/features/<feature_slug>/execution.html` when the routed `/aw:build` stage writes an HTML companion
+
+## Human HTML Companion
+
+`/aw:execute` inherits the `/aw:build` HTML companion contract.
+Markdown remains canonical for agents, and the `aw:echo` subagent produces the human review companion when output mode is `dual` or `html`.
+Subagent authorization: invoking `/aw:execute` in `dual` or `html` output mode is an explicit user request to delegate the human-facing HTML companion to exactly one background `aw:echo` subagent. This authorization is scoped only to HTML companion generation; do not spawn unrelated subagents.
+HTML sidecars are required before the final handoff. Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar 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, record `generated_fallback` with the blocker, and keep Markdown canonical.
 
 ## Must Not Do
 
@@ -48,4 +56,5 @@ Always end with:
 - `Canonical Stage`
 - `Changes`
 - `Validation`
+- `HTML Companion`
 - `Next`

package/commands/feature.md

@@ -0,0 +1,333 @@
+---
+name: aw:feature
+description: Guided phase-by-phase feature development — from repo setup to production deployment. PM-friendly, pauses at each phase for user input.
+argument-hint: "<feature description, ticket URL, or screenshot>"
+status: active
+stage: feature
+internal_skill: aw-feature
+---
+
+# Feature — Guided SDLC Workflow
+
+## Your first response
+
+When this command is invoked, your entire first response is the roadmap below — nothing else. Do not start any phase, do not create files, do not write code, do not plan. Just show the roadmap and ask where to start.
+
+Feature context (for reference, not for acting on yet): $ARGUMENTS
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ⟁ AW ► FEATURE WORKFLOW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Feature: <feature title derived from $ARGUMENTS>
+
+You'll go through these phases:
+
+ SETUP & CONTEXT
+  1.  Repo Setup .............. Clone/identify repo from screenshot or URL
+  2.  Codebase Onboarding ..... Understand architecture and conventions
+
+ PLANNING
+  3.  Requirements ............ Gather and confirm acceptance criteria
+  4.  PRD ..................... Write product requirements document
+  5.  Design .................. Explore design options, make decisions
+  6.  Technical Spec .......... Architecture, API impact, data model
+  7.  Task Breakdown .......... Implementation tasks in phased order
+
+ IMPLEMENTATION
+  8.  Build ................... Implement in thin, reversible slices
+  9.  Tests ................... Write and run tests
+  10. Self-Review ............. Code quality and correctness review
+
+ HARDENING
+  11. Debug & Fix ............. Fix issues found in review/tests
+  12. Docs & i18n ............. Documentation and translation strings
+  13. Platform Specialists .... Security, performance, accessibility reviews
+  14. Setup Audit ............. Verify lint, types, build, tests all pass
+
+ RELEASE
+  15. PR Creation ............. Create pull request with summary
+  16. PR Checks & Fixes ....... Auto-detect and fix CI warnings
+  17. Staging Deploy .......... Deploy to staging, get staging link
+  18. Production & Closeout ... Production deploy and release notes
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+You can say:
+  "next"          → proceed to the next phase
+  "skip"          → skip current phase (I'll ask why)
+  "phase <N>"     → jump to a specific phase
+  "status"        → see progress tracker
+  "refine"        → redo or adjust current phase
+  "back to <N>"   → revisit a completed phase
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Along with the roadmap, mention which phases you'd auto-skip (e.g., "You're already in a repo so we'd skip Phase 1") and suggest a starting phase. Then ask the user: "Ready to begin at Phase N, or would you like to start somewhere else?"
+
+Wait for the user to respond before doing anything.
+
+## Smart Entry Detection
+
+When scanning for auto-skips, check these signals:
+
+| Signal | Action |
+|---|---|
+| Already inside a git repo | Skip Phase 1 |
+| Onboarding artifact exists | Skip Phase 2 |
+| `.aw_docs/features/<slug>/prd.md` exists | Skip Phases 3-4 |
+| `.aw_docs/features/<slug>/spec.md` exists | Skip Phase 6 |
+| `.aw_docs/features/<slug>/tasks.md` exists | Skip Phase 7 |
+| Implementation code exists for this feature | Suggest Phase 9 or later, **ask the user** |
+| PR already exists | Suggest Phase 16, **ask the user** |
+
+Always announce every skip in the roadmap response. Never silently skip.
+
+## Role
+
+You are a guide walking the user through 18 SDLC phases. At each phase you explain what's happening, delegate to the appropriate skill, and pause for user input before moving on. This is not autonomous — the user drives the pace.
+
+## Modes
+
+| Mode | Use when | Behavior |
+|---|---|---|
+| `full` | Starting a new feature from scratch | Show roadmap, begin at Phase 1 |
+| `resume` | Continuing a previously started feature | Read state.json, resume from last incomplete phase |
+| `status` | User wants to see progress | Show progress tracker only |
+
+## Phase Execution Pattern
+
+For **every** phase, follow this exact pattern:
+
+### 1. Announce the Phase
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Phase <N>/18: <Phase Name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+<One plain-language sentence explaining what this phase does and why it matters.>
+```
+
+### 2. Execute the Phase
+Load the backing skill and execute. See the Phase Definitions table below for which skill each phase delegates to.
+
+### 3. Show What Was Produced
+```
+✓ Phase <N> complete.
+  Produced: <list of artifacts or outcomes>
+```
+
+When a phase delegates to an AW stage that writes a canonical Markdown artifact, include the generated `.aw_docs/features/<feature_slug>/<artifact_basename>.html` companion in the produced list. Markdown-only is allowed only when the user explicitly requests it for this run.
+
+### 4. Pause and Ask
+```
+► Ready for Phase <N+1> (<Next Phase Name>)?
+  Say "next" to proceed, "refine" to adjust, or "skip" to skip it.
+```
+
+**Never proceed without user input.** Wait for the user to say "next", "skip", "refine", "phase N", or give other direction.
+
+## Phase Definitions
+
+| # | Phase | Delegates to | Skills loaded | Hard gate? |
+|---|---|---|---|---|
+| 1 | Repo Setup | direct skill invocation | `local-ghl-setup-from-screenshot` | No |
+| 2 | Codebase Onboarding | direct skill invocation | `codebase-onboarding` | No |
+| 3 | Requirements | `aw-plan` (product mode) | `aw-plan` | No |
+| 4 | PRD | `aw-plan` (product mode) | `aw-plan` | No |
+| 5 | Design | `aw-design` | `aw-design` | No |
+| 6 | Technical Spec | `aw-plan` (technical mode) | `aw-plan` | No |
+| 7 | Task Breakdown | `aw-plan` (tasks mode) | `aw-plan` | No |
+| 8 | Build | `aw-build` (code mode) | `aw-build`, `incremental-implementation` | No |
+| 9 | Tests | `aw-test` (feature mode) | `aw-test`, `tdd-workflow` | No |
+| 10 | Self-Review | `aw-review` (findings mode) | `aw-review` | No |
+| 11 | Debug & Fix | `aw-investigate` + `aw-build` | `aw-investigate`, `aw-build` | No |
+| 12 | Docs & i18n | `aw-build` (docs mode) | `aw-build` | No |
+| 13 | Platform Specialists | `aw-review` (governance mode) | `aw-review`, `using-platform-skills` | No |
+| 14 | Setup Audit | `aw-test` (release mode) | `aw-test`, `verification-loop` | **Yes** — must pass before Phase 15 |
+| 15 | PR Creation | `aw-deploy` (pr mode) | `aw-deploy` | No |
+| 16 | PR Checks & Fixes | `aw-build` + `aw-review` | `aw-build`, `aw-review` | **Yes** — auto-runs, auto-fixes |
+| 17 | Staging Deploy | `aw-deploy` (staging mode) | `aw-deploy` | No |
+| 18 | Production & Closeout | `aw-ship` | `aw-ship` | No |
+
+## Phase-Specific Behavior
+
+### Phase 1: Repo Setup
+If the user provides a screenshot, load and execute `local-ghl-setup-from-screenshot`.
+If the user provides a repo URL or name, clone it.
+If already in a repo, auto-skip with announcement.
+
+### Phase 3 & 4: Requirements + PRD
+Phase 3 is a **conversation** — your job is to understand the feature by talking to the user, not by guessing.
+
+Think of yourself as a product manager sitting down with a stakeholder. You ask about scope, users, success criteria, edge cases, and constraints. You listen to the answers. You follow up on anything that's vague or missing. You keep the conversation going until you genuinely understand what needs to be built and how you'd know it's done. Only then do you write up `requirements.md`.
+
+Phase 4 takes Phase 3 outputs and writes the PRD document.
+These are separate because PMs often know what they want but need help structuring it.
+
+### Phase 5: Design
+Load and execute `aw-design`. It handles feature type detection (frontend/full-stack/backend-only), generates HTML prototypes using the Highrise design system, and uses Stitch MCP when available. For backend-only features, it suggests skipping.
+
+### Phase 8: Build
+This is typically the longest phase. Use `incremental-implementation` to break into thin slices.
+After each meaningful slice, show progress and ask if the user wants to continue or pause.
+
+### Phase 11: Debug & Fix
+Only enters this phase if Phase 9 (Tests) or Phase 10 (Self-Review) found issues.
+If no issues were found, auto-skip with announcement:
+```
+○ Skipping Phase 11 (Debug & Fix) — no issues found in tests or review.
+```
+
+### Phase 14: Setup Audit (Hard Gate)
+This is a **hard gate** — it must pass before PR creation.
+Run: lint, type check, build, and test suite.
+If any fail, fix them within this phase before proceeding.
+```
+⚠ Setup Audit found 3 issues. Fixing before we can create the PR...
+```
+
+### Phase 16: PR Checks & Fixes (Automatic)
+After PR creation, this phase runs a **three-step sequence automatically**:
+
+**Step 1: Merge Conflict Detection & Resolution**
+```bash
+git fetch origin main && git merge origin/main --no-commit --no-ff
+```
+- If merge conflicts exist, identify conflicting files, resolve them intelligently (understanding both sides of the conflict), and commit the resolution.
+- If the target branch is not `main`, detect the correct base branch from the PR.
+- Show every conflict and its resolution to the user:
+```
+◆ Checking for merge conflicts with main...
+  ⚠ Found 3 merge conflicts:
+    → src/components/ExportButton.vue — resolved (kept our new component + their import reorder)
+    → src/utils/helpers.ts — resolved (merged both additions)
+    → package.json — resolved (kept both dependency additions)
+  → Committed merge resolution.
+```
+
+**Step 2: CI / Lint / Type Fixes**
+Check PR status (CI checks, lint warnings, type errors). Fix automatically:
+```
+◆ Checking CI status...
+  → Fixed 2 lint warnings in src/components/ExportButton.vue
+  → Fixed 1 type error in src/utils/export.ts
+  → Pushed fixes to PR branch.
+```
+
+**Step 3: Final Verification**
+Re-run `git status`, confirm PR is clean, no remaining conflicts or failing checks.
+```
+✓ PR is clean — no conflicts, no warnings, all checks passing.
+```
+
+If any fix requires a **design decision** (e.g., conflicting business logic, not just formatting), pause and ask the user instead of guessing.
+
+## Progress Tracker
+
+When the user says "status" or at phase boundaries, show:
+
+```
+Feature: <feature-title>
+[============..........................] Phase 5/18
+
+  1.  Repo Setup .............. ✓ DONE
+  2.  Codebase Onboarding ..... ✓ DONE
+  3.  Requirements ............ ✓ DONE
+  4.  PRD ..................... ✓ DONE
+  5.  Design .................. ► IN PROGRESS  <--
+  6.  Technical Spec .......... ○ PENDING
+  7.  Task Breakdown .......... ○ PENDING
+  8.  Build ................... ○ PENDING
+  9.  Tests ................... ○ PENDING
+  10. Self-Review ............. ○ PENDING
+  11. Debug & Fix ............. ○ PENDING
+  12. Docs & i18n ............. ○ PENDING
+  13. Platform Specialists .... ○ PENDING
+  14. Setup Audit ............. ○ PENDING
+  15. PR Creation ............. ○ PENDING
+  16. PR Checks & Fixes ....... ○ PENDING
+  17. Staging Deploy .......... ○ PENDING
+  18. Production & Closeout ... ○ PENDING
+```
+
+Status symbols: `✓` done, `►` in progress, `○` pending, `⊘` skipped
+
+## State Persistence (MANDATORY)
+
+**You MUST update state.json at every phase boundary.** This is non-negotiable — it is the only way to resume across sessions. If you forget, the user loses all progress on session restart.
+
+File: `.aw_docs/features/<feature-slug>/state.json`
+
+**Update trigger:** Immediately after showing the phase completion message (`✓ Phase <N> complete`), before the pause prompt.
+
+**Format — keep it minimal** (do not add extra fields):
+```json
+{
+  "feature_slug": "<slug>",
+  "feature_title": "<title>",
+  "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"`
+
+**On resume:** Read this file, show progress tracker, and resume from the first non-done phase.
+
+## 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`.
+Subagent authorization: invoking `/aw:feature` in `dual` or `html` output mode is an explicit user request to delegate each human-facing HTML companion to exactly one background `aw:echo` subagent per artifact-producing phase. This authorization is scoped only to HTML companion generation; do not spawn unrelated subagents.
+HTML sidecars are required before each artifact-producing phase handoff. Spawn exactly one `aw:echo` subagent for the phase companion and wait for the colocated `.html` sidecar 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, record `generated_fallback` with the blocker, and keep Markdown canonical.
+
+## Skipping Rules
+
+| Skip type | Behavior |
+|---|---|
+| **Auto-skip** (nonsensical phase) | Announce and skip — e.g., already in repo, no UI to design |
+| **User-requested skip** | Ask for a one-line reason, log it, proceed |
+| **Hard-gate phase** (14, 16) | Cannot be skipped — must pass |
+
+When auto-skipping:
+```
+○ Skipping Phase <N> (<Name>) — <reason>.
+```
+
+When user requests skip:
+```
+> Skipping Phase <N> (<Name>).
+  Quick note: why are we skipping this? (Helps me adjust later phases.)
+```
+
+## Hard Gates
+
+- **Phase 14 (Setup Audit)** must pass before Phase 15 (PR Creation)
+- **Phase 16 (PR Checks & Fixes)** runs automatically after PR creation — cannot be skipped
+
+## Must Not Do
+
+- Must not auto-advance between phases without user input
+- Must not skip phases silently — always announce skips with reasons
+- Must not duplicate the workflow logic of backing skills (delegate, don't reimplement)
+- Must not run all phases in one shot like `aw-yolo` — this is guided, not autonomous
+- Must not show technical jargon without a plain-language explanation
+
+## Final Output Shape
+
+At each phase boundary:
+- `Phase`: current phase number and name
+- `Status`: what was produced or decided
+- `Progress`: X/18 phases complete
+- `HTML Companion`: generated path when the phase produced a stage artifact, or explicit Markdown-only skip
+- `Next`: what the next phase is and what it does
+- `Prompt`: ask user to proceed, refine, or skip

package/commands/investigate.md

@@ -28,17 +28,29 @@ Turn vague breakage into a concrete reproduction, localized fault surface, and n
 
 - `.aw_docs/features/<feature_slug>/investigation.md`
 - updated `.aw_docs/features/<feature_slug>/state.json`
+- `.aw_docs/features/<feature_slug>/investigation.html` when docs output mode is `dual` or `html`
 - reproduction, expected-vs-actual, hypothesis, and next probe or build handoff
 
+## Human HTML Companion
+
+Markdown `investigation.md` remains canonical for agents.
+When `/aw:investigate` writes or materially updates investigation evidence, delegate to the `aw:echo` subagent with the `investigation-report` profile. Markdown-only is allowed only when the user explicitly requests it for this run.
+Subagent authorization: invoking `/aw:investigate` in `dual` or `html` output mode is an explicit user request to delegate the human-facing HTML companion to exactly one background `aw:echo` subagent. This authorization is scoped only to HTML companion generation; do not spawn unrelated subagents.
+HTML sidecars are required before the final handoff. Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar 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, record `generated_fallback` with the blocker, and keep Markdown canonical.
+
+Record `html_companion_artifacts` in `state.json` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
+
 ## Investigation Rules
 
 1. Reproduce first.
 2. Capture expected vs actual behavior.
-3. Use the smallest confirming probe before patching.
-4. Load org-standard observability and platform playbooks when the baseline requires them.
-5. For frontend issues, include runtime and responsive evidence when relevant.
-6. Name the exact next probe or next command before stopping.
-7. Do not broaden into implementation until the fault surface is concrete enough.
+3. Load `diagnose` for unclear bugs, regressions, performance problems, repeated failed fixes, or any case where a reliable feedback loop is not already established.
+4. Use the smallest confirming probe before patching.
+5. Load org-standard observability and platform playbooks when the baseline requires them.
+6. For frontend issues, include runtime and responsive evidence when relevant.
+7. Name the exact next probe or next command before stopping.
+8. Do not broaden into implementation until the fault surface is concrete enough.
+9. Generate or explicitly record the HTML companion status before handoff.
 
 ## Must Not Do
 
@@ -60,4 +72,5 @@ Always end with:
 - `Expected vs Actual`
 - `Evidence`
 - `Likely Fault Surface`
+- `HTML Companion`
 - `Next`

package/commands/plan.md

@@ -52,19 +52,32 @@ Turn an idea, requirement, approved design, or technical request into the minimu
   - `designs/`
   - `spec.md`
   - `tasks.md`
+- colocated HTML sidecars beside generated planning artifacts, for example `prd.html`, `design.html`, `spec.html`, and `tasks.html`, when docs output mode is `dual` or `html`
+
+## Human HTML Companion
+
+Markdown artifacts remain canonical for agents.
+When `/aw:plan` writes or materially updates planning artifacts, delegate to the `aw:echo` subagent to produce the TeamOfOne-readable companion. Markdown-only is allowed only when the user explicitly requests it for this run.
+Subagent authorization: invoking `/aw:plan` in `dual` or `html` output mode is an explicit user request to delegate the human-facing HTML companion to exactly one background `aw:echo` subagent. This authorization is scoped only to HTML companion generation; do not spawn unrelated subagents.
+HTML sidecars are required before the final handoff. Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar 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, record `generated_fallback` with the blocker, and keep Markdown canonical.
+
+Record `html_companion_artifacts` in `state.json` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
 
 ## Execution Rules
 
 1. Classify the request into one primary mode first.
-2. Operate in read-only planning mode until the artifacts are written.
-3. Default to single-scope planning.
-4. If the request is fuzzy, discovery-heavy, or too large for one spec, route internally through `aw-brainstorm` before technical planning.
-5. Use existing artifacts as inputs when they are already sufficient.
-6. Route approved technical direction through `aw-spec` before task planning.
-7. Route approved specs through `aw-tasks` when execution-ready tasks are missing or stale.
-8. Do not require a PRD for a technical request that is already well defined.
-9. When writing technical or task artifacts, make them concrete enough for build to proceed without re-planning file scope, validation, and task order.
-10. When writing `tasks.md`, always include an explicit `## Spec Brief` section and organize the work into explicit phases.
+2. Use `grill-with-docs` when the request is fuzzy, high-impact, domain-language-heavy, or likely to hide edge cases; do not make it a blanket blocker for small or already-clear plans.
+3. Use `to-prd` only when product scope must be frozen (`product` or `full` mode, or missing product assumptions); do not require a PRD for a technical request that is already well defined.
+4. Use `to-issues` before `tasks.md` when the work needs a vertical-slice breakdown; feed those slices into `aw-tasks` rather than publishing tracker issues by default.
+5. Operate in read-only planning mode until the artifacts are written.
+6. Default to single-scope planning.
+7. If the request is fuzzy, discovery-heavy, or too large for one spec, route internally through `aw-brainstorm` before technical planning.
+8. Use existing artifacts as inputs when they are already sufficient.
+9. Route approved technical direction through `aw-spec` before task planning.
+10. Route approved specs through `aw-tasks` when execution-ready tasks are missing or stale.
+11. When writing technical or task artifacts, make them concrete enough for build to proceed without re-planning file scope, validation, and task order.
+12. When writing `tasks.md`, always include an explicit `## Spec Brief` section and organize the work into explicit phases.
+13. Generate or explicitly record the HTML companion status before handoff.
 
 ## Planning Depth
 
@@ -126,5 +139,6 @@ Always end with:
 - `Phases`
 - `Summary`
 - `Execution Readiness`
+- `HTML Companion`
 - `Missing`
 - `Next`