aw-ecc 1.4.32 → 1.4.48

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`

package/commands/publish.md

@@ -0,0 +1,65 @@
+---
+name: aw:publish
+description: "Publish locally created/modified CASRE artifacts to the remote platform-docs registry via PR. Intent-based — triggers on 'push', 'publish', 'sync to registry', 'send upstream'. Always confirms before pushing."
+argument-hint: "[path] [--dry-run] — e.g., '.aw_registry/platform/data/', '--dry-run', 'rules'"
+status: active
+stage: deploy
+internal_skill: aw-publish
+---
+
+# Publish — Registry Push
+
+Push local registry artifacts to the remote platform-docs registry via PR.
+
+## Usage
+
+```
+/aw:publish                                    → auto-detect all changes, dry-run first
+/aw:publish .aw_registry/platform/data/        → push changes in a namespace
+/aw:publish .aw_registry/platform/data/agents/my-agent.md → push one file
+/aw:publish --dry-run                          → preview only, no push
+/aw:publish rules                              → push platform rules (.aw_rules/)
+```
+
+## Natural Language (no command needed)
+
+You don't need to type `/aw:publish` — the LLM detects intent automatically when the context is about **registry artifacts** (.aw_registry/ or .aw_rules/):
+
+- "push this agent to the registry"
+- "publish my registry changes"
+- "sync platform/data to platform-docs"
+- "I'm done testing this skill, publish it"
+- "what would get pushed to the registry?"
+- "push the rules"
+
+**Note:** Regular git push, code PRs, and deploys do NOT trigger this skill.
+
+## Arguments
+
+| Argument | Values | Default |
+|---|---|---|
+| path | `.aw_registry/...` path, namespace folder, or `rules` | auto-detect all changes |
+| `--dry-run` | flag | off (but skill always does dry-run first as confirmation) |
+| `--repo` | override target repository | `GoHighLevel/platform-docs` |
+
+## Execution
+
+**Step 1: Read the skill file.** Open and read `skills/aw-publish/SKILL.md` before doing anything else.
+
+**Step 2: Follow the confirmation gate.** Every publish must:
+1. Run `aw push --dry-run` to preview changes
+2. Show the user what will be pushed
+3. Ask "Do you want to publish?"
+4. Only push after explicit user confirmation
+
+**Step 3: Choose the right command.**
+- Registry artifacts (agents, skills, commands, evals, references) → `aw push`
+- Platform rules (.aw_rules/) → `aw push-rules`
+- Never combine both in one action
+
+## When No Arguments
+
+If invoked without arguments:
+1. Run `aw push --dry-run` to see all pending changes
+2. If rules changes detected, mention them and suggest `aw push-rules` separately
+3. Show the full list and ask for confirmation

package/commands/review.md

@@ -28,8 +28,18 @@ This stage may request or rerun targeted tests when existing evidence is stale,
 
 - `.aw_docs/features/<feature_slug>/verification.md`
 - updated `.aw_docs/features/<feature_slug>/state.json`
+- `.aw_docs/features/<feature_slug>/verification.html` when docs output mode is `dual` or `html`
 - explicit overall status: `PASS`, `PASS_WITH_NOTES`, or `FAIL`
 
+## Human HTML Companion
+
+Markdown `verification.md` remains canonical for agents.
+When `/aw:review` writes or materially updates findings, governance, or readiness evidence, delegate to the `aw:echo` subagent with the `pr-one-pager` profile. Markdown-only is allowed only when the user explicitly requests it for this run.
+Subagent authorization: invoking `/aw:review` 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.
+
 ## Review Rules
 
 1. Review tests and validation evidence first.
@@ -39,6 +49,7 @@ This stage may request or rerun targeted tests when existing evidence is stale,
 5. Continue until the requested findings, governance, and readiness scope is covered or explicitly blocked.
 6. Route back to `/aw:build` when repair is needed.
 7. Do not clear findings on stale evidence.
+8. Generate or explicitly record the HTML companion status before handoff.
 
 ## Must Not Do
 
@@ -61,4 +72,5 @@ Always end with:
 - `Governance`
 - `Readiness`
 - `Outcome`
+- `HTML Companion`
 - `Next`

package/commands/ship.md

@@ -34,8 +34,18 @@ Confirm the release is ready to launch, roll it out safely, document rollback re
 
 - `.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`
 - launch recommendation, rollout checkpoints, rollback path, and closeout notes
 
+## Human HTML Companion
+
+Markdown `release.md` remains canonical for agents.
+When `/aw:ship` writes or materially updates launch, rollout, rollback, or closeout 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:ship` 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.
+
 ## Shipping Rules
 
 1. Treat rollout safety as its own stage.
@@ -45,6 +55,7 @@ Confirm the release is ready to launch, roll it out safely, document rollback re
 5. Capture post-deploy evidence, monitoring links, and known risks.
 6. For frontend releases, include versioned entry, smoke, and accessibility or design-signoff notes when relevant.
 7. Do not use `ship` as a synonym for composite orchestration.
+8. Generate or explicitly record the HTML companion status before handoff.
 
 ## Internal Phase Routing
 
@@ -74,4 +85,5 @@ Always end with:
 - `Rollback Path`
 - `Evidence`
 - `Outcome`
+- `HTML Companion`
 - `Next`

package/commands/test.md

@@ -28,8 +28,18 @@ Run the smallest correct QA scope for the requested feature, fix, or release and
 
 - `.aw_docs/features/<feature_slug>/verification.md`
 - updated `.aw_docs/features/<feature_slug>/state.json`
+- `.aw_docs/features/<feature_slug>/verification.html` when docs output mode is `dual` or `html`
 - fresh evidence for local validation, E2E, external validation, or targeted runtime checks
 
+## Human HTML Companion
+
+Markdown `verification.md` remains canonical for agents.
+When `/aw:test` writes or materially updates QA evidence, delegate to the `aw:echo` subagent with the `verification-report` profile. Markdown-only is allowed only when the user explicitly requests it for this run.
+Subagent authorization: invoking `/aw:test` 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.
+
 ## QA Rules
 
 1. Select the smallest correct test scope, not the loudest available suite.
@@ -39,6 +49,7 @@ Run the smallest correct QA scope for the requested feature, fix, or release and
 5. Continue until the requested QA scope is covered or explicitly blocked.
 6. Mark unavailable checks as unavailable instead of inventing a pass.
 7. Hand off to `/aw:review` when findings, governance, or readiness still need a decision.
+8. Generate or explicitly record the HTML companion status before handoff.
 
 ## Must Not Do
 
@@ -61,4 +72,5 @@ Always end with:
 - `Evidence`
 - `Failures`
 - `Unavailable`
+- `HTML Companion`
 - `Next`