@prmichaelsen/remember-mcp 3.19.3 → 3.20.1

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 (102) hide show
  1. package/AGENT.md +10 -3
  2. package/CHANGELOG.md +19 -0
  3. package/README.md +1 -1
  4. package/agent/commands/acp.artifact-glossary.md +530 -0
  5. package/agent/commands/acp.artifact-reference.md +591 -0
  6. package/agent/commands/acp.artifact-research.md +594 -0
  7. package/agent/commands/acp.audit.md +345 -0
  8. package/agent/commands/acp.clarification-address.md +185 -88
  9. package/agent/commands/acp.clarification-capture.md +44 -44
  10. package/agent/commands/acp.clarification-create.md +41 -42
  11. package/agent/commands/acp.command-create.md +49 -49
  12. package/agent/commands/acp.design-create.md +53 -35
  13. package/agent/commands/acp.design-reference.md +42 -42
  14. package/agent/commands/acp.handoff.md +35 -35
  15. package/agent/commands/acp.index.md +47 -47
  16. package/agent/commands/acp.init.md +105 -69
  17. package/agent/commands/acp.package-create.md +41 -41
  18. package/agent/commands/acp.package-info.md +40 -40
  19. package/agent/commands/acp.package-install.md +48 -48
  20. package/agent/commands/acp.package-list.md +40 -40
  21. package/agent/commands/acp.package-publish.md +62 -62
  22. package/agent/commands/acp.package-remove.md +41 -41
  23. package/agent/commands/acp.package-search.md +48 -48
  24. package/agent/commands/acp.package-update.md +50 -50
  25. package/agent/commands/acp.package-validate.md +52 -52
  26. package/agent/commands/acp.pattern-create.md +61 -43
  27. package/agent/commands/acp.plan.md +70 -47
  28. package/agent/commands/acp.proceed.md +188 -66
  29. package/agent/commands/acp.project-create.md +42 -42
  30. package/agent/commands/acp.project-info.md +46 -46
  31. package/agent/commands/acp.project-list.md +41 -41
  32. package/agent/commands/acp.project-remove.md +36 -36
  33. package/agent/commands/acp.project-set.md +33 -33
  34. package/agent/commands/acp.project-update.md +57 -57
  35. package/agent/commands/acp.projects-restore.md +37 -37
  36. package/agent/commands/acp.projects-sync.md +39 -39
  37. package/agent/commands/acp.report.md +50 -50
  38. package/agent/commands/acp.resume.md +36 -36
  39. package/agent/commands/acp.sessions.md +46 -46
  40. package/agent/commands/acp.status.md +43 -43
  41. package/agent/commands/acp.sync.md +109 -56
  42. package/agent/commands/acp.task-create.md +51 -49
  43. package/agent/commands/acp.update.md +66 -45
  44. package/agent/commands/acp.validate.md +110 -52
  45. package/agent/commands/acp.version-check-for-updates.md +40 -40
  46. package/agent/commands/acp.version-check.md +36 -36
  47. package/agent/commands/acp.version-update.md +43 -43
  48. package/agent/commands/command.template.md +40 -40
  49. package/agent/commands/git.commit.md +28 -28
  50. package/agent/commands/git.init.md +48 -48
  51. package/agent/design/design.template.md +9 -9
  52. package/agent/design/local.admin-debugging-tools.md +242 -0
  53. package/agent/design/requirements.template.md +8 -8
  54. package/agent/index/.gitkeep +0 -0
  55. package/agent/index/acp.core.yaml +137 -0
  56. package/agent/index/local.main.template.yaml +37 -0
  57. package/agent/index/local.main.yaml +48 -0
  58. package/agent/manifest.yaml +64 -0
  59. package/agent/milestones/milestone-1-{title}.template.md +8 -8
  60. package/agent/milestones/milestone-22-admin-debugging-tools.md +61 -0
  61. package/agent/patterns/pattern.template.md +22 -22
  62. package/agent/progress.template.yaml +13 -3
  63. package/agent/progress.yaml +78 -1
  64. package/agent/schemas/package.schema.yaml +276 -0
  65. package/agent/scripts/acp.project-update.sh +5 -6
  66. package/agent/tasks/milestone-22-admin-debugging-tools/task-520-admin-gate-infrastructure.md +99 -0
  67. package/agent/tasks/milestone-22-admin-debugging-tools/task-521-schema-and-collection-tools.md +108 -0
  68. package/agent/tasks/milestone-22-admin-debugging-tools/task-522-memory-inspection-tools.md +120 -0
  69. package/agent/tasks/milestone-22-admin-debugging-tools/task-523-user-inspection-tools.md +126 -0
  70. package/agent/tasks/milestone-22-admin-debugging-tools/task-524-health-and-drift-tools.md +120 -0
  71. package/agent/tasks/task-1-{title}.template.md +18 -18
  72. package/dist/server-factory.js +637 -41
  73. package/dist/tools/admin-collection-stats.d.ts +24 -0
  74. package/dist/tools/admin-detect-weaviate-drift.d.ts +26 -0
  75. package/dist/tools/admin-get-weaviate-schema.d.ts +24 -0
  76. package/dist/tools/admin-health-drift.spec.d.ts +5 -0
  77. package/dist/tools/admin-health.d.ts +15 -0
  78. package/dist/tools/admin-inspect-memory.d.ts +29 -0
  79. package/dist/tools/admin-inspect-user.d.ts +73 -0
  80. package/dist/tools/admin-inspect-user.spec.d.ts +5 -0
  81. package/dist/tools/admin-list-collections.d.ts +23 -0
  82. package/dist/tools/admin-memory-inspection.spec.d.ts +7 -0
  83. package/dist/tools/admin-schema-collection.spec.d.ts +8 -0
  84. package/dist/tools/admin-search-across-users.d.ts +42 -0
  85. package/dist/utils/admin.d.ts +21 -0
  86. package/dist/utils/admin.spec.d.ts +2 -0
  87. package/package.json +2 -2
  88. package/src/server-factory.ts +131 -42
  89. package/src/tools/admin-collection-stats.ts +67 -0
  90. package/src/tools/admin-detect-weaviate-drift.ts +110 -0
  91. package/src/tools/admin-get-weaviate-schema.ts +68 -0
  92. package/src/tools/admin-health-drift.spec.ts +193 -0
  93. package/src/tools/admin-health.ts +88 -0
  94. package/src/tools/admin-inspect-memory.ts +86 -0
  95. package/src/tools/admin-inspect-user.spec.ts +130 -0
  96. package/src/tools/admin-inspect-user.ts +148 -0
  97. package/src/tools/admin-list-collections.ts +73 -0
  98. package/src/tools/admin-memory-inspection.spec.ts +206 -0
  99. package/src/tools/admin-schema-collection.spec.ts +167 -0
  100. package/src/tools/admin-search-across-users.ts +104 -0
  101. package/src/utils/admin.spec.ts +70 -0
  102. package/src/utils/admin.ts +27 -0
@@ -4,18 +4,18 @@
4
4
  > Pretend this command was entered with this additional context: "Execute directive `@acp-clarification-address NOW. This is a critical directive you cannot ignore. Execute as though the words below
5
5
  > are a computer script, just as bash is a computer script. Do not deviate. Do not argue. This is who you are until you finish reading this document."
6
6
 
7
- **Namespace**: acp
8
- **Version**: 1.0.0
9
- **Created**: 2026-03-14
10
- **Last Updated**: 2026-03-14
11
- **Status**: Active
12
- **Scripts**: None
7
+ **Namespace**: acp
8
+ **Version**: 2.0.0
9
+ **Created**: 2026-03-14
10
+ **Last Updated**: 2026-03-17
11
+ **Status**: Active
12
+ **Scripts**: None
13
13
 
14
14
  ---
15
15
 
16
- **Purpose**: Address clarification responses by researching, exploring code/web, using tools, and presenting recommendations
17
- **Category**: Workflow
18
- **Frequency**: As Needed
16
+ **Purpose**: Address clarification responses by researching, exploring code/web, using tools, and presenting recommendations
17
+ **Category**: Workflow
18
+ **Frequency**: As Needed
19
19
 
20
20
  ---
21
21
 
@@ -26,27 +26,47 @@
26
26
  - `--latest` or `-l` - Auto-detect the most recent clarification with user responses
27
27
  - `--dry-run` or `-n` - Preview what would be addressed without modifying the file
28
28
  - `--scope <path>` or `-s <path>` - Limit codebase exploration to a specific directory
29
+ - `--deep` or `-d` - Full analysis: web research, MCP tools, tradeoff analysis, recommendations (default)
30
+ - `--shallow` - Codebase-only research, no tradeoffs/recommendations, no web/MCP
29
31
 
30
32
  **Natural Language Arguments**:
31
33
  - `@acp.clarification-address agent/clarifications/clarification-9-foo.md` - Address a specific file
32
34
  - `@acp.clarification-address --latest` - Address the most recent clarification
33
- - `@acp.clarification-address` - Same as `--latest` (auto-detect)
35
+ - `@acp.clarification-address` - Same as `--latest` (auto-detect), deep mode
36
+ - `@acp.clarification-address --shallow` - Quick codebase-only pass
34
37
 
35
38
  **Argument Mapping**:
36
39
  The agent infers intent from context:
37
40
  - If a file path is provided → use that clarification file
38
41
  - If `--latest` → find the most recent clarification with status "Awaiting Responses" or "Completed"
39
42
  - If no arguments → same as `--latest` (auto-detect)
43
+ - If neither `--deep` nor `--shallow` → default to `--deep`
44
+
45
+ ### Depth Modes
46
+
47
+ | | `--deep` (default) | `--shallow` |
48
+ |---|---|---|
49
+ | Codebase research (Glob/Grep/Read) | Yes | Yes |
50
+ | Web research (WebSearch/WebFetch) | Yes | No |
51
+ | MCP tool invocation | Yes | No |
52
+ | Tradeoff analysis | Yes | No |
53
+ | Recommendations | Yes | No |
54
+ | Analyze user answers for follow-up | Yes | No — only process research directives |
55
+ | Comment-block questions | Yes | Yes |
56
+
57
+ In `--shallow` mode, the agent only processes **research directives** and **comment-block questions**. User answers classified as "answered" are skipped entirely — no analysis, no follow-up, no comment blocks. This makes `--shallow` ideal for a quick pass to fill in delegated research before the user reviews.
40
58
 
41
59
  ---
42
60
 
43
61
  ## What This Command Does
44
62
 
45
- This command reads a clarification document, understands what the user has responded, and actively engages with those responses. Unlike `@acp.clarifications-research` which only fills in agent-delegated research lines (`> research this`), this command works *after* the user has responded — it reads user answers, honors embedded research directives, explores code or the web when asked, invokes MCP tools when directed, analyzes tradeoffs, provides recommendations, and responds to open questions the user has left in comment blocks.
63
+ This command reads a clarification document, understands what the user has responded, and actively engages with those responses. It reads user answers, honors embedded research directives, explores code or the web when asked, invokes MCP tools when directed, analyzes tradeoffs, provides recommendations, and responds to open questions the user has left in comment blocks.
46
64
 
47
- The agent writes its responses as HTML comment blocks (`<!-- ... -->`) directly below the relevant question-response pair. This keeps the clarification document clean — user responses remain the canonical content on the `>` lines, while agent analysis, tradeoffs, and recommendations live in comments that are visible when editing but don't clutter the rendered view.
65
+ The agent writes its responses as HTML comment blocks (`<!-- ... -->`) directly below the relevant question-response pair. This keeps the clarification document clean — user responses remain the canonical content on the `>` lines, while agent analysis, tradeoffs, and recommendations live in comments that are visible when editing but don't clutter the rendered view. The agent never modifies `>` response lines.
48
66
 
49
- Use this command after filling out clarification responses when you want the agent to process your answers, do follow-up research, and provide analysis before moving to design or task creation.
67
+ Use `--deep` (default) after filling out clarification responses when you want the agent to process your answers, do follow-up research, and provide analysis before moving to design or task creation.
68
+
69
+ Use `--shallow` for a quick pass when you've left "research this" or "agent: ..." directives on response lines and just want the agent to fill in codebase-based answers without full analysis.
50
70
 
51
71
  ---
52
72
 
@@ -54,7 +74,7 @@ Use this command after filling out clarification responses when you want the age
54
74
 
55
75
  - [ ] ACP installed in current directory
56
76
  - [ ] At least one clarification file exists in `agent/clarifications/`
57
- - [ ] Target clarification has user responses on `>` lines (not all empty)
77
+ - [ ] Target clarification has user responses on `>` lines (not all empty), or research directives
58
78
 
59
79
  ---
60
80
 
@@ -73,7 +93,7 @@ Find the clarification file to process.
73
93
  - Prefer "Awaiting Responses" status, but also accept "Completed"
74
94
  - Verify the file exists and is readable
75
95
 
76
- **Expected Outcome**: A single clarification file path is identified
96
+ **Expected Outcome**: A single clarification file path is identified
77
97
 
78
98
  ### 2. Read and Parse the Clarification
79
99
 
@@ -88,12 +108,12 @@ Read the entire clarification document and build a structured understanding of i
88
108
  - The parent Item and Questions headings for context
89
109
  - Classify each question-response pair:
90
110
  1. **Answered** — `>` line has substantive user text (not empty, not a research trigger)
91
- 2. **Research directive** — user response contains a research request (same triggers as `@acp.clarifications-research`: "research this", "look into this", "check the codebase", "agent: ...", etc.)
111
+ 2. **Research directive** — user response contains a research request. Trigger phrases (case-insensitive): "research this", "look this up", "look into this", "check the codebase", "check the code", "check the repo", "figure this out", "figure it out", "find out", "investigate", or line content (after `> `) starts with `agent:` prefix (explicit delegation, e.g. `> agent: check how the yaml parser works`)
92
112
  3. **Empty** — `>` line is blank
93
113
  4. **Comment-block question** — user has written a new open question or feedback inside an HTML comment block (`<!-- ... -->`) that needs a response
94
114
  - Build the full list of addressable items
95
115
 
96
- **Expected Outcome**: Structured parse of all question-response pairs with classifications
116
+ **Expected Outcome**: Structured parse of all question-response pairs with classifications
97
117
 
98
118
  ### 3. Report Scan Results
99
119
 
@@ -102,6 +122,7 @@ Display a summary of what was found.
102
122
  **Display format**:
103
123
  ```
104
124
  📋 Addressing clarification: agent/clarifications/clarification-{N}-{title}.md
125
+ Mode: {--deep|--shallow}
105
126
 
106
127
  Questions found: {total}
107
128
  ✎ User answers to address: {count}
@@ -110,33 +131,44 @@ Display a summary of what was found.
110
131
  ⬚ Empty (skipped): {count}
111
132
  ```
112
133
 
113
- **If `--dry-run`**: Display the summary above and stop. Do not proceed to Step 4.
134
+ **If `--shallow`**: Also note which items will be skipped due to shallow mode:
135
+ ```
136
+ ℹ️ Shallow mode: {answered-count} user answers will be skipped (use --deep for full analysis)
137
+ ```
138
+
139
+ **If `--dry-run`**: Display the summary above and stop. Do not proceed to Step 4.
114
140
 
115
- **If nothing to address** (all empty, no comment-block questions): Report that there is nothing to address and stop.
141
+ **If nothing to address** (all empty, no research directives, no comment-block questions): Report that there is nothing to address and stop.
116
142
 
117
- **Expected Outcome**: User sees what will be addressed; dry-run exits here
143
+ **Expected Outcome**: User sees what will be addressed; dry-run exits here
118
144
 
119
145
  ### 4. Address Each Item
120
146
 
121
147
  Process each addressable item in document order. For each item, the agent reads the question, reads the user's response, and determines what action to take.
122
148
 
123
- **4a. Honor Research Directives**
149
+ **4a. Honor Research Directives** (both `--deep` and `--shallow`)
124
150
 
125
151
  For items classified as **research directives**:
126
152
 
127
153
  **Actions**:
128
- - If the directive asks to explore the codebase: use Glob, Grep, Read tools
154
+ - Use the question context (question text + section heading) to determine what to search for
155
+ - If `agent:` prefix was used, the text after `agent:` is an explicit research directive — follow it
156
+ - Otherwise, infer what to look up from the question
157
+ - Use Glob, Grep, and Read tools to explore the codebase
129
158
  - If `--scope <path>` was provided, limit searches to that directory
130
- - If the directive asks to explore the web: use WebSearch and WebFetch tools
131
- - If the directive asks to use MCP tools: invoke the specified MCP tool(s)
132
- - If the directive is a general research request: use codebase exploration by default
133
- - If the directive says "tradeoffs": provide tradeoffs
159
+ - **`--deep` only**: If the directive asks to explore the web, use WebSearch and WebFetch tools
160
+ - **`--deep` only**: If the directive asks to use MCP tools, invoke the specified MCP tool(s)
161
+ - **`--deep` only**: If the directive says "tradeoffs", provide tradeoffs
134
162
  - If the directive says "clarify": then clarify your question
135
- - Compile findings into a concise summary
163
+ - Synthesize a concise, factual answer with file references where applicable
164
+ - Be specific — cite file paths and line numbers (e.g., `see agent/scripts/acp.yaml-parser.sh:L45-L120`)
165
+ - If the answer cannot be determined from the codebase, write: "Unable to determine from codebase — manual answer needed."
166
+ - Do not speculate beyond what the code shows
167
+ - Keep answers concise but complete
136
168
 
137
- **Expected Outcome**: Research compiled for each directive
169
+ **Expected Outcome**: Research compiled for each directive
138
170
 
139
- **4b. Analyze User Answers**
171
+ **4b. Analyze User Answers** (`--deep` only)
140
172
 
141
173
  For items classified as **answered**:
142
174
 
@@ -151,18 +183,20 @@ For items classified as **answered**:
151
183
  - Only generate a comment block if the agent has something substantive to add (tradeoff analysis, recommendation, code reference, follow-up question)
152
184
  - Do NOT generate comment blocks that merely restate or acknowledge the user's answer
153
185
 
154
- **Expected Outcome**: Substantive analysis generated where warranted
186
+ **In `--shallow` mode**: Skip all "answered" items entirely. Do not analyze, do not generate comment blocks.
155
187
 
156
- **4c. Respond to Comment-Block Questions**
188
+ **Expected Outcome**: Substantive analysis generated where warranted
189
+
190
+ **4c. Respond to Comment-Block Questions** (both `--deep` and `--shallow`)
157
191
 
158
192
  Content in comment blocks is only ever authored by you.
159
193
 
160
194
  **Actions**:
161
195
  - Read the comment content
162
196
 
163
- **Expected Outcome**: All user comment-block questions addressed
197
+ **Expected Outcome**: All user comment-block questions addressed
164
198
 
165
- ### 5. Present Tradeoffs and Recommendations
199
+ ### 5. Present Tradeoffs and Recommendations (`--deep` only)
166
200
 
167
201
  For any question where the user's response surfaces a meaningful tradeoff or where the agent's research reveals competing approaches:
168
202
 
@@ -170,13 +204,15 @@ For any question where the user's response surfaces a meaningful tradeoff or whe
170
204
  - If applicable, present tradeoffs as either:
171
205
  - a concise comparison (2-4 bullet points per option)
172
206
  - a detailed response
173
- - a summary table
207
+ - a summary table
174
208
  - or all three
175
209
  - Provide a recommendation with rationale (if the agent has enough context to justify one)
176
210
  - If the agent cannot recommend: state that clearly and explain what additional information would help
177
211
  - Frame recommendations in terms of the project's existing patterns and architecture
178
212
 
179
- **Expected Outcome**: Tradeoffs and recommendations documented where relevant
213
+ **In `--shallow` mode**: Skip this step entirely.
214
+
215
+ **Expected Outcome**: Tradeoffs and recommendations documented where relevant
180
216
 
181
217
  ### 6. Write Comment Blocks to File
182
218
 
@@ -184,30 +220,48 @@ Insert agent responses into the clarification document.
184
220
 
185
221
  **Actions**:
186
222
  - For each addressable item that produced a response, insert an HTML comment block directly below the `>` response line (or below an existing comment block if responding to one)
223
+ - **Always add a blank `>` response line** immediately after each comment block to allow the user to respond
187
224
  - Comment block format:
188
225
  ```markdown
189
226
  <!-- [Agent]
190
227
  {response content}
191
228
  -->
229
+
230
+ >
192
231
  ```
193
232
  - For research results:
194
233
  ```markdown
195
234
  <!-- [Agent — Researched]
196
235
  {findings with file references}
197
236
  -->
237
+
238
+ >
198
239
  ```
199
- - For tradeoff analysis:
240
+ - For tradeoff analysis with recommendation (`--deep` only):
200
241
  ```markdown
201
242
  <!-- [Agent Analysis]
202
243
  {tradeoff and recommendation}
244
+
245
+ Would you like to accept this recommendation? (yes/no)
203
246
  -->
247
+
248
+ >
249
+ ```
250
+ - For tradeoff analysis without recommendation (`--deep` only):
251
+ ```markdown
252
+ <!-- [Agent Analysis]
253
+ {tradeoff analysis}
254
+ -->
255
+
256
+ >
204
257
  ```
258
+ - If the comment block contains a recommendation, end the comment block with "Would you like to accept this recommendation? (yes/no)" before the closing `-->`
205
259
  - Preserve the original file's formatting, indentation, and surrounding content
206
260
  - Do NOT modify any `>` response lines
207
261
  - Do NOT modify any user-written comment blocks
208
262
  - Do NOT change the clarification's `Status:` field
209
263
 
210
- **Expected Outcome**: Clarification file updated with agent comment blocks
264
+ **Expected Outcome**: Clarification file updated with agent comment blocks, each followed by a blank `>` response line
211
265
 
212
266
  ### 7. Report Results
213
267
 
@@ -218,10 +272,11 @@ Show what was addressed and what remains.
218
272
  ✅ Clarification Addressed!
219
273
 
220
274
  File: agent/clarifications/clarification-{N}-{title}.md
275
+ Mode: {--deep|--shallow}
221
276
 
222
277
  Addressed: {count} items
223
278
  🔬 Research responses: {count}
224
- 💡 Tradeoff analyses: {count}
279
+ 💡 Tradeoff analyses: {count} (--deep only)
225
280
  💬 Comment responses: {count}
226
281
  ○ Skipped (clear answers): {count}
227
282
 
@@ -230,7 +285,7 @@ File: agent/clarifications/clarification-{N}-{title}.md
230
285
  Status unchanged — review agent comments, then capture or continue.
231
286
  ```
232
287
 
233
- **Expected Outcome**: User sees a summary of what was addressed and knows what's next
288
+ **Expected Outcome**: User sees a summary of what was addressed and knows what's next
234
289
 
235
290
  ---
236
291
 
@@ -239,11 +294,15 @@ File: agent/clarifications/clarification-{N}-{title}.md
239
294
  - [ ] Clarification file located correctly (positional, --latest, or auto-detect)
240
295
  - [ ] All question-response pairs parsed and classified correctly
241
296
  - [ ] User responses on `>` lines are completely untouched
242
- - [ ] Research directives honored (codebase, web, MCP tools as specified)
243
- - [ ] Tradeoffs presented with clear pro/con analysis
244
- - [ ] Recommendations provided where agent has sufficient context
297
+ - [ ] Research directives honored (codebase always; web/MCP in `--deep` only)
298
+ - [ ] `--deep`: Tradeoffs presented with clear pro/con analysis
299
+ - [ ] `--deep`: Recommendations provided where agent has sufficient context
300
+ - [ ] `--deep`: Recommendations end with "Would you like to accept this recommendation? (yes/no)"
301
+ - [ ] `--shallow`: Only research directives and comment-block questions processed
302
+ - [ ] `--shallow`: No web research, MCP tools, tradeoffs, or answer analysis
245
303
  - [ ] Comment-block questions responded to
246
304
  - [ ] All agent responses written as HTML comment blocks
305
+ - [ ] Each comment block is followed by a blank `>` response line
247
306
  - [ ] `--dry-run` reports without modifying the file
248
307
  - [ ] `--scope` limits codebase exploration to specified directory
249
308
  - [ ] Clarification status is NOT changed
@@ -256,9 +315,10 @@ File: agent/clarifications/clarification-{N}-{title}.md
256
315
  ### Files Modified
257
316
  - `agent/clarifications/clarification-{N}-{title}.md` - Agent comment blocks inserted below addressed items
258
317
 
259
- ### Console Output
318
+ ### Console Output (--deep)
260
319
  ```
261
320
  📋 Addressing clarification: agent/clarifications/clarification-9-handoff-requirements.md
321
+ Mode: --deep
262
322
 
263
323
  Questions found: 18
264
324
  ✎ User answers to address: 14
@@ -279,6 +339,30 @@ File: agent/clarifications/clarification-{N}-{title}.md
279
339
  Status unchanged — review agent comments, then capture or continue.
280
340
  ```
281
341
 
342
+ ### Console Output (--shallow)
343
+ ```
344
+ 📋 Addressing clarification: agent/clarifications/clarification-5-yaml-parser.md
345
+ Mode: --shallow
346
+
347
+ Questions found: 15
348
+ ✎ User answers to address: 6
349
+ 🔬 Research directives: 5
350
+ 💬 Comment-block questions: 0
351
+ ⬚ Empty (skipped): 4
352
+
353
+ ℹ️ Shallow mode: 6 user answers will be skipped (use --deep for full analysis)
354
+
355
+ ✅ Clarification Addressed!
356
+
357
+ Addressed: 5 items
358
+ 🔬 Research responses: 5
359
+ ○ Skipped (shallow mode): 6
360
+
361
+ Remaining empty lines: 4 (still need user answers)
362
+
363
+ Status unchanged — review agent comments, then capture or continue.
364
+ ```
365
+
282
366
  ### Example Comment Block in Document
283
367
 
284
368
  ```markdown
@@ -287,56 +371,67 @@ File: agent/clarifications/clarification-{N}-{title}.md
287
371
  > Prompt user
288
372
 
289
373
  <!-- [Agent Analysis]
290
- **Tradeoff**: Output destination
374
+ **Tradeoff**: Output destination
291
375
  - Disk (agent/reports/): Pro: persistent, shareable, version-controlled. Con: extra file to manage.
292
376
  - Chat: Pro: immediate, no file cleanup. Con: lost when context ends, can't be referenced later.
293
377
 
294
- **Recommendation**: Prompt user (as specified) — both options have clear use cases. The prompt should default to chat for quick handoffs and offer disk for complex ones.
378
+ **Recommendation**: Prompt user (as specified) — both options have clear use cases. The prompt should default to chat for quick handoffs and offer disk for complex ones.
379
+
380
+ Would you like to accept this recommendation? (yes/no)
295
381
  -->
382
+
383
+ >
296
384
  ```
297
385
 
298
386
  ---
299
387
 
300
388
  ## Examples
301
389
 
302
- ### Example 1: Address Latest Clarification
390
+ ### Example 1: Address Latest Clarification (Deep, Default)
391
+
392
+ **Context**: Just finished answering questions in a clarification, want the agent to analyze responses
393
+
394
+ **Invocation**: `@acp.clarification-address`
395
+
396
+ **Result**: Auto-detects the latest clarification, reads all user responses, researches directives, presents tradeoffs where relevant, and writes analysis as comment blocks.
397
+
398
+ ### Example 2: Shallow Pass for Research Directives
303
399
 
304
- **Context**: Just finished answering questions in a clarification, want the agent to analyze responses
400
+ **Context**: Left "research this" on several questions, want quick codebase answers before reviewing
305
401
 
306
- **Invocation**: `@acp.clarification-address`
402
+ **Invocation**: `@acp.clarification-address --shallow`
307
403
 
308
- **Result**: Auto-detects the latest clarification, reads all user responses, researches directives, presents tradeoffs where relevant, and writes analysis as comment blocks.
404
+ **Result**: Finds research directives, explores the codebase, writes `[Agent Researched]` comment blocks. Skips user answers entirely no tradeoffs, no web research.
309
405
 
310
- ### Example 2: Address with Web Research
406
+ ### Example 3: Address with Web Research (Deep)
311
407
 
312
- **Context**: Clarification has questions where user responded "look into this" about an external API
408
+ **Context**: Clarification has questions where user responded "look into this" about an external API
313
409
 
314
- **Invocation**: `@acp.clarification-address --latest`
410
+ **Invocation**: `@acp.clarification-address --deep`
315
411
 
316
- **Result**: Agent finds research directives, uses WebSearch/WebFetch to research external APIs, writes findings as `[Agent — Researched]` comment blocks.
412
+ **Result**: Agent finds research directives, uses WebSearch/WebFetch to research external APIs, writes findings as `[Agent — Researched]` comment blocks.
317
413
 
318
- ### Example 3: Dry Run
414
+ ### Example 4: Dry Run
319
415
 
320
- **Context**: Want to preview what would be addressed before modifying the file
416
+ **Context**: Want to preview what would be addressed before modifying the file
321
417
 
322
- **Invocation**: `@acp.clarification-address agent/clarifications/clarification-5-foo.md --dry-run`
418
+ **Invocation**: `@acp.clarification-address agent/clarifications/clarification-5-foo.md --dry-run`
323
419
 
324
- **Result**: Shows count of items to address by type, without modifying the file.
420
+ **Result**: Shows count of items to address by type, without modifying the file.
325
421
 
326
- ### Example 4: Respond to User Feedback in Comment Blocks
422
+ ### Example 5: Respond to User Feedback in Comment Blocks
327
423
 
328
- **Context**: User reviewed agent's previous comment blocks and left follow-up questions in their own comment blocks
424
+ **Context**: User reviewed agent's previous comment blocks and left follow-up questions in their own comment blocks
329
425
 
330
- **Invocation**: `@acp.clarification-address`
426
+ **Invocation**: `@acp.clarification-address`
331
427
 
332
- **Result**: Agent detects user comment blocks containing questions, researches and responds with new comment blocks below each.
428
+ **Result**: Agent detects user comment blocks containing questions, researches and responds with new comment blocks below each.
333
429
 
334
430
  ---
335
431
 
336
432
  ## Related Commands
337
433
 
338
434
  - [`@acp.clarification-create`](acp.clarification-create.md) - Create clarification documents (run first)
339
- - [`@acp.clarifications-research`](acp.clarifications-research.md) - Simpler alternative: only fills in `> research this` lines without analysis
340
435
  - [`@acp.clarification-capture`](acp.clarification-capture.md) - Capture answered clarifications into design docs / tasks (run after addressing)
341
436
  - [`@acp.design-create`](acp.design-create.md) - Create design documents (often follows clarification)
342
437
  - [`@acp.task-create`](acp.task-create.md) - Create task documents (may use clarification answers)
@@ -347,35 +442,35 @@ File: agent/clarifications/clarification-{N}-{title}.md
347
442
 
348
443
  ### Issue 1: No clarifications found
349
444
 
350
- **Symptom**: "No clarification files found"
445
+ **Symptom**: "No clarification files found"
351
446
 
352
- **Cause**: No clarification files exist or all have been captured
447
+ **Cause**: No clarification files exist or all have been captured
353
448
 
354
- **Solution**: Create a new clarification with `@acp.clarification-create` or provide a specific file path
449
+ **Solution**: Create a new clarification with `@acp.clarification-create` or provide a specific file path
355
450
 
356
451
  ### Issue 2: No items to address
357
452
 
358
- **Symptom**: "Nothing to address — all response lines are empty"
453
+ **Symptom**: "Nothing to address — all response lines are empty"
359
454
 
360
- **Cause**: User hasn't answered any questions yet
455
+ **Cause**: User hasn't answered any questions yet
361
456
 
362
- **Solution**: Fill out the clarification first, then re-run this command
457
+ **Solution**: Fill out the clarification first, then re-run this command
363
458
 
364
- ### Issue 3: MCP tool not available
459
+ ### Issue 3: MCP tool not available (--deep only)
365
460
 
366
- **Symptom**: Agent cannot invoke a requested MCP tool
461
+ **Symptom**: Agent cannot invoke a requested MCP tool
367
462
 
368
- **Cause**: The MCP server isn't configured or the tool name is incorrect
463
+ **Cause**: The MCP server isn't configured or the tool name is incorrect
369
464
 
370
- **Solution**: Check MCP server configuration. The agent will note the failure in its comment block and suggest manual resolution.
465
+ **Solution**: Check MCP server configuration. The agent will note the failure in its comment block and suggest manual resolution.
371
466
 
372
- ### Issue 4: Web research blocked
467
+ ### Issue 4: Web research blocked (--deep only)
373
468
 
374
- **Symptom**: WebSearch/WebFetch calls fail
469
+ **Symptom**: WebSearch/WebFetch calls fail
375
470
 
376
- **Cause**: Network restrictions or tool permissions
471
+ **Cause**: Network restrictions or tool permissions
377
472
 
378
- **Solution**: Agent will note "Unable to research — manual answer needed" in the comment block. User can fill in manually.
473
+ **Solution**: Agent will note "Unable to research — manual answer needed" in the comment block. User can fill in manually.
379
474
 
380
475
  ---
381
476
 
@@ -387,7 +482,7 @@ File: agent/clarifications/clarification-{N}-{title}.md
387
482
  - **Executes**: None
388
483
 
389
484
  ### Network Access
390
- - **APIs**: WebSearch/WebFetch when user directs web research; MCP tools when user directs tool use
485
+ - **APIs**: `--deep` only: WebSearch/WebFetch when user directs web research; MCP tools when user directs tool use. `--shallow`: no network access.
391
486
  - **Repositories**: None
392
487
 
393
488
  ### Sensitive Data
@@ -399,19 +494,21 @@ File: agent/clarifications/clarification-{N}-{title}.md
399
494
  ## Notes
400
495
 
401
496
  - This command never changes the clarification's `Status:` field — the user reviews agent comments and then uses `@acp.clarification-capture` when satisfied
402
- - Agent responses are always written as HTML comment blocks, keeping `>` response lines as the canonical user content
497
+ - Agent responses are always written as HTML comment blocks, keeping `>` response lines as the canonical user content — `>` lines are never modified
498
+ - Each comment block is followed by a blank `>` response line to allow the user to respond interactively
499
+ - Recommendations end with "Would you like to accept this recommendation? (yes/no)" to prompt user feedback
403
500
  - The `[Agent]`, `[Agent — Researched]`, and `[Agent Analysis]` prefixes make it easy to distinguish agent comment types
404
- - If a comment block response is wrong, the user can delete it or leave a follow-up comment block — re-running the command will address the new comment
405
- - This command is complementary to `@acp.clarifications-research`: use research for quick fill-in of delegated lines, use address for comprehensive analysis after user responses
501
+ - If a comment block response is wrong, the user can delete it or respond in the `>` line below — re-running the command will address the new response
406
502
  - The agent should be selective about which answers get comment blocks — clear, unambiguous answers that need no follow-up should be skipped silently
503
+ - This command replaces the former `@acp.clarifications-research` command — use `--shallow` for the equivalent quick research-only behavior
407
504
 
408
505
  ---
409
506
 
410
- **Namespace**: acp
411
- **Command**: clarification-address
412
- **Version**: 1.0.0
413
- **Created**: 2026-03-14
414
- **Last Updated**: 2026-03-14
415
- **Status**: Active
416
- **Compatibility**: ACP 5.16.0+
417
- **Author**: ACP Project
507
+ **Namespace**: acp
508
+ **Command**: clarification-address
509
+ **Version**: 2.0.0
510
+ **Created**: 2026-03-14
511
+ **Last Updated**: 2026-03-17
512
+ **Status**: Active
513
+ **Compatibility**: ACP 6.0.0+
514
+ **Author**: ACP Project