@opensassi/opencode 0.1.2 → 0.1.4

package/scripts/generate-daily-summaries.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const SESSIONS_DIR = resolve(process.cwd(), 'sessions');
+
+function parseMdField(content, label) {
+  const re = new RegExp(`\\*\\*${label}:\\*\\*\\s*(.+?)(?:\\n\\n|\\n(?=\\*\\*)|$)`, 's');
+  const m = content.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function parseDurationMinutes(content) {
+  // Try **Duration:** HH<something>
+  const durMatch = content.match(/\*\*Duration:\*\*\s*(\d+)\s*min/);
+  if (durMatch) return parseInt(durMatch[1], 10);
+
+  // Fallback: from .json.bz2 (handled below)
+  return 0;
+}
+
+function parsePrompterMinutes(content) {
+  const totalMatch = content.match(/\*\*Total:\*\*\s*([\d.]+)\s*hours?/);
+  if (totalMatch) return Math.round(parseFloat(totalMatch[1]) * 60);
+  // also try: prompter active ≈ X hours
+  const activeMatch = content.match(/prompter active\s*[≈~]?\s*([\d.]+)\s*hours?/);
+  if (activeMatch) return Math.round(parseFloat(activeMatch[1]) * 60);
+  return 30;
+}
+
+function parseSmeHours(content) {
+  const smeMatch = content.match(/\*\*Model-Equivalent SME Time Estimate:\*\*\s*(?:~|≈)?\s*([\d.]+)\s*hours?/);
+  if (smeMatch) return Math.round(parseFloat(smeMatch[1]) * 60);
+  return 60;
+}
+
+function parseTags(content) {
+  const tagMatch = content.match(/\*\*Aggregation Tags:\*\*\s*(.+?)(?:\\n\\n|$)/s);
+  if (tagMatch) {
+    return tagMatch[1].split(',').map(t => t.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function parseSessionId(content) {
+  return parseMdField(content, 'Session ID') || '';
+}
+
+function parseDescription(content) {
+  return parseMdField(content, 'Top-Level Component') || '';
+}
+
+function parseConfidence(/*content*/) {
+  return 'medium';
+}
+
+function extractDate(sessionId, filename) {
+  if (sessionId) {
+    const m = sessionId.match(/^(\d{4}-\d{2}-\d{2})/);
+    if (m) return m[1];
+  }
+  const m = filename.match(/^(\d{4}-\d{2}-\d{2})/);
+  return m ? m[1] : null;
+}
+
+function getBz2Duration(sessionDir, sessionId) {
+  if (!sessionId) return null;
+  const files = readdirSync(sessionDir);
+  const match = files.find(f => f.startsWith(sessionId) && f.endsWith('.json.bz2'));
+  if (!match) return null;
+  try {
+    const buf = execFileSync('bzcat', [join(sessionDir, match)], {
+      encoding: 'utf-8', maxBuffer: 100 * 1024 * 1024, stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    const d = JSON.parse(buf);
+    const info = d.info || {};
+    const t = info.time || {};
+    const created = t.created || 0;
+    const updated = t.updated || 0;
+    if (updated && created) return Math.round((updated - created) / 60000);
+    return null;
+  } catch { return null; }
+}
+
+async function main() {
+  if (!existsSync(SESSIONS_DIR)) {
+    console.error(`Sessions directory not found: ${SESSIONS_DIR}`);
+    process.exit(1);
+  }
+
+  const files = readdirSync(SESSIONS_DIR);
+  const mdFiles = files.filter(f => f.endsWith('.md') && !f.endsWith('.spec.md') && f !== 'README.md' && f !== 'export-session.sh');
+
+  // Group sessions by date
+  const byDate = {};
+
+  for (const mdFile of mdFiles) {
+    const content = readFileSync(join(SESSIONS_DIR, mdFile), 'utf-8');
+    const sessionId = parseSessionId(content);
+    const date = extractDate(sessionId, mdFile);
+    if (!date) { console.error(`Could not extract date from ${mdFile}`); continue; }
+
+    const prompterMin = parsePrompterMinutes(content);
+    const smeMin = parseSmeHours(content);
+    const bz2Duration = getBz2Duration(SESSIONS_DIR, sessionId);
+    const durationMin = bz2Duration || prompterMin || parseDurationMinutes(content);
+    const tags = parseTags(content);
+    const description = parseDescription(content);
+    const confidence = parseConfidence(content);
+
+    if (!byDate[date]) byDate[date] = [];
+    byDate[date].push({
+      session_id: sessionId || mdFile.replace(/\.md$/, ''),
+      duration_minutes: durationMin,
+      prompter_time_minutes: Math.min(prompterMin, durationMin || prompterMin),
+      sme_time_minutes: smeMin,
+      top_component_summary: description,
+      tags,
+      human_confidence: confidence,
+    });
+  }
+
+  // Generate daily files
+  const dailyDir = join(SESSIONS_DIR, 'daily');
+  if (!existsSync(dailyDir)) {
+    mkdirSync(dailyDir, { recursive: true });
+  }
+
+  for (const [date, sessions] of Object.entries(byDate).sort()) {
+    let totalPrompter = 0, totalSme = 0;
+    for (const s of sessions) {
+      totalPrompter += s.prompter_time_minutes;
+      totalSme += s.sme_time_minutes;
+    }
+    const totalPrompterHrs = Math.round((totalPrompter / 60) * 10) / 10;
+    const totalSmeHrs = Math.round((totalSme / 60) * 10) / 10;
+
+    // Compute per-tag aggregates
+    const tagMap = {};
+    for (const s of sessions) {
+      const perTagSme = s.sme_time_minutes / (s.tags.length || 1);
+      const perTagPrompter = s.prompter_time_minutes / (s.tags.length || 1);
+      for (const tag of s.tags) {
+        if (!tagMap[tag]) tagMap[tag] = { prompter: 0, sme: 0 };
+        tagMap[tag].prompter += perTagPrompter;
+        tagMap[tag].sme += perTagSme;
+      }
+    }
+    const topSubjectAreas = Object.entries(tagMap)
+      .map(([name, v]) => ({
+        name,
+        prompter_time_hours: Math.round((v.prompter / 60) * 100) / 100,
+        sme_time_hours: Math.round((v.sme / 60) * 100) / 100,
+        ai_multiplier: v.prompter > 0 ? Math.round((v.sme / v.prompter) * 10) / 10 : 0,
+      }))
+      .sort((a, b) => b.sme_time_hours - a.sme_time_hours);
+
+    const aiMultiplier = totalPrompterHrs > 0
+      ? Math.round((totalSmeHrs / totalPrompterHrs) * 10) / 10
+      : 0;
+
+    const daily = {
+      dashboard: {
+        metadata: {
+          generated_at: new Date().toISOString(),
+          audited: false,
+          audit_note: 'Auto-generated from session evaluation files',
+        },
+        daily_summary: {
+          date,
+          total_prompter_time_hours: totalPrompterHrs,
+          total_sme_time_hours: totalSmeHrs,
+          ai_multiplier: aiMultiplier,
+          total_sessions: sessions.length,
+          top_subject_areas: topSubjectAreas,
+        },
+        session_breakdown: sessions,
+      },
+    };
+
+    const outPath = join(dailyDir, `${date}.json`);
+    writeFileSync(outPath, JSON.stringify(daily, null, 2) + '\n');
+    console.log(`Wrote ${outPath}  (${sessions.length} sessions, ${totalPrompterHrs}h prompter, ${totalSmeHrs}h SME)`);
+  }
+
+  console.log(`\nDone. Generated ${Object.keys(byDate).length} daily summaries.`);
+}
+
+main().catch(e => { console.error(e); process.exit(1); });

package/skills/opensassi/SKILL.md

@@ -1,75 +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
 
-Available sub-skills: asm-optimizer, daily-evaluation, git, issue, npx, npm-optimizer, profiler, session-evaluation, skill-manager, system-design, system-design-review, todo
+## Init
 
-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
+Single shell command: `npx @opensassi/opencode run --skill opensassi env-check.sh`
 
-- `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>`)
+Returns JSON: `{"os": ..., "distro": ..., "node_version": ..., "git_version": ..., ...}`
 
-## Commands
-
-### `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
 
@@ -78,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

@@ -70,12 +70,9 @@
     },
     {
       "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"
       ]
     },
     {
@@ -139,8 +136,14 @@
     },
     {
       "name": "todo",
-      "description": "Create issues + debugging skills from session context",
-      "commands": []
+      "description": "Extract unfinished work from session context, create GitHub issues, and save structured todo entries to todos/ for future agents",
+      "commands": [
+        "extract",
+        "propose-todo",
+        "save-todo",
+        "load-todo",
+        "list-todos"
+      ]
     }
   ]
 }