feat(dev): add research init scaffolding workflow

Author: Bakobiibizo

README.md

@@ -14,8 +14,9 @@ A single-binary Rust CLI for unified developer workflows:
 - Versioning (`dev version ...`)
 - `.env` helpers (`dev env ...`)
 - System setup (`dev setup ...`)
-- Dockerized GPU dev containers (`dev docker ...`)
-- Review overlays and directory manifests (`dev review`, `dev walk`)
+- Dockerized GPU dev containers (`dev docker ...`)
+- Isolated research project scaffolding (`dev research init`)
+- Review overlays and directory manifests (`dev review`, `dev walk`)
 
 ### `devkey` (Windows only)
 
@@ -84,7 +85,7 @@ dev install [rust|python|typescript]
 dev language set <name>
 ```
 
-### `.env` management
+### `.env` management
 
 ```bash
 dev env [--raw]
@@ -101,8 +102,20 @@ dev env init
 dev env template
 
 dev env diff [REF]
-dev env sync [REF]
-```
+dev env sync [REF]
+```
+
+### Research management
+
+```bash
+# Scaffold an isolated, project-local research workspace
+dev research init [DIR] --name <project-name> --package <python_package>
+
+# Preview without writing files
+dev --dry-run research init ./research/heu-exp-01
+```
+
+`dev research init` creates a clean-room research layout (`project.yaml`, `experiments/`, `src/<package>/bindings/`, `reports/templates/`, `.harness/`) and sets `HARNESS_HOME=.harness` so runs remain project-local and commit-friendly.
 
 ## Docker workflow (GPU dev container)
 

crates/dev/src/cli.rs

@@ -145,6 +145,11 @@ pub enum Command {
         #[command(subcommand)]
         command: DockerCommand,
     },
+    /// Research workflow management (isolated harness projects).
+    Research {
+        #[command(subcommand)]
+        command: ResearchCommand,
+    },
     /// Kubernetes helpers (contexts, namespaces, quick info)
     Kube {
         #[command(subcommand)]
@@ -164,6 +169,42 @@ pub enum Command {
     External(Vec<String>),
 }
 
+#[derive(Subcommand, Debug)]
+pub enum ResearchCommand {
+    /// Scaffold an isolated, project-local research workspace.
+    Init(ResearchInitArgs),
+}
+
+#[derive(Args, Debug)]
+pub struct ResearchInitArgs {
+    /// Target directory for the research project (default: current directory).
+    #[arg(default_value = ".")]
+    pub directory: PathBuf,
+
+    /// Project name written into project.yaml (default: directory name).
+    #[arg(long = "name")]
+    pub name: Option<String>,
+
+    /// Python package name for reusable bindings/logic.
+    #[arg(long = "package")]
+    pub package: Option<String>,
+
+    /// Overwrite scaffold files if they already exist.
+    #[arg(long = "force", default_value_t = false)]
+    pub force: bool,
+
+    /// Skip automatic harness dependency install with uv.
+    #[arg(long = "skip-install", default_value_t = false)]
+    pub skip_install: bool,
+
+    /// Git URL used to install research-harness.
+    #[arg(
+        long = "harness-git",
+        default_value = "https://github.com/hydra-dynamix/research-harness-2.git"
+    )]
+    pub harness_git: String,
+}
+
 #[derive(Subcommand, Debug)]
 pub enum OsCommand {
     /// Switch to Windows configuration (uses npx.cmd, .cmd extensions).

crates/dev/src/runner.rs

@@ -1,20 +1,20 @@
-use std::io::{BufRead, BufReader};
-use std::path::{Path, PathBuf};
-use std::process::{Command as ProcessCommand, Stdio};
-use std::thread;
-use std::time::Instant;
+use std::io::{BufRead, BufReader};
+use std::path::{Path, PathBuf};
+use std::process::{Command as ProcessCommand, Stdio};
+use std::thread;
+use std::time::Instant;
 use std::{fs, io};
 
 use anyhow::{Context, Result, anyhow, bail};
 use camino::Utf8PathBuf;
 use clap::Parser;
 
-use crate::cli::{
-    Cli, Command, ConfigCommand, DockerBuildArgs, DockerCommand, DockerComposeCommand,
-    DockerComposeUpCommand, DockerComposeUpBuildArgs, DockerInitArgs, EnvArgs, EnvCommand,
-    GitCommand, InstallArgs, KubeCommand, LanguageCommand, OsCommand, SetupCommand, StartArgs,
-    VaultCommand, Verb, VersionCommand,
-};
+use crate::cli::{
+    Cli, Command, ConfigCommand, DockerBuildArgs, DockerCommand, DockerComposeCommand,
+    DockerComposeUpCommand, DockerComposeUpBuildArgs, DockerInitArgs, EnvArgs, EnvCommand,
+    GitCommand, InstallArgs, KubeCommand, LanguageCommand, OsCommand, ResearchCommand,
+    ResearchInitArgs, SetupCommand, StartArgs, VaultCommand, Verb, VersionCommand,
+};
 use crate::config::{DevConfig, TaskUpdateMode};
 use crate::envfile;
 use crate::tasks::{CommandSpec, TaskIndex};
@@ -157,8 +157,8 @@ pub fn run(cli: Cli) -> Result<()> {
 }
 
 fn handle_with_state(state: &AppState, command: Command) -> Result<()> {
-    match command {
-        Command::List => handle_list(state),
+    match command {
+        Command::List => handle_list(state),
         Command::Run { task } => handle_run(state, &task),
         Command::Start(args) => handle_start(state, args),
         Command::Fmt => handle_verb(state, Verb::Fmt),
@@ -174,8 +174,9 @@ fn handle_with_state(state: &AppState, command: Command) -> Result<()> {
         Command::Git { command } => handle_git(state, command),
         Command::Version { command } => handle_version(state, command),
         Command::Env(args) => handle_env(state, args),
-        Command::Docker { command } => handle_docker(state, command),
-        Command::Kube { command } => handle_kube(state, command),
+        Command::Docker { command } => handle_docker(state, command),
+        Command::Research { command } => handle_research(state, command),
+        Command::Kube { command } => handle_kube(state, command),
         Command::Vault { command } => handle_vault(state, command),
         Command::Os { command } => handle_os(state, command),
         Command::Config { .. } => unreachable!("config commands handled earlier"),
@@ -186,7 +187,217 @@ fn handle_with_state(state: &AppState, command: Command) -> Result<()> {
             bail!("unknown command: {}", extra.join(" "))
         }
     }
-}
+}
+
+fn handle_research(state: &AppState, command: ResearchCommand) -> Result<()> {
+    match command {
+        ResearchCommand::Init(args) => research_init(state, args),
+    }
+}
+
+fn research_init(state: &AppState, args: ResearchInitArgs) -> Result<()> {
+    let target = if args.directory.is_absolute() {
+        args.directory.clone()
+    } else {
+        std::env::current_dir()?.join(&args.directory)
+    };
+    let target = target
+        .canonicalize()
+        .unwrap_or_else(|_| target.clone());
+
+    let project_name = args.name.unwrap_or_else(|| {
+        target
+            .file_name()
+            .map(|s| s.to_string_lossy().to_string())
+            .filter(|s| !s.trim().is_empty())
+            .unwrap_or_else(|| "research-project".to_owned())
+    });
+    let package_name = args
+        .package
+        .unwrap_or_else(|| normalize_package_name(&project_name));
+
+    if target.exists() && target.read_dir()?.next().is_some() && !args.force {
+        bail!(
+            "target directory is not empty: {} (rerun with --force to overwrite scaffold files)",
+            target.display()
+        );
+    }
+
+    if state.ctx.dry_run {
+        println!("[dry-run] would initialize research project at {}", target.display());
+        println!("[dry-run] project name: {}", project_name);
+        println!("[dry-run] package name: {}", package_name);
+        if !args.skip_install {
+            println!(
+                "[dry-run] would run: uv add \"research-harness @ git+{}\"",
+                args.harness_git
+            );
+        }
+        return Ok(());
+    }
+
+    fs::create_dir_all(&target)
+        .with_context(|| format!("creating {}", target.display()))?;
+
+    let project_yaml = format!(
+        "name: {name}\nversion: \"0.1.0\"\ndescription: \"\"\n\nexperiments:\n  - id: example\n    module: experiments.example\n    callable: run\n    description: \"Example experiment\"\n\nconfig:\n  default: configs/default.yaml\n\ndatasets: []\n\nthresholds: configs/thresholds.yaml\n\noutputs:\n  format: parquet\n",
+        name = project_name
+    );
+
+    let default_config = "# Default experiment configuration.\n";
+    let thresholds = "thresholds: {}\n";
+    let experiments_init = "\"\"\"Experiments package.\"\"\"\n";
+    let example_exp = "\"\"\"Example experiment module.\"\"\"\n\n\ndef run(seed: int, output_dir, **kwargs):\n    \"\"\"Run the example experiment.\"\"\"\n    return {\"status\": \"ok\", \"seed\": seed}\n";
+    let package_init = format!("\"\"\"Reusable package for {}.\"\"\"\n", project_name);
+    let bindings_init = "\"\"\"Bindings for target systems.\"\"\"\n";
+    let binding_example = "\"\"\"Example binding stub.\n\nImplement clean-room adapters here.\n\"\"\"\n";
+    let analysis_tpl = "# Analysis Report\n\n## Scope\n- Hypothesis:\n- Dataset(s):\n- Config + seed policy:\n\n## Results\n- Run IDs:\n- Threshold outcomes:\n- Key observations:\n\n## Risks / Caveats\n-\n";
+    let synthesis_tpl = "# Meta-Synthesis\n\n## Experiments Included\n-\n\n## Cross-Experiment Findings\n-\n\n## Plain-Language Overview\n-\n";
+    let env_example = "HARNESS_HOME=.harness\n";
+    let env_local = "HARNESS_HOME=.harness\n";
+
+    write_scaffold_file(&target.join("project.yaml"), &project_yaml, args.force)?;
+    write_scaffold_file(
+        &target.join("configs").join("default.yaml"),
+        default_config,
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target.join("configs").join("thresholds.yaml"),
+        thresholds,
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target.join("experiments").join("__init__.py"),
+        experiments_init,
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target.join("experiments").join("example.py"),
+        example_exp,
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target.join("src").join(&package_name).join("__init__.py"),
+        &package_init,
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target
+            .join("src")
+            .join(&package_name)
+            .join("bindings")
+            .join("__init__.py"),
+        bindings_init,
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target
+            .join("src")
+            .join(&package_name)
+            .join("bindings")
+            .join("example.py"),
+        binding_example,
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target
+            .join("reports")
+            .join("templates")
+            .join("analysis.md"),
+        analysis_tpl,
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target
+            .join("reports")
+            .join("templates")
+            .join("meta_synthesis.md"),
+        synthesis_tpl,
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target.join(".harness").join("runs").join(".gitkeep"),
+        "",
+        args.force,
+    )?;
+    write_scaffold_file(
+        &target.join(".harness").join("datasets").join(".gitkeep"),
+        "",
+        args.force,
+    )?;
+    write_scaffold_file(&target.join(".env.example"), env_example, args.force)?;
+    write_scaffold_file(&target.join(".env"), env_local, false)?;
+
+    if !args.skip_install {
+        let argv = vec![
+            "uv".to_owned(),
+            "add".to_owned(),
+            format!("research-harness @ git+{}", args.harness_git),
+        ];
+        println!("Installing harness dependency: {}", format_command(&argv));
+        let status = run_process_streaming_in_dir(&argv, &target)?;
+        if !status.success() {
+            bail!(
+                "command `{}` failed with exit code {:?}",
+                format_command(&argv),
+                status.code()
+            );
+        }
+    }
+
+    println!("Research project initialized at {}", target.display());
+    println!("  project.yaml");
+    println!("  configs/default.yaml");
+    println!("  configs/thresholds.yaml");
+    println!("  experiments/example.py");
+    println!("  src/{}/bindings/", package_name);
+    println!("  reports/templates/");
+    println!("  .harness/ (project-local run state)");
+    println!("  .env with HARNESS_HOME=.harness");
+
+    Ok(())
+}
+
+fn normalize_package_name(input: &str) -> String {
+    let mut out = String::new();
+    let mut prev_was_sep = false;
+    for ch in input.chars() {
+        if ch.is_ascii_alphanumeric() || ch == '_' {
+            out.push(ch.to_ascii_lowercase());
+            prev_was_sep = false;
+        } else if !prev_was_sep {
+            out.push('_');
+            prev_was_sep = true;
+        }
+    }
+    let trimmed = out.trim_matches('_').to_string();
+    let mut final_name = if trimmed.is_empty() {
+        "research_project".to_owned()
+    } else {
+        trimmed
+    };
+    if final_name
+        .chars()
+        .next()
+        .map(|c| c.is_ascii_digit())
+        .unwrap_or(false)
+    {
+        final_name = format!("pkg_{}", final_name);
+    }
+    final_name
+}
+
+fn write_scaffold_file(path: &Path, content: &str, force: bool) -> Result<()> {
+    if path.exists() && !force {
+        return Ok(());
+    }
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).with_context(|| format!("creating {}", parent.display()))?;
+    }
+    fs::write(path, content).with_context(|| format!("writing {}", path.display()))?;
+    Ok(())
+}
 
 fn handle_docker(state: &AppState, command: DockerCommand) -> Result<()> {
     match command {

docs/USAGE.md

@@ -53,6 +53,17 @@ Global flags:
 
 - `dev install [language]` – scaffold language-specific config files and run optional provisioning commands defined in config. Supports `--dry-run` to preview actions.
 
+### Research Scaffolding
+
+- `dev research init [directory] [--name <name>] [--package <pkg>] [--force] [--skip-install]`
+  - Creates an isolated, project-local research scaffold with:
+    - `project.yaml`
+    - `configs/`, `experiments/`, `src/<package>/bindings/`
+    - `reports/templates/`
+    - `.harness/runs` and `.harness/datasets`
+    - `.env` with `HARNESS_HOME=.harness`
+  - Installs harness dependency via `uv add "research-harness @ git+<url>"` unless `--skip-install` is passed.
+
 ## Git Automation
 
 - `dev git branch-create <name> [--from <base>] [--push] [--allow-dirty]`