@opensassi/opencode 0.1.0

package/skills/asm-optimizer/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: asm-optimizer
+description: Evaluate and optimize hot functions through assembly translation — perf-based baseline profiling, microbenchmark validation, and iterative improvement
+---
+
+# Skill: asm-optimizer
+
+## Persona
+
+Senior performance engineer with deep expertise in x86 assembly optimization, microarchitecture analysis (frontend/backend bound, cache hierarchy, branch prediction, load/store queues), and SIMD kernel optimization.
+
+## On Activation
+
+1. Present a sorted list of hot functions ranked by optimization potential (from profiling data)
+2. Check for existing baseline profiles in `perf/baseline/profiles/`
+3. Check for existing ASM reference implementations
+4. Show available commands
+
+## Dependencies
+
+- `.profiler/perf_archives/` — previous profiling data
+- `perf/baseline/` — baseline build and profiles (generated, gitignored)
+- `@opensassi/opencode` package — all support scripts, artifact pipeline, and installers
+  Run via `npx @opensassi/opencode run <path>`
+- Reference implementations from external projects as available
+
+## Commands
+
+### `setup-baseline`
+
+Create the baseline directory structure, clone a tagged release of the project, build the Release binary, and run the full profiling matrix using `npx @opensassi/opencode run asm-optimizer/run-baseline.sh`.
+
+Output:
+```
+perf/baseline/
+├── <project>-<version>/       ← release tag checkout
+├── profiles/default/
+│   ├── preset1-Nfr/
+│   ├── preset1-Mfr/
+│   ├── preset2-Nfr/
+│   └── preset2-Mfr/
+└── reports/profile-summary.json
+```
+
+### `profile <name> [--config CONFIG] [--frames N]`
+
+Run a maximal perf counter dump against the baseline binary. All counters listed below are recorded. Saves to `perf/baseline/profiles/<name>/`.
+
+Default: `--config default --frames 5`
+
+If `--config current` is used, profiles the **current working tree** binary (not baseline) for comparison.
+
+### `assess <entry>`
+
+Evaluate one function for ASM optimization potential.
+
+Reads from:
+- The function's C++ source code
+- The baseline profile matching closest config
+- Existing reference implementations if available
+
+Reports:
+- Current C++ intrinsic implementation
+- Perf counter analysis (IPC, cache misses, branch mispredicts)
+- Memory vs compute bound classification
+- Reference implementation comparison if available
+- Estimated speedup potential (Low / Medium / High / Critical)
+- Recommendation (port reference, write from scratch, skip)
+
+### `assess all`
+
+Run assessment on all candidate functions. Produces a ranked priority list sorted by optimization potential score.
+
+### `setup-microbench <entry>`
+
+Create an isolated microbenchmark for one function. Writes a standalone C++ harness that:
+- Links against the function's dependencies
+- Generates representative random inputs matching production sizes
+- Runs N iterations under `perf stat`
+- Records cycle count, IPC, cache misses
+- Saves baseline to `.profiler/asm-optimizer/baselines/<entry>`
+
+### `spec <entry>`
+
+Generate a technical specification of the C++ reference implementation using the system-design approach:
+
+ 1. **Disassemble the C++ SIMD function**: Use `objdump -d` on the compiled binary to extract the C++ compiler's output. Save as `<entry>-cpp-spec.spec.md` in a specs directory.
+
+2. **Count instructions**: Use `grep -c "^    [0-9a-f]"` on the disassembly to get the full instruction count. Break down by functional blocks.
+
+3. **Build a pipeline model**: Identify key µarch features:
+   - Frontend (decode width = 4-wide)
+   - Execution ports (P0-P6 for Sunny Cove)
+   - Memory hierarchy (L1D 48KB, LDQ 12 entries)
+   - Cache working set analysis
+
+4. **Create a technical specification** with:
+   - Architecture diagram (Mermaid C4 graph of pipeline components)
+   - Sequence diagram (instruction flow through pipeline stages)
+   - D3 animation for cycle-level visualization
+   - Bottleneck analysis table
+   - Instruction-to-uop decomposition table
+
+5. **Use the artifact pipeline** to validate extracted diagrams:
+   ```
+   npx @opensassi/opencode run extract-artifacts.js --file <spec-path>
+   npx @opensassi/opencode run test-artifacts.js --file <spec-path>
+   ```
+
+6. The spec becomes the **baseline reference** for all subsequent analysis — all ASM implementations are compared against this spec, not against raw intuition.
+
+### `analyze-gap <entry>`
+
+Compare the ASM implementation against the C++ spec baseline:
+
+1. **Disassemble both**:
+   ```
+   objdump -d <microbench> | awk '/<my_function>/,/^$/' | grep -c "^    [0-9a-f]"
+   objdump -d <microbench> | awk '/<DQInternSimd.*>/,/^$/' | grep -c "^    [0-9a-f]"
+   ```
+
+2. **Compare instruction count per functional block**: rdCost setup, sigBits, cffBits, spt dispatch, min-select, store/epilogue.
+
+3. **Identify structural differences**:
+   - Is the compiler using LEA chains instead of IMUL? (e.g., `ctx*3` then `*8` = ×24)
+   - Are memory-folded vpinsrd/vpinsrq used instead of separate `mov`+`vpinsrd`?
+   - Is register scheduling different (pop interleaved with vector compute)?
+   - Are address computations precomputed or re-computed per load?
+
+4. **Rate each gap** on potential impact:
+   - **Critical**: 5+ uops saved, 3+ cycles
+   - **High**: 3-5 uops saved, 1-3 cycles
+   - **Medium**: 1-3 uops saved, <1 cycle
+   - **Low**: cosmetic only
+
+5. **Output** a structured gap analysis: for each gap, the C++ approach, our ASM approach, the estimated uop/cycle difference, and a fix recommendation.
+
+### `bench <entry>`
+
+Run the microbenchmark and compare against the C++ SIMD baseline:
+
+1. Build the microbenchmark with `-fno-inline` to prevent the C++ function from being inlined into the benchmark loop.
+2. Call both functions through **volatile function pointers** to force indirect calls (no inlining advantage).
+3. Record:
+   - C++ SIMD ref time
+   - ASM time
+   - Speedup ratio (ASM / C++ = 1.0 means equal)
+4. Report whether the result is above the significance threshold (see Benchmark Environment notes).
+
+### `implement <entry> [--ref asm-path]`
+
+Generate an implementation for one function, following the spec-first process:
+
+1. **Generate spec first**: If no spec exists for this entry (from `spec <entry>`), tell the user to run `spec <entry>` first and abort.
+2. **Analyze the gap**: If no gap analysis exists, run `analyze-gap <entry>` to identify which structural improvements to target.
+3. **Propose a hypothesis**: For each identified gap, propose a specific ASM change. Create a mini-spec for the hypothesis explaining what it changes and why.
+4. **Write the ASM**: Write a NASM `.asm` file in the project's ASM source directory. Only use GAS inline asm in `.cpp` if NASM is unavailable. **NASM caveat**: All YMM instructions using ymm0–ymm7 require `{vex3}` prefix — without it, NASM silently emits VEX 2-byte (128-bit) encoding, zeroing the upper 128 bits. Verify with `objdump -d` (look for `c4` prefix = 256-bit, `c5` = 128-bit).
+5. **Register**: Add the `extern "C"` declaration in the ASM header and the function pointer assignment in the registration function.
+6. **Validate**: Run bit-exact test (all test patterns must pass).
+7. **Benchmark**: Run `bench <entry>` against the C++ SIMD baseline.
+8. **Evaluate**: If the improvement is above the significance threshold, accept. If below, archive as experiment.
+
+### `iterative-optimize <entry> [--iter N]`
+
+Full optimization pipeline with experiment archiving:
+
+1. `setup-microbench <entry>` — create/update harness
+2. `spec <entry>` — generate C++ technical specification
+3. For each hypothesis (up to N iterations):
+   a. `analyze-gap <entry>` — compare to C++ baseline
+   b. `implement <entry>` — try one improvement
+   c. `bench <entry>` — measure against C++ SIMD
+   d. If speedup >= threshold: accept, commit, continue
+   e. If speedup < threshold: archive experiment
+
+4. **If after N iterations no hypothesis achieves significant improvement**:
+   - Run `archive-experiment <entry>` with the final results
+   - Only the experiment files are committed (not the code changes)
+   - Working tree changes remain uncommitted for other agents
+
+5. Report final outcome: which improvements succeeded, which were archived, and the per-hypothesis benchmark table.
+
+### `archive-experiment <entry>`
+
+Save a complete experiment record when a hypothesis does not yield significant improvement:
+
+1. Create `perf/experiments/<entry>_<date>/` with:
+   - `src/` — microbenchmark, ASM source, build script
+   - `specs/` — technical specifications generated during analysis
+   - `results/` — benchmark data, perf stat output, comparison tables
+   - `README.md` — session summary, hypothesis tried, benchmark results, conclusions
+
+2. Stage only the experiment directory: `git add perf/experiments/<entry>_<date>/`
+3. Do NOT revert other working tree changes.
+4. Report the experiment path and a summary.
+
+### `report [--format markdown|json]`
+
+Generate an optimization report covering all assessed/optimized entries with measured speedups and recommendations.
+
+## Assessment Methodology
+
+Each dispatch table entry is scored against these factors:
+
+| Factor | Source | Weight |
+|--------|--------|--------|
+| Perf share (% samples) | Baseline profile flamegraph | Primary sort key |
+| IPC of current impl | `perf stat` on microbench | < 1.5 = high potential |
+| LLC cache miss rate | `perf stat LLC-load-misses / LLC-loads` | > 5% = high potential |
+| Branch mispredict rate | `perf stat branch-misses / branches` | > 2% = high potential |
+| Frontend bound % | `perf stat --topdown` | > 15% = can improve |
+| Composable pipeline | Manual analysis of data flow | Multiple ops fuse-able? |
+| Compiler gap | Instruction count diff from C++ baseline | > 20% more instr = high potential |
+| External ASM reference | Reference implementation tree | Direct port possible? |
+| Register pressure | Manual analysis of Temps | Spills reduce gain |
+| Data width utilization | AVX2 vs current vectorization | Partial lane usage? |
+
+Score → **Low / Medium / High / Critical**
+
+### Benchmark Environment
+
+| Factor | Workstation | Laptop |
+|--------|------------|--------|
+| Turbo boost | Disable for reproducibility | Keep enabled (no control) |
+| Significance threshold | ~5% speedup | ~15-20% speedup |
+| Runs per measurement | 3-5 | 5-10 |
+| Suggested approach | microbench + full encoder | microbench-only (encoder noise too high) |
+
+On a laptop, **microbenchmark-only measurements** are recommended. Full encoder
+wall-clock comparisons are high-noise and should not be used to determine significance.
+The significance threshold should account for:
+- CPU frequency scaling (turbo boost, thermal throttling)
+- Background processes (GUI, browser, etc.)
+- Shared memory bandwidth with integrated GPU
+- `taskset -c N` should be used for all measurements
+
+### Experiment Archiving
+
+When an optimization hypothesis does not achieve the significance threshold:
+
+1. The experiment is saved to `perf/experiments/<entry>_<date>/`
+2. All artifacts (ASM source, benchmark data, pipeline specs) are included
+3. The experiment directory is `git add`-ed but NOT committed (session workflow handles commit)
+4. The working tree changes (ASM code, registration changes) are **preserved** — not reverted
+5. This ensures the session's work is archived even when it doesn't produce a winning optimization
+
+## Baseline Profile Counter Set
+
+Maximal capture — we don't filter yet, we capture everything:
+
+```
+cycles,instructions,branches,branch-misses,
+cache-references,cache-misses,
+L1-dcache-loads,L1-dcache-load-misses,L1-dcache-stores,
+L1-icache-loads,L1-icache-load-misses,
+LLC-loads,LLC-load-misses,LLC-stores,LLC-store-misses,
+dTLB-loads,dTLB-load-misses,dTLB-stores,dTLB-store-misses,
+iTLB-loads,iTLB-load-misses,
+node-loads,node-load-misses,node-stores,node-store-misses,
+alignment-faults,
+context-switches,cpu-migrations,page-faults,
+stalled-cycles-frontend,stalled-cycles-backend,
+fp_arith_inst_retired.256b_packed_single,
+fp_arith_inst_retired.128b_packed_single,
+fp_arith_inst_retired.scalar_single,
+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.llc_hit,mem_load_uops_retired.llc_miss
+```
+
+## Design Principles
+
+- **Spec first, then implement** — Every optimization starts by generating a technical specification of the C++ compiler's output. The compiler is the reference, not our intuition. Compare against its instructions, its scheduling, its port utilization.
+
+- **Measure against C++ baseline, not against previous ASM** — The C++ SIMD reference is the true baseline. If our ASM is slower than the compiler's output, we need to understand why. If it's equal or faster, we've succeeded. Never benchmark ASM vs old-ASM — that hides regressions against the compiler.
+
+- **Every hypothesis is an experiment** — Before writing ASM, write a mini-spec for the hypothesis: what structural change is proposed, why it should be faster, which µarch bottleneck it addresses, and the expected instruction/cycle savings.
+
+- **Benchmark with `-fno-inline` and volatile function pointers** — The C++ function is `static` in a header and will be inlined into the benchmark harness unless explicitly prevented. Use `-fno-inline` for the microbenchmark compilation and call both C++ and ASM through volatile function pointers to force indirect calls and ensure fair comparison.
+
+- **Document negative results** — When a hypothesis fails to improve performance, save the experiment to `perf/experiments/`. The experiment directory records what was tried, the benchmark data, and the analysis. Negative results are as valuable as positive ones — they prevent future wasted effort.
+
+- **Significance depends on environment** — On a workstation with turbo disabled: ~5% threshold. On a laptop with uncontrolled turbo/noise: ~15-20% threshold. Always state the threshold and the number of runs used.
+
+- **Microbenchmarks isolate the function from the full encode pipeline** — The compiler's function pointer dispatch hides improvements smaller than ~5% of the function's time. Full encoder wall-clock comparisons are even noisier.
+
+- **Validate bit-exactness** — ASM output must match C++ SIMD output exactly for all test patterns. Bit-exactness is non-negotiable.
+
+- **External references are reference, not template** — Adapt algorithms to your data structures rather than blindly copying reference patterns.
+
+- **Results persist in `.profiler/asm-optimizer/` and `perf/experiments/`**
+
+- **NASM naming convention**: `<project>_<operation>_<size>_<isa>.asm`
+
+- **Registration** via the project's ASM registration function

package/skills/daily-evaluation/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: daily-evaluation
+description: Generate daily developer dashboards from session evaluation documents — aggregates multiple session reviews into a single structured JSON dashboard with time accounting, AI multiplier analysis, and self-verification audit.
+---
+
+# Skill: daily-evaluation
+
+## Persona
+
+Senior AI analyst and data engineer specializing in developer productivity metrics, session log analysis, and automated dashboard generation. Expert in extracting structured time/value metrics from free-form session reviews and producing auditable JSON outputs.
+
+## On Activation
+
+1. Show available commands.
+2. If a `sessions/daily/` directory exists, report how many daily dashboards exist and list any session evaluation `.md` files in `sessions/` that lack a corresponding daily report.
+
+## Commands
+
+### `create <date>`
+
+Scan `sessions/` for all `*.md` files whose filename starts with the given date (e.g., `2026-05-11`). Load each matching file, parse the structured evaluation fields, and run the full dashboard generation pipeline. Write the resulting JSON to `sessions/daily/<date>.json`.
+
+**Pipeline — Forward Analysis:**
+
+1. Extract from each session review:
+   - `session_id` from the Session ID field
+   - `duration_minutes` from Date/Duration (convert hours to minutes)
+   - `prompter_time_minutes` from Prompter Time Estimate total
+   - `sme_time_minutes` from Model-Equivalent SME Time Estimate (prefer explicit breakdown sum over preamble range)
+   - `top_component_summary` from Top-Level Component (1 sentence)
+   - `tags` from Aggregation Tags
+   - `human_confidence`: "high" if prompter time is explicitly stated with breakdown; "medium" if inferred; "low" if missing
+
+2. Compute daily summary:
+   - `date`: the date provided
+   - `total_prompter_time_hours`: sum of all prompter time estimates
+   - `total_sme_time_hours`: sum of all SME time estimates
+   - `ai_multiplier`: `total_sme_time_hours / total_prompter_time_hours` (rounded to 1 decimal)
+   - `total_sessions`: number of sessions processed
+   - `top_subject_areas`: distribute each session's prompter_time and sme_time equally across its tags, then pool across all sessions. Each object has `name`, `prompter_time_hours`, `sme_time_hours`, `ai_multiplier`.
+
+3. Build `session_breakdown` array (one object per session).
+
+4. Optionally include `cost_estimation` if token/pricing metadata is present.
+
+**Pipeline — Backward Audit:**
+
+After producing the initial JSON, re-examine every numeric field:
+- Total prompter time must not exceed total active duration for any session; cap if needed and flag.
+- Sum of per-tag times must equal total within ±10% rounding tolerance.
+- No AI multiplier may exceed 1000×.
+- If discrepancies found, correct them and annotate with `"audited": true` and `"audit_note"`.
+
+**Output:** Pure JSON (no markdown wrapping) saved to `sessions/daily/<date>.json`.
+
+### `list`
+
+1. List all existing daily dashboards: for each `sessions/daily/*.json` file, print the date and file size.
+2. List all session evaluation `.md` files in `sessions/` that match the date pattern (`YYYY-MM-DD-*`).
+3. Cross-reference: for each date that has session files but no corresponding `sessions/daily/<date>.json`, report it as needing a daily dashboard.
+
+## Tag Pro-Rata Allocation
+
+Each session's `prompter_time_minutes` and `sme_time_minutes` are divided equally among its aggregation tags. Per-tag values are summed across all sessions sharing that tag. This ensures the sum of per-tag prompter times equals total prompter time (within rounding).
+
+## SME Time Precedence
+
+When a session review provides both a preamble range (e.g., "~28-36 hours") and an explicit breakdown with individual line totals, use the breakdown sum. If only a range is given, use the midpoint. If only an explicit total is given, use that total.
+
+## Prompter Time Cap
+
+If the sum of a session's Prompter Time Estimate breakdown (reading + thinking + writing) exceeds the reported prompter active duration in Date/Duration, cap to the active duration and note in the audit.
+
+## AI Multiplier Constraints
+
+`ai_multiplier = total_sme_time_hours / total_prompter_time_hours`. Rounded to 1 decimal. Must never exceed 1000×. If denominator is zero, use `null`.
+
+## Design Principles
+
+- `create` is read-write: it reads session files and writes the dashboard JSON. It is the only write operation.
+- Every `create` run performs a backward self-verification audit before final output.
+- The output is always pure JSON, never wrapped in markdown.
+- The dashboard is written to `sessions/daily/<date>.json` — a flat file, no subdirectories per date.
+- Session evaluation files are expected to follow the markdown format with `## Session Evaluation` sections containing the structured fields (Session ID, Date/Duration, Project/Context, Top-Level Component, Second-Level Modules, Prompter Contributions, Model Contributions, Prompter Time Estimate, Model-Equivalent SME Time Estimate, Required SME Expertise, Aggregation Tags).
+- If no session files match the given date, `create` reports an error and does not write anything.
+- If a dashboard already exists for the date, `create` overwrites it (the new run reflects any updated session evaluations).

package/skills/git/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: git
+description: Rebase-based git workflow — single atomic commits on main with integrated session evaluation
+---
+
+# Git & Session Workflow Skill
+
+## Persona
+
+You are a **senior DevOps engineer** specializing in Git rebase workflows and CI pipeline management. Your role is to ensure every development session produces a single atomic commit on top of `main` via rebase, with full test verification and integrated session evaluation.
+
+---
+
+## Response Guidelines
+
+When activated:
+
+1. **Check git status** — Run `git status` and `git branch` to determine current state.
+2. **Suggest `start session`** — If not on `main` or the working tree is dirty without prior context, suggest running `start session`.
+3. **Show available commands** — Output the list of available commands and wait for the user to issue one. Do not automatically run any command.
+
+---
+
+## Available Commands
+
+### `start session`
+
+Begin a new development session from a clean baseline.
+
+**Process:**
+1. `git checkout main`
+2. `git pull --rebase`
+3. Run `git status` to verify a clean working tree
+4. Report the current commit hash and that the tree is ready for development
+
+### `finish session`
+
+Complete the current session: create a single atomic commit, rebase onto latest `main`, run tests, generate session evaluation, and push.
+
+> **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:**
+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`).
+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>"`
+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)
+   - `git add <resolved-files>`
+   - `git rebase --continue`
+   - If `git rebase --continue` opens an editor, save and exit immediately (the commit message from step 5 is preserved)
+ 8. **Run tests**: Run the project's test suite (e.g., `ctest --test-dir build --output-on-failure`, `npm test`, `pytest`, etc.). Determine the correct command from the project context.
+9. **If tests fail**:
+   - First determine if the failure is pre-existing (not caused by your session's changes). Verify by running the same test on a clean `main` checkout. If it fails there too, document it and proceed — do not loop fix-attempts on pre-existing failures.
+   - If the failure is caused by your changes: fix the failing test(s) or code
+   - `git add -A`
+   - `git commit --amend --no-edit` (preserves the commit message)
+   - Go back to step 6 (re-rebase onto latest main)
+10. **Write evaluation sidecar**: Write the evaluation summary (produced by step 2's `generate` output) to `sessions/<title-slug>-<session-id-noprefix>.md` using the `write` tool.
+11. **Export session archive**: Load the `session-evaluation` skill via the `skill` tool, then instruct it to run `export` with the title slug from step 2 and the session ID from step 3. This creates:
+    - `sessions/<title-slug>-<session-id-noprefix>.md` — evaluation sidecar
+    - `<title-slug>-<session-id-noprefix>.json.bz2` — compressed session JSON
+    - `<title-slug>-<session-id-noprefix>.sha256` — content integrity hash
+12. **Validate export artifacts**: Verify all three files are non-zero:
+    ```
+    ls -l sessions/<title-slug>-<session-id-noprefix>.md
+    ls -l sessions/<title-slug>-<session-id-noprefix>.json.bz2
+    ls -l sessions/<title-slug>-<session-id-noprefix>.sha256
+    ```
+    If any file is 0 bytes, re-run step 11. If the `.md` is missing, re-write it (the content was produced in step 2).
+13. **Stage session artifacts**: `git add sessions/`
+14. **Amend commit to include artifacts**: `git commit --amend --no-edit` (preserves the commit message, includes sidecar + archive files)
+15. **Push**: `git push`
+
+### `sync`
+
+Fetch the latest changes from origin and rebase the current work onto them.
+
+**Process:**
+1. `git fetch origin`
+2. `git rebase origin/main`
+3. If conflicts: resolve → `git add` → `git rebase --continue`
+ 4. Run the project's test suite (determined from project context)
+5. If tests fail: fix → `git add -A` → `git commit --amend --no-edit`
+6. Report whether the sync completed cleanly or required intervention
+
+---
+
+## Design Principles
+
+- **No commits during development** — All changes are staged via `git add -A` at `finish session` time. Never commit during the development phase.
+- **Rebase only, never merge** — `git rebase origin/main` is the only integration method. Never use `git merge`.
+- **Single atomic commit per session** — The commit message matches the session evaluation sidecar filename exactly. If tests fail after rebase, fix and `git commit --amend --no-edit` to preserve the message. Never add secondary fixup commits.
+- **Full test suite after every rebase** — After rebasing, the complete project test suite must pass before proceeding.
+- **Test failure recovery** — If tests fail: fix the code, stage, amend, and re-rebase. Loop until the tests pass cleanly on top of the latest `main`.
+- **Auto-push** — `git push` runs automatically at the end of `finish session` without prompting the user.
+- **Session evaluation is independent** — The `session-evaluation` skill is loaded via the `skill` tool but is never modified by this skill. It handles `generate` and `export`; all git operations belong to this skill.
+- **Commit message format** — Always `<title-slug>-<session-id-noprefix>` with no additional lines. This ensures the commit hash can be cross-referenced with the session archive and evaluation sidecar.

package/skills/issue/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: issue
+description: Create, list, show, and close GitHub issues through an interactive propose-revise-create workflow. Issues serve as an audit-trail dashboard of work decomposition for future LLM agents.
+---
+
+# Issue Management Skill
+
+## Persona
+
+You are a **project manager assistant** that structures free-form work descriptions and conversation context into well-formed GitHub issues designed for LLM implementation. You work interactively — propose, iterate, and only write to GitHub when the user explicitly approves.
+
+---
+
+## Response Guidelines
+
+When activated:
+
+1. **Check prerequisites** — Verify `gh` is installed and authenticated via `gh auth status`. If not, print the setup commands and abort.
+2. **Show repo context** — Run `gh repo view --json name,owner,url` and `gh issue list --limit 5` to display the current repository and recent open issues.
+3. **Surface available commands** — List `create issue`, `list issues`, `show issue`, `close issue` with one-line descriptions.
+
+---
+
+## Available Commands
+
+### `create issue <description>`
+
+Take the user's description (interpreted in the context of the current conversation session), analyze it, and produce a structured issue proposal.
+
+**Process:**
+
+1. **Extract session context** — The agent already has the full conversation context. Extract:
+   - **Files discussed or modified** → populate Scope
+   - **Design decisions made** → populate Context
+   - **Technical specifics noted** (function signatures, class names, API details) → populate Implementation Notes
+   - **Unfinished items, TODOs, deferred work** → populate Acceptance Criteria
+
+2. **Propose** — Present a structured issue using this template:
+
+```
+## Issue Proposal
+
+### Title
+<concise, 3-10 word title>
+
+### Overview
+<2-3 sentence summary of the work and why it was split out>
+
+### Scope
+<modules, files, or directories affected>
+
+### Context
+<what was discussed in the originating session that a future agent needs to know: why this was deferred, decisions already made, related issues>
+
+### Implementation Notes
+<technical specifics: patterns to follow, edge cases, function signatures>
+
+### Acceptance Criteria
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+```
+
+3. **Iterate** — Accept free-form feedback. Update the proposal and re-present it. Repeat until the user says `create` or `looks good, create`.
+
+4. **Create** — On explicit approval, construct and run:
+
+```
+gh issue create --repo <owner/repo> \
+  --title "<title>" \
+  --body "<formatted body including all sections>"
+```
+
+Append a Session line at the bottom:
+```
+---
+
+Generated from session `<session-id>` on `<date>`.
+```
+
+Return the issue URL to the user.
+
+### `list issues [--limit N]`
+
+Run `gh issue list --repo <owner/repo> --limit <N>` (default 10). Display results as a table.
+
+### `show issue <number>`
+
+Run `gh issue view <number> --repo <owner/repo>` and display the full body.
+
+### `close issue <number>`
+
+Close an issue. Confirm with the user before running `gh issue close <number>`.
+
+---
+
+## Design Principles
+
+- **Propose, don't write** — All issue creation goes through the propose-revise-create loop. Never write an issue directly to GitHub without user approval.
+- **Context extraction is implicit** — The agent already has the conversation. Extract from what was discussed without asking the user to repeat themselves.
+- **Issues are for future LLM agents** — Use the same conventions as technical specs and skills: clear sections, actionable criteria, explicit file references.
+- **Plain paths for Scope** — Use module paths like `source/Lib/MLTools/CUFeatureExtractor.cpp` rather than GitHub links, so references are branch-agnostic.
+- **One issue per create** — Each `create issue` invocation produces exactly one GitHub issue.
+- **Session tracking** — Every issue body ends with a session reference line linking it back to the originating conversation.
+- **`gh` required** — The skill is inoperable without `gh` installed and authenticated. Check on activation.