pi-skill-search 0.1.0

package/skills/scikit-survival/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: scikit-survival
+description: Comprehensive toolkit for survival analysis and time-to-event modeling in Python using scikit-survival. Use this skill when working with censored survival data, performing time-to-event analysis, fitting Cox models, Random Survival Forests, Gradient Boosting models, or Survival SVMs, evaluating survival predictions with concordance index or Brier score, handling competing risks, or implementing any survival analysis workflow with the scikit-survival library.
+---
+
+# scikit-survival: Survival Analysis in Python
+
+## Overview
+
+scikit-survival is a Python library for survival analysis built on top of scikit-learn. It provides specialized tools for time-to-event analysis, handling the unique challenge of censored data where some observations are only partially known.
+
+Survival analysis aims to establish connections between covariates and the time of an event, accounting for censored records (particularly right-censored data from studies where participants don't experience events during observation periods).
+
+## When to Use This Skill
+
+Use this skill when:
+- Performing survival analysis or time-to-event modeling
+- Working with censored data (right-censored, left-censored, or interval-censored)
+- Fitting Cox proportional hazards models (standard or penalized)
+- Building ensemble survival models (Random Survival Forests, Gradient Boosting)
+- Training Survival Support Vector Machines
+- Evaluating survival model performance (concordance index, Brier score, time-dependent AUC)
+- Estimating Kaplan-Meier or Nelson-Aalen curves
+- Analyzing competing risks
+- Preprocessing survival data or handling missing values in survival datasets
+- Conducting any analysis using the scikit-survival library
+
+## Core Capabilities
+
+### 1. Model Types and Selection
+
+scikit-survival provides multiple model families, each suited for different scenarios:
+
+#### Cox Proportional Hazards Models
+**Use for**: Standard survival analysis with interpretable coefficients
+- `CoxPHSurvivalAnalysis`: Basic Cox model
+- `CoxnetSurvivalAnalysis`: Penalized Cox with elastic net for high-dimensional data
+- `IPCRidge`: Ridge regression for accelerated failure time models
+
+**See**: `(see docs)` for detailed guidance on Cox models, regularization, and interpretation
+
+#### Ensemble Methods
+**Use for**: High predictive performance with complex non-linear relationships
+- `RandomSurvivalForest`: Robust, non-parametric ensemble method
+
+### 2. Data Preparation and Preprocessing
+
+Before modeling, properly prepare survival data:
+
+#### Creating Survival Outcomes
+```python
+from sksurv.util import Surv
+
+# From separate arrays
+y = Surv.from_arrays(event=event_array, time=time_array)
+
+# From DataFrame
+y = Surv.from_dataframe('event', 'time', df)
+```
+
+#### Essential Preprocessing Steps
+1. **Handle missing values**: Imputation strategies for features
+2. **Encode categorical variables**: One-hot encoding or label encoding
+3. **Standardize features**: Critical for SVMs and regularized Cox models
+4. **Validate data quality**: Check for negative times, sufficient events per feature
+5. **Train-test split**: Maintain similar censoring rates across splits
+
+**See**: `(see docs)` for complete preprocessing workflows, data validation, and best practices
+
+### 3. Model Evaluation
+
+Proper evaluation is critical for survival models. Use appropriate metrics that account for censoring:
+
+#### Concordance Index (C-index)
+Primary metric for ranking/discrimination:
+- **Harrell's C-index**: Use for low censoring (<40%)
+- **Uno's C-index**: Use for moderate to high censoring (>40%) - more robust
+
+```python
+from sksurv.metrics import concordance_index_censored, concordance_index_ipcw
+
+# Harrell's C-index
+c_harrell = concordance_index_censored(y_test['event'], y_test['time'], risk_scores)[0]
+
+# Uno's C-index (recommended)
+c_uno = concordance_index_ipcw(y_train, y_test, risk_scores)[0]
+```
+
+#### Time-Dependent AUC
+Evaluate discrimination at specific time points:
+
+```python
+from sksurv.metrics import cumulative_dynamic_auc
+
+times = [365, 730, 1095]  # 1, 2, 3 years
+auc, mean_auc = cumulative_dynamic_auc(y_train, y_test, risk_scores, times)
+```
+
+#### Brier Score
+
+### 4. Competing Risks Analysis
+
+Handle situations with multiple mutually exclusive event types:
+
+```python
+from sksurv.nonparametric import cumulative_incidence_competing_risks
+
+# Estimate cumulative incidence for each event type
+time_points, cif_event1, cif_event2 = cumulative_incidence_competing_risks(y)
+```

package/skills/sciomc/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: sciomc
+description: Orchestrate parallel scientist agents for comprehensive analysis with AUTO mode
+---
+
+# Research Skill
+
+Orchestrate parallel scientist agents for comprehensive research workflows with optional AUTO mode for fully autonomous execution.
+
+## Overview
+
+Research is a multi-stage workflow that decomposes complex research goals into parallel investigations:
+
+1. **Decomposition** - Break research goal into independent stages/hypotheses
+2. **Execution** - Run parallel scientist agents on each stage
+3. **Verification** - Cross-validate findings, check consistency
+4. **Synthesis** - Aggregate results into comprehensive report
+
+## Usage Examples
+
+```
+sciomc <goal>                    # Standard research with user checkpoints
+sciomc AUTO: <goal>              # Fully autonomous until complete
+sciomc status                    # Check current research session status
+sciomc resume                    # Resume interrupted research session
+sciomc list                      # List all research sessions
+sciomc report <session-id>       # Generate report for session
+```
+
+### Quick Examples
+
+```
+sciomc What are the performance characteristics of different sorting algorithms?
+sciomc AUTO: Analyze authentication patterns in this codebase
+sciomc How does the error handling work across the API layer?
+```
+
+## Research Protocol
+
+### Stage Decomposition Pattern
+
+When given a research goal, decompose into 3-7 independent stages:
+
+```markdown
+## Research Decomposition
+
+**Goal:** <original research goal>
+
+### Stage 1: <stage-name>
+- **Focus:** What this stage investigates
+- **Hypothesis:** Expected finding (if applicable)
+- **Scope:** Files/areas to examine
+- **Tier:** LOW | MEDIUM | HIGH
+
+### Stage 2: <stage-name>
+...
+```
+
+### Parallel Scientist Invocation
+
+Fire independent stages in parallel via Task tool:
+
+```
+// Stage 1 - Simple data gathering
+Task(subagent_type="oh-my-claudecode:scientist", model="haiku", prompt="[RESEARCH_STAGE:1] Investigate...")
+
+// Stage 2 - Standard analysis
+Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="[RESEARCH_STAGE:2] Analyze...")
+
+// Stage 3 - Complex reasoning
+Task(subagent_type="oh-my-claudecode:scientist", model="opus", prompt="[RESEARCH_STAGE:3] Deep analysis of...")
+```
+
+### Smart Model Routing
+
+**CRITICAL: Always pass `model` parameter explicitly!**
+
+| Task Complexity | Agent | Model | Use For |
+|-----------------|-------|-------|---------|
+| Data gathering | `scientist` (model=haiku) | haiku | File enumeration, pattern counting, simple lookups |
+| Standard analysis | `scientist` | sonnet | Code analysis, pattern detection, documentation review |
+| Complex reasoning | `scientist` | opus | Architecture analysis, cross-cutting concerns, hypothesis validation |
+
+### Routing Decision Guide
+
+

package/skills/scvelo/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: scvelo
+description: RNA velocity analysis with scVelo. Estimate cell state transitions from unspliced/spliced mRNA dynamics, infer trajectory directions, compute latent time, and identify driver genes in single-cell RNA-seq data. Complements Scanpy/scVI-tools for trajectory inference.
+---
+
+# scVelo — RNA Velocity Analysis
+
+## Overview
+
+scVelo is the leading Python package for RNA velocity analysis in single-cell RNA-seq data. It infers cell state transitions by modeling the kinetics of mRNA splicing — using the ratio of unspliced (pre-mRNA) to spliced (mature mRNA) abundances to determine whether a gene is being upregulated or downregulated in each cell. This allows reconstruction of developmental trajectories and identification of cell fate decisions without requiring time-course data.
+
+**Installation:** `pip install scvelo`
+
+**Key resources:**
+- Documentation: https://scvelo.readthedocs.io/
+- GitHub: https://github.com/theislab/scvelo
+- Paper: Bergen et al. (2020) Nature Biotechnology. PMID: 32747759
+
+## When to Use This Skill
+
+Use scVelo when:
+
+- **Trajectory inference from snapshot data**: Determine which direction cells are differentiating
+- **Cell fate prediction**: Identify progenitor cells and their downstream fates
+- **Driver gene identification**: Find genes whose dynamics best explain observed trajectories
+- **Developmental biology**: Model hematopoiesis, neurogenesis, epithelial-to-mesenchymal transitions
+- **Latent time estimation**: Order cells along a pseudotime derived from splicing dynamics
+- **Complement to Scanpy**: Add directional information to UMAP embeddings
+
+## Prerequisites
+
+scVelo requires count matrices for both **unspliced** and **spliced** RNA. These are generated by:
+1. **STARsolo** or **kallisto|bustools** with `lamanno` mode
+2. **velocyto** CLI: `velocyto run10x` / `velocyto run`
+3. **alevin-fry** / **simpleaf** with spliced/unspliced output
+
+Data is stored in an `AnnData` object with `layers["spliced"]` and `layers["unspliced"]`.
+
+## Standard RNA Velocity Workflow
+
+### 1. Setup and Data Loading
+
+```python
+import scvelo as scv
+import scanpy as sc
+import numpy as np
+import matplotlib.pyplot as plt
+
+# Configure settings
+scv.settings.verbosity = 3       # Show computation steps
+scv.settings.presenter_view = True
+scv.settings.set_figure_params('scvelo')
+
+# Load data (AnnData with spliced/unspliced layers)
+# Option A: Load from loom (velocyto output)
+adata = scv.read("cellranger_output.loom", cache=True)
+
+# Option B: Merge velocyto loom with Scanpy-processed AnnData
+adata_processed = sc.read_h5ad("processed.h5ad")  # Has UMAP, clusters
+adata_velocity = scv.read("velocyto.loom")
+adata = scv.utils.merge(adata_processed, adata_velocity)
+
+# Verify layers
+print(adata)
+# obs × var: N × G
+# layers: 'spliced', 'unspliced' (required)
+# obsm['X_umap'] (required for visualization)
+```
+
+### 2. Preprocessing
+
+```python
+# Filter and normalize (follows Scanpy conventions)
+scv.pp.filter_and_normalize(
+    adata,
+    min_shared_counts=20,   # Minimum counts in spliced+unspliced
+    n_top_genes=2000        # Top highly variable genes
+)
+
+# Compute first and second order moments (means and variances)
+# knn_connectivities must be computed first
+sc.pp.neighbors(adata, n_neighbors=30, n_pcs=30)
+scv.pp.moments(
+    adata,
+    n_pcs=30,
+    n_neighbors=30
+)
+```
+
+### 3. Velocity Estimation — Stochastic Model
+
+The stochastic model is fast and suitable for exploratory analysis:
+
+```python
+# Stochastic velocity (faster, less accurate)
+scv.tl.velocity(adata, mode='stochastic')
+scv.tl.velocity_graph(adata)
+
+# Visualize
+scv.pl.velocity_embedding_stream(
+    adata,
+    basis='umap',
+    color='leiden',
+    title="RNA Velocity (Stochastic)"
+)
+```

package/skills/scvi-tools/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: scvi-tools
+description: Deep generative models for single-cell omics. Use when you need probabilistic batch correction (scVI), transfer learning, differential expression with uncertainty, or multi-modal integration (TOTALVI, MultiVI). Best for advanced modeling, batch effects, multimodal data. For standard analysis pipelines use scanpy.
+---
+
+# scvi-tools
+
+## Overview
+
+scvi-tools is a comprehensive Python framework for probabilistic models in single-cell genomics. Built on PyTorch and PyTorch Lightning, it provides deep generative models using variational inference for analyzing diverse single-cell data modalities.
+
+## When to Use This Skill
+
+Use this skill when:
+- Analyzing single-cell RNA-seq data (dimensionality reduction, batch correction, integration)
+- Working with single-cell ATAC-seq or chromatin accessibility data
+- Integrating multimodal data (CITE-seq, multiome, paired/unpaired datasets)
+- Analyzing spatial transcriptomics data (deconvolution, spatial mapping)
+- Performing differential expression analysis on single-cell data
+- Conducting cell type annotation or transfer learning tasks
+- Working with specialized single-cell modalities (methylation, cytometry, RNA velocity)
+- Building custom probabilistic models for single-cell analysis
+
+## Core Capabilities
+
+scvi-tools provides models organized by data modality:
+
+### 1. Single-Cell RNA-seq Analysis
+Core models for expression analysis, batch correction, and integration. See `(see docs)` for:
+- **scVI**: Unsupervised dimensionality reduction and batch correction
+- **scANVI**: Semi-supervised cell type annotation and integration
+- **AUTOZI**: Zero-inflation detection and modeling
+- **VeloVI**: RNA velocity analysis
+- **contrastiveVI**: Perturbation effect isolation
+
+### 2. Chromatin Accessibility (ATAC-seq)
+Models for analyzing single-cell chromatin data. See `(see docs)` for:
+- **PeakVI**: Peak-based ATAC-seq analysis and integration
+- **PoissonVI**: Quantitative fragment count modeling
+- **scBasset**: Deep learning approach with motif analysis
+
+### 3. Multimodal & Multi-omics Integration
+Joint analysis of multiple data types. See `(see docs)` for:
+- **totalVI**: CITE-seq protein and RNA joint modeling
+- **MultiVI**: Paired and unpaired multi-omic integration
+- **MrVI**: Multi-resolution cross-sample analysis
+
+### 4. Spatial Transcriptomics
+Spatially-resolved transcriptomics analysis. See `(see docs)` for:
+- **DestVI**: Multi-resolution spatial deconvolution
+- **Stereoscope**: Cell type deconvolution
+- **Tangram**: Spatial mapping and integration
+- **scVIVA**: Cell-environment relationship analysis
+
+### 5. Specialized Modalities
+Additional specialized analysis tools. See `(see docs)` for:
+- **MethylVI/MethylANVI**: Single-cell methylation analysis
+- **CytoVI**: Flow/mass cytometry batch correction
+- **Solo**: Doublet detection
+- **CellAssign**: Marker-based cell type annotation
+
+## Typical Workflow
+
+All scvi-tools models follow a consistent API pattern:
+
+```python
+# 2. Register data with model (specify layers, covariates)
+scvi.model.SCVI.setup_anndata(
+    adata,
+    layer="counts",  # Use raw counts, not log-normalized
+    batch_key="batch",
+    categorical_covariate_keys=["donor"],
+    continuous_covariate_keys=["percent_mito"]
+)
+
+# 3. Create and train model
+model = scvi.model.SCVI(adata)
+model.train()
+
+# 4. Extract latent representations and normalized values
+latent = model.get_latent_representation()
+normalized = model.get_normalized_expression(library_size=1e4)
+
+# 5. Store in AnnData for downstream analysis
+adata.obsm["X_scVI"] = latent
+adata.layers["scvi_normalized"] = normalized
+
+# 6. Downstream analysis with scanpy
+sc.pp.neighbors(adata, use_rep="X_scVI")
+sc.tl.umap(adata)
+sc.tl.leiden(adata)
+```
+
+**Key Design Principles:**
+- **Raw counts required**: Models expect unnormalized count data for optimal performance
+- **Unified API**: Consistent interface across all models (setup → train → extract)
+- **AnnData-centric**: Seamless integration with the scanpy ecosystem
+- **GPU acceleration**: Automatic utilization of available GPUs
+- **Batch correction**: Handle technical variation through covariate registration
+
+## Common Analysis Tasks
+
+### Differential Expression
+Probabilistic DE analysis using the learned generative models:
+
+```python
+de_results = model.differential_expression(
+    groupby="cell_type",
+    group1="TypeA",
+    group2="TypeB",
+    mode="change",  # Use composite hypothesis testing
+    delta=0.25      # Minimum effect size threshold
+)
+```

package/skills/seaborn/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: seaborn
+description: Statistical visualization with pandas integration. Use for quick exploration of distributions, relationships, and categorical comparisons with attractive defaults. Best for box plots, violin plots, pair plots, heatmaps. Built on matplotlib. For interactive plots use plotly; for publication styling use scientific-visualization.
+---
+
+# Seaborn Statistical Visualization
+
+## Overview
+
+Seaborn is a Python visualization library for creating publication-quality statistical graphics. Use this skill for dataset-oriented plotting, multivariate analysis, automatic statistical estimation, and complex multi-panel figures with minimal code.
+
+## Design Philosophy
+
+Seaborn follows these core principles:
+
+1. **Dataset-oriented**: Work directly with DataFrames and named variables rather than abstract coordinates
+2. **Semantic mapping**: Automatically translate data values into visual properties (colors, sizes, styles)
+3. **Statistical awareness**: Built-in aggregation, error estimation, and confidence intervals
+4. **Aesthetic defaults**: Publication-ready themes and color palettes out of the box
+5. **Matplotlib integration**: Full compatibility with matplotlib customization when needed
+
+## Quick Start
+
+```python
+import seaborn as sns
+import matplotlib.pyplot as plt
+import pandas as pd
+
+# Load example dataset
+df = sns.load_dataset('tips')
+
+# Create a simple visualization
+sns.scatterplot(data=df, x='total_bill', y='tip', hue='day')
+plt.show()
+```
+
+## Core Plotting Interfaces
+
+### Function Interface (Traditional)
+
+The function interface provides specialized plotting functions organized by visualization type. Each category has **axes-level** functions (plot to single axes) and **figure-level** functions (manage entire figure with faceting).
+
+**When to use:**
+- Quick exploratory analysis
+- Single-purpose visualizations
+- When you need a specific plot type
+
+### Objects Interface (Modern)
+
+The `seaborn.objects` interface provides a declarative, composable API similar to ggplot2. Build visualizations by chaining methods to specify data mappings, marks, transformations, and scales.
+
+**When to use:**
+- Complex layered visualizations
+- When you need fine-grained control over transformations
+- Building custom plot types
+- Programmatic plot generation
+
+```python
+from seaborn import objects as so
+
+# Declarative syntax
+(
+    so.Plot(data=df, x='total_bill', y='tip')
+    .add(so.Dot(), color='day')
+    .add(so.Line(), so.PolyFit())
+)
+```
+
+## Plotting Functions by Category
+
+### Relational Plots (Relationships Between Variables)
+
+**Use for:** Exploring how two or more variables relate to each other
+
+- `scatterplot()` - Display individual observations as points
+- `lineplot()` - Show trends and changes (automatically aggregates and computes CI)
+- `relplot()` - Figure-level interface with automatic faceting
+
+**Key parameters:**
+- `x`, `y` - Primary variables
+- `hue` - Color encoding for additional categorical/continuous variable
+- `size` - Point/line size encoding
+- `style` - Marker/line style encoding
+- `col`, `row` - Facet into multiple subplots (figure-level only)
+
+```python
+# Scatter with multiple semantic mappings
+sns.scatterplot(data=df, x='total_bill', y='tip',
+                hue='time', size='size', style='sex')
+
+# Line plot with confidence intervals
+sns.lineplot(data=timeseries, x='date', y='value', hue='category')
+
+# Faceted relational plot
+sns.relplot(data=df, x='total_bill', y='tip',
+            col='time', row='sex', hue='smoker', kind='scatter')
+```

package/skills/secure-agent-orchestration-review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: secure-agent-orchestration-review
+description: Use when reviewing delegation, skill loading, tool access, worker prompts, artifacts, runtime config, state, ownership, or subprocess execution.
+---
+
+
+# secure-agent-orchestration-review
+
+Core principle: every delegated worker crosses trust boundaries. Safe orchestration requires contained paths, explicit ownership, scoped tools, non-invasive defaults, and prompt-injection resistance.
+
+Distilled from detailed reads of security notice, insecure-defaults, sharp-edges, differential-review, guardrail, and skill quality patterns.
+
+## Trust Boundaries
+
+Review:
+
+- parent session ↔ child Pi worker;
+- user prompt ↔ generated task packet;
+- project skills ↔ package skills;
+- global config ↔ project config;
+- artifacts/logs ↔ future prompts/UI;
+- mailbox/respond/steer/cancel ↔ session ownership;
+- external skills/docs ↔ prompt injection/tool poisoning;
+- runtime env/CLI args ↔ provider/model behavior.
+
+## Must-Check Findings
+
+- Unsafe defaults: scaffold mode unexpectedly enabled, dangerous limits, missing depth guards, overbroad tools.
+- Path containment: cwd override escape, symlink traversal, unsafe skill names, absolute path leakage.
+- Prompt injection: untrusted output treated as instruction, skill metadata overtrusted, missing precedence text.
+- Secrets: env/config/log/artifact/diagnostic leakage.
+- Destructive commands: delete/prune/reset/force push without explicit confirmation.
+- Ownership races: authorization checked outside lock, stale task/manifest written after re-read.
+- Supply chain: external skill content imported without review, unknown tool requirements, hidden commands.
+
+## Secure Defaults for pi-crew
+
+- Real execution should be explicit and disable-able, but generated config must not accidentally block normal workflows.
+- Project overrides should be contained to the project root.
+- Missing/invalid config should fall back safely.
+- Skills should be loaded by safe name and source-labeled without absolute path disclosure.
+- Worker prompts should state instruction precedence and treat artifacts as data.
+
+## Finding Format
+
+Include severity, path/symbol, scenario, fix, and verification. Separate must-fix security issues from hardening suggestions.
+

package/skills/self-improve/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: self-improve
+description: Autonomous evolutionary code improvement engine with tournament selection
+---
+
+# Self-Improvement Orchestrator
+
+You are the **loop controller** for the self-improvement system. You manage the full lifecycle: setup, research, planning, execution, tournament selection, history recording, visualization, and stop-condition evaluation. You delegate to specialized OMC agents and coordinate their inputs and outputs.
+
+---
+
+## Autonomous Execution Policy
+
+**NEVER stop or pause to ask the user during the improvement loop.** Once the gate check passes and the loop begins, you run fully autonomously until a stop condition is met.
+
+- **Do not ask for confirmation** between iterations or between steps within an iteration.
+- **Do not summarize and wait** — execute the next step immediately.
+- **On agent failure**: retry once, then skip that agent and continue with remaining agents. Log the failure in iteration history.
+- **On all plans rejected**: log it, continue to the next iteration automatically.
+- **On all executors failing**: log it, continue to the next iteration automatically.
+- **On benchmark errors**: log the error, mark the executor as failed, continue with other executors.
+- **The only things that stop the loop** are the stop conditions in Step 11.
+- **Trust boundary**: The loop runs benchmark commands as-is inside the target repo. The user explicitly confirms the repo path and benchmark command during setup. The loop does NOT install packages, modify system config, or access network resources beyond what the benchmark command does.
+- **Sealed files**: validate.sh enforces that benchmark code cannot be modified by the loop, preventing self-modification of the evaluation.
+
+---
+
+## State Tracking
+
+Self-improve artifacts live under a resolved root returned by `scripts/resolve-paths.mjs`.
+
+- New runs default to `.omc/self-improve/topics/default/`.
+- When the user provides a topic or slug, use `.omc/self-improve/topics/{topic_slug}/`.
+- Legacy single-track state at `.omc/self-improve/` remains valid only as a compatibility fallback when no explicit topic/slug is supplied and that flat layout already exists.
+
+Treat `<self-improve-root>/` below as that resolved root:
+
+```
+<self-improve-root>/
+├── config/                    # User configuration
+│   ├── settings.json          # agents, benchmark, thresholds, sealed_files
+│   ├── goal.md                # Improvement objective + target metric
+
+## Agent Mapping
+
+All augmentations delivered via Task description context at spawn time. No modifications to existing agent .md files.
+
+| Step | Role | OMC Agent | Model |
+|------|------|-----------|-------|
+| Research | Codebase analysis + hypothesis generation | general-purpose Agent | opus |
+| Planning | Hypothesis → structured plan | oh-my-claudecode:planner | opus |
+| Architecture Review | 6-point plan review | oh-my-claudecode:architect | opus |
+| Critic Review | Harness rule enforcement | oh-my-claudecode:critic | opus |
+| Execution | Implement plan + run benchmark | oh-my-claudecode:executor | opus |
+| Git Operations | Atomic merge/tag/PR | oh-my-claudecode:git-master | sonnet |
+| Goal Setup | Interactive interview | (directly in this skill) | N/A |
+| Benchmark Setup | Create + validate benchmark | custom agent | opus |
+
+
+## Inputs
+
+Read these files at startup and at the beginning of each iteration:
+
+| File | Purpose |
+|---|---|
+| `<self-improve-root>/config/settings.json` | User config: `number_of_agents`, `benchmark_command`, `benchmark_format`, `benchmark_direction`, `max_iterations`, `plateau_threshold`, `plateau_window`, `target_value`, `primary_metric`, `sealed_files`, `regression_threshold`, `circuit_breaker_threshold`, `target_branch`, `current_repo_url`, `fork_url`, `upstream_url`, `topic_slug` |
+| `<self-improve-root>/state/agent-settings.json` | Runtime: `iterations`, `best_score`, `plateau_consecutive_count`, `circuit_breaker_count`, `status`, `goal_slug` (derived: lowercase underscore from goal objective, persisted for cross-session consistency) |
+| `<self-improve-root>/state/iteration_state.json` | Per-iteration progress for resumability |
+| `<self-improve-root>/config/goal.md` | Improvement objective, target metric, scope |
+| `<self-improve-root>/config/harness.md` | Guardrail rules (H001, H002, H003) |
+
+---
+
+## Setup Phase
+
+1. Check if target repo path exists. If not configured, ask user for the path to the repository to improve.
+2. Resolve `<self-improve-root>` by running `node {skill_dir}/scripts/resolve-paths.mjs --project-root {repo_path} [--topic "..."] [--slug "..."] --ensure-dirs`.
+3. Create the `<self-improve-root>/` directory structure by copying from `templates/` in this skill directory into the resolved `config/` root.
+4. Read `<self-improve-root>/state/agent-settings.json`. Check `si_setting_goal`, `si_setting_benchmark`, `si_setting_harness`.
+4. **Trust confirmation** (mandatory, cannot be skipped):
+   a. If `trust_confirmed` is already `true` in agent-settings.json, skip to step 5 (resume path).
+   b. Display the target repo path and ask user to confirm:
+      `"Self-improve will run benchmark commands inside {repo_path}. This executes arbitrary code in that repository. Confirm? [yes/no]"`
+   c. If user declines: abort setup and exit. Do NOT proceed.
+   d. Record consent: set `trust_confirmed: true` in agent-settings.json.
+5. Persist `topic_slug` into `config/settings.json` when the resolved root is topic-scoped so future resumes stay on the same track.
+6. If goal not set → read `si-goal-clarifier.md` from this skill directory and run the 4-dimension Socratic interview directly in this context (Objective, Metric, Target, Scope). Write result to `<self-improve-root>/config/goal.md`.
+6. If benchmark not set → read `si-benchmark-builder.md` from this skill directory, spawn a custom Agent(model=opus) with its content as prompt. The agent surveys the repo, creates or wraps a benchmark, validates 3x, and records baseline.
+
+## Git Strategy
+
+All git operations happen inside the target repo, NOT in the OMC project root.
+
+- **Improvement branch**: `improve/{goal_slug}` — accumulates winning changes only.
+- **Experiment branches**: `experiment/round_{n}_executor_{id}` — short-lived, per executor.
+- **Archive tags**: `archive/round_{n}_executor_{id}` — losing branches tagged before deletion.
+- **Worktree setup** (SKILL.md creates before each executor):
+  ```
+  git -C {repo_path} worktree add worktrees/round_{n}_executor_{id} -b experiment/round_{n}_executor_{id} improve/{goal_slug}
+  ```
+- **Winner merges** via `oh-my-claudecode:git-master`:
+  ```
+  Merge experiment/round_{n}_executor_{winner_id} into improve/{goal_slug} with --no-ff
+  Message: "Iteration {n}: {hypothesis} (score: {before} → {after})"
+
+## Improvement Loop
+
+**Gate**: All settings must be true. Once the gate passes, execute continuously without stopping.
+
+Update `state_write(mode='self-improve', active=true, status="running")`.
+
+### Step 0 — Stale Worktree Cleanup (mandatory, runs every iteration)
+
+**PREREQUISITE**: This step MUST run to completion before any other step, including resume logic. It is idempotent and safe to run multiple times.
+
+1. List all worktrees in the target repo: `git -C {repo_path} worktree list`
+2. For any worktree matching `worktrees/round_*` that does NOT belong to the current iteration: remove it with `git -C {repo_path} worktree remove {path} --force`
+
+