aw-ecc 1.4.23 → 1.4.25

package/.cursor/skills/aw-ship/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: aw-ship
+description: Launch, rollout, rollback readiness, and release closeout skill for work that already has the required build, test, review, and deploy context.
+trigger: User requests launch readiness, rollout management, or release closeout after deploy or during final release preparation.
+---
+
+# AW Ship
+
+## Overview
+
+`aw-ship` is now the shipping stage, not the composite "do everything" workflow.
+It owns launch safety, rollback readiness, monitoring posture, and release closeout.
+
+## When to Use
+
+- launch readiness is the goal
+- rollout checkpoints and monitoring need to be named
+- the release action already happened and needs closeout
+- rollback confidence must be documented before claiming readiness
+
+Do not use for end-to-end orchestration.
+That belongs to `aw-yolo`.
+
+## Preparation Gate
+
+Before risky shipping work, call `aw-prepare` as the internal preparation gate when any of these are unclear:
+
+- release context
+- artifact readiness
+- workspace isolation or repo cleanliness
+- whether the current request is really shipping versus deploy or review
+
+Do not guess through missing release inputs when `aw-prepare` should be used first.
+
+## Workflow
+
+1. Load the release context.
+   Start from deploy evidence, review status, known risks, and rollout intent.
+   If release inputs or workspace readiness are unclear, run the internal `aw-prepare` gate first instead of guessing.
+2. Apply the launch checklist.
+   Use `../../references/ship-launch-checklist.md`.
+   Load `ci-cd-and-automation` when release automation, staged rollout, or rollback machinery is part of the ship decision.
+3. Continue until the selected shipping scope is covered.
+   Do not stop after one checklist item, one smoke result, or one monitoring note if the requested launch-readiness, rollout, or closeout scope still has open gaps.
+4. Confirm rollback posture.
+   If rollback is unclear, do not claim launch readiness.
+5. Capture monitoring and follow-through.
+   Name health checks, monitoring links, smoke results, and ownership.
+   For release notes, runbooks, or durable decision capture, load `documentation-and-adrs`.
+6. Close out the release.
+   Update `release.md` and `state.json` with launch or blocker notes.
+
+## Completion Contract
+
+Shipping is complete only when one of these is true:
+
+- launch readiness, rollout, or closeout scope is covered clearly enough for operations
+- a launch blocker prevents safe shipping and that blocker is named clearly
+
+Every shipping handoff must make these things obvious:
+
+- the current launch readiness decision
+- the rollout or monitoring plan
+- the rollback path or rollback blocker
+- the operational evidence captured
+- which exact next command should run next, if any
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Deploy already proved we're safe to ship." | Execution success is not the same as rollout safety. |
+| "Rollback can be figured out later." | No rollback story means no real launch confidence. |
+| "Ship should still mean the whole pipeline." | Overloading ship is what made the old model confusing. |
+
+## Red Flags
+
+- no rollback plan or rollback blocker is named
+- no monitoring or smoke evidence exists for a risky release
+- ship is used as a synonym for end-to-end automation
+
+## State File
+
+`state.json` should record at least:
+
+- `feature_slug`
+- `stage: "ship"`
+- `mode`
+- `status`
+- written artifacts
+- launch readiness
+- rollout plan
+- rollback path
+- evidence captured
+- blockers
+- recommended next commands
+
+## Verification
+
+- [ ] launch checklist or blocker is explicit
+- [ ] rollback readiness is documented
+- [ ] monitoring and smoke expectations are named
+- [ ] `release.md` and `state.json` are updated with closeout evidence
+
+## Final Output Shape
+
+Always end with:
+
+- `Mode`
+- `Launch Readiness`
+- `Rollout Plan`
+- `Rollback Path`
+- `Evidence`
+- `Outcome`
+- `Next`

package/.cursor/skills/aw-spec/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: aw-spec
+description: Internal spec helper that turns an approved direction into a deterministic technical spec without writing implementation tasks or code.
+trigger: Internal only. Invoked by aw-plan after discovery is approved or when a technical contract must be written before task planning.
+---
+
+# AW Spec
+
+## Overview
+
+`aw-spec` owns the technical contract layer inside AW planning.
+It turns an approved direction into `.aw_docs/features/<feature_slug>/spec.md` without collapsing directly into implementation tasks or code.
+
+The public planning route remains `/aw:plan`.
+
+## When to Use
+
+- discovery or planning has already approved the direction
+- the request needs a technical contract before task breakdown
+- an existing spec is vague, incomplete, or inconsistent
+- the work spans interfaces, file boundaries, rollout concerns, or migration risk
+
+Do not use when execution-ready tasks already exist or when the request is still fundamentally a product or design question.
+
+## Workflow
+
+This legacy heading maps to the gated workflow below.
+
+## The Gated Workflow
+
+1. Enter technical planning mode.
+   Read the approved direction, relevant code paths, and the smallest set of architecture context needed.
+   Do not write code while authoring the spec.
+2. Check the scope shape.
+   If the request spans multiple independent subsystems, decompose it before writing one giant spec.
+3. Define the stable contract.
+   Name interfaces, boundaries, file responsibilities, rollout constraints, and failure modes.
+   Use `../../references/interface-stability.md` when an API or contract is changing.
+4. Write `spec.md` for a fresh planner or builder.
+   Make it specific enough that `aw-tasks` can proceed without rediscovering the architecture.
+5. Run a fast review pass.
+   Fix placeholders, contradictions, scope drift, and ambiguous names before handoff.
+6. Update state and hand off.
+   Update `.aw_docs/features/<feature_slug>/state.json` and hand the approved spec to `aw-tasks`.
+
+## Required `spec.md` Content
+
+Capture at least:
+
+- implementation goal
+- scope and non-goals
+- architecture or technical approach
+- interfaces, contracts, or integration points
+- expected file or module map when it can be inferred safely
+- failure modes and rollback constraints
+- acceptance criteria
+- verification targets
+- rollout, migration, or environment constraints when relevant
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The builder can figure the interfaces out." | Unstable interfaces are where rework and regressions start. |
+| "This is only one feature, so one large spec is fine." | Mixed subsystems still need decomposition if the boundaries differ. |
+| "I’ll leave the risky rollout details for later." | Migration and rollback constraints belong in the spec if they affect implementation. |
+
+## Red Flags
+
+- the spec says "update as needed" instead of naming boundaries
+- file or module responsibility is still vague
+- rollout or migration constraints are implied instead of stated
+- contradictory helper names, interface names, or paths appear across sections
+
+## Verification
+
+Before handoff, run this inline review:
+
+1. placeholder scan
+2. internal consistency check
+3. scope check
+4. ambiguity check
+
+Fix issues inline instead of carrying them into task planning.
+
+## Hard Gates
+
+- do not write implementation code
+- do not jump directly to `/aw:build`
+- do not create `tasks.md`
+- do not leave contradictory interfaces, names, or file boundaries unresolved
+- do not treat a multi-subsystem request as one spec when it should be decomposed
+
+## Final Output Shape
+
+Always end with:
+
+- `Feature Slug`
+- `Spec Path`
+- `Scope Decision`
+- `Architecture`
+- `Acceptance Criteria`
+- `Open Approval Needs`
+- `Recommended Next`

package/.cursor/skills/aw-tasks/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: aw-tasks
+description: Internal task helper that turns an approved spec into a recipe-level tasks.md artifact for aw-build.
+trigger: Internal only. Invoked by aw-plan after spec authoring or when an existing spec must be expanded into execution-ready tasks.
+---
+
+# AW Tasks
+
+## Overview
+
+`aw-tasks` owns `tasks.md`.
+It turns an approved technical contract into a fresh-worker execution recipe without adding a new public planning command.
+
+The canonical public route remains `/aw:plan`.
+
+## When to Use
+
+- an approved `spec.md` exists and work needs an execution recipe
+- execution scope is still too large or vague for a fresh builder
+- task ordering, checkpoints, or parallel boundaries are unclear
+
+Do not use when the request is still missing a stable technical contract.
+
+## Workflow
+
+This legacy heading maps to the detailed planning process below.
+
+## The Planning Process
+
+1. Enter task-planning mode.
+   Load `.aw_docs/features/<feature_slug>/spec.md` and only the supporting design or product artifacts that matter.
+   Do not write code during task authoring.
+2. Map the file structure first.
+   Name the exact files to create, modify, or verify before defining tasks.
+3. Break the work into vertical slices.
+   Prefer end-to-end slices and checkpointed phases over horizontal batches.
+   Use `../../references/task-sizing-and-checkpoints.md` when sizing gets fuzzy.
+4. Write tasks as fresh-worker instructions.
+   Include explicit file paths, commands, expected outcomes, commit boundaries, save-point commit expectations, phase ordering, and any bounded parallel execution metadata.
+5. Review the task list before handoff.
+   Remove placeholders, fix dependency drift, and confirm the steps are build-ready.
+6. Update state and hand off.
+   Update `.aw_docs/features/<feature_slug>/state.json` and recommend `/aw:build`.
+
+## Task Granularity
+
+Each implementation step should usually be one action that takes about 2-5 minutes, for example:
+
+- write the failing test
+- run it to verify it fails for the expected reason
+- write the minimal implementation
+- rerun the test to verify it passes
+- commit the focused change
+
+## Required `tasks.md` Structure
+
+`tasks.md` should include:
+
+- an explicit `## Spec Brief` section near the top with the feature goal, approved scope, and architecture summary
+- a file structure map before the tasks
+- explicit phase sections such as `## Phase 1`, `## Phase 2`, and so on
+- a short phase outcome or exit check for each phase
+- task sections with exact file paths
+- checkbox steps for tracking
+- validation commands with expected outcomes
+- commit steps for meaningful slices
+- save-point commit expectation for each meaningful slice
+- dependency or ordering notes
+- bounded `parallel_candidate` markers only for disjoint write scopes
+- `parallel_group`, `parallel_ready_when`, and `parallel_write_scope` details for any parallel slice
+- `max_parallel_subagents: 3` by default when parallel fan-out is planned, unless another cap is explicitly justified
+
+If a slice cannot end in a clean save-point commit, it should usually be merged into the next dependent slice before handoff to build.
+If no safe disjoint work exists, say so explicitly instead of forcing fake parallelism.
+Even a small plan should still start with `## Spec Brief` and label the execution order with at least `## Phase 1` so the next worker can see the sequence immediately.
+
+## Code and Command Detail
+
+When a step changes code or tests, include the smallest concrete snippet, interface shape, or patch intent needed for a fresh worker to execute the step correctly.
+
+Every validation step should include:
+
+- exact command
+- why that command is being run
+- expected signal such as `FAIL`, `PASS`, or the named artifact/evidence result
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The builder can improvise the missing steps." | If the worker must guess, the task plan is not ready. |
+| "I’ll keep tasks broad so the plan stays short." | Broad tasks hide dependencies and break rollback-friendly execution. |
+| "I don’t need checkpoints for a small project." | Checkpoints are how you keep multi-slice work verifiable. |
+
+## Red Flags
+
+- a task title includes multiple independent changes joined by "and"
+- file scope is missing or generic
+- verification steps do not name exact commands or evidence targets
+- parallel work is marked without disjoint write boundaries
+- parallel fan-out is proposed without a cap or without naming the owned write scope
+
+## No Placeholders
+
+Never write:
+
+- `TODO`
+- `TBD`
+- `implement later`
+- `write tests`
+- `handle edge cases`
+- `same as previous task`
+
+If a worker would have to guess, the task is not ready.
+
+## Verification
+
+Before handoff:
+
+1. confirm every spec requirement maps to at least one task
+2. confirm file paths and interface names stay consistent across tasks
+3. confirm no task relies on an undefined helper, type, or command
+4. confirm `## Spec Brief` and the phase order are obvious from the top of `tasks.md`
+5. confirm execution can route straight to `/aw:build`
+
+## Final Output Shape
+
+Always end with:
+
+- `Feature Slug`
+- `Tasks Path`
+- `Spec Brief`
+- `File Map`
+- `Phases`
+- `Execution Route`
+- `Parallel Candidates`
+- `Review Result`
+- `Recommended Next`

package/.cursor/skills/aw-test/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: aw-test
+description: Produce fresh QA evidence for feature, bugfix, frontend runtime, and release scopes using repo and org quality gates.
+trigger: User requests QA, validation, regression proof, runtime proof, or a legacy verify request resolves to the testing stage.
+---
+
+# AW Test
+
+## Overview
+
+`aw-test` owns QA proof.
+It turns implementation into current, scoped evidence that review and deploy can trust, and it should continue until the requested QA scope is actually covered.
+
+## When to Use
+
+- the request is to test a feature or bugfix
+- the work needs fresh validation after build
+- frontend behavior needs runtime proof
+- release preparation needs broader QA evidence
+- a legacy `/aw:verify` request is primarily about testing
+
+Do not use for findings-oriented review or launch closeout.
+
+## Workflow
+
+1. Select the smallest correct QA scope.
+   Use `../../references/test-scope-and-evidence.md`.
+   Distinguish feature QA, bugfix regression proof, UI runtime proof, and release QA.
+2. Resolve org standards.
+   Load the resolved GHL baseline profile.
+   Pull in the required local validation, E2E, external validation, sandbox, and quality-gate expectations.
+3. Run the right checks.
+   Use `../../references/testing-patterns.md` for test structure.
+   For frontend work, load `../../references/frontend-quality-checklist.md`.
+   For accessibility-sensitive UI, load `../../references/accessibility-checklist.md`.
+   For substantial UI validation, load `frontend-ui-engineering`.
+   For live browser, DOM, console, network, or runtime-proof work, load `browser-testing-with-devtools`.
+   For performance-sensitive paths, load `performance-optimization` and `../../references/performance-checklist.md`.
+4. Continue through the requested QA scope.
+   Do not stop after the first passing check if the requested feature, bugfix, UI-runtime, or release scope still has missing evidence.
+   Only stop early when the remaining work clearly belongs to another stage or a blocker prevents additional testing.
+5. Record evidence, not vibes.
+   Name which commands ran, what passed, what failed, what was unavailable, and what still remains unproven.
+6. Decide the handoff.
+   Route to `aw-review` when findings, governance, or readiness decisions remain.
+   Route to `aw-build` when a failure needs repair.
+   If the stage is blocked, name the blocker and the smallest safe next action explicitly.
+7. Persist the result.
+   Write `verification.md` and update `state.json`.
+
+## Completion Contract
+
+Testing is complete only when one of these is true:
+
+- the requested QA scope has fresh enough evidence for the next stage
+- a failure sends the work back to `aw-build`
+- a blocker prevents additional proof and that blocker is explicit
+
+Every testing handoff must make these things obvious:
+
+- which scope was tested
+- which checks ran
+- which evidence passed or failed
+- which gaps are still unavailable or unresolved
+- which exact next command should run next
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Review can cover testing later." | Review is stronger when QA evidence is already concrete. |
+| "The unit tests are enough for this frontend change." | UI work may also need responsive, accessibility, and runtime proof. |
+| "The check doesn't exist, so I can treat it as passed." | Unavailable is not the same as passed. Record the gap explicitly. |
+
+## Red Flags
+
+- stale evidence after code changed
+- no regression proof for a bugfix
+- frontend changes have no runtime or responsive evidence
+- release QA is described vaguely instead of by concrete checks
+
+## State File
+
+`state.json` should record at least:
+
+- `feature_slug`
+- `stage: "test"`
+- `mode`
+- `status`
+- written artifacts
+- commands run
+- evidence artifacts
+- failures
+- unavailable checks
+- blockers
+- recommended next commands
+
+## Verification
+
+Before leaving test, confirm:
+
+- [ ] the QA scope is explicit and proportional
+- [ ] org-standard baseline checks were applied where available
+- [ ] unavailable checks are marked unavailable, not silently passed
+- [ ] fresh evidence is written to `verification.md`
+- [ ] `state.json` is updated with checks, failures, and next action
+
+## Final Output Shape
+
+Always end with:
+
+- `Mode`
+- `Scope`
+- `Checks Run`
+- `Evidence`
+- `Failures`
+- `Unavailable`
+- `Next`

package/.cursor/skills/aw-verify/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: aw-verify
+description: Compatibility skill for the older verify stage. Resolve the request into aw-test, aw-review, or the smallest correct combined verification flow.
+trigger: Internal compatibility only. Invoked when older docs, habits, or commands still reference aw-verify.
+---
+
+# AW Verify
+
+## Overview
+
+`aw-verify` is a compatibility layer.
+The canonical public verification model is now:
+
+- `aw-test` for QA evidence
+- `aw-review` for findings, governance, and readiness
+
+## When to Use
+
+- a legacy `/aw:verify` request arrives
+- an older doc still frames testing and review as one overloaded stage
+
+## Workflow
+
+1. Identify the real need.
+   If the request is mostly QA, route to `aw-test`.
+   If it is mostly findings, governance, or readiness, route to `aw-review`.
+   If both are clearly needed, use `aw-test -> aw-review`.
+2. Preserve the compatibility artifact contract.
+   Keep writing `verification.md` and `state.json`.
+3. Preserve stage continuation as well as stage boundaries.
+   Do not stop after partial evidence if the selected test or review scope still remains.
+4. Do not preserve old ambiguity.
+   Prefer the narrowest modern stage once the intent is clear.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Verify can keep meaning everything forever." | Overloaded stages make routing and ownership unclear. |
+
+## Red Flags
+
+- verification requests are not decomposed into test or review intent
+- old verify language is used to hide missing evidence or findings
+
+## Verification
+
+- [ ] the request resolved to `aw-test`, `aw-review`, or both
+- [ ] the selected test or review scope was completed or blocked explicitly
+- [ ] compatibility did not create a second verification workflow
+- [ ] `verification.md` and `state.json` stayed consistent with the resolved canonical flow

package/.cursor/skills/aw-yolo/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: aw-yolo
+description: Explicit internal orchestration skill for one-run end-to-end automation across plan, build, test, review, deploy, and ship.
+trigger: Internal only. Use when the user clearly asks for one-run end-to-end automation instead of stage-by-stage progress.
+---
+
+# AW YOLO
+
+## Overview
+
+`aw-yolo` is the explicit full-flow orchestration skill.
+It exists so `ship` can stay a real shipping stage instead of an overloaded composite label.
+Use it to orchestrate the smallest correct remaining multi-stage path from the current state to a safe release outcome.
+
+## When to Use
+
+- the user explicitly asks to handle the full flow in one run
+- the request spans multiple AW stages and the user wants automation, not manual stage boundaries
+- the starting point is already partway through the lifecycle, but the user still wants the rest handled end to end
+
+Do not use by default.
+If the user asked for one stage, stay in that stage.
+
+## Workflow
+
+1. Confirm the request really wants orchestration.
+   `aw-yolo` is only correct when the user wants the remaining workflow handled in one pass.
+   If they only asked to deploy, ship, review, or test, stay in that stage.
+2. Classify the current starting state.
+   Identify which stage artifacts already exist and which stages are still unsatisfied.
+   Use this table as the default operating model:
+
+   | Starting state | Smallest correct remaining flow |
+   |---|---|
+   | only an idea, PRD, or vague approved direction | `aw-plan -> aw-build -> aw-test -> aw-review -> aw-deploy -> aw-ship` |
+   | approved spec/tasks or otherwise build-ready inputs | `aw-build -> aw-test -> aw-review -> aw-deploy -> aw-ship` |
+   | implementation exists but fresh evidence is missing | `aw-test -> aw-review -> aw-deploy -> aw-ship` |
+   | verification is complete and the user wants release action plus closeout | `aw-deploy -> aw-ship` |
+   | deploy action is complete and only rollout closeout remains | `aw-ship` |
+
+   Do not reopen already satisfied stages unless the current stage fails and forces a backward step.
+3. Execute one stage at a time.
+   Run the first unsatisfied stage, write its required artifacts, then reassess the next smallest safe stage.
+   Typical full sequence:
+   - `aw-plan`
+   - `aw-build`
+   - `aw-test`
+   - `aw-review`
+   - `aw-deploy`
+   - `aw-ship`
+   Do not leave a stage early just because one slice, one check, or one note succeeded.
+   A stage only hands off when its own completion contract is met or it is blocked explicitly.
+4. Preserve stage artifacts.
+   Internal orchestration is not permission to skip `execution.md`, `verification.md`, `release.md`, or `state.json`.
+   A stage is not done until its required artifacts are written.
+5. Respect stage boundaries.
+   `aw-yolo` coordinates stages, but it does not collapse them together.
+   Build still cannot self-certify.
+   Test still cannot quietly implement.
+   Deploy still cannot skip verify.
+   Ship still owns rollout closeout rather than implementation or release execution.
+6. Respect org standards at each stage.
+   Use the resolved GHL baseline profile, platform playbooks, and `.aw_rules`.
+7. Stop cleanly on blockers.
+   Stop immediately if a stage fails, evidence is missing, deploy configuration is unknown, or approval assumptions become unsafe.
+   Name the blocking stage and the smallest safe next action.
+   Name:
+   - the blocking stage
+   - what was completed
+   - the smallest safe next action
+8. End with a real terminal state.
+   The run is complete only when:
+   - the final remaining stage is finished and its artifact exists, or
+   - the workflow stops at a named blocker with a clear handoff
+
+## Final Output Shape
+
+Always end with:
+
+- `Current Stage`
+- `Completed Stages`
+- `Artifacts Written`
+- `Blockers`
+- `Recommended Next`
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "If the user said ship, I should always use yolo." | `ship` is now its own stage. `aw-yolo` is only for explicit whole-flow automation. |
+| "One-run automation means I can skip stage evidence." | Orchestration still owes every required artifact. |
+| "The request mentioned several stages, so I should always start from plan." | Start from the first unsatisfied stage, not from the beginning by habit. |
+| "If test or review fails, I should push through to deploy anyway." | `aw-yolo` must stop at the failing stage and hand back the blocker clearly. |
+
+## Red Flags
+
+- the request only named one stage but yolo was selected anyway
+- stage artifacts are skipped because the flow is internal
+- rollout safety is collapsed into deploy
+- already satisfied stages are reopened without a concrete reason
+- the run reaches deploy or ship even though test or review evidence failed
+- the final output does not say which stage the workflow ended on
+
+## Verification
+
+- [ ] the user explicitly wanted full-flow automation
+- [ ] the selected flow is the smallest correct end-to-end sequence
+- [ ] the chosen starting stage matches the current repo/artifact state
+- [ ] each stage still writes its required artifacts
+- [ ] failed stages stop the flow instead of being hand-waved away
+- [ ] blockers name the exact stage where the run stopped