@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.
- package/AGENT.md +10 -3
- package/CHANGELOG.md +19 -0
- package/README.md +1 -1
- package/agent/commands/acp.artifact-glossary.md +530 -0
- package/agent/commands/acp.artifact-reference.md +591 -0
- package/agent/commands/acp.artifact-research.md +594 -0
- package/agent/commands/acp.audit.md +345 -0
- package/agent/commands/acp.clarification-address.md +185 -88
- package/agent/commands/acp.clarification-capture.md +44 -44
- package/agent/commands/acp.clarification-create.md +41 -42
- package/agent/commands/acp.command-create.md +49 -49
- package/agent/commands/acp.design-create.md +53 -35
- package/agent/commands/acp.design-reference.md +42 -42
- package/agent/commands/acp.handoff.md +35 -35
- package/agent/commands/acp.index.md +47 -47
- package/agent/commands/acp.init.md +105 -69
- package/agent/commands/acp.package-create.md +41 -41
- package/agent/commands/acp.package-info.md +40 -40
- package/agent/commands/acp.package-install.md +48 -48
- package/agent/commands/acp.package-list.md +40 -40
- package/agent/commands/acp.package-publish.md +62 -62
- package/agent/commands/acp.package-remove.md +41 -41
- package/agent/commands/acp.package-search.md +48 -48
- package/agent/commands/acp.package-update.md +50 -50
- package/agent/commands/acp.package-validate.md +52 -52
- package/agent/commands/acp.pattern-create.md +61 -43
- package/agent/commands/acp.plan.md +70 -47
- package/agent/commands/acp.proceed.md +188 -66
- package/agent/commands/acp.project-create.md +42 -42
- package/agent/commands/acp.project-info.md +46 -46
- package/agent/commands/acp.project-list.md +41 -41
- package/agent/commands/acp.project-remove.md +36 -36
- package/agent/commands/acp.project-set.md +33 -33
- package/agent/commands/acp.project-update.md +57 -57
- package/agent/commands/acp.projects-restore.md +37 -37
- package/agent/commands/acp.projects-sync.md +39 -39
- package/agent/commands/acp.report.md +50 -50
- package/agent/commands/acp.resume.md +36 -36
- package/agent/commands/acp.sessions.md +46 -46
- package/agent/commands/acp.status.md +43 -43
- package/agent/commands/acp.sync.md +109 -56
- package/agent/commands/acp.task-create.md +51 -49
- package/agent/commands/acp.update.md +66 -45
- package/agent/commands/acp.validate.md +110 -52
- package/agent/commands/acp.version-check-for-updates.md +40 -40
- package/agent/commands/acp.version-check.md +36 -36
- package/agent/commands/acp.version-update.md +43 -43
- package/agent/commands/command.template.md +40 -40
- package/agent/commands/git.commit.md +28 -28
- package/agent/commands/git.init.md +48 -48
- package/agent/design/design.template.md +9 -9
- package/agent/design/local.admin-debugging-tools.md +242 -0
- package/agent/design/requirements.template.md +8 -8
- package/agent/index/.gitkeep +0 -0
- package/agent/index/acp.core.yaml +137 -0
- package/agent/index/local.main.template.yaml +37 -0
- package/agent/index/local.main.yaml +48 -0
- package/agent/manifest.yaml +64 -0
- package/agent/milestones/milestone-1-{title}.template.md +8 -8
- package/agent/milestones/milestone-22-admin-debugging-tools.md +61 -0
- package/agent/patterns/pattern.template.md +22 -22
- package/agent/progress.template.yaml +13 -3
- package/agent/progress.yaml +78 -1
- package/agent/schemas/package.schema.yaml +276 -0
- package/agent/scripts/acp.project-update.sh +5 -6
- package/agent/tasks/milestone-22-admin-debugging-tools/task-520-admin-gate-infrastructure.md +99 -0
- package/agent/tasks/milestone-22-admin-debugging-tools/task-521-schema-and-collection-tools.md +108 -0
- package/agent/tasks/milestone-22-admin-debugging-tools/task-522-memory-inspection-tools.md +120 -0
- package/agent/tasks/milestone-22-admin-debugging-tools/task-523-user-inspection-tools.md +126 -0
- package/agent/tasks/milestone-22-admin-debugging-tools/task-524-health-and-drift-tools.md +120 -0
- package/agent/tasks/task-1-{title}.template.md +18 -18
- package/dist/server-factory.js +637 -41
- package/dist/tools/admin-collection-stats.d.ts +24 -0
- package/dist/tools/admin-detect-weaviate-drift.d.ts +26 -0
- package/dist/tools/admin-get-weaviate-schema.d.ts +24 -0
- package/dist/tools/admin-health-drift.spec.d.ts +5 -0
- package/dist/tools/admin-health.d.ts +15 -0
- package/dist/tools/admin-inspect-memory.d.ts +29 -0
- package/dist/tools/admin-inspect-user.d.ts +73 -0
- package/dist/tools/admin-inspect-user.spec.d.ts +5 -0
- package/dist/tools/admin-list-collections.d.ts +23 -0
- package/dist/tools/admin-memory-inspection.spec.d.ts +7 -0
- package/dist/tools/admin-schema-collection.spec.d.ts +8 -0
- package/dist/tools/admin-search-across-users.d.ts +42 -0
- package/dist/utils/admin.d.ts +21 -0
- package/dist/utils/admin.spec.d.ts +2 -0
- package/package.json +2 -2
- package/src/server-factory.ts +131 -42
- package/src/tools/admin-collection-stats.ts +67 -0
- package/src/tools/admin-detect-weaviate-drift.ts +110 -0
- package/src/tools/admin-get-weaviate-schema.ts +68 -0
- package/src/tools/admin-health-drift.spec.ts +193 -0
- package/src/tools/admin-health.ts +88 -0
- package/src/tools/admin-inspect-memory.ts +86 -0
- package/src/tools/admin-inspect-user.spec.ts +130 -0
- package/src/tools/admin-inspect-user.ts +148 -0
- package/src/tools/admin-list-collections.ts +73 -0
- package/src/tools/admin-memory-inspection.spec.ts +206 -0
- package/src/tools/admin-schema-collection.spec.ts +167 -0
- package/src/tools/admin-search-across-users.ts +104 -0
- package/src/utils/admin.spec.ts +70 -0
- 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**:
|
|
9
|
-
**Created**: 2026-03-14
|
|
10
|
-
**Last Updated**: 2026-03-
|
|
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.
|
|
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
|
|
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
|
|
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 `--
|
|
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
|
-
-
|
|
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
|
|
131
|
-
- If the directive asks to use MCP tools
|
|
132
|
-
- If the directive
|
|
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
|
-
-
|
|
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
|
-
**
|
|
186
|
+
**In `--shallow` mode**: Skip all "answered" items entirely. Do not analyze, do not generate comment blocks.
|
|
155
187
|
|
|
156
|
-
**
|
|
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
|
-
**
|
|
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
|
|
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**:
|
|
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**:
|
|
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
|
|
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 --
|
|
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
|
|
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
|
|
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
|
|
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**:
|
|
413
|
-
**Created**: 2026-03-14
|
|
414
|
-
**Last Updated**: 2026-03-
|
|
415
|
-
**Status**: Active
|
|
416
|
-
**Compatibility**: ACP
|
|
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
|