aw-ecc 1.4.21 → 1.4.25

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

@@ -0,0 +1,118 @@
+---
+name: aw-review
+description: Review work for findings, governance, and readiness using explicit severity, org-standard playbooks, and fresh evidence.
+trigger: User requests review, readiness, or PR governance, or a legacy verify request resolves to the review stage.
+---
+
+# AW Review
+
+## Overview
+
+`aw-review` is now a public stage skill.
+It turns evidence into findings, release decisions, and clear next actions.
+
+## When to Use
+
+- the request is findings-oriented review
+- PR governance or readiness matters
+- the work needs a release recommendation
+- a legacy `/aw:verify` request is mostly about review
+
+Do not use as a hidden helper that replaces explicit review intent.
+
+## Workflow
+
+1. Review the evidence first.
+   Start with tests, local validation, E2E, runtime proof, and prior investigation artifacts.
+2. Load the right org-standard playbooks.
+   Pull in platform review, design, accessibility, and quality-gate playbooks from the resolved baseline.
+3. Review across the five core axes.
+   Correctness, readability and simplicity, architecture, security, and performance.
+   Use `../../references/review-findings-severity.md`.
+   For readability and maintainability concerns, load `code-simplification`.
+   For public contract or boundary changes, load `api-and-interface-design`.
+   For security-sensitive work, load `security-and-hardening` and `../../references/security-checklist.md`.
+   For performance-sensitive work, load `performance-optimization` and `../../references/performance-checklist.md`.
+   For branch hygiene, save-point quality, or reviewability concerns, load `git-workflow-and-versioning`.
+4. Classify findings explicitly.
+   Separate blocking findings from advisory notes.
+   Name evidence, scope, and required fix.
+5. Continue until the requested review scope is covered.
+   Do not stop after the first finding or the first review axis if correctness, governance, architecture, security, performance, or readiness checks still remain.
+6. Check governance and readiness.
+   Confirm PR checklist, approvals, status checks, rollback notes, and release recommendation.
+   For architecture or public-behavior changes that need durable rationale, load `documentation-and-adrs`.
+7. Request fresh testing when needed.
+   If evidence is stale, missing, or too broad, route back to `aw-test` for the smallest targeted rerun.
+8. Persist the result.
+   Write `verification.md` and update `state.json`.
+
+## Completion Contract
+
+Review is complete only when one of these is true:
+
+- the requested findings, governance, and readiness scope is covered with current evidence
+- the work fails review and the repair path is explicit
+- a blocker prevents a trustworthy decision and that blocker is named
+
+Every review handoff must make these things obvious:
+
+- which evidence was reviewed
+- which findings are blocking versus advisory
+- which governance checks were completed
+- what the readiness outcome is
+- which exact next command should run next
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The tests passed, so review is basically done." | Tests are evidence, not the whole decision. |
+| "This looks fine overall." | Findings need explicit severity, scope, and evidence. |
+| "I can clear the finding from memory." | Resolutions require fresh evidence against the original issue. |
+
+## Red Flags
+
+- no explicit severity language
+- PR governance is implied instead of checked
+- platform review or design playbooks are skipped for applicable work
+- stale test evidence is reused after repairs
+
+## State File
+
+`state.json` should record at least:
+
+- `feature_slug`
+- `stage: "review"`
+- `mode`
+- `status`
+- written artifacts
+- evidence reviewed
+- blocking findings
+- advisory notes
+- governance status
+- readiness outcome
+- blockers
+- recommended next commands
+
+## Verification
+
+Before leaving review, confirm:
+
+- [ ] test and runtime evidence were reviewed first
+- [ ] findings are explicit, evidence-backed, and severity-tagged
+- [ ] governance and readiness checks match the resolved baseline
+- [ ] repairs point back to build or test with clear scope
+- [ ] `verification.md` and `state.json` are updated
+
+## Final Output Shape
+
+Always end with:
+
+- `Mode`
+- `Evidence`
+- `Findings`
+- `Governance`
+- `Readiness`
+- `Outcome`
+- `Next`

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