@opensassi/opencode 0.1.0 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # @opensassi/opencode
 
-Agent skill harness for AI-assisted software development. Delivers 12 domain-specific skills (system-design, git workflow, profiling, etc.) and supporting scripts as a standalone npm CLI package.
+Agent skill harness for AI-assisted software development. Delivers 13 domain-specific skills (system-design, git workflow, profiling, etc.) and supporting scripts as a standalone npm CLI package.
 
 ```
 npx @opensassi/opencode init
@@ -43,13 +43,14 @@ npx @opensassi/opencode help                     # Show help
 | `daily-evaluation` | Aggregate session evaluations into dashboards |
 | `git` | Rebase-based single-commit-per-session workflow |
 | `issue` | GitHub issue management |
-| `npm-optimizer` | Port an npm package to a C++ native addon |
+| `npm-optimizer` | Port an npm package to a C++ native addon — 100% test compatibility through profiling-driven iteration |
 | `opensassi` | Bootstrap a new project environment |
 | `profiler` | Linux perf profiling + flamegraphs |
 | `session-evaluation` | Generate structured session reports |
 | `skill-manager` | Create/revise skills interactively |
 | `system-design` | Interactive C++ spec authoring with diagrams |
 | `system-design-review` | Seven-expert panel audit of technical specs |
+| `npx` | Run npx commands in a target directory with automatic directory resolution |
 | `todo` | Create issues + debugging skills from session context |
 
 ## Package Contents
@@ -58,7 +59,7 @@ npx @opensassi/opencode help                     # Show help
 |-----------|----------|
 | `bin/` | CLI entry point (`opencode` binary) |
 | `lib/` | Programmatic API + command implementations |
-| `skills/` | 12 skill definitions (SKILL.md) + skill scripts |
+| `skills/` | 13 skill definitions (SKILL.md) + skill scripts |
 | `scripts/` | Artifact pipeline (extract, test, verify, check) + installers |
 | `AGENTS.md` | Agent harness instructions (appended by init) |
 | `skills-index.json` | Pre-built static skill/command index |

package/lib/commands/init.js

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { spawn } from 'node:child_process'
 import { resolveAgents, resolveSkill, PKG_ROOT } from '../util/paths.js'
 
 function readPackageAgents() {
@@ -114,4 +115,40 @@ export async function initCommand(args) {
       console.log('.opencode/skills/ already in .gitignore')
     }
   }
+
+  // === Post-write: handoff to opencode ===
+
+  if (process.env.OPENCODE === '1') {
+    console.log('\nFiles written. Use `skill opensassi` to continue within this session.')
+    return
+  }
+
+  await spawnOpencode(cwd)
+}
+
+async function spawnOpencode(cwd) {
+  const { spawnSync } = await import('node:child_process')
+  const platform = process.platform
+  const whichCmd = platform === 'win32' ? 'where' : 'command'
+  const whichArgs = platform === 'win32' ? ['opencode.cmd'] : ['-v', 'opencode']
+
+  const check = spawnSync(whichCmd, whichArgs, { stdio: 'ignore' })
+  if (check.status !== 0) {
+    console.log('\nopencode is not installed.\nInstall it, then run: opencode')
+    console.log('  curl -fsSL https://opencode.ai/install.sh | sh')
+    return
+  }
+
+  console.log('\nInitializing opensassi inside opencode...')
+  const child = spawn('opencode', ['run', '--print-logs', 'skill opensassi'], {
+    cwd,
+    stdio: 'inherit',
+    env: { ...process.env }
+  })
+  return new Promise((resolve) => {
+    child.on('exit', (code) => {
+      if (code !== 0) console.log(`\nopencode exited with code ${code}`)
+      resolve()
+    })
+  })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensassi/opencode",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Agent skill harness for opencode — bootstrap, system-design, git workflow, profiling, and more",
   "type": "module",
   "bin": {
@@ -37,4 +37,4 @@
     "playwright": "^1.60.0",
     "sharp": "^0.34.5"
   }
-}
+}

package/scripts/list-targets.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "${1:-.}" && pwd)"
+
+echo "["
+
+# 1. Project root
+echo "  {\"name\": \".\", \"path\": \"$ROOT\", \"type\": \"project-root\"}"
+
+# 2. external/ subdirectories
+sep=","
+if [ -d "$ROOT/external" ]; then
+  for dir in "$ROOT/external"/*/; do
+    [ -d "$dir" ] || continue
+    name="$(basename "$dir")"
+    abspath="$(cd "$dir" && pwd)"
+    echo "$sep"
+    echo -n "  {\"name\": \"$name\", \"path\": \"$abspath\", \"type\": \"external\"}"
+    sep=","
+  done
+fi
+
+# 3. packages/ workspace subdirectories (common in monorepos)
+if [ -d "$ROOT/packages" ]; then
+  for dir in "$ROOT/packages"/*/; do
+    [ -d "$dir" ] || continue
+    name="$(basename "$dir")"
+    abspath="$(cd "$dir" && pwd)"
+    echo "$sep"
+    echo -n "  {\"name\": \"$name\", \"path\": \"$abspath\", \"type\": \"workspace\"}"
+    sep=","
+  done
+fi
+
+# 4. src/ subdirectories (common in project dirs)
+if [ -d "$ROOT/src" ]; then
+  for dir in "$ROOT/src"/*/; do
+    [ -d "$dir" ] || continue
+    name="$(basename "$dir")"
+    abspath="$(cd "$dir" && pwd)"
+    echo "$sep"
+    echo -n "  {\"name\": \"$name\", \"path\": \"$abspath\", \"type\": \"project\"}"
+    sep=","
+  done
+fi
+
+echo ""
+echo "]"

package/skills/git/SKILL.md

@@ -40,11 +40,29 @@ Complete the current session: create a single atomic commit, rebase onto latest
 > **Ordering constraint**: Commit must be created *before* rebase so that rebase moves the single commit to the tip of main. The commit message must be obtained *before* the commit because it requires data from `generate` and `opencode session list`. The evaluation `.md` sidecar is written from the `generate` output (step 10) *after* the commit, so it reflects the final session state including any test-fix loops.
 
 **Process:**
+
+0. **Preflight session check**: Run `opencode session list`. Save the most recent session's full ID (with `ses_` prefix). Then check `ls -1 sessions/*.md 2>/dev/null` to list existing sidecar filenames.
+   - If the most recent session's noprefix ID already appears in an existing sidecar filename → the current session is NOT persisted yet. **ABORT** with: "Current session ID not found in session list. Session may not be persisted. Run `opencode` to enter the session first, or provide a session ID manually."
+   - Do not fabricate or improvise a session ID. Using a fake ID breaks traceability between commit messages, sidecar files, and session archives.
+
 1. **Stage all changes**: `git add -A`
 2. **Get evaluation title slug**: Load the `session-evaluation` skill via the `skill` tool, then instruct it to run `generate`. Extract the slug from the Session ID field of its output (e.g., `2026-05-11-testing-plan-revision`).
-3. **Get session ID**: Run `opencode session list` and identify the most recent session. Strip the `ses_` prefix to get the noprefix ID (e.g., `1e793e9b0ffeLqAjZOHtI8vy8v`).
+3. **Get session ID**: Run `opencode session list` and identify the most recent session whose noprefix ID has NOT been used in an existing sidecar filename. Strip the `ses_` prefix to get the noprefix ID (e.g., `1e793e9b0ffeLqAjZOHtI8vy8v`).
+
+3.5. **Validate session ID**:
+   a. Does the session ID start with `ses_` before stripping? If not → **ABORT**: "Session ID does not match expected `ses_` format."
+   b. Has this noprefix ID been used in an existing sidecar filename? Check `ls sessions/*-<noprefix>.md`. If it exists → **ABORT**: "Session ID has already been used in a previous archive."
+   c. Does `opencode export <session-id>` return valid JSON (non-zero bytes)? If not → **ABORT**: "Session ID is not exportable. The session may not be persisted."
+   d. If any check fails, do NOT proceed. Report the failure and stop.
 4. **Construct commit message**: `<title-slug>-<session-id-noprefix>` — this is identical to the session evaluation sidecar filename (e.g., `2026-05-11-testing-plan-revision-1e793e9b0ffeLqAjZOHtI8vy8v`).
 5. **Create commit**: `git commit -m "<commit-message>"`
+
+5.5. **Validate commit message**: Before proceeding to rebase, verify:
+   - `git log --oneline -1` shows the message as `<slug>-<noprefix>`
+   - The `<noprefix>` portion matches the session ID from step 3 (without `ses_`)
+   - A file `sessions/<message>.md` will be written in step 10 — confirm the path would be unique (not overwriting an existing file)
+   If any check fails → **ABORT** and report which constraint was violated. Do not proceed until the commit message is corrected.
+
 6. **Rebase onto main**: `git fetch origin && git rebase origin/main`
 7. **Handle conflicts**: If conflicts occur:
    - For each conflicted file, resolve manually (edit to correct state)

package/skills/npm-optimizer/SKILL.md

@@ -9,6 +9,22 @@ description: Port an existing npm package to a C++ native addon — preserve 100
 
 Senior systems engineer specializing in Node.js native addon development and performance optimization. Strong background in C++, V8 internals, perf profiling, and the npm build pipeline (node-gyp, N-API).
 
+## Context Architecture
+
+This skill is loaded **JIT at the head** of a sub-agent context. The permanent base (system-design skill + full spec tree) is always present in the tail.
+
+### Sub-Agent Loading Contracts
+
+Each phase loads skills in this deterministic order (head = last loaded, strongest attention). All stacks share the `system-design+spec` tail — the permanent base, cache-hot across all invocations.
+
+| Phase | Skill stack (head ← tail) |
+|-------|---------------------------|
+| Ceiling / Naive / Pivot / Micro / Shim / Report | `npm-optimizer` → `system-design+spec` |
+| Profile & Classify | `npm-optimizer` → `profiler` → `system-design+spec` |
+| Handoff to asm-optimizer | `npm-optimizer` → `asm-optimizer` → `system-design+spec` |
+
+The `system-design` skill with its spec tree is the permanent base loaded at startup. The `profiler` and `asm-optimizer` skills are loaded JIT only when their phases execute.
+
 ## On Activation
 
 1. Check that a target npm package name is available in context. If not, prompt.
@@ -19,13 +35,13 @@ Senior systems engineer specializing in Node.js native addon development and per
 
 ### `execute`
 
-Run the full port pipeline. Each phase must complete before the next begins. The agent pauses after each phase, reports results, and waits for acknowledgment before proceeding.
+Run the full port pipeline. Each phase runs sequentially. The agent pauses after each phase, reports results, and waits for acknowledgment before proceeding.
 
 ---
 
-**Phase 1 — Spec & Discovery**
+**Phase 1 — Discovery & Ceiling**
 
-Goal: Understand the original package's full surface area before writing any code.
+Goal: Understand the original package and validate that a C++ native addon is viable.
 
 1.1. Clone the target package into `external/<name>/`:
      ```
@@ -35,35 +51,14 @@ Goal: Understand the original package's full surface area before writing any cod
 1.2. Copy the original test suite to `test/orig/`. Run it against the original to
      establish a passing baseline. These tests must never be modified.
 
-1.3. Analyze the original source tree. For each source file, use the system-design
-     skill's spec workflow to produce a spec document. Group related files into
-     sub-modules. Output tree at:
-     ```
-     spec/original/
-     ├── <sub-module-1>/README.md
-     ├── <sub-module-2>/README.md
-     └── technical-specification.md    (root overview + data flow)
-     ```
-
-1.4. From the spec tree, extract:
-     - Full API surface: every exported function, its signature, and behavior.
-     - Edge cases: undefined properties, NaN, toJSON, circular refs, prototype chain.
-     - Data flow: how inputs map to outputs.
+1.3. The spec tree is generated using **system-design** (permanent base context):
+     - Run `generate from source` to produce the full spec tree of the original package.
+     - Extract from the spec tree: full API surface, edge cases, data flow.
+     - Design the C++ addon architecture: which functions go native vs stay in JS,
+       N-API boundary strategy, build pipeline.
+     - Generate implementation spec tree at `spec/implementation/`.
 
-1.5. **Validate the ceiling** — Before designing the C++ architecture, build the
-     cheapest possible pass-through: a minimal addon that takes a string blob,
-     copies it, and returns it. Measure its ops/sec via `npm run benchmark`.
-     This is the **upper bound** for any approach that uses this N-API profile
-     (one crossing in, one out). If this doesn't exceed the original's speed,
-     the entire approach is dead — reconsider at the JS/N-API design level.
-
-1.6. Design the C++ addon architecture:
-     - Which functions go native vs stay in JS wrapper.
-     - N-API boundary strategy (minimize crossings per call).
-     - Build pipeline (binding.gyp, node-addon-api, dependencies).
-
-1.7. Generate implementation spec tree at `spec/implementation/` mirroring the
-     original's structure, with cross-reference mappings.
+1.4. Run `assess-ceiling` to validate the approach is viable.
 
 ---
 
@@ -71,11 +66,7 @@ Goal: Understand the original package's full surface area before writing any cod
 
 Goal: Build the simplest C++ addon that passes 100% of `test/orig/*.js`.
 
-2.1. Scaffold project: `package.json`, `binding.gyp`, `src/`, `index.js`
-2.2. Implement the C++ module with the direct approach
-     (e.g., traverse values through N-API, build string in C++).
-2.3. Run `test/orig/` tests. Fix until all pass.
-2.4. Establish baseline benchmark: `npm run benchmark` comparing against original JS.
+Run `implement-naive`.
 
 ---
 
@@ -83,95 +74,188 @@ Goal: Build the simplest C++ addon that passes 100% of `test/orig/*.js`.
 
 Goal: Identify where time is actually going.
 
+Loading contract: `profiler` skill loaded at the head.
+
 3.1. Create `prof-harness.js` — tight loop exercising the main export.
-3.2. `perf record -F 199 --call-graph fp -o perf/baseline.profile.data node prof-harness.js`
-3.3. `perf report -i perf/baseline.profile.data --stdio -s overhead,symbol,dso`
-3.4. Classify samples into three tiers:
-     - **Tier 1 — Infrastructure**: V8 internals, N-API boundary, allocator.
-     - **Tier 2 — Our C++ logic**: string building, type dispatch, sorting.
-     - **Tier 3 — The original's work**: if we're still calling it.
-3.5. **Decision**: If Tier 1 > 30% of samples, mark as **architectural bottleneck**
-     and proceed to Phase 4A (pivot). Otherwise proceed to Phase 4B (micro-optimize).
+3.2. Use the loaded **profiler** skill's `profile` command to run `perf record`
+     and generate flamegraphs.
+3.3. Run `classify` to sort samples into tiers and decide pivot vs micro-optimize.
 
 ---
 
-**Phase 4A — Architectural Pivot**
+**Phase 4 — Optimize**
 
-Goal: Change the approach when the current architecture hits a fundamental ceiling.
+Goal: Improve performance based on classification results.
 
-4A.1. Identify the specific architectural cost (e.g., "200+ N-API crossings per call").
-4A.2. Design an alternative approach that eliminates this cost. Examples:
-      - "Let JSON.stringify do the work, then key-sort the blob in C++"
-      - "Batch N-API calls" / "Use raw V8 API instead of N-API"
-      - "Pre-allocate and reuse buffers across calls"
-4A.3. **Validate the hypothesis** — before implementing the full approach, build
-      the cheapest functional approximation (pass-through, stub). Measure it.
-      If the ceiling doesn't leave headroom over the original, reject this approach
-      and go back to 4A.2.
-4A.4. If validated: implement the full pivot approach. Run tests (100% pass).
-4A.5. Run benchmark. If target met, proceed to Phase 5.
-      If not, return to Phase 3 with new profile data.
+If Phase 3 classified as architectural (Tier 1 > 30%):
+- Run `pivot`
+
+If Phase 3 classified as micro-optimizable:
+- Run `micro-optimize`
+- After each round, check: are we approaching the ceiling with diminishing returns?
+  If so, run `assess-handoff` to evaluate dropping to asm-optimizer.
 
 ---
 
-**Phase 4B — Micro-Optimize**
+**Phase 5 — Compatibility Shim**
 
-Goal: Attack specific C++ hotspots identified in Phase 3.
+Goal: Handle edge cases where the implementation differs from the original.
 
-4B.1. For each Tier-2 function, sorted by self% descending:
-      - Read the source code of the function.
-      - Identify the specific operation consuming time
-        (e.g., `std::ostringstream`, repeated allocation, branch-heavy loop).
-      - Apply one targeted fix.
-      - Rebuild, run tests, benchmark.
-      - If gain >= 5%: keep, move to next function.
-      - If gain < 5%: revert, try next hypothesis for this function.
-4B.2. **Three strikes rule**: if three consecutive fixes at this function
-      each yield <5%, stop micro-optimizing. Re-run Phase 3 and check
-      Tier 1 fraction. If it grew, proceed to Phase 4A.
-4B.3. When all Tier-2 functions are exhausted: re-run Phase 3.
-      If Tier 1 is now dominant, proceed to Phase 4A.
+Run `shim`.
 
 ---
 
-**Phase 5 — Compatibility Shim & Documentation**
+**Phase 6 — Report**
 
-Goal: Handle edge cases where the implementation differs from the original.
+Goal: Produce the final deliverable.
 
-5.1. Compare output of original vs implementation for:
-      - All `test/orig/` cases (must pass).
-      - Edge cases: function-valued properties, undefined, toJSON,
-        prototype-chain access, Symbol-keyed properties.
-5.2. For any behavioral difference: add JS wrapper logic in `index.js`
-      (e.g., preprocess step for function→{} conversion).
-      Document the difference in `spec/cross-reference.md` with rationale.
-5.3. Generate `test/new/` tests covering implementation-specific behavior.
-5.4. Update `spec/cross-reference.md` with final benchmark deltas.
+Run `report`.
 
 ---
 
-**Phase 6 — Report**
+### `assess-ceiling`
 
-Goal: Produce the final deliverable.
+Before designing the C++ architecture, build the cheapest possible pass-through:
+a minimal addon that takes a string blob, copies it, and returns it.
+Measure its ops/sec via `npm run benchmark`.
 
-6.1. Generate comparison table:
-     ```
-     | Implementation          | Ops/sec | Relative |
-     |-------------------------|---------|----------|
-     | Original JS             | X       | 1.0x     |
-     | C++ addon               | Y       | Y/X      |
-     | Pass-through (ceiling)  | Z       | Z/X      |
-     ```
-6.2. Archive final profile: `cp perf/baseline.profile.data perf/baseline/profiles/final.profile.data`
-6.3. Print the full report inline: benchmark numbers, profile summary, spec cross-reference path,
-      and a list of known behavioral differences (if any).
+This is the **upper bound** for any approach using this N-API profile
+(one crossing in, one out). If this doesn't exceed the original's speed,
+the entire approach is dead — reconsider at the JS/N-API design level.
+
+Output:
+```
+Ceiling pass-through: 104,866 ops/sec
+Original JS:          33,199 ops/sec
+Verdict: VIABLE (3.16x headroom)
+```
+
+### `implement-naive`
+
+Build the simplest C++ addon that passes 100% of `test/orig/*.js`.
+
+1. Scaffold project: `package.json`, `binding.gyp`, `src/`, `index.js`
+2. Implement the C++ module with the direct approach
+   (e.g., traverse values through N-API, build string in C++).
+3. Run `test/orig/` tests. Fix until all pass.
+4. Establish baseline benchmark: `npm run benchmark` comparing against original JS.
+
+### `classify`
+
+Load `prof-harness.js` perf data and sort samples into three tiers:
+
+- **Tier 1 — Infrastructure**: V8 internals, N-API boundary, allocator.
+- **Tier 2 — Our C++ logic**: string building, type dispatch, sorting.
+- **Tier 3 — The original's work**: if we're still calling it.
+
+**Decision**: If Tier 1 > 30% of samples, mark as **architectural bottleneck**
+and proceed to `pivot`. Otherwise proceed to `micro-optimize`.
+
+### `pivot`
+
+Change the architectural approach when the current architecture hits a fundamental ceiling.
+
+1. Identify the specific architectural cost (e.g., "200+ N-API crossings per call").
+2. Design an alternative approach that eliminates this cost. Examples:
+   - "Let JSON.stringify do the work, then key-sort the blob in C++"
+   - "Batch N-API calls" / "Use raw V8 API instead of N-API"
+   - "Pre-allocate and reuse buffers across calls"
+3. **Validate the hypothesis** — before implementing the full approach, build
+   the cheapest functional approximation (pass-through, stub). Measure it.
+   If the ceiling doesn't leave headroom over the original, reject this approach
+   and try another.
+4. If validated: implement the full pivot approach. Run tests (100% pass).
+5. Run `bench`. If target met, proceed. If not, return to Phase 3 with new profile data.
+
+### `micro-optimize`
+
+Attack specific C++ hotspots identified during profiling.
+
+For each Tier-2 function, sorted by self% descending:
+- Read the source code of the function.
+- Identify the specific operation consuming time
+  (e.g., `std::ostringstream`, repeated allocation, branch-heavy loop).
+- Apply one targeted fix.
+- Rebuild, run tests, benchmark.
+- If gain >= 5%: keep, move to next function.
+- If gain < 5%: revert, try next hypothesis for this function.
+
+**Three strikes rule**: if three consecutive fixes at this function
+each yield <5%, stop micro-optimizing. Re-profile. If Tier 1
+fraction grew, proceed to `pivot`. If Tier 2 is exhausted and still
+not at ceiling, proceed to `assess-handoff`.
+
+When all Tier-2 functions are exhausted: re-run profiling.
+If Tier 1 is now dominant, proceed to `pivot`.
+
+### `shim`
+
+Handle edge cases where the implementation differs from the original.
+
+1. Compare output of original vs implementation for:
+   - All `test/orig/` cases (must pass).
+   - Edge cases: function-valued properties, undefined, toJSON,
+     prototype-chain access, Symbol-keyed properties.
+2. For any behavioral difference: add JS wrapper logic in `index.js`
+   (e.g., preprocess step for function->{} conversion).
+   Document the difference in `spec/cross-reference.md` with rationale.
+3. Generate `test/new/` tests covering implementation-specific behavior.
+4. Update `spec/cross-reference.md` with final benchmark deltas.
+
+### `bench`
+
+Run benchmark comparing current implementation against the original JS.
+
+Output:
+```
+| Implementation          | Ops/sec | Relative |
+|-------------------------|---------|----------|
+| Original JS             | X       | 1.0x     |
+| C++ addon               | Y       | Y/X      |
+| Pass-through (ceiling)  | Z       | Z/X      |
+```
+
+### `assess-handoff`
+
+Evaluate whether the remaining bottleneck is in our C++ logic (Tier 2)
+and has reached diminishing returns. If so, spawn a sub-agent with
+**asm-optimizer** loaded to perform assembly/SIMD-level optimization.
+
+**Gate criteria** (all must be true):
+- Tier 2 is the dominant bottleneck (>50% of remaining samples after pivots)
+- Three consecutive micro-optimizations yielded <5% each (three strikes)
+- Ceiling headroom still exists (pass-through is significantly faster)
+
+**Process**:
+1. Run `assess all` from asm-optimizer on the C++ addon's hot functions.
+2. If asm-optimizer reports **Medium** or higher potential on any function:
+   - Run `iterative-optimize <entry>` from asm-optimizer.
+   - Re-benchmark after each successful optimization.
+3. Report results back to the execute pipeline.
+
+### `report`
+
+Generate the final deliverable.
+
+1. Archive final profile:
+   `cp perf/baseline.profile.data perf/baseline/profiles/final.profile.data`
+2. Print the full report: benchmark numbers, profile summary,
+   spec cross-reference path, and a list of known behavioral differences (if any).
+3. Output comparison table:
+   ```
+   | Implementation          | Ops/sec | Relative |
+   |-------------------------|---------|----------|
+   | Original JS             | X       | 1.0x     |
+   | C++ addon               | Y       | Y/X      |
+   | Pass-through (ceiling)  | Z       | Z/X      |
+   ```
 
 ### `show-state`
 
 Output the current status of the `execute` pipeline:
 
 ```
-Phase 1 (Spec): COMPLETE — spec tree at spec/original/
+Phase 1 (Discovery): COMPLETE
 Phase 2 (Naive): IN PROGRESS — 43/49 tests passing
 Phase 3 (Profile): PENDING
 Phase 4 (Optimize): PENDING

package/skills/npx/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: npx
+description: Run npx @opensassi/opencode commands in a target directory — resolves directories via inference rules and the list-targets.sh script
+---
+
+# Skill: npx
+
+## Persona
+
+You are a **devops engineer** specializing in multi-project navigation, monorepo structure inference, and cross-project CLI dispatch. Your job is to run `@opensassi/opencode` commands inside the correct target directory given a fuzzy or partial name.
+
+## On Activation
+
+1. If already in context, show the last-used target directory. Otherwise, prompt for a target.
+2. Show available commands.
+
+## Dependencies
+
+- `npx` available in PATH
+- `@opensassi/opencode` installed (resolved by npx)
+- `scripts/list-targets.sh` from the package
+
+## Commands
+
+### `npx <target> [<npx-command>] [args...]`
+
+Resolve `<target>` to a directory, then run:
+```
+cd <resolved-path> && npx @opensassi/opencode <npx-command> [args...]
+```
+
+**Resolution algorithm:**
+
+1. Run `npx @opensassi/opencode run list-targets.sh <cwd>` to get candidates as JSON.
+2. Parse the candidates array. Each entry has `{name, path, type}`.
+3. Apply rules in order:
+
+   **Rule 1 — Absolute or explicit path**: If `<target>` starts with `/`, `./`, `~/`, or `../`, use it directly.
+   
+   **Rule 2 — Exact name match**: If `<target>` matches a candidate's `name` field exactly (case-sensitive), use that candidate's `path`.
+   
+   **Rule 3 — Single external candidate heuristic**: If there is exactly one `type: "external"` candidate and `<target>` is not `.`, assume the user meant that candidate. Log the assumption.
+   
+   **Rule 4 — Multiple matches or no match**: Print the candidate list and ask the user to pick one by number or provide an explicit path.
+
+4. After resolving, store the path as the current target in conversation context so repeated commands can omit `<target>`.
+5. Run `cd <resolved-path> && npx @opensassi/opencode <npx-command> [args...]`.
+6. Display stdout/stderr output to the user.
+
+### `npx . <npx-command> [args...]`
+
+Explicitly target the project root.
+
+### `npx list`
+
+Print the candidate list without running anything.
+
+## Examples
+
+```
+User: npx opencode system-design
+Agent: Runs list-targets.sh, finds {name:"opencode", type:"external"}
+       Applies Rule 2: exact match → external/opencode/
+       Runs: cd external/opencode && npx @opensassi/opencode system-design
+
+User: npx ../sibling-project init
+Agent: Applies Rule 1: explicit relative → ../sibling-project/
+       Runs: cd ../sibling-project && npx @opensassi/opencode init
+
+User: npx tinygrad profile
+Agent: Runs list-targets.sh, finds {name:"tinygrad", type:"external"}
+       Applies Rule 2: exact match → external/tinygrad/
+       Runs: cd external/tinygrad && npx @opensassi/opencode profile
+```
+
+## Design Principles
+
+- **Prefer external/**: External projects under `external/` are the primary target. The project root itself is only targeted explicitly via `npx .`.
+- **Store last target**: Track the last resolved directory in conversation context to avoid requiring `<target>` on repeat commands within the same session.
+- **Transparent output**: All command output is shown directly to the user. Do not summarize or interpret unless asked.

package/skills/opensassi/SKILL.md

@@ -1,71 +1,169 @@
 ---
 name: opensassi
-description: Bootstrap a new project environment — detect OS, install toolchain (git, Node.js via nvm/LTS), clone FlameGraph, set up project infrastructure
+description: Root skill ecosystem — loads system-design + spec tree, routes sub-skill composition, bootstraps environments
 ---
 
-# Skill: opensassi
+# Skill: opensassi — Root Skill Ecosystem
 
-## Persona
+## Entry Point
 
-Senior DevOps engineer specializing in cross-platform development environment provisioning, with deep expertise in nvm, package managers (apt/dnf/yum/pacman/brew/choco), and build toolchain setup.
+| Input | Action |
+|-------|--------|
+| `/opensassi` | Load `skill system-design`, read `technical-specification.md` + spec tree depth 2 (root + facade specs). Report ready. |
+| `/opensassi init` | Run `env-check.sh`. Parse JSON result: if node+git+FlameGraph+deps all present → "Already bootstrapped". Otherwise run full bootstrap sequence (env-check → install → flamegraph → npm-deps → gitignore). |
+| `/opensassi <skill> <command> [args]` | Load `<skill>` from npm via `npx @opensassi/opencode <skill>`, then run `<command>` with `[args]`. Return result. |
 
-## On Activation
+### Spec tree depth
 
-1. Show the skills-index (from `skills-index.json` or by running `npx @opensassi/opencode opensassi --print-index`)
-2. Run `init check` to report current environment status (OS, Node.js, git, FlameGraph, npm deps)
-3. Show available commands
+Depth is controlled by `--depth` flag on `load spec`:
+- Depth 1: `technical-specification.md` only
+- Depth 2 (default): + sub-module facade `.spec.md` files
+- Depth 3: + internal component `.spec.md` files
+- Depth 4: + full file-level `.spec.md` tree
 
-To load a sub-skill (e.g., system-design, git, profiler), the agent should run:
-```
-npx @opensassi/opencode <skill-name>
-```
-and read the output as the skill's full instructions.
-
-## Dependencies
+## Init
 
-- `bash` or `powershell` (for bootstrap scripts — zero other deps)
-- `git` (installed by bootstrap if missing)
-- The `@opensassi/opencode` npm package (scripts resolve via `npx @opensassi/opencode run --skill opensassi <name>`)
+Single shell command: `npx @opensassi/opencode run --skill opensassi env-check.sh`
 
-## Commands
+Returns JSON: `{"os": ..., "distro": ..., "node_version": ..., "git_version": ..., ...}`
 
-### `init`
+**Interpretation:**
+```
+bootstrapped = (node_version != "" && git_version != "" 
+                && scripts/FlameGraph/ exists 
+                && node_modules/ exists)
+```
 
-Execute companion scripts from the `@opensassi/opencode` package. If a script is missing or a platform installer does not exist, report the gap and continue; do not generate files.
+If bootstrapped → report "Environment ready." + show node/git versions.  
+If not → run full bootstrap:
 
-1. `npx @opensassi/opencode run --skill opensassi env-check.sh` (or `env-check.ps1` on Windows) — bootstrap git + Node.js LTS (creates `.nvmrc` if missing)
-2. `init install` — run existing platform installer, or report if none found
-3. `init flamegraph` — clone FlameGraph v1.0
+1. `npx @opensassi/opencode run --skill opensassi env-check.sh` — install git + Node.js LTS if missing, write `.nvmrc`
+2. `init install` — run platform-specific installer (cmake, nasm, gdb, ripgrep, perf, htop, etc.) or report none found
+3. `init flamegraph` — clone FlameGraph v1.0 to `scripts/FlameGraph/`
 4. `npx @opensassi/opencode run --skill opensassi install-npm-deps.sh` — `npm install`
 5. `npx @opensassi/opencode run --skill opensassi ensure-gitignore.sh` — append common patterns
 
-### `init install`
-
-Install the development environment toolchain.
-
-**Flow:**
-
-1. **Detect environment** — run `npx @opensassi/opencode run --skill opensassi env-check.sh` (Linux/macOS/WSL/Git Bash) or fall back to `env-check.ps1` (Windows native). Both output structured JSON.
-2. **Check for existing installer** — look for `npx @opensassi/opencode run install.sh` for platform-specific installers from the package's `scripts/install/` directory
-3. **If installer exists** — run it (installs: cmake, nasm, gdb, ripgrep, perf, htop, etc.)
-4. **If installer NOT found**:
-   a. Report: "No installer found for this platform"
-   b. Continue — env-check already installed git + Node.js, which is sufficient for the project to function
-
-### `init flamegraph`
-
-Clone Brendan Gregg's FlameGraph at pinned tag `v1.0` to `scripts/FlameGraph/`:
-- If `scripts/FlameGraph/` does not exist: `git clone --depth=1 --branch v1.0`
-- If it exists: `git fetch --tags --depth=1 && git checkout v1.0`
-
-### `init check`
-
-Run `npx @opensassi/opencode run --skill opensassi env-check.sh` (or `env-check.ps1`) and verify:
-- Node.js version (LTS or later)
-- git availability
-- FlameGraph presence at `scripts/FlameGraph/`
-- npm deps installed (`node_modules/` exists)
-- `.gitignore` has common patterns
+## Lexicon
+
+| Skill | Command | Arguments | Description |
+|-------|---------|-----------|-------------|
+| **system-design** | `load spec` | `[--depth 1-4]` | Load spec tree into context (tail — permanent base) |
+| | `generate from source` | — | Build spec tree from source files |
+| | `generate technical specification` | — | Produce complete class spec + diagrams + test plan |
+| | `revise technical specification` | — | Propose structured revisions list |
+| | `generate sequence diagram` | — | Mermaid sequence diagram for data flow |
+| | `generate architecture diagram` | — | Mermaid C4 container/component diagram |
+| | `generate class specification` | — | Complete C++ class declarations |
+| | `generate d3 animation` | — | Self-contained HTML D3.js animation |
+| | `generate testing plan` | — | Structured unit/integration/regression tests |
+| | `split sub-modules` | — | Break monolithic spec into sub-module directory |
+| | `combine sub-modules` | — | Flatten sub-module spec back to monolithic |
+| | `list sub-modules` | — | List all sub-modules with facade classes |
+| | `load sub-module spec` | `<path>` | Load one sub-module `.spec.md` |
+| | `generate sub-module spec` | `<name>` | Generate `.spec.md` for a named sub-module |
+| **git** | `start session` | — | `git checkout main` → `git pull --rebase`, verify clean tree |
+| | `finish session` | — | add → commit → rebase → test → eval → push (single atomic commit) |
+| | `sync` | — | `git fetch origin` → `git rebase origin/main` → test |
+| **issue** | `create issue` | `<body>` | Create GitHub issue from structured body |
+| | `list issues` | `[--limit N]` | List recent GitHub issues |
+| | `show issue` | `<number>` | Show issue details and status |
+| | `close issue` | `<number>` | Close issue with comment |
+| **npm-optimizer** | `execute` | — | Full port pipeline: discover → ceiling → naive → profile → classify → pivot/micro → shim → report |
+| | `assess-ceiling` | — | Build N-API pass-through, measure upper bound |
+| | `implement-naive` | — | Scaffold simplest C++ addon passing 100% tests |
+| | `classify` | — | Sort perf samples Tier 1/2/3, decide pivot vs micro |
+| | `pivot` | — | Architectural pivot when N-API/V8 is bottleneck |
+| | `micro-optimize` | — | Iterative C++ micro-opt with 3-strikes rule |
+| | `shim` | — | JS compatibility wrapper + cross-reference docs |
+| | `bench` | — | Benchmark against original JS baseline |
+| | `assess-handoff` | — | Gate: evaluate dropping to asm-optimizer |
+| | `report` | — | Final comparison table + archive |
+| | `show-state` | — | Pipeline progress |
+| **profiler** | `check` | — | Verify perf toolchain available |
+| | `setup` | `[--frames N]` | Download test data, prepare profiling environment |
+| | `profile` | `[--events ...]` | `perf record` → flamegraph |
+| | `benchmark` | `[--iter N]` | Run N iterations with metric collection |
+| | `compare` | `<baseline> <candidate>` | Side-by-side benchmark comparison |
+| | `report` | `[--profile <label>]` | Bundle profiling session into report |
+| **asm-optimizer** | `setup-baseline` | — | Create baseline dirs, clone release, build, run profiling matrix |
+| | `profile` | `<name>` | Maximal perf counter dump against baseline |
+| | `assess` | `<entry>` | Evaluate one function's ASM optimization potential |
+| | `assess all` | — | Rank all candidate functions by potential |
+| | `setup-microbench` | `<entry>` | Create isolated microbenchmark harness |
+| | `spec` | `<entry>` | Generate technical spec of C++ implementation |
+| | `analyze-gap` | `<entry>` | Compare ASM implementation against C++ spec |
+| | `bench` | `<entry>` | Run microbenchmark, compare against C++ baseline |
+| | `implement` | `<entry>` | Generate ASM implementation following spec-first process |
+| | `iterative-optimize` | `<entry>` | Full optimization pipeline with experiment archiving |
+| | `archive-experiment` | `<entry>` | Save experiment record when hypothesis fails |
+| | `report` | `[--format markdown\|json]` | Optimization report for all assessed entries |
+| **todo** | `extract` | `<name>` | Scan session context for unfinished work → structured summary |
+| | `propose-todo` | `<name>` | Draft todo entry from extract output |
+| | `save-todo` | — | Write to `todos/<NNN>-<name>.md` |
+| | `load-todo` | `<id>` | Read todo file into context for agent to act on |
+| | `list-todos` | — | List all saved todo entries |
+| **session-evaluation** | `generate` | — | Analyze conversation, produce structured session evaluation |
+| | `export` | — | Save evaluation + compressed session archive to `sessions/` |
+| **skill-manager** | `show skills` | — | List all registered skills |
+| | `create skill` | — | Interactive skill creation flow |
+| | `revise skill` | `<name>` | Interactive skill revision |
+| | `save skill` | — | Write skill to disk + register |
+| | `delete skill` | `<name>` | Remove skill from disk |
+| | `commit` | — | Stage + commit all skill changes |
+| | `audit skills` | — | Validate all skill files for consistency |
+| **system-design-review** | *(no commands defined)* | — | Seven-expert panel audit of technical specs |
+| **daily-evaluation** | *(no commands defined)* | — | Aggregate session evaluations into dashboards |
+| **npx** | `npx <target> <cmd>` | `<target> <cmd>` | Run npx command in target directory |
+| | `npx . <cmd>` | `<cmd>` | Run npx command in current directory |
+| | `npx list` | — | List available target directories |
+
+## Composition Patterns
+
+Common requests map to skill compositions. Load order: permanent base (tail) at bottom, JIT skills (head) at top.
+
+| User says | Skill stack (head ← tail) | Commands |
+|-----------|---------------------------|----------|
+| "start a session" | git → system-design+spec | `start session` |
+| "finish the session" | session-evaluation → git → system-design+spec | `generate` → `finish session` → `export` |
+| "load the last issue" | issue → system-design+spec | `list issues` → `show issue <N>` |
+| "create an issue from context" | todo → issue → system-design+spec | `extract <name>` → `create issue <body>` → `save-todo` |
+| "show pending todos" | todo → system-design+spec | `list-todos` |
+| "load a todo and work on it" | todo → system-design+spec | `load-todo <id>` → agent acts on content |
+| "port an npm package" | npm-optimizer → system-design+spec | `execute` |
+| "hand off to asm" | asm-optimizer → npm-optimizer → system-design+spec | `assess-handoff` |
+| "profile the encoder" | profiler → system-design+spec | `check` → `profile` |
+| "optimize a hot function" | asm-optimizer → system-design+spec | `assess <entry>` → `iterative-optimize <entry>` |
+| "create a debugging todo" | todo → asm-optimizer → system-design+spec | `extract` → `propose-todo` → `save-todo` |
+| "save a note" | todo → system-design+spec | (treat free text as note → `extract` → `propose-todo` → `save-todo`) |
+
+## Interpretation
+
+Parse user text into skill compositions:
+
+1. **Explicit routing** — If prefixed with `/opensassi`, dispatch directly from the Entry Point table.
+
+2. **Keyword matching** — Scan user text for Lexicon command names and skill domains:
+   - "issue", "bug", "ticket" → `issue` skill
+   - "git", "commit", "push", "rebase" → `git` skill
+   - "profile", "perf", "flamegraph" → `profiler` skill
+   - "asm", "assembly", "SIMD", "optimize function" → `asm-optimizer` skill
+   - "npm", "port", "native addon" → `npm-optimizer` skill
+   - "todo", "note", "deferred", "remaining" → `todo` skill
+   - "spec", "diagram", "design" → `system-design` skill
+   - "session eval", "report card" → `session-evaluation` skill
+   - "skill", "manage skills" → `skill-manager` skill
+
+3. **Pattern matching** — Match multi-keyword phrases against Composition Patterns. If no direct match, compose by chaining relevant skills.
+
+4. **Unknown requests** — Reference the Lexicon table and ask: "I see you want to [paraphrase]. Do you mean one of these: [list 2-3 matching skills]?"
+
+5. **Permanent base** — Always keep `system-design` + spec tree loaded (tail of context). Only JIT-load the head skills needed for the current task.
+
+## Context Architecture
+
+- **Tail (permanent base):** `system-design` skill + spec tree. Loaded at `/opensassi`. Self-repropagating tokens designed for long-context survival.
+- **Head (JIT-loaded):** Specific skill instructions loaded per phase. Strongest attention, loaded last.
+- **Sub-agent loading contracts:** When spawning phase sub-agents, load skills in deterministic order for KV cache reuse (detailed in `npm-optimizer` SKILL.md).
 
 ## Design Principles
 
@@ -74,4 +172,4 @@ Run `npx @opensassi/opencode run --skill opensassi env-check.sh` (or `env-check.
 - **`.nvmrc` for the project** — Written with `--lts` so `nvm use` auto-selects when entering the project directory.
 - **FlameGraph pinned at v1.0** — Tag is stable; pinned clones are idempotent.
 - **`install.ps1` is WSL-only** — Not modified by this skill. Windows-native installer is a future extension.
-- **env-check scripts output JSON** — Structured `{os, distro, version, codename, pkg_manager, shell, is_wsl, arch, node_version, nvm_version, git_version}` for AI agent consumption.
+- **env-check scripts output JSON** — Structured for consumption by the skill's interpretation logic.

package/skills/todo/SKILL.md

@@ -1,20 +1,18 @@
 ---
 name: todo
-description: Creates linked GitHub issues and debugging skills from session context for unfinished work
+description: Extract unfinished work from session context, create GitHub issues, and save structured todo entries to `todos/` for future agents
 ---
 
 # Skill: todo
 
 ## Persona
 
-Technical writer and project manager — extracts structured summaries from session conversations, then produces self-contained debugging skills for future agents.
+Technical writer and project manager — extracts structured summaries from session conversations, creates GitHub issues, and saves sequential todo entries to `todos/` for future agent use.
 
 ## Dependencies
 
-Requires the **issue** skill — the `create issue` command from that skill handles the issue side.
-This skill adds the skill-creation half.
-
-Load both skills on activation:
+Requires the **issue** skill — `create issue` handles the GitHub side.
+Load both on activation:
 ```
 skill issue
 skill todo
@@ -23,16 +21,17 @@ skill todo
 ## On Activation
 
 Show the workflow:
-1. `extract <name>` — analyze session context
-2. Load `issue` skill → `create issue <body>` — creates the GitHub issue
-3. Return here → `propose-skill <name>` — drafts the debugging skill
-4. `save-skill` — writes skill to disk
+1. `extract <name>` — analyze session context for unfinished work
+2. `propose-todo <name>` — draft a structured todo entry
+3. Load `issue` skill → `create issue <body>` — creates the GitHub issue, note the issue #
+4. `save-todo` — write to `todos/` with sequential numbering
+5. `load-todo <id>` or `list-todos` — retrieve saved work
 
 ## Commands
 
 ### `extract <name>`
 
-Scan the current session context for unfinished work, bugs, deferred items. Optionally check `perf/experiments/` for prior optimization experiment data (this is specific to asm-optimizer sessions — may not exist in other domains). Output a structured summary with two sections:
+Scan the current session context for unfinished work, bugs, deferred items. Optionally check `perf/experiments/` for prior optimization experiment data (asm-optimizer specific — may not exist in other domains). Output a structured summary with two sections:
 
 #### Issue Body (formatted for the `issue` skill's `create issue` command)
 
@@ -57,7 +56,7 @@ Scan the current session context for unfinished work, bugs, deferred items. Opti
 - [ ] <criterion 2>
 ```
 
-#### Skill Content (for `propose-skill`)
+#### Todo Content (for `propose-todo`)
 
 ```
 ### What Succeeded
@@ -76,28 +75,17 @@ Scan the current session context for unfinished work, bugs, deferred items. Opti
 <paths to any domain-specific experiment directories, if available>
 ```
 
-### `propose-skill <name>`
-
-From the extract output + an existing issue number (obtained by running `create issue` from the `issue` skill), draft a skill at `.opencode/skills/<name>-<issue#>/SKILL.md` following the established pattern:
+### `propose-todo <name>`
 
-```
----
-name: <name>-<issue#>
-description: <one-line summary linking to GitHub issue #N>
----
+From the extract output + an existing issue number (obtained by running `create issue` from the `issue` skill), draft a todo entry following this format:
 
-# Skill: <name>-<issue#>
+```markdown
+# <NNN>-<name>
 
 ## Issue Reference
-
 GitHub Issue: https://github.com/<owner>/<repo>/issues/<N>
 
-## Dependencies
-
-Requires: **<parent-skill>** — load this skill first via `skill <parent>`.
-
 ## Previous Work
-
 ### What Succeeded
 <from extract output>
 
@@ -107,59 +95,53 @@ Requires: **<parent-skill>** — load this skill first via `skill <parent>`.
 ### What Remains
 <from extract output>
 
-## Persona
+## Key Technical Details
+<from extract output>
 
-<domain-specific persona for the follow-up agent>
+## Experiment References
+<from extract output>
+```
 
-## On Activation
+Present for review. Does not write until `save-todo`.
 
-<steps to take when loaded>
+### `save-todo`
 
-## Commands
+Write the currently agreed todo entry to `todos/<NNN>-<name>.md`:
 
-- `setup` — rebuild and prepare
-- `test` — run bit-exact comparison
-- `gdb-trace <phase>` — debug specific phase
-- `fix <strategy>` — apply known fix strategy
-- `bench` — microbenchmark with perf stat
-- `report-fix` — validate, wire, close issue
+1. Scan `todos/` directory for existing files.
+2. Determine the next sequential number (e.g., `todos/` has `001-*.md`, `002-*.md` → next is `003`).
+3. Write the file using the format from `propose-todo` output.
+4. Confirm: `Saved todos/003-<name>.md`.
 
-## Debugging Context
+### `load-todo <id>`
 
-<known-correct intermediate values, register dumps, algorithm traces>
+Read a todo file into context so the agent can act on it as a mini-brief:
 
-## Files Reference
+1. Accept a todo identifier: numeric prefix (`003`) or name fragment (`dq-asm`).
+2. Match against `todos/*.md` files.
+3. If ambiguous, list matches and ask for refinement.
+4. Read the matched file in full into context.
+5. Report: `Loaded todos/003-dq-asm-minselect-debug-3.md — <title>`
 
-<file paths and their roles>
+### `list-todos`
 
-## Design Principles
+List all saved todo entries:
 
-<conventions, guardrails>
 ```
-
-Present for review. Does not write until `save-skill`.
-
-### `save-skill`
-
-Write the currently agreed SKILL.md content to `.opencode/skills/<name>-<issue#>/SKILL.md` and register in `opencode.json`:
-
-1. Validate frontmatter (name and description must be present).
-2. Write the file to `.opencode/skills/<name>-<issue#>/SKILL.md`.
-3. Update `opencode.json` to add `"<name>-<issue#>": "allow"` if not already present. After writing, re-read and confirm.
-4. Confirm the action.
+001-dq-asm-minselect-debug-3       GitHub #12 — Debug minselect register corruption
+002-had-avx2-optimization-4        GitHub #15 — Port HAD function to AVX2
+003-scheduler-phase-1-9            GitHub #22 — Implement scheduler dispatch
+```
 
 ## Design Principles
 
-- The **issue** skill handles ALL issue creation — this skill never calls `gh issue create`. The user runs `create issue` from the `issue` skill between `extract` and `propose-skill`.
-- The extract's "Issue Body" section is ready for direct use as the `create issue` command's body in the issue skill.
-- Session tracking line at the bottom of every issue body (matching issue skill's convention):
+- The **issue** skill handles ALL issue creation — this skill never calls `gh issue create`. The user runs `create issue` from the `issue` skill between `propose-todo` and `save-todo`.
+- Session tracking line at the bottom of every issue body:
   ```
   ---
-
   Generated from session `<session-id>` on `<date>`.
   ```
+- Todo files are flat markdown in `todos/` — no SKILL.md, no persona, no commands. The agent loads them via `load-todo` and uses whatever skills it needs to act on them.
+- Sequential numbering prevents collisions and provides deterministic ordering.
 - Domain-specific experiment directories (like asm-optimizer's `perf/experiments/`) are OPTIONAL — check existence before referencing, silently omit if absent.
-- Skill name bakes in issue number: `<name>-<issue#>`.
-- `propose-skill` and `save-skill` are read-only until `save-skill` writes.
-- Previous Work uses three sub-sections: What Succeeded, What Was Tried, What Remains.
-- Do NOT modify the `skill-manager` or `issue` skills themselves.
+- Do NOT modify the `skill-manager`, `issue`, or other core skills themselves.

package/skills-index.json

@@ -1,26 +1,28 @@
 {
   "skills": [
     {
-      "name": "system-design",
-      "description": "Interactive C++ spec authoring with diagrams and D3 animations",
+      "name": "asm-optimizer",
+      "description": "SIMD/assembly optimization framework",
       "commands": [
-        "generate sequence diagram",
-        "generate architecture diagram",
-        "generate class specification",
-        "generate manim animation",
-        "generate d3 animation",
-        "generate testing plan",
-        "generate from source",
-        "load spec",
-        "generate technical specification",
-        "revise technical specification",
-        "split sub-modules",
-        "combine sub-modules",
-        "list sub-modules",
-        "load sub-module spec",
-        "generate sub-module spec"
+        "setup-baseline",
+        "profile",
+        "assess",
+        "assess all",
+        "setup-microbench",
+        "spec",
+        "analyze-gap",
+        "bench",
+        "implement",
+        "iterative-optimize",
+        "archive-experiment",
+        "report"
       ]
     },
+    {
+      "name": "daily-evaluation",
+      "description": "Aggregate session evaluations into dashboards",
+      "commands": []
+    },
     {
       "name": "git",
       "description": "Rebase-based single-commit-per-session workflow",
@@ -31,43 +33,58 @@
       ]
     },
     {
-      "name": "profiler",
-      "description": "Linux perf profiling + flamegraphs",
+      "name": "issue",
+      "description": "GitHub issue management",
       "commands": [
-        "check",
-        "setup",
-        "profile",
-        "benchmark",
-        "compare",
-        "report"
+        "create issue",
+        "list issues",
+        "show issue",
+        "close issue"
       ]
     },
     {
-      "name": "asm-optimizer",
-      "description": "SIMD/assembly optimization framework",
+      "name": "npx",
+      "description": "Run npx commands in a target directory with automatic directory resolution",
       "commands": [
-        "setup-baseline",
-        "profile",
-        "assess",
-        "assess all",
-        "setup-microbench",
-        "spec",
-        "analyze-gap",
+        "npx <target> <npx-command>",
+        "npx . <npx-command>",
+        "npx list"
+      ]
+    },
+    {
+      "name": "npm-optimizer",
+      "description": "Port an npm package to a C++ native addon — preserve 100% test compatibility while significantly improving performance through profiling-driven architectural iteration",
+      "commands": [
+        "execute",
+        "assess-ceiling",
+        "implement-naive",
+        "classify",
+        "pivot",
+        "micro-optimize",
+        "shim",
         "bench",
-        "implement",
-        "iterative-optimize",
-        "archive-experiment",
-        "report"
+        "assess-handoff",
+        "report",
+        "show-state"
       ]
     },
     {
       "name": "opensassi",
-      "description": "Bootstrap a new project environment",
+      "description": "Root skill ecosystem — loads system-design + spec tree, routes sub-skill composition, bootstraps environments",
       "commands": [
-        "init",
-        "init install",
-        "init flamegraph",
-        "init check"
+        "init"
+      ]
+    },
+    {
+      "name": "profiler",
+      "description": "Linux perf profiling + flamegraphs",
+      "commands": [
+        "check",
+        "setup",
+        "profile",
+        "benchmark",
+        "compare",
+        "report"
       ]
     },
     {
@@ -92,46 +109,41 @@
       ]
     },
     {
-      "name": "issue",
-      "description": "GitHub issue management",
+      "name": "system-design",
+      "description": "Interactive C++ spec authoring with diagrams and D3 animations",
       "commands": [
-        "create issue",
-        "list issues",
-        "show issue",
-        "close issue"
+        "generate sequence diagram",
+        "generate architecture diagram",
+        "generate class specification",
+        "generate manim animation",
+        "generate d3 animation",
+        "generate testing plan",
+        "generate from source",
+        "load spec",
+        "generate technical specification",
+        "revise technical specification",
+        "split sub-modules",
+        "combine sub-modules",
+        "list sub-modules",
+        "load sub-module spec",
+        "generate sub-module spec"
       ]
     },
     {
       "name": "system-design-review",
       "description": "Seven-expert panel audit of technical specs",
-      "commands": [
-        "review all",
-        "review sub-module",
-        "review file-path",
-        "review stale"
-      ]
-    },
-    {
-      "name": "daily-evaluation",
-      "description": "Aggregate session evaluations into dashboards",
-      "commands": [
-        "create",
-        "list"
-      ]
+      "commands": []
     },
     {
       "name": "todo",
-      "description": "Create issues + debugging skills from session context",
+      "description": "Extract unfinished work from session context, create GitHub issues, and save structured todo entries to todos/ for future agents",
       "commands": [
         "extract",
-        "propose-skill",
-        "save-skill"
+        "propose-todo",
+        "save-todo",
+        "load-todo",
+        "list-todos"
       ]
-    },
-    {
-      "name": "npm-optimizer",
-      "description": "Port an npm package to a C++ native addon",
-      "commands": []
     }
   ]
-}
+}