@ngxtm/devkit 3.12.0 → 3.13.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 (6) hide show
  1. package/SKILLS_INDEX.md +1 -1
  2. package/merged-commands/learn.md +88 -21
  3. package/package.json +1 -1
  4. package/rules-index.json +1 -1
  5. package/skills/learn/SKILL.md +88 -21
  6. 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
- Interactive learning mode. Teaches by doing with verified code, adaptive difficulty, and Socratic questioning.
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: Interactive learning mode. Teaches by doing with verified code, adaptive difficulty, and Socratic questioning.
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 v2.0
7
+ # Learn Mode v3.0
8
8
 
9
- > Learn by doing. Verified at every step. Adapted to your level.
9
+ > Build your product. Write every line. Understand every decision.
10
10
 
11
11
  ## Activation
12
12
 
13
- `/learn "topic"` — e.g., `/learn "JWT auth in Express"`, `/learn "React custom hooks"`
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. **Mode from codingLevel** (read from `.claude/.ck.json`):
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. **Create output file**: `learn/{YYYY-MM-DD}-{topic-slug}.md` with YAML frontmatter:
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
- mode: {deep|standard|quick}
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 mode)
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
 
@@ -86,24 +97,75 @@ Update frontmatter: `phase: LEARN`
86
97
 
87
98
  1. **Plan steps**: Break implementation into 3-7 verifiable steps. Show plan to user.
88
99
 
89
- 2. **For each step**:
100
+ 2. **For each step, follow the teaching mode**:
101
+
102
+ ### Guided Mode (user codes everything)
103
+
104
+ a. **Describe the task**: Explain WHAT to implement and WHY. Include:
105
+ - The goal of this step
106
+ - Which file(s) to create or modify
107
+ - Key concepts/APIs to use
108
+ - Acceptance criteria (what "done" looks like)
109
+ - **Do NOT show the solution code.**
110
+
111
+ b. **User codes**: Tell user to write the code. Wait for them to say "done" or ask for help.
112
+ - If user asks for a hint → give a small hint, not the full answer
113
+ - If user is stuck after 2 hints → offer to show one specific part
114
+
115
+ c. **AI reviews**: Read the file(s) user modified. Provide:
116
+ - Does it work? Run verify commands.
117
+ - Best-practice review: naming, patterns, security, performance
118
+ - Specific feedback: "Line X: consider Y because Z"
119
+ - If issues found → explain and let user fix (don't fix for them)
120
+
121
+ d. **Socratic**: "Why did you choose this approach?" or "What happens if X fails?" via `AskUserQuestion`
122
+
123
+ ### Scaffolded Mode (AI provides skeleton, user fills in)
90
124
 
91
- a. **Explain** what we're doing and why (skip in Quick mode)
125
+ a. **Explain** what we're building and why
126
+
127
+ b. **Write skeleton code** with clearly marked `// TODO: implement` sections. Use `Edit`/`Write` tools. The skeleton should include:
128
+ - File structure and imports
129
+ - Function signatures with parameter types
130
+ - Comments describing what each TODO section should do
131
+ - Keep TODOs focused (each is 3-15 lines of real code)
132
+
133
+ c. **User fills in TODOs**: Wait for user to complete them.
134
+
135
+ d. **AI reviews**: Read filled-in code. Same review process as Guided mode.
136
+
137
+ ### Demonstrated Mode (AI codes, user reads)
138
+
139
+ a. **Explain** what we're doing and why
92
140
 
93
141
  b. **Write real code** — no placeholders, no pseudocode. Use project conventions. Use `Edit` for existing files, `Write` for new files.
94
142
 
95
- c. **Tiered verify**:
96
- - Always: run syntax check command from table above
143
+ c. **Explain key decisions**: After writing, highlight WHY specific choices were made.
144
+
145
+ ### All Modes — after coding:
146
+
147
+ e. **Tiered verify**:
148
+ - Always: run syntax check command from language table
97
149
  - When possible: run the code
98
150
  - If test framework detected: write/run a test
99
151
 
100
- d. **Socratic** (Deep mode only): Ask "Why did we use X instead of Y?" via `AskUserQuestion`
152
+ f. **Best-practice review** (all modes): Check the completed code for:
153
+ - Security issues (injection, XSS, exposed secrets)
154
+ - Anti-patterns for the language/framework
155
+ - Naming and convention consistency with project
156
+ - Performance concerns
157
+ - Present findings to user with explanations
101
158
 
102
- e. **Checkpoint**: `AskUserQuestion` — "Step {N}/{total} verified. Understood?"
103
- - If user reports error → debug, fix, re-verify, update tutorial
159
+ g. **Checkpoint**: `AskUserQuestion` — "Step {N}/{total} verified. Ready for next?"
160
+ - If user reports error → debug together (Guided: guide user to fix; Demonstrated: fix directly)
104
161
  - If user needs explanation → explain, then continue
105
162
 
106
- f. **Write to tutorial file**: step title, explanation, code, key points, verify result
163
+ h. **Explain-back check** (every 2-3 steps): Ask user via `AskUserQuestion`:
164
+ > "Quick check — can you explain in your own words what we built in the last {N} steps and how they connect?"
165
+ - If user explains well → acknowledge and continue
166
+ - If gaps → re-explain the unclear parts before proceeding
167
+
168
+ i. **Write to tutorial file**: step title, explanation, code, key points, verify result
107
169
 
108
170
  Update frontmatter: `phase: BUILD`, `step: {N}`, `total_steps: {total}`
109
171
 
@@ -126,22 +188,27 @@ Display: `Tutorial saved: learn/{filename}.md`
126
188
 
127
189
  ## Principles
128
190
 
129
- 1. **Verify everything** — never assume code works
130
- 2. **Real code only** — no placeholders, no pseudocode
131
- 3. **User controls pace** — always checkpoint before proceeding
132
- 4. **Teach with their code** — use project's actual codebase, not generic examples
191
+ 1. **User owns the code** — in Guided/Scaffolded mode, user writes; AI reviews, never writes for them
192
+ 2. **Verify everything** — never assume code works
193
+ 3. **Real code only** — no placeholders, no pseudocode (except Scaffolded TODOs)
194
+ 4. **User controls pace** — always checkpoint before proceeding
195
+ 5. **Teach with their code** — use project's actual codebase, not generic examples
196
+ 6. **Best practices always** — review every step for security, patterns, conventions
197
+ 7. **Understanding > completion** — if user doesn't understand, stop and re-explain
133
198
 
134
199
  ---
135
200
 
136
201
  ## Error Handling
137
202
 
138
203
  - **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, fix, re-verify, update tutorial
204
+ - **Code doesn't work on user's machine**: Get error message, debug together, re-verify, update tutorial
140
205
  - **Language not detected**: Ask user to specify, set verify strategy accordingly
206
+ - **User stuck in Guided mode**: After 2 hints, offer to show solution for that specific part only
141
207
 
142
208
  ---
143
209
 
144
210
  ## Version History
145
211
 
212
+ - **3.0.0** - Teaching modes (guided/scaffolded/demonstrated), best-practice review, explain-back checkpoints, user-codes-first philosophy
146
213
  - **2.0.0** - Rewrite: adaptive difficulty via codingLevel, 4 phases, WebSearch, Socratic method, resume support, tiered verify, 17 languages, codebase-aware
147
214
  - **1.0.0** - Initial release
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngxtm/devkit",
3
- "version": "3.12.0",
3
+ "version": "3.13.0",
4
4
  "description": "Per-project AI skills with smart tech detection - lightweight and context-optimized",
5
5
  "main": "cli/index.js",
6
6
  "bin": {
package/rules-index.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "version": "1.0.0",
3
- "generatedAt": "2026-02-18T04:28:45.416Z",
3
+ "generatedAt": "2026-02-19T07:09:25.835Z",
4
4
  "templates": {
5
5
  "dart": {
6
6
  "path": "templates/dart/rules",
package/skills/learn/SKILL.md CHANGED
@@ -1,16 +1,16 @@
1
1
  ---
2
2
  name: learn
3
- description: Interactive learning mode. Teaches by doing with verified code, adaptive difficulty, and Socratic questioning.
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 v2.0
7
+ # Learn Mode v3.0
8
8
 
9
- > Learn by doing. Verified at every step. Adapted to your level.
9
+ > Build your product. Write every line. Understand every decision.
10
10
 
11
11
  ## Activation
12
12
 
13
- `/learn "topic"` — e.g., `/learn "JWT auth in Express"`, `/learn "React custom hooks"`
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. **Mode from codingLevel** (read from `.claude/.ck.json`):
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. **Create output file**: `learn/{YYYY-MM-DD}-{topic-slug}.md` with YAML frontmatter:
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
- mode: {deep|standard|quick}
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 mode)
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
 
@@ -86,24 +97,75 @@ Update frontmatter: `phase: LEARN`
86
97
 
87
98
  1. **Plan steps**: Break implementation into 3-7 verifiable steps. Show plan to user.
88
99
 
89
- 2. **For each step**:
100
+ 2. **For each step, follow the teaching mode**:
101
+
102
+ ### Guided Mode (user codes everything)
103
+
104
+ a. **Describe the task**: Explain WHAT to implement and WHY. Include:
105
+ - The goal of this step
106
+ - Which file(s) to create or modify
107
+ - Key concepts/APIs to use
108
+ - Acceptance criteria (what "done" looks like)
109
+ - **Do NOT show the solution code.**
110
+
111
+ b. **User codes**: Tell user to write the code. Wait for them to say "done" or ask for help.
112
+ - If user asks for a hint → give a small hint, not the full answer
113
+ - If user is stuck after 2 hints → offer to show one specific part
114
+
115
+ c. **AI reviews**: Read the file(s) user modified. Provide:
116
+ - Does it work? Run verify commands.
117
+ - Best-practice review: naming, patterns, security, performance
118
+ - Specific feedback: "Line X: consider Y because Z"
119
+ - If issues found → explain and let user fix (don't fix for them)
120
+
121
+ d. **Socratic**: "Why did you choose this approach?" or "What happens if X fails?" via `AskUserQuestion`
122
+
123
+ ### Scaffolded Mode (AI provides skeleton, user fills in)
90
124
 
91
- a. **Explain** what we're doing and why (skip in Quick mode)
125
+ a. **Explain** what we're building and why
126
+
127
+ b. **Write skeleton code** with clearly marked `// TODO: implement` sections. Use `Edit`/`Write` tools. The skeleton should include:
128
+ - File structure and imports
129
+ - Function signatures with parameter types
130
+ - Comments describing what each TODO section should do
131
+ - Keep TODOs focused (each is 3-15 lines of real code)
132
+
133
+ c. **User fills in TODOs**: Wait for user to complete them.
134
+
135
+ d. **AI reviews**: Read filled-in code. Same review process as Guided mode.
136
+
137
+ ### Demonstrated Mode (AI codes, user reads)
138
+
139
+ a. **Explain** what we're doing and why
92
140
 
93
141
  b. **Write real code** — no placeholders, no pseudocode. Use project conventions. Use `Edit` for existing files, `Write` for new files.
94
142
 
95
- c. **Tiered verify**:
96
- - Always: run syntax check command from table above
143
+ c. **Explain key decisions**: After writing, highlight WHY specific choices were made.
144
+
145
+ ### All Modes — after coding:
146
+
147
+ e. **Tiered verify**:
148
+ - Always: run syntax check command from language table
97
149
  - When possible: run the code
98
150
  - If test framework detected: write/run a test
99
151
 
100
- d. **Socratic** (Deep mode only): Ask "Why did we use X instead of Y?" via `AskUserQuestion`
152
+ f. **Best-practice review** (all modes): Check the completed code for:
153
+ - Security issues (injection, XSS, exposed secrets)
154
+ - Anti-patterns for the language/framework
155
+ - Naming and convention consistency with project
156
+ - Performance concerns
157
+ - Present findings to user with explanations
101
158
 
102
- e. **Checkpoint**: `AskUserQuestion` — "Step {N}/{total} verified. Understood?"
103
- - If user reports error → debug, fix, re-verify, update tutorial
159
+ g. **Checkpoint**: `AskUserQuestion` — "Step {N}/{total} verified. Ready for next?"
160
+ - If user reports error → debug together (Guided: guide user to fix; Demonstrated: fix directly)
104
161
  - If user needs explanation → explain, then continue
105
162
 
106
- f. **Write to tutorial file**: step title, explanation, code, key points, verify result
163
+ h. **Explain-back check** (every 2-3 steps): Ask user via `AskUserQuestion`:
164
+ > "Quick check — can you explain in your own words what we built in the last {N} steps and how they connect?"
165
+ - If user explains well → acknowledge and continue
166
+ - If gaps → re-explain the unclear parts before proceeding
167
+
168
+ i. **Write to tutorial file**: step title, explanation, code, key points, verify result
107
169
 
108
170
  Update frontmatter: `phase: BUILD`, `step: {N}`, `total_steps: {total}`
109
171
 
@@ -126,22 +188,27 @@ Display: `Tutorial saved: learn/{filename}.md`
126
188
 
127
189
  ## Principles
128
190
 
129
- 1. **Verify everything** — never assume code works
130
- 2. **Real code only** — no placeholders, no pseudocode
131
- 3. **User controls pace** — always checkpoint before proceeding
132
- 4. **Teach with their code** — use project's actual codebase, not generic examples
191
+ 1. **User owns the code** — in Guided/Scaffolded mode, user writes; AI reviews, never writes for them
192
+ 2. **Verify everything** — never assume code works
193
+ 3. **Real code only** — no placeholders, no pseudocode (except Scaffolded TODOs)
194
+ 4. **User controls pace** — always checkpoint before proceeding
195
+ 5. **Teach with their code** — use project's actual codebase, not generic examples
196
+ 6. **Best practices always** — review every step for security, patterns, conventions
197
+ 7. **Understanding > completion** — if user doesn't understand, stop and re-explain
133
198
 
134
199
  ---
135
200
 
136
201
  ## Error Handling
137
202
 
138
203
  - **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, fix, re-verify, update tutorial
204
+ - **Code doesn't work on user's machine**: Get error message, debug together, re-verify, update tutorial
140
205
  - **Language not detected**: Ask user to specify, set verify strategy accordingly
206
+ - **User stuck in Guided mode**: After 2 hints, offer to show solution for that specific part only
141
207
 
142
208
  ---
143
209
 
144
210
  ## Version History
145
211
 
212
+ - **3.0.0** - Teaching modes (guided/scaffolded/demonstrated), best-practice review, explain-back checkpoints, user-codes-first philosophy
146
213
  - **2.0.0** - Rewrite: adaptive difficulty via codingLevel, 4 phases, WebSearch, Socratic method, resume support, tiered verify, 17 languages, codebase-aware
147
214
  - **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": "Interactive learning mode. Teaches by doing with verified code, adaptive difficulty, and Socratic questioning."
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",