learnship 2.1.2 → 2.2.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 (49) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.cursor-plugin/plugin.json +1 -1
  3. package/README.md +172 -155
  4. package/SKILL.md +23 -2
  5. package/bin/install.js +316 -3
  6. package/commands/learnship/diagnose-issues.md +1 -0
  7. package/commands/learnship/discuss-phase.md +1 -0
  8. package/commands/learnship/ideate.md +3 -0
  9. package/commands/learnship/list-phase-assumptions.md +1 -0
  10. package/commands/learnship/new-project.md +2 -0
  11. package/commands/learnship/plan-phase.md +2 -0
  12. package/commands/learnship/quick.md +1 -0
  13. package/commands/learnship/research-phase.md +3 -0
  14. package/commands/learnship/secure-phase.md +1 -0
  15. package/commands/learnship/validate-phase.md +2 -0
  16. package/commands/learnship/verify-work.md +1 -0
  17. package/cursor-rules/learnship.mdc +14 -4
  18. package/gemini-extension.json +1 -1
  19. package/hooks/learnship-context-monitor.js +120 -0
  20. package/hooks/learnship-prompt-guard.js +75 -0
  21. package/hooks/learnship-session-state.js +136 -0
  22. package/hooks/learnship-statusline.js +179 -0
  23. package/learnship/agents/researcher.md +43 -2
  24. package/learnship/contexts/dev.md +21 -0
  25. package/learnship/contexts/research.md +22 -0
  26. package/learnship/contexts/review.md +22 -0
  27. package/learnship/templates/research-project/ARCHITECTURE.md +140 -0
  28. package/learnship/templates/research-project/FEATURES.md +130 -0
  29. package/learnship/templates/research-project/PITFALLS.md +102 -0
  30. package/learnship/templates/research-project/STACK.md +105 -0
  31. package/learnship/templates/research-project/SUMMARY.md +111 -0
  32. package/learnship/workflows/challenge.md +16 -4
  33. package/learnship/workflows/debug.md +30 -6
  34. package/learnship/workflows/diagnose-issues.md +14 -1
  35. package/learnship/workflows/discuss-milestone.md +15 -1
  36. package/learnship/workflows/discuss-phase.md +83 -10
  37. package/learnship/workflows/ideate.md +25 -5
  38. package/learnship/workflows/list-phase-assumptions.md +12 -5
  39. package/learnship/workflows/new-milestone.md +12 -6
  40. package/learnship/workflows/new-project.md +232 -75
  41. package/learnship/workflows/plan-phase.md +17 -3
  42. package/learnship/workflows/quick.md +18 -4
  43. package/learnship/workflows/research-phase.md +62 -9
  44. package/learnship/workflows/secure-phase.md +57 -15
  45. package/learnship/workflows/settings.md +142 -142
  46. package/learnship/workflows/validate-phase.md +39 -12
  47. package/learnship/workflows/verify-work.md +27 -0
  48. package/package.json +1 -1
  49. package/templates/config.json +1 -0
@@ -112,13 +112,25 @@ Task(
112
112
  <objective>
113
113
  Research how to implement Phase [phase_number]: [phase_name].
114
114
  Answer: 'What do I need to know to PLAN this phase well?'
115
- Write RESEARCH.md to [phase_dir]/[padded_phase]-RESEARCH.md.
115
+
116
+ IMPORTANT: You MUST do online research BEFORE writing the research file. Your training data is stale — verify everything.
117
+
118
+ Phase 1 — INVESTIGATE (do this first):
119
+ 1. Read user decisions from CONTEXT.md (if exists), requirements from REQUIREMENTS.md, and project state from STATE.md
120
+ 2. Read the researcher persona at @./agents/researcher.md for research principles and tool strategy
121
+ 3. Run at least 3 WebSearch queries to discover: standard approaches, recommended libraries, and common pitfalls for this phase's domain. Include the current year in queries.
122
+ 4. Use WebFetch to read official documentation for any key libraries or frameworks discovered
123
+ 5. Scan the codebase for existing patterns relevant to this phase
124
+
125
+ Phase 2 — WRITE FILE (only after investigating):
126
+ Write RESEARCH.md to [phase_dir]/[padded_phase]-RESEARCH.md with Don't Hand-Roll, Common Pitfalls, Existing Patterns, and Recommended Approach sections. Include confidence levels (HIGH/MEDIUM/LOW) and cite sources.
116
127
  </objective>
117
128
 
118
129
  <files_to_read>
119
130
  - [context_path] (user decisions, if exists)
120
131
  - .planning/REQUIREMENTS.md
121
132
  - .planning/STATE.md
133
+ - @./agents/researcher.md (persona — read for research principles and tool strategy)
122
134
  </files_to_read>
123
135
  "
124
136
  )
@@ -128,13 +140,15 @@ Wait for agent to complete, then verify RESEARCH.md was written.
128
140
 
129
141
  **If `parallelization` is `false` (sequential mode):**
130
142
 
131
- Using `@./agents/researcher.md` as your research persona, investigate how to implement this phase. Read:
143
+ Using `@./agents/researcher.md` as your research persona, investigate how to implement this phase.
144
+
145
+ **Online research first.** Before writing anything, run at least 3 WebSearch queries relevant to this phase's domain. Use WebFetch to read official docs for any libraries discovered. Then read:
132
146
  - The CONTEXT.md (user decisions)
133
147
  - `.planning/REQUIREMENTS.md` (which requirements this phase covers)
134
148
  - `.planning/STATE.md` (project history and decisions)
135
149
  - Existing codebase for relevant patterns
136
150
 
137
- Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-RESEARCH.md` with two key sections:
151
+ Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-RESEARCH.md` based on your web research findings. Include confidence levels and cite sources. The file must have two key sections:
138
152
  - **Don't Hand-Roll** — problems with good existing solutions ("Don't build your own JWT — use jose")
139
153
  - **Common Pitfalls** — what goes wrong, why, how to avoid it
140
154
 
@@ -73,13 +73,27 @@ Report: "Creating quick task ${NEXT_NUM}: ${DESCRIPTION}"
73
73
 
74
74
  Analyze `DESCRIPTION` to identify 2-4 gray areas — implementation decisions that would change the outcome.
75
75
 
76
- Present them for selection (multi-select):
77
- - Each area is a concrete decision point (not generic)
78
- - Include an "All clear — skip discussion" option
76
+ Present them for selection using a structured multi-select question:
77
+
78
+ ```
79
+ AskUserQuestion([
80
+ {
81
+ header: "Gray Areas",
82
+ question: "Which areas need clarification? (select all that apply)",
83
+ multiSelect: true,
84
+ options: [
85
+ { label: "[Area 1]", description: "[Concrete decision point]" },
86
+ { label: "[Area 2]", description: "[Concrete decision point]" },
87
+ { label: "[Area 3]", description: "[Concrete decision point]" },
88
+ { label: "All clear — skip discussion", description: "No gray areas need clarification" }
89
+ ]
90
+ }
91
+ ])
92
+ ```
79
93
 
80
94
  If "All clear" → skip to Step 4.
81
95
 
82
- For each selected area, ask 1-2 focused questions with concrete options. Max 2 questions per area — keep it lightweight.
96
+ For each selected area, ask 1-2 focused questions with concrete options using structured questions. Max 2 questions per area — keep it lightweight.
83
97
 
84
98
  Write `CONTEXT.md` to the task directory:
85
99
 
@@ -30,16 +30,21 @@ ls ".planning/phases/"*"/"*"-RESEARCH.md" 2>/dev/null | grep "^[N]-\|/[N][^0-9]"
30
30
  ```
31
31
 
32
32
  If RESEARCH.md already exists for this phase:
33
- ```
34
- Research already exists: .planning/phases/[phase-dir]/[N]-RESEARCH.md
35
33
 
36
- Options:
37
- 1. View existing research
38
- 2. Re-run and overwrite
39
- 3. Skip — use existing
40
34
  ```
41
-
42
- Wait for choice.
35
+ AskUserQuestion([
36
+ {
37
+ header: "Existing Research",
38
+ question: "Research already exists for this phase. What do you want to do?",
39
+ multiSelect: false,
40
+ options: [
41
+ { label: "View existing", description: "Show current research, then decide" },
42
+ { label: "Re-run and overwrite", description: "Discard existing research and re-run" },
43
+ { label: "Skip", description: "Use existing research as-is" }
44
+ ]
45
+ }
46
+ ])
47
+ ```
43
48
 
44
49
  ## Step 3: Load Context
45
50
 
@@ -65,9 +70,57 @@ If CONTEXT.md exists, read it — user decisions shape what to research.
65
70
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
66
71
  ```
67
72
 
73
+ Read `parallelization` from `.planning/config.json` (defaults to `false`).
74
+
75
+ **If `parallelization.enabled` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
76
+
77
+ Spawn a dedicated researcher agent:
78
+ ```
79
+ Task(
80
+ subagent_type="learnship-researcher",
81
+ prompt="
82
+ <objective>
83
+ Research how to implement phase [N] for this project.
84
+
85
+ IMPORTANT: You MUST do online research BEFORE writing the research file. Your training data is stale — verify everything.
86
+
87
+ Phase 1 — INVESTIGATE (do this first):
88
+ 1. Read the phase goal from ROADMAP.md, requirements from REQUIREMENTS.md, and any CONTEXT.md decisions
89
+ 2. Read the researcher persona at @./agents/researcher.md for research principles and tool strategy
90
+ 3. Run at least 3 WebSearch queries to discover: standard approaches, recommended libraries, and common pitfalls for this phase's domain. Include the current year in queries.
91
+ 4. Use WebFetch to read official documentation for any key libraries or frameworks discovered
92
+ 5. Scan the codebase for existing patterns relevant to this phase
93
+
94
+ Phase 2 — WRITE FILE (only after investigating):
95
+ Write [padded_phase]-RESEARCH.md with Don't Hand-Roll, Common Pitfalls, Existing Patterns, and Recommended Approach sections. Include confidence levels (HIGH/MEDIUM/LOW) and cite sources.
96
+ </objective>
97
+
98
+ <files_to_read>
99
+ - .planning/ROADMAP.md
100
+ - .planning/REQUIREMENTS.md
101
+ - .planning/STATE.md
102
+ - .planning/phases/[padded_phase]-[slug]/[padded_phase]-CONTEXT.md (if exists)
103
+ - @./agents/researcher.md (persona — read for research principles and tool strategy)
104
+ </files_to_read>
105
+ "
106
+ )
107
+ ```
108
+
109
+ **If `parallelization.enabled` is `false` (sequential mode):**
110
+
68
111
  Using `@./agents/researcher.md` as your research persona in **phase research mode**:
69
112
 
70
- Read all loaded context, then investigate how to implement this phase. Write `.planning/phases/[padded_phase]-[slug]/[padded_phase]-RESEARCH.md` with two sections:
113
+ **Online research first.** Before writing anything, run at least 3 WebSearch queries relevant to this phase's domain:
114
+
115
+ 1. `"[phase technology] best practices 2026"` — current recommendations
116
+ 2. `"[phase technology] common mistakes gotchas"` — what goes wrong
117
+ 3. `"[phase technology] recommended libraries"` — standard tools
118
+
119
+ Use WebFetch to read official docs for any libraries or frameworks discovered. Record findings internally.
120
+
121
+ > 🛑 STOP. Confirm: did you run at least 3 WebSearch queries? If you skipped straight to writing the research file, go back and search now.
122
+
123
+ Then write `.planning/phases/[padded_phase]-[slug]/[padded_phase]-RESEARCH.md` based on your web research findings. Include confidence levels and cite sources. The file must have these sections:
71
124
 
72
125
  **Don't Hand-Roll** — problems that have battle-tested solutions:
73
126
  ```
@@ -75,30 +75,72 @@ Classify each threat:
75
75
 
76
76
  If all threats are CLOSED: skip to Step 6.
77
77
 
78
- If open threats exist, present them:
78
+ If open threats exist, present them with a structured question:
79
79
 
80
+ Display the threat table first, then:
81
+
82
+ ```
83
+ AskUserQuestion([
84
+ {
85
+ header: "Open Threats",
86
+ question: "[N] open threat(s) found. How do you want to handle them?",
87
+ multiSelect: false,
88
+ options: [
89
+ { label: "Verify all", description: "Investigate and resolve each open threat against the codebase" },
90
+ { label: "Accept all", description: "Document all as accepted risks with rationale" },
91
+ { label: "Review individually", description: "Decide per threat: verify, accept, or skip" }
92
+ ]
93
+ }
94
+ ])
80
95
  ```
81
- Open Threats ([N]):
82
96
 
83
- | ID | Category | Component | Description |
84
- |----|----------|-----------|-------------|
85
- | T-03-01 | Info Disclosure | api/auth.ts | JWT secret in environment without validation |
97
+ ## Step 5: Resolve Open Threats
86
98
 
87
- Options:
88
- 1. Verify all open threats — investigate and resolve
89
- 2. Accept all open — document as accepted risks
90
- 3. Review individually — decide per threat
91
- ```
99
+ Read `parallelization` from `.planning/config.json` (defaults to `false`).
92
100
 
93
- Wait for user response.
101
+ **For "Verify all":**
94
102
 
95
- ## Step 5: Resolve Open Threats
103
+ **If `parallelization.enabled` is `true`:**
104
+ ```
105
+ Task(
106
+ subagent_type="learnship-security-auditor",
107
+ prompt="
108
+ <objective>
109
+ Verify all open threats in the threat register for phase [N].
110
+ Check each threat against the actual codebase. Update status to
111
+ CLOSED if mitigation found, or document what's missing.
112
+ Follow the security auditor persona at @./agents/security-auditor.md.
113
+ </objective>
114
+
115
+ <files_to_read>
116
+ - [phase SECURITY.md or threat register]
117
+ - @./agents/security-auditor.md (persona)
118
+ </files_to_read>
119
+ "
120
+ )
121
+ ```
122
+
123
+ **If `parallelization.enabled` is `false`:**
124
+ Using `@./agents/security-auditor.md`, check each open threat against the codebase. Update status based on findings.
96
125
 
97
- For option 1 (verify all): Using `@./agents/verifier.md`, check each open threat against the codebase. Update status based on findings.
126
+ **For "Accept all":** Add each to the Accepted Risks Log with user's rationale.
98
127
 
99
- For option 2 (accept all): Add each to the Accepted Risks Log with user's rationale.
128
+ **For "Review individually":** Present each threat one at a time:
100
129
 
101
- For option 3 (individual): Present each threat one at a time with options: Verify / Accept / Skip.
130
+ ```
131
+ AskUserQuestion([
132
+ {
133
+ header: "Threat [ID]",
134
+ question: "[Category]: [Description] in [Component]",
135
+ multiSelect: false,
136
+ options: [
137
+ { label: "Verify", description: "Investigate this threat against the codebase" },
138
+ { label: "Accept", description: "Document as accepted risk" },
139
+ { label: "Skip", description: "Leave open for now" }
140
+ ]
141
+ }
142
+ ])
143
+ ```
102
144
 
103
145
  ## Step 6: Write SECURITY.md
104
146
 
@@ -87,166 +87,166 @@ cat .planning/config.json
87
87
 
88
88
  Parse current values to use as defaults in the prompts.
89
89
 
90
- ## Step 3: Present Settings Menu
90
+ ## Step 3: Present Settings
91
91
 
92
- Display current settings and ask what to change:
92
+ Display the settings banner, then present settings using structured question rounds. Use your platform's interactive question tool, or numbered text lists if unavailable. Pre-select current values where the tool supports it.
93
93
 
94
94
  ```
95
95
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
96
96
  learnship ► SETTINGS
97
97
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
98
-
99
- Current configuration:
100
-
101
- [1] Mode: [current] (yolo | interactive)
102
- [2] Granularity: [current] (coarse | standard | fine)
103
- [3] Model profile: [current] (quality | balanced | budget)
104
- [4] Learning mode: [current] (auto | manual)
105
- [5] Test-first (TDD): [on/off]
106
- [6] Research agent: [on/off]
107
- [7] Plan check agent: [on/off]
108
- [8] Verifier agent: [on/off]
109
- [9] Test validation: [on/off]
110
- [10] Review workflow: [on/off]
111
- [11] Solutions search: [on/off]
112
- [12] Security enforcement: [on/off]
113
- [13] Auto-review after verify: [on/off]
114
- [14] Ship: auto-test: [on/off]
115
- [15] Ship: conventional commits: [on/off]
116
- [16] Ship: PR template: [on/off]
117
- [17] Parallelization: [on/off] (max agents: [N])
118
- [18] Git branching: [current] (none | phase | milestone)
119
- [19] Commit docs: [on/off]
120
- [20] Safety: confirm destructive: [on/off]
121
- [21] Context warnings: [on/off]
122
-
123
- Enter a number to change a setting, or 'done' to save.
124
- ```
125
-
126
- Wait for selection. Repeat until user types "done".
127
-
128
- ## Step 4: Change Selected Setting
129
-
130
- For each selected setting, explain the options and ask for the new value:
131
-
132
- **[1] Mode:**
133
- ```
134
- Mode controls how much Cascade auto-approves vs. asks you:
135
- - yolo: auto-approves decisions, fastest flow
136
- - interactive: confirms at each step, more control
137
-
138
- Current: [current]. New value?
139
- ```
140
-
141
- **[2] Granularity:**
142
- ```
143
- Granularity controls phase size:
144
- - coarse: 3-5 phases (broad strokes)
145
- - standard: 5-8 phases (default)
146
- - fine: 8-12 phases (more granular, better for complex projects)
147
-
148
- Current: [current]. New value?
149
- ```
150
-
151
- **[3] Model profile:**
152
- ```
153
- Model profile controls which model tier each agent uses:
154
- - quality: large-tier for all decision-making agents (highest cost, best results)
155
- - balanced: large for planning, medium for execution (default — good balance)
156
- - budget: medium for writing code, small for research/verification (lowest cost)
157
-
158
- Current: [current]. New value?
159
- ```
160
-
161
- **[4] Learning mode:**
162
- ```
163
- Learning mode controls when learning actions are offered:
164
- - auto: offered automatically at workflow checkpoints (default)
165
- - manual: only when you explicitly invoke @agentic-learning
166
-
167
- Current: [current]. New value?
168
- ```
169
-
170
- **[5] Test-first (TDD):**
171
- ```
172
- Test-first mode enforces red-green-refactor during execute-phase:
173
- - on: write failing test → verify red → implement → verify green
174
- - off: write tests alongside implementation (default)
175
-
176
- Current: [current]. New value? (on/off)
177
- ```
178
-
179
- **[6-8] Agent toggles (research / plan_check / verifier):**
180
- ```
181
- [Research / Plan check / Verifier] agent:
182
- - on: agent runs (recommended for production work)
183
- - off: skip this agent (faster, for familiar domains or prototyping)
184
-
185
- Current: [current]. New value? (on/off)
186
98
  ```
187
99
 
188
- **[9] Test validation:**
189
- ```
190
- Test validation maps automated test coverage to requirements during plan-phase.
191
- - on: plans include automated verify commands per task (recommended)
192
- - off: skip validation research (good for rapid prototyping)
193
-
194
- Current: [current]. New value? (on/off)
195
- ```
196
-
197
- **[10] Review workflow:**
198
- ```
199
- Multi-persona code review after verification:
200
- - on: /review is available and can be auto-triggered (recommended)
201
- - off: skip review workflow
202
-
203
- Current: [current]. New value? (on/off)
204
- ```
100
+ **Round 1 — Core settings (4 questions):**
205
101
 
206
- **[11] Solutions search:**
207
102
  ```
208
- Search .planning/solutions/ for prior art during plan-phase:
209
- - on: reuse patterns from solved problems (recommended)
210
- - off: skip solutions search
211
-
212
- Current: [current]. New value? (on/off)
213
- ```
214
-
215
- **[12] Auto-review after verify:**
216
- ```
217
- Automatically trigger /review after verify-work passes:
218
- - on: review starts immediately after successful verification
219
- - off: run /review manually when ready (default)
220
-
221
- Current: [current]. New value? (on/off)
103
+ AskUserQuestion([
104
+ {
105
+ header: "Model Profile",
106
+ question: "Which model quality tier for agents?",
107
+ multiSelect: false,
108
+ options: [
109
+ { label: "Balanced (Recommended)", description: "Large for planning, medium for execution" },
110
+ { label: "Quality", description: "Large-tier for all agents (highest cost)" },
111
+ { label: "Budget", description: "Medium for code, small for research (lowest cost)" },
112
+ { label: "Inherit", description: "Use current session model for all agents" }
113
+ ]
114
+ },
115
+ {
116
+ header: "Mode",
117
+ question: "Working style?",
118
+ multiSelect: false,
119
+ options: [
120
+ { label: "YOLO", description: "Auto-approve steps, just execute" },
121
+ { label: "Interactive", description: "Confirm at each step, more control" }
122
+ ]
123
+ },
124
+ {
125
+ header: "Granularity",
126
+ question: "Phase size?",
127
+ multiSelect: false,
128
+ options: [
129
+ { label: "Coarse", description: "3-5 phases, broad strokes" },
130
+ { label: "Standard", description: "5-8 phases, balanced (default)" },
131
+ { label: "Fine", description: "8-12 phases, granular for complex projects" }
132
+ ]
133
+ },
134
+ {
135
+ header: "Learning",
136
+ question: "When should learning partner activate?",
137
+ multiSelect: false,
138
+ options: [
139
+ { label: "Auto", description: "Offer at natural checkpoints (default)" },
140
+ { label: "Manual", description: "Only when you invoke @agentic-learning" }
141
+ ]
142
+ }
143
+ ])
222
144
  ```
223
145
 
224
- **[13-15] Ship pipeline (auto_test / conventional_commits / pr_template):**
225
- ```
226
- [Auto-test / Conventional commits / PR template]:
227
- - on: enabled (recommended)
228
- - off: disabled
146
+ **Round 2 Workflow agents (6 questions):**
229
147
 
230
- Current: [current]. New value? (on/off)
231
148
  ```
232
-
233
- **[16] Git branching:**
149
+ AskUserQuestion([
150
+ {
151
+ header: "Research",
152
+ question: "Spawn researcher agent before planning?",
153
+ multiSelect: false,
154
+ options: [
155
+ { label: "Yes (Recommended)", description: "Research domain before planning each phase" },
156
+ { label: "No", description: "Skip research, plan directly" }
157
+ ]
158
+ },
159
+ {
160
+ header: "Plan Check",
161
+ question: "Verify plans before execution?",
162
+ multiSelect: false,
163
+ options: [
164
+ { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
165
+ { label: "No", description: "Execute without plan verification" }
166
+ ]
167
+ },
168
+ {
169
+ header: "Verifier",
170
+ question: "Verify phase completion?",
171
+ multiSelect: false,
172
+ options: [
173
+ { label: "Yes (Recommended)", description: "Confirm deliverables after execution" },
174
+ { label: "No", description: "Skip post-execution verification" }
175
+ ]
176
+ },
177
+ {
178
+ header: "Review",
179
+ question: "Multi-persona code review?",
180
+ multiSelect: false,
181
+ options: [
182
+ { label: "Yes (Recommended)", description: "Correctness, security, performance review" },
183
+ { label: "No", description: "Skip review" }
184
+ ]
185
+ },
186
+ {
187
+ header: "Solutions",
188
+ question: "Search prior solutions during planning?",
189
+ multiSelect: false,
190
+ options: [
191
+ { label: "Yes (Recommended)", description: "Check .planning/solutions/ for reusable patterns" },
192
+ { label: "No", description: "Plan without searching prior solutions" }
193
+ ]
194
+ },
195
+ {
196
+ header: "TDD",
197
+ question: "Test-first mode?",
198
+ multiSelect: false,
199
+ options: [
200
+ { label: "No (Recommended)", description: "Write tests alongside implementation" },
201
+ { label: "Yes", description: "Red-green-refactor: failing test first, then implement" }
202
+ ]
203
+ }
204
+ ])
234
205
  ```
235
- Branching strategy:
236
- - none: no automatic branches (good for solo work)
237
- - phase: create a branch at each execute-phase (good for code review per phase)
238
- - milestone: one branch for all phases in a milestone (good for release branches)
239
206
 
240
- Current: [current]. New value?
241
- ```
207
+ **Round 3 Pipeline & git (4 questions):**
242
208
 
243
- **[17] Commit docs:**
244
209
  ```
245
- Whether .planning/ files are committed to git:
246
- - on: planning artifacts tracked in git (default)
247
- - off: keep .planning/ local only (add to .gitignore for privacy)
248
-
249
- Current: [current]. New value? (on/off)
210
+ AskUserQuestion([
211
+ {
212
+ header: "Ship Pipeline",
213
+ question: "Ship pipeline preferences?",
214
+ multiSelect: true,
215
+ options: [
216
+ { label: "Auto-test before shipping (Recommended)", description: "Run tests before every ship" },
217
+ { label: "Conventional commits (Recommended)", description: "Use feat:, fix:, docs: prefixes" },
218
+ { label: "Auto-generate PR description (Recommended)", description: "Create PR body from commits" }
219
+ ]
220
+ },
221
+ {
222
+ header: "Git Tracking",
223
+ question: "Commit planning docs to git?",
224
+ multiSelect: false,
225
+ options: [
226
+ { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
227
+ { label: "No", description: "Keep .planning/ local-only" }
228
+ ]
229
+ },
230
+ {
231
+ header: "Branching",
232
+ question: "Git branching strategy?",
233
+ multiSelect: false,
234
+ options: [
235
+ { label: "None (Recommended)", description: "Commit directly to current branch" },
236
+ { label: "Per Phase", description: "Create branch for each phase" },
237
+ { label: "Per Milestone", description: "One branch for entire milestone" }
238
+ ]
239
+ },
240
+ {
241
+ header: "Context Warnings",
242
+ question: "Context window warnings?",
243
+ multiSelect: false,
244
+ options: [
245
+ { label: "Yes (Recommended)", description: "Warn when context usage is high" },
246
+ { label: "No", description: "Disable warnings, allow natural auto-compact" }
247
+ ]
248
+ }
249
+ ])
250
250
  ```
251
251
 
252
252
  ## Step 5: Save Config
@@ -80,24 +80,51 @@ If no gaps (all COVERED): proceed directly to step 8 with `compliant: true`.
80
80
 
81
81
  ## Step 7: Present Gap Plan and Fill
82
82
 
83
- Show gap table:
83
+ Show the gap table, then present a structured question:
84
+
85
+ ```
86
+ AskUserQuestion([
87
+ {
88
+ header: "Validation Gaps",
89
+ question: "[N] gap(s) found. How do you want to handle them?",
90
+ multiSelect: false,
91
+ options: [
92
+ { label: "Fill all gaps", description: "I'll write the missing tests automatically" },
93
+ { label: "Manual-only", description: "Skip automation, verify these manually" },
94
+ { label: "Cancel", description: "Stop validation — no changes" }
95
+ ]
96
+ }
97
+ ])
84
98
  ```
85
- Phase [N] Validation Gaps
86
99
 
87
- | Requirement | Status | Suggested test |
88
- |-------------|--------|----------------|
89
- | REQ-AUTH-01 | MISSING | src/__tests__/auth.test.ts |
90
- | REQ-DASH-02 | PARTIAL | src/__tests__/dashboard.test.ts |
100
+ **If "Fill all gaps":**
91
101
 
92
- Options:
93
- 1. Fill all gaps — I'll write the missing tests
94
- 2. Mark as manual-only — skip automation, verify manually
95
- 3. Cancel
102
+ Read `parallelization` from `.planning/config.json` (defaults to `false`).
103
+
104
+ **If `parallelization.enabled` is `true` (subagent mode):**
105
+ ```
106
+ Task(
107
+ subagent_type="learnship-verifier",
108
+ prompt="
109
+ <objective>
110
+ Write missing test files for phase [N] validation gaps.
111
+ Read VALIDATION.md gaps and write tests that cover each MISSING or PARTIAL requirement.
112
+ Follow the verifier persona at @./agents/verifier.md.
113
+ Never modify implementation files — only write test files.
114
+ Run tests to verify they pass. Up to 3 debug attempts if tests fail.
115
+ </objective>
116
+
117
+ <files_to_read>
118
+ - [VALIDATION.md path]
119
+ - @./agents/verifier.md (persona)
120
+ </files_to_read>
121
+ "
122
+ )
96
123
  ```
97
124
 
98
- Wait for choice.
125
+ **If `parallelization.enabled` is `false` (sequential mode):**
99
126
 
100
- **If "Fill all gaps":** Write the missing test files. Rules:
127
+ Write the missing test files. Rules:
101
128
  - Never touch implementation files
102
129
  - Match the existing test framework and style
103
130
  - Write tests that actually run (import real modules, not mocks of the implementation)
@@ -245,6 +245,33 @@ All tests passed. ✓
245
245
  [N] issues found. Diagnosing root causes...
246
246
  ```
247
247
 
248
+ Read `parallelization` from `.planning/config.json` (defaults to `false`).
249
+
250
+ **If `parallelization.enabled` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
251
+
252
+ Spawn a dedicated debugger agent for diagnosis:
253
+ ```
254
+ Task(
255
+ subagent_type="learnship-debugger",
256
+ prompt="
257
+ <objective>
258
+ Diagnose all issues found in UAT for phase [N].
259
+ Read the UAT.md file with gaps, trace each issue to its root cause.
260
+ Do NOT fix anything — just diagnose and document root causes.
261
+ Follow the debugger persona at @./agents/debugger.md.
262
+ Write root_cause and affected_files for each gap back to UAT.md.
263
+ </objective>
264
+
265
+ <files_to_read>
266
+ - [UAT.md path]
267
+ - @./agents/debugger.md (persona)
268
+ </files_to_read>
269
+ "
270
+ )
271
+ ```
272
+
273
+ **If `parallelization.enabled` is `false` (sequential mode):**
274
+
248
275
  For each issue in the Gaps section, investigate using `@./agents/debugger.md` as your debug persona:
249
276
  - Read the relevant source files
250
277
  - Trace the issue to its root cause
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "learnship",
3
- "version": "2.1.2",
3
+ "version": "2.2.1",
4
4
  "description": "Learn as you build. Build with intent. — A multi-platform agentic engineering system for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex: spec-driven workflows, integrated learning, and production-grade design.",
5
5
  "keywords": [
6
6
  "agentic",
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "mode": "interactive",
3
3
  "granularity": "standard",
4
+ "context": "dev",
4
5
  "model_profile": "balanced",
5
6
  "learning_mode": "auto",
6
7
  "test_first": false,