aw-ecc 1.4.21 → 1.4.25

package/.cursor/skills/git-workflow-and-versioning/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: git-workflow-and-versioning
+description: Keeps work reviewable, reversible, and well-scoped. Use for any code change that needs branches, save points, commit hygiene, or parallel work isolation.
+origin: ECC
+---
+
+# Git Workflow and Versioning
+
+## Overview
+
+Git is the safety system for fast-moving engineering work.
+Treat branches as sandboxes, commits as save points, and history as operational documentation for humans, reviewers, and future agents.
+
+## When to Use
+
+- making any code, config, docs, or migration change
+- deciding branch or worktree strategy
+- choosing commit boundaries
+- preparing changes for review or rollback
+- organizing parallel agent or multi-slice work
+
+**When NOT to use**
+
+- only when no repository-backed change is being made at all
+
+## Workflow
+
+1. Start from the smallest isolated workspace that fits the change.
+   Prefer short-lived feature branches.
+   For parallel work or risky experiments, use worktrees instead of branch thrash.
+2. Size the work before committing.
+   Break the change into logical slices that can be explained, reviewed, and reverted independently.
+   Use `../../references/git-save-points.md` when save-point discipline matters.
+3. Commit each successful increment.
+   The pattern is:
+   implement slice -> verify slice -> commit slice.
+   Do not wait for one giant final commit.
+4. Keep concerns separate.
+   Avoid mixing formatting, refactors, dependency churn, and feature behavior in the same commit unless they are inseparable.
+   Reviewable history is part of engineering quality.
+5. Run pre-commit hygiene.
+   Check the staged diff, run the smallest relevant validation, and verify secrets or generated junk are not being committed.
+6. Leave a scope map for the next human or agent.
+   Name:
+   - what changed
+   - what did not change
+   - what still needs follow-up
+   In AW flows, keep this aligned with the stage artifacts and change summaries.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll clean up the history later." | Messy history is harder to split and explain after the fact. |
+| "One big commit is faster." | Giant commits are slower to review, debug, and revert. |
+| "This cleanup can ride along with the feature." | Mixed concerns make scope, blame, and rollback harder. |
+| "I don't need an isolated branch for a small change." | Isolation is cheap; accidental overlap is expensive. |
+
+## Red Flags
+
+- one commit mixes unrelated concerns
+- the diff is too large to explain in one sentence
+- no save point exists between meaningful slices
+- generated output, secrets, or local-only noise are staged
+- branch or worktree discipline is vague during multi-agent work
+
+## Verification
+
+After using git workflow discipline, confirm:
+
+- [ ] the work is isolated in the right branch or worktree
+- [ ] commit boundaries match real progress
+- [ ] staged content excludes secrets and unrelated noise
+- [ ] the history is reviewable and reversible
+- [ ] the change summary makes scope boundaries explicit

package/.cursor/skills/idea-refine/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: idea-refine
+description: Refines raw ideas into sharper, build-worthy directions. Use when a request starts as an idea, concept, or vague opportunity rather than an implementation-ready plan.
+origin: ECC
+---
+
+# Idea Refine
+
+## Overview
+
+Refine ideas before turning them into specs.
+This skill takes a raw concept, pressure-tests it, and turns it into a concrete direction with explicit assumptions, MVP scope, and a clear "not doing" list.
+
+## When to Use
+
+- the user has a raw product, feature, or workflow idea
+- the request is still more concept than plan
+- multiple possible directions exist and the tradeoffs are not obvious
+- the team needs a sharper problem statement before `aw-plan`
+
+**When NOT to use**
+
+- the technical direction is already approved and the work is ready for `aw-plan`
+- the task is really implementation, testing, or review rather than idea shaping
+
+## Workflow
+
+1. Restate the idea as a sharp problem.
+   Convert the raw concept into a crisp problem statement or "How Might We" framing.
+   The goal is to name who the work is for and what better outcome it creates.
+2. Ask only the questions that change the direction.
+   Focus on:
+   - target user or operator
+   - success criteria
+   - real constraints
+   - timing or urgency
+   - what has already been tried
+3. Generate a small set of meaningful directions.
+   Explore 3-5 distinct options instead of polishing the first instinct.
+   Use lenses like simplification, inversion, audience shift, or "what would make this 10x more valuable?"
+4. Converge with pressure, not vibes.
+   Compare directions on:
+   - user value
+   - feasibility
+   - org fit and platform constraints
+   - differentiation
+   - rollout or maintenance risk
+5. Surface the bet explicitly.
+   Name:
+   - key assumptions
+   - what could kill the idea
+   - MVP scope
+   - what we are intentionally not doing
+6. Produce a one-pager that can move into planning.
+   The output should be easy to hand to `aw-plan` or `aw-brainstorm` without redoing the ideation.
+   In AW repos, keep this outcome inside planning artifacts or `state.json` instead of inventing a second artifact system.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "We already know what to build." | If the problem statement and user are fuzzy, the plan will be fuzzy too. |
+| "More ideas is always better." | A few meaningful directions beat a long list of shallow variants. |
+| "We'll decide scope once we start building." | Scope discovered too late becomes rework and churn. |
+| "Not doing lists are negative." | Explicitly saying no is what makes a direction buildable. |
+
+## Red Flags
+
+- the output jumps to implementation without clarifying user value
+- only one direction is considered when real alternatives exist
+- no assumptions or risks are surfaced
+- the final direction has no MVP boundary or "not doing" list
+- ideation silently turns into coding or detailed task planning
+
+## Verification
+
+After refining an idea, confirm:
+
+- [ ] the problem statement is explicit
+- [ ] the target user or operator and success criteria are named
+- [ ] multiple viable directions were considered
+- [ ] key assumptions and failure risks are visible
+- [ ] MVP scope and "not doing" boundaries are clear
+- [ ] the output is ready to feed `aw-plan` without restarting discovery

package/.cursor/skills/incremental-implementation/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: incremental-implementation
+description: Delivers multi-file work in thin, reversible slices. Use when a change spans more than one file, when a task feels too large to land safely in one pass, or when rollback clarity matters.
+origin: ECC
+---
+
+# Incremental Implementation
+
+## Overview
+
+Build in thin vertical slices.
+Each slice should leave the system in a working, testable, reviewable state before the next one begins, but a passing slice is only a checkpoint until the approved build scope is complete.
+
+## When to Use
+
+- a change touches more than one file
+- a feature is large enough to tempt one big patch
+- a migration, UI change, or rollout-sensitive task needs safe checkpoints
+- you want commit boundaries that reflect real progress
+
+**When NOT to use**
+
+- the work is already truly minimal and single-scope
+- the next step is still unclear and needs planning or investigation first
+
+## Workflow
+
+1. Select the next smallest slice.
+   Start from approved scope.
+   Choose one user-visible behavior, one boundary change, or one safe infrastructure increment.
+2. Define the proof for that slice.
+   Name the failing signal, acceptance check, or runtime evidence that will prove the slice is real.
+3. Implement only that slice.
+   Avoid adjacent cleanup and hidden follow-on work.
+   Use `../../references/build-increments.md` when sizing or rollback shape is fuzzy.
+4. Verify immediately.
+   Run the smallest relevant check:
+   - targeted test
+   - build or typecheck
+   - runtime/browser proof
+   - migration validation
+5. Save the progress cleanly.
+   Use `../../references/git-save-points.md` when the work benefits from explicit commit discipline.
+   A good save point is small, passing, and easy to explain.
+6. Decide whether to continue or hand off.
+   If more approved build slices remain, continue with the next slice.
+   If the approved build scope is complete and the next unsatisfied need is QA, review, or release work, stop and hand off.
+   Do not keep building just because speculative cleanup or unrelated improvements are possible.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll do the whole feature first, then test it." | Large unverified batches hide regressions and make rollback harder. |
+| "This extra cleanup is basically free." | Scope creep weakens slice boundaries and review quality. |
+| "I don't need a save point yet." | Save points matter most before the diff becomes hard to reason about. |
+| "The slice is too small to be worth validating." | Small slices are exactly what make validation cheap and reliable. |
+
+## Red Flags
+
+- one slice changes multiple unrelated behaviors
+- one passing slice is treated as the end of build even though approved build slices remain
+- rollback is unclear after the latest patch
+- tests are deferred instead of attached to the slice
+- commit/save-point boundaries no longer match meaningful progress
+
+## Verification
+
+After each increment, confirm:
+
+- [ ] the slice has one clear purpose
+- [ ] the slice has current proof, not assumed proof
+- [ ] the diff is still reversible and reviewable
+- [ ] the next slice is either the next approved build step or an explicit handoff boundary
+- [ ] save points reflect meaningful progress

package/.cursor/skills/performance-optimization/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: performance-optimization
+description: Optimizes performance with a measure-first workflow. Use when performance requirements exist, when regressions are suspected, or when user-visible speed and efficiency matter.
+origin: ECC
+---
+
+# Performance Optimization
+
+## Overview
+
+Measure first, optimize second.
+Performance work should improve a real bottleneck, not just produce clever code.
+
+## When to Use
+
+- a feature has explicit performance budgets or SLAs
+- users or monitoring report slow behavior
+- Core Web Vitals or endpoint timings are regressing
+- large datasets, hot paths, or expensive rendering are involved
+- review identifies likely performance risk that needs proof
+
+**When NOT to use**
+
+- there is no measurement and no evidence of a problem
+- the "optimization" is really a speculative rewrite
+
+## Workflow
+
+1. Choose the performance goal.
+   Name the metric that matters:
+   - browser responsiveness
+   - Core Web Vitals
+   - API latency
+   - query efficiency
+   - throughput or batch time
+2. Establish a baseline.
+   Use `../../references/performance-checklist.md`.
+   Capture the current measurement before touching code.
+3. Localize the bottleneck.
+   Identify whether the cost is in:
+   - network
+   - rendering
+   - computation
+   - data access
+   - bundle or startup cost
+4. Apply the smallest meaningful fix.
+   Optimize the proven bottleneck, not the whole subsystem.
+5. Measure again.
+   Confirm the change improved the chosen metric and did not create a regression elsewhere.
+6. Guard the gain.
+   Add follow-up monitoring, benchmark expectations, or review notes so the regression is less likely to return.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "This looks slow, so I'll optimize it now." | Visual intuition is not measurement. |
+| "I'll rewrite it for performance just in case." | Premature optimization adds complexity and often misses the real bottleneck. |
+| "A micro-optimization is better than no optimization." | Small cleverness is noise if the dominant cost lives elsewhere. |
+| "The benchmark is enough; user experience will follow." | Good optimization improves the metric that matters to the user or operator, not just the easiest one to measure. |
+
+## Red Flags
+
+- no baseline exists before code changes
+- the optimization changes multiple subsystems at once
+- claimed improvements are not measured after the fix
+- the new code is much harder to maintain for marginal gain
+
+## Verification
+
+After optimizing, confirm:
+
+- [ ] the target metric was explicit
+- [ ] a before/after measurement exists
+- [ ] the fix targeted the actual bottleneck
+- [ ] no obvious regression was introduced elsewhere
+- [ ] the performance gain is documented in a form reviewers can verify

package/.cursor/skills/security-and-hardening/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: security-and-hardening
+description: Hardens code and system boundaries against misuse. Use when working with authentication, user input, secrets, external integrations, sensitive data, or any new trust boundary.
+origin: ECC
+---
+
+# Security And Hardening
+
+## Overview
+
+Security is boundary work.
+This skill makes the agent classify trust boundaries, harden them deliberately, and prove the risky paths were reviewed rather than assumed safe.
+
+## When to Use
+
+- adding or changing authentication or authorization
+- handling user input, uploads, webhooks, or external API traffic
+- working with secrets, tokens, session state, or encryption
+- storing or transmitting sensitive or regulated data
+- introducing a new integration, endpoint, or background execution path
+
+**When NOT to use**
+
+- purely local changes with no user, network, secret, or boundary impact
+
+## Workflow
+
+1. Classify the boundaries first.
+   Identify:
+   - external input boundaries
+   - authz and identity boundaries
+   - data storage boundaries
+   - outbound trust boundaries
+2. Harden the entry points.
+   Validate input, apply authn/authz, enforce tenant or ownership scoping, and reject malformed or over-broad requests early.
+3. Protect secrets and configuration.
+   Use `../../references/security-checklist.md`.
+   Secrets must stay out of source, logs, screenshots, and error payloads.
+4. Reduce abuse and blast radius.
+   Add rate limits, safe defaults, least privilege, error handling, and logging that helps operators without leaking sensitive data.
+5. Review dependencies and operational posture.
+   Check whether packages, headers, storage settings, or integration modes introduce known risk.
+6. Prove the risky path was considered.
+   Name what was hardened, what remains risky, and what follow-up work is still required.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It's internal, so the security bar is lower." | Internal paths still become attack surfaces and privilege boundaries. |
+| "The framework handles that automatically." | Framework defaults help, but boundary ownership still belongs to the implementation. |
+| "We'll secure it after the happy path works." | Security debt compounds quickly once an interface is already in use. |
+| "Nobody will hit that edge case." | Attackers and accidental misuse both live in edge cases. |
+
+## Red Flags
+
+- trust boundaries are unclear or unnamed
+- secrets appear in code, logs, or test fixtures
+- auth exists without authorization checks
+- outbound integrations accept overly broad input or destination control
+
+## Verification
+
+After hardening, confirm:
+
+- [ ] the relevant trust boundaries are explicit
+- [ ] input, auth, and secret handling were reviewed deliberately
+- [ ] abusive or malformed requests fail safely
+- [ ] logs and errors avoid leaking sensitive data
+- [ ] remaining security risks or follow-ups are documented

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

@@ -0,0 +1,290 @@
+---
+name: using-aw-skills
+description: Session-start skill-first routing for the AW SDLC surface. Select the smallest correct AW skill stack before any substantive response, then load deeper stage, domain, and org-standard detail on demand.
+trigger: Every session start. Loaded automatically via session-start hook.
+---
+
+# Using AW Skills
+
+## Overview
+
+This skill is the thin router for the AW SDLC surface.
+Its job is to:
+
+- choose the smallest correct public route
+- choose the smallest correct AW skill stack
+- stop generic commentary until the stage is clear
+- load deeper references only when they materially change the decision
+
+Keep this file small.
+Stage behavior belongs in stage skills.
+Long examples, checklists, and loading guidance belong in shared references.
+
+This means the file should optimize for one thing first:
+
+- make the right next skill obvious
+
+## When to Use
+
+- at session start
+- before any substantive response
+- whenever the request might map to planning, building, investigating, testing, reviewing, deploying, or shipping work
+- whenever the user gives a vague request and the right stage still has to be selected
+
+Do not skip this skill just because the work looks small.
+
+## Skill Discovery
+
+When a task arrives, identify the current delivery phase and load the smallest correct route:
+
+```text
+Task arrives
+    │
+    ├── Vague idea, spec, or task breakdown? ───────→ /aw:plan
+    ├── Approved change to implement? ──────────────→ /aw:build
+    ├── Bug, alert, or unclear runtime failure? ────→ /aw:investigate
+    ├── Need QA proof or regression evidence? ──────→ /aw:test
+    ├── Need findings or readiness decision? ───────→ /aw:review
+    ├── Need one concrete release action? ──────────→ /aw:deploy
+    ├── Need launch or rollout closeout? ───────────→ /aw:ship
+    └── Need one-run end-to-end automation? ───────→ aw-yolo
+```
+
+Then load the supporting craft and domain skills that sharpen that route.
+If the work is in a real GHL domain, load `using-platform-skills` next.
+
+## Public Surface
+
+The public surface stays intentionally small.
+The canonical routes are the stages shown in the discovery flow above:
+
+- `/aw:plan`, `/aw:build`, `/aw:test`, `/aw:review`, `/aw:deploy`, `/aw:ship`
+- `/aw:investigate`
+
+Default delivery flow:
+
+- `/aw:plan` -> `/aw:build` -> `/aw:test` -> `/aw:review` -> `/aw:deploy` -> `/aw:ship`
+
+Conditional route:
+
+- `/aw:investigate`
+
+`/aw:investigate` is a first-class route for bugs, alerts, regressions, and unclear root cause.
+It should not be treated as a mandatory phase in every request.
+
+Compatibility entrypoints remain available during migration:
+
+- `/aw:execute` -> `/aw:build`
+- `/aw:verify` -> `/aw:test`, `/aw:review`, or the smallest correct combined verification flow
+
+There is also one explicit internal power workflow:
+
+- `aw-yolo`
+
+`aw-yolo` is for clearly end-to-end requests where the user wants one-run automation.
+It should not become the default route for normal stage-specific work.
+When it is selected, begin at the first unsatisfied stage rather than restarting the lifecycle from the top.
+
+## Core Operating Behaviors
+
+These behaviors apply across every route.
+
+### 1. Surface Assumptions
+
+Name assumptions that materially change scope, architecture, rollout, or verification.
+If an assumption could change the selected route, say it early.
+
+### 2. Manage Confusion Actively
+
+If the request, spec, code, or baseline disagree:
+
+1. stop
+2. name the contradiction
+3. state the tradeoff or blocking question
+4. do not guess through it
+
+### 3. Push Back With Concrete Tradeoffs
+
+If an approach creates obvious risk, complexity, or rollout danger:
+
+- say so directly
+- name the downside
+- propose the smallest safer alternative
+
+### 4. Enforce Simplicity
+
+Prefer the smallest route and the smallest supporting skill stack.
+Do not turn a single-stage task into a hidden multi-stage workflow.
+
+### 5. Maintain Scope Discipline
+
+Touch only the stage and supporting context required for the current request.
+Do not reopen planning, implementation, or release work without a reason.
+
+### 6. Verify, Don't Assume
+
+Every route must eventually produce evidence, not just confidence.
+Proof belongs in the right stage artifact, not only in narration.
+
+## Always-On Activation
+
+Before any substantive response, this router must select the smallest correct AW skill stack and matching public route.
+
+- explicit user command -> honor that command and load the mapped AW stage skill first
+- clear process need -> load the needed internal process skill first
+- otherwise choose the smallest correct AW primary stage skill and matching public route by intent
+- only after the required AW skills are selected, load deeper domain skills or ask clarifying questions
+
+Do not start with generic implementation, review, or deploy advice before skill selection.
+Do not leave the active skill stack or matching route implicit for non-trivial work.
+
+## The Rule
+
+If there is even a small chance that an AW process skill, stage skill, or required domain skill applies, load it before responding.
+
+Questions count.
+Clarifying questions count.
+Quick exploration counts.
+
+The AW public command is the user-facing projection of the selected primary stage skill.
+
+## Skill Priority
+
+When multiple AW skills could apply, use this order:
+
+1. process skills first:
+   - `aw-brainstorm`
+   - `aw-debug`
+   - `aw-prepare`
+   - `aw-yolo`
+2. primary stage skills second:
+   - `aw-plan`
+   - `aw-build`
+   - `aw-investigate`
+   - `aw-test`
+   - `aw-review`
+   - `aw-deploy`
+   - `aw-ship`
+3. domain and cross-cutting skills third
+
+The selected public route should reflect the primary stage skill, not hide it.
+
+## Route Selection
+
+Use one primary route unless the user explicitly asks for end-to-end orchestration.
+
+For route examples, explicit routing priority, and scope guardrails, see [`../../references/route-selection-patterns.md`](../../references/route-selection-patterns.md).
+
+## Failure Modes to Avoid
+
+These patterns look productive, but they create routing drift:
+
+1. answering quickly before selecting a route
+2. treating exploration as exempt from routing
+3. choosing `/aw:investigate` for every bug, even when the fix is already known
+4. treating `aw-yolo` as the default because it feels convenient
+5. reopening planning during `build` without a real blocker
+6. silently implementing during `test` or `review`
+7. loading every domain skill "just in case"
+8. giving a confident answer without evidence or stage artifacts
+
+## Cross-Cutting Engineering Skills
+
+After the primary stage is selected, load the portable craft skill that best sharpens the work:
+
+- `idea-refine`
+- `context-engineering`
+- `incremental-implementation`
+- `frontend-ui-engineering`
+- `api-and-interface-design`
+- `browser-testing-with-devtools`
+- `code-simplification`
+- `security-and-hardening`
+- `performance-optimization`
+- `git-workflow-and-versioning`
+- `ci-cd-and-automation`
+- `deprecation-and-migration`
+- `documentation-and-adrs`
+
+Load them because they improve the selected stage, not because they create a new public route.
+For domain families, cross-cutting guidance, and org-standard loading, see [`../../references/domain-skill-loading.md`](../../references/domain-skill-loading.md).
+
+## Platform Skill Loading
+
+After the primary AW route is known, use `using-platform-skills` when GHL platform behavior materially affects the stage.
+
+- backend and worker work -> `platform-services:*`
+- frontend and design-system work -> `platform-frontend:*` plus `platform-design:*`
+- data and migrations -> `platform-data:*`
+- infra and deploy paths -> `platform-infra:*`
+- test systems and QA governance -> `platform-sdet:*`
+- review depth and readiness -> `platform-review:*`
+- product context and business behavior -> `platform-product:*`
+
+Use `using-platform-skills` to decide the first supporting platform skills for the selected stage.
+
+## Context Loading
+
+Load context in the smallest order that reduces uncertainty without flooding the session.
+Start with repo-local contracts and approved AW artifacts before broad code search or domain docs.
+
+See [`../../references/context-loading-and-intake.md`](../../references/context-loading-and-intake.md).
+
+## Org Standards Always On
+
+When the selected stage falls inside a resolved baseline profile, the stage must honor:
+
+- `defaults/aw-sdlc/baseline-profiles.yml`
+- relevant platform playbooks
+- relevant `.aw_rules`
+
+Frontend work should still inherit HighRise, accessibility, responsive, and review expectations.
+Release work should still inherit governance, rollback, and evidence expectations.
+See [`../../references/domain-skill-loading.md`](../../references/domain-skill-loading.md).
+
+## Skill Rules
+
+1. Check for an applicable AW route before starting real work.
+2. Use one primary route unless the user explicitly asks for end-to-end orchestration.
+3. Load process skills before stage skills when the process itself changes the right path.
+4. Load domain and craft skills only after the primary route is clear.
+5. Load `using-platform-skills` when a GHL platform family materially changes the work.
+6. When in doubt between diagnosis and implementation, choose `/aw:investigate` only if root cause is still unclear.
+7. When in doubt between a normal route and `aw-yolo`, prefer the normal route.
+
+## Typical Sequences
+
+For a normal feature:
+
+```text
+/aw:plan -> /aw:build -> /aw:test -> /aw:review -> /aw:deploy -> /aw:ship
+```
+
+For a bug with unclear root cause:
+
+```text
+/aw:investigate -> /aw:build -> /aw:test -> /aw:review
+```
+
+For a release-ready change that only needs rollout work:
+
+```text
+/aw:deploy -> /aw:ship
+```
+
+For explicit one-run automation:
+
+```text
+aw-yolo -> [smallest correct internal stage sequence]
+```
+
+## Verification
+
+Before moving past routing, confirm:
+
+- [ ] the smallest correct AW skill stack was selected first
+- [ ] the public route matches the actual stage intent
+- [ ] `/aw:investigate` was only chosen when diagnosis is actually required
+- [ ] org-standard playbooks and `.aw_rules` are loaded when the baseline requires them
+- [ ] the task is not being silently broadened into extra stages
+- [ ] `aw-yolo` is used only when the user explicitly asked for end-to-end automation