@opensassi/opencode 0.1.0

package/AGENTS.md

@@ -0,0 +1,35 @@
+# opencode Agent Instructions — @opensassi/opencode
+
+This project uses the **@opensassi/opencode** skill pack.
+All skills, scripts, and tooling are delivered via the npm package.
+
+## Available Skills
+
+| `skill` | Use case |
+|---------|----------|
+| `asm-optimizer` | SIMD/assembly optimization framework |
+| `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 |
+| `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 |
+| `todo` | Create issues + debugging skills from session context |
+
+## Workflow
+
+1. `skill opensassi` — Load the bootstrap skill. It exposes the full skills-index as a reference table.
+2. Run `npx @opensassi/opencode <skill-name>` to load any sub-skill. The agent reads the output as the skill's full instructions.
+3. Use the skill's commands. Scripts are run via `npx @opensassi/opencode run <path>` or `npx @opensassi/opencode run --skill <name> <path>`.
+
+## Design Constraints
+
+- No commits during development — all changes staged at finish session time
+- Single atomic commit per session
+- Full test suite after every rebase
+- Session evaluation is read-only (generate) / write-once (export)
+- All skills, scripts, and AGENTS.md live in the npm package, not in the project

package/README.md

@@ -0,0 +1,81 @@
+# @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.
+
+```
+npx @opensassi/opencode init
+```
+
+## Installation
+
+```bash
+npm install --dev @opensassi/opencode
+```
+
+Then bootstrap a project to make its skills available to opencode:
+
+```bash
+npx opencode init
+```
+
+This writes three files to your project:
+- **`AGENTS.md`** — appends full opensassi agent instructions
+- **`.opencode/skills/opensassi/SKILL.md`** — bootstrap skill (the only skill on disk)
+- **`.opencode/opencode.json`** — permission rules + MCP server config
+
+All other skills (system-design, git, profiler, etc.) are loaded at runtime via the CLI.
+
+## CLI Commands
+
+```
+npx @opensassi/opencode init                    # Bootstrap project
+npx @opensassi/opencode <skill-name>             # Print skill instructions to stdout
+npx @opensassi/opencode run <path> [args...]     # Run a script from the package
+npx @opensassi/opencode run --skill <n> <path>   # Run a skill-specific script
+npx @opensassi/opencode help                     # Show help
+```
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `asm-optimizer` | SIMD/assembly optimization framework |
+| `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 |
+| `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 |
+| `todo` | Create issues + debugging skills from session context |
+
+## Package Contents
+
+| Directory | Contents |
+|-----------|----------|
+| `bin/` | CLI entry point (`opencode` binary) |
+| `lib/` | Programmatic API + command implementations |
+| `skills/` | 12 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 |
+
+## Development
+
+```bash
+git clone git@github.com:opensassi/opencode.git
+cd opencode
+node bin/opencode.js help
+npm pack --dry-run     # Review package contents
+npm run validate-all   # Full artifact pipeline test
+```
+
+## Design
+
+- **Minimal filesystem footprint** — `init` writes only 3 files. All sub-skills load from the npm package at runtime.
+- **opencode-agnostic** — The CLI works stand-alone. Skills are consumed by opencode but the package doesn't depend on it.
+- **Runtime skill loading** — Sub-skills are never on disk; the agent loads them by running `npx @opensassi/opencode <name>`.
+- **Programmatic API** — `import { init, run, printSkill } from '@opensassi/opencode'`

package/bin/opencode.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { cli } from '../lib/cli.js'
+process.exit(await cli(process.argv.slice(2)))

package/lib/cli.js

@@ -0,0 +1,38 @@
+import { initCommand } from './commands/init.js'
+import { printSkill } from './commands/print-skill.js'
+import { runCommand } from './commands/run.js'
+
+export async function cli(args) {
+  if (args.length === 0 || args[0] === '--help' || args[0] === 'help') {
+    console.log(`Usage: opencode <command> [options]
+
+Commands:
+  init                          Bootstrap this directory with opensassi skills
+  run <path> [args...]          Run a script from the package scripts/ directory
+  run --skill <name> <path>     Run a script from a skill's scripts/ directory
+  <skill-name>                  Print a skill's SKILL.md content to stdout
+  <skill-name> --command="..."  Execute a skill command
+  help                          Show this help`)
+    return 0
+  }
+
+  const cmd = args[0]
+
+  if (cmd === 'init') {
+    await initCommand(args.slice(1))
+    return 0
+  }
+
+  if (cmd === 'run') {
+    const code = await runCommand(args.slice(1))
+    return code
+  }
+
+  const skillContent = await printSkill(cmd)
+  if (skillContent === null) {
+    console.error(`Unknown command or skill: ${cmd}`)
+    return 1
+  }
+  console.log(skillContent)
+  return 0
+}

package/lib/commands/init.js

@@ -0,0 +1,117 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { resolveAgents, resolveSkill, PKG_ROOT } from '../util/paths.js'
+
+function readPackageAgents() {
+  return readFileSync(resolveAgents(), 'utf-8')
+}
+
+function readPackageOpensassiSkill() {
+  return readFileSync(resolveSkill('opensassi'), 'utf-8')
+}
+
+function defaultOpencodeJson() {
+  return JSON.stringify({
+    $schema: "https://opencode.ai/config.json",
+    permission: {
+      skill: "allow",
+      read: "allow",
+      edit: "allow",
+      glob: "allow",
+      grep: "allow",
+      bash: "ask",
+      task: "allow",
+      webfetch: "allow"
+    },
+    instructions: ["AGENTS.md"],
+    mcp: {
+      playwright: {
+        type: "local",
+        command: ["npx", "@playwright/mcp@latest", "--headless"],
+        enabled: true
+      },
+      debugger: {
+        type: "local",
+        command: ["gdb-mcp-server"],
+        enabled: true
+      }
+    }
+  }, null, 2) + '\n'
+}
+
+export async function initCommand(args) {
+  const cwd = process.cwd()
+  const dryRun = args.includes('--dry-run')
+  const force = args.includes('--force')
+
+  const hasAgents = existsSync(resolve(cwd, 'AGENTS.md'))
+  const hasOpencodeDir = existsSync(resolve(cwd, '.opencode'))
+  const hasOpencodeJson = existsSync(resolve(cwd, '.opencode/opencode.json'))
+  const hasOpensassiSkill = existsSync(resolve(cwd, '.opencode/skills/opensassi/SKILL.md'))
+  const hasGitignore = existsSync(resolve(cwd, '.gitignore'))
+
+  if (hasOpensassiSkill && !force) {
+    console.log('Already initialized. Use --force to refresh.')
+    return
+  }
+
+  const pkgAgents = readPackageAgents()
+  const pkgSkill = readPackageOpensassiSkill()
+
+  if (dryRun) {
+    console.log('Dry-run: would write the following files')
+    if (!hasAgents) console.log('  CREATE AGENTS.md  (from package)')
+    else console.log('  APPEND AGENTS.md  (append opensassi instructions)')
+    console.log('  WRITE .opencode/skills/opensassi/SKILL.md')
+    console.log('  WRITE .opencode/opencode.json')
+    if (!hasGitignore) console.log('  CREATE .gitignore')
+    console.log('  APPEND .gitignore  (.opencode/skills/)')
+    return
+  }
+
+  const separator = '\n---\n\n'
+  const agentHeader = 'Instructions from: @opensassi/opencode\n\n'
+
+  if (!hasAgents) {
+    writeFileSync(resolve(cwd, 'AGENTS.md'), pkgAgents, 'utf-8')
+    console.log('Created AGENTS.md')
+  } else {
+    const existing = readFileSync(resolve(cwd, 'AGENTS.md'), 'utf-8')
+    if (!existing.includes('@opensassi/opencode')) {
+      appendFileSync(resolve(cwd, 'AGENTS.md'), separator + agentHeader + pkgAgents, 'utf-8')
+      console.log('Appended opensassi instructions to AGENTS.md')
+    } else {
+      console.log('AGENTS.md already includes opensassi instructions')
+    }
+  }
+
+  {
+    const skillDir = resolve(cwd, '.opencode/skills/opensassi')
+    if (!existsSync(skillDir)) mkdirSync(skillDir, { recursive: true })
+    writeFileSync(resolve(skillDir, 'SKILL.md'), pkgSkill, 'utf-8')
+    console.log('Wrote .opencode/skills/opensassi/SKILL.md')
+  }
+
+  if (!hasOpencodeJson) {
+    const opencodeDir = resolve(cwd, '.opencode')
+    if (!existsSync(opencodeDir)) mkdirSync(opencodeDir, { recursive: true })
+    writeFileSync(resolve(opencodeDir, 'opencode.json'), defaultOpencodeJson(), 'utf-8')
+    console.log('Wrote .opencode/opencode.json')
+  } else {
+    console.log('.opencode/opencode.json already exists (skipped)')
+  }
+
+  const gitignorePath = resolve(cwd, '.gitignore')
+  if (!hasGitignore) {
+    writeFileSync(gitignorePath, '.opencode/skills/\n', 'utf-8')
+    console.log('Created .gitignore with .opencode/skills/ rule')
+  } else {
+    const gitignore = readFileSync(gitignorePath, 'utf-8')
+    if (!gitignore.includes('.opencode/skills/')) {
+      appendFileSync(gitignorePath, '\n.opencode/skills/\n', 'utf-8')
+      console.log('Added .opencode/skills/ to .gitignore')
+    } else {
+      console.log('.opencode/skills/ already in .gitignore')
+    }
+  }
+}

package/lib/commands/print-agents.js

@@ -0,0 +1,6 @@
+import { readFileSync } from 'node:fs'
+import { resolveAgents } from '../util/paths.js'
+
+export async function printAgents() {
+  return readFileSync(resolveAgents(), 'utf-8')
+}

package/lib/commands/print-skill.js

@@ -0,0 +1,8 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolveSkill } from '../util/paths.js'
+
+export async function printSkill(name) {
+  const path = resolveSkill(name)
+  if (!existsSync(path)) return null
+  return readFileSync(path, 'utf-8')
+}

package/lib/commands/run.js

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs'
+import { spawn } from 'node:child_process'
+import { resolveSkillScript, resolveScript, PKG_ROOT } from '../util/paths.js'
+
+export async function runCommand(args) {
+  const skillIdx = args.indexOf('--skill')
+  let resolvedPath
+  let restArgs
+
+  if (skillIdx !== -1) {
+    const skillName = args[skillIdx + 1]
+    if (!skillName) {
+      console.error('--skill requires a name argument')
+      return 1
+    }
+    const scriptPath = args[skillIdx + 2]
+    if (!scriptPath) {
+      console.error('--skill requires a script path after the skill name')
+      return 1
+    }
+    resolvedPath = resolveSkillScript(skillName, scriptPath)
+    restArgs = args.slice(skillIdx + 3)
+  } else {
+    const scriptPath = args[0]
+    if (!scriptPath) {
+      console.error('Usage: opencode run <script> [args...]')
+      return 1
+    }
+    resolvedPath = resolveScript(scriptPath)
+    restArgs = args.slice(1)
+  }
+
+  if (!existsSync(resolvedPath)) {
+    console.error(`Script not found: ${resolvedPath}`)
+    return 1
+  }
+
+  const ext = resolvedPath.split('.').pop()
+
+  return new Promise((resolve) => {
+    let proc
+    if (ext === 'sh' || ext === 'bash') {
+      proc = spawn('bash', [resolvedPath, ...restArgs], { stdio: 'inherit' })
+    } else if (ext === 'ps1') {
+      proc = spawn('powershell', ['-File', resolvedPath, ...restArgs], { stdio: 'inherit' })
+    } else if (ext === 'js' || ext === 'mjs') {
+      proc = spawn(process.execPath, [resolvedPath, ...restArgs], { stdio: 'inherit' })
+    } else {
+      proc = spawn(resolvedPath, restArgs, { stdio: 'inherit' })
+    }
+    proc.on('exit', (code) => resolve(code ?? 1))
+    proc.on('error', (err) => {
+      console.error(`Failed to run script: ${err.message}`)
+      resolve(1)
+    })
+  })
+}

package/lib/index.js

@@ -0,0 +1,4 @@
+export { init } from './commands/init.js'
+export { run } from './commands/run.js'
+export { printSkill } from './commands/print-skill.js'
+export { printAgents } from './commands/print-agents.js'

package/lib/util/paths.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+export const PKG_ROOT = resolve(__dirname, '../..')
+
+export function resolveScript(path) {
+  return resolve(PKG_ROOT, 'scripts', path)
+}
+
+export function resolveSkillScript(skillName, path) {
+  return resolve(PKG_ROOT, 'skills', skillName, 'scripts', path)
+}
+
+export function resolveSkill(skillName) {
+  return resolve(PKG_ROOT, 'skills', skillName, 'SKILL.md')
+}
+
+export function resolveAgents() {
+  return resolve(PKG_ROOT, 'AGENTS.md')
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@opensassi/opencode",
+  "version": "0.1.0",
+  "description": "Agent skill harness for opencode — bootstrap, system-design, git workflow, profiling, and more",
+  "type": "module",
+  "bin": {
+    "opencode": "bin/opencode.js"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "scripts/",
+    "AGENTS.md",
+    "skills-index.json",
+    "!scripts/FlameGraph/",
+    "!**/*.spec.md"
+  ],
+  "scripts": {
+    "extract": "node scripts/extract-artifacts.js",
+    "extract:file": "node scripts/extract-artifacts.js --file",
+    "test-artifacts": "node scripts/test-artifacts.js",
+    "test-artifact": "node scripts/test-artifacts.js --file",
+    "validate-all": "node scripts/extract-artifacts.js --all && node scripts/test-artifacts.js",
+    "verify-animation": "node scripts/verify-artifact.js",
+    "check-artifacts": "node scripts/check-artifacts.js",
+    "start": "bin/opencode.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "playwright": "^1.60.0",
+    "sharp": "^0.34.5"
+  }
+}

package/scripts/asm-optimizer/run-baseline.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# run-baseline.sh
+# Build a tagged release baseline and run the profiling matrix.
+#
+# USAGE: Customize the variables below for your project, then run:
+#   ./scripts/asm-optimizer/run-baseline.sh [--rebuild]
+#
+#   --rebuild  Force rebuild even if baseline binaries exist
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+BASELINE_DIR="$REPO_ROOT/perf/baseline"
+
+# === CUSTOMIZE THESE FOR YOUR PROJECT ===
+PROJECT_NAME="my-project"
+TAG="v1.0.0"
+BASELINE_SRC="$BASELINE_DIR/$PROJECT_NAME-$TAG"
+BASELINE_BUILD="$BASELINE_DIR/build"
+BASELINE_BIN="$BASELINE_SRC/build"
+PROFILES_DIR="$BASELINE_DIR/profiles/default"
+REPORTS_DIR="$BASELINE_DIR/reports"
+TEST_INPUT="$REPO_ROOT/test/data/input.yuv"
+PROGRAM_ARGS=("--input" "$TEST_INPUT" "--frames" "50")
+# =========================================
+
+# Output tree:
+#   perf/baseline/
+#   ├── <project>-<tag>/       ← git worktree checkout
+#   ├── build/                  ← Release cmake build
+#   ├── profiles/default/
+#   │   ├── fast-5fr/
+#   │   ├── fast-50fr/
+#   │   ├── slow-5fr/
+#   │   └── slow-50fr/
+#   └── reports/
+#       └── profile-summary.json
+
+# Perf counter groups
+PERF_COMPREHENSIVE="-d -d -d"
+PERF_SIMD="-e fp_arith_inst_retired.256b_packed_single,fp_arith_inst_retired.128b_packed_single,fp_arith_inst_retired.scalar_single"
+PERF_MEM_UOP="-e mem_load_uops_retired.l1_hit,mem_load_uops_retired.l1_miss,mem_load_uops_retired.l2_hit,mem_load_uops_retired.l2_miss,mem_load_uops_retired.l3_hit,mem_load_uops_retired_misc.l3_miss"
+
+run_perf_pass() {
+    local label="$1"
+    local config="$2"
+    local frames="$3"
+    local events="$4"
+    local suffix="$5"
+
+    local outdir="$PROFILES_DIR/$label"
+    mkdir -p "$outdir"
+    local output="$outdir/perf-${suffix}.txt"
+
+    echo "  [perf:$suffix] $config ${frames}fr ..."
+    perf stat $events -o "$output" \
+        "$BASELINE_BIN/$PROJECT_NAME" \
+        "${PROGRAM_ARGS[@]}" \
+        --config "$config" \
+        --frames "$frames" \
+        2>/dev/null || true
+
+    if [ -f "$output" ]; then
+        sed -i "1i# RUN: config=$config frames=$frames date=$(date -Iseconds)" "$output"
+    fi
+}
+
+run_timing_pass() {
+    local label="$1"
+    local config="$2"
+    local frames="$3"
+
+    local outdir="$PROFILES_DIR/$label"
+    mkdir -p "$outdir"
+    local output="$outdir/timing.txt"
+
+    echo "  [timing] $config ${frames}fr ..."
+    for i in 1 2 3; do
+        /usr/bin/time -f "real %e user %U sys %S" -a -o "$output" \
+            "$BASELINE_BIN/$PROJECT_NAME" \
+            "${PROGRAM_ARGS[@]}" \
+            --config "$config" \
+            --frames "$frames" \
+            2>/dev/null
+    done
+
+    sed -i "1i# RUN: config=$config frames=$frames date=$(date -Iseconds)" "$output"
+}
+
+# ----------------------------------------------------------------
+
+step() { echo ""; echo "==> $1"; }
+
+step "1. Create baseline directory structure"
+mkdir -p "$BASELINE_DIR" "$PROFILES_DIR" "$REPORTS_DIR"
+
+step "2. Checkout $TAG via git worktree"
+if [ ! -d "$BASELINE_SRC" ] || [ ! -f "$BASELINE_SRC/CMakeLists.txt" ]; then
+    git -C "$REPO_ROOT" worktree add -f "$BASELINE_SRC" "$TAG"
+    echo "  checked out $TAG at $BASELINE_SRC"
+else
+    echo "  source already exists"
+fi
+
+step "3. Build Release binary"
+if [ ! -f "$BASELINE_BIN/$PROJECT_NAME" ] || [ "${1:-}" == "--rebuild" ]; then
+    cmake -S "$BASELINE_SRC" -B "$BASELINE_BUILD" \
+        -DCMAKE_BUILD_TYPE=Release
+    cmake --build "$BASELINE_BUILD" -j "$(nproc)"
+    echo "  build complete: $BASELINE_BIN/$PROJECT_NAME"
+else
+    echo "  binary already exists"
+fi
+
+# Verify binary
+"$BASELINE_BIN/$PROJECT_NAME" --version 2>/dev/null || echo "  (no --version flag)"
+
+step "4. Run profiling matrix"
+CONFIGS=("fast" "slow")
+FRAME_COUNTS=(5 50)
+
+for config in "${CONFIGS[@]}"; do
+    for frames in "${FRAME_COUNTS[@]}"; do
+        label="${config}-${frames}fr"
+        echo "--- Profiling $label ---"
+
+        run_perf_pass "$label" "$config" "$frames" "$PERF_COMPREHENSIVE" "comprehensive"
+        run_perf_pass "$label" "$config" "$frames" "$PERF_SIMD"          "simd"
+        run_perf_pass "$label" "$config" "$frames" "$PERF_MEM_UOP"       "mem-uop"
+        run_timing_pass  "$label" "$config" "$frames"
+    done
+done
+
+step "5. Generate summary report"
+cat > "$REPORTS_DIR/profile-summary.json" << REPORT_EOF
+{
+  "baseline": "$TAG",
+  "date": "REPLACE_DATE",
+  "configs": ["fast", "slow"],
+  "frames": [5, 50],
+  "counter_groups": [
+    "comprehensive", "simd", "mem-uop"
+  ]
+}
+REPORT_EOF
+
+sed -i "s/REPLACE_DATE/$(date -Iseconds)/" "$REPORTS_DIR/profile-summary.json"
+
+echo ""
+echo "=========================================="
+echo "Baseline setup complete!"
+echo "  Source: $BASELINE_SRC"
+echo "  Build:  $BASELINE_BUILD"
+echo "  Binary: $BASELINE_BIN/$PROJECT_NAME"
+echo "  Profiles: $PROFILES_DIR/"
+echo "  Report:  $REPORTS_DIR/profile-summary.json"
+echo "=========================================="