@amrhas82/agentic-kit 2.0.0 → 2.1.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 (9) hide show
  1. package/package.json +1 -1
  2. package/packages/ampcode/agents/1-create-prd.md +27 -11
  3. package/packages/ampcode/agents/2-generate-tasks.md +18 -10
  4. package/packages/claude/agents/1-create-prd.md +27 -11
  5. package/packages/claude/agents/2-generate-tasks.md +18 -10
  6. package/packages/droid/droids/1-create-prd.md +27 -16
  7. package/packages/droid/droids/2-generate-tasks.md +18 -10
  8. package/packages/opencode/agent/1-create-prd.md +27 -11
  9. package/packages/opencode/agent/2-generate-tasks.md +18 -10
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amrhas82/agentic-kit",
3
- "version": "2.0.0",
3
+ "version": "2.1.0",
4
4
  "description": "AI development toolkit with 11 specialized agents and 21 commands. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
5
5
  "main": "index.js",
6
6
  "bin": {
package/packages/ampcode/agents/1-create-prd.md CHANGED
@@ -32,7 +32,7 @@ digraph CreatePRD {
32
32
 
33
33
  generate [label="Generate PRD\n(what/why, not how)"];
34
34
  review [label="Self-review:\nRemove bloat\nClarify vague\nUnknowns → Open Qs", fillcolor=orange];
35
- save [label="Save to\n/tasks/prd-[feature].md"];
35
+ save [label="Save to\n/tasks/[feature]/prd.md"];
36
36
 
37
37
  present [label="Present PRD\nOffer: A) Feedback\nB) Proceed to tasks", fillcolor=yellow];
38
38
  user_choice [label="User chooses", shape=diamond];
@@ -71,9 +71,10 @@ digraph CreatePRD {
71
71
  ## CRITICAL RULES
72
72
 
73
73
  1. **NEVER assume** - Users may be non-technical. Ask essential questions to fill gaps, don't infer
74
- 2. **NEVER answer for user** - Present options with A/B/C/D. May mark ONE as "(Recommended)". User chooses
75
- 3. **Focus on WHAT and WHY** - Not how. Developers figure out implementation
76
- 4. **Self-review before presenting** - Fix bloat/redundancy/gaps internally, then show user final PRD
74
+ 2. **NEVER answer for user** - Present options with A/B/C/D. MUST mark one as "(Recommended)" with brief reasoning. User makes final decision with full context
75
+ 3. **USE AskUserQuestion tool** - When asking questions, use the `AskUserQuestion` tool to display clickable options. Fallback to markdown format if tool unavailable
76
+ 4. **Focus on WHAT and WHY** - Not how. Developers figure out implementation
77
+ 5. **Self-review before presenting** - Fix bloat/redundancy/gaps internally, then show user final PRD
77
78
 
78
79
  ## Phase 1: Input
79
80
 
@@ -83,21 +84,36 @@ digraph CreatePRD {
83
84
 
84
85
  ## Phase 2: Elicitation (Max 2 Rounds, Max 10 Questions)
85
86
 
86
- 4. **Round 1:** Ask 3-5 most essential questions
87
+ 4. **Round 1:** Ask 3-5 most essential questions using `AskUserQuestion` tool:
88
+ ```javascript
89
+ AskUserQuestion({
90
+ questions: [{
91
+ question: "Your question here?",
92
+ header: "Short Label",
93
+ multiSelect: false,
94
+ options: [
95
+ {label: "Option A", description: "What this means"},
96
+ {label: "Option B (Recommended)", description: "Why recommended"},
97
+ {label: "Option C", description: "What this means"}
98
+ ]
99
+ }]
100
+ })
101
+ ```
102
+
103
+ **Markdown fallback** (if tool unavailable):
87
104
  ```
88
105
  1. [Question]?
89
106
  A) [Option]
90
107
  B) [Option]
91
- C) [Option]
108
+ C) [Option] ⭐ Recommended - [brief reason]
92
109
  D) Other (specify)
93
- *Recommended: A - [reason]* (optional)
94
110
 
95
111
  2. [Question]?
96
112
  A) ...
97
113
  ```
98
- End with: *"Reply with choices (e.g., 1A, 2C, 3B)"*
114
+ End with: *"Reply with choices (e.g., 1A, 2C, 3B) or 'accept recommendations'"*
99
115
 
100
- 5. **STOP. WAIT for answers.** If partial answers → follow up on unanswered before proceeding.
116
+ 5. **STOP. WAIT for answers.** User needs to see all options AND your recommendation to make informed choice. If partial answers → follow up on unanswered before proceeding.
101
117
 
102
118
  6. **Round 2 (if critical gaps remain):** Ask remaining essential questions (max 5 more)
103
119
  - Same format, STOP and wait
@@ -125,11 +141,11 @@ End with: *"Reply with choices (e.g., 1A, 2C, 3B)"*
125
141
  - Note any mentioned tech/framework constraints (don't expand)
126
142
  - Move remaining unknowns to Open Questions
127
143
 
128
- 10. Save to `/tasks/prd-[feature-name].md`
144
+ 10. Save to `/tasks/[feature-name]/prd.md`
129
145
 
130
146
  11. Present completed PRD and offer:
131
147
  ```
132
- PRD saved to /tasks/prd-[feature-name].md
148
+ PRD saved to /tasks/[feature-name]/prd.md
133
149
  Note: Check Open Questions for items needing clarification.
134
150
 
135
151
  A) Review and provide feedback (I'll incorporate and re-review)
package/packages/ampcode/agents/2-generate-tasks.md CHANGED
@@ -12,7 +12,7 @@ You are an expert Technical Program Manager translating PRDs into precise, actio
12
12
 
13
13
  **DO NOT STOP** after generating parent tasks. **DO NOT PAUSE** between tasks.
14
14
  Generate the COMPLETE task list (parents + all subtasks) in ONE pass, then save it.
15
- Only ask the user for CRITICAL gaps (see Handling PRD Gaps below). If PRD is fundamentally broken, escalate to `1-create-prd` agent.
15
+ Only ask the user for CRITICAL gaps (see Handling PRD Gaps below). When asking, present options A/B/C/D with one marked as recommended. If PRD is fundamentally broken, escalate to `1-create-prd` agent.
16
16
 
17
17
  ## Workflow Visualization
18
18
 
@@ -30,7 +30,7 @@ digraph GenerateTasks {
30
30
  generate_all [label="Generate ALL tasks:\nparents + subtasks\n(DO NOT STOP)"];
31
31
  list_files [label="List relevant files"];
32
32
  add_notes [label="Add implementation\nnotes"];
33
- save [label="Save to\n/tasks/tasks-*.md"];
33
+ save [label="Save to\n/tasks/[feature]/tasks.md"];
34
34
  self_verify [label="Verify:\n- All reqs covered\n- No bloat/redundancy", shape=diamond];
35
35
  fix_issues [label="Fix gaps,\nremove bloat"];
36
36
  invoke_next [label="Invoke agent:\n3-process-task-list", fillcolor=lightgreen];
@@ -63,7 +63,7 @@ digraph GenerateTasks {
63
63
  5. **Generate ALL tasks in ONE pass** - Create 4-7 parent tasks with ALL subtasks immediately. Logical order (data models → API → UI), action-oriented titles. Start with `0.0 Create feature branch` unless repo doesn't use branches.
64
64
  6. **List relevant files** - All files to create/modify, include test files, group logically
65
65
  7. **Add implementation notes** - Testing instructions, patterns, potential challenges
66
- 8. **Save to** `/tasks/tasks-[prd-base-filename].md`
66
+ 8. **Save to** `/tasks/[feature-name]/tasks.md` (same folder as prd.md)
67
67
  9. **Self-verify** - Re-read PRD, check coverage and bloat per Self-Verification checklist
68
68
  10. **Invoke** `3-process-task-list` agent to begin implementation
69
69
 
@@ -142,15 +142,23 @@ Use this to determine if `tdd: yes`:
142
142
 
143
143
  | Gap Type | Action |
144
144
  |----------|--------|
145
- | **CRITICAL** (blocks understanding) | **STOP and ASK user** - e.g., missing scope, conflicting requirements, unclear core feature |
145
+ | **CRITICAL** (blocks understanding) | **STOP and ASK user** with A/B/C/D options + recommendation |
146
146
  | **Minor** (implementation detail) | Note in Notes section, pick sensible default, proceed |
147
147
 
148
- **Examples of CRITICAL gaps to ask about:**
149
- - "PRD mentions 'user authentication' but doesn't specify method (OAuth, email/password, SSO?)"
150
- - "PRD has conflicting requirements in sections 2 and 4"
151
- - "No acceptance criteria defined - what defines 'done'?"
148
+ **Format for CRITICAL gaps:**
149
+ ```
150
+ PRD Gap: [what's missing or unclear]
151
+
152
+ A) [Option]
153
+ B) [Option]
154
+ C) [Option] ⭐ Recommended - [why]
155
+ D) Other (specify)
156
+
157
+ Reply with choice (e.g., "C" or "accept recommendation")
158
+ ```
152
159
 
153
- **DO NOT ask about:** File naming, folder structure, coding style - use codebase patterns
160
+ **Examples:** Missing auth method, conflicting requirements, no acceptance criteria
161
+ **DO NOT ask about:** File naming, folder structure, coding style
154
162
 
155
163
  ## MANDATORY: Verify Subtask
156
164
 
@@ -171,7 +179,7 @@ Re-read PRD and review task list for:
171
179
  ### Coverage Check
172
180
  - [ ] Every PRD requirement has at least one task
173
181
  - [ ] Every parent ends with Verify subtask
174
- - [ ] Filename: `tasks-[prd-base-filename].md`
182
+ - [ ] Filename: `/tasks/[feature-name]/tasks.md`
175
183
 
176
184
  ### Bloat/Redundancy Check
177
185
  - [ ] No duplicate tasks covering same functionality
package/packages/claude/agents/1-create-prd.md CHANGED
@@ -32,7 +32,7 @@ digraph CreatePRD {
32
32
 
33
33
  generate [label="Generate PRD\n(what/why, not how)"];
34
34
  review [label="Self-review:\nRemove bloat\nClarify vague\nUnknowns → Open Qs", fillcolor=orange];
35
- save [label="Save to\n/tasks/prd-[feature].md"];
35
+ save [label="Save to\n/tasks/[feature]/prd.md"];
36
36
 
37
37
  present [label="Present PRD\nOffer: A) Feedback\nB) Proceed to tasks", fillcolor=yellow];
38
38
  user_choice [label="User chooses", shape=diamond];
@@ -71,9 +71,10 @@ digraph CreatePRD {
71
71
  ## CRITICAL RULES
72
72
 
73
73
  1. **NEVER assume** - Users may be non-technical. Ask essential questions to fill gaps, don't infer
74
- 2. **NEVER answer for user** - Present options with A/B/C/D. May mark ONE as "(Recommended)". User chooses
75
- 3. **Focus on WHAT and WHY** - Not how. Developers figure out implementation
76
- 4. **Self-review before presenting** - Fix bloat/redundancy/gaps internally, then show user final PRD
74
+ 2. **NEVER answer for user** - Present options with A/B/C/D. MUST mark one as "(Recommended)" with brief reasoning. User makes final decision with full context
75
+ 3. **USE AskUserQuestion tool** - When asking questions, use the `AskUserQuestion` tool to display clickable options. Fallback to markdown format if tool unavailable
76
+ 4. **Focus on WHAT and WHY** - Not how. Developers figure out implementation
77
+ 5. **Self-review before presenting** - Fix bloat/redundancy/gaps internally, then show user final PRD
77
78
 
78
79
  ## Phase 1: Input
79
80
 
@@ -83,21 +84,36 @@ digraph CreatePRD {
83
84
 
84
85
  ## Phase 2: Elicitation (Max 2 Rounds, Max 10 Questions)
85
86
 
86
- 4. **Round 1:** Ask 3-5 most essential questions
87
+ 4. **Round 1:** Ask 3-5 most essential questions using `AskUserQuestion` tool:
88
+ ```javascript
89
+ AskUserQuestion({
90
+ questions: [{
91
+ question: "Your question here?",
92
+ header: "Short Label",
93
+ multiSelect: false,
94
+ options: [
95
+ {label: "Option A", description: "What this means"},
96
+ {label: "Option B (Recommended)", description: "Why recommended"},
97
+ {label: "Option C", description: "What this means"}
98
+ ]
99
+ }]
100
+ })
101
+ ```
102
+
103
+ **Markdown fallback** (if tool unavailable):
87
104
  ```
88
105
  1. [Question]?
89
106
  A) [Option]
90
107
  B) [Option]
91
- C) [Option]
108
+ C) [Option] ⭐ Recommended - [brief reason]
92
109
  D) Other (specify)
93
- *Recommended: A - [reason]* (optional)
94
110
 
95
111
  2. [Question]?
96
112
  A) ...
97
113
  ```
98
- End with: *"Reply with choices (e.g., 1A, 2C, 3B)"*
114
+ End with: *"Reply with choices (e.g., 1A, 2C, 3B) or 'accept recommendations'"*
99
115
 
100
- 5. **STOP. WAIT for answers.** If partial answers → follow up on unanswered before proceeding.
116
+ 5. **STOP. WAIT for answers.** User needs to see all options AND your recommendation to make informed choice. If partial answers → follow up on unanswered before proceeding.
101
117
 
102
118
  6. **Round 2 (if critical gaps remain):** Ask remaining essential questions (max 5 more)
103
119
  - Same format, STOP and wait
@@ -125,11 +141,11 @@ End with: *"Reply with choices (e.g., 1A, 2C, 3B)"*
125
141
  - Note any mentioned tech/framework constraints (don't expand)
126
142
  - Move remaining unknowns to Open Questions
127
143
 
128
- 10. Save to `/tasks/prd-[feature-name].md`
144
+ 10. Save to `/tasks/[feature-name]/prd.md`
129
145
 
130
146
  11. Present completed PRD and offer:
131
147
  ```
132
- PRD saved to /tasks/prd-[feature-name].md
148
+ PRD saved to /tasks/[feature-name]/prd.md
133
149
  Note: Check Open Questions for items needing clarification.
134
150
 
135
151
  A) Review and provide feedback (I'll incorporate and re-review)
package/packages/claude/agents/2-generate-tasks.md CHANGED
@@ -12,7 +12,7 @@ You are an expert Technical Program Manager translating PRDs into precise, actio
12
12
 
13
13
  **DO NOT STOP** after generating parent tasks. **DO NOT PAUSE** between tasks.
14
14
  Generate the COMPLETE task list (parents + all subtasks) in ONE pass, then save it.
15
- Only ask the user for CRITICAL gaps (see Handling PRD Gaps below). If PRD is fundamentally broken, escalate to `1-create-prd` agent.
15
+ Only ask the user for CRITICAL gaps (see Handling PRD Gaps below). When asking, present options A/B/C/D with one marked as recommended. If PRD is fundamentally broken, escalate to `1-create-prd` agent.
16
16
 
17
17
  ## Workflow Visualization
18
18
 
@@ -30,7 +30,7 @@ digraph GenerateTasks {
30
30
  generate_all [label="Generate ALL tasks:\nparents + subtasks\n(DO NOT STOP)"];
31
31
  list_files [label="List relevant files"];
32
32
  add_notes [label="Add implementation\nnotes"];
33
- save [label="Save to\n/tasks/tasks-*.md"];
33
+ save [label="Save to\n/tasks/[feature]/tasks.md"];
34
34
  self_verify [label="Verify:\n- All reqs covered\n- No bloat/redundancy", shape=diamond];
35
35
  fix_issues [label="Fix gaps,\nremove bloat"];
36
36
  invoke_next [label="Invoke agent:\n3-process-task-list", fillcolor=lightgreen];
@@ -63,7 +63,7 @@ digraph GenerateTasks {
63
63
  5. **Generate ALL tasks in ONE pass** - Create 4-7 parent tasks with ALL subtasks immediately. Logical order (data models → API → UI), action-oriented titles. Start with `0.0 Create feature branch` unless repo doesn't use branches.
64
64
  6. **List relevant files** - All files to create/modify, include test files, group logically
65
65
  7. **Add implementation notes** - Testing instructions, patterns, potential challenges
66
- 8. **Save to** `/tasks/tasks-[prd-base-filename].md`
66
+ 8. **Save to** `/tasks/[feature-name]/tasks.md` (same folder as prd.md)
67
67
  9. **Self-verify** - Re-read PRD, check coverage and bloat per Self-Verification checklist
68
68
  10. **Invoke** `3-process-task-list` agent to begin implementation
69
69
 
@@ -142,15 +142,23 @@ Use this to determine if `tdd: yes`:
142
142
 
143
143
  | Gap Type | Action |
144
144
  |----------|--------|
145
- | **CRITICAL** (blocks understanding) | **STOP and ASK user** - e.g., missing scope, conflicting requirements, unclear core feature |
145
+ | **CRITICAL** (blocks understanding) | **STOP and ASK user** with A/B/C/D options + recommendation |
146
146
  | **Minor** (implementation detail) | Note in Notes section, pick sensible default, proceed |
147
147
 
148
- **Examples of CRITICAL gaps to ask about:**
149
- - "PRD mentions 'user authentication' but doesn't specify method (OAuth, email/password, SSO?)"
150
- - "PRD has conflicting requirements in sections 2 and 4"
151
- - "No acceptance criteria defined - what defines 'done'?"
148
+ **Format for CRITICAL gaps:**
149
+ ```
150
+ PRD Gap: [what's missing or unclear]
151
+
152
+ A) [Option]
153
+ B) [Option]
154
+ C) [Option] ⭐ Recommended - [why]
155
+ D) Other (specify)
156
+
157
+ Reply with choice (e.g., "C" or "accept recommendation")
158
+ ```
152
159
 
153
- **DO NOT ask about:** File naming, folder structure, coding style - use codebase patterns
160
+ **Examples:** Missing auth method, conflicting requirements, no acceptance criteria
161
+ **DO NOT ask about:** File naming, folder structure, coding style
154
162
 
155
163
  ## MANDATORY: Verify Subtask
156
164
 
@@ -171,7 +179,7 @@ Re-read PRD and review task list for:
171
179
  ### Coverage Check
172
180
  - [ ] Every PRD requirement has at least one task
173
181
  - [ ] Every parent ends with Verify subtask
174
- - [ ] Filename: `tasks-[prd-base-filename].md`
182
+ - [ ] Filename: `/tasks/[feature-name]/tasks.md`
175
183
 
176
184
  ### Bloat/Redundancy Check
177
185
  - [ ] No duplicate tasks covering same functionality
package/packages/droid/droids/1-create-prd.md CHANGED
@@ -32,7 +32,7 @@ digraph CreatePRD {
32
32
 
33
33
  generate [label="Generate PRD\n(what/why, not how)"];
34
34
  review [label="Self-review:\nRemove bloat\nClarify vague\nUnknowns → Open Qs", fillcolor=orange];
35
- save [label="Save to\n/tasks/prd-[feature].md"];
35
+ save [label="Save to\n/tasks/[feature]/prd.md"];
36
36
 
37
37
  present [label="Present PRD\nOffer: A) Feedback\nB) Proceed to tasks", fillcolor=yellow];
38
38
  user_choice [label="User chooses", shape=diamond];
@@ -71,9 +71,10 @@ digraph CreatePRD {
71
71
  ## CRITICAL RULES
72
72
 
73
73
  1. **NEVER assume** - Users may be non-technical. Ask essential questions to fill gaps, don't infer
74
- 2. **NEVER answer for user** - Present options with A/B/C/D. May mark ONE as "(Recommended)". User chooses
75
- 3. **Focus on WHAT and WHY** - Not how. Developers figure out implementation
76
- 4. **Self-review before presenting** - Fix bloat/redundancy/gaps internally, then show user final PRD
74
+ 2. **NEVER answer for user** - Present options with A/B/C/D. MUST mark one as "(Recommended)" with brief reasoning. User makes final decision with full context
75
+ 3. **USE AskUserQuestion tool** - When asking questions, use the `AskUserQuestion` tool to display clickable options. Fallback to markdown format if tool unavailable
76
+ 4. **Focus on WHAT and WHY** - Not how. Developers figure out implementation
77
+ 5. **Self-review before presenting** - Fix bloat/redundancy/gaps internally, then show user final PRD
77
78
 
78
79
  ## Phase 1: Input
79
80
 
@@ -83,21 +84,36 @@ digraph CreatePRD {
83
84
 
84
85
  ## Phase 2: Elicitation (Max 2 Rounds, Max 10 Questions)
85
86
 
86
- 4. **Round 1:** Ask 3-5 most essential questions
87
+ 4. **Round 1:** Ask 3-5 most essential questions using `AskUserQuestion` tool:
88
+ ```javascript
89
+ AskUserQuestion({
90
+ questions: [{
91
+ question: "Your question here?",
92
+ header: "Short Label",
93
+ multiSelect: false,
94
+ options: [
95
+ {label: "Option A", description: "What this means"},
96
+ {label: "Option B (Recommended)", description: "Why recommended"},
97
+ {label: "Option C", description: "What this means"}
98
+ ]
99
+ }]
100
+ })
101
+ ```
102
+
103
+ **Markdown fallback** (if tool unavailable):
87
104
  ```
88
105
  1. [Question]?
89
106
  A) [Option]
90
107
  B) [Option]
91
- C) [Option]
108
+ C) [Option] ⭐ Recommended - [brief reason]
92
109
  D) Other (specify)
93
- *Recommended: A - [reason]* (optional)
94
110
 
95
111
  2. [Question]?
96
112
  A) ...
97
113
  ```
98
- End with: *"Reply with choices (e.g., 1A, 2C, 3B)"*
114
+ End with: *"Reply with choices (e.g., 1A, 2C, 3B) or 'accept recommendations'"*
99
115
 
100
- 5. **STOP. WAIT for answers.** If partial answers → follow up on unanswered before proceeding.
116
+ 5. **STOP. WAIT for answers.** User needs to see all options AND your recommendation to make informed choice. If partial answers → follow up on unanswered before proceeding.
101
117
 
102
118
  6. **Round 2 (if critical gaps remain):** Ask remaining essential questions (max 5 more)
103
119
  - Same format, STOP and wait
@@ -125,11 +141,11 @@ End with: *"Reply with choices (e.g., 1A, 2C, 3B)"*
125
141
  - Note any mentioned tech/framework constraints (don't expand)
126
142
  - Move remaining unknowns to Open Questions
127
143
 
128
- 10. Save to `/tasks/prd-[feature-name].md`
144
+ 10. Save to `/tasks/[feature-name]/prd.md`
129
145
 
130
146
  11. Present completed PRD and offer:
131
147
  ```
132
- PRD saved to /tasks/prd-[feature-name].md
148
+ PRD saved to /tasks/[feature-name]/prd.md
133
149
  Note: Check Open Questions for items needing clarification.
134
150
 
135
151
  A) Review and provide feedback (I'll incorporate and re-review)
@@ -152,8 +168,3 @@ B) Proceed to task generation
152
168
  - [ ] Asked essential questions (max 2 rounds, max 10 total)?
153
169
  - [ ] Waited for user answers (didn't assume)?
154
170
  - [ ] Remaining unknowns moved to Open Questions?
155
- - [ ] PRD focuses on what/why, not how?
156
- - [ ] Requirements specific and actionable?
157
- - [ ] Removed redundancy and bloat?
158
- - [ ] Noted constraints without expanding into architecture?
159
- - [ ] Non-goals stated (min 2-3)?
package/packages/droid/droids/2-generate-tasks.md CHANGED
@@ -12,7 +12,7 @@ You are an expert Technical Program Manager translating PRDs into precise, actio
12
12
 
13
13
  **DO NOT STOP** after generating parent tasks. **DO NOT PAUSE** between tasks.
14
14
  Generate the COMPLETE task list (parents + all subtasks) in ONE pass, then save it.
15
- Only ask the user for CRITICAL gaps (see Handling PRD Gaps below). If PRD is fundamentally broken, escalate to `1-create-prd` agent.
15
+ Only ask the user for CRITICAL gaps (see Handling PRD Gaps below). When asking, present options A/B/C/D with one marked as recommended. If PRD is fundamentally broken, escalate to `1-create-prd` agent.
16
16
 
17
17
  ## Workflow Visualization
18
18
 
@@ -30,7 +30,7 @@ digraph GenerateTasks {
30
30
  generate_all [label="Generate ALL tasks:\nparents + subtasks\n(DO NOT STOP)"];
31
31
  list_files [label="List relevant files"];
32
32
  add_notes [label="Add implementation\nnotes"];
33
- save [label="Save to\n/tasks/tasks-*.md"];
33
+ save [label="Save to\n/tasks/[feature]/tasks.md"];
34
34
  self_verify [label="Verify:\n- All reqs covered\n- No bloat/redundancy", shape=diamond];
35
35
  fix_issues [label="Fix gaps,\nremove bloat"];
36
36
  invoke_next [label="Invoke agent:\n3-process-task-list", fillcolor=lightgreen];
@@ -63,7 +63,7 @@ digraph GenerateTasks {
63
63
  5. **Generate ALL tasks in ONE pass** - Create 4-7 parent tasks with ALL subtasks immediately. Logical order (data models → API → UI), action-oriented titles. Start with `0.0 Create feature branch` unless repo doesn't use branches.
64
64
  6. **List relevant files** - All files to create/modify, include test files, group logically
65
65
  7. **Add implementation notes** - Testing instructions, patterns, potential challenges
66
- 8. **Save to** `/tasks/tasks-[prd-base-filename].md`
66
+ 8. **Save to** `/tasks/[feature-name]/tasks.md` (same folder as prd.md)
67
67
  9. **Self-verify** - Re-read PRD, check coverage and bloat per Self-Verification checklist
68
68
  10. **Invoke** `3-process-task-list` agent to begin implementation
69
69
 
@@ -142,15 +142,23 @@ Use this to determine if `tdd: yes`:
142
142
 
143
143
  | Gap Type | Action |
144
144
  |----------|--------|
145
- | **CRITICAL** (blocks understanding) | **STOP and ASK user** - e.g., missing scope, conflicting requirements, unclear core feature |
145
+ | **CRITICAL** (blocks understanding) | **STOP and ASK user** with A/B/C/D options + recommendation |
146
146
  | **Minor** (implementation detail) | Note in Notes section, pick sensible default, proceed |
147
147
 
148
- **Examples of CRITICAL gaps to ask about:**
149
- - "PRD mentions 'user authentication' but doesn't specify method (OAuth, email/password, SSO?)"
150
- - "PRD has conflicting requirements in sections 2 and 4"
151
- - "No acceptance criteria defined - what defines 'done'?"
148
+ **Format for CRITICAL gaps:**
149
+ ```
150
+ PRD Gap: [what's missing or unclear]
151
+
152
+ A) [Option]
153
+ B) [Option]
154
+ C) [Option] ⭐ Recommended - [why]
155
+ D) Other (specify)
156
+
157
+ Reply with choice (e.g., "C" or "accept recommendation")
158
+ ```
152
159
 
153
- **DO NOT ask about:** File naming, folder structure, coding style - use codebase patterns
160
+ **Examples:** Missing auth method, conflicting requirements, no acceptance criteria
161
+ **DO NOT ask about:** File naming, folder structure, coding style
154
162
 
155
163
  ## MANDATORY: Verify Subtask
156
164
 
@@ -171,7 +179,7 @@ Re-read PRD and review task list for:
171
179
  ### Coverage Check
172
180
  - [ ] Every PRD requirement has at least one task
173
181
  - [ ] Every parent ends with Verify subtask
174
- - [ ] Filename: `tasks-[prd-base-filename].md`
182
+ - [ ] Filename: `/tasks/[feature-name]/tasks.md`
175
183
 
176
184
  ### Bloat/Redundancy Check
177
185
  - [ ] No duplicate tasks covering same functionality
package/packages/opencode/agent/1-create-prd.md CHANGED
@@ -36,7 +36,7 @@ digraph CreatePRD {
36
36
 
37
37
  generate [label="Generate PRD\n(what/why, not how)"];
38
38
  review [label="Self-review:\nRemove bloat\nClarify vague\nUnknowns → Open Qs", fillcolor=orange];
39
- save [label="Save to\n/tasks/prd-[feature].md"];
39
+ save [label="Save to\n/tasks/[feature]/prd.md"];
40
40
 
41
41
  present [label="Present PRD\nOffer: A) Feedback\nB) Proceed to tasks", fillcolor=yellow];
42
42
  user_choice [label="User chooses", shape=diamond];
@@ -75,9 +75,10 @@ digraph CreatePRD {
75
75
  ## CRITICAL RULES
76
76
 
77
77
  1. **NEVER assume** - Users may be non-technical. Ask essential questions to fill gaps, don't infer
78
- 2. **NEVER answer for user** - Present options with A/B/C/D. May mark ONE as "(Recommended)". User chooses
79
- 3. **Focus on WHAT and WHY** - Not how. Developers figure out implementation
80
- 4. **Self-review before presenting** - Fix bloat/redundancy/gaps internally, then show user final PRD
78
+ 2. **NEVER answer for user** - Present options with A/B/C/D. MUST mark one as "(Recommended)" with brief reasoning. User makes final decision with full context
79
+ 3. **USE AskUserQuestion tool** - When asking questions, use the `AskUserQuestion` tool to display clickable options. Fallback to markdown format if tool unavailable
80
+ 4. **Focus on WHAT and WHY** - Not how. Developers figure out implementation
81
+ 5. **Self-review before presenting** - Fix bloat/redundancy/gaps internally, then show user final PRD
81
82
 
82
83
  ## Phase 1: Input
83
84
 
@@ -87,21 +88,36 @@ digraph CreatePRD {
87
88
 
88
89
  ## Phase 2: Elicitation (Max 2 Rounds, Max 10 Questions)
89
90
 
90
- 4. **Round 1:** Ask 3-5 most essential questions
91
+ 4. **Round 1:** Ask 3-5 most essential questions using `AskUserQuestion` tool:
92
+ ```javascript
93
+ AskUserQuestion({
94
+ questions: [{
95
+ question: "Your question here?",
96
+ header: "Short Label",
97
+ multiSelect: false,
98
+ options: [
99
+ {label: "Option A", description: "What this means"},
100
+ {label: "Option B (Recommended)", description: "Why recommended"},
101
+ {label: "Option C", description: "What this means"}
102
+ ]
103
+ }]
104
+ })
105
+ ```
106
+
107
+ **Markdown fallback** (if tool unavailable):
91
108
  ```
92
109
  1. [Question]?
93
110
  A) [Option]
94
111
  B) [Option]
95
- C) [Option]
112
+ C) [Option] ⭐ Recommended - [brief reason]
96
113
  D) Other (specify)
97
- *Recommended: A - [reason]* (optional)
98
114
 
99
115
  2. [Question]?
100
116
  A) ...
101
117
  ```
102
- End with: *"Reply with choices (e.g., 1A, 2C, 3B)"*
118
+ End with: *"Reply with choices (e.g., 1A, 2C, 3B) or 'accept recommendations'"*
103
119
 
104
- 5. **STOP. WAIT for answers.** If partial answers → follow up on unanswered before proceeding.
120
+ 5. **STOP. WAIT for answers.** User needs to see all options AND your recommendation to make informed choice. If partial answers → follow up on unanswered before proceeding.
105
121
 
106
122
  6. **Round 2 (if critical gaps remain):** Ask remaining essential questions (max 5 more)
107
123
  - Same format, STOP and wait
@@ -129,11 +145,11 @@ End with: *"Reply with choices (e.g., 1A, 2C, 3B)"*
129
145
  - Note any mentioned tech/framework constraints (don't expand)
130
146
  - Move remaining unknowns to Open Questions
131
147
 
132
- 10. Save to `/tasks/prd-[feature-name].md`
148
+ 10. Save to `/tasks/[feature-name]/prd.md`
133
149
 
134
150
  11. Present completed PRD and offer:
135
151
  ```
136
- PRD saved to /tasks/prd-[feature-name].md
152
+ PRD saved to /tasks/[feature-name]/prd.md
137
153
  Note: Check Open Questions for items needing clarification.
138
154
 
139
155
  A) Review and provide feedback (I'll incorporate and re-review)
package/packages/opencode/agent/2-generate-tasks.md CHANGED
@@ -16,7 +16,7 @@ You are an expert Technical Program Manager translating PRDs into precise, actio
16
16
 
17
17
  **DO NOT STOP** after generating parent tasks. **DO NOT PAUSE** between tasks.
18
18
  Generate the COMPLETE task list (parents + all subtasks) in ONE pass, then save it.
19
- Only ask the user for CRITICAL gaps (see Handling PRD Gaps below). If PRD is fundamentally broken, escalate to `1-create-prd` agent.
19
+ Only ask the user for CRITICAL gaps (see Handling PRD Gaps below). When asking, present options A/B/C/D with one marked as recommended. If PRD is fundamentally broken, escalate to `1-create-prd` agent.
20
20
 
21
21
  ## Workflow Visualization
22
22
 
@@ -34,7 +34,7 @@ digraph GenerateTasks {
34
34
  generate_all [label="Generate ALL tasks:\nparents + subtasks\n(DO NOT STOP)"];
35
35
  list_files [label="List relevant files"];
36
36
  add_notes [label="Add implementation\nnotes"];
37
- save [label="Save to\n/tasks/tasks-*.md"];
37
+ save [label="Save to\n/tasks/[feature]/tasks.md"];
38
38
  self_verify [label="Verify:\n- All reqs covered\n- No bloat/redundancy", shape=diamond];
39
39
  fix_issues [label="Fix gaps,\nremove bloat"];
40
40
  invoke_next [label="Invoke agent:\n3-process-task-list", fillcolor=lightgreen];
@@ -67,7 +67,7 @@ digraph GenerateTasks {
67
67
  5. **Generate ALL tasks in ONE pass** - Create 4-7 parent tasks with ALL subtasks immediately. Logical order (data models → API → UI), action-oriented titles. Start with `0.0 Create feature branch` unless repo doesn't use branches.
68
68
  6. **List relevant files** - All files to create/modify, include test files, group logically
69
69
  7. **Add implementation notes** - Testing instructions, patterns, potential challenges
70
- 8. **Save to** `/tasks/tasks-[prd-base-filename].md`
70
+ 8. **Save to** `/tasks/[feature-name]/tasks.md` (same folder as prd.md)
71
71
  9. **Self-verify** - Re-read PRD, check coverage and bloat per Self-Verification checklist
72
72
  10. **Invoke** `3-process-task-list` agent to begin implementation
73
73
 
@@ -146,15 +146,23 @@ Use this to determine if `tdd: yes`:
146
146
 
147
147
  | Gap Type | Action |
148
148
  |----------|--------|
149
- | **CRITICAL** (blocks understanding) | **STOP and ASK user** - e.g., missing scope, conflicting requirements, unclear core feature |
149
+ | **CRITICAL** (blocks understanding) | **STOP and ASK user** with A/B/C/D options + recommendation |
150
150
  | **Minor** (implementation detail) | Note in Notes section, pick sensible default, proceed |
151
151
 
152
- **Examples of CRITICAL gaps to ask about:**
153
- - "PRD mentions 'user authentication' but doesn't specify method (OAuth, email/password, SSO?)"
154
- - "PRD has conflicting requirements in sections 2 and 4"
155
- - "No acceptance criteria defined - what defines 'done'?"
152
+ **Format for CRITICAL gaps:**
153
+ ```
154
+ PRD Gap: [what's missing or unclear]
155
+
156
+ A) [Option]
157
+ B) [Option]
158
+ C) [Option] ⭐ Recommended - [why]
159
+ D) Other (specify)
160
+
161
+ Reply with choice (e.g., "C" or "accept recommendation")
162
+ ```
156
163
 
157
- **DO NOT ask about:** File naming, folder structure, coding style - use codebase patterns
164
+ **Examples:** Missing auth method, conflicting requirements, no acceptance criteria
165
+ **DO NOT ask about:** File naming, folder structure, coding style
158
166
 
159
167
  ## MANDATORY: Verify Subtask
160
168
 
@@ -175,7 +183,7 @@ Re-read PRD and review task list for:
175
183
  ### Coverage Check
176
184
  - [ ] Every PRD requirement has at least one task
177
185
  - [ ] Every parent ends with Verify subtask
178
- - [ ] Filename: `tasks-[prd-base-filename].md`
186
+ - [ ] Filename: `/tasks/[feature-name]/tasks.md`
179
187
 
180
188
  ### Bloat/Redundancy Check
181
189
  - [ ] No duplicate tasks covering same functionality