aw-ecc 1.4.23 → 1.4.25

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

@@ -0,0 +1,368 @@
+---
+name: aw-plan
+description: Create the minimum correct planning artifacts under `.aw_docs/features/<feature_slug>/` and stop cleanly before implementation.
+trigger: User requests planning, a missing planning artifact blocks build, or `aw-yolo` needs to move work into a build-ready state.
+---
+
+# AW Plan
+
+## Overview
+
+`aw-plan` owns planning only.
+It creates the minimum correct planning artifact set for the request and always writes deterministic outputs under:
+
+- `.aw_docs/features/<feature_slug>/`
+
+When planning is required, the output should be execution-ready for a fresh worker with limited repo context.
+That means the plan should reduce guesswork around files, validation, order, and handoff risks instead of stopping at vague prose.
+For non-trivial work, `aw-plan` should behave like a small internal planning graph rather than a single flat prompt.
+
+## When to Use
+
+- the user needs a PRD, design, spec, or task breakdown
+- approved work is missing a planning artifact needed by build
+- a request is too large, too fuzzy, or too risky to execute directly
+- `aw-yolo` needs to move work into a build-ready state
+
+**When NOT to use:** when the request is already build-ready, when the issue is really investigation rather than planning, or when the user is only asking for test, review, deploy, or ship work.
+
+## Workflow
+
+This legacy heading maps to the detailed planning process below.
+
+## The Planning Process
+
+1. Enter plan mode.
+   Load repo context, relevant platform docs, and relevant `.aw_rules`.
+   Planning is read-only until the planning artifacts are written.
+2. Identify the feature and current artifact state.
+   Infer or honor the feature slug.
+   Detect which planning artifacts already exist and which are actually missing.
+3. Choose the smallest internal route.
+   Decide whether the request is already clear enough for direct planning or needs discovery first.
+   For raw concepts or product-shaping work, load `idea-refine` before freezing the direction.
+4. Plan in dependency order.
+   Use dependency graph thinking to decide whether product, design, technical, or tasks work must come first.
+   For public interface or contract changes, load `api-and-interface-design`.
+   For deprecation, replacement, or migration work, load `deprecation-and-migration`.
+   For major architectural or public-behavior decisions, load `documentation-and-adrs`.
+5. Slice vertically where possible.
+   Prefer end-to-end feature slices and concrete checkpoints over horizontal batch plans.
+6. Write only the missing artifacts.
+   Make every created artifact concrete enough for the next stage to proceed without re-planning file scope, validation, and task order.
+7. Review and update state.
+   Run a placeholder and consistency pass, then update `.aw_docs/features/<feature_slug>/state.json`.
+8. Stop after planning.
+   Recommend the next stage without drifting into build, test, or deploy.
+
+## Internal Skill Graph
+
+Use the smallest correct internal route:
+
+- raw idea or under-shaped concept -> `idea-refine`, then `aw-brainstorm` when deeper repo-aware exploration is still needed
+- fuzzy request, open design question, or overscoped feature -> `aw-brainstorm`
+- approved direction but missing technical contract -> `aw-spec`
+- approved spec but missing execution recipe -> `aw-tasks`
+- already execution-ready tasks -> stop and recommend `aw-build`
+
+Do not collapse all of these responsibilities back into one vague planning pass.
+
+## Planning Modes
+
+| Mode | Use when | Primary outputs |
+|---|---|---|
+| `product` | problem, scope, or acceptance criteria are unclear | `prd.md`, `state.json` |
+| `design` | UX behavior or interface design must be defined | `design.md`, `designs/`, `state.json` |
+| `technical` | implementation approach or architecture must be defined | `spec.md`, `state.json` |
+| `tasks` | implementation work needs to be broken into steps | `tasks.md`, `state.json` |
+| `full` | multiple planning artifacts are missing | missing artifacts in order, plus `state.json` |
+
+## Artifact Rules
+
+- write artifacts only under `.aw_docs/features/<feature_slug>/`
+- use only deterministic names:
+  - `prd.md`
+  - `design.md`
+  - `designs/`
+  - `spec.md`
+  - `tasks.md`
+  - `state.json`
+- do not write planning artifacts to `docs/plans/`
+- do not create random filenames
+- do not write implementation code
+
+## Plan Document Template
+
+### `prd.md`
+
+Capture:
+
+- goal
+- scope
+- non-goals
+- acceptance criteria
+- risks or dependencies
+
+### `design.md`
+
+Capture:
+
+- routes or flows
+- states
+- interaction rules
+- accessibility notes
+- references to `designs/`
+
+### `spec.md`
+
+Canonical internal owner: `aw-spec`
+
+Capture:
+
+- implementation goal
+- scope
+- interfaces or contracts
+- technical approach
+- failure modes
+- acceptance criteria
+- verification targets
+- expected changed files or modules when those can be inferred safely
+- key commands, migrations, or rollout constraints that execution must honor
+
+### `tasks.md`
+
+Canonical internal owner: `aw-tasks`
+
+Start with a short header and an explicit `## Spec Brief` section that captures:
+
+- feature goal
+- spec brief
+- architecture summary
+- execution route: `/aw:build`
+- expected execution mode when it is known safely
+
+Before task sections, map the file structure:
+
+- exact files to create
+- exact files to modify
+- exact tests to add or update
+- the responsibility of each file when that can be stated clearly
+
+Organize the work into explicit phases before listing slices:
+
+- always label the execution order with headings such as `## Phase 1`, `## Phase 2`, and so on
+- give each phase a short outcome statement so the next worker knows what should be true when that phase ends
+- use phases to show dependency order, not to create abstract ceremony
+
+Break implementation into small, executable chunks with:
+
+- files
+- checkbox steps
+- acceptance
+- task type: `code`, `infra`, `docs`, `migration`, or `config`
+- validation command or evidence target
+- save-point commit expected for the slice
+- dependency or ordering note when sequencing matters
+- `parallel_candidate` only when the write scope is safely disjoint
+- `parallel_group` when multiple slices can fan out after the same prerequisite
+- `parallel_ready_when` when parallel work must wait for a contract, helper, or schema to land first
+- `parallel_write_scope` so execution can keep ownership boundaries explicit
+- `max_parallel_subagents: 3` by default when parallel fan-out is planned, unless another cap is explicitly justified
+
+For code behavior, prefer task steps close to:
+
+- write the failing test or capture the failing signal
+- run it to verify the failure is real
+- write the minimal change
+- rerun the relevant verification to confirm the pass
+- commit the focused slice
+
+Each step should usually be small enough to fit in about 2-5 minutes.
+Use `../../references/task-sizing-and-checkpoints.md` when sizing or checkpointing gets fuzzy.
+
+## Execution-Ready Tasks
+
+`tasks.md` is not complete until a fresh worker can execute it without rediscovering the plan.
+
+Execution-ready tasks should make it obvious:
+
+- what `## Spec Brief` says at the top of the plan
+- which phases exist and what each phase is meant to deliver
+- which files change first
+- which validation command or evidence target proves each slice
+- which steps are safe to parallelize
+- which `parallel_group` and `parallel_write_scope` belong to those steps
+- what `max_parallel_subagents` cap build should honor for that plan
+- which slice should produce the next save-point commit
+- which blocker should send execution back to planning instead of guessing
+
+## Plan Richness
+
+When the request is in `technical`, `tasks`, or `full` mode, planning should be specific enough that execution does not have to rediscover the shape of the work.
+
+Prefer including:
+
+- an explicit `## Spec Brief` section at the top of `tasks.md`
+- exact or likely changed files and what each one is responsible for
+- exact file paths when they can be inferred safely
+- explicit phase headings for the task plan
+- concrete task goals
+- checkbox execution steps for non-trivial work
+- exact commands and expected outcomes for failure and pass checks
+- the minimal validation commands or evidence expected after implementation
+- commit boundaries for meaningful slices
+- save-point commit expectations for meaningful slices
+- sequencing notes for dependent tasks
+- bounded parallel candidates for disjoint work
+- explicit `parallel_group`, `parallel_ready_when`, and `parallel_write_scope` notes when work may fan out
+- a `max_parallel_subagents` cap that defaults to `3` unless a different cap is explicitly justified
+- key risks, blockers, or rollback constraints
+
+If a proposed slice cannot support a clean save-point commit, planning should merge it into the next dependent slice instead of normalizing a no-commit checkpoint.
+
+The goal is not maximum verbosity.
+The goal is minimum ambiguity.
+
+Use `../../references/task-sizing-and-checkpoints.md` when task sizing, checkpoint placement, or phase boundaries start getting fuzzy.
+
+## Task Sizing Guidelines
+
+`tasks.md` should avoid vague tasks such as:
+
+- "implement feature"
+- "fix bug"
+- "update code as needed"
+
+Prefer task units that name:
+
+- goal
+- file scope
+- change intent
+- acceptance check
+- validation command or evidence target
+- expected verification signal
+- commit boundary when the slice is meaningful
+
+## No Placeholders
+
+Planning fails if it contains placeholders such as:
+
+- `TODO`
+- `TBD`
+- `implement later`
+- `write tests`
+- `handle edge cases`
+- `same as Task N`
+
+If execution would need to guess what a step means, planning is not complete.
+
+Use these guardrails when sizing work:
+
+| Size | Scope signal | Default action |
+|---|---|---|
+| `XS` | single-file or single-boundary clarification | keep it as one focused task |
+| `S` | one slice with one primary validation target | ideal task size |
+| `M` | 3-5 files or one vertical feature slice | acceptable when checkpoints are explicit |
+| `L` | multiple subsystems or mixed rollout risk | break it down further |
+| `XL` | broad subsystem batch or multi-phase rollout | planning failure until decomposed |
+
+If a task title needs "and", it is usually more than one task.
+If a step would take longer than one focused implementation session, break it down further.
+
+## Parallelization Opportunities
+
+Parallel work is allowed only when the write scope is clearly disjoint.
+Plan parallel work in bounded waves rather than unbounded fan-out.
+
+- safe to parallelize:
+  - docs versus code
+  - backend versus frontend after the contract is fixed
+  - implementation versus reference/checklist preparation
+- do not parallelize:
+  - tasks that change the same files
+  - rollout-sensitive migrations
+  - tasks that depend on a helper, interface, or schema not created yet
+
+Default to `max_parallel_subagents: 3` when parallel build fan-out is useful.
+Only change that cap when the plan names a concrete reason such as runtime limits, repo size, or a proven need for tighter sequencing.
+
+When in doubt, sequence the work and leave `parallel_candidate` off.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I’ll figure it out while building." | That is how scope drift and rework start. |
+| "The tasks are obvious, so I don’t need to write them down." | Written plans expose hidden dependencies and missing checks. |
+| "A big batch plan is faster." | Thin vertical slices are easier to verify, review, and roll back. |
+| "Planning should stay abstract." | Abstract plans force the next stage to re-plan the work. |
+
+## Red Flags
+
+- planning begins with implementation advice instead of artifact selection
+- task steps are vague enough that build would need to rediscover the file scope
+- no checkpoints exist between meaningful phases
+- multiple independent subsystems are bundled into one undifferentiated task list
+- placeholders like `TODO`, `TBD`, or "handle edge cases" remain in the artifacts
+
+## Verification
+
+The verification pass for planning is the plan self-review.
+
+## Plan Self-Review
+
+Before ending the planning stage:
+
+1. confirm each spec requirement maps to a task or explicit reason it is out of scope
+2. confirm `## Spec Brief` at the top of `tasks.md` matches the approved spec
+3. confirm the phase order is obvious and every phase has a clear outcome
+4. scan for placeholders and vague steps
+5. check that file paths, type names, helper names, and commands stay consistent
+6. confirm the next stage can route directly to `/aw:build` or explicitly state what approval is still missing
+
+Treat this as the planning verification pass.
+If the plan cannot survive this self-review, it is not ready for execution handoff.
+
+## Execution Handoff
+
+When `tasks.md` is ready:
+
+- recommend `/aw:build`
+- name the selected execution mode when it is known safely
+- name any blocker that should send the work back to planning instead of guessing
+
+## Hard Gates
+
+- do not write code
+- do not require `prd.md` for a technical-only request that is already well-defined
+- do not force unrelated artifacts
+- do not silently broaden a narrow planning request into full planning
+- do not produce handoff tasks so vague that execution must re-plan the file scope
+
+## State File
+
+`state.json` should record at least:
+
+- `feature_slug`
+- `stage: "plan"`
+- `mode`
+- `status`
+- written artifacts
+- key inputs
+- internal skills used
+- planned save-point commit policy
+- parallel build policy and cap when parallel execution is planned
+- recommended next commands
+
+## Final Output Shape
+
+Always end with:
+
+- `Route`
+- `Mode`
+- `Created`
+- `Spec Brief`
+- `Phases`
+- `Execution Readiness`
+- `Missing`
+- `Next`

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

@@ -0,0 +1,118 @@
+---
+name: aw-prepare
+description: Internal preparation layer that validates repo state, branch or worktree isolation, and execution readiness before risky AW stages begin.
+trigger: Internal only. Invoked by aw-build, aw-deploy, aw-ship, or aw-yolo before code-changing or release-oriented work.
+---
+
+# AW Prepare
+
+## Purpose
+
+`aw-prepare` is an internal setup gate.
+It keeps the public AW surface small while adding the practical safety checks needed before execution or release work starts.
+
+## Responsibilities
+
+Always check the smallest correct set of:
+
+- current branch or worktree isolation
+- dirty tracked or untracked state that could contaminate the requested work
+- feature slug and artifact baseline
+- workspace metadata handoff for the active feature
+- obvious runnable baseline validation when it is cheap and safe
+- deploy-target prerequisites when the next stage is release-oriented
+
+## Isolation Levels
+
+Preparation should classify the current workspace into one of these levels:
+
+| Level | Meaning | Default action |
+|---|---|---|
+| `isolated-worktree` | dedicated worktree or clearly isolated workspace | proceed |
+| `isolated-branch` | dedicated feature branch in the main checkout | proceed with caution notes |
+| `shared-branch-dirty` | shared branch or dirty state could contaminate work | warn or block based on risk |
+| `snapshot-degraded` | source snapshot or eval workspace without live git metadata | proceed in degraded mode when side effects are not required |
+
+## Recommended Isolation Action
+
+When isolation is weaker than `isolated-worktree`, preparation should recommend the smallest corrective action, such as:
+
+- create a feature branch
+- switch to a dedicated worktree
+- stash or isolate unrelated local changes
+- continue in degraded snapshot mode with blocked external side effects
+
+## Operational Lifecycle
+
+When a dedicated worktree is the right isolation boundary, use the repo-local orchestration helpers instead of leaving setup implicit:
+
+- `node scripts/orchestrate-worktrees.js <plan.json>` to render the branch-backed worktree plan
+- `node scripts/orchestrate-worktrees.js <plan.json> --execute` to create the worktree session
+- `node scripts/orchestration-status.js <plan.json|session-name>` to inspect the resulting orchestration snapshot
+
+For single-worker isolation, a one-worker orchestration plan is valid.
+Do not invent a separate workflow for "simple" worktree creation.
+
+## Workspace Metadata
+
+When preparation creates, selects, or reuses an isolated workspace, persist `.aw_docs/features/<feature_slug>/workspace.json` with the minimum useful fields:
+
+- `feature_slug`
+- `isolation_level`
+- `branch_name`
+- `worktree_path`
+- `coordination_dir`
+- `cleanup_policy`
+- `status_command`
+- `recommended_next`
+
+## Required Behavior
+
+1. detect whether the work is running in an isolated branch or worktree
+2. report risky dirty state instead of silently continuing
+3. confirm the intended feature slug and relevant AW artifact directory
+4. recommend the smallest isolation action when the current workspace is weaker than ideal
+5. capture baseline commands that should be rerun later when practical
+6. write or update `workspace.json` when a dedicated branch or worktree is selected
+7. hand back a preparation summary to the calling stage
+8. when repo metadata is unavailable because the work is running inside a source snapshot or eval workspace, record degraded isolation as a warning and continue when local artifact work is still safe
+9. only hard-block on missing git metadata when the next action truly requires live branch, PR, or deployment execution that cannot be represented safely as blocked evidence
+
+## Hard Gates
+
+- do not create a new public command
+- do not silently discard or overwrite unrelated local changes
+- do not claim deploy readiness from preparation alone
+- do not block lightweight docs-only work unless repo state creates real ambiguity
+- do not treat missing `.git` metadata in snapshot or eval workspaces as an automatic blocker for plan, execute, verify, or evidence-only deploy handoff
+- do not treat a dirty shared branch as equivalent to an isolated worktree
+- do not continue into multi-stage ship work without naming the chosen isolation level
+
+## Preparation Summary
+
+Preparation output should capture:
+
+- isolation level
+- isolation status
+- recommended isolation action
+- repo cleanliness summary
+- baseline artifacts detected
+- cheap baseline commands run, if any
+- blockers or warnings
+- recommended next stage
+- whether the stage is continuing in degraded snapshot mode
+- workspace metadata path, when written
+
+## Final Output Shape
+
+Always end with:
+
+- `Isolation Level`
+- `Isolation`
+- `Recommended Isolation Action`
+- `Repo State`
+- `Artifacts Found`
+- `Baseline Checks`
+- `Warnings`
+- `Workspace Metadata`
+- `Recommended Next`

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`