@ngxtm/devkit 3.20.0 → 3.21.0

package/merged-commands/recover.md

@@ -0,0 +1,22 @@
+---
+description: "\U0001F504 Recover context from a previous session checkpoint"
+---
+
+Look for checkpoint files in `.claude/sessions/` directory and recover context from a previous session.
+
+## Workflow
+
+1. **Check git**: Run `git rev-parse --is-inside-work-tree 2>/dev/null` to detect git repo
+2. **Get branch**: If git repo, run `git branch --show-current` to get current branch
+3. **Find checkpoints**: Glob `.claude/sessions/*.md` to list all checkpoint files
+4. **Cleanup stale**: Delete any checkpoint files older than 7 days (abandoned sessions)
+5. **Check results**: If no checkpoints remain → tell user "No active checkpoints found"
+6. **Filter by branch**: If git repo, filter checkpoints matching `branch:{current-branch}` in the first line. If no match on current branch, show all checkpoints with branch labels.
+7. **Show recent**: Display max 5 most recent checkpoints (sorted by filename date prefix `YYMMDD-HHMM`)
+8. **Select**: If only 1 match → read it automatically. If multiple → always list them and let user pick using `AskUserQuestion`.
+9. **Validate**: Verify the checkpoint file has a `#` header line and a `## Next Action` section. If malformed, skip it and try the next one.
+10. **Display summary**: Show the checkpoint's task description, current phase, progress (done/pending), next action, and referenced plan file
+11. **Confirm**: Ask user "Continue from this checkpoint?"
+12. **Resume**: If yes → read the referenced plan file (if any) and proceed with the Next Action from the checkpoint
+
+**IMPORTANT**: For non-git projects, skip branch filtering and show all checkpoints.

package/merged-commands/skill/sync.md

@@ -95,15 +95,31 @@ For each item in `external-skills`:
 
 ### Step 5: Evaluate Rules
 
+**IMPORTANT:** Never overwrite or sync rules in `rules/base/`. Base rules are devkit-native and managed manually. Only evaluate rules in tech-specific directories.
+
 For each item in `rules.new`:
 1. Read the rule content from `path` field
 2. Classify: useful (covers new pattern) or skip (duplicate/too generic)
-3. In `--auto` mode: sync all useful
-4. In interactive mode: ask user
+3. Count lines — if > 50 lines, flag as "verbose, needs compaction"
+4. In `--auto` mode: sync all useful (compact verbose ones automatically)
+5. In interactive mode: ask user
 
 For each item in `rules.updated`:
 1. Compare upstream and local content
 2. Accept meaningful updates, skip trivial ones
+3. Count lines — if > 50 lines, flag as "verbose, needs compaction"
+
+**Note:** Size-based compaction applies to RULES only. Skills are loaded on-demand and do not need compaction.
+
+### Step 5.5: Compact Verbose Rules
+
+For each rule flagged as verbose (> 50 lines):
+1. Read full content
+2. Compact while preserving: core patterns, conventions, do's/don'ts, lookup tables, key code examples (max 1-2)
+3. Remove: redundant explanations, excessive examples, sections repeating what Claude already knows, full example interactions/dialogs
+4. Target: ≤ 50 lines for tech rules
+5. In `--auto` mode: compact automatically
+6. In interactive mode: show line count before/after, ask user
 
 ### Step 6: Apply Changes
 
@@ -134,7 +150,7 @@ npm run build
 
 Stage and commit the changes:
 ```bash
-git add skills/ rules/ merged-commands/ SKILLS_INDEX.md skills-index.json skills-compact.json skills-graph.json rules-index.json
+git add skills/ rules/ merged-commands/ templates/ SKILLS_INDEX.md skills-index.json skills-compact.json skills-graph.json rules-index.json
 ```
 
 Commit message format:
@@ -162,9 +178,17 @@ If stash was created earlier: `git stash pop` to restore user's changes.
 - Always update version tracking
 - Never overwrite devkit-specific frontmatter (`triggers`, `role`, `scope`, `output-format`)
 
-### Rules
-- **Accept**: Rule covers useful pattern not in existing rules
+### Rules (loaded every turn — context cost matters)
+- **Accept**: Useful pattern, ≤ 50 lines
+- **Compact**: Useful but > 50 lines → reduce while preserving core content
 - **Skip**: Duplicate or too generic
+- **Protect**: Never touch rules/base/ (devkit-native)
+
+### Skills (loaded on-demand — no compaction needed)
+- **Useful**: Covers distinct domain, well-structured SKILL.md, actionable patterns/commands
+- **Duplicate**: Similar name or description to existing skill in skills-compact.json
+- **Skip**: Too niche, low quality, just "be a senior X engineer" boilerplate
+- No size-based compaction — verbose skills are acceptable
 
 ## Important
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngxtm/devkit",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "description": "Per-project AI skills with smart tech detection - lightweight and context-optimized",
   "main": "cli/index.js",
   "bin": {

package/rules/base/auto-skill.md

@@ -0,0 +1,60 @@
+# Auto-Skill Detection
+
+> Automatically detect and suggest relevant skills based on user's task
+
+## When to Activate
+
+Before starting ANY coding task, check if a relevant skill exists:
+
+1. **Analyze** the user's request — extract key technologies, patterns, or domains
+2. **Search** `skills-compact.json` for matching skill names/descriptions
+3. **Suggest** top 1-3 matching skills with name and category
+4. **Load** on user confirmation — read full skill from `skills/{name}/SKILL.md`
+
+## Skill Categories
+
+| Code | Category | Examples |
+|------|----------|----------|
+| `fe` | Frontend | react, vue, nextjs, tailwind, ui/ux |
+| `be` | Backend | node, express, nestjs, fastapi, api |
+| `db` | Database | postgres, mysql, mongodb, redis, prisma |
+| `ai` | AI/ML | llm, agents, rag, mcp, embeddings |
+| `ops` | DevOps | docker, k8s, ci/cd, aws, terraform |
+| `test` | Testing | jest, playwright, tdd, e2e |
+| `sec` | Security | auth, oauth, jwt, owasp, pentest |
+| `git` | Git/Workflow | pr, review, commit, branching |
+| `mob` | Mobile | react-native, flutter, ios, android |
+| `py` | Python | django, flask, fastapi, pandas |
+| `go` | Golang | gin, echo, fiber, concurrency |
+
+## How to Search
+
+1. Read `skills-compact.json` — format: `{ "skills": { "name": { "c": "category", "d": "description" } } }`
+2. Match skills whose name or description contains user's keywords
+3. If no direct match, suggest skills from the matching category
+4. On confirmation, read `skills/{skill-name}/SKILL.md`
+
+## Auto-Activate Triggers
+
+| User says... | Suggest skill |
+|--------------|---------------|
+| "create PR", "pull request" | /git-advanced-workflows |
+| "code review" | /code-review |
+| "write tests", "add tests" | /test-master |
+| "fix bug", "debug" | /systematic-debugging |
+| "learn", "teach me" | /learn |
+| "react component" | /react-expert |
+| "nextjs", "next.js" | /nextjs-best-practices |
+| "docker", "container" | /docker-expert |
+| "api design" | /api-design-principles |
+| "database schema" | /database-design |
+| "authentication", "auth" | /auth-implementation-patterns |
+| "mcp server" | /mcp-developer |
+
+## Rules
+
+1. **Don't auto-load** — always ask before loading a skill
+2. **Max 3 suggestions** — don't overwhelm user
+3. **Be concise** — one-line per skill suggestion
+4. **Remember context** — if user said "none", don't suggest again for same task
+5. **On-demand only** — only read full SKILL.md when user confirms

package/rules/base/command-routing.md

@@ -0,0 +1,58 @@
+# Command Routing Guide
+
+> Help Claude choose the right command and execution mode for each task.
+
+## Decision Tree
+
+```
+Is this a learning/educational request?
+  → /learn
+
+Is this brainstorming/ideation only (no code)?
+  → /brainstorm
+
+Is this just planning (no implementation)?
+  → /plan
+
+Is this a bug fix?
+  → /fix (simple) or /fix:hard (complex)
+
+Is this a small, well-defined task?
+  → /cook:fast
+
+Is this a medium task with clear requirements?
+  → /cook:auto (auto: plan → code → commit)
+  → OR /plan → /code (manual control)
+
+Is this a complex, full-lifecycle feature?
+  → /cook:hard (includes brainstorm+research+plan+code+test+review)
+  → OR /brainstorm → /plan → /code (manual, more control)
+```
+
+## Anti-Patterns
+
+- **NEVER** chain `/brainstorm` → `/plan` before `/cook:hard` — it already includes both internally, causing duplicate work
+- **NEVER** use `/cook:hard` for trivial fixes — overkill, wastes context
+- **NEVER** use `/cook:fast` for complex features — skips research/design, leads to rework
+
+## Command Reference
+
+| Command | Complexity | Multi-Agent | Best For |
+|---------|-----------|-------------|----------|
+| `/cook:fast` | Low | Light (scouter, engineer) | Well-defined small tasks |
+| `/cook` | Medium | Yes (full team) | Standard feature work |
+| `/cook:auto` | Medium | Yes (plan → code → git) | Autonomous implementation |
+| `/cook:hard` | High | Full (8 phases, all agents) | Complex features from scratch |
+| `/brainstorm` | N/A | No | Ideation, design exploration |
+| `/plan` | N/A | Optional (researcher) | Creating implementation plans |
+| `/code` | Medium | Yes (tester, reviewer) | Executing an existing plan |
+| `/learn` | N/A | No | Interactive tutorials |
+| `/fix` | Low | No | Quick bug fixes |
+| `/fix:hard` | Medium | Yes (debugger, tester) | Complex debugging |
+
+## When to Suggest Skills
+
+After choosing the right command, check if a domain-specific skill would help:
+- User says "react" → suggest `/react-expert` skill alongside chosen command
+- User says "auth" → suggest `/auth-implementation-patterns` skill
+- See `auto-skill.md` for full detection flow

package/rules/base/context-checkpoint.md

@@ -0,0 +1,38 @@
+# Context Checkpoint
+
+Auto-save session state to `.claude/sessions/` for context recovery.
+
+## When to Checkpoint
+After completing a subtask: implementing a feature step, running tests, phase transitions,
+receiving Task agent results, making key decisions.
+Do NOT checkpoint per individual file edit — wait until the subtask is complete.
+
+## Skip Checkpoint
+Simple Q&A, exploration reads, brainstorming, tasks completing in < 3 steps.
+
+## Protocol
+1. First checkpoint → ensure `.claude/sessions` is covered by `.gitignore`
+   (skip if `.claude/` or `.claude/sessions` already in gitignore), then create
+   `.claude/sessions/{YYMMDD-HHMM-desc}.md`
+2. Include `branch:{branch}` in header if in a git repo. Omit if not git.
+3. Update same file at each subsequent trigger. Silent — don't announce.
+4. Keep each section to 10 items max. Summarize older items if needed.
+5. On task completion → delete the checkpoint file.
+
+## Recovery
+If you recall working on a task but notice gaps in your prior context (earlier messages
+seem compressed or summarized), check `.claude/sessions/` for a matching checkpoint
+to restore state. Verify checkpoint has a `#` header and `## Next Action` before using.
+Say: "Resumed from checkpoint. Continuing..."
+Do NOT auto-load checkpoints in a fresh session — use `/recover` for cross-session.
+
+## Format
+```
+# {desc} | {command} | {phase} | branch:{branch}
+## Plan — {path or "none"}
+## Done — {bullets}
+## Pending — {bullets}
+## Decisions — {bullets}
+## Next Action — {exact step}
+## Files — Modified: {list} | Remaining: {list}
+```

package/rules-index.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "generatedAt": "2026-02-27T15:08:44.475Z",
+  "generatedAt": "2026-02-28T03:44:29.823Z",
   "templates": {
     "dart": {
       "path": "templates/dart/rules",

package/scripts/organize-rules.js

@@ -109,6 +109,7 @@ function organizeRules() {
   const stats = {};
 
   for (const ruleDir of rulesDirs) {
+    if (ruleDir === 'base') continue; // base rules handled by createBaseTemplate
     const srcDir = path.join(RULES_DIR, ruleDir);
     const tech = RULES_MAPPING[ruleDir] || ruleDir;
     const destDir = path.join(TEMPLATES_DIR, tech, 'rules', ruleDir);
@@ -171,6 +172,14 @@ function createBaseTemplate() {
   }
 
   console.log('  Created base template with essential hooks');
+
+  // Copy base rules from rules/base/ to templates/base/rules/
+  const baseRulesSource = path.join(RULES_DIR, 'base');
+  const baseRulesDest = path.join(baseDir, 'rules');
+  if (fs.existsSync(baseRulesSource)) {
+    const count = copyDir(baseRulesSource, baseRulesDest);
+    console.log(`  Copied ${count} base rules`);
+  }
 }
 
 /**

package/skills-graph.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "version": 2,
-    "lastUpdated": "2026-02-27",
+    "lastUpdated": "2026-02-28",
     "stats": {
       "totalSkills": 1127,
       "graphedSkills": 1070,

package/templates/base/rules/auto-skill.md

@@ -4,14 +4,14 @@
 
 ## When to Activate
 
-Before starting ANY coding task, you SHOULD check if a relevant skill exists:
+Before starting ANY coding task, check if a relevant skill exists:
 
-1. **Analyze the user's request** - Extract key technologies, patterns, or domains
-2. **Check compact index** - Read `skills-compact.json` (~20KB) for skill names and categories
-3. **Suggest to user** - Present top 1-3 matching skills
-4. **Load on-demand** - When user confirms, read full skill from `skills/{name}/SKILL.md`
+1. **Analyze** the user's request — extract key technologies, patterns, or domains
+2. **Search** `skills-compact.json` for matching skill names/descriptions
+3. **Suggest** top 1-3 matching skills with name and category
+4. **Load** on user confirmation — read full skill from `skills/{name}/SKILL.md`
 
-## Quick Reference: Skill Categories
+## Skill Categories
 
 | Code | Category | Examples |
 |------|----------|----------|
@@ -27,69 +27,15 @@ Before starting ANY coding task, you SHOULD check if a relevant skill exists:
 | `py` | Python | django, flask, fastapi, pandas |
 | `go` | Golang | gin, echo, fiber, concurrency |
 
-## Detection Flow
-
-```
-User Request → Extract keywords (react, auth, test, etc.)
-                    ↓
-            Read skills-compact.json
-                    ↓
-            Match skill names containing keywords
-                    ↓
-            Found? → Suggest: "I found /skill-name. Use it?"
-              ↓ No
-            Check category (fe, be, ai, etc.)
-                    ↓
-            Suggest skills in that category
-```
-
 ## How to Search
 
-### Step 1: Read Compact Index
-```
-Read: .claude/skills-compact.json
-Format: { "_categories": {...}, "skills": { "skill-name": { "c": "category", "d": "short description" } } }
-Note: Some skills may be just a category string if no description available.
-```
-
-### Step 2: Match by Name/Keyword
-Look for skills whose name OR description contains user's keywords:
-- User says "react" → find skills with "react" in name
-- User says "authentication" → find "auth" skills
-- User says "docker" → find "docker" skills
-
-### Step 3: Load Full Skill
-When user confirms, read the full skill:
-```
-Read: .claude/skills/{skill-name}/SKILL.md
-```
-
-## Suggestion Format
-
-**Single match:**
-```
-I found a skill that might help:
-
-📌 /skill-name - [category]
-
-Load this skill? It has specialized patterns for your task.
-```
-
-**Multiple matches (max 3):**
-```
-I found skills that might help:
-
-1. /skill-1 - [category]
-2. /skill-2 - [category]
-3. /skill-3 - [category]
-
-Which one should I use? (or "none" to proceed without)
-```
+1. Read `skills-compact.json` — format: `{ "skills": { "name": { "c": "category", "d": "description" } } }`
+2. Match skills whose name or description contains user's keywords
+3. If no direct match, suggest skills from the matching category
+4. On confirmation, read `skills/{skill-name}/SKILL.md`
 
 ## Auto-Activate Triggers
 
-Some patterns should auto-suggest specific skills:
-
 | User says... | Suggest skill |
 |--------------|---------------|
 | "create PR", "pull request" | /git-advanced-workflows |
@@ -105,36 +51,10 @@ Some patterns should auto-suggest specific skills:
 | "authentication", "auth" | /auth-implementation-patterns |
 | "mcp server" | /mcp-developer |
 
-## Important Rules
-
-1. **Don't auto-load** - Always ask before loading a skill
-2. **Max 3 suggestions** - Don't overwhelm user
-3. **Be concise** - One-line per skill
-4. **Remember context** - If user said "none", don't suggest again for same task
-5. **On-demand loading** - Only read full SKILL.md when user confirms
-6. **Core commands available** - /learn, /react-expert, /docker-expert, etc. are pre-loaded
-
-## File Locations
-
-| File | Purpose | Size |
-|------|---------|------|
-| `skills-compact.json` | Quick lookup index | ~20KB |
-| `skills/{name}/SKILL.md` | Full skill content | varies |
-| `commands/*.md` | Core commands (pre-loaded) | ~400KB |
-
-## Example Interaction
-
-**User:** "Help me add JWT authentication to my Express API"
-
-**Claude:** (reads skills-compact.json, finds "auth-implementation-patterns")
-```
-I found a skill that matches your task:
-
-📌 /auth-implementation-patterns - security
-
-This skill has JWT, OAuth2, and session patterns. Load it?
-```
-
-**User:** "yes"
+## Rules
 
-**Claude:** (reads skills/auth-implementation-patterns/SKILL.md and applies it)
+1. **Don't auto-load** — always ask before loading a skill
+2. **Max 3 suggestions** — don't overwhelm user
+3. **Be concise** — one-line per skill suggestion
+4. **Remember context** — if user said "none", don't suggest again for same task
+5. **On-demand only** — only read full SKILL.md when user confirms

package/templates/base/rules/command-routing.md

@@ -50,19 +50,6 @@ Is this a complex, full-lifecycle feature?
 | `/fix` | Low | No | Quick bug fixes |
 | `/fix:hard` | Medium | Yes (debugger, tester) | Complex debugging |
 
-## Multi-Agent Phases in /cook:hard
-
-```
-Phase 1: brainstormer  → Requirements discovery
-Phase 2: researcher    → Best practices research
-Phase 3: scouter       → Codebase analysis
-Phase 4: designer      → UI/UX design (if needed)
-Phase 5: planner       → Implementation plan
-Phase 6: tech-lead     → Routes to specialist engineers
-Phase 7: tester        → Testing
-Phase 8: reviewer      → Code review
-```
-
 ## When to Suggest Skills
 
 After choosing the right command, check if a domain-specific skill would help:

package/templates/base/rules/context-checkpoint.md

@@ -0,0 +1,38 @@
+# Context Checkpoint
+
+Auto-save session state to `.claude/sessions/` for context recovery.
+
+## When to Checkpoint
+After completing a subtask: implementing a feature step, running tests, phase transitions,
+receiving Task agent results, making key decisions.
+Do NOT checkpoint per individual file edit — wait until the subtask is complete.
+
+## Skip Checkpoint
+Simple Q&A, exploration reads, brainstorming, tasks completing in < 3 steps.
+
+## Protocol
+1. First checkpoint → ensure `.claude/sessions` is covered by `.gitignore`
+   (skip if `.claude/` or `.claude/sessions` already in gitignore), then create
+   `.claude/sessions/{YYMMDD-HHMM-desc}.md`
+2. Include `branch:{branch}` in header if in a git repo. Omit if not git.
+3. Update same file at each subsequent trigger. Silent — don't announce.
+4. Keep each section to 10 items max. Summarize older items if needed.
+5. On task completion → delete the checkpoint file.
+
+## Recovery
+If you recall working on a task but notice gaps in your prior context (earlier messages
+seem compressed or summarized), check `.claude/sessions/` for a matching checkpoint
+to restore state. Verify checkpoint has a `#` header and `## Next Action` before using.
+Say: "Resumed from checkpoint. Continuing..."
+Do NOT auto-load checkpoints in a fresh session — use `/recover` for cross-session.
+
+## Format
+```
+# {desc} | {command} | {phase} | branch:{branch}
+## Plan — {path or "none"}
+## Done — {bullets}
+## Pending — {bullets}
+## Decisions — {bullets}
+## Next Action — {exact step}
+## Files — Modified: {list} | Remaining: {list}
+```