claude-turing 1.0.0

package/src/claude-md.js

@@ -0,0 +1,55 @@
+import { readFile, writeFile } from "fs/promises";
+
+const BEGIN = "<!-- BEGIN turing -->";
+const END = "<!-- END turing -->";
+
+const SECTION = `${BEGIN}
+## turing
+
+Autonomous ML research harness. The autoresearch loop as a formal protocol.
+
+### Commands
+
+| Command | Purpose |
+|---------|---------|
+| \`/turing\` | Router — detects ML intent and routes to sub-commands |
+| \`/turing:init\` | Scaffold a new ML project with autoresearch harness |
+| \`/turing:train [N]\` | Run autonomous experiment loop (optional max iterations) |
+| \`/turing:status\` | Show experiment status, best model, convergence state |
+| \`/turing:compare <a> <b>\` | Side-by-side experiment comparison |
+| \`/turing:sweep\` | Generate and run hyperparameter sweep |
+| \`/turing:validate\` | Check metric stability, auto-fix if noisy |
+| \`/turing:try <hypothesis>\` | Inject a hypothesis into the experiment queue |
+| \`/turing:brief\` | Generate research intelligence report |
+| \`/turing:preflight\` | Pre-flight resource check (VRAM/RAM/disk) |
+
+### Agents
+
+| Agent | Purpose |
+|-------|---------|
+| \`@ml-researcher\` | Autonomous training agent (Read/Write/Edit/Bash) |
+| \`@ml-evaluator\` | Read-only analysis agent (Read/Bash only) |
+${END}`;
+
+export async function updateClaudeMd(claudeMdPath) {
+  let content = "";
+  try {
+    content = await readFile(claudeMdPath, "utf-8");
+  } catch {
+    // File doesn't exist yet
+  }
+
+  const regex = new RegExp(
+    `${BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+  );
+
+  if (regex.test(content)) {
+    content = content.replace(regex, SECTION);
+  } else {
+    content = content
+      ? content.trimEnd() + "\n\n" + SECTION + "\n"
+      : SECTION + "\n";
+  }
+
+  await writeFile(claudeMdPath, content, "utf-8");
+}

package/src/install.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Turing installer.
+ *
+ * Deploys commands, agents, and config to the Claude Code plugin directory.
+ * Optionally inserts a managed section into the project's CLAUDE.md.
+ *
+ * Usage:
+ *   node src/install.js [--global] [--project]
+ */
+
+import { readdir, copyFile, mkdir } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { getTargetPaths } from "./paths.js";
+import { updateClaudeMd } from "./claude-md.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = join(__dirname, "..");
+
+// Single source of truth for sub-commands (DRY — used for dirs and file copy)
+const SUB_COMMANDS = [
+  "init", "train", "status", "compare", "sweep", "validate",
+  "try", "brief", "suggest", "design", "logbook", "poster",
+  "report", "mode", "preflight",
+];
+
+export async function install(opts = {}) {
+  const scope = opts.global ? "global" : opts.project ? "project" : "global";
+  const paths = getTargetPaths(scope);
+
+  console.log("Turing ML Research Harness — Installer");
+  console.log(`Target: ${paths.commands} (${scope})`);
+  console.log("");
+
+  // Create directories for each sub-command + agents + config
+  for (const subDir of ["", "agents", "config", "rules", ...SUB_COMMANDS]) {
+    await mkdir(join(paths.commands, subDir), { recursive: true });
+  }
+
+  // Copy root command (router) as SKILL.md
+  await copyFile(
+    join(PLUGIN_ROOT, "commands", "turing.md"),
+    join(paths.commands, "SKILL.md"),
+  );
+  console.log("  Router -> SKILL.md");
+
+  // Copy sub-commands as <name>/SKILL.md
+  for (const cmd of SUB_COMMANDS) {
+    await copyFile(
+      join(PLUGIN_ROOT, "commands", `${cmd}.md`),
+      join(paths.commands, cmd, "SKILL.md"),
+    );
+  }
+  console.log(`  ${SUB_COMMANDS.length} commands installed`);
+
+  // Copy rules
+  await copyFile(
+    join(PLUGIN_ROOT, "commands", "rules", "loop-protocol.md"),
+    join(paths.commands, "rules", "loop-protocol.md"),
+  );
+  console.log("  Rules installed");
+
+  // Copy agents
+  const agentFiles = await readdir(join(PLUGIN_ROOT, "agents"));
+  for (const file of agentFiles) {
+    await copyFile(
+      join(PLUGIN_ROOT, "agents", file),
+      join(paths.agents, file),
+    );
+  }
+  console.log(`  ${agentFiles.length} agents installed`);
+
+  // Copy config (static schema files only)
+  const CONFIG_FILES = [
+    "defaults.yaml", "lifecycle.toml", "taxonomy.toml",
+    "experiment_archetypes.yaml", "novelty_aliases.yaml",
+    "relationships.toml", "state.toml", "task_taxonomy.yaml",
+  ];
+  for (const file of CONFIG_FILES) {
+    await copyFile(
+      join(PLUGIN_ROOT, "config", file),
+      join(paths.config, file),
+    );
+  }
+  console.log(`  ${CONFIG_FILES.length} config files installed`);
+
+  // Update CLAUDE.md
+  await updateClaudeMd(paths.claudeMd);
+  console.log("  CLAUDE.md updated");
+
+  console.log("");
+  console.log(
+    `Installation complete. Run /turing:init to scaffold an ML project.`,
+  );
+}
+
+// Direct execution
+const isDirectRun =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url).endsWith(process.argv[1].replace(/^.*\//, ""));
+if (isDirectRun) {
+  install({
+    global: process.argv.includes("--global"),
+    project: process.argv.includes("--project"),
+  });
+}

package/src/paths.js

@@ -0,0 +1,20 @@
+import { homedir } from "os";
+import { join } from "path";
+
+export function getTargetPaths(scope) {
+  const base =
+    scope === "global"
+      ? join(homedir(), ".claude")
+      : join(process.cwd(), ".claude");
+
+  return {
+    commands: join(base, "commands", "turing"),
+    agents: join(base, "commands", "turing", "agents"),
+    config: join(base, "commands", "turing", "config"),
+    claudeMd:
+      scope === "global"
+        ? join(homedir(), ".claude", "CLAUDE.md")
+        : join(process.cwd(), "CLAUDE.md"),
+    scope,
+  };
+}

package/src/postinstall.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * npm postinstall hook.
+ *
+ * Prints setup instructions after `npm install claude-turing`.
+ * Does NOT auto-install — the user must explicitly run the installer.
+ */
+
+console.log("");
+console.log("╔══════════════════════════════════════════════════════╗");
+console.log("║           Turing ML Research Harness                ║");
+console.log("║                                                     ║");
+console.log("║  To complete setup, run:                            ║");
+console.log("║    npx claude-turing install --global               ║");
+console.log("║                                                     ║");
+console.log("║  Or within a project:                               ║");
+console.log("║    npx claude-turing install                        ║");
+console.log("║                                                     ║");
+console.log("║  Then in Claude Code:                               ║");
+console.log("║    /turing:init                                     ║");
+console.log("╚══════════════════════════════════════════════════════╝");
+console.log("");

package/src/verify.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Turing installation verifier.
+ *
+ * Checks that all expected files are in place and reports status.
+ *
+ * Usage:
+ *   node src/verify.js [--scope global|project]
+ */
+
+import { access } from "fs/promises";
+import { join } from "path";
+import { getTargetPaths } from "./paths.js";
+
+const EXPECTED_COMMANDS = [
+  "SKILL.md",
+  "init/SKILL.md",
+  "train/SKILL.md",
+  "status/SKILL.md",
+  "compare/SKILL.md",
+  "sweep/SKILL.md",
+  "validate/SKILL.md",
+  "try/SKILL.md",
+  "brief/SKILL.md",
+  "suggest/SKILL.md",
+  "design/SKILL.md",
+  "logbook/SKILL.md",
+  "poster/SKILL.md",
+  "report/SKILL.md",
+  "mode/SKILL.md",
+  "preflight/SKILL.md",
+];
+
+const EXPECTED_AGENTS = ["ml-researcher.md", "ml-evaluator.md"];
+
+const EXPECTED_CONFIG = [
+  "defaults.yaml", "lifecycle.toml", "taxonomy.toml",
+  "experiment_archetypes.yaml", "novelty_aliases.yaml",
+  "relationships.toml", "state.toml", "task_taxonomy.yaml",
+];
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function verify(opts = {}) {
+  const scopes = opts.scope ? [opts.scope] : ["global", "project"];
+  let found = false;
+
+  for (const scope of scopes) {
+    const paths = getTargetPaths(scope);
+    const exists = await fileExists(join(paths.commands, "SKILL.md"));
+    if (!exists) continue;
+    found = true;
+
+    console.log(`\n✓ turing found (${scope}): ${paths.commands}\n`);
+
+    let missing = 0;
+
+    console.log("Commands:");
+    for (const cmd of EXPECTED_COMMANDS) {
+      const ok = await fileExists(join(paths.commands, cmd));
+      console.log(`  ${ok ? "✓" : "✗"} commands/${cmd}`);
+      if (!ok) missing++;
+    }
+
+    console.log("\nAgents:");
+    for (const agent of EXPECTED_AGENTS) {
+      const ok = await fileExists(join(paths.agents, agent));
+      console.log(`  ${ok ? "✓" : "✗"} agents/${agent}`);
+      if (!ok) missing++;
+    }
+
+    console.log("\nConfig:");
+    for (const cfg of EXPECTED_CONFIG) {
+      const ok = await fileExists(join(paths.config, cfg));
+      console.log(`  ${ok ? "✓" : "✗"} config/${cfg}`);
+      if (!ok) missing++;
+    }
+
+    // Check CLAUDE.md
+    const claudeOk = await fileExists(paths.claudeMd);
+    console.log(`\n  ${claudeOk ? "✓" : "✗"} CLAUDE.md`);
+
+    console.log(
+      `\n  ${missing === 0 ? "✓ Installation complete" : `✗ ${missing} files missing — run claude-turing install`}\n`,
+    );
+  }
+
+  if (!found) {
+    console.log("\n✗ turing not found. Run: claude-turing install\n");
+  }
+}
+
+// Direct execution
+const isDirectRun =
+  process.argv[1] &&
+  import.meta.url.endsWith(process.argv[1].replace(/^.*\//, ""));
+if (isDirectRun) {
+  const scopeIdx = process.argv.indexOf("--scope");
+  verify({
+    scope: scopeIdx !== -1 ? process.argv[scopeIdx + 1] : undefined,
+  });
+}

package/templates/MEMORY.md

@@ -0,0 +1,36 @@
+# ML Researcher Memory
+
+## Goal
+
+{{TASK_DESCRIPTION}}
+
+Primary metric: {{TARGET_METRIC}} ({{METRIC_DIRECTION}} is better).
+
+## Best Result
+
+No experiments completed yet. Run `/turing:train` to begin.
+
+## Observations
+
+- Initial model: XGBoost with default hyperparams (n_estimators=100, max_depth=4, lr=0.1)
+- Config file: `config.yaml` controls all hyperparameters — do not hardcode in train.py
+- Sweep tool: `python scripts/sweep.py` for systematic grid search
+- Per-experiment branches: `exp/NNN-description` preserves all code variants
+- Evaluation is immutable: `prepare.py` and `evaluate.py` are READ-ONLY
+
+## Failed Approaches
+
+(none yet)
+
+## Promising Directions
+
+- Hyperparameter sweep across n_estimators, max_depth, learning_rate
+- LightGBM as alternative to XGBoost
+- Feature engineering: add domain-specific features
+- Try different model architectures (RandomForest, MLP)
+
+## Session History
+
+| Session | Experiments | Best Metric | Notes |
+|---------|-------------|-------------|-------|
+| (none) | 0 | N/A | Pipeline initialized, no experiments run |

package/templates/README.md

@@ -0,0 +1,93 @@
+# {{PROJECT_NAME}} ML Pipeline
+
+{{TASK_DESCRIPTION}}
+
+## Overview
+
+This pipeline uses the [Turing](https://github.com/pragnition/turing) autoresearch pattern — an AI agent iteratively trains, evaluates, and improves models by modifying `train.py` while the evaluation infrastructure (`prepare.py`, `evaluate.py`) remains immutable.
+
+**Primary metric:** {{TARGET_METRIC}} ({{METRIC_DIRECTION}} is better)
+
+## The Separation
+
+| Layer | Files | Agent Access | Purpose |
+|-------|-------|-------------|---------|
+| Measurement | `prepare.py`, `evaluate.py` | READ-ONLY | Ensures all experiments are measured by the same yardstick |
+| Hypothesis | `train.py`, `config.yaml` | READ-WRITE | All experimental changes go here |
+
+This separation is the invariant that makes experiment comparisons valid.
+
+## Quick Start
+
+```bash
+# 1. Set up the environment
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# 2. Add your training data to {{DATA_SOURCE}}
+
+# 3. Create train/val/test splits
+python prepare.py
+
+# 4. Run training
+python train.py > run.log 2>&1
+
+# 5. Check results
+grep -A 10 "^---" run.log
+
+# 6. View experiment history
+python scripts/show_metrics.py
+```
+
+## Using the Autoresearch Agent
+
+The agent follows `program.md`. It:
+
+1. Reads recent experiment results
+2. Proposes a hypothesis
+3. Modifies `train.py` or `config.yaml`
+4. Runs training and evaluates
+5. Keeps improvements, discards regressions
+6. Repeats until convergence
+
+To start: `/turing:train` in Claude Code.
+For hands-off mode: `/loop 5m /turing:train`
+
+## Directory Structure
+
+```
+{{ML_DIR}}/
+  prepare.py              READ-ONLY: Data loading, splitting
+  evaluate.py             READ-ONLY: Evaluation harness
+  train.py                AGENT-EDITABLE: Training code
+  config.yaml             Hyperparameters and settings
+  sweep_config.yaml       Sweep parameter ranges
+  program.md              Agent protocol instructions
+  features/
+    featurizers.py         Feature engineering pipeline
+  scripts/
+    log_experiment.py      Experiment JSONL logging
+    show_metrics.py        Display experiment metrics
+    compare_runs.py        Side-by-side comparison
+    sweep.py               Hyperparameter sweep tool
+    post-train-hook.sh     Auto-log after training
+    stop-hook.sh           Convergence detection hook
+  experiments/
+    log.jsonl              Structured experiment log
+    results.tsv            Quick-reference summary
+  models/
+    best/                  Current best model
+    archive/               Previous best models
+  data/
+    splits/                Train/val/test splits
+  tests/
+    conftest.py            Shared test fixtures
+```
+
+## Running Tests
+
+```bash
+source .venv/bin/activate
+python -m pytest tests/ -v
+```

package/templates/config.yaml

@@ -0,0 +1,48 @@
+# {{PROJECT_NAME}} ML Pipeline Configuration
+# Edit this file to change hyperparameters. The autoresearch agent
+# modifies this file for hyperparameter experiments.
+
+data:
+  source: "{{DATA_SOURCE}}"
+  splits_dir: "data/splits"
+  target_column: "label"  # Column name for the prediction target
+  split_ratios:
+    train: 0.70
+    val: 0.15
+    test: 0.15
+  random_state: 42
+
+evaluation:
+  primary_metric: "{{TARGET_METRIC}}"
+  metrics: ["{{TARGET_METRIC}}", "f1_weighted", "accuracy"]
+  # Set to true for metrics where lower is better (mae, mse, rmse, loss)
+  # Set to false for metrics where higher is better (accuracy, f1, auc)
+  lower_is_better: false  # {{METRIC_DIRECTION}} -- change to true if lower is better
+
+convergence:
+  patience: 3                    # Consecutive non-improvements before stopping
+  improvement_threshold: 0.005   # 0.5% relative improvement required
+
+model:
+  type: "xgboost"
+  hyperparams:
+    n_estimators: 100
+    max_depth: 4
+    learning_rate: 0.1
+    objective: "multi:softmax"
+    num_class: 2        # Adjust for your number of classes
+    eval_metric: "mlogloss"
+    verbosity: 0
+
+output:
+  models_dir: "models"
+  best_model_dir: "models/best"
+  archive_dir: "models/archive"
+  experiment_log: "experiments/log.jsonl"
+  results_tsv: "experiments/results.tsv"
+
+# Behavioral probe constraints (enforced by hidden evaluation harness)
+# These prevent the agent from gaming the metric by skipping real work.
+constraints:
+  min_train_time: 5             # Seconds — training under this is suspicious
+  min_model_size_bytes: 100     # Bytes — a real model has non-trivial size