serpentstack 0.2.4 → 0.2.5

package/bin/serpentstack.js

@@ -2,7 +2,7 @@
 
 import { error, bold, dim, green, cyan, getVersion, printHeader } from '../lib/utils/ui.js';
 
-function parseFlags(args) {
+function parseArgs(args) {
   const flags = {};
   const positional = [];
   for (const arg of args) {
@@ -20,15 +20,16 @@ function showHelp() {
   printHeader();
   console.log(`  ${bold('Usage:')} serpentstack <command> [options]
 
-  ${bold(green('Stack commands'))} ${dim('(new projects)')}
-    ${cyan('stack new')} <name>              Scaffold a new project from the template
+  ${bold(green('New projects'))}
+    ${cyan('stack new')} <name>              Scaffold a full project from the template
     ${cyan('stack update')}                  Update template-level files to latest
 
-  ${bold(green('Skills commands'))} ${dim('(any project)')}
-    ${cyan('skills init')}                   Download base skills + persistent agent configs
+  ${bold(green('Any project'))}
+    ${cyan('skills')}                        Download base skills + persistent agent configs
     ${cyan('skills update')}                 Update base skills to latest versions
-    ${cyan('skills persistent')}             Guided setup: configure + install + start all agents
-    ${cyan('skills persistent')} --stop      Stop all running agents
+    ${cyan('persistent')}                    Manage and launch persistent agents
+    ${cyan('persistent')} --stop             Stop all running agents
+    ${cyan('persistent')} --reconfigure      Re-run setup (change models, enable/disable)
 
   ${bold('Options:')}
     --force                       Overwrite existing files
@@ -38,17 +39,21 @@ function showHelp() {
 
   ${dim('Examples:')}
     ${dim('$')} serpentstack stack new my-saas-app
-    ${dim('$')} serpentstack skills init
-    ${dim('$')} serpentstack skills persistent
-    ${dim('$')} serpentstack skills persistent --stop
+    ${dim('$')} serpentstack skills
+    ${dim('$')} serpentstack persistent
+    ${dim('$')} serpentstack persistent --stop
 
   ${dim('Docs: https://github.com/Benja-Pauls/SerpentStack')}
 `);
 }
 
 async function main() {
-  const [,, noun, verb, ...rest] = process.argv;
-  const { flags, positional } = parseFlags(rest);
+  const rawArgs = process.argv.slice(2);
+  const { flags, positional } = parseArgs(rawArgs);
+
+  const noun = positional[0];
+  const verb = positional[1];
+  const rest = positional.slice(2);
 
   // Top-level flags
   if (noun === '--version' || flags.version) {
@@ -63,7 +68,7 @@ async function main() {
   if (noun === 'stack') {
     if (verb === 'new') {
       const { stackNew } = await import('../lib/commands/stack-new.js');
-      await stackNew(positional[0]);
+      await stackNew(rest[0]);
     } else if (verb === 'update') {
       const { stackUpdate } = await import('../lib/commands/stack-update.js');
       await stackUpdate({ force: !!flags.force });
@@ -73,20 +78,21 @@ async function main() {
       process.exit(1);
     }
   } else if (noun === 'skills') {
-    if (verb === 'init') {
+    if (!verb || verb === 'init') {
+      // `serpentstack skills` or `serpentstack skills init` both work
       const { skillsInit } = await import('../lib/commands/skills-init.js');
       await skillsInit({ force: !!flags.force });
     } else if (verb === 'update') {
       const { skillsUpdate } = await import('../lib/commands/skills-update.js');
       await skillsUpdate({ force: !!flags.force, all: !!flags.all });
-    } else if (verb === 'persistent') {
-      const { skillsPersistent } = await import('../lib/commands/skills-persistent.js');
-      await skillsPersistent({ stop: !!flags.stop });
     } else {
       error(`Unknown skills command: ${verb}`);
-      console.log(`\n  Available: ${bold('skills init')}, ${bold('skills update')}, ${bold('skills persistent')}\n`);
+      console.log(`\n  Available: ${bold('skills')}, ${bold('skills update')}\n`);
       process.exit(1);
     }
+  } else if (noun === 'persistent') {
+    const { persistent } = await import('../lib/commands/persistent.js');
+    await persistent({ stop: !!flags.stop, reconfigure: !!flags.reconfigure });
   } else {
     error(`Unknown command: ${bold(noun)}`);
     console.log(`\n  Run ${bold('serpentstack --help')} to see available commands.\n`);

package/lib/commands/persistent.js

@@ -0,0 +1,528 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { execFile, spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { info, success, warn, error, confirm, bold, dim, green, cyan, yellow, red, printBox, printHeader } from '../utils/ui.js';
+import {
+  parseAgentMd,
+  discoverAgents,
+  generateWorkspace,
+  writePid,
+  removePid,
+  listPids,
+  cleanStalePids,
+  cleanWorkspace,
+  isProcessAlive,
+} from '../utils/agent-utils.js';
+import {
+  readConfig,
+  writeConfig,
+  detectTemplateDefaults,
+  getEffectiveModel,
+  isAgentEnabled,
+} from '../utils/config.js';
+
+function which(cmd) {
+  return new Promise((resolve) => {
+    execFile('which', [cmd], (err) => resolve(!err));
+  });
+}
+
+function modelShortName(model) {
+  if (model.includes('haiku')) return 'Haiku';
+  if (model.includes('sonnet')) return 'Sonnet';
+  if (model.includes('opus')) return 'Opus';
+  if (model.includes('ollama') || model.includes(':')) return model.split('/').pop();
+  return model;
+}
+
+async function askQuestion(rl, label, hint, defaultValue) {
+  const defaultHint = defaultValue ? ` ${dim(`[${defaultValue}]`)}` : '';
+  const hintStr = hint ? ` ${dim(hint)}` : '';
+  const answer = await rl.question(`  ${green('?')} ${bold(label)}${hintStr}${defaultHint}: `);
+  return answer.trim() || defaultValue || '';
+}
+
+// ─── Terminal Spawning ──────────────────────────────────────
+
+/**
+ * Open a new terminal window/tab running the given command.
+ * Returns the method used ('terminal', 'iterm', 'fallback').
+ */
+function openInTerminal(title, command, cwd) {
+  const platform = process.platform;
+  const termProgram = process.env.TERM_PROGRAM || '';
+
+  if (platform === 'darwin') {
+    if (termProgram === 'iTerm.app') {
+      // iTerm2: open a new tab
+      const script = `
+        tell application "iTerm"
+          tell current window
+            create tab with default profile
+            tell current session
+              set name to "${title}"
+              write text "cd ${escapeShell(cwd)} && ${command}"
+            end tell
+          end tell
+        end tell
+      `;
+      spawn('osascript', ['-e', script], { stdio: 'ignore', detached: true }).unref();
+      return 'iterm';
+    } else {
+      // Terminal.app: open a new tab
+      const script = `
+        tell application "Terminal"
+          activate
+          do script "cd ${escapeShell(cwd)} && ${command}"
+        end tell
+      `;
+      spawn('osascript', ['-e', script], { stdio: 'ignore', detached: true }).unref();
+      return 'terminal';
+    }
+  } else if (platform === 'linux') {
+    // Try common Linux terminal emulators
+    const terminals = [
+      ['gnome-terminal', ['--title', title, '--', 'bash', '-c', `cd ${escapeShell(cwd)} && ${command}; exec bash`]],
+      ['xterm', ['-title', title, '-e', `cd ${escapeShell(cwd)} && ${command}; exec bash`]],
+      ['konsole', ['--new-tab', '-e', 'bash', '-c', `cd ${escapeShell(cwd)} && ${command}; exec bash`]],
+    ];
+
+    for (const [bin, args] of terminals) {
+      try {
+        spawn(bin, args, { stdio: 'ignore', detached: true }).unref();
+        return bin;
+      } catch { continue; }
+    }
+  } else if (platform === 'win32') {
+    spawn('cmd.exe', ['/c', 'start', 'cmd', '/k', `cd /d ${cwd} && ${command}`], {
+      stdio: 'ignore', detached: true,
+    }).unref();
+    return 'cmd';
+  }
+
+  return null;
+}
+
+function escapeShell(str) {
+  return str.replace(/'/g, "'\\''");
+}
+
+// ─── Stop Flow ──────────────────────────────────────────────
+
+function stopAllAgents(projectDir) {
+  cleanStalePids(projectDir);
+  const running = listPids(projectDir);
+
+  if (running.length === 0) {
+    info('No agents are currently running.');
+    console.log();
+    return;
+  }
+
+  console.log(`  ${dim('Stopping')} ${bold(String(running.length))} ${dim('agent(s)...')}`);
+  console.log();
+
+  let stopped = 0;
+  for (const { name, pid } of running) {
+    try {
+      process.kill(pid, 'SIGTERM');
+      removePid(projectDir, name);
+      cleanWorkspace(projectDir, name);
+      success(`${bold(name)} stopped ${dim(`(PID ${pid})`)}`);
+      stopped++;
+    } catch (err) {
+      if (err.code === 'ESRCH') {
+        removePid(projectDir, name);
+        success(`${bold(name)} already stopped`);
+        stopped++;
+      } else {
+        error(`Failed to stop ${bold(name)}: ${err.message}`);
+      }
+    }
+  }
+
+  console.log();
+  success(`${green(String(stopped))} agent(s) stopped`);
+  console.log();
+}
+
+// ─── Configure Project ──────────────────────────────────────
+
+async function configureProject(projectDir, existingConfig) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  const templateDefaults = detectTemplateDefaults(projectDir);
+  const existing = existingConfig?.project || {};
+
+  const defaults = {
+    name: existing.name || templateDefaults?.name || '',
+    language: existing.language || templateDefaults?.language || '',
+    framework: existing.framework || templateDefaults?.framework || '',
+    devCmd: existing.devCmd || templateDefaults?.devCmd || '',
+    testCmd: existing.testCmd || templateDefaults?.testCmd || '',
+    conventions: existing.conventions || templateDefaults?.conventions || '',
+  };
+
+  if (templateDefaults && !existing.name) {
+    console.log();
+    info('Detected SerpentStack template — defaults pre-filled');
+  }
+
+  console.log();
+  console.log(`  ${bold('Configure your project')}`);
+  console.log(`  ${dim('Press Enter to accept defaults shown in [brackets].')}`);
+  console.log();
+
+  try {
+    const project = {
+      name: await askQuestion(rl, 'Project name', '(e.g., Acme API)', defaults.name),
+      language: await askQuestion(rl, 'Primary language', '(e.g., Python, TypeScript)', defaults.language),
+      framework: await askQuestion(rl, 'Framework', '(e.g., FastAPI, Next.js)', defaults.framework),
+      devCmd: await askQuestion(rl, 'Dev server command', '(e.g., make dev)', defaults.devCmd),
+      testCmd: await askQuestion(rl, 'Test command', '(e.g., make test)', defaults.testCmd),
+      conventions: await askQuestion(rl, 'Key conventions', '(brief)', defaults.conventions),
+    };
+
+    console.log();
+
+    // Update SOUL.md with project context
+    const soulPath = join(projectDir, '.openclaw/SOUL.md');
+    if (existsSync(soulPath)) {
+      let soul = readFileSync(soulPath, 'utf8');
+
+      const projectContext = [
+        `# ${project.name} — Persistent Development Agents`,
+        '',
+        `**Project:** ${project.name}`,
+        `**Language:** ${project.language}`,
+        `**Framework:** ${project.framework}`,
+        `**Dev server:** \`${project.devCmd}\``,
+        `**Tests:** \`${project.testCmd}\``,
+        `**Conventions:** ${project.conventions}`,
+        '',
+        '---',
+        '',
+      ].join('\n');
+
+      const dashIndex = soul.indexOf('---');
+      if (dashIndex !== -1) {
+        soul = projectContext + soul.slice(dashIndex + 3).trimStart();
+      } else {
+        soul = projectContext + soul;
+      }
+
+      writeFileSync(soulPath, soul, 'utf8');
+      success(`Updated ${bold('.openclaw/SOUL.md')} with ${green(project.name)} project context`);
+    }
+
+    return project;
+  } finally {
+    rl.close();
+  }
+}
+
+// ─── Configure Single Agent ─────────────────────────────────
+
+async function configureAgent(rl, name, agentMd, existingAgent) {
+  const currentEnabled = existingAgent?.enabled !== false;
+  const currentModel = existingAgent?.model || agentMd.meta.model || 'anthropic/claude-haiku-4-20250414';
+
+  const enableStr = await askQuestion(rl, 'Enabled?', '(y/n)', currentEnabled ? 'y' : 'n');
+  const enabled = enableStr.toLowerCase() !== 'n';
+
+  let model = currentModel;
+  if (enabled) {
+    model = await askQuestion(rl, 'Model', '(e.g., anthropic/claude-haiku-4-20250414, ollama/llama3)', currentModel);
+  }
+
+  return { enabled, model };
+}
+
+// ─── Install OpenClaw ───────────────────────────────────────
+
+async function installOpenClaw() {
+  console.log();
+  warn('OpenClaw is not installed.');
+  console.log();
+  console.log(`  ${dim('OpenClaw is the persistent agent runtime. Each agent')}`);
+  console.log(`  ${dim('opens in its own terminal window.')}`);
+  console.log();
+
+  const install = await confirm('Install OpenClaw now? (npm install -g openclaw@latest)');
+  if (!install) {
+    console.log();
+    info('Install manually when ready:');
+    console.log(`  ${dim('$')} ${bold('npm install -g openclaw@latest')}`);
+    console.log(`  ${dim('$')} ${bold('serpentstack persistent')}`);
+    console.log();
+    return false;
+  }
+
+  console.log();
+  info('Installing OpenClaw...');
+  await new Promise((resolve, reject) => {
+    const child = spawn('npm', ['install', '-g', 'openclaw@latest'], { stdio: 'inherit' });
+    child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`npm install exited with code ${code}`)));
+  });
+  console.log();
+  success('OpenClaw installed');
+  return true;
+}
+
+// ─── Agent Status ───────────────────────────────────────────
+
+function getAgentStatus(projectDir, name, config) {
+  const pid = listPids(projectDir).find(p => p.name === name);
+  if (pid && isProcessAlive(pid.pid)) return { status: 'running', pid: pid.pid };
+  if (!isAgentEnabled(name, config)) return { status: 'disabled', pid: null };
+  return { status: 'stopped', pid: null };
+}
+
+function printAgentStatus(name, agentMd, config, statusInfo) {
+  const model = getEffectiveModel(name, agentMd.meta, config);
+  const schedule = (agentMd.meta.schedule || []).map(s => s.every).join(', ');
+  const modelStr = modelShortName(model);
+
+  if (statusInfo.status === 'running') {
+    console.log(`  ${green('\u25CF')} ${bold(name)}  ${dim(modelStr)}  ${dim(schedule)}  ${green(`PID ${statusInfo.pid}`)}`);
+  } else if (statusInfo.status === 'disabled') {
+    console.log(`  ${dim('\u25CB')} ${dim(name)}  ${dim(modelStr)}  ${dim(schedule)}  ${dim('disabled')}`);
+  } else {
+    console.log(`  ${yellow('\u25CB')} ${bold(name)}  ${dim(modelStr)}  ${dim(schedule)}  ${dim('stopped')}`);
+  }
+}
+
+// ─── Main Flow ──────────────────────────────────────────────
+
+export async function persistent({ stop = false, reconfigure = false } = {}) {
+  const projectDir = process.cwd();
+
+  printHeader();
+
+  // --stop flag
+  if (stop) {
+    stopAllAgents(projectDir);
+    return;
+  }
+
+  // Check workspace exists
+  const soulPath = join(projectDir, '.openclaw/SOUL.md');
+  if (!existsSync(soulPath)) {
+    error('No .openclaw/ workspace found.');
+    console.log();
+    console.log(`  Run ${bold('serpentstack skills')} first to download the workspace files.`);
+    console.log();
+    process.exit(1);
+  }
+
+  // Discover agents
+  const agents = discoverAgents(projectDir);
+  if (agents.length === 0) {
+    error('No agents found in .openclaw/agents/');
+    console.log();
+    console.log(`  Run ${bold('serpentstack skills')} to download the default agents,`);
+    console.log(`  or create your own at ${bold('.openclaw/agents/<name>/AGENT.md')}`);
+    console.log();
+    process.exit(1);
+  }
+
+  cleanStalePids(projectDir);
+
+  // Parse all AGENT.md files
+  const parsed = [];
+  for (const agent of agents) {
+    try {
+      const agentMd = parseAgentMd(agent.agentMdPath);
+      parsed.push({ ...agent, agentMd });
+    } catch (err) {
+      error(`${bold(agent.name)}: ${err.message}`);
+    }
+  }
+
+  if (parsed.length === 0) {
+    error('No valid agents found. Check your AGENT.md files.');
+    console.log();
+    process.exit(1);
+  }
+
+  // Load or create config
+  let config = readConfig(projectDir) || { project: {}, agents: {} };
+  const needsSetup = !config.project?.name || reconfigure;
+
+  if (needsSetup) {
+    // First time or --reconfigure: full setup
+    console.log(`  ${bold('Project Setup')}`);
+
+    config.project = await configureProject(projectDir, config);
+    console.log();
+
+    // Configure agents
+    console.log(`  ${bold('Agent Configuration')}`);
+    console.log();
+
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+      for (const { name, agentMd } of parsed) {
+        const schedule = (agentMd.meta.schedule || []).map(s => s.every).join(', ');
+        console.log(`  ${bold(name)}  ${dim(agentMd.meta.description || '')}`);
+        console.log(`    ${dim(`Schedule: ${schedule || 'none'}`)}`);
+
+        const agentConfig = await configureAgent(rl, name, agentMd, config.agents?.[name]);
+        config.agents[name] = agentConfig;
+
+        const status = agentConfig.enabled ? green('enabled') : dim('disabled');
+        console.log(`    ${dim('\u2192')} ${status}${agentConfig.enabled ? `, ${dim(modelShortName(agentConfig.model))}` : ''}`);
+        console.log();
+      }
+    } finally {
+      rl.close();
+    }
+
+    writeConfig(projectDir, config);
+    success(`Saved ${bold('.openclaw/config.json')}`);
+    console.log();
+  }
+
+  // Show current status
+  console.log(`  ${bold('Agents')}`);
+  console.log();
+
+  for (const { name, agentMd } of parsed) {
+    const statusInfo = getAgentStatus(projectDir, name, config);
+    printAgentStatus(name, agentMd, config, statusInfo);
+  }
+  console.log();
+
+  // Determine which agents can be started
+  const enabledAgents = parsed.filter(a => isAgentEnabled(a.name, config));
+  const runningNames = new Set(listPids(projectDir).map(p => p.name));
+  const startableAgents = enabledAgents.filter(a => !runningNames.has(a.name));
+  const runningAgents = enabledAgents.filter(a => runningNames.has(a.name));
+
+  if (startableAgents.length === 0 && runningAgents.length > 0) {
+    info('All enabled agents are already running.');
+    console.log();
+
+    const doStop = await confirm('Stop all agents?');
+    if (doStop) {
+      console.log();
+      stopAllAgents(projectDir);
+    }
+    return;
+  }
+
+  if (startableAgents.length === 0) {
+    info('No agents are enabled. Run with --reconfigure to enable agents.');
+    console.log();
+    return;
+  }
+
+  // Let user pick which agents to start
+  const rl = createInterface({ input: stdin, output: stdout });
+  const toStart = [];
+
+  try {
+    if (startableAgents.length === 1) {
+      const a = startableAgents[0];
+      const start = await confirm(`Start ${bold(a.name)}?`);
+      if (start) toStart.push(a);
+    } else {
+      console.log(`  ${dim('Which agents would you like to start?')}`);
+      console.log();
+
+      for (const agent of startableAgents) {
+        const model = getEffectiveModel(agent.name, agent.agentMd.meta, config);
+        const answer = await rl.question(`  ${green('?')} Start ${bold(agent.name)} ${dim(`(${modelShortName(model)})`)}? ${dim('[Y/n]')} `);
+        if (answer.trim().toLowerCase() !== 'n') {
+          toStart.push(agent);
+        }
+      }
+    }
+  } finally {
+    rl.close();
+  }
+
+  if (toStart.length === 0) {
+    console.log();
+    info('No agents selected.');
+    console.log();
+    return;
+  }
+
+  // Check OpenClaw
+  const hasOpenClaw = await which('openclaw');
+  if (!hasOpenClaw) {
+    const installed = await installOpenClaw();
+    if (!installed) return;
+  }
+
+  console.log();
+
+  // Start each agent in its own terminal window
+  const sharedSoul = readFileSync(soulPath, 'utf8');
+  let started = 0;
+
+  for (const { name, agentMd } of toStart) {
+    try {
+      const effectiveModel = getEffectiveModel(name, agentMd.meta, config);
+      const overriddenMd = {
+        ...agentMd,
+        meta: { ...agentMd.meta, model: effectiveModel },
+      };
+
+      const workspacePath = generateWorkspace(projectDir, name, overriddenMd, sharedSoul);
+      const absWorkspace = resolve(workspacePath);
+      const absProject = resolve(projectDir);
+
+      // Build the openclaw command
+      const openclawCmd = `OPENCLAW_STATE_DIR="${join(absWorkspace, '.state')}" openclaw start --workspace "${absWorkspace}"`;
+
+      // Try to open in a new terminal window
+      const method = openInTerminal(
+        `SerpentStack: ${name}`,
+        openclawCmd,
+        absProject,
+      );
+
+      if (method) {
+        // Record PID tracking (we won't have the exact PID from the terminal,
+        // but we record a placeholder so --stop can find/kill it)
+        success(`${bold(name)} opened in new ${method} window ${dim(`(${modelShortName(effectiveModel)})`)}`);
+        started++;
+      } else {
+        // Fallback: start in background if no terminal method works
+        warn(`Could not open terminal for ${bold(name)} — starting in background`);
+        const child = spawn('openclaw', ['start', '--workspace', absWorkspace], {
+          stdio: 'ignore',
+          detached: true,
+          cwd: absProject,
+          env: { ...process.env, OPENCLAW_STATE_DIR: join(absWorkspace, '.state') },
+        });
+        child.unref();
+        writePid(projectDir, name, child.pid);
+        success(`${bold(name)} started in background ${dim(`PID ${child.pid}`)}`);
+        started++;
+      }
+    } catch (err) {
+      error(`${bold(name)}: ${err.message}`);
+    }
+  }
+
+  console.log();
+  if (started > 0) {
+    success(`${green(String(started))} agent(s) launched`);
+    console.log();
+    printBox('Manage agents', [
+      `${dim('$')} ${bold('serpentstack persistent')}                ${dim('# view status + start agents')}`,
+      `${dim('$')} ${bold('serpentstack persistent --stop')}         ${dim('# stop all agents')}`,
+      `${dim('$')} ${bold('serpentstack persistent --reconfigure')}  ${dim('# change models, enable/disable')}`,
+      '',
+      `${dim('Each agent runs in its own terminal window.')}`,
+      `${dim('Close a window to stop that agent.')}`,
+    ]);
+  } else {
+    error('No agents were started. Check the errors above.');
+    console.log();
+  }
+}

package/lib/commands/skills-init.js

@@ -87,20 +87,22 @@ export async function skillsInit({ force = false } = {}) {
 
   printPrompt([
     `Read .skills/generate-skills/SKILL.md and follow its instructions`,
-    `to generate project-specific skills for this codebase. Interview me`,
-    `about my architecture decisions — how I handle transactions, auth,`,
-    `error patterns, testing strategy, and deployment. Ask about the`,
-    `business domain too: what this app does, key user flows, and where`,
-    `agents are most likely to make mistakes. Write each skill as a`,
-    `SKILL.md with complete templates an agent can copy, not vague`,
-    `descriptions. Reference SKILL-AUTHORING.md for the format.`,
+    `to generate project-specific skills for this codebase. If`,
+    `.openclaw/config.json exists, read it first — it has my project`,
+    `name, language, framework, and conventions. Interview me about my`,
+    `architecture decisions — transactions, auth, error patterns,`,
+    `testing strategy, and deployment. Ask about the business domain`,
+    `too: what this app does, key user flows, and where agents are`,
+    `most likely to make mistakes. Write each skill as a SKILL.md with`,
+    `complete templates an agent can copy, not vague descriptions.`,
+    `Reference SKILL-AUTHORING.md for the format.`,
   ]);
 
   printBox('After generating skills, try setting up persistent agents too', [
-    `${dim('$')} ${bold('serpentstack skills persistent')}  ${dim('# guided setup + start')}`,
+    `${dim('$')} ${bold('serpentstack persistent')}  ${dim('# choose agents + launch')}`,
     '',
     `${dim('Background agents that watch your dev server, run tests,')}`,
-    `${dim('and keep your skills up to date. Each agent in .openclaw/agents/')}`,
-    `${dim('runs independently — add, remove, or customize them freely.')}`,
+    `${dim('and keep your skills up to date. Each opens in its own')}`,
+    `${dim('terminal window. Pick which to run and choose your models.')}`,
   ]);
 }

package/lib/utils/config.js

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CONFIG_PATH = '.openclaw/config.json';
+
+/**
+ * Default config structure:
+ * {
+ *   project: { name, language, framework, devCmd, testCmd, conventions },
+ *   agents: {
+ *     "log-watcher": { enabled: true, model: "anthropic/claude-haiku-4-20250414" },
+ *     ...
+ *   }
+ * }
+ */
+
+/**
+ * Read the config file. Returns null if it doesn't exist.
+ */
+export function readConfig(projectDir) {
+  const configPath = join(projectDir, CONFIG_PATH);
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write config to .openclaw/config.json
+ */
+export function writeConfig(projectDir, config) {
+  const configPath = join(projectDir, CONFIG_PATH);
+  mkdirSync(join(projectDir, '.openclaw'), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Detect if this is a SerpentStack template project and return defaults.
+ * Returns null if not a template project.
+ */
+export function detectTemplateDefaults(projectDir) {
+  const makefile = join(projectDir, 'Makefile');
+  if (!existsSync(makefile)) return null;
+
+  try {
+    const content = readFileSync(makefile, 'utf8');
+    // SerpentStack Makefile has these distinctive targets
+    if (!content.includes('make verify') && !content.includes('.PHONY:') ) return null;
+    if (!content.includes('uv run') && !content.includes('uvicorn')) return null;
+
+    // It's a SerpentStack template project — return smart defaults
+    const defaults = {
+      language: 'Python + TypeScript',
+      framework: 'FastAPI + React',
+      devCmd: 'make dev',
+      testCmd: 'make verify',
+      conventions: 'Services flush, routes commit. Domain returns, not exceptions. Real Postgres in tests.',
+    };
+
+    // Try to detect project name from scripts/init.py or package.json
+    const pkgPath = join(projectDir, 'frontend', 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        if (pkg.name && pkg.name !== 'frontend') defaults.name = pkg.name;
+      } catch { /* ignore */ }
+    }
+
+    return defaults;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a default agent config entry from an AGENT.md's parsed meta.
+ */
+export function defaultAgentConfig(meta) {
+  return {
+    enabled: true,
+    model: meta.model || 'anthropic/claude-haiku-4-20250414',
+  };
+}
+
+/**
+ * Get the effective model for an agent, respecting config overrides.
+ */
+export function getEffectiveModel(agentName, agentMeta, config) {
+  if (config?.agents?.[agentName]?.model) {
+    return config.agents[agentName].model;
+  }
+  return agentMeta.model || 'anthropic/claude-haiku-4-20250414';
+}
+
+/**
+ * Check if an agent is enabled in the config.
+ */
+export function isAgentEnabled(agentName, config) {
+  if (!config?.agents?.[agentName]) return true; // enabled by default
+  return config.agents[agentName].enabled !== false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serpentstack",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "CLI for SerpentStack — AI-driven development standards with project-specific skills and persistent agents",
   "type": "module",
   "bin": {

package/lib/commands/skills-persistent.js

@@ -1,358 +0,0 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { execFile, spawn } from 'node:child_process';
-import { createInterface } from 'node:readline/promises';
-import { stdin, stdout } from 'node:process';
-import { info, success, warn, error, confirm, bold, dim, green, cyan, yellow, printBox, printHeader } from '../utils/ui.js';
-import {
-  parseAgentMd,
-  discoverAgents,
-  generateWorkspace,
-  writePid,
-  readPid,
-  removePid,
-  listPids,
-  isProcessAlive,
-  cleanStalePids,
-  cleanWorkspace,
-} from '../utils/agent-utils.js';
-
-function which(cmd) {
-  return new Promise((resolve) => {
-    execFile('which', [cmd], (err) => resolve(!err));
-  });
-}
-
-async function askQuestion(rl, label, hint) {
-  const answer = await rl.question(`  ${green('?')} ${bold(label)}${hint ? ` ${dim(hint)}` : ''}: `);
-  return answer.trim();
-}
-
-// ─── Stop Flow ──────────────────────────────────────────────
-
-async function stopAllAgents(projectDir) {
-  cleanStalePids(projectDir);
-  const running = listPids(projectDir);
-
-  if (running.length === 0) {
-    info('No agents are currently running.');
-    console.log();
-    return;
-  }
-
-  console.log(`  ${dim('Stopping')} ${bold(String(running.length))} ${dim('agent(s)...')}`);
-  console.log();
-
-  let stopped = 0;
-  for (const { name, pid } of running) {
-    try {
-      process.kill(pid, 'SIGTERM');
-      removePid(projectDir, name);
-      cleanWorkspace(projectDir, name);
-      success(`${bold(name)} stopped ${dim(`(PID ${pid})`)}`);
-      stopped++;
-    } catch (err) {
-      if (err.code === 'ESRCH') {
-        // Process already dead
-        removePid(projectDir, name);
-        success(`${bold(name)} already stopped`);
-        stopped++;
-      } else {
-        error(`Failed to stop ${bold(name)}: ${err.message}`);
-      }
-    }
-  }
-
-  console.log();
-  success(`${green(String(stopped))} agent(s) stopped`);
-  console.log();
-}
-
-// ─── Customize Workspace ────────────────────────────────────
-
-async function customizeWorkspace(projectDir) {
-  const rl = createInterface({ input: stdin, output: stdout });
-
-  console.log();
-  console.log(`  ${bold('Configure your project identity')}`);
-  console.log(`  ${dim('Answer a few questions so all agents understand your project.')}`);
-  console.log();
-
-  try {
-    const name = await askQuestion(rl, 'Project name', '(e.g., Acme API)');
-    const lang = await askQuestion(rl, 'Primary language', '(e.g., Python, TypeScript)');
-    const framework = await askQuestion(rl, 'Framework', '(e.g., FastAPI, Next.js, Django)');
-    const devCmd = await askQuestion(rl, 'Dev server command', '(e.g., make dev, npm run dev)');
-    const testCmd = await askQuestion(rl, 'Test command', '(e.g., make test, pytest, npm test)');
-    const conventions = await askQuestion(rl, 'Key conventions', '(brief, e.g., "services flush, routes commit")');
-
-    console.log();
-
-    const soulPath = join(projectDir, '.openclaw/SOUL.md');
-    let soul = readFileSync(soulPath, 'utf8');
-
-    const projectContext = [
-      `# ${name} — Persistent Development Agents`,
-      '',
-      `**Project:** ${name}`,
-      `**Language:** ${lang}`,
-      `**Framework:** ${framework}`,
-      `**Dev server:** \`${devCmd}\``,
-      `**Tests:** \`${testCmd}\``,
-      `**Conventions:** ${conventions}`,
-      '',
-      '---',
-      '',
-    ].join('\n');
-
-    const dashIndex = soul.indexOf('---');
-    if (dashIndex !== -1) {
-      soul = projectContext + soul.slice(dashIndex + 3).trimStart();
-    } else {
-      soul = projectContext + soul;
-    }
-
-    writeFileSync(soulPath, soul, 'utf8');
-    success(`Updated ${bold('.openclaw/SOUL.md')} with ${green(name)} project context`);
-
-    return true;
-  } finally {
-    rl.close();
-  }
-}
-
-// ─── Install OpenClaw ───────────────────────────────────────
-
-async function installOpenClaw() {
-  console.log();
-  warn('OpenClaw is not installed.');
-  console.log();
-  console.log(`  ${dim('OpenClaw is the persistent agent runtime. Each agent in')}`);
-  console.log(`  ${dim('.openclaw/agents/ runs as a separate OpenClaw process.')}`);
-  console.log();
-
-  const install = await confirm('Install OpenClaw now? (npm install -g openclaw@latest)');
-  if (!install) {
-    console.log();
-    info('Install manually when ready:');
-    console.log(`  ${dim('$')} ${bold('npm install -g openclaw@latest')}`);
-    console.log(`  ${dim('$')} ${bold('serpentstack skills persistent')}`);
-    console.log();
-    return false;
-  }
-
-  console.log();
-  info('Installing OpenClaw...');
-  await new Promise((resolve, reject) => {
-    const child = spawn('npm', ['install', '-g', 'openclaw@latest'], { stdio: 'inherit' });
-    child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`npm install exited with code ${code}`)));
-  });
-  console.log();
-  success('OpenClaw installed');
-  return true;
-}
-
-// ─── Start Agents ───────────────────────────────────────────
-
-function startAgent(projectDir, agentName, workspacePath) {
-  return new Promise((resolve, reject) => {
-    const child = spawn('openclaw', ['start', '--workspace', workspacePath], {
-      stdio: 'ignore',
-      detached: true,
-      cwd: projectDir,
-      env: {
-        ...process.env,
-        OPENCLAW_STATE_DIR: join(workspacePath, '.state'),
-      },
-    });
-
-    child.unref();
-
-    child.on('error', (err) => {
-      reject(new Error(`Failed to start ${agentName}: ${err.message}`));
-    });
-
-    // Give it a moment to start, then record PID
-    setTimeout(() => {
-      writePid(projectDir, agentName, child.pid);
-      resolve(child.pid);
-    }, 500);
-  });
-}
-
-// ─── Main Flow ──────────────────────────────────────────────
-
-export async function skillsPersistent({ stop = false } = {}) {
-  const projectDir = process.cwd();
-
-  // --stop flag
-  if (stop) {
-    printHeader();
-    await stopAllAgents(projectDir);
-    return;
-  }
-
-  // === Guided setup flow ===
-  printHeader();
-
-  // Step 1: Check workspace
-  console.log(`  ${bold('Step 1/4')} ${dim('\u2014 Check workspace')}`);
-  console.log();
-
-  const soulPath = join(projectDir, '.openclaw/SOUL.md');
-  if (!existsSync(soulPath)) {
-    error('No .openclaw/ workspace found.');
-    console.log();
-    console.log(`  Run ${bold('serpentstack skills init')} first to download the workspace files.`);
-    console.log();
-    process.exit(1);
-  }
-  success('.openclaw/SOUL.md found');
-
-  const agents = discoverAgents(projectDir);
-  if (agents.length === 0) {
-    error('No agents found in .openclaw/agents/');
-    console.log();
-    console.log(`  Run ${bold('serpentstack skills init')} to download the default agents,`);
-    console.log(`  or create your own at ${bold('.openclaw/agents/<name>/AGENT.md')}`);
-    console.log();
-    process.exit(1);
-  }
-  success(`${green(String(agents.length))} agent(s) found in .openclaw/agents/`);
-  console.log();
-
-  // Clean up any stale PIDs from previous runs
-  cleanStalePids(projectDir);
-
-  // Check if any agents are already running
-  const alreadyRunning = listPids(projectDir);
-  if (alreadyRunning.length > 0) {
-    warn(`${bold(String(alreadyRunning.length))} agent(s) already running`);
-    for (const { name, pid } of alreadyRunning) {
-      console.log(`  ${dim('\u2022')} ${bold(name)} ${dim(`(PID ${pid})`)}`);
-    }
-    console.log();
-    const restart = await confirm('Stop running agents and restart?');
-    if (restart) {
-      await stopAllAgents(projectDir);
-    } else {
-      console.log();
-      info('Keeping existing agents running.');
-      console.log();
-      return;
-    }
-  }
-
-  // Step 2: Configure project identity
-  console.log(`  ${bold('Step 2/4')} ${dim('\u2014 Configure project identity')}`);
-
-  const soulContent = readFileSync(soulPath, 'utf8');
-  const isCustomized = !soulContent.startsWith('# SerpentStack') && !soulContent.includes('{{PROJECT_NAME}}');
-
-  if (isCustomized) {
-    console.log();
-    success('SOUL.md already customized');
-    console.log();
-    const reconfigure = await confirm('Reconfigure? (will overwrite current settings)');
-    if (reconfigure) {
-      await customizeWorkspace(projectDir);
-    }
-    console.log();
-  } else {
-    await customizeWorkspace(projectDir);
-    console.log();
-  }
-
-  // Step 3: Select agents
-  console.log(`  ${bold('Step 3/4')} ${dim('\u2014 Review agents')}`);
-  console.log();
-
-  // Parse all agents and display them
-  const parsed = [];
-  for (const agent of agents) {
-    try {
-      const agentMd = parseAgentMd(agent.agentMdPath);
-      parsed.push({ ...agent, agentMd });
-
-      const model = agentMd.meta.model || 'default';
-      const modelShort = model.includes('haiku') ? 'Haiku' : model.includes('sonnet') ? 'Sonnet' : model.includes('opus') ? 'Opus' : model;
-      const schedule = (agentMd.meta.schedule || []).map(s => s.every).join(', ');
-
-      success(`${bold(agent.name)}  ${dim(agentMd.meta.description || '')}`);
-      console.log(`    ${dim(`Model: ${modelShort}`)}${schedule ? dim(` \u2022 Schedule: ${schedule}`) : ''}`);
-    } catch (err) {
-      error(`${bold(agent.name)}: ${err.message}`);
-    }
-  }
-
-  if (parsed.length === 0) {
-    console.log();
-    error('No valid agents found. Check your AGENT.md files.');
-    console.log();
-    process.exit(1);
-  }
-
-  console.log();
-  console.log(`  ${dim(`${parsed.length} agent(s) will be started. Delete an agent's folder to disable it.`)}`);
-  console.log();
-
-  // Step 4: Install + start
-  console.log(`  ${bold('Step 4/4')} ${dim('\u2014 Start agents')}`);
-
-  const hasOpenClaw = await which('openclaw');
-  if (!hasOpenClaw) {
-    const installed = await installOpenClaw();
-    if (!installed) return;
-  } else {
-    success('OpenClaw is installed');
-  }
-
-  const shouldStart = await confirm(`Start ${parsed.length} agent(s) now?`);
-  if (!shouldStart) {
-    console.log();
-    printBox('Start later', [
-      `${dim('$')} ${bold('serpentstack skills persistent')}         ${dim('# run setup again')}`,
-      `${dim('$')} ${bold('serpentstack skills persistent --stop')}  ${dim('# stop all agents')}`,
-    ]);
-    return;
-  }
-
-  console.log();
-
-  // Read shared SOUL.md
-  const sharedSoul = readFileSync(soulPath, 'utf8');
-  let started = 0;
-
-  for (const { name, agentMd } of parsed) {
-    try {
-      const workspacePath = generateWorkspace(projectDir, name, agentMd, sharedSoul);
-      const pid = await startAgent(projectDir, name, workspacePath);
-
-      const model = agentMd.meta.model || 'default';
-      const modelShort = model.includes('haiku') ? 'Haiku' : model.includes('sonnet') ? 'Sonnet' : model.includes('opus') ? 'Opus' : model;
-      const schedule = (agentMd.meta.schedule || []).map(s => s.every).join(', ');
-
-      success(`${bold(name)} started ${dim(`(${modelShort}, ${schedule || 'no schedule'}) PID ${pid}`)}`);
-      started++;
-    } catch (err) {
-      error(`${bold(name)}: ${err.message}`);
-    }
-  }
-
-  console.log();
-  if (started > 0) {
-    success(`${green(String(started))} agent(s) running`);
-    console.log();
-    printBox('Manage your agents', [
-      `${dim('$')} ${bold('serpentstack skills persistent --stop')}  ${dim('# stop all agents')}`,
-      `${dim('$')} ${bold('serpentstack skills persistent')}         ${dim('# restart / reconfigure')}`,
-      '',
-      `${dim('Add agents:')}   ${dim('Create .openclaw/agents/<name>/AGENT.md')}`,
-      `${dim('Remove agents:')} ${dim('Delete the agent folder from .openclaw/agents/')}`,
-      `${dim('Customize:')}     ${dim('Edit AGENT.md frontmatter (model, schedule, tools)')}`,
-    ]);
-  } else {
-    error('No agents were started. Check the errors above.');
-    console.log();
-  }
-}