aw-ecc 1.4.21

package/skills/aw-rules/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: aw-rules
+description: Create, audit, fix, and score .aw_rules reference files grounded in real platform docs, skills, and codebase. Use when adding new rules, reviewing rule PRs, checking for hallucinated APIs, or improving rule quality.
+trigger: when the user says /aw-rules, asks to create/add/audit/verify/fix/score rules, check rules for hallucinations, or manage .aw_rules content
+---
+
+# .aw_rules — Create, Audit, Fix, Score
+
+Full lifecycle management for `.aw_rules/` reference files. Every code example must be verified against real platform docs, skills, and repos — never hallucinated.
+
+## When to Use
+
+- **Create**: Adding a new rule to `.aw_rules/platform/<domain>/references/`
+- **Audit**: Verifying existing rules against real docs before merging a PR
+- **Fix**: Correcting hallucinated APIs, fabricated URLs, wrong patterns
+- **Score**: Rating rule quality against the rubric
+
+## Commands
+
+```
+/aw-rules create backend/new-rule     # Create a new verified rule
+/aw-rules audit backend               # Audit one domain
+/aw-rules audit all                   # Audit all domains
+/aw-rules audit all --fix             # Audit + auto-fix
+/aw-rules score backend               # Score rules against quality rubric
+```
+
+---
+
+## Create Workflow
+
+1. **Identify the canonical source** — find the pattern in platform skills or docs first
+2. **Read the source** — `.aw_registry/platform/docs/<domain>/` or `skills/<slug>/SKILL.md`
+3. **If uncertain** — `gh search code "<pattern>" --owner GoHighLevel --limit 10`
+4. **Write the rule** using WRONG/RIGHT format (~40 lines max):
+
+```markdown
+---
+id: <domain>/<rule-name>
+severity: MUST|SHOULD|MAY
+domains: [<domain>]
+paths: ["**/<glob-patterns>"]
+---
+
+# <Rule Title>
+
+## Rule
+
+<One sentence — what is required and why.>
+
+## WRONG
+
+\`\`\`typescript
+// The violation
+\`\`\`
+
+## RIGHT
+
+\`\`\`typescript
+// The fix — verified against platform docs/skills
+\`\`\`
+
+> Full details: [<skill-link>](/platform/<domain>/skills/<slug>)
+```
+
+5. **Add to manifest.json** — id, severity, domains, rule path, description, principle
+6. **Add one-liner to domain AGENTS.md**
+7. **Self-audit** — run the 5-check verification below
+
+---
+
+## Audit Workflow
+
+For each reference file, check 5 things:
+
+| Check | How | Common Failures |
+|-------|-----|-----------------|
+| **Import paths** | Grep in skills + real repos | `@highrise/components` -> `@platform-ui/highrise` |
+| **API patterns** | Read skill's SKILL.md | `v-model` -> `v-model:value` for HL |
+| **URLs/paths** | Verify exist on disk or in repos | Fabricated git URLs, wrong module paths |
+| **CLI commands** | Check docs for actual tools | `helm rollback` -> Jenkins pipeline |
+| **Deprecated** | Search docs for deprecation | KEDA -> deprecated |
+
+### Verification chain (per pattern)
+
+```
+1. Read the rule file
+2. Read the linked skill (follow reference link at bottom)
+3. Read platform docs (.aw_registry/platform/docs/<domain>/)
+4. If uncertain: gh search code "<pattern>" --owner GoHighLevel --limit 10
+5. Verdict: CORRECT / WRONG (with fix) / UNVERIFIABLE
+```
+
+---
+
+## Score Rubric
+
+| Dimension | 0 | 5 | 10 |
+|-----------|---|---|-----|
+| Frontmatter | Missing | id + severity | id + severity + domains + paths |
+| Rule statement | Missing | Vague | One clear sentence |
+| WRONG example | Missing | Generic | Real violation from GHL code |
+| RIGHT example | Missing | Generic | Verified against skill/docs |
+| Skill link | Missing | Wrong link | Correct link, skill exists |
+
+**Score = /50 per file. Target: 40+.**
+
+---
+
+## Output Format
+
+```markdown
+## Audit: <domain>/<file>.md
+
+| Line | Content | Verdict | Evidence |
+|------|---------|---------|----------|
+| 12 | `@platform-core/base-worker` | CORRECT | worker-patterns skill |
+| 20 | `git::github.com/ghl/...` | WRONG | Real: `../modules/frontend-apps-infra` |
+
+### Summary
+- Files: 5 | CORRECT: 12 | WRONG: 3 | UNVERIFIABLE: 1
+```
+
+---
+
+## References
+
+- [verification-sources.md](references/verification-sources.md) — Where to look per domain
+- [known-hallucinations.md](references/known-hallucinations.md) — Catalog of AI-fabricated patterns found in GHL rules

package/skills/aw-rules/references/known-hallucinations.md

@@ -0,0 +1,43 @@
+# Known Hallucination Patterns
+
+AI-generated `.aw_rules/` content commonly fabricates these patterns. Check for them first.
+
+## Package Names
+
+| Hallucinated | Real |
+|-------------|------|
+| `@highrise/components` | `@platform-ui/highrise` |
+| `@platform-core/auth` | `@platform-core/iam-v2` |
+| `@platform-core/workers` | `@platform-core/base-worker` |
+| `HlButton` (lowercase l) | `HLButton` (uppercase L) |
+
+## API Patterns
+
+| Hallucinated | Real |
+|-------------|------|
+| `v-model` on HL inputs | `v-model:value` |
+| `v-model:open` on modals | `v-model:show` |
+| `IamGuard` decorator | `IAM.auth(req, authConfigs)` |
+| `@UseGuards(IamGuard)` import from package | Teams create own guard wrapping `IAM.auth()` |
+| `readonly topic/subscription` on BaseWorker | `getSubscriptionName()` method |
+| `processMessage(): Promise<void>` | `processMessage(): Promise<{ success: boolean; error: any }>` |
+
+## Infrastructure
+
+| Hallucinated | Real |
+|-------------|------|
+| `git::github.com/ghl/terraform-platform-modules` | Local `../modules/frontend-apps-infra` |
+| `data.google_secret_manager_secret_version` for secrets | `secrets:` block in values.yaml (Helm fetches) |
+| `helm rollback contacts-api 0` | `Deployment-Revision-Rollback` Jenkins pipeline |
+| `kubectl patch service` for blue-green | Jenkins `DeploymentOption` parameter |
+| `/health/live`, `/health/ready` as defaults | Default probe path is `/` on port `6050` |
+| KEDA `ScaledObject` recommended | KEDA is deprecated — use `peakLoad.peakLoadMinReplicas` |
+| `docker build -t ...` in Jenkinsfile | `marketplace_backend_base()` shared library function |
+
+## Observability
+
+| Hallucinated | Real |
+|-------------|------|
+| Cloud Logging → log-based metrics | Prometheus → Mimir → Grafana |
+| PagerDuty alerts | Unverified — no docs confirm |
+| `@platform-core/observability` (no version) | `@platform-core/observability>=4.0.0` |

package/skills/aw-rules/references/verification-sources.md

@@ -0,0 +1,50 @@
+# Verification Sources by Domain
+
+Where to look when validating a rule file's code examples and patterns.
+
+## Backend
+
+| Pattern | Verify Against |
+|---------|---------------|
+| `@platform-core/logger` | `platform/services/skills/structured-logging/SKILL.md` |
+| `@platform-core/base-worker` | `platform/services/skills/worker-patterns/SKILL.md` |
+| `@platform-core/iam-v2` | `platform/services/skills/authentication-authorization/SKILL.md` |
+| NestJS module structure | `platform/services/skills/development/SKILL.md` |
+| class-validator DTOs | `platform/services/skills/development/SKILL.md` |
+
+## Frontend
+
+| Pattern | Verify Against |
+|---------|---------------|
+| `@platform-ui/highrise` components | `platform/frontend/skills/highrise-compliance/SKILL.md` |
+| `v-model:value`, `v-model:show` | `platform/frontend/skills/highrise-compliance/references/` |
+| `@tanstack/vue-query` | `platform/frontend/skills/vue-development/references/query-store-pattern.md` |
+| Vue 3 Composition API | `platform/frontend/skills/vue-development/SKILL.md` |
+| `@platform-ui/sentry` | `platform/frontend/skills/vue-development/SKILL.md` |
+
+## Infra
+
+| Pattern | Verify Against |
+|---------|---------------|
+| Helm values (resources, probes) | `platform/docs/infra/how-to/server/values-server.md` |
+| Worker values | `platform/docs/infra/how-to/worker/` |
+| Terraform modules | `platform/docs/infra/how-to/terraform-for-frontend-apps.md` |
+| Jenkins shared library | `platform/docs/infra/how-is-this-working/jenkins-library.md` |
+| Blue-green deploy | `platform/docs/infra/blue-green/` |
+| Secret management | `platform/docs/infra/how-to/secret-management.md` |
+| Rollback | `platform/docs/infra/how-to/how-to-revision-rollback-deployments.md` |
+| KEDA (deprecated) | `platform/docs/infra/how-to/how-to-use-keda-autoscaling.md` |
+
+## Security
+
+| Pattern | Verify Against |
+|---------|---------------|
+| IAM v2 auth | `platform/services/skills/authentication-authorization/SKILL.md` |
+| DOMPurify | `platform/frontend/skills/vue-development/SKILL.md` |
+
+## Data
+
+| Pattern | Verify Against |
+|---------|---------------|
+| Mongoose v8 schemas | `platform/data/skills/mongodb-patterns/SKILL.md` |
+| Redis patterns | `platform/data/skills/redis-patterns/SKILL.md` |

package/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/skills/aw-spec/SKILL.md

@@ -0,0 +1,128 @@
+---
+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.
+   Perform an explicit architecture review before freezing the technical path.
+   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, assumptions, constraints, rollout constraints, and failure modes.
+   Record non-goals, compatibility rules, and operator-facing observability or debugging constraints when they matter.
+   Document the current state, alternatives considered, and the reason the chosen design wins.
+   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 or inventing missing contracts.
+5. Run a fast review pass.
+   Fix placeholders, contradictions, scope drift, ambiguous names, and missing assumption, testing, or rollout detail 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
+- current state and existing patterns that the change should respect or replace
+- scope and non-goals
+- assumptions and constraints
+- architecture or technical approach
+- architecture rationale for non-obvious decisions
+- decision and alternatives considered for major technical choices
+- non-functional requirements when relevant: performance, security, scalability, availability
+- interfaces, contracts, or integration points
+- invariants and backward-compatibility rules when relevant
+- component or data-flow responsibilities when they are non-trivial
+- expected file or module map when it can be inferred safely
+- failure modes and rollback constraints
+- observability, debugging, or operator-facing constraints when relevant
+- risks and mitigations when they materially affect implementation order
+- testing strategy
+- acceptance criteria
+- verification targets
+- operations and rollback verification when relevant
+- ADR-needed decision when the change has durable architectural impact
+- 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
+- a major design choice has no alternatives or rationale recorded
+- testing strategy is implied instead of stated
+- 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. spec coverage check against the approved direction
+2. placeholder scan
+3. internal consistency check (including naming)
+4. scope check (including decomposition)
+5. assumptions, constraints, and rollout completeness check
+6. alternatives and decision-rationale check
+7. testing and operations completeness check
+8. 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`
+- `Decision & Alternatives`
+- `Testing Strategy`
+- `Assumptions & Constraints`
+- `Acceptance Criteria`
+- `Open Approval Needs`
+- `Recommended Next`

package/skills/aw-tasks/SKILL.md

@@ -0,0 +1,155 @@
+---
+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, expected review mode when it is known safely, and any bounded parallel execution metadata.
+   For behavior-changing slices, default to explicit `RED -> GREEN -> REFACTOR` steps instead of generic "write tests" guidance.
+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 RED test
+- run it to verify it fails for the expected reason
+- write the minimal implementation
+- rerun the exact command to verify GREEN
+- refactor or simplify while keeping the same proof green
+- 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
+- assumptions or constraints that materially affect execution
+- 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
+- explicit RED and GREEN commands with expected outcomes for behavior-changing slices
+- 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
+
+For behavior-changing work, tasks should not say only "add tests" or "verify it works."
+They should spell out:
+
+- RED command and expected failure
+- GREEN command and expected pass
+- refactor or simplification expectation after GREEN
+
+If test-first is not meaningful for a slice, say why and provide the best pre-change proof plus focused post-change validation instead.
+
+## 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
+- behavior-changing work lacks explicit RED and GREEN proof
+- 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 behavior-changing slices use explicit `RED -> GREEN -> REFACTOR` wording or explicitly justify why test-first is not meaningful
+6. confirm the execution mode and review mode are clear when they can be known safely
+7. 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`
+- `Review Mode`
+- `Parallel Candidates`
+- `Review Result`
+- `Recommended Next`