@nano-step/skill-manager 5.2.2 → 5.4.0

package/skills/feature-analysis/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: feature-analysis
+description: "Deep code analysis of any feature or service before writing docs, diagrams, or making changes. Enforces read-everything-first discipline. Traces exact execution paths, data transformations, guard clauses, bugs, and gaps between existing docs and actual code. Produces a validated Mermaid diagram and structured analysis output. Language and framework agnostic."
+compatibility: "OpenCode"
+metadata:
+  version: "2.0.0"
+tools:
+  required:
+    - Read (every file in the feature)
+    - Bash (find all files, run mermaid validator)
+  uses:
+    - mermaid-validator skill (validate any diagram produced)
+triggers:
+  - "analyze [feature]"
+  - "how does X work"
+  - "trace the flow of"
+  - "understand X"
+  - "what does X do"
+  - "deep dive into"
+  - "working on X - understand it first"
+  - "update docs/brain for"
+---
+
+# Feature Analysis Skill
+
+A disciplined protocol for deeply analyzing any feature in any codebase before producing docs, diagrams, or making changes. Framework-agnostic. Language-agnostic.
+
+---
+
+## The Core Rule
+
+**READ EVERYTHING. PRODUCE NOTHING. THEN SYNTHESIZE.**
+
+Do not write a single diagram node, doc line, or description until every file in the feature has been read. Every time you produce output before reading all files, you will miss something.
+
+---
+
+## Phase 1: Discovery — Find Every File
+
+Before reading anything, map the full file set.
+
+```bash
+# Find all source files for the feature
+find <feature-dir> -type f | sort
+
+# Check imports to catch shared utilities, decorators, helpers
+grep -r "import\|require" <feature-dir> | grep -v node_modules | sort -u
+```
+
+**Read in dependency order (bottom-up — foundations first):**
+
+1. **Entry point / bootstrap** — port, env vars, startup config
+2. **Schema / model files** — DB schema, columns, nullable, indexes, types
+3. **Utility / helper files** — every function, every transformation, every constant
+4. **Decorator / middleware files** — wrapping logic, side effects, return value handling
+5. **Infrastructure services** — cache, lock, queue, external connections
+6. **Core business logic** — the main service/handler files
+7. **External / fetch services** — HTTP calls, filters applied, error handling
+8. **Entry controllers / routers / handlers** — HTTP method, route, params, return
+9. **Wiring files** — module/DI config, middleware registration
+
+**Do not skip any file. Do not skim.**
+
+---
+
+## Phase 2: Per-File Checklist
+
+For each file, answer these questions before moving to the next.
+
+### Entry point / bootstrap
+- [ ] What port or address? (default? env override?)
+- [ ] Any global middleware, pipes, interceptors, or lifecycle hooks?
+
+### Schema / model files
+- [ ] Table/collection name
+- [ ] Every field: type, nullable, default, constraints, indexes
+- [ ] Relations / references to other entities
+
+### Utility / helper files
+- [ ] Every exported function — what does it do, step by step?
+- [ ] For transformations: what inputs? what outputs? what edge cases handled?
+- [ ] Where is this function called? (grep for usages)
+- [ ] How many times is it called within a single method? (once per batch? once per item?)
+
+### Decorator / middleware files
+- [ ] What does it wrap?
+- [ ] What side effects before / after the original method?
+- [ ] **Does it `return` the result of the original method?** (missing `return` = silent discard bug)
+- [ ] Does it use try/finally? What runs in finally?
+- [ ] What happens on the early-exit path?
+
+### Core business logic files
+- [ ] Every method: signature, return type
+- [ ] For each method: trace every line — no summarizing
+- [ ] Accumulator variables — where initialized, where incremented, where returned
+- [ ] Loop structure: sequential or parallel?
+- [ ] Every external call: what service/module, what args, what returned
+- [ ] Guard clauses: every early return / continue / throw
+- [ ] Every branch in conditionals
+
+### External / fetch service files
+- [ ] Exact URLs or endpoints (hardcoded or env?)
+- [ ] Filters applied to response data (which calls filter, which don't?)
+- [ ] Error handling on external calls
+
+### Entry controllers / routers / handlers
+- [ ] HTTP method (GET vs POST — don't assume)
+- [ ] Route path
+- [ ] What core method is called?
+- [ ] What is returned?
+
+### Wiring / module files
+- [ ] What is imported / registered?
+- [ ] What is exported / exposed?
+
+---
+
+## Phase 3: Execution Trace
+
+After reading all files, produce a numbered step-by-step trace of the full execution path. This is not prose — it is a precise trace.
+
+**Format:**
+```
+1. [HTTP METHOD] /route → HandlerName.methodName()
+2. HandlerName.methodName() → ServiceName.methodName()
+3. @DecoratorName: step A (e.g. acquire lock, check cache)
+4.   → if condition X: early return [what is returned / not returned]
+5. ServiceName.methodName():
+6.   step 1: call externalService.fetchAll() → parallel([fetchA(), fetchB()])
+7.     fetchA(): GET https://... → returns all items (no filter)
+8.     fetchB(): GET https://... → filter(x => x.field !== null) → returns filtered
+9.   step 2: parallel([processItems(a, 'typeA'), processItems(b, 'typeB')])
+10. processItems(items, type):
+11.   init: totalUpdated = 0, totalInserted = 0
+12.   for loop (sequential): i = 0 to items.length, step batchSize
+13.     batch = items.slice(i, i + batchSize)
+14.     { updated, inserted } = await processBatch(batch)
+15.     totalUpdated += updated; totalInserted += inserted
+16.   return { total: items.length, updated: totalUpdated, inserted: totalInserted }
+17. processBatch(batch):
+18.   guard: if batch.length === 0 → return { updated: 0, inserted: 0 }
+19.   step 1: names = batch.map(item => transform(item.field))   ← called ONCE per batch
+20.   step 2: existing = repo.find(WHERE field IN names)
+21.   step 3: map = existing.reduce(...)
+22.   step 4: for each item in batch:
+23.     value = transform(item.field)   ← called AGAIN per item
+24.     ...decision tree...
+25.   repo.save(itemsToSave)
+26.   return { updated, inserted }
+27. @DecoratorName finally: releaseLock()
+28. BUG: decorator does not return result → caller receives undefined
+```
+
+**Key things to call out in the trace:**
+- When a utility function is called more than once (note the count and context)
+- Every accumulator variable (where init, where increment, where return)
+- Every guard clause / early exit
+- Sequential vs parallel (for loop vs Promise.all / asyncio.gather / goroutines)
+- Any discarded return values
+
+---
+
+## Phase 4: Data Transformations Audit
+
+For every utility/transformation function used:
+
+| Function | What it does (step by step) | Called where | Called how many times |
+|----------|----------------------------|--------------|----------------------|
+| `transformFn(x)` | 1. step A 2. step B 3. step C | methodName | TWICE: once in step N (batch), once per item in loop |
+
+---
+
+## Phase 5: Gap Analysis — Docs vs Code
+
+Compare existing docs/brain files against what the code actually does:
+
+| Claim in docs | What code actually does | Verdict |
+|---------------|------------------------|---------|
+| "POST /endpoint" | `@Get()` in controller | ❌ Wrong |
+| "Port 3000" | `process.env.PORT \|\| 4001` in entrypoint | ❌ Wrong |
+| "function converts X" | Also does Y (undocumented) | ⚠️ Incomplete |
+| "returns JSON result" | Decorator discards return value | ❌ Bug |
+
+---
+
+## Phase 6: Produce Outputs
+
+Only now, after phases 1–5 are complete, produce:
+
+### 6a. Structured Analysis Document
+
+```markdown
+## Feature Analysis: [Feature Name]
+Repo: [repo] | Date: [date]
+
+### Files Read
+- `path/to/controller.ts` — entry point, GET /endpoint, calls ServiceA.run()
+- `path/to/service.ts` — core logic, orchestrates fetch + batch loop
+- [... every file ...]
+
+### Execution Trace
+[numbered trace from Phase 3]
+
+### Data Transformations
+[table from Phase 4]
+
+### Guard Clauses & Edge Cases
+- processBatch: empty batch guard → returns {0,0} immediately
+- fetchItems: filters items where field === null
+- LockManager: if lock not acquired → returns void immediately (no error thrown)
+
+### Bugs / Issues Found
+- path/to/decorator.ts line N: `await originalMethod.apply(this, args)` missing `return`
+  → result is discarded, caller always receives undefined
+- [any others]
+
+### Gaps: Docs vs Code
+[table from Phase 5]
+
+### Files to Update
+- [ ] `.agents/_repos/[repo].md` — update port, endpoint method, transformation description
+- [ ] `.agents/_domains/[domain].md` — if architecture changed
+```
+
+### 6b. Mermaid Diagram
+
+Write the diagram. Then **immediately run the validator before doing anything else.**
+
+If you have the mermaid-validator skill:
+```bash
+node /path/to/project/scripts/validate-mermaid.mjs [file.md]
+```
+
+Otherwise validate manually — common syntax errors:
+- Labels with `()` must be wrapped in `"double quotes"`: `A["method()"]`
+- No `\n` in node labels — use `<br/>` or shorten
+- No HTML entities (`&amp;`, `&gt;`) in labels — use literal characters
+- `end` is a reserved word in Mermaid — use `END` or `done` as node IDs
+
+If errors → fix → re-run. Do not proceed until clean.
+
+**Diagram must include:**
+- Every step from the execution trace
+- Data transformation nodes (show what the function does, not just its name)
+- Guard clauses as decision nodes
+- Parallel vs sequential clearly distinguished
+- Bugs annotated inline (e.g. "BUG: result discarded")
+
+### 6c. Doc / Brain File Updates
+
+Update relevant docs with:
+- Corrected facts (port, endpoint method, etc.)
+- The validated Mermaid diagram
+- Data transformation table
+- Known bugs section
+
+---
+
+## Anti-Patterns (What This Skill Prevents)
+
+| Anti-pattern | What gets missed | Rule violated |
+|---|---|---|
+| Drew diagram before reading utility files | Transformation called twice — not shown | READ EVERYTHING FIRST |
+| Trusted existing docs for endpoint method | GET vs POST wrong in docs | GAP ANALYSIS required |
+| Summarized service method instead of tracing | Guard clause (empty batch) missed | TRACE NOT SUMMARIZE |
+| Trusted existing docs for port/config | Wrong values | Verify entry point |
+| Read decorator without checking return | Silent result discard bug | RETURN VALUE AUDIT |
+| Merged H1/H2 paths into shared loop node | Sequential vs parallel distinction lost | TRACE LOOP STRUCTURE |
+| Assumed filter applies to all fetches | One fetch had no filter — skipped items | READ EVERY FETCH FILE |
+
+---
+
+## Quick Reference Checklist
+
+Before producing any output, verify:
+
+- [ ] Entry point read — port/address confirmed
+- [ ] All schema/model files read — every field noted
+- [ ] All utility files read — every transformation step documented
+- [ ] All decorator/middleware files read — return value audited
+- [ ] All core service files read — every method traced line by line
+- [ ] All fetch/external services read — filters noted (which have filters, which don't)
+- [ ] All controller/router/handler files read — HTTP method confirmed (not assumed)
+- [ ] All wiring/module files read — dependency graph understood
+- [ ] Utility functions: call count per method noted
+- [ ] All guard clauses documented
+- [ ] Accumulator variables traced (init → increment → return)
+- [ ] Loop structure confirmed (sequential vs parallel)
+- [ ] Existing docs compared against code (gap analysis done)
+- [ ] Mermaid diagram validated before saving

package/skills/feature-analysis/skill.json

@@ -0,0 +1,15 @@
+{
+    "name": "feature-analysis",
+    "version": "2.0.0",
+    "description": "Deep code analysis of any feature or service before writing docs, diagrams, or making changes. Enforces read-everything-first discipline with execution tracing, data transformation audits, and gap analysis.",
+    "compatibility": "OpenCode",
+    "agent": null,
+    "commands": [],
+    "tags": [
+        "analysis",
+        "code-review",
+        "documentation",
+        "mermaid",
+        "tracing"
+    ]
+}

package/skills/mermaid-validator/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: mermaid-validator
+description: "Validate and write correct Mermaid diagrams. Run the validator script before finalizing any .md file containing a mermaid block. Enforces syntax rules that prevent parse errors."
+compatibility: "OpenCode"
+metadata:
+  version: "2.0.0"
+tools:
+  required:
+    - bash (node scripts/validate-mermaid.mjs)
+---
+
+# Mermaid Validator Skill
+
+## MANDATORY WORKFLOW
+
+**Any time you write or edit a Mermaid diagram, you MUST:**
+
+1. Write the diagram
+2. Run the validator
+3. Fix any errors reported
+4. Re-run until clean
+
+**Never** mark a documentation task complete if the validator reports errors.
+
+---
+
+## Validator Script Setup (Per Project)
+
+This skill expects a zero-dependency Node.js validator script at `scripts/validate-mermaid.mjs` in the project root.
+
+If the script doesn't exist yet, create it — see the reference implementation in any project that has already set this up, or ask to scaffold it.
+
+```bash
+# Validate all markdown files (default: scans .agents/ directory)
+node scripts/validate-mermaid.mjs
+
+# Validate a specific file
+node scripts/validate-mermaid.mjs path/to/file.md
+
+# Validate a whole directory
+node scripts/validate-mermaid.mjs path/to/dir/
+```
+
+**Expected clean output:**
+```
+Scanned 12 file(s), 3 mermaid block(s).
+✅ All diagrams passed.
+```
+
+**Error output example:**
+```
+❌ path/to/file.md
+   Line 47 [no-literal-newline]: Literal \n inside node/edge label — use <br/> or rewrite as plain text
+   > B --> C[ServiceName.method\n@Decorator]
+```
+
+---
+
+## Mermaid Syntax Rules (Mandatory Reference)
+
+### ✅ Safe — No quoting needed
+```
+Letters, digits, spaces, hyphens, underscores, colons, slashes, dots, angle brackets
+```
+
+### ⚠️ Requires `"double quotes"` around the whole label
+| Character | Wrong | Right |
+|-----------|-------|-------|
+| Parentheses `()` | `A[label (detail)]` | `A["label (detail)"]` |
+| Percent `%` | `A[100%]` | `A["100%"]` |
+| Ampersand `&` | `A[foo & bar]` | `A["foo & bar"]` |
+| Hash `#` | `A[#tag]` | `A["#tag"]` |
+| At-sign `@` | `A[@lock]` | `A["@lock"]` |
+
+### ❌ Never use inside a diagram block
+| Pattern | Wrong | Fix |
+|---------|-------|-----|
+| Literal `\n` in label | `A[Line1\nLine2]` | `A["Line1<br/>Line2"]` or just `A[Line1 Line2]` |
+| HTML entities | `A[foo &amp; bar]` | `A["foo & bar"]` |
+| HTML numeric entities | `A[&#40;parens&#41;]` | `A["(parens)"]` |
+| Reserved word `end` as node ID | `end[task]` | `End[task]` |
+
+### Edge label quoting
+```
+A -- simple text --> B          ✅ fine
+A -- "text with (parens)" --> B ✅ quoted
+A -- text with (parens) --> B   ❌ breaks
+```
+
+### Node shape reference
+```
+A[Rectangle]
+A(Rounded)
+A([Stadium])        ← OK to have ( inside [ here — this is shape syntax
+A{Diamond}
+A[(Cylinder/DB)]
+A((Circle))
+A>Asymmetric]
+```
+
+### Mermaid entity codes (inside `"quoted"` labels only)
+```
+#40; = (    #41; = )    #35; = #    #37; = %
+```
+
+---
+
+## Writing a Mermaid Diagram — Checklist
+
+Before saving any diagram, mentally check each line:
+
+- [ ] No `\n` inside any label (bracket, brace, or paren)
+- [ ] No `&#NN;` or `&amp;` HTML entities
+- [ ] Any label containing `()` is wrapped in `"double quotes"`
+- [ ] Node IDs are alphanumeric + underscore only (no hyphens in ID itself)
+- [ ] No node ID named `end` (lowercase)
+- [ ] Edge labels containing special chars are `"quoted"`
+- [ ] Diagram has at least one node and one valid statement
+
+Then run the validator. If it passes, you're done.
+
+---
+
+## Common Diagram Patterns
+
+### Service method with decorator
+```mermaid
+flowchart TD
+    A[Controller] --> B["Service.method - @Decorator key ttl"]
+```
+Note: `@` is safe after the first non-@ character. Put the whole label in quotes to be safe.
+
+### Lock/cache decision
+```mermaid
+flowchart TD
+    A --> B{"Redis SET NX EX - key - TTL 1800s"}
+    B -- Lock held --> C([Return void])
+    B -- Lock acquired --> D[Continue]
+```
+
+### DB node (cylinder)
+```mermaid
+flowchart TD
+    A --> B[(database.table)]
+```
+
+### Parallel execution
+```mermaid
+flowchart TD
+    A["Promise.all"] --> B[Task 1]
+    A --> C[Task 2]
+```
+
+### Sequential batch loop
+```mermaid
+flowchart TD
+    A[Start loop] --> B["for i = 0 to items.length step batchSize"]
+    B --> C["batch = items.slice(i, i + batchSize)"]
+    C --> D["processBatch(batch)"]
+    D --> E{More batches?}
+    E -- Yes --> B
+    E -- No --> F[Return totals]
+```

package/skills/mermaid-validator/skill.json

@@ -0,0 +1,15 @@
+{
+    "name": "mermaid-validator",
+    "version": "2.0.0",
+    "description": "Validate and write correct Mermaid diagrams. Run the validator script before finalizing any .md file containing a mermaid block. Enforces syntax rules that prevent parse errors.",
+    "compatibility": "OpenCode",
+    "agent": null,
+    "commands": [],
+    "tags": [
+        "mermaid",
+        "validation",
+        "diagrams",
+        "documentation",
+        "syntax"
+    ]
+}

package/skills/nano-brain/AGENTS_SNIPPET.md

@@ -0,0 +1,46 @@
+<!-- OPENCODE-MEMORY:START -->
+<!-- Managed block - do not edit manually. Updated by: npx nano-brain init -->
+
+## Memory System (nano-brain)
+
+This project uses **nano-brain** for persistent context across sessions.
+
+### Quick Reference
+
+nano-brain supports two access methods. Try MCP first; if unavailable, use CLI.
+
+| I want to... | MCP Tool | CLI Fallback |
+|--------------|----------|--------------|
+| Recall past work on a topic | `memory_query("topic")` | `npx nano-brain query "topic"` |
+| Find exact error/function name | `memory_search("exact term")` | `npx nano-brain query "exact term"` |
+| Explore a concept semantically | `memory_vsearch("concept")` | `npx nano-brain query "concept"` |
+| Save a decision for future sessions | `memory_write("decision context")` | Create file in `~/.nano-brain/memory/` |
+| Check index health | `memory_status` | `npx nano-brain status` |
+
+### Session Workflow
+
+**Start of session:** Check memory for relevant past context before exploring the codebase.
+```
+# MCP (if available):
+memory_query("what have we done regarding {current task topic}")
+
+# CLI fallback:
+npx nano-brain query "what have we done regarding {current task topic}"
+```
+
+**End of session:** Save key decisions, patterns discovered, and debugging insights.
+```
+# MCP (if available):
+memory_write("## Summary\n- Decision: ...\n- Why: ...\n- Files: ...")
+
+# CLI fallback: create a markdown file
+# File: ~/.nano-brain/memory/YYYY-MM-DD-summary.md
+```
+
+### When to Search Memory vs Codebase
+
+- **"Have we done this before?"** → `memory_query` or `npx nano-brain query` (searches past sessions)
+- **"Where is this in the code?"** → grep / ast-grep (searches current files)
+- **"How does this concept work here?"** → Both (memory for past context + grep for current code)
+
+<!-- OPENCODE-MEMORY:END -->

package/skills/nano-brain/SKILL.md

@@ -0,0 +1,77 @@
+# nano-brain
+
+Persistent memory for AI coding agents. Hybrid search (BM25 + semantic + LLM reranking) across past sessions, codebase, notes, and daily logs.
+
+## Slash Commands
+
+| Command | When |
+|---------|------|
+| `/nano-brain-init` | First-time workspace setup |
+| `/nano-brain-status` | Health check, embedding progress |
+| `/nano-brain-reindex` | After branch switch, pull, or major changes |
+
+## When to Use Memory
+
+**Before work:** Recall past decisions, patterns, debugging insights, cross-session context.
+**After work:** Save key decisions, architecture choices, non-obvious fixes, domain knowledge.
+
+## Access Methods: MCP vs CLI
+
+nano-brain can be accessed via **MCP tools** (when the MCP server is configured) or **CLI** (always available).
+
+**Detection:** Try calling `memory_status` MCP tool first. If it fails with "MCP server not found", fall back to CLI.
+
+### MCP Tools (preferred when available)
+
+| Need | MCP Tool |
+|------|----------|
+| Exact keyword (error msg, function name) | `memory_search` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_search")` |
+| Conceptual ("how does auth work") | `memory_vsearch` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_vsearch")` |
+| Best quality, complex question | `memory_query` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_query")` |
+| Retrieve specific doc | `memory_get` / `memory_multi_get` |
+| Save insight or decision (append to daily log) | `memory_write` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_write")` |
+| Set/update a keyed memory (overwrites previous) | `memory_set` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_set")` |
+| Delete a keyed memory | `memory_delete` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_delete")` |
+| List all keyed memories | `memory_keys` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_keys")` |
+| Check health | `memory_status` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_status")` |
+| Rescan source files | `memory_index_codebase` |
+| Refresh all indexes | `memory_update` |
+
+### CLI Fallback (always available)
+
+When MCP server is not available, use the CLI via Bash tool:
+
+| Need | CLI Command |
+|------|-------------|
+| Best quality search (hybrid: BM25 + vector + reranking) | `npx nano-brain query "search terms"` |
+| Search with collection filter | `npx nano-brain query "terms" -c codebase` |
+| Search with more/fewer results | `npx nano-brain query "terms" -n 20` |
+| Show full content of results | `npx nano-brain query "terms" --full` |
+| Check health & stats | `npx nano-brain status` |
+| Initialize workspace | `npx nano-brain init --root=/path/to/workspace` |
+| Generate embeddings | `npx nano-brain embed` |
+| Harvest sessions | `npx nano-brain harvest` |
+| List collections | `npx nano-brain collection list` |
+
+**CLI limitations vs MCP:**
+- CLI only has `query` (unified hybrid search) — no separate `search` (BM25-only) or `vsearch` (vector-only)
+- CLI cannot `write` notes — use MCP or manually create files in `~/.nano-brain/memory/`
+- CLI cannot `get` specific docs by ID — use `query` with specific terms instead
+
+**Default:** Use `npx nano-brain query "..."` — it combines BM25 + vector + reranking for best results.
+
+## Collection Filtering
+
+Works with both MCP and CLI (`-c` flag):
+
+- `codebase` — source files only
+- `sessions` — past AI sessions only
+- `memory` — curated notes only
+- Omit — search everything (recommended)
+
+## Memory vs Native Tools
+
+Memory excels at **recall and semantics** — past sessions, conceptual search, cross-project knowledge.
+Native tools (grep, ast-grep, glob) excel at **precise code patterns** — exact matches, AST structure.
+
+**They are complementary.** Use both.

package/skills/nano-brain/skill.json

@@ -0,0 +1,15 @@
+{
+    "name": "nano-brain",
+    "version": "1.0.0",
+    "description": "Persistent memory for AI coding agents. Hybrid search (BM25 + semantic + LLM reranking) across past sessions, codebase, notes, and daily logs.",
+    "compatibility": "OpenCode",
+    "agent": null,
+    "commands": [],
+    "tags": [
+        "memory",
+        "persistence",
+        "search",
+        "context",
+        "sessions"
+    ]
+}