@ngxtm/devkit 3.12.0 → 3.14.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.
- package/SKILLS_INDEX.md +1 -1
- package/merged-commands/learn.md +150 -24
- package/package.json +1 -1
- package/rules-index.json +1 -1
- package/skills/learn/SKILL.md +150 -24
- package/skills-index.json +1 -1
package/SKILLS_INDEX.md
CHANGED
|
@@ -1036,7 +1036,7 @@ Identifies high-quality leads for your product or service by analyzing your busi
|
|
|
1036
1036
|
### learn
|
|
1037
1037
|
`skills/learn`
|
|
1038
1038
|
|
|
1039
|
-
|
|
1039
|
+
Guided project building — you code, AI mentors. Build your own product step-by-step with best practices and deep understanding.
|
|
1040
1040
|
|
|
1041
1041
|
### legacy-modernizer
|
|
1042
1042
|
`skills/legacy-modernizer`
|
package/merged-commands/learn.md
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: learn
|
|
3
|
-
description:
|
|
3
|
+
description: Guided project building — you code, AI mentors. Build your own product step-by-step with best practices and deep understanding.
|
|
4
4
|
argument-hint: [topic]
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
# Learn Mode
|
|
7
|
+
# Learn Mode v3.1
|
|
8
8
|
|
|
9
|
-
>
|
|
9
|
+
> Build your product. Design the architecture. Write every line. Understand every decision.
|
|
10
10
|
|
|
11
11
|
## Activation
|
|
12
12
|
|
|
13
|
-
`/learn "topic"` — e.g., `/learn "JWT auth in Express"`, `/learn "
|
|
13
|
+
`/learn "topic"` — e.g., `/learn "JWT auth in Express"`, `/learn "build real-time chat"`
|
|
14
14
|
|
|
15
15
|
---
|
|
16
16
|
|
|
@@ -44,13 +44,23 @@ If multiple detected → ask user. If none → ask user.
|
|
|
44
44
|
|
|
45
45
|
3. **Codebase scan**: Read key project files (entry points, configs, existing code related to topic) for context. Use project's conventions in all examples.
|
|
46
46
|
|
|
47
|
-
4. **
|
|
47
|
+
4. **Difficulty from codingLevel** (read from `.claude/.ck.json`):
|
|
48
48
|
- Level 0-1 → **Deep**: full concepts, analogies, Socratic questions at every step
|
|
49
49
|
- Level 2-3 → **Standard**: concepts + code, balanced explanations
|
|
50
50
|
- Level 4-5 → **Quick**: minimal explanation, jump straight to code
|
|
51
51
|
- Not set → ask user with `AskUserQuestion`
|
|
52
52
|
|
|
53
|
-
5. **
|
|
53
|
+
5. **Teaching mode** — ask user via `AskUserQuestion`:
|
|
54
|
+
|
|
55
|
+
| Mode | Who codes? | AI does what? | Best for |
|
|
56
|
+
|------|-----------|---------------|----------|
|
|
57
|
+
| **Guided** | User writes all code | Describe task + review after | Deep understanding, own the code |
|
|
58
|
+
| **Scaffolded** | User fills in key parts | Provide skeleton + hints | Learning new patterns |
|
|
59
|
+
| **Demonstrated** | AI writes, user reads | Write code + explain | Quick overview, reading comprehension |
|
|
60
|
+
|
|
61
|
+
Default suggestion based on difficulty: Deep → Guided, Standard → Scaffolded, Quick → Demonstrated.
|
|
62
|
+
|
|
63
|
+
6. **Create output file**: `learn/{YYYY-MM-DD}-{topic-slug}.md` with YAML frontmatter:
|
|
54
64
|
```yaml
|
|
55
65
|
---
|
|
56
66
|
topic: "{topic}"
|
|
@@ -58,7 +68,8 @@ language: {detected}
|
|
|
58
68
|
phase: INIT
|
|
59
69
|
step: 0
|
|
60
70
|
total_steps: 0
|
|
61
|
-
|
|
71
|
+
difficulty: {deep|standard|quick}
|
|
72
|
+
teaching: {guided|scaffolded|demonstrated}
|
|
62
73
|
started: {ISO timestamp}
|
|
63
74
|
updated: {ISO timestamp}
|
|
64
75
|
---
|
|
@@ -66,7 +77,7 @@ updated: {ISO timestamp}
|
|
|
66
77
|
|
|
67
78
|
---
|
|
68
79
|
|
|
69
|
-
## Phase 2: LEARN (skip entirely in Quick
|
|
80
|
+
## Phase 2: LEARN (skip entirely in Quick difficulty)
|
|
70
81
|
|
|
71
82
|
1. **WebSearch** official docs: `WebSearch("{topic} {language} official documentation")`, then `WebFetch` the most relevant result. Cite sources in tutorial.
|
|
72
83
|
|
|
@@ -82,34 +93,143 @@ Update frontmatter: `phase: LEARN`
|
|
|
82
93
|
|
|
83
94
|
---
|
|
84
95
|
|
|
85
|
-
## Phase 3:
|
|
96
|
+
## Phase 3: DESIGN (Socratic architecture thinking)
|
|
97
|
+
|
|
98
|
+
> User thinks first, AI guides — not the other way around.
|
|
99
|
+
|
|
100
|
+
1. **Frame the problem**: AI presents the high-level problem to solve:
|
|
101
|
+
> "We need to build {topic}. Before I suggest anything — how would YOU approach this? What components or pieces do you think we need?"
|
|
102
|
+
|
|
103
|
+
Ask via `AskUserQuestion`. Let user think and answer.
|
|
104
|
+
|
|
105
|
+
2. **Build on user's answer**:
|
|
106
|
+
- If user's approach is solid → acknowledge strengths, refine together
|
|
107
|
+
- If user's approach has gaps → ask guiding questions: "What about {concern}? How would you handle that?"
|
|
108
|
+
- If user has no idea → break it down: "Let's start smaller — what's the first thing a user would do with this feature?"
|
|
109
|
+
|
|
110
|
+
3. **Explore alternatives**: Present 2-3 different approaches with trade-offs:
|
|
111
|
+
> "Your approach uses X. Another option is Y. Here's how they compare:"
|
|
112
|
+
|
|
113
|
+
| Aspect | Approach A (user's) | Approach B | Approach C |
|
|
114
|
+
|--------|-------------------|-----------|-----------|
|
|
115
|
+
| Complexity | ... | ... | ... |
|
|
116
|
+
| Scalability | ... | ... | ... |
|
|
117
|
+
| Learning value | ... | ... | ... |
|
|
118
|
+
|
|
119
|
+
Ask user to choose via `AskUserQuestion`. Explain WHY each trade-off matters.
|
|
120
|
+
|
|
121
|
+
4. **Architecture decisions**: For the chosen approach, walk through key decisions:
|
|
122
|
+
- Data flow: how data moves through the system
|
|
123
|
+
- File/module structure: where code lives and why
|
|
124
|
+
- Dependencies: what libraries/tools and why those specifically
|
|
125
|
+
- Patterns: which design patterns and why (not just "use MVC" but why MVC fits here)
|
|
126
|
+
|
|
127
|
+
For each decision, ask user: "Does this make sense? Any concerns?"
|
|
128
|
+
|
|
129
|
+
5. **Write to tutorial file**: Record the design discussion, chosen approach, and rationale.
|
|
130
|
+
|
|
131
|
+
Update frontmatter: `phase: DESIGN`
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Phase 4: PLAN (concrete implementation steps)
|
|
136
|
+
|
|
137
|
+
1. **Break down the chosen design** into 3-7 concrete, verifiable steps. Each step should:
|
|
138
|
+
- Have a clear goal (what's done when this step is complete)
|
|
139
|
+
- Build on previous steps (incremental, testable progress)
|
|
140
|
+
- Be small enough to verify immediately
|
|
141
|
+
|
|
142
|
+
2. **Show plan to user** with rationale for the ordering:
|
|
143
|
+
> "Here's the build order. We start with X because Y depends on it. Step 3 before Step 4 because..."
|
|
144
|
+
|
|
145
|
+
3. **User validates**: Ask via `AskUserQuestion`:
|
|
146
|
+
> "Does this plan make sense? Want to reorder anything or add/remove steps?"
|
|
86
147
|
|
|
87
|
-
|
|
148
|
+
Adjust plan based on user feedback.
|
|
88
149
|
|
|
89
|
-
|
|
150
|
+
4. **Write plan to tutorial file**: Each step with goal, files involved, and acceptance criteria.
|
|
90
151
|
|
|
91
|
-
|
|
152
|
+
Update frontmatter: `phase: PLAN`, `total_steps: {N}`
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Phase 5: BUILD (core phase)
|
|
157
|
+
|
|
158
|
+
1. **For each step from the PLAN phase, follow the teaching mode**:
|
|
159
|
+
|
|
160
|
+
### Guided Mode (user codes everything)
|
|
161
|
+
|
|
162
|
+
a. **Describe the task**: Explain WHAT to implement and WHY. Include:
|
|
163
|
+
- The goal of this step
|
|
164
|
+
- Which file(s) to create or modify
|
|
165
|
+
- Key concepts/APIs to use
|
|
166
|
+
- Acceptance criteria (what "done" looks like)
|
|
167
|
+
- **Do NOT show the solution code.**
|
|
168
|
+
|
|
169
|
+
b. **User codes**: Tell user to write the code. Wait for them to say "done" or ask for help.
|
|
170
|
+
- If user asks for a hint → give a small hint, not the full answer
|
|
171
|
+
- If user is stuck after 2 hints → offer to show one specific part
|
|
172
|
+
|
|
173
|
+
c. **AI reviews**: Read the file(s) user modified. Provide:
|
|
174
|
+
- Does it work? Run verify commands.
|
|
175
|
+
- Best-practice review: naming, patterns, security, performance
|
|
176
|
+
- Specific feedback: "Line X: consider Y because Z"
|
|
177
|
+
- If issues found → explain and let user fix (don't fix for them)
|
|
178
|
+
|
|
179
|
+
d. **Socratic**: "Why did you choose this approach?" or "What happens if X fails?" via `AskUserQuestion`
|
|
180
|
+
|
|
181
|
+
### Scaffolded Mode (AI provides skeleton, user fills in)
|
|
182
|
+
|
|
183
|
+
a. **Explain** what we're building and why
|
|
184
|
+
|
|
185
|
+
b. **Write skeleton code** with clearly marked `// TODO: implement` sections. Use `Edit`/`Write` tools. The skeleton should include:
|
|
186
|
+
- File structure and imports
|
|
187
|
+
- Function signatures with parameter types
|
|
188
|
+
- Comments describing what each TODO section should do
|
|
189
|
+
- Keep TODOs focused (each is 3-15 lines of real code)
|
|
190
|
+
|
|
191
|
+
c. **User fills in TODOs**: Wait for user to complete them.
|
|
192
|
+
|
|
193
|
+
d. **AI reviews**: Read filled-in code. Same review process as Guided mode.
|
|
194
|
+
|
|
195
|
+
### Demonstrated Mode (AI codes, user reads)
|
|
196
|
+
|
|
197
|
+
a. **Explain** what we're doing and why
|
|
92
198
|
|
|
93
199
|
b. **Write real code** — no placeholders, no pseudocode. Use project conventions. Use `Edit` for existing files, `Write` for new files.
|
|
94
200
|
|
|
95
|
-
c. **
|
|
96
|
-
|
|
201
|
+
c. **Explain key decisions**: After writing, highlight WHY specific choices were made.
|
|
202
|
+
|
|
203
|
+
### All Modes — after coding:
|
|
204
|
+
|
|
205
|
+
e. **Tiered verify**:
|
|
206
|
+
- Always: run syntax check command from language table
|
|
97
207
|
- When possible: run the code
|
|
98
208
|
- If test framework detected: write/run a test
|
|
99
209
|
|
|
100
|
-
|
|
210
|
+
f. **Best-practice review** (all modes): Check the completed code for:
|
|
211
|
+
- Security issues (injection, XSS, exposed secrets)
|
|
212
|
+
- Anti-patterns for the language/framework
|
|
213
|
+
- Naming and convention consistency with project
|
|
214
|
+
- Performance concerns
|
|
215
|
+
- Present findings to user with explanations
|
|
101
216
|
|
|
102
|
-
|
|
103
|
-
- If user reports error → debug
|
|
217
|
+
g. **Checkpoint**: `AskUserQuestion` — "Step {N}/{total} verified. Ready for next?"
|
|
218
|
+
- If user reports error → debug together (Guided: guide user to fix; Demonstrated: fix directly)
|
|
104
219
|
- If user needs explanation → explain, then continue
|
|
105
220
|
|
|
106
|
-
|
|
221
|
+
h. **Explain-back check** (every 2-3 steps): Ask user via `AskUserQuestion`:
|
|
222
|
+
> "Quick check — can you explain in your own words what we built in the last {N} steps and how they connect?"
|
|
223
|
+
- If user explains well → acknowledge and continue
|
|
224
|
+
- If gaps → re-explain the unclear parts before proceeding
|
|
225
|
+
|
|
226
|
+
i. **Write to tutorial file**: step title, explanation, code, key points, verify result
|
|
107
227
|
|
|
108
228
|
Update frontmatter: `phase: BUILD`, `step: {N}`, `total_steps: {total}`
|
|
109
229
|
|
|
110
230
|
---
|
|
111
231
|
|
|
112
|
-
## Phase
|
|
232
|
+
## Phase 6: WRAP-UP
|
|
113
233
|
|
|
114
234
|
1. **Summary**: What was built, key takeaways (3-5 points)
|
|
115
235
|
|
|
@@ -126,22 +246,28 @@ Display: `Tutorial saved: learn/{filename}.md`
|
|
|
126
246
|
|
|
127
247
|
## Principles
|
|
128
248
|
|
|
129
|
-
1. **
|
|
130
|
-
2. **
|
|
131
|
-
3. **
|
|
132
|
-
4. **
|
|
249
|
+
1. **User owns the code** — in Guided/Scaffolded mode, user writes; AI reviews, never writes for them
|
|
250
|
+
2. **Verify everything** — never assume code works
|
|
251
|
+
3. **Real code only** — no placeholders, no pseudocode (except Scaffolded TODOs)
|
|
252
|
+
4. **User controls pace** — always checkpoint before proceeding
|
|
253
|
+
5. **Teach with their code** — use project's actual codebase, not generic examples
|
|
254
|
+
6. **Best practices always** — review every step for security, patterns, conventions
|
|
255
|
+
7. **Understanding > completion** — if user doesn't understand, stop and re-explain
|
|
133
256
|
|
|
134
257
|
---
|
|
135
258
|
|
|
136
259
|
## Error Handling
|
|
137
260
|
|
|
138
261
|
- **Verify tool missing**: Ask user to install or switch to manual verification
|
|
139
|
-
- **Code doesn't work on user's machine**: Get error message, debug
|
|
262
|
+
- **Code doesn't work on user's machine**: Get error message, debug together, re-verify, update tutorial
|
|
140
263
|
- **Language not detected**: Ask user to specify, set verify strategy accordingly
|
|
264
|
+
- **User stuck in Guided mode**: After 2 hints, offer to show solution for that specific part only
|
|
141
265
|
|
|
142
266
|
---
|
|
143
267
|
|
|
144
268
|
## Version History
|
|
145
269
|
|
|
270
|
+
- **3.1.0** - Added DESIGN phase (Socratic architecture) and PLAN phase (concrete steps). Full flow: INIT → LEARN → DESIGN → PLAN → BUILD → WRAP-UP
|
|
271
|
+
- **3.0.0** - Teaching modes (guided/scaffolded/demonstrated), best-practice review, explain-back checkpoints, user-codes-first philosophy
|
|
146
272
|
- **2.0.0** - Rewrite: adaptive difficulty via codingLevel, 4 phases, WebSearch, Socratic method, resume support, tiered verify, 17 languages, codebase-aware
|
|
147
273
|
- **1.0.0** - Initial release
|
package/package.json
CHANGED
package/rules-index.json
CHANGED
package/skills/learn/SKILL.md
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: learn
|
|
3
|
-
description:
|
|
3
|
+
description: Guided project building — you code, AI mentors. Build your own product step-by-step with best practices and deep understanding.
|
|
4
4
|
argument-hint: [topic]
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
# Learn Mode
|
|
7
|
+
# Learn Mode v3.1
|
|
8
8
|
|
|
9
|
-
>
|
|
9
|
+
> Build your product. Design the architecture. Write every line. Understand every decision.
|
|
10
10
|
|
|
11
11
|
## Activation
|
|
12
12
|
|
|
13
|
-
`/learn "topic"` — e.g., `/learn "JWT auth in Express"`, `/learn "
|
|
13
|
+
`/learn "topic"` — e.g., `/learn "JWT auth in Express"`, `/learn "build real-time chat"`
|
|
14
14
|
|
|
15
15
|
---
|
|
16
16
|
|
|
@@ -44,13 +44,23 @@ If multiple detected → ask user. If none → ask user.
|
|
|
44
44
|
|
|
45
45
|
3. **Codebase scan**: Read key project files (entry points, configs, existing code related to topic) for context. Use project's conventions in all examples.
|
|
46
46
|
|
|
47
|
-
4. **
|
|
47
|
+
4. **Difficulty from codingLevel** (read from `.claude/.ck.json`):
|
|
48
48
|
- Level 0-1 → **Deep**: full concepts, analogies, Socratic questions at every step
|
|
49
49
|
- Level 2-3 → **Standard**: concepts + code, balanced explanations
|
|
50
50
|
- Level 4-5 → **Quick**: minimal explanation, jump straight to code
|
|
51
51
|
- Not set → ask user with `AskUserQuestion`
|
|
52
52
|
|
|
53
|
-
5. **
|
|
53
|
+
5. **Teaching mode** — ask user via `AskUserQuestion`:
|
|
54
|
+
|
|
55
|
+
| Mode | Who codes? | AI does what? | Best for |
|
|
56
|
+
|------|-----------|---------------|----------|
|
|
57
|
+
| **Guided** | User writes all code | Describe task + review after | Deep understanding, own the code |
|
|
58
|
+
| **Scaffolded** | User fills in key parts | Provide skeleton + hints | Learning new patterns |
|
|
59
|
+
| **Demonstrated** | AI writes, user reads | Write code + explain | Quick overview, reading comprehension |
|
|
60
|
+
|
|
61
|
+
Default suggestion based on difficulty: Deep → Guided, Standard → Scaffolded, Quick → Demonstrated.
|
|
62
|
+
|
|
63
|
+
6. **Create output file**: `learn/{YYYY-MM-DD}-{topic-slug}.md` with YAML frontmatter:
|
|
54
64
|
```yaml
|
|
55
65
|
---
|
|
56
66
|
topic: "{topic}"
|
|
@@ -58,7 +68,8 @@ language: {detected}
|
|
|
58
68
|
phase: INIT
|
|
59
69
|
step: 0
|
|
60
70
|
total_steps: 0
|
|
61
|
-
|
|
71
|
+
difficulty: {deep|standard|quick}
|
|
72
|
+
teaching: {guided|scaffolded|demonstrated}
|
|
62
73
|
started: {ISO timestamp}
|
|
63
74
|
updated: {ISO timestamp}
|
|
64
75
|
---
|
|
@@ -66,7 +77,7 @@ updated: {ISO timestamp}
|
|
|
66
77
|
|
|
67
78
|
---
|
|
68
79
|
|
|
69
|
-
## Phase 2: LEARN (skip entirely in Quick
|
|
80
|
+
## Phase 2: LEARN (skip entirely in Quick difficulty)
|
|
70
81
|
|
|
71
82
|
1. **WebSearch** official docs: `WebSearch("{topic} {language} official documentation")`, then `WebFetch` the most relevant result. Cite sources in tutorial.
|
|
72
83
|
|
|
@@ -82,34 +93,143 @@ Update frontmatter: `phase: LEARN`
|
|
|
82
93
|
|
|
83
94
|
---
|
|
84
95
|
|
|
85
|
-
## Phase 3:
|
|
96
|
+
## Phase 3: DESIGN (Socratic architecture thinking)
|
|
97
|
+
|
|
98
|
+
> User thinks first, AI guides — not the other way around.
|
|
99
|
+
|
|
100
|
+
1. **Frame the problem**: AI presents the high-level problem to solve:
|
|
101
|
+
> "We need to build {topic}. Before I suggest anything — how would YOU approach this? What components or pieces do you think we need?"
|
|
102
|
+
|
|
103
|
+
Ask via `AskUserQuestion`. Let user think and answer.
|
|
104
|
+
|
|
105
|
+
2. **Build on user's answer**:
|
|
106
|
+
- If user's approach is solid → acknowledge strengths, refine together
|
|
107
|
+
- If user's approach has gaps → ask guiding questions: "What about {concern}? How would you handle that?"
|
|
108
|
+
- If user has no idea → break it down: "Let's start smaller — what's the first thing a user would do with this feature?"
|
|
109
|
+
|
|
110
|
+
3. **Explore alternatives**: Present 2-3 different approaches with trade-offs:
|
|
111
|
+
> "Your approach uses X. Another option is Y. Here's how they compare:"
|
|
112
|
+
|
|
113
|
+
| Aspect | Approach A (user's) | Approach B | Approach C |
|
|
114
|
+
|--------|-------------------|-----------|-----------|
|
|
115
|
+
| Complexity | ... | ... | ... |
|
|
116
|
+
| Scalability | ... | ... | ... |
|
|
117
|
+
| Learning value | ... | ... | ... |
|
|
118
|
+
|
|
119
|
+
Ask user to choose via `AskUserQuestion`. Explain WHY each trade-off matters.
|
|
120
|
+
|
|
121
|
+
4. **Architecture decisions**: For the chosen approach, walk through key decisions:
|
|
122
|
+
- Data flow: how data moves through the system
|
|
123
|
+
- File/module structure: where code lives and why
|
|
124
|
+
- Dependencies: what libraries/tools and why those specifically
|
|
125
|
+
- Patterns: which design patterns and why (not just "use MVC" but why MVC fits here)
|
|
126
|
+
|
|
127
|
+
For each decision, ask user: "Does this make sense? Any concerns?"
|
|
128
|
+
|
|
129
|
+
5. **Write to tutorial file**: Record the design discussion, chosen approach, and rationale.
|
|
130
|
+
|
|
131
|
+
Update frontmatter: `phase: DESIGN`
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Phase 4: PLAN (concrete implementation steps)
|
|
136
|
+
|
|
137
|
+
1. **Break down the chosen design** into 3-7 concrete, verifiable steps. Each step should:
|
|
138
|
+
- Have a clear goal (what's done when this step is complete)
|
|
139
|
+
- Build on previous steps (incremental, testable progress)
|
|
140
|
+
- Be small enough to verify immediately
|
|
141
|
+
|
|
142
|
+
2. **Show plan to user** with rationale for the ordering:
|
|
143
|
+
> "Here's the build order. We start with X because Y depends on it. Step 3 before Step 4 because..."
|
|
144
|
+
|
|
145
|
+
3. **User validates**: Ask via `AskUserQuestion`:
|
|
146
|
+
> "Does this plan make sense? Want to reorder anything or add/remove steps?"
|
|
86
147
|
|
|
87
|
-
|
|
148
|
+
Adjust plan based on user feedback.
|
|
88
149
|
|
|
89
|
-
|
|
150
|
+
4. **Write plan to tutorial file**: Each step with goal, files involved, and acceptance criteria.
|
|
90
151
|
|
|
91
|
-
|
|
152
|
+
Update frontmatter: `phase: PLAN`, `total_steps: {N}`
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Phase 5: BUILD (core phase)
|
|
157
|
+
|
|
158
|
+
1. **For each step from the PLAN phase, follow the teaching mode**:
|
|
159
|
+
|
|
160
|
+
### Guided Mode (user codes everything)
|
|
161
|
+
|
|
162
|
+
a. **Describe the task**: Explain WHAT to implement and WHY. Include:
|
|
163
|
+
- The goal of this step
|
|
164
|
+
- Which file(s) to create or modify
|
|
165
|
+
- Key concepts/APIs to use
|
|
166
|
+
- Acceptance criteria (what "done" looks like)
|
|
167
|
+
- **Do NOT show the solution code.**
|
|
168
|
+
|
|
169
|
+
b. **User codes**: Tell user to write the code. Wait for them to say "done" or ask for help.
|
|
170
|
+
- If user asks for a hint → give a small hint, not the full answer
|
|
171
|
+
- If user is stuck after 2 hints → offer to show one specific part
|
|
172
|
+
|
|
173
|
+
c. **AI reviews**: Read the file(s) user modified. Provide:
|
|
174
|
+
- Does it work? Run verify commands.
|
|
175
|
+
- Best-practice review: naming, patterns, security, performance
|
|
176
|
+
- Specific feedback: "Line X: consider Y because Z"
|
|
177
|
+
- If issues found → explain and let user fix (don't fix for them)
|
|
178
|
+
|
|
179
|
+
d. **Socratic**: "Why did you choose this approach?" or "What happens if X fails?" via `AskUserQuestion`
|
|
180
|
+
|
|
181
|
+
### Scaffolded Mode (AI provides skeleton, user fills in)
|
|
182
|
+
|
|
183
|
+
a. **Explain** what we're building and why
|
|
184
|
+
|
|
185
|
+
b. **Write skeleton code** with clearly marked `// TODO: implement` sections. Use `Edit`/`Write` tools. The skeleton should include:
|
|
186
|
+
- File structure and imports
|
|
187
|
+
- Function signatures with parameter types
|
|
188
|
+
- Comments describing what each TODO section should do
|
|
189
|
+
- Keep TODOs focused (each is 3-15 lines of real code)
|
|
190
|
+
|
|
191
|
+
c. **User fills in TODOs**: Wait for user to complete them.
|
|
192
|
+
|
|
193
|
+
d. **AI reviews**: Read filled-in code. Same review process as Guided mode.
|
|
194
|
+
|
|
195
|
+
### Demonstrated Mode (AI codes, user reads)
|
|
196
|
+
|
|
197
|
+
a. **Explain** what we're doing and why
|
|
92
198
|
|
|
93
199
|
b. **Write real code** — no placeholders, no pseudocode. Use project conventions. Use `Edit` for existing files, `Write` for new files.
|
|
94
200
|
|
|
95
|
-
c. **
|
|
96
|
-
|
|
201
|
+
c. **Explain key decisions**: After writing, highlight WHY specific choices were made.
|
|
202
|
+
|
|
203
|
+
### All Modes — after coding:
|
|
204
|
+
|
|
205
|
+
e. **Tiered verify**:
|
|
206
|
+
- Always: run syntax check command from language table
|
|
97
207
|
- When possible: run the code
|
|
98
208
|
- If test framework detected: write/run a test
|
|
99
209
|
|
|
100
|
-
|
|
210
|
+
f. **Best-practice review** (all modes): Check the completed code for:
|
|
211
|
+
- Security issues (injection, XSS, exposed secrets)
|
|
212
|
+
- Anti-patterns for the language/framework
|
|
213
|
+
- Naming and convention consistency with project
|
|
214
|
+
- Performance concerns
|
|
215
|
+
- Present findings to user with explanations
|
|
101
216
|
|
|
102
|
-
|
|
103
|
-
- If user reports error → debug
|
|
217
|
+
g. **Checkpoint**: `AskUserQuestion` — "Step {N}/{total} verified. Ready for next?"
|
|
218
|
+
- If user reports error → debug together (Guided: guide user to fix; Demonstrated: fix directly)
|
|
104
219
|
- If user needs explanation → explain, then continue
|
|
105
220
|
|
|
106
|
-
|
|
221
|
+
h. **Explain-back check** (every 2-3 steps): Ask user via `AskUserQuestion`:
|
|
222
|
+
> "Quick check — can you explain in your own words what we built in the last {N} steps and how they connect?"
|
|
223
|
+
- If user explains well → acknowledge and continue
|
|
224
|
+
- If gaps → re-explain the unclear parts before proceeding
|
|
225
|
+
|
|
226
|
+
i. **Write to tutorial file**: step title, explanation, code, key points, verify result
|
|
107
227
|
|
|
108
228
|
Update frontmatter: `phase: BUILD`, `step: {N}`, `total_steps: {total}`
|
|
109
229
|
|
|
110
230
|
---
|
|
111
231
|
|
|
112
|
-
## Phase
|
|
232
|
+
## Phase 6: WRAP-UP
|
|
113
233
|
|
|
114
234
|
1. **Summary**: What was built, key takeaways (3-5 points)
|
|
115
235
|
|
|
@@ -126,22 +246,28 @@ Display: `Tutorial saved: learn/{filename}.md`
|
|
|
126
246
|
|
|
127
247
|
## Principles
|
|
128
248
|
|
|
129
|
-
1. **
|
|
130
|
-
2. **
|
|
131
|
-
3. **
|
|
132
|
-
4. **
|
|
249
|
+
1. **User owns the code** — in Guided/Scaffolded mode, user writes; AI reviews, never writes for them
|
|
250
|
+
2. **Verify everything** — never assume code works
|
|
251
|
+
3. **Real code only** — no placeholders, no pseudocode (except Scaffolded TODOs)
|
|
252
|
+
4. **User controls pace** — always checkpoint before proceeding
|
|
253
|
+
5. **Teach with their code** — use project's actual codebase, not generic examples
|
|
254
|
+
6. **Best practices always** — review every step for security, patterns, conventions
|
|
255
|
+
7. **Understanding > completion** — if user doesn't understand, stop and re-explain
|
|
133
256
|
|
|
134
257
|
---
|
|
135
258
|
|
|
136
259
|
## Error Handling
|
|
137
260
|
|
|
138
261
|
- **Verify tool missing**: Ask user to install or switch to manual verification
|
|
139
|
-
- **Code doesn't work on user's machine**: Get error message, debug
|
|
262
|
+
- **Code doesn't work on user's machine**: Get error message, debug together, re-verify, update tutorial
|
|
140
263
|
- **Language not detected**: Ask user to specify, set verify strategy accordingly
|
|
264
|
+
- **User stuck in Guided mode**: After 2 hints, offer to show solution for that specific part only
|
|
141
265
|
|
|
142
266
|
---
|
|
143
267
|
|
|
144
268
|
## Version History
|
|
145
269
|
|
|
270
|
+
- **3.1.0** - Added DESIGN phase (Socratic architecture) and PLAN phase (concrete steps). Full flow: INIT → LEARN → DESIGN → PLAN → BUILD → WRAP-UP
|
|
271
|
+
- **3.0.0** - Teaching modes (guided/scaffolded/demonstrated), best-practice review, explain-back checkpoints, user-codes-first philosophy
|
|
146
272
|
- **2.0.0** - Rewrite: adaptive difficulty via codingLevel, 4 phases, WebSearch, Socratic method, resume support, tiered verify, 17 languages, codebase-aware
|
|
147
273
|
- **1.0.0** - Initial release
|
package/skills-index.json
CHANGED
|
@@ -1977,7 +1977,7 @@
|
|
|
1977
1977
|
{
|
|
1978
1978
|
"name": "learn",
|
|
1979
1979
|
"path": "skills/learn",
|
|
1980
|
-
"description": "
|
|
1980
|
+
"description": "Guided project building — you code, AI mentors. Build your own product step-by-step with best practices and deep understanding."
|
|
1981
1981
|
},
|
|
1982
1982
|
{
|
|
1983
1983
|
"name": "legacy-modernizer",
|