aw-ecc 1.4.21 → 1.4.25
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex/hooks/aw-post-tool-use.sh +1 -0
- package/.codex/hooks/aw-pre-tool-use.sh +1 -0
- package/.codex/hooks/aw-session-start.sh +4 -0
- package/.codex/hooks/aw-stop.sh +1 -0
- package/.codex/hooks/aw-user-prompt-submit.sh +1 -0
- package/.cursor/INSTALL.md +9 -0
- package/.cursor/hooks/adapter.js +34 -3
- package/.cursor/hooks/aw-phase-definitions.js +11 -0
- package/.cursor/hooks/before-submit-prompt.js +1 -1
- package/.cursor/hooks/before-submit-prompt.sh +17 -0
- package/.cursor/hooks/session-start.sh +36 -0
- package/.cursor/hooks/shared/aw-phase-definitions.js +1 -19
- package/.cursor/hooks/shared/aw-phase-runner.js +38 -2
- package/.cursor/hooks/shared/session-start.sh +4 -0
- package/.cursor/hooks/shared/user-prompt-submit.sh +33 -140
- package/.cursor/hooks.json +15 -15
- package/.cursor/rules/common-aw-routing.md +43 -0
- package/.cursor/skills/api-and-interface-design/SKILL.md +75 -0
- package/.cursor/skills/aw-brainstorm/SKILL.md +115 -0
- package/.cursor/skills/aw-build/SKILL.md +152 -0
- package/.cursor/skills/aw-build/evals/build-stage-cases.json +28 -0
- package/.cursor/skills/aw-debug/SKILL.md +49 -0
- package/.cursor/skills/aw-deploy/SKILL.md +101 -0
- package/.cursor/skills/aw-deploy/evals/deploy-stage-cases.json +32 -0
- package/.cursor/skills/aw-execute/SKILL.md +47 -0
- package/.cursor/skills/aw-execute/references/mode-code.md +47 -0
- package/.cursor/skills/aw-execute/references/mode-docs.md +28 -0
- package/.cursor/skills/aw-execute/references/mode-infra.md +44 -0
- package/.cursor/skills/aw-execute/references/mode-migration.md +58 -0
- package/.cursor/skills/aw-execute/references/worker-implementer.md +26 -0
- package/.cursor/skills/aw-execute/references/worker-parallel-worker.md +23 -0
- package/.cursor/skills/aw-execute/references/worker-quality-reviewer.md +23 -0
- package/.cursor/skills/aw-execute/references/worker-spec-reviewer.md +23 -0
- package/.cursor/skills/aw-execute/scripts/build-worker-bundle.js +229 -0
- package/.cursor/skills/aw-finish/SKILL.md +111 -0
- package/.cursor/skills/aw-investigate/SKILL.md +109 -0
- package/.cursor/skills/aw-plan/SKILL.md +368 -0
- package/.cursor/skills/aw-prepare/SKILL.md +118 -0
- package/.cursor/skills/aw-review/SKILL.md +118 -0
- package/.cursor/skills/aw-ship/SKILL.md +115 -0
- package/.cursor/skills/aw-spec/SKILL.md +104 -0
- package/.cursor/skills/aw-tasks/SKILL.md +138 -0
- package/.cursor/skills/aw-test/SKILL.md +118 -0
- package/.cursor/skills/aw-verify/SKILL.md +51 -0
- package/.cursor/skills/aw-yolo/SKILL.md +111 -0
- package/.cursor/skills/browser-testing-with-devtools/SKILL.md +81 -0
- package/.cursor/skills/ci-cd-and-automation/SKILL.md +71 -0
- package/.cursor/skills/code-simplification/SKILL.md +74 -0
- package/.cursor/skills/context-engineering/SKILL.md +74 -0
- package/.cursor/skills/deprecation-and-migration/SKILL.md +75 -0
- package/.cursor/skills/documentation-and-adrs/SKILL.md +75 -0
- package/.cursor/skills/frontend-ui-engineering/SKILL.md +68 -0
- package/.cursor/skills/git-workflow-and-versioning/SKILL.md +75 -0
- package/.cursor/skills/idea-refine/SKILL.md +84 -0
- package/.cursor/skills/incremental-implementation/SKILL.md +75 -0
- package/.cursor/skills/performance-optimization/SKILL.md +77 -0
- package/.cursor/skills/security-and-hardening/SKILL.md +70 -0
- package/.cursor/skills/using-aw-skills/SKILL.md +290 -0
- package/.cursor/skills/using-aw-skills/evals/skill-trigger-cases.tsv +25 -0
- package/.cursor/skills/using-aw-skills/evals/test-skill-triggers.sh +171 -0
- package/.cursor/skills/using-aw-skills/hooks/hooks.json +9 -0
- package/.cursor/skills/using-aw-skills/hooks/session-start.sh +67 -0
- package/.cursor/skills/using-platform-skills/SKILL.md +163 -0
- package/.cursor/skills/using-platform-skills/evals/platform-selection-cases.json +52 -0
- package/.opencode/package.json +1 -1
- package/package.json +3 -1
- package/scripts/cursor-aw-home/hooks.json +15 -15
- package/scripts/cursor-aw-hooks/adapter.js +34 -3
- package/scripts/cursor-aw-hooks/aw-phase-definitions.js +11 -0
- package/scripts/cursor-aw-hooks/before-submit-prompt.js +1 -1
- package/scripts/cursor-aw-hooks/before-submit-prompt.sh +17 -0
- package/scripts/cursor-aw-hooks/session-start.sh +36 -0
- package/scripts/hooks/session-start-rules-context.sh +8 -1
- package/scripts/hooks/shared/aw-phase-definitions.js +1 -19
- package/scripts/hooks/shared/aw-phase-runner.js +38 -2
- package/scripts/hooks/shared/session-start.sh +4 -0
- package/scripts/hooks/shared/user-prompt-submit.sh +33 -140
- package/scripts/lib/cursor-aw-hook-files.js +2 -0
- package/scripts/lib/cursor-hook-config.js +47 -15
- package/scripts/lib/install-executor.js +7 -0
- package/scripts/lib/install-targets/cursor-project.js +7 -0
- package/skills/using-aw-skills/hooks/session-start.sh +4 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "AW global routing: use the AW router skill first, then apply org rules and references by domain"
|
|
3
|
+
alwaysApply: true
|
|
4
|
+
---
|
|
5
|
+
# AW Global Routing
|
|
6
|
+
|
|
7
|
+
- Before any substantive response, load `using-aw-skills` from `~/.cursor/skills/using-aw-skills/SKILL.md`.
|
|
8
|
+
- Select the smallest correct AW route first:
|
|
9
|
+
- `/aw:plan`
|
|
10
|
+
- `/aw:build`
|
|
11
|
+
- `/aw:investigate`
|
|
12
|
+
- `/aw:test`
|
|
13
|
+
- `/aw:review`
|
|
14
|
+
- `/aw:deploy`
|
|
15
|
+
- `/aw:ship`
|
|
16
|
+
- For non-trivial requests, the first substantive line should be `Selected AW Route: <route>`.
|
|
17
|
+
- After the route is known, load the matching AW stage skill from `~/.cursor/skills/` and only the smallest supporting skills needed.
|
|
18
|
+
|
|
19
|
+
## Org Rules
|
|
20
|
+
|
|
21
|
+
- Always read:
|
|
22
|
+
- `~/.aw_rules/platform/universal/AGENTS.md`
|
|
23
|
+
- `~/.aw_rules/platform/security/AGENTS.md`
|
|
24
|
+
- Then pick the smallest correct domain rule based on the requirement and current context, and read it before acting:
|
|
25
|
+
- `api-design` -> `~/.aw_rules/platform/api-design/AGENTS.md`
|
|
26
|
+
- `backend` -> `~/.aw_rules/platform/backend/AGENTS.md`
|
|
27
|
+
- `data` -> `~/.aw_rules/platform/data/AGENTS.md`
|
|
28
|
+
- `frontend` -> `~/.aw_rules/platform/frontend/AGENTS.md`
|
|
29
|
+
- `infra` -> `~/.aw_rules/platform/infra/AGENTS.md`
|
|
30
|
+
- `mobile` -> `~/.aw_rules/platform/mobile/AGENTS.md`
|
|
31
|
+
- `sdet` -> `~/.aw_rules/platform/sdet/AGENTS.md`
|
|
32
|
+
- Load `references/` under the chosen domain on demand when implementation details or canonical links matter.
|
|
33
|
+
- If repo-local instructions conflict with org-level AW rules, follow the org-level AW rules.
|
|
34
|
+
|
|
35
|
+
## Route Hints
|
|
36
|
+
|
|
37
|
+
- Ideas, architecture, specs, planning, new project setup, and database choice -> `/aw:plan`
|
|
38
|
+
- Implementation, bug fixing, and build work -> `/aw:build`
|
|
39
|
+
- Unclear failures, alerts, or root-cause hunting -> `/aw:investigate`
|
|
40
|
+
- QA proof, regression evidence, and validation -> `/aw:test`
|
|
41
|
+
- Findings, readiness, and approval decisions -> `/aw:review`
|
|
42
|
+
- One release action -> `/aw:deploy`
|
|
43
|
+
- Rollout, rollback readiness, and closeout -> `/aw:ship`
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: api-and-interface-design
|
|
3
|
+
description: Designs stable APIs and module boundaries. Use when changing public contracts, service interfaces, component props, or any boundary another system or team depends on.
|
|
4
|
+
origin: ECC
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# API and Interface Design
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
Design interfaces that are stable, documented, and hard to misuse.
|
|
12
|
+
This applies to REST and GraphQL APIs, TypeScript contracts, event payloads, component props, database-informed boundaries, and service-to-service interfaces.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- designing or changing API endpoints
|
|
17
|
+
- defining interfaces between modules, services, or teams
|
|
18
|
+
- shaping component props or shared library contracts
|
|
19
|
+
- planning data contracts that other code depends on
|
|
20
|
+
- changing existing public behavior that consumers may already rely on
|
|
21
|
+
|
|
22
|
+
**When NOT to use**
|
|
23
|
+
|
|
24
|
+
- the change is fully internal and does not cross a meaningful boundary
|
|
25
|
+
- the work is purely implementation with no contract implications
|
|
26
|
+
|
|
27
|
+
## Workflow
|
|
28
|
+
|
|
29
|
+
1. Name the boundary and its consumers first.
|
|
30
|
+
Clarify who consumes the interface and what kind of compatibility risk exists:
|
|
31
|
+
user clients, internal services, frontend callers, workers, or shared packages.
|
|
32
|
+
2. Define the contract before the implementation.
|
|
33
|
+
Write the request and response shape, error semantics, idempotency rules, and ordering guarantees before coding the handler.
|
|
34
|
+
Use `../../references/interface-stability.md` and `api-design` when the surface is HTTP-facing.
|
|
35
|
+
3. Treat observable behavior as part of the contract.
|
|
36
|
+
Apply Hyrum's Law thinking:
|
|
37
|
+
if consumers can observe it, they may depend on it.
|
|
38
|
+
Avoid leaking implementation details, inconsistent error patterns, or unstable defaults.
|
|
39
|
+
4. Validate at the boundary, not everywhere.
|
|
40
|
+
Validate user input, third-party responses, environment configuration, and external payloads where they enter the system.
|
|
41
|
+
Keep internal code paths simpler once the boundary is trusted.
|
|
42
|
+
5. Prefer extension over breaking change.
|
|
43
|
+
Add optional fields, new endpoints, new event versions, or adapters before removing or changing existing semantics.
|
|
44
|
+
If a breaking change is unavoidable, load `deprecation-and-migration`.
|
|
45
|
+
6. Record the long-lived design decision.
|
|
46
|
+
For important public or architectural contracts, update docs or ADRs through `documentation-and-adrs`.
|
|
47
|
+
In GHL- or AW-governed repos, align the contract with `.aw_rules`, platform APIs, and baseline expectations.
|
|
48
|
+
|
|
49
|
+
## Common Rationalizations
|
|
50
|
+
|
|
51
|
+
| Rationalization | Reality |
|
|
52
|
+
|---|---|
|
|
53
|
+
| "We can document the contract later." | The contract is the design. If it is unclear now, implementation will drift. |
|
|
54
|
+
| "Nobody depends on that behavior." | If it is observable, somebody eventually will. |
|
|
55
|
+
| "We can just support two versions forever." | Version sprawl multiplies maintenance and creates dependency pain. |
|
|
56
|
+
| "Validation everywhere is safer." | Boundary validation is safer and simpler than repeating checks throughout internal code. |
|
|
57
|
+
|
|
58
|
+
## Red Flags
|
|
59
|
+
|
|
60
|
+
- different endpoints or modules expose inconsistent error behavior
|
|
61
|
+
- breaking changes are introduced without migration or compatibility planning
|
|
62
|
+
- boundary validation is missing for user or third-party input
|
|
63
|
+
- implementation details leak into public behavior or naming
|
|
64
|
+
- the team cannot explain what part of the behavior is contract versus accident
|
|
65
|
+
|
|
66
|
+
## Verification
|
|
67
|
+
|
|
68
|
+
After designing or changing an interface, confirm:
|
|
69
|
+
|
|
70
|
+
- [ ] the consumers and compatibility surface are explicit
|
|
71
|
+
- [ ] the contract exists before or alongside implementation
|
|
72
|
+
- [ ] error semantics and validation boundaries are consistent
|
|
73
|
+
- [ ] additions were preferred over breaking changes where possible
|
|
74
|
+
- [ ] deprecation or migration is planned for any unavoidable break
|
|
75
|
+
- [ ] important interface decisions are documented for future engineers and agents
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: aw-brainstorm
|
|
3
|
+
description: Internal discovery helper that deepens pre-code exploration, compares approaches, and hands an approved direction to aw-plan without expanding the public command surface.
|
|
4
|
+
trigger: Internal only. Invoked by aw-plan or aw-ship when discovery is still too fuzzy for direct planning.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# AW Brainstorm
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
`aw-brainstorm` is an internal depth skill.
|
|
12
|
+
It should make the planning input sharper, not create a parallel public workflow or a second artifact system.
|
|
13
|
+
|
|
14
|
+
The canonical public route for planning remains `/aw:plan`.
|
|
15
|
+
|
|
16
|
+
## Hard Gate
|
|
17
|
+
|
|
18
|
+
No implementation code may be written while discovery is still open.
|
|
19
|
+
This skill stops at an approved direction and hands that direction to `aw-spec` through `aw-plan`.
|
|
20
|
+
In other words, the public handoff is still: invoke `aw-plan`.
|
|
21
|
+
|
|
22
|
+
## Discovery Loop
|
|
23
|
+
|
|
24
|
+
Use this loop only when direct planning would otherwise guess:
|
|
25
|
+
|
|
26
|
+
1. explore project context first:
|
|
27
|
+
- current files
|
|
28
|
+
- docs
|
|
29
|
+
- recent commits or adjacent artifacts when useful
|
|
30
|
+
2. decide whether the request is actually one feature or multiple independent subsystems
|
|
31
|
+
3. if the scope is too large for one spec, decompose it before detailed design work
|
|
32
|
+
4. identify the unknowns, assumptions, and decision points
|
|
33
|
+
5. ask at most one clarifying question at a time when a real decision is blocked
|
|
34
|
+
6. propose 2-3 distinct approaches with trade-offs
|
|
35
|
+
7. recommend one approach explicitly
|
|
36
|
+
8. present the proposed direction in a way the user can approve or correct
|
|
37
|
+
9. confirm the chosen direction or record the current best default
|
|
38
|
+
10. run a quick self-review for placeholders, contradictions, ambiguity, and overscope
|
|
39
|
+
11. hand the approved direction to `aw-spec` through `aw-plan`
|
|
40
|
+
|
|
41
|
+
## Scope Check
|
|
42
|
+
|
|
43
|
+
Before deepening the design, decide whether the request needs decomposition.
|
|
44
|
+
|
|
45
|
+
If the request spans multiple independent subsystems, do not force one giant planning artifact.
|
|
46
|
+
Break it into smaller spec-worthy scopes and continue with the smallest correct slice.
|
|
47
|
+
If the request is too large for one spec, decompose it before moving on.
|
|
48
|
+
|
|
49
|
+
## Design Expectations
|
|
50
|
+
|
|
51
|
+
Discovery should be concrete enough that the next planning step does not need to rediscover the core shape of the work.
|
|
52
|
+
|
|
53
|
+
Capture:
|
|
54
|
+
|
|
55
|
+
- problem framing
|
|
56
|
+
- purpose and success criteria
|
|
57
|
+
- constraints
|
|
58
|
+
- compared approaches
|
|
59
|
+
- chosen approach with rationale
|
|
60
|
+
- major risks
|
|
61
|
+
- non-goals
|
|
62
|
+
- the next planning artifact that should be written
|
|
63
|
+
|
|
64
|
+
If the topic is visual and the active harness supports it, a browser-based visual companion may be offered as its own message before visual questions.
|
|
65
|
+
|
|
66
|
+
## Required Output
|
|
67
|
+
|
|
68
|
+
Produce a discovery summary that `aw-plan` and `aw-spec` can consume without redoing the ideation step.
|
|
69
|
+
|
|
70
|
+
The summary should capture:
|
|
71
|
+
|
|
72
|
+
- problem framing
|
|
73
|
+
- assumptions and open questions
|
|
74
|
+
- compared approaches
|
|
75
|
+
- chosen approach with rationale
|
|
76
|
+
- major risks
|
|
77
|
+
- constraints and non-goals
|
|
78
|
+
- what planning artifact should come next
|
|
79
|
+
|
|
80
|
+
## Artifact Rule
|
|
81
|
+
|
|
82
|
+
`aw-brainstorm` should not create a second planning file system or revive any legacy non-deterministic planning path.
|
|
83
|
+
|
|
84
|
+
If it needs to persist discovery context, keep it inside:
|
|
85
|
+
|
|
86
|
+
- `.aw_docs/features/<feature_slug>/state.json`
|
|
87
|
+
|
|
88
|
+
or pass it directly into `aw-plan`.
|
|
89
|
+
|
|
90
|
+
`aw-plan` remains responsible for canonical planning artifacts such as `prd.md`, `design.md`, `spec.md`, and `tasks.md`.
|
|
91
|
+
|
|
92
|
+
## Platform Context
|
|
93
|
+
|
|
94
|
+
| Domain Signal | Platform Skills to Load |
|
|
95
|
+
|---|---|
|
|
96
|
+
| API, controller, endpoint | `api-design`, `platform-services:development`, `platform-services:rate-limiting` |
|
|
97
|
+
| Vue, component, UI | `platform-frontend:vue-development`, `platform-frontend:highrise-compliance`, `platform-design:system` |
|
|
98
|
+
| Database, schema, collection | `platform-data:mongodb-patterns`, `platform-data:firestore-patterns` |
|
|
99
|
+
| Auth, IAM, permissions | `platform-services:authentication-authorization` |
|
|
100
|
+
| Deploy, k8s, helm | `platform-infra:kubernetes-workloads`, `platform-infra:jenkins-pipelines` |
|
|
101
|
+
| Worker, queue, pub/sub | `platform-services:worker-patterns`, `platform-infra:pubsub-messaging` |
|
|
102
|
+
| Multi-tenant, locationId | `platform-services:multi-tenancy` |
|
|
103
|
+
|
|
104
|
+
## Anti-Patterns
|
|
105
|
+
|
|
106
|
+
- jumping straight to code or implementation planning without resolving the real decision
|
|
107
|
+
- batching many questions at once
|
|
108
|
+
- presenting only one approach when meaningful alternatives exist
|
|
109
|
+
- writing final planning artifacts directly instead of routing through `aw-plan`
|
|
110
|
+
- reopening brainstorming after the direction is already clear
|
|
111
|
+
- ignoring platform rules, repo context, or known constraints
|
|
112
|
+
|
|
113
|
+
## Next Skill
|
|
114
|
+
|
|
115
|
+
After the direction is approved, invoke `aw-plan`, which should then invoke `aw-spec`.
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: aw-build
|
|
3
|
+
description: Build approved work from `.aw_docs/features/<feature_slug>/` artifacts in thin, reversible increments with org-standard validation and handoff discipline.
|
|
4
|
+
trigger: User requests implementation of approved work, or a compatible `/aw:execute` request needs to route to the canonical build stage.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# AW Build
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
`aw-build` owns implementation only.
|
|
12
|
+
It turns approved work into the smallest correct code, config, docs, or migration changes, continues through the full approved build scope in thin slices, and then hands off to test or review instead of self-certifying success.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- approved implementation artifacts already exist
|
|
17
|
+
- the request is to code, configure, migrate, or document an approved change
|
|
18
|
+
- a bug was already investigated and now needs a concrete fix
|
|
19
|
+
- a legacy `/aw:execute` request arrives
|
|
20
|
+
|
|
21
|
+
Do not use for vague ideation, unclear bugs, or release-only work.
|
|
22
|
+
|
|
23
|
+
## Workflow
|
|
24
|
+
|
|
25
|
+
1. Intake the approved inputs.
|
|
26
|
+
Load `spec.md`, `tasks.md`, and any relevant design or PRD context.
|
|
27
|
+
If the plan has a critical gap, route back to `aw-plan`.
|
|
28
|
+
2. Select the smallest correct build mode.
|
|
29
|
+
Choose `code`, `infra`, `docs`, `migration`, or `config`.
|
|
30
|
+
3. Resolve the execution topology before editing.
|
|
31
|
+
Default to sequential slice execution.
|
|
32
|
+
Use bounded parallel fan-out only when the approved plan marks disjoint `parallel_candidate` slices, names `parallel_group` and `parallel_write_scope`, and supplies or accepts the default `max_parallel_subagents: 3`.
|
|
33
|
+
4. Slice the work before editing.
|
|
34
|
+
Use `../../references/build-increments.md` to keep changes thin, reversible, and rollback-friendly.
|
|
35
|
+
For multi-file or high-risk work, load `incremental-implementation`.
|
|
36
|
+
5. Build one slice or one bounded parallel wave at a time.
|
|
37
|
+
For behavior changes, require RED-GREEN or a concrete failing signal.
|
|
38
|
+
Use `../../references/testing-patterns.md` when test structure needs support.
|
|
39
|
+
6. Continue through the approved build scope.
|
|
40
|
+
Keep moving slice-to-slice until the approved implementation scope for this stage is complete or the next unsatisfied need is no longer build.
|
|
41
|
+
Do not stop after the first passing slice if more approved build slices remain.
|
|
42
|
+
Only pause early for an explicit blocker, a requested checkpoint, or a real approval boundary already present in the artifacts.
|
|
43
|
+
7. Apply org standards during the slice.
|
|
44
|
+
Respect `.aw_rules`, relevant platform playbooks, and the resolved GHL baseline.
|
|
45
|
+
When context quality or scope focus is degrading, load `context-engineering`.
|
|
46
|
+
For frontend work, load `../../references/frontend-quality-checklist.md`.
|
|
47
|
+
For non-trivial UI work, load `frontend-ui-engineering`.
|
|
48
|
+
For interface changes, load `../../references/interface-stability.md` and `api-and-interface-design`.
|
|
49
|
+
For deprecation, removal, or migration slices, load `deprecation-and-migration`.
|
|
50
|
+
8. Record evidence and boundaries.
|
|
51
|
+
Note what changed, what did not change, which slices or parallel waves are complete, which build slices still remain, and which checks were run.
|
|
52
|
+
When the approved tasks are grouped into phases, record phase transitions explicitly: which phase completed, which phase is now active, and what remains in later phases.
|
|
53
|
+
Use `../../references/git-save-points.md` when the work needs explicit save-point discipline.
|
|
54
|
+
For meaningful completed slices, create focused save-point commits.
|
|
55
|
+
For non-trivial commit boundaries, branch hygiene, or worktree isolation, load `git-workflow-and-versioning`.
|
|
56
|
+
9. Hand off cleanly.
|
|
57
|
+
If build scope is complete, route to `aw-test` for QA proof or `aw-review` when the work needs findings, governance, or readiness decisions.
|
|
58
|
+
If the work is blocked mid-build, name the blocker, the last completed slice, and the smallest safe next action instead of stopping with a vague pause.
|
|
59
|
+
|
|
60
|
+
## Completion Contract
|
|
61
|
+
|
|
62
|
+
Build is complete only when one of these is true:
|
|
63
|
+
|
|
64
|
+
- the approved implementation scope for the current stage is complete and written down
|
|
65
|
+
- a blocker prevents the next approved build slice and that blocker is named explicitly
|
|
66
|
+
|
|
67
|
+
A successful slice is a checkpoint, not an automatic terminal state.
|
|
68
|
+
|
|
69
|
+
Every build handoff must make these things obvious:
|
|
70
|
+
|
|
71
|
+
- what approved inputs were used
|
|
72
|
+
- which phases were completed, if the approved plan used phases
|
|
73
|
+
- which phase is current or next, if phased execution is still in flight
|
|
74
|
+
- which slices were completed
|
|
75
|
+
- whether work ran sequentially or in bounded parallel waves
|
|
76
|
+
- which build slices remain, if any
|
|
77
|
+
- which validation was run
|
|
78
|
+
- which save-point commits were created
|
|
79
|
+
- which exact next command should run next
|
|
80
|
+
|
|
81
|
+
Meaningful completed build slices must create save-point commits in git-capable workspaces.
|
|
82
|
+
If a slice cannot support a clean save-point commit, that is a planning problem and the slice should usually be merged with its dependent follow-up before build treats it as complete.
|
|
83
|
+
Parallel build fan-out must stay within the planned `max_parallel_subagents` cap, which defaults to `3` when the plan does not justify another number.
|
|
84
|
+
|
|
85
|
+
## Common Rationalizations
|
|
86
|
+
|
|
87
|
+
| Rationalization | Reality |
|
|
88
|
+
|---|---|
|
|
89
|
+
| "This is small enough to do in one big patch." | Small tasks still benefit from thin slices and explicit validation. |
|
|
90
|
+
| "I'll add tests after the code is working." | If the behavior is testable, failure-first proof should lead the change. |
|
|
91
|
+
| "Frontend changes don't need special handling." | Responsive behavior, accessibility, and design-system compliance are part of the work. |
|
|
92
|
+
| "I can just clean up adjacent code too." | Scope creep makes rollback and review harder. |
|
|
93
|
+
|
|
94
|
+
## Red Flags
|
|
95
|
+
|
|
96
|
+
- a slice touches unrelated files
|
|
97
|
+
- a passing slice is treated as stage completion even though planned build work remains
|
|
98
|
+
- tests are hand-waved instead of run or explicitly declared unavailable
|
|
99
|
+
- the diff is large enough that rollback is unclear
|
|
100
|
+
- interface changes are made without boundary validation
|
|
101
|
+
- bugfix code appears before the failing signal is concrete
|
|
102
|
+
|
|
103
|
+
## State File
|
|
104
|
+
|
|
105
|
+
`state.json` should record at least:
|
|
106
|
+
|
|
107
|
+
- `feature_slug`
|
|
108
|
+
- `stage: "build"`
|
|
109
|
+
- `mode`
|
|
110
|
+
- `status`
|
|
111
|
+
- written artifacts
|
|
112
|
+
- inputs used
|
|
113
|
+
- files changed
|
|
114
|
+
- `completed_phases` when the approved plan used phases
|
|
115
|
+
- `current_phase` for the active or next build phase when phase sequencing exists
|
|
116
|
+
- completed slices
|
|
117
|
+
- remaining slices
|
|
118
|
+
- parallel execution mode and cap when parallel build fan-out was used
|
|
119
|
+
- validation commands
|
|
120
|
+
- `save_point_commits`
|
|
121
|
+
- blockers or concerns
|
|
122
|
+
- recommended next commands
|
|
123
|
+
|
|
124
|
+
## Verification
|
|
125
|
+
|
|
126
|
+
Before leaving build, confirm:
|
|
127
|
+
|
|
128
|
+
- [ ] the change came from approved inputs or a clearly approved direct technical request
|
|
129
|
+
- [ ] the work was split into thin, reversible increments when non-trivial
|
|
130
|
+
- [ ] behavior changes have failing-signal evidence or a clear explanation of why not
|
|
131
|
+
- [ ] the approved build scope is either complete or blocked explicitly
|
|
132
|
+
- [ ] relevant org standards, platform playbooks, and `.aw_rules` were applied
|
|
133
|
+
- [ ] parallel execution, if used, stayed within the planned worker cap and disjoint write scopes
|
|
134
|
+
- [ ] phased plans, if used, recorded phase completion plus the next phase transition
|
|
135
|
+
- [ ] meaningful completed slices produced recorded save-point commits
|
|
136
|
+
- [ ] `execution.md` and `state.json` are updated
|
|
137
|
+
|
|
138
|
+
## Final Output Shape
|
|
139
|
+
|
|
140
|
+
Always end with:
|
|
141
|
+
|
|
142
|
+
- `Mode`
|
|
143
|
+
- `Approved Inputs`
|
|
144
|
+
- `Parallelization`
|
|
145
|
+
- `Phase Progress`
|
|
146
|
+
- `Completed Slices`
|
|
147
|
+
- `Remaining Build Scope`
|
|
148
|
+
- `Changes`
|
|
149
|
+
- `Validation`
|
|
150
|
+
- `Save Points`
|
|
151
|
+
- `Blockers`
|
|
152
|
+
- `Next`
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
{
|
|
2
|
+
"cases": [
|
|
3
|
+
{
|
|
4
|
+
"id": "backend-approved-slice",
|
|
5
|
+
"request": "Implement the approved Communities moderation API change in thin slices.",
|
|
6
|
+
"buildMode": "code",
|
|
7
|
+
"expectedFollowupStages": ["aw-test", "aw-review"],
|
|
8
|
+
"expectedArtifacts": ["execution.md", "state.json"],
|
|
9
|
+
"expectedSupportingSkills": ["platform-services:development", "incremental-implementation"]
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"id": "frontend-ui-slice",
|
|
13
|
+
"request": "Take the approved Communities feed MFA UI change forward and update the app accordingly.",
|
|
14
|
+
"buildMode": "code",
|
|
15
|
+
"expectedFollowupStages": ["aw-test", "aw-review"],
|
|
16
|
+
"expectedArtifacts": ["execution.md", "state.json"],
|
|
17
|
+
"expectedSupportingSkills": ["platform-frontend:vue-development", "highrise-ui-governance", "frontend-ui-engineering"]
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"id": "migration-slice",
|
|
21
|
+
"request": "Apply the approved migration slice without widening scope.",
|
|
22
|
+
"buildMode": "migration",
|
|
23
|
+
"expectedFollowupStages": ["aw-test", "aw-review"],
|
|
24
|
+
"expectedArtifacts": ["execution.md", "state.json"],
|
|
25
|
+
"expectedSupportingSkills": ["platform-data:migration-patterns", "deprecation-and-migration"]
|
|
26
|
+
}
|
|
27
|
+
]
|
|
28
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: aw-debug
|
|
3
|
+
description: Internal debugging helper that drives reproduction, root-cause isolation, confirming probes, and guarded repair.
|
|
4
|
+
trigger: Internal only. Invoked by aw-investigate, aw-build, aw-test, or aw-review when failure remains uncertain.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# AW Debug
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
`aw-debug` is the internal debugging playbook.
|
|
12
|
+
It keeps bug work from devolving into guess-and-patch behavior.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- the failure is real but the cause is still uncertain
|
|
17
|
+
- multiple fix attempts already happened
|
|
18
|
+
- alerts or regressions need a concrete next probe
|
|
19
|
+
|
|
20
|
+
## Workflow
|
|
21
|
+
|
|
22
|
+
1. Capture a reproduction or equivalent failure signal.
|
|
23
|
+
2. Define expected vs actual behavior.
|
|
24
|
+
3. Identify the smallest plausible fault surface.
|
|
25
|
+
4. Run the next confirming probe.
|
|
26
|
+
5. Update the hypothesis based on evidence, not intuition.
|
|
27
|
+
6. Only then hand back to investigation, build, test, or review.
|
|
28
|
+
|
|
29
|
+
Use `../../references/debug-triage.md` for the stable checklist.
|
|
30
|
+
|
|
31
|
+
## Common Rationalizations
|
|
32
|
+
|
|
33
|
+
| Rationalization | Reality |
|
|
34
|
+
|---|---|
|
|
35
|
+
| "I already know the likely fix." | Likely is not confirmed. |
|
|
36
|
+
| "Another patch is faster than another probe." | Repeated speculative fixes usually waste more time. |
|
|
37
|
+
|
|
38
|
+
## Red Flags
|
|
39
|
+
|
|
40
|
+
- third fix attempt without new evidence
|
|
41
|
+
- patch size grows while root cause stays vague
|
|
42
|
+
- reproduction disappears and the team starts guessing from memory
|
|
43
|
+
|
|
44
|
+
## Verification
|
|
45
|
+
|
|
46
|
+
- [ ] a reproduction or equivalent failure signal exists
|
|
47
|
+
- [ ] expected vs actual behavior is explicit
|
|
48
|
+
- [ ] the next probe or likely cause is evidence-backed
|
|
49
|
+
- [ ] no speculative repair is treated as root-cause understanding
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: aw-deploy
|
|
3
|
+
description: Turn reviewed work into one requested release outcome with explicit GHL provider resolution and deterministic release artifacts.
|
|
4
|
+
trigger: Test and review passed and the user requests PR creation, branch handoff, or deployment.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# AW Deploy
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
`aw-deploy` owns release action only.
|
|
12
|
+
It should not reopen planning or implementation.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- reviewed work needs a PR
|
|
17
|
+
- reviewed work should remain on a branch
|
|
18
|
+
- reviewed work should go to staging or production
|
|
19
|
+
|
|
20
|
+
Do not use for launch discipline or end-to-end orchestration.
|
|
21
|
+
|
|
22
|
+
## Workflow
|
|
23
|
+
|
|
24
|
+
1. Confirm the evidence gate.
|
|
25
|
+
The required QA and review outputs must exist.
|
|
26
|
+
2. Select one release path.
|
|
27
|
+
PR, branch, staging, or production.
|
|
28
|
+
3. Resolve the org-standard mechanism.
|
|
29
|
+
Use the repo archetype and resolved baseline profile to choose provider and mechanism.
|
|
30
|
+
Load `ci-cd-and-automation` for gate ordering, preview/deploy automation, and rollback-aware pipeline expectations.
|
|
31
|
+
For releases that retire or migrate legacy paths, load `deprecation-and-migration`.
|
|
32
|
+
4. Execute or record the blocker.
|
|
33
|
+
Complete the selected release action end-to-end for the chosen mode.
|
|
34
|
+
External failure should still yield deterministic `release.md` evidence.
|
|
35
|
+
5. Hand off to `aw-ship` when requested.
|
|
36
|
+
Use `aw-ship` for rollout safety, rollback readiness, and closeout.
|
|
37
|
+
|
|
38
|
+
## Completion Contract
|
|
39
|
+
|
|
40
|
+
Deploy is complete only when one of these is true:
|
|
41
|
+
|
|
42
|
+
- the selected release action finished and was recorded clearly
|
|
43
|
+
- the release action is blocked and the blocker is recorded clearly
|
|
44
|
+
|
|
45
|
+
Every deploy handoff must make these things obvious:
|
|
46
|
+
|
|
47
|
+
- which release mode was selected
|
|
48
|
+
- which provider and mechanism were resolved
|
|
49
|
+
- what evidence or links were produced
|
|
50
|
+
- what rollback path is currently known
|
|
51
|
+
- which exact next command should run next
|
|
52
|
+
|
|
53
|
+
## Common Rationalizations
|
|
54
|
+
|
|
55
|
+
| Rationalization | Reality |
|
|
56
|
+
|---|---|
|
|
57
|
+
| "Deploy can also handle launch closeout." | Release action and launch discipline are related but distinct. |
|
|
58
|
+
| "I'll just guess the staging mechanism." | Unknown deployment config must fail closed. |
|
|
59
|
+
|
|
60
|
+
## Red Flags
|
|
61
|
+
|
|
62
|
+
- deploy runs without clear test and review evidence
|
|
63
|
+
- provider or mechanism is guessed
|
|
64
|
+
- deploy silently turns into release orchestration
|
|
65
|
+
|
|
66
|
+
## State File
|
|
67
|
+
|
|
68
|
+
`state.json` should record at least:
|
|
69
|
+
|
|
70
|
+
- `feature_slug`
|
|
71
|
+
- `stage: "deploy"`
|
|
72
|
+
- `mode`
|
|
73
|
+
- `status`
|
|
74
|
+
- written artifacts
|
|
75
|
+
- provider
|
|
76
|
+
- resolved mechanism
|
|
77
|
+
- build or release links
|
|
78
|
+
- execution evidence
|
|
79
|
+
- rollback path
|
|
80
|
+
- blockers
|
|
81
|
+
- recommended next commands
|
|
82
|
+
|
|
83
|
+
## Verification
|
|
84
|
+
|
|
85
|
+
- [ ] one release action was selected explicitly
|
|
86
|
+
- [ ] provider and mechanism came from repo archetype and baseline resolution
|
|
87
|
+
- [ ] `release.md` and `state.json` are updated
|
|
88
|
+
- [ ] handoff to `aw-ship` is clear when launch discipline is still needed
|
|
89
|
+
|
|
90
|
+
## Final Output Shape
|
|
91
|
+
|
|
92
|
+
Always end with:
|
|
93
|
+
|
|
94
|
+
- `Selected Mode`
|
|
95
|
+
- `Provider`
|
|
96
|
+
- `Resolved Mechanism`
|
|
97
|
+
- `Build Links`
|
|
98
|
+
- `Execution Evidence`
|
|
99
|
+
- `Rollback Path`
|
|
100
|
+
- `Outcome`
|
|
101
|
+
- `Next`
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"cases": [
|
|
3
|
+
{
|
|
4
|
+
"id": "pr-creation",
|
|
5
|
+
"request": "Create a PR for this reviewed work.",
|
|
6
|
+
"releasePath": "pr",
|
|
7
|
+
"expectedArtifacts": ["release.md", "state.json"],
|
|
8
|
+
"expectedSupportingSkills": ["ci-cd-and-automation"]
|
|
9
|
+
},
|
|
10
|
+
{
|
|
11
|
+
"id": "service-staging",
|
|
12
|
+
"request": "Deploy this verified Communities moderation API service to staging.",
|
|
13
|
+
"releasePath": "staging",
|
|
14
|
+
"expectedArtifacts": ["release.md", "state.json"],
|
|
15
|
+
"expectedSupportingSkills": ["platform-infra:staging-deploy", "platform-infra:deployment-strategies", "platform-infra:production-readiness"]
|
|
16
|
+
},
|
|
17
|
+
{
|
|
18
|
+
"id": "mfa-staging",
|
|
19
|
+
"request": "Deploy this verified Communities feed MFA to staging.",
|
|
20
|
+
"releasePath": "staging",
|
|
21
|
+
"expectedArtifacts": ["release.md", "state.json"],
|
|
22
|
+
"expectedSupportingSkills": ["deploy-versioned-mfa", "platform-infra:staging-deploy", "platform-infra:production-readiness"]
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"id": "release-automation",
|
|
26
|
+
"request": "Set up the release automation, preview gates, and rollback path for this service deployment.",
|
|
27
|
+
"releasePath": "deployment-automation",
|
|
28
|
+
"expectedArtifacts": ["release.md", "state.json"],
|
|
29
|
+
"expectedSupportingSkills": ["ci-cd-and-automation"]
|
|
30
|
+
}
|
|
31
|
+
]
|
|
32
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: aw-execute
|
|
3
|
+
description: Compatibility skill for the older execute stage. Follow aw-build as the canonical implementation behavior.
|
|
4
|
+
trigger: Internal compatibility only. Invoked when older docs, habits, or commands still reference aw-execute.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# AW Execute
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
`aw-execute` is a compatibility layer.
|
|
12
|
+
The canonical implementation stage is now `aw-build`.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- a legacy `/aw:execute` request arrives
|
|
17
|
+
- an older doc or test still refers to execute semantics
|
|
18
|
+
|
|
19
|
+
Do not create a separate execute-specific workflow.
|
|
20
|
+
|
|
21
|
+
## Workflow
|
|
22
|
+
|
|
23
|
+
1. Route to `aw-build`.
|
|
24
|
+
2. Preserve the same artifact discipline:
|
|
25
|
+
- `execution.md`
|
|
26
|
+
- `state.json`
|
|
27
|
+
3. Preserve the same continuation and downstream handoff:
|
|
28
|
+
- complete the current build scope or block it explicitly
|
|
29
|
+
- `aw-test`
|
|
30
|
+
- `aw-review`
|
|
31
|
+
|
|
32
|
+
## Common Rationalizations
|
|
33
|
+
|
|
34
|
+
| Rationalization | Reality |
|
|
35
|
+
|---|---|
|
|
36
|
+
| "Execute can stay different from build for now." | Dual semantics create drift and confusion. |
|
|
37
|
+
|
|
38
|
+
## Red Flags
|
|
39
|
+
|
|
40
|
+
- execute-specific behavior diverges from build
|
|
41
|
+
- old naming is used to bypass the new stage model
|
|
42
|
+
|
|
43
|
+
## Verification
|
|
44
|
+
|
|
45
|
+
- [ ] the request was routed to `aw-build`
|
|
46
|
+
- [ ] the current build scope was completed or blocked explicitly
|
|
47
|
+
- [ ] artifact and handoff behavior stayed consistent with the canonical build stage
|