aw-ecc 1.4.23 → 1.4.31
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/.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.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/user-prompt-submit.sh +40 -60
- 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 +5 -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.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/user-prompt-submit.sh +40 -60
- 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
|
@@ -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
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Mode: Code — TDD Execution
|
|
2
|
+
|
|
3
|
+
## Iron Law
|
|
4
|
+
|
|
5
|
+
> **Every [code] task follows TDD. No exceptions. No rationalizations.**
|
|
6
|
+
|
|
7
|
+
## Red-Green-Refactor Cycle
|
|
8
|
+
|
|
9
|
+
### 1. RED — Write the test first
|
|
10
|
+
|
|
11
|
+
- Write a failing test that describes the expected behavior.
|
|
12
|
+
- Run the test. It MUST fail. If it passes, the test is wrong or the behavior already exists.
|
|
13
|
+
- The test defines the contract. Implementation serves the test.
|
|
14
|
+
|
|
15
|
+
### 2. GREEN — Write minimal code to pass
|
|
16
|
+
|
|
17
|
+
- Write the simplest implementation that makes the test pass.
|
|
18
|
+
- Do not add features, optimizations, or "nice-to-haves" at this stage.
|
|
19
|
+
- Run the test. It MUST pass.
|
|
20
|
+
|
|
21
|
+
### 3. REFACTOR — Clean up without changing behavior
|
|
22
|
+
|
|
23
|
+
- Extract helpers, rename variables, reduce duplication.
|
|
24
|
+
- Run tests after every refactor step. They MUST still pass.
|
|
25
|
+
- Stop refactoring when the code is clean and readable.
|
|
26
|
+
|
|
27
|
+
## Rules
|
|
28
|
+
|
|
29
|
+
- **Test file per source file** — `feature.service.ts` gets `feature.service.spec.ts`.
|
|
30
|
+
- **Descriptive test names** — `it('should return empty array when no features exist for locationId')`.
|
|
31
|
+
- **No mocking internals** — Mock boundaries (HTTP, database, external services), not internal functions.
|
|
32
|
+
- **Coverage gate** — 80% minimum. Check with `npm run test:cov` or equivalent.
|
|
33
|
+
- **No skipped tests** — `it.skip` and `xit` are not allowed in committed code.
|
|
34
|
+
- **Platform logger** — Use `@platform-core/logger`, never `console.*`.
|
|
35
|
+
- **DTO validation** — Every `@Body()` parameter has a class-validator DTO.
|
|
36
|
+
- **Error handling** — Every async call has explicit error handling.
|
|
37
|
+
|
|
38
|
+
## Rationalization Table
|
|
39
|
+
|
|
40
|
+
| Rationalization | Why It Is Wrong |
|
|
41
|
+
|---|---|
|
|
42
|
+
| "I'll write tests after" | You will not. And the code will be shaped for implementation, not testability. |
|
|
43
|
+
| "This is too simple to test" | Simple code breaks too. The test documents the contract. |
|
|
44
|
+
| "Tests slow me down" | Tests slow you down now. Bugs slow you down forever. |
|
|
45
|
+
| "I'll just test the happy path" | Errors happen on unhappy paths. Test both. |
|
|
46
|
+
| "The integration test covers it" | Integration tests are slow and broad. Unit tests are fast and precise. |
|
|
47
|
+
| "I know this works" | Prove it. Run the test. |
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Mode: Docs — Write, Review, Commit
|
|
2
|
+
|
|
3
|
+
## Process
|
|
4
|
+
|
|
5
|
+
### 1. Write
|
|
6
|
+
|
|
7
|
+
- Write the documentation in the appropriate location.
|
|
8
|
+
- Follow existing documentation style and format in the repo.
|
|
9
|
+
- Include code examples where they aid understanding.
|
|
10
|
+
- Keep language clear, concise, and direct.
|
|
11
|
+
|
|
12
|
+
### 2. Self-Review Checklist
|
|
13
|
+
|
|
14
|
+
Before committing documentation:
|
|
15
|
+
|
|
16
|
+
- [ ] **Accuracy** — All technical details are correct and verified against the code.
|
|
17
|
+
- [ ] **Completeness** — All public APIs, config options, and workflows are documented.
|
|
18
|
+
- [ ] **Examples** — Code examples compile/run and match current API signatures.
|
|
19
|
+
- [ ] **Links** — All internal links resolve. No broken references.
|
|
20
|
+
- [ ] **Formatting** — Consistent heading levels, code block languages, and list styles.
|
|
21
|
+
- [ ] **No stale content** — Removed or updated references to deprecated features.
|
|
22
|
+
- [ ] **Audience** — Written for the target reader (developer, operator, end user).
|
|
23
|
+
|
|
24
|
+
### 3. Commit
|
|
25
|
+
|
|
26
|
+
- Commit documentation changes with `docs:` prefix.
|
|
27
|
+
- If docs accompany code changes, include in the same PR.
|
|
28
|
+
- Update the table of contents or index if one exists.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Mode: Infra — Dry-Run First
|
|
2
|
+
|
|
3
|
+
## Core Principle
|
|
4
|
+
|
|
5
|
+
> **Never apply infrastructure changes directly. Validate first, deploy via Jenkins.**
|
|
6
|
+
|
|
7
|
+
## Process
|
|
8
|
+
|
|
9
|
+
### 1. Validate
|
|
10
|
+
|
|
11
|
+
- Run `helm lint` for Helm chart changes.
|
|
12
|
+
- Run `terraform plan` for Terraform changes.
|
|
13
|
+
- Run `docker build` to verify Dockerfile changes.
|
|
14
|
+
- Review the diff carefully before proceeding.
|
|
15
|
+
|
|
16
|
+
### 2. Dry-Run
|
|
17
|
+
|
|
18
|
+
- `terraform plan -out=tfplan` — Review every resource change.
|
|
19
|
+
- `helm template` — Render and inspect the full manifest.
|
|
20
|
+
- `helm diff upgrade` — Compare current state with proposed changes.
|
|
21
|
+
|
|
22
|
+
### 3. Deploy via Jenkins
|
|
23
|
+
|
|
24
|
+
- **Never** run `kubectl apply`, `helm install`, or `terraform apply` directly.
|
|
25
|
+
- Use Jenkins shared library functions for all deployments.
|
|
26
|
+
- Trigger deployments via Jenkins pipeline, not CLI.
|
|
27
|
+
|
|
28
|
+
### 4. Verify
|
|
29
|
+
|
|
30
|
+
- Check pod status after deployment.
|
|
31
|
+
- Verify health probes are responding.
|
|
32
|
+
- Check logs for startup errors.
|
|
33
|
+
- Confirm the change is reflected in the running system.
|
|
34
|
+
|
|
35
|
+
## Platform Rules
|
|
36
|
+
|
|
37
|
+
- **Resource requests** — Set `resources.requests` for every container. Limits auto-calculated for servers.
|
|
38
|
+
- **Health probes** — Configure for every deployment (default path `/` on port 6050).
|
|
39
|
+
- **No CPU limits = requests** — Never set CPU limits equal to CPU requests (causes throttling).
|
|
40
|
+
- **No secrets in Helm** — Use GCP Secret Manager, not Helm values or ConfigMaps.
|
|
41
|
+
- **No KEDA** — KEDA is deprecated. Use `peakLoad.peakLoadMinReplicas` instead.
|
|
42
|
+
- **Pin image tags** — Never use `latest`. Use specific digest or semver.
|
|
43
|
+
- **Graceful shutdown** — `terminationGracePeriodSeconds` >= 30 seconds.
|
|
44
|
+
- **Terraform managed** — All GCP resources via Terraform. No manual console changes.
|