aw-ecc 1.4.23 → 1.4.31

package/.cursor/skills/aw-execute/references/mode-migration.md

@@ -0,0 +1,58 @@
+# Mode: Migration — Staged Rollout
+
+## Process
+
+### 1. Script
+
+- Write the migration script. It MUST be **idempotent** — running it twice produces the same result.
+- Use `up()` and `down()` functions (or equivalent) for forward and rollback.
+- Include validation checks that confirm the migration was applied correctly.
+- Test the migration against a copy of production data (or realistic test data).
+
+### 2. Rollback
+
+- Every migration MUST have a rollback path.
+- Write the rollback script before applying the migration.
+- Test the rollback independently.
+- Document the rollback procedure in the migration file header.
+
+### 3. Validate
+
+- Run the migration in a test/staging environment first.
+- Verify data integrity after migration.
+- Check that dependent queries still work with the new schema.
+- Confirm indexes are in place before queries execute.
+
+### 4. Commit
+
+- Commit migration files with `migration:` or `feat:` prefix.
+- Include the rollback script in the same commit.
+- Document the migration in the PR description.
+
+## Rules
+
+### Indexes
+
+- **Deploy indexes BEFORE** deploying schema or query changes that use them.
+- Use `background: true` for index creation (or rely on MongoDB 4.2+ default).
+- Add compound indexes for multi-field queries — avoid multiple single-field indexes.
+- Scope all MongoDB queries by `locationId` (compound index required).
+
+### Fields
+
+- New fields MUST have default values or be nullable — never break existing documents.
+- Remove fields in two phases: (1) stop writing, (2) remove after migration window.
+- Never rename fields in a single migration — add new, migrate data, remove old.
+
+### Secrets
+
+- Never store secrets in migration scripts.
+- Use environment variables or GCP Secret Manager for connection strings.
+- Never log sensitive data during migration (PII, credentials, tokens).
+
+### Data Safety
+
+- Back up the collection/table before running destructive migrations.
+- Use transactions where available for multi-document updates.
+- Set reasonable batch sizes for bulk operations — avoid OOM.
+- Log progress for long-running migrations (every N records).

package/.cursor/skills/aw-execute/references/worker-implementer.md

@@ -0,0 +1,26 @@
+# Worker Role: Implementer
+
+## Objective
+
+Own one bounded task unit from the approved AW execution inputs.
+Change only the smallest correct file set for that unit.
+
+## Inputs
+
+- approved feature inputs from `.aw_docs/features/<feature_slug>/`
+- current task-unit bundle
+- repo-local AW execution contract
+
+## Required Behavior
+
+1. confirm the task-unit goal and file scope
+2. capture the RED or failure-first signal when behavior changes
+3. implement the smallest correct GREEN change
+4. record handoff notes for spec and quality review
+5. stop when the task unit is complete or blocked
+
+## Hard Gates
+
+- do not widen the write scope without naming why
+- do not skip runnable tests silently
+- do not mark the task done without concrete notes for the next review roles

package/.cursor/skills/aw-execute/references/worker-parallel-worker.md

@@ -0,0 +1,23 @@
+# Worker Role: Parallel Worker
+
+## Objective
+
+Execute one task unit that has already been marked `parallel_candidate` with a disjoint write scope.
+The orchestrator should keep active parallel workers within the configured cap, which defaults to `3`.
+
+## Inputs
+
+- current task-unit bundle
+- declared disjoint write scope
+- repo-local AW execution contract
+
+## Required Behavior
+
+1. stay inside the declared write scope
+2. keep notes concise so the merge-back step can reconcile outputs cleanly
+3. stop immediately if the work crosses into another worker's files
+
+## Hard Gates
+
+- do not edit shared files outside the declared scope
+- do not claim a task unit is parallel-safe if overlap was discovered during execution

package/.cursor/skills/aw-execute/references/worker-quality-reviewer.md

@@ -0,0 +1,23 @@
+# Worker Role: Quality Reviewer
+
+## Objective
+
+Check maintainability, reliability, and stage readiness for one completed task unit.
+
+## Inputs
+
+- implementer handoff notes
+- spec review outcome
+- current task-unit bundle
+
+## Required Behavior
+
+1. inspect the changed files and local validation notes
+2. flag maintainability or reliability issues that would block handoff
+3. state `pass`, `pass_with_notes`, or `fail`
+4. hand back the smallest concrete repair scope when failing
+
+## Hard Gates
+
+- do not reopen planning
+- do not wave through unresolved reliability or validation gaps

package/.cursor/skills/aw-execute/references/worker-spec-reviewer.md

@@ -0,0 +1,23 @@
+# Worker Role: Spec Reviewer
+
+## Objective
+
+Check one completed task unit against the approved AW inputs before the stage can move forward.
+
+## Inputs
+
+- approved feature inputs from `.aw_docs/features/<feature_slug>/`
+- implementer handoff notes
+- current task-unit bundle
+
+## Required Behavior
+
+1. compare the implementation against the approved task-unit goal
+2. flag scope drift or missed acceptance criteria
+3. state `pass`, `pass_with_notes`, or `fail`
+4. hand back the smallest concrete repair scope when failing
+
+## Hard Gates
+
+- do not invent new product scope
+- do not approve a task unit that skipped a required acceptance point

package/.cursor/skills/aw-execute/scripts/build-worker-bundle.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function usage() {
+  console.error(
+    'Usage: node skills/aw-execute/scripts/build-worker-bundle.js --feature <slug> --tasks-file <path> [--output <path>] [--allow-parallel] [--max-parallel-workers <n>]'
+  );
+}
+
+function parseArgs(argv) {
+  const args = {
+    allowParallel: false,
+    maxParallelWorkers: 3,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+    if (current === '--allow-parallel') {
+      args.allowParallel = true;
+      continue;
+    }
+
+    if (!current.startsWith('--')) {
+      throw new Error(`Unexpected argument: ${current}`);
+    }
+
+    const next = argv[index + 1];
+    if (!next || next.startsWith('--')) {
+      throw new Error(`Missing value for ${current}`);
+    }
+
+    if (current === '--feature') {
+      args.featureSlug = next;
+    } else if (current === '--tasks-file') {
+      args.tasksFile = next;
+    } else if (current === '--output') {
+      args.output = next;
+    } else if (current === '--max-parallel-workers') {
+      const parsedValue = Number(next);
+      if (!Number.isInteger(parsedValue) || parsedValue < 1) {
+        throw new Error('--max-parallel-workers must be a positive integer');
+      }
+      args.maxParallelWorkers = parsedValue;
+    } else {
+      throw new Error(`Unknown argument: ${current}`);
+    }
+
+    index += 1;
+  }
+
+  if (!args.featureSlug || !args.tasksFile) {
+    usage();
+    throw new Error('--feature and --tasks-file are required');
+  }
+
+  return args;
+}
+
+function toPosixPath(value) {
+  return value.split(path.sep).join('/');
+}
+
+function parseTaskUnits(content) {
+  const units = [];
+
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:- \[[ xX]\]|-|\*|\d+\.)\s+(.+?)\s*$/);
+    if (!match) {
+      continue;
+    }
+
+    const title = match[1].trim();
+    if (!title) {
+      continue;
+    }
+
+    units.push(title);
+  }
+
+  if (units.length === 0) {
+    throw new Error('No task units found in tasks file');
+  }
+
+  return units;
+}
+
+function buildRolePrompt({ roleGuide, featureSlug, taskUnitTitle, tasksFilePath, roleName }) {
+  return [
+    `Load role guide: ${roleGuide}`,
+    `Feature slug: ${featureSlug}`,
+    `Task unit: ${taskUnitTitle}`,
+    `Approved task source: ${tasksFilePath}`,
+    `Role: ${roleName}`,
+    'Stay within the repo-local AW execute contract and keep the scope bounded.',
+  ].join('\n');
+}
+
+function buildBundle({ featureSlug, tasksFilePath, allowParallel, maxParallelWorkers, repoRoot }) {
+  const taskUnits = parseTaskUnits(fs.readFileSync(tasksFilePath, 'utf8'));
+  const referencePaths = {
+    implementer: 'skills/aw-execute/references/worker-implementer.md',
+    spec_reviewer: 'skills/aw-execute/references/worker-spec-reviewer.md',
+    quality_reviewer: 'skills/aw-execute/references/worker-quality-reviewer.md',
+    parallel_worker: 'skills/aw-execute/references/worker-parallel-worker.md',
+  };
+
+  const relativeTasksFile = toPosixPath(path.relative(repoRoot, tasksFilePath) || path.basename(tasksFilePath));
+  const bundle = {
+    schema_version: 'aw.execute.worker-bundle.v1',
+    feature_slug: featureSlug,
+    generated_at: new Date().toISOString(),
+    source_tasks_file: relativeTasksFile,
+    role_reference_paths: referencePaths,
+    task_units: taskUnits.map((title, index) => {
+      const taskUnitId = `task-${index + 1}`;
+      const parallelCandidate = allowParallel && taskUnits.length > 1;
+
+      const taskUnit = {
+        id: taskUnitId,
+        title,
+        parallel_candidate: parallelCandidate,
+        roles: {
+          implementer: {
+            reference_path: referencePaths.implementer,
+            prompt: buildRolePrompt({
+              roleGuide: referencePaths.implementer,
+              featureSlug,
+              taskUnitTitle: title,
+              tasksFilePath: relativeTasksFile,
+              roleName: 'implementer',
+            }),
+          },
+          spec_reviewer: {
+            reference_path: referencePaths.spec_reviewer,
+            prompt: buildRolePrompt({
+              roleGuide: referencePaths.spec_reviewer,
+              featureSlug,
+              taskUnitTitle: title,
+              tasksFilePath: relativeTasksFile,
+              roleName: 'spec_reviewer',
+            }),
+          },
+          quality_reviewer: {
+            reference_path: referencePaths.quality_reviewer,
+            prompt: buildRolePrompt({
+              roleGuide: referencePaths.quality_reviewer,
+              featureSlug,
+              taskUnitTitle: title,
+              tasksFilePath: relativeTasksFile,
+              roleName: 'quality_reviewer',
+            }),
+          },
+        },
+      };
+
+      if (parallelCandidate) {
+        taskUnit.roles.parallel_worker = {
+          reference_path: referencePaths.parallel_worker,
+          prompt: buildRolePrompt({
+            roleGuide: referencePaths.parallel_worker,
+            featureSlug,
+            taskUnitTitle: title,
+            tasksFilePath: relativeTasksFile,
+            roleName: 'parallel_worker',
+          }),
+        };
+      }
+
+      return taskUnit;
+    }),
+    orchestration_plan: allowParallel
+      ? {
+          sessionName: `aw-execute-${featureSlug}`,
+          repoRoot,
+          baseRef: 'HEAD',
+          max_parallel_workers: maxParallelWorkers,
+          seedPaths: [
+            'skills/aw-execute/scripts/build-worker-bundle.js',
+            ...Object.values(referencePaths),
+          ],
+          launcherCommand: 'codex exec --skip-git-repo-check "$(cat {task_file_sh})"',
+          workers: taskUnits.map((title, index) => ({
+            name: `implementer-task-${index + 1}`,
+            task: buildRolePrompt({
+              roleGuide: referencePaths.parallel_worker,
+              featureSlug,
+              taskUnitTitle: title,
+              tasksFilePath: relativeTasksFile,
+              roleName: 'parallel_worker',
+            }),
+          })),
+        }
+      : null,
+  };
+
+  return bundle;
+}
+
+function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const repoRoot = process.cwd();
+    const tasksFilePath = path.resolve(repoRoot, args.tasksFile);
+    const outputPath = args.output ? path.resolve(repoRoot, args.output) : null;
+    const bundle = buildBundle({
+      featureSlug: args.featureSlug,
+      tasksFilePath,
+      allowParallel: args.allowParallel,
+      maxParallelWorkers: args.maxParallelWorkers,
+      repoRoot,
+    });
+
+    const payload = `${JSON.stringify(bundle, null, 2)}\n`;
+    if (outputPath) {
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+      fs.writeFileSync(outputPath, payload, 'utf8');
+    } else {
+      process.stdout.write(payload);
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+main();

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

@@ -0,0 +1,111 @@
+---
+name: aw-finish
+description: Internal compatibility helper for completing a verified development branch with explicit merge, PR, keep, or discard choices and safe worktree cleanup.
+trigger: Internal only. Invoked when verified branch work is done and the next step is a branch-completion decision rather than a staging deployment.
+---
+
+# AW Finish
+
+`aw-finish` is a legacy compatibility skill.
+The canonical public release stage remains `/aw:deploy`, but this helper still owns the branch-completion decision flow when that workflow is needed internally.
+
+## Hard Gate
+
+`aw-test` and `aw-review` must have passed before this skill runs, or the compatibility umbrella must have recorded an equivalent verified outcome.
+If verification failed, route back to `aw-build`, `aw-test`, or `aw-review` instead of finishing.
+
+## Purpose
+
+Use this skill to close out verified branch work safely:
+
+- verify tests before offering completion choices
+- present explicit branch-completion options
+- execute the selected path
+- clean up the worktree only when appropriate
+
+If `.aw_docs/features/<feature_slug>/workspace.json` exists, use it as the source of truth for:
+
+- the active branch and worktree path
+- cleanup policy
+- orchestration coordination directory
+- the recommended `node scripts/orchestration-status.js ...` status command
+
+Staging or production deployment requests should stay on `aw-deploy`.
+
+## Deprecation Timeline
+
+This skill is still active internally even though `/aw:finish` is deprecated as a public entrypoint.
+Keep `aw-finish` available until `/aw:deploy` fully absorbs branch-completion choices, workspace metadata reuse, and cleanup behavior.
+Public deprecation must not be interpreted as immediate removal of the internal helper.
+
+## Completion Flow
+
+1. verify tests and validation signals still pass
+2. determine the base branch
+3. present exactly these choices:
+   - merge locally
+   - push and create PR
+   - keep as branch
+   - discard
+4. execute the selected path
+5. clean up the worktree when the selected path requires cleanup
+6. update or clear `workspace.json` to reflect the final cleanup decision
+
+## Required Options
+
+### Option 1: Merge Locally
+
+- switch to base branch
+- update from remote when appropriate
+- merge the verified branch
+- rerun the minimum correct verification
+- remove the branch or worktree when safe
+- clear `workspace.json` when cleanup completed successfully
+
+### Option 2: Push and Create PR
+
+- push the branch
+- create or update the PR with concise summary and test plan
+- keep the worktree if the branch remains active
+- preserve `workspace.json` for the active branch lifecycle
+
+### Option 3: Keep As-Is
+
+- keep the branch and worktree intact
+- report the branch name and next expected action
+- keep `workspace.json` intact for follow-up work
+
+### Option 4: Discard
+
+- require explicit confirmation
+- delete the branch or worktree only after confirmation
+- remove `workspace.json` only after cleanup succeeds
+
+## Worktree Cleanup Rule
+
+Only clean up the worktree automatically for:
+
+- merge-complete paths
+- confirmed discard paths
+
+Do not clean up the worktree for:
+
+- keep-as-branch
+- PR-open workflows where the branch is still in active use
+
+## Hard Gates
+
+- do not offer completion choices until tests are rechecked
+- do not discard work without explicit confirmation
+- do not turn branch completion into deployment orchestration
+- do not clean up an active PR worktree by accident
+
+## Final Output Shape
+
+Always end with:
+
+- `Verification Check`
+- `Base Branch`
+- `Completion Options`
+- `Selected Path`
+- `Cleanup Decision`

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

@@ -0,0 +1,109 @@
+---
+name: aw-investigate
+description: Reproduce, localize, and confirm bugs, alerts, and regressions before broad fixes are attempted.
+trigger: User requests bug investigation, alert triage, root-cause analysis, or a legacy fix request arrives without a trustworthy cause.
+---
+
+# AW Investigate
+
+## Overview
+
+`aw-investigate` is the public debugging and triage stage.
+It turns vague failure into concrete evidence, a likely fault surface, and a clear next step.
+
+## When to Use
+
+- root cause is unclear
+- the request starts from an alert, failure, log, or regression report
+- repeated fix attempts have already happened
+- the right next step might be "gather more evidence," not "change code"
+
+Do not use once the cause is already clear and implementation is ready.
+
+## Workflow
+
+1. Capture the failure signal.
+   Record the trigger, expected behavior, actual behavior, and current blast radius.
+2. Reproduce or isolate.
+   Use `aw-debug` and `../../references/debug-triage.md`.
+   For browser-visible issues, load `browser-testing-with-devtools`.
+   Prefer the smallest confirming probe over speculative patching.
+3. Load the right org-standard context.
+   Pull in relevant platform services, frontend, data, or infra playbooks.
+   For incident-style problems, load observability or log-analysis helpers as needed.
+4. Narrow the fault surface.
+   Identify the smallest plausible layer, file set, or dependency boundary.
+5. Decide the next stage.
+   If the cause is concrete enough, hand off to `aw-build` and name the exact starting slice or repair surface.
+   If the work still needs proof, stay in investigation and name the next probe explicitly instead of pausing with a vague "needs more digging" note.
+6. Persist the evidence.
+   Write `investigation.md` and update `state.json` with completed probes, open questions, and the recommended next command.
+
+## Completion Contract
+
+Investigation is complete only when one of these is true:
+
+- the likely fault surface is concrete enough for `aw-build`
+- the next probe is explicit enough for another investigation pass to continue without rediscovery
+- the work is blocked and the blocker is named clearly
+
+Every investigation handoff must make these things obvious:
+
+- what was reproduced
+- which probes were completed
+- what remains uncertain
+- which exact next command or next probe should run next
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I already know the likely fix." | Likely is not the same as confirmed. |
+| "The third patch will probably work." | Repeated speculative fixes are a debugging failure. |
+| "I don't need logs or runtime evidence for this." | Alerts and regressions need concrete signals, not memory. |
+
+## Red Flags
+
+- fix attempts outnumber confirming probes
+- the failure is described only in prose, not evidence
+- the blast radius is guessed instead of scoped
+- the next action is "try another patch" instead of "run the next probe"
+
+## State File
+
+`state.json` should record at least:
+
+- `feature_slug`
+- `stage: "investigate"`
+- `mode`
+- `status`
+- written artifacts
+- completed probes
+- commands run
+- likely fault surface
+- open questions
+- blockers
+- recommended next commands
+
+## Verification
+
+Before leaving investigate, confirm:
+
+- [ ] reproduction or equivalent failure signal is captured
+- [ ] expected vs actual behavior is explicit
+- [ ] the likely fault surface is concrete enough to guide build
+- [ ] the next stage is clear: build, more investigation, or blocked
+- [ ] `investigation.md` and `state.json` are updated
+
+## Final Output Shape
+
+Always end with:
+
+- `Mode`
+- `Reproduction`
+- `Expected vs Actual`
+- `Evidence`
+- `Completed Probes`
+- `Likely Fault Surface`
+- `Open Questions`
+- `Next`