anyone-can-architect 0.2.0 → 0.4.0

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.
Files changed (146) hide show
  1. package/CONTEXT.md +2 -2
  2. package/README.md +6 -4
  3. package/README.zh-CN.md +4 -2
  4. package/SSOT.md +5 -0
  5. package/VERSION +1 -1
  6. package/axioms/README.md +1 -1
  7. package/axioms/writing.md +3 -1
  8. package/dist/antigravity/aca/SKILL.md +3 -2
  9. package/dist/antigravity/aca-design/SKILL.md +12 -6
  10. package/dist/antigravity/aca-implement/SKILL.md +102 -114
  11. package/dist/antigravity/aca-release/SKILL.md +13 -20
  12. package/dist/antigravity/aca-repo-audit/SKILL.md +13 -9
  13. package/dist/antigravity/aca-review/SKILL.md +146 -182
  14. package/dist/antigravity/aca-test/SKILL.md +112 -0
  15. package/dist/antigravity/aca-walkthrough/SKILL.md +18 -14
  16. package/dist/antigravity-cli/aca/SKILL.md +3 -2
  17. package/dist/antigravity-cli/aca-design/SKILL.md +12 -6
  18. package/dist/antigravity-cli/aca-implement/SKILL.md +102 -114
  19. package/dist/antigravity-cli/aca-release/SKILL.md +13 -20
  20. package/dist/antigravity-cli/aca-repo-audit/SKILL.md +13 -9
  21. package/dist/antigravity-cli/aca-review/SKILL.md +146 -182
  22. package/dist/antigravity-cli/aca-test/SKILL.md +112 -0
  23. package/dist/antigravity-cli/aca-walkthrough/SKILL.md +18 -14
  24. package/dist/codex/aca/SKILL.md +3 -2
  25. package/dist/codex/aca-design/SKILL.md +12 -6
  26. package/dist/codex/aca-implement/SKILL.md +102 -114
  27. package/dist/codex/aca-release/SKILL.md +13 -20
  28. package/dist/codex/aca-repo-audit/SKILL.md +13 -9
  29. package/dist/codex/aca-review/SKILL.md +146 -182
  30. package/dist/codex/aca-test/SKILL.md +112 -0
  31. package/dist/codex/aca-walkthrough/SKILL.md +18 -14
  32. package/dist/cursor/aca/SKILL.md +3 -2
  33. package/dist/cursor/aca-design/SKILL.md +12 -6
  34. package/dist/cursor/aca-implement/SKILL.md +102 -114
  35. package/dist/cursor/aca-release/SKILL.md +13 -20
  36. package/dist/cursor/aca-repo-audit/SKILL.md +13 -9
  37. package/dist/cursor/aca-review/SKILL.md +146 -182
  38. package/dist/cursor/aca-test/SKILL.md +113 -0
  39. package/dist/cursor/aca-walkthrough/SKILL.md +18 -14
  40. package/dist/grok/aca/SKILL.md +3 -2
  41. package/dist/grok/aca-design/SKILL.md +12 -6
  42. package/dist/grok/aca-implement/SKILL.md +102 -114
  43. package/dist/grok/aca-release/SKILL.md +13 -20
  44. package/dist/grok/aca-repo-audit/SKILL.md +13 -9
  45. package/dist/grok/aca-review/SKILL.md +146 -182
  46. package/dist/grok/aca-test/SKILL.md +112 -0
  47. package/dist/grok/aca-walkthrough/SKILL.md +18 -14
  48. package/doc-design/document-sets/module.md +6 -2
  49. package/doc-design/document-sets/ops-guide.md +25 -27
  50. package/doc-design/documents/class-design.md +7 -4
  51. package/doc-design/documents/instrumentation.md +3 -2
  52. package/doc-design/documents/integration-guide.md +7 -5
  53. package/doc-design/documents/interaction.md +516 -143
  54. package/doc-design/documents/interface.md +12 -7
  55. package/doc-design/documents/release.md +137 -105
  56. package/doc-design/patterns/interface.md +135 -14
  57. package/doc-design/repo-types/client-sdk.md +3 -3
  58. package/doc-design/repo-types/web-app.md +11 -5
  59. package/meta-skills/aca/SKILL.md +3 -2
  60. package/meta-skills/aca/SKILL.md.tmpl +3 -2
  61. package/package.json +1 -1
  62. package/skills/aca-design/SKILL.md +12 -6
  63. package/skills/aca-design/SKILL.md.tmpl +9 -5
  64. package/skills/aca-implement/SKILL.md +102 -114
  65. package/skills/aca-implement/SKILL.md.tmpl +103 -115
  66. package/skills/aca-release/SKILL.md +13 -20
  67. package/skills/aca-release/SKILL.md.tmpl +13 -20
  68. package/skills/aca-repo-audit/SKILL.md +13 -9
  69. package/skills/aca-repo-audit/SKILL.md.tmpl +10 -8
  70. package/skills/aca-review/SKILL.md +146 -182
  71. package/skills/aca-review/SKILL.md.tmpl +143 -181
  72. package/skills/aca-test/SKILL.md +112 -0
  73. package/skills/aca-test/SKILL.md.tmpl +110 -0
  74. package/skills/aca-walkthrough/SKILL.md +18 -14
  75. package/skills/aca-walkthrough/SKILL.md.tmpl +15 -13
  76. package/zh-CN/CONTEXT.md +2 -2
  77. package/zh-CN/SSOT.md +5 -0
  78. package/zh-CN/axioms/README.md +1 -1
  79. package/zh-CN/axioms/writing.md +3 -1
  80. package/zh-CN/dist/antigravity/aca/SKILL.md +3 -2
  81. package/zh-CN/dist/antigravity/aca-design/SKILL.md +12 -6
  82. package/zh-CN/dist/antigravity/aca-implement/SKILL.md +102 -114
  83. package/zh-CN/dist/antigravity/aca-release/SKILL.md +71 -69
  84. package/zh-CN/dist/antigravity/aca-repo-audit/SKILL.md +39 -29
  85. package/zh-CN/dist/antigravity/aca-review/SKILL.md +143 -179
  86. package/zh-CN/dist/antigravity/aca-test/SKILL.md +112 -0
  87. package/zh-CN/dist/antigravity/aca-walkthrough/SKILL.md +18 -14
  88. package/zh-CN/dist/antigravity-cli/aca/SKILL.md +3 -2
  89. package/zh-CN/dist/antigravity-cli/aca-design/SKILL.md +12 -6
  90. package/zh-CN/dist/antigravity-cli/aca-implement/SKILL.md +102 -114
  91. package/zh-CN/dist/antigravity-cli/aca-release/SKILL.md +71 -69
  92. package/zh-CN/dist/antigravity-cli/aca-repo-audit/SKILL.md +39 -29
  93. package/zh-CN/dist/antigravity-cli/aca-review/SKILL.md +143 -179
  94. package/zh-CN/dist/antigravity-cli/aca-test/SKILL.md +112 -0
  95. package/zh-CN/dist/antigravity-cli/aca-walkthrough/SKILL.md +18 -14
  96. package/zh-CN/dist/codex/aca/SKILL.md +3 -2
  97. package/zh-CN/dist/codex/aca-design/SKILL.md +12 -6
  98. package/zh-CN/dist/codex/aca-implement/SKILL.md +102 -114
  99. package/zh-CN/dist/codex/aca-release/SKILL.md +71 -69
  100. package/zh-CN/dist/codex/aca-repo-audit/SKILL.md +39 -29
  101. package/zh-CN/dist/codex/aca-review/SKILL.md +143 -179
  102. package/zh-CN/dist/codex/aca-test/SKILL.md +112 -0
  103. package/zh-CN/dist/codex/aca-walkthrough/SKILL.md +18 -14
  104. package/zh-CN/dist/cursor/aca/SKILL.md +3 -2
  105. package/zh-CN/dist/cursor/aca-design/SKILL.md +12 -6
  106. package/zh-CN/dist/cursor/aca-implement/SKILL.md +102 -114
  107. package/zh-CN/dist/cursor/aca-release/SKILL.md +71 -69
  108. package/zh-CN/dist/cursor/aca-repo-audit/SKILL.md +39 -29
  109. package/zh-CN/dist/cursor/aca-review/SKILL.md +143 -179
  110. package/zh-CN/dist/cursor/aca-test/SKILL.md +113 -0
  111. package/zh-CN/dist/cursor/aca-walkthrough/SKILL.md +18 -14
  112. package/zh-CN/dist/grok/aca/SKILL.md +3 -2
  113. package/zh-CN/dist/grok/aca-design/SKILL.md +12 -6
  114. package/zh-CN/dist/grok/aca-implement/SKILL.md +102 -114
  115. package/zh-CN/dist/grok/aca-release/SKILL.md +71 -69
  116. package/zh-CN/dist/grok/aca-repo-audit/SKILL.md +39 -29
  117. package/zh-CN/dist/grok/aca-review/SKILL.md +143 -179
  118. package/zh-CN/dist/grok/aca-test/SKILL.md +112 -0
  119. package/zh-CN/dist/grok/aca-walkthrough/SKILL.md +18 -14
  120. package/zh-CN/doc-design/document-sets/module.md +6 -2
  121. package/zh-CN/doc-design/document-sets/ops-guide.md +25 -27
  122. package/zh-CN/doc-design/documents/class-design.md +7 -4
  123. package/zh-CN/doc-design/documents/instrumentation.md +3 -2
  124. package/zh-CN/doc-design/documents/integration-guide.md +7 -5
  125. package/zh-CN/doc-design/documents/interaction.md +516 -143
  126. package/zh-CN/doc-design/documents/interface.md +12 -7
  127. package/zh-CN/doc-design/documents/release.md +138 -106
  128. package/zh-CN/doc-design/patterns/interface.md +135 -14
  129. package/zh-CN/doc-design/repo-types/client-sdk.md +3 -3
  130. package/zh-CN/doc-design/repo-types/web-app.md +11 -5
  131. package/zh-CN/meta-skills/aca/SKILL.md +3 -2
  132. package/zh-CN/meta-skills/aca/SKILL.md.tmpl +3 -2
  133. package/zh-CN/skills/aca-design/SKILL.md +12 -6
  134. package/zh-CN/skills/aca-design/SKILL.md.tmpl +9 -5
  135. package/zh-CN/skills/aca-implement/SKILL.md +102 -114
  136. package/zh-CN/skills/aca-implement/SKILL.md.tmpl +102 -114
  137. package/zh-CN/skills/aca-release/SKILL.md +71 -69
  138. package/zh-CN/skills/aca-release/SKILL.md.tmpl +71 -69
  139. package/zh-CN/skills/aca-repo-audit/SKILL.md +39 -29
  140. package/zh-CN/skills/aca-repo-audit/SKILL.md.tmpl +36 -28
  141. package/zh-CN/skills/aca-review/SKILL.md +143 -179
  142. package/zh-CN/skills/aca-review/SKILL.md.tmpl +140 -178
  143. package/zh-CN/skills/aca-test/SKILL.md +112 -0
  144. package/zh-CN/skills/aca-test/SKILL.md.tmpl +110 -0
  145. package/zh-CN/skills/aca-walkthrough/SKILL.md +18 -14
  146. package/zh-CN/skills/aca-walkthrough/SKILL.md.tmpl +15 -13
@@ -98,14 +98,10 @@ If execution cannot continue in Chapters 4 through 7, report completed facts, th
98
98
  1. Run `bash ~/.cursor/skills/aca/bin/aca-release-notify-check .` to check the announcement configuration
99
99
  Record the check result and the corresponding configuration location
100
100
  2. Act on the check result
101
-
102
- | Result | Action |
103
- | --- | --- |
104
- | `NOTIFY_NONE` | Record that no transport is configured and continue the release |
105
- | `NOTIFY_WIRED` | Record the platform and consumer point and continue the release |
106
- | `NOTIFY_UNWIRED` | Stop and report that the announcement does not use `aca-tag-notify-extract <tag>` to extract content, then check again after the configuration is corrected |
107
- | Unable to complete the check | Stop and report the reason and resume conditions |
108
-
101
+ - `NOTIFY_NONE`: record that no transport is configured and continue the release
102
+ - `NOTIFY_WIRED`: record the platform and consumer point and continue the release
103
+ - `NOTIFY_UNWIRED`: stop and report that the announcement does not use `aca-tag-notify-extract <tag>` to extract content, then check again after the configuration is corrected
104
+ - Unable to complete the check: stop and report the reason and resume conditions
109
105
  3. Use the configuration check result for the [Announcement Cross-Check](#72-cross-check-the-release-announcement)
110
106
  Check again after the configuration is corrected
111
107
  The configuration check confirms that the summary is integrated
@@ -202,9 +198,9 @@ If execution cannot continue in Chapters 4 through 7, report completed facts, th
202
198
  Cross-check that the Anyone Can Architect footer matches the current Anyone Can Architect version, immediately follows the repository version line, and is the last line
203
199
  Cross-check that the final commit contains the complete design, implementation, and tests for this scope
204
200
  3. Complete final verification
205
- Complete the verification required by the repository release workflow on the final commit
201
+ Complete the verification required by the repository release workflow and the `/aca-test` test scope on the final commit
206
202
  Record verification results and the corresponding commit
207
- When reusing existing results, state which reuse conditions are met and the basis for their correspondence to the final commit
203
+ When reusing existing `/aca-test` or verification results, state which reuse conditions are met and the basis for their correspondence to the final commit
208
204
  If artifacts are involved, cross-check their traceability to this commit
209
205
  Verification artifacts cannot replace evidence of completed delivery
210
206
  4. Determine whether release locking is allowed
@@ -306,15 +302,11 @@ Release announcements are generated from the NOTIFY block in the annotated Tag
306
302
  1. Locate the delivery results
307
303
  Use the [announcement configuration](#33-announcement-configuration) and the repository release workflow to find tasks, logs, or delivery receipts for this Tag
308
304
  2. Record the delivery status based on evidence
309
-
310
- | Status | Basis for determination |
311
- | --- | --- |
312
- | Sent | Evidence of successful delivery for this Tag |
313
- | Pending delivery | Confirmed to still be waiting or in progress |
314
- | Delivery failed | An explicit failure result |
315
- | Unconfirmed | Insufficient evidence to determine the delivery status |
316
- | Transport not configured | Configuration checks confirm that no delivery mechanism is configured |
317
-
305
+ - Evidence of successful delivery for this Tag exists: mark as sent
306
+ - The task is confirmed to still be waiting or in progress: mark as pending delivery
307
+ - An explicit delivery failure result exists: mark as delivery failed
308
+ - Evidence is insufficient to determine the delivery status: mark as unconfirmed
309
+ - Configuration checks confirm that no delivery mechanism is configured: mark as transport not configured
318
310
  3. Handle follow-up actions
319
311
  If delivery fails, recover or resend according to repository conventions
320
312
  If the status is unconfirmed, report the missing evidence
@@ -369,7 +361,8 @@ Select one immediately executable action based on the incomplete items
369
361
  | Execution conditions are missing | Meet the conditions, then check the status against [release preparation](#3-release-preparation) and resume |
370
362
  | The design solution still needs reasoning | `/aca-specify` Reason through the solution |
371
363
  | The revision solution is clear and only doc changes are needed | `/aca-design` Revise the docs |
372
- | Implementation issues | `/aca-implement` Fix and verify |
364
+ | Implementation issues | `/aca-implement` Fix code or tests |
365
+ | Tests or final verification incomplete | `/aca-test` Run verification, then resume the release |
373
366
  | Merge conflicts | Resolve and commit the conflicts, then rerun the [pre-merge audit](#43-pre-merge-audit) |
374
367
  | Push, cleanup, or announcement is still incomplete | Resume from the corresponding incomplete step |
375
368
  | Everything is complete and no follow-up items remain | Report that there are no pending tasks |
@@ -35,7 +35,7 @@ Use `/aca-review` when you need to judge whether business goals and design solut
35
35
  - Present the whole first, then expand on the details, see the [Pyramid Principle](~/.cursor/skills/aca/SSOT.md#2-structure)
36
36
  - When stating a judgment, give the conclusion first, then the supporting evidence
37
37
  - Merge heading levels that add no information
38
- - Use numbered lists for items with a sequence or priority, and indent multiple attributes under each item
38
+ - Use numbered lists for items with a sequence or priority; when a step contains sub-items, start the step with a bold phrase stating its purpose and indent specific operations and conditional branches under it
39
39
  - Use tables only for content with multiple rows of the same structure, more than two attributes per row, and no sequence between rows
40
40
  - Write list items as complete sentences
41
41
  - When an item has branches, indent the branches under that item
@@ -54,6 +54,8 @@ Use `/aca-review` when you need to judge whether business goals and design solut
54
54
  - Remove content that adds no information and does not help understanding
55
55
  - Write one sentence per line, with only one fact per sentence
56
56
  - State actions directly in operational steps
57
+ - If a specific practice fully expresses a constraint, write the practice directly
58
+ - Keep prohibitions that no specific practice can fully express
57
59
  - Write sequential actions as separate items
58
60
  - Make the actor, the object of the action, and the referents clear
59
61
  - Do not repeat actors, objects of actions, or referents already clear from context
@@ -182,16 +184,17 @@ When an implementation audit is included, cross-check all design items in scope
182
184
 
183
185
  ### 5.2 Runtime Verification
184
186
 
185
- 1. Determine verification requirements
186
- Read the full test and build commands specified by the repository
187
+ 1. **Determine verification requirements**
188
+ Determine the test and build commands required for the current scope according to the boundary rules in `/aca-test` and the repository `release` doc
189
+ Run full tests and builds by default when the repository does not specify tiered verification
187
190
  Check the required environment, configuration, and fixtures
188
- 2. Run verification or reuse its results
189
- Reuse existing results if they cover the required verification and the content under review, tests, fixtures, configuration, dependency environment, and commands have not changed
191
+ 2. **Run verification or reuse its results**
192
+ Reuse existing `/aca-test` or build results if they cover the required scope and the commit under review, tests, fixtures, configuration, dependency environment, and commands have not changed
190
193
  State the original verification results and the basis for reuse in the report
191
- Run the corresponding verification in an isolated environment if the reuse conditions are not met
194
+ Run the required tests and builds in an isolated environment following the execution rules of `/aca-test` if the reuse conditions are not met
192
195
  Static reading cannot replace verification by execution
193
196
  Do not modify project source code, design docs, or commit history during verification
194
- 3. Record results and handle exceptions
197
+ 3. **Record results and handle exceptions**
195
198
  Record the results and supporting evidence when verification passes
196
199
  Verify diagnostics and record confirmed issues when verification fails
197
200
  Mark the corresponding verification as incomplete and explain why if the environment is unavailable or execution is not possible
@@ -224,7 +227,7 @@ When an implementation audit is included, cross-check all design items in scope
224
227
  | Incomplete | Pass conditions are not met, and no confirmed must fix items exist |
225
228
 
226
229
  Required checks include reading documentation, mechanical checks, and content checks in the current scope
227
- When an implementation audit is included, they also include all consistency cross-checks, full tests, and builds
230
+ When an implementation audit is included, they also include all consistency cross-checks and the tests and builds required for the current scope
228
231
  When both must fix items and incomplete checks exist, set the verdict to action required and list the incomplete items
229
232
  Optional trim does not affect a pass
230
233
 
@@ -274,7 +277,8 @@ Choose one immediately executable action based on the nature of the issues and t
274
277
  | Verification prerequisites are missing | Meet the prerequisites, then continue this audit through `/aca-repo-audit` |
275
278
  | The solution still needs reasoning | Use `/aca-specify` to reason through the solution |
276
279
  | The revised solution is clear and only docs need changes | Use `/aca-design` to revise the docs |
277
- | Implementation deviates | Use `/aca-implement` to fix and verify |
280
+ | Implementation deviates | `/aca-implement` Fix code or tests |
281
+ | Tests or builds incomplete | `/aca-test` Run verification |
278
282
  | Audit passes | Return to the caller and continue with the confirmed arrangements |
279
283
 
280
284
  Audit the affected scope again after the issues are corrected
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: aca-review
3
- description: Review the design docs or code implementation in the current scope, determine pass, needs changes, or incomplete, and do not modify the docs or code under review
3
+ description: Review the design docs or code structure in the current scope, determine pass, needs changes, or incomplete, and do not modify the docs or code under review
4
4
  disable-model-invocation: true
5
5
  ---
6
6
  <!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
@@ -8,8 +8,8 @@ disable-model-invocation: true
8
8
 
9
9
  # aca-review
10
10
 
11
- Review the design docs or code implementation in the current scope and determine pass, needs changes, or incomplete
12
- Do not modify design docs, project source code, or test code
11
+ Review the design docs or code structure in the current scope and determine pass, needs changes, or incomplete
12
+ Do not modify design docs, project source code, or test code, and do not run the code or tests under review
13
13
  Use `/aca-repo-audit` for the repository-wide audit before release
14
14
 
15
15
  ## 1 Principles
@@ -18,11 +18,11 @@ Use `/aca-repo-audit` for the repository-wide audit before release
18
18
 
19
19
  1. **Source-driven review**
20
20
  Review the design against confirmed requirements and applicable rules
21
- Review the implementation against the confirmed design
21
+ Review the modularity and overall structure of the code against the confirmed design
22
22
  2. **Independent judgment**
23
- Form conclusions independently for each review task
23
+ Form conclusions independently for each review dimension
24
24
  3. **Evidence-based verdict**
25
- Determine issues and review conclusions from item-by-item verification results and evidence
25
+ Determine issues and review conclusions from facts in the code structure and docs
26
26
  4. **Scope constraints**
27
27
  Limit review conclusions to the current scope
28
28
 
@@ -37,7 +37,7 @@ The writing axiom applies to reviews of design doc prose and the wording of revi
37
37
  - Present the whole first, then expand on the details, see the [Pyramid Principle](~/.cursor/skills/aca/SSOT.md#2-structure)
38
38
  - When stating a judgment, give the conclusion first, then the supporting evidence
39
39
  - Merge heading levels that add no information
40
- - Use numbered lists for items with a sequence or priority, and indent multiple attributes under each item
40
+ - Use numbered lists for items with a sequence or priority; when a step contains sub-items, start the step with a bold phrase stating its purpose and indent specific operations and conditional branches under it
41
41
  - Use tables only for content with multiple rows of the same structure, more than two attributes per row, and no sequence between rows
42
42
  - Write list items as complete sentences
43
43
  - When an item has branches, indent the branches under that item
@@ -56,6 +56,8 @@ The writing axiom applies to reviews of design doc prose and the wording of revi
56
56
  - Remove content that adds no information and does not help understanding
57
57
  - Write one sentence per line, with only one fact per sentence
58
58
  - State actions directly in operational steps
59
+ - If a specific practice fully expresses a constraint, write the practice directly
60
+ - Keep prohibitions that no specific practice can fully express
59
61
  - Write sequential actions as separate items
60
62
  - Make the actor, the object of the action, and the referents clear
61
63
  - Do not repeat actors, objects of actions, or referents already clear from context
@@ -81,12 +83,12 @@ Reference: [ASD-STE100](~/.cursor/skills/aca/SSOT.md#1-writing-rules)
81
83
  ```mermaid
82
84
  flowchart TD
83
85
  Start([Receive review request]) --> Scope["Confirm review scope and execution models · §3"]
84
- Scope --> Check["Determine review type and run the corresponding checks · §4"]
85
- Check --> Audit["Orchestrate and run independent reviews for the selected review type · §5"]
86
- Audit --> Verify["Recheck and summarize · §6"]
87
- Verify --> Issues{"Confirmed must-fix items exist · §7"}
88
- Issues -- Yes, needs changes --> Report(["Output and next step · §8"])
89
- Issues -- No --> Complete{"All pass criteria are met · §7"}
86
+ Scope --> Check["Determine review type and prepare sources · §4"]
87
+ Check --> Audit["Run independent reviews by review type · §5"]
88
+ Audit --> Verify["Recheck and determine the verdict · §6"]
89
+ Verify --> Issues{"Confirmed must-fix items exist · §6.2"}
90
+ Issues -- Yes, needs changes --> Report(["Output and next step · §7"])
91
+ Issues -- No --> Complete{"All pass criteria are met · §6.2"}
90
92
  Complete -- Yes, pass --> Report
91
93
  Complete -- No, incomplete --> Report
92
94
  ```
@@ -95,81 +97,72 @@ flowchart TD
95
97
 
96
98
  ### 3.1 Subject, Scope, and Prerequisites
97
99
 
98
- 1. If the developer has specified the review subject and scope, follow that specification first
99
- Otherwise, use the review subject and scope already specified by the caller
100
- 2. If the subject or scope is unclear, determine it from current workspace changes and recent relevant commits
101
- Read the descriptions and diffs of recent relevant commits to understand the intent and content of the changes
102
- 3. If the review subject or scope is still unclear, ask the developer to specify it
103
- 4. Record the review subject, scope, and comparison baseline
104
- Specify the commits under review and any uncommitted changes included in the review
105
- 5. Run `bash ~/.cursor/skills/aca/bin/aca-repo-type-check` to check the repo type
106
- If the repo type is missing or invalid, mark the repo-type spec check as incomplete and recommend running `/aca-init`
107
- If the repo type is not yet supported, mark the repo-type spec check as incomplete and note that the corresponding rules are missing
108
- 6. If the input does not include the design doc location, locate it through the documentation entry in the root README
109
- If the review source material or files under review cannot be located, ask the developer to provide their locations
110
- Until the locations are clear, mark checks that depend on this content as incomplete
111
-
112
- 7. Read the general review source material
113
- Read the confirmed problems, goals, and change scope for this review
114
- If the repo type is valid and supported, read the corresponding Repo Type rules
115
- Read `CONTEXT.md` and check the business concepts and definitions involved in this review
116
- Read the design docs for the current scope and follow references to read any additional docs needed for understanding and verification
100
+ 1. **Confirm the review subject and scope**
101
+ - Developer has specified the review subject and scope: follow that specification first
102
+ - Developer has not specified them: use the review subject and scope already specified by the caller
103
+ - Subject or scope is still unclear: determine it from current workspace changes and recent relevant commits, reading the descriptions and diffs of recent relevant commits
104
+ - Review subject or scope still cannot be determined: ask the developer to specify it
105
+ 2. **Record the comparison baseline**
106
+ - Record the review subject, scope, and comparison baseline
107
+ - Specify the commits under review and any uncommitted changes included in the review
108
+ 3. **Check the repo type**
109
+ - Run `bash ~/.cursor/skills/aca/bin/aca-repo-type-check` to check the repo type
110
+ - Repo type is missing or invalid: mark the repo-type spec check as incomplete and recommend running `/aca-init`
111
+ - Repo type is not yet supported: mark the repo-type spec check as incomplete and note that the corresponding rules are missing
112
+ 4. **Locate and read general review sources**
113
+ - When the input does not include the design doc location, locate it from the documentation entry in the root README, or ask the developer for its location if it cannot be located and mark checks that depend on this content as incomplete until the location is clear
114
+ - Read the confirmed problems, goals, and change scope for this review
115
+ - If the repo type is valid and supported, read the corresponding Repo Type rules
116
+ - Read `CONTEXT.md` and check the business concepts and definitions involved in this review
117
+ - Read the design docs for the current scope and follow references to read any additional docs needed for understanding and verification
117
118
 
118
119
  ### 3.2 Agent and Model Selection
119
120
 
120
- 1. Scan the current AI Agent environment and other AI Agent environments already available on this machine
121
- Record the Agent tool types and actual model identifiers in each environment and compare them with the main agent
122
- Use existing tool entry points, configuration, and model lists to verify invocation methods and availability
123
- Installation or configuration alone does not prove that an environment can be invoked
124
- Mark information that cannot be verified as unknown
125
- 2. Propose execution combinations based on the scan results
126
- Prefer callable flagship models and assess flagship status using information that can currently be verified
127
- Prefer combinations whose Agent environment and model both differ from those of the main agent
128
- Do not prescribe a brand, model, or order of attempts
129
- If no other suitable and callable candidate is available, propose using the current model
130
- 3. Show each candidate's Agent, model, availability, invocation method, and differences from the main agent
131
- Explain the recommendation and available alternative combinations, and ask the developer to confirm
132
- Run the review only after the developer confirms
133
- Reuse the existing confirmation if the confirmed selection and availability conditions have not changed
134
- 4. Use the confirmed execution combinations for [task orchestration](#53-model-and-task-orchestration)
135
- If the selected combination cannot be invoked, use a confirmed alternative
136
- If no alternative has been confirmed, report the change and ask the developer to confirm a new combination
137
- Record the actual selection, fallback, and reasons in the report
121
+ 1. **Reuse the confirmed model first**
122
+ - Developer has specified an Agent environment or model: run with that specification
123
+ - A review model has already been confirmed and its availability conditions have not changed: reuse the last confirmed Agent environment and model by default, and skip the environment scan and confirmation
124
+ 2. **Scan and confirm the model on the first review**
125
+ - On the first review with no model specified, scan the current AI Agent environment and other AI Agent environments on this machine, and the models that can be invoked
126
+ - Prefer recommending a callable flagship model that differs from the main agent; if no other suitable and callable candidate is available, propose using the current model
127
+ - Show each candidate's Agent environment, model, availability, and the reason for the recommendation, and ask the developer to confirm before running the review; later reviews reuse this confirmation by default
128
+ 3. **Handle execution fallback**
129
+ - Use the confirmed or reused execution combination for [Task Orchestration and Execution](#53-task-orchestration-and-execution)
130
+ - If the selected combination cannot be invoked, use a confirmed alternative, or report the change and ask the developer to confirm a new combination if no alternative has been confirmed
131
+ - Record the Agent environment and model actually used, whether they were reused, and the reasons for any fallback in the [Review Report](#71-review-report)
138
132
 
139
133
  ## 4 Read Source Material and Run Checks
140
134
 
141
135
  ```mermaid
142
136
  flowchart TD
143
- Kind["Determine review type · §4.1"] -- Design review --> Design["Design review · §4.2"]
144
- Kind -- Implementation review --> Implementation["Implementation review · §4.3"]
145
- Design --> Results["Handle check results · §4.4"]
146
- Implementation --> Results
137
+ Kind["Determine review type · §4.1"] -- Design review --> Design["Design review preparation and mechanical checks · §4.2"]
138
+ Kind -- Implementation review --> Implementation["Implementation review source preparation · §4.3"]
139
+ Design --> Next(["Proceed to independent review · §5"])
140
+ Implementation --> Next
147
141
  ```
148
142
 
149
143
  ### 4.1 Determine Review Type
150
144
 
151
- 1. If the developer has specified the review type, follow that specification first
152
- Otherwise, use the review type already specified by the caller
153
- 2. If the review type is unclear, determine it from the subject under review and the actual changes
154
- - Design docs: run a design review
155
- - Code, tests, or runtime configuration: run an implementation review
156
- - Both design and implementation: run both review types separately
157
- 3. If the review type is still unclear, ask the developer to specify it
145
+ 1. **Determine the review type for this run**
146
+ - Developer has specified the review type: follow that specification first
147
+ - Developer has not specified it: use the review type already specified by the caller
148
+ - Review type is not specified: determine it from the subject under review and the actual changes (run a design review for design docs, run an implementation review for code, and run both review types separately when both are involved)
149
+ - Review type still cannot be determined: ask the developer to specify it
158
150
 
159
- Run both check branches when both review types are selected
151
+ Run both branches when both review types are selected
160
152
 
161
153
  ### 4.2 Design Review
162
154
 
163
- 1. Read the document set, Doc Design, and Patterns actually used for the current scope
164
- Extract their applicable checklist items as the basis for item-by-item verification
165
- 2. Determine target paths for mechanical checks based on the current review scope
166
- Prose checks cover all docs under review, including project-level records within the review scope
167
- For the doc graph check, select a doc tree that includes the docs under review and has a README entry
168
- Mechanical checks for Context verify structure and formatting, while content is verified against the corresponding Doc Design checklist
169
- 3. Run or reuse mechanical checks
170
- Existing mechanical check results from this session can be reused if they cover the same scope and the relevant files, check rules, and tools have not changed
171
- When reusing results, state the original check results and the reuse conditions met in this review in the report
172
- If the reuse conditions are not met, replace the placeholder paths in the following commands with the actual paths determined in step 2 and run them
155
+ By default, design review applies to cross-module design changes (involving multiple modules, the project-level architecture, the module division, or cross-module interfaces and collaboration contracts), or to a design review the developer explicitly requests
156
+
157
+ 1. **Extract applicable checklist items**
158
+ - Read the document set, Doc Design, and Patterns actually used for the current scope
159
+ - Extract their applicable checklist items as the basis for verification in the design review
160
+ 2. **Reuse or run mechanical checks**
161
+ - Existing mechanical check results from this session can be reused directly if they cover the same scope and the relevant files, check rules, and tools have not changed, stating the original results and the basis for reuse in the report
162
+ - If the reuse conditions are not met, replace the placeholder paths in the following commands with the actual paths of the docs under review and run them
163
+ - Prose checks cover all docs under review, including project-level records within the review scope
164
+ - For the doc graph check, select a doc tree that includes the docs under review and has a README entry
165
+ - Mechanical checks for Context verify structure and formatting
173
166
 
174
167
  ```bash
175
168
  bash ~/.cursor/skills/aca/bin/aca-doc-graph-check <doc directory>
@@ -177,111 +170,94 @@ Run both check branches when both review types are selected
177
170
  bash ~/.cursor/skills/aca/bin/aca-prose-check <paths to all docs under review>
178
171
  ```
179
172
 
180
- ### 4.3 Implementation Review
181
-
182
- 1. Read the confirmed design, test design, and repository implementation conventions for the current scope
183
- 2. Read the current diff and changed files against the established comparison baseline
184
- Read affected callers and dependency code
185
- Read the functions, classes, and related call chains containing the changes to understand their execution context
186
- 3. Map the implementation and tests to the design conventions and test scenarios respectively
187
- 4. Based on the impact scope of the current changes, run or reuse the tests, builds, and static checks required by the design and repository conventions
188
- Verify behavior that the design requires checking through actual execution by running the corresponding test cases
189
- Existing verification results can be reused if they cover the same content under review and the test cases, fixtures, configuration, and dependency environment have not changed
190
- When reusing results, state the original verification results and the reuse conditions met in this review in the report
191
- Run the corresponding checks if verification evidence is insufficient or reuse conditions are not met
192
- Use an isolated verification environment as specified by the test design
193
- Do not modify commit history during verification
194
-
195
- ### 4.4 Handle Check Results
196
-
197
- Handle tool checks for both review types as specified in this section
173
+ 3. **Handle mechanical check results**
198
174
 
199
175
  | Check status | Action |
200
176
  | --- | --- |
201
- | Pass | Record the results and verification evidence |
177
+ | Pass, or reuse conditions met | Record the results and the verification or reuse evidence |
202
178
  | Failure returned | Check the diagnostics and list confirmed issues as must fix |
203
179
  | Cannot run or diagnostics cannot be verified | Mark the corresponding check or issue verification as incomplete and state the reason |
204
180
 
181
+ ### 4.3 Implementation Review
182
+
183
+ 1. **Read the structural design and organization conventions**
184
+ - Read the architecture design, module boundaries, interface definitions, internal composition, and repository code organization conventions for the current scope
185
+ 2. **Read the overall structure of the code under review**
186
+ - Against the established comparison baseline, read the directory and file distribution, module dependencies, function and class definitions, and cross-module assembly wiring involved in the changes
187
+ 3. **Define the review boundary**
188
+ - By default, implementation review applies to cross-module changes or changes to a module's overall code structure (changes that stay inside a module and do not change its overall code structure skip implementation review and go directly to `/aca-test`)
189
+ - Implementation review checks only the overall structure (module structure, overall code distribution, and function construction), and does not check specific code details or implementation logic
190
+ - Implementation review does not run code, tests, or builds directly, and runtime verification is executed by `/aca-test` after the review passes
191
+
205
192
  ## 5 Review Orchestration and Execution
206
193
 
207
194
  ### 5.1 Design Review Dimensions
208
195
 
209
- 1. **Product perspective**
196
+ Design review is one overall review task that checks the design docs under review against the following four items
197
+
198
+ 1. **Requirements and scope coverage**
210
199
  Check whether the design fully addresses the confirmed problems, goals, and scope
211
- 2. **Design perspective**
212
- Check whether the division of responsibilities and boundaries matches the division of business work
213
- Check whether the collaboration and processing mechanisms can achieve the confirmed business goals
214
- If user interaction is involved, check whether users can achieve their goals by following the designed workflow
215
- Check whether each interaction state and each success and failure path provides clear feedback and action guidance
216
- 3. **Implementation perspective**
217
- Check whether module dependencies and interface conventions are sufficient to guide module collaboration
218
- Check whether data, state changes, error handling, and boundary behavior are sufficient to guide detailed implementation
200
+ 2. **Responsibility boundaries and collaboration mechanisms**
201
+ Check whether the division of responsibilities and boundaries, module dependencies, and interface conventions match the division of business work and are sufficient to guide module collaboration
202
+ Check whether the collaboration and processing mechanisms, data and state changes, error handling, and boundary behavior are sufficient to guide detailed implementation
203
+ If user interaction is involved, check whether the interaction flow, each interaction state, and each success and failure path provide clear feedback and action guidance
204
+ Check whether the design contains ambiguities that would lead to different business behavior, and whether additional design decisions are still needed before implementation
205
+ 3. **Completeness of the verification design**
219
206
  Check whether the test design specifies fixtures, scenarios, execution methods, and expected results
220
207
  Check whether test results can determine if the corresponding acceptance criteria are met
221
- Check whether the design contains ambiguities that would lead to different business behavior
222
- Check whether additional design decisions are still needed before implementation
223
- 4. **Overall perspective**
208
+ 4. **Cross-doc consistency and writing rules**
224
209
  Check whether the documentation entry and references accurately locate the current design and its dependencies
225
210
  Check related docs for design omissions, conflicting conventions, duplicate definitions, or inconsistent terminology
211
+ Check whether the checklist items of the applicable document set, Doc Design, and Patterns are met
226
212
 
227
213
  ### 5.2 Implementation Review Dimensions
228
214
 
229
- Check the following items individually against the confirmed design docs
230
-
231
- 1. **Structural setup**
232
- Check whether the division of modules and files, responsibility assignments, interface definitions, and dependencies conform to the design
233
- 2. **Detailed logic implementation**
234
- Check whether inputs, outputs, and processing flows conform to the design
235
- Check whether data and state changes, error handling, and boundary behavior conform to the design
236
- Check whether fixtures, scenarios, and expected results in black-box and white-box tests conform to the corresponding test design
237
- Check whether test assertions can detect deviations between actual behavior and expected results
238
- 3. **Overall structural implementation**
239
- Check whether module assembly, call chains, and collaboration methods conform to the overall architecture design
240
- Check whether integrated behavior conforms to the cross-module flows and acceptance criteria in the design
241
-
242
- ### 5.3 Model and Task Orchestration
243
-
244
- 1. Create independent review tasks for the selected review type
245
- For design reviews, assign an independent sub-agent to each perspective
246
- For implementation reviews, assign independent sub-agents to structural setup, detailed logic implementation, and overall structural implementation
247
- Each sub-agent forms conclusions independently without reading other sub-agents' review results beforehand
248
- 2. Arrange execution using the combinations confirmed in [Agent and Model Selection](#32-agent-and-model-selection)
249
- Keep review tasks independent even when using the current model
250
- 3. Provide task context to each sub-agent
251
- - Assigned review items and applicable checklist items
215
+ Implementation review is one overall review task that uses the confirmed design docs as its basis, checks only the modularity and overall structure of the code, and does not check specific code details or implementation logic
216
+
217
+ 1. **Module structure**
218
+ Check whether the division of modules and submodules, responsibility assignments, interface boundaries, dependencies, and cross-module assembly wiring conform to the design
219
+ 2. **Overall code distribution**
220
+ Check whether the directory and file organization conforms to the design, whether each file has a single responsibility and clear ownership, and whether responsibilities are mixed or layers are coupled across boundaries
221
+ 3. **Function construction**
222
+ Check whether the responsibility split, signature design, granularity, and level of abstraction of functions and classes are clear and reasonable
223
+
224
+ ### 5.3 Task Orchestration and Execution
225
+
226
+ 1. **Dispatch independent review tasks by review type**
227
+ - When only a design review or only an implementation review runs, create 1 independent sub-agent task to complete all check items of that dimension
228
+ - When both design and implementation reviews run, create 1 independent sub-agent task for the design review and 1 for the implementation review
229
+ - Run each review task according to [Agent and Model Selection](#32-agent-and-model-selection), and form conclusions independently
230
+ 2. **Provide task context**
231
+ - The assigned review type, its check items, and applicable checklist items
252
232
  - Review subject, scope, and comparison baseline, including commits under review and uncommitted changes included in the review
253
233
  - Locations of the content under review and the corresponding design source material
254
- - Existing check results and evidence from chapter 4, with the basis for execution or reuse
255
- - The diff, changed files, affected callers and dependency code, and repository implementation conventions needed for the implementation review
256
-
257
- ### 5.4 Run the Review
258
-
259
- 1. Each sub-agent verifies its assigned checklist items individually
260
- If a checklist item does not apply to the current scope, record it as not applicable and state the basis
261
- 2. For each check, record the verification result, corresponding file location, and basis for judgment
262
- 3. For each issue, record the location, problem, impact, and recommended changes using the issue format in [Review Report](#81-review-report)
263
- 4. Return the complete check records, issue list, and incomplete items to the main agent
264
-
265
- ## 6 Recheck and Summarize
266
-
267
- 1. The main agent reads each sub-agent's check records
268
- Check whether tool checks and verification evidence correspond to the current content under review
269
- 2. Check the files and evidence for each issue and include it in the report only after confirming it
270
- Exclude disproven issues
271
- Mark issues with insufficient evidence as incomplete verification
272
- The main agent can add issues it finds independently after applying the same evidence verification
273
- Merge duplicate issues while retaining their locations, evidence, and impact
274
- 3. Summarize the check records for all review items and check each checklist item's applicability and verification result
275
- If a sub-agent did not cover its assigned scope, omitted checks, or lacked verification evidence, assign the corresponding supplementary checks
276
- The main agent rechecks the supplementary results
277
- Mark review items or checks that still cannot be completed as incomplete and state the reasons
278
- 4. Summarize confirmed issues and check completion status as the basis for the verdict
279
-
280
- ## 7 Verdict
234
+ - For design review, the mechanical check results and evidence from Chapter 4
235
+ - For implementation review, the directory and file structure, changed files, module dependencies, and repository code organization conventions
236
+ 3. **Run an issue-oriented review**
237
+ - The sub-agent verifies each check item and applicable checklist item of its dimension
238
+ - When it finds an issue, it records the file location, problem, impact, and recommended change using the issue format in the [Review Report](#71-review-report)
239
+ - When a check item cannot be completed, it records the incomplete item and the reason
240
+ - Pass and not-applicable items are not itemized; the sub-agent returns the list of issues found, incomplete items, and its review conclusion to the main agent
241
+
242
+ ## 6 Recheck and Verdict
243
+
244
+ ### 6.1 Recheck and Merge
245
+
246
+ 1. **Recheck issue evidence**
247
+ - The main agent checks the files and evidence for each issue returned by the sub-agents and includes it in the report only after confirming it
248
+ - Exclude disproven issues and mark issues with insufficient evidence as incomplete verification
249
+ - The main agent can add issues it finds independently after applying the same evidence verification
250
+ - Merge duplicate issues while retaining their locations, evidence, and impact
251
+ 2. **Check review coverage**
252
+ - Confirm that the selected review dimensions and their check items have all been verified
253
+ - If a sub-agent did not cover its assigned scope or omitted check items, check the corresponding content and recheck the results
254
+ - Mark review dimensions or checks that still cannot be completed as incomplete and state the reasons
255
+
256
+ ### 6.2 Verdict
281
257
 
282
258
  | Verdict | Criteria |
283
259
  | --- | --- |
284
- | Pass | All selected review tasks are complete, all applicable checklist items have passed verification, all applicable tool checks have passed, and there are no must-fix items |
260
+ | Pass | All selected review tasks are complete, all applicable checklist items have passed verification, all applicable mechanical checks have passed, and there are no must-fix items |
285
261
  | Needs changes | Confirmed must-fix items exist |
286
262
  | Incomplete | Pass criteria are not met and there are no confirmed must-fix items |
287
263
 
@@ -289,9 +265,9 @@ If must-fix items and incomplete checks both exist, the verdict is needs changes
289
265
  Optional improvements do not affect a pass
290
266
  After the content under review changes, review the affected scope again and update the corresponding conclusions
291
267
 
292
- ## 8 Output and Next Step
268
+ ## 7 Output and Next Step
293
269
 
294
- ### 8.1 Review Report
270
+ ### 7.1 Review Report
295
271
 
296
272
  Output the review results in the current conversation using the following template without writing to project files
297
273
 
@@ -300,12 +276,13 @@ Output the review results in the current conversation using the following templa
300
276
 
301
277
  | Item | Result |
302
278
  | --- | --- |
303
- | Subject | <design docs / code implementation / both> |
279
+ | Subject | <design docs / code structure / both> |
304
280
  | Scope | <modules, files, or changes under review> |
305
281
  | Baseline | <comparison baseline, commits under review, and uncommitted changes> |
282
+ | Execution model | <Agent environment and model actually used, reuse status, and fallback reasons> |
306
283
  | Verdict basis | <how pass criteria are met, or issues and incomplete checks preventing a pass> |
307
284
  | Must fix | <issue count and main impact / none> |
308
- | Tool checks | <pass, failure, and incomplete status of tests, builds, or mechanical checks> |
285
+ | Tool checks | <pass, reuse, failure, and incomplete status of design review mechanical checks / not applicable for implementation review> |
309
286
  | Incomplete | <incomplete review tasks and checks within the current scope, and reasons / none> |
310
287
  | Next step | <one immediately actionable step> |
311
288
 
@@ -313,39 +290,26 @@ Output the review results in the current conversation using the following templa
313
290
 
314
291
  - <doc section link / code file link and line number>
315
292
  - Problem: <actual content, design conventions or checklist items violated, and specific deviations>
316
- - Impact: <impact on design understanding, implementation, or runtime behavior, and conditions under which it occurs>
293
+ - Impact: <impact on design understanding, implementation, or maintenance of the code structure, and conditions under which it occurs>
317
294
  - Change: <content to correct or confirm, and conventions or checklist items to satisfy after correction>
318
295
 
319
296
  ## Optional Improvements
320
297
 
321
298
  - <suggested improvements that do not affect a pass, corresponding locations, and expected benefits>
322
-
323
- ## Check Scope
324
-
325
- - Read: <files actually read in this review>
326
- - Checklist: <criteria and sources, item-by-item verification results, basis for non-applicability, and reasons for incomplete checks>
327
- - Tools: <commands actually run and their results, or original results reused and basis for reuse>
328
-
329
- | Review item | Agent environment | Model | Completion status | Notes |
330
- | --- | --- | --- | --- | --- |
331
- | <design review perspective / implementation review item> | <actual Agent environment> | <actual model and verifiable version> | <complete / incomplete> | <reason for fallback or incomplete status / none> |
332
299
  ```
333
300
 
334
- For design reviews, list the four perspectives: product, design, implementation, and overall
335
- For implementation reviews, list the three items: structural setup, detailed logic implementation, and overall structural implementation
336
-
337
- ### 8.2 Follow-Up Actions
301
+ ### 7.2 Follow-Up Actions
338
302
 
339
303
  Select the next step based on the review verdict and progress in the current round
340
304
 
341
305
  | Verdict | Situation | Next step |
342
306
  | --- | --- | --- |
343
- | Incomplete | Inputs, verification environment, or verification conditions are missing | Report the conditions for resuming and continue this review through `/aca-review` once they are met |
344
- | Needs changes | Implementation issues | Fix and verify through `/aca-implement` |
345
- | Needs changes | The design solution still needs reasoning or decisions | Extend or revise the solution through `/aca-specify` |
346
- | Needs changes | The solution is clear and only design docs need revision | Revise the docs through `/aca-design` |
347
- | Pass | Only the design review has passed and implementation is needed in this round | `/aca-implement` |
348
- | Pass | The implementation review has passed and implementation tasks remain in this round | Continue implementation through `/aca-implement` |
349
- | Pass | All work in this round is complete and all required reviews have passed | Proceed to `/aca-release` according to the confirmed version progression plan |
350
-
351
- After design or implementation corrections, review the affected scope again through `/aca-review`
307
+ | Incomplete | Inputs or verification conditions are missing | Report the conditions for resuming and continue this review through `/aca-review` once they are met |
308
+ | Needs changes | The design solution still needs reasoning or decisions | `/aca-specify` Extend or revise the solution |
309
+ | Needs changes | The solution is clear and only design docs need revision | `/aca-design` Revise the docs |
310
+ | Needs changes | Code structure issues | `/aca-implement` Adjust the code structure |
311
+ | Pass | Design review passed and code implementation is needed in this round | `/aca-implement` |
312
+ | Pass | Design review passed and only design docs are changed in this round | Proceed to `/aca-release` according to the confirmed version progression plan |
313
+ | Pass | Implementation review passed | `/aca-test` Run test verification for the current scope |
314
+
315
+ After design or code structure corrections, review the affected scope again through `/aca-review`