aw-ecc 1.4.32 → 1.4.48

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

@@ -1,368 +0,0 @@
----
-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

@@ -1,118 +0,0 @@
----
-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

@@ -1,118 +0,0 @@
----
-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`