@opensassi/opencode 0.1.0 → 0.1.2

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.2",
   "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

@@ -15,12 +15,16 @@ Senior DevOps engineer specializing in cross-platform development environment pr
 2. Run `init check` to report current environment status (OS, Node.js, git, FlameGraph, npm deps)
 3. Show available commands
 
-To load a sub-skill (e.g., system-design, git, profiler), the agent should run:
+Available sub-skills: asm-optimizer, daily-evaluation, git, issue, npx, npm-optimizer, profiler, session-evaluation, skill-manager, system-design, system-design-review, todo
+
+To load a sub-skill, run:
 ```
 npx @opensassi/opencode <skill-name>
 ```
 and read the output as the skill's full instructions.
 
+The `npx` sub-skill provides cross-project dispatch — it runs `@opensassi/opencode` commands in a different target directory (handy for operating on `external/` projects from the root).
+
 ## Dependencies
 
 - `bash` or `powershell` (for bootstrap scripts — zero other deps)

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,33 +33,39 @@
       ]
     },
     {
-      "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"
       ]
     },
     {
@@ -70,6 +78,18 @@
         "init check"
       ]
     },
+    {
+      "name": "profiler",
+      "description": "Linux perf profiling + flamegraphs",
+      "commands": [
+        "check",
+        "setup",
+        "profile",
+        "benchmark",
+        "compare",
+        "report"
+      ]
+    },
     {
       "name": "session-evaluation",
       "description": "Generate structured session reports",
@@ -92,46 +112,35 @@
       ]
     },
     {
-      "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",
-      "commands": [
-        "extract",
-        "propose-skill",
-        "save-skill"
-      ]
-    },
-    {
-      "name": "npm-optimizer",
-      "description": "Port an npm package to a C++ native addon",
       "commands": []
     }
   ]
-}
+}