valent-pipeline 0.1.0

package/bin/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('valent-pipeline')
+  .description('v3 multi-agent AI pipeline for software development lifecycle')
+  .version(pkg.version);
+
+// init command
+program
+  .command('init')
+  .description('Initialize a new v3 pipeline in the current project')
+  .option('--yes', 'Use defaults for all prompts (non-interactive)')
+  .option('--force', 'Overwrite existing pipeline configuration')
+  .action(async (options) => {
+    const { init } = await import('../src/commands/init.js');
+    await init(options);
+  });
+
+// upgrade command
+program
+  .command('upgrade')
+  .description('Upgrade pipeline infrastructure files to the latest version')
+  .option('--dry-run', 'Show what would change without writing')
+  .option('--force', 'Force upgrade even on major version bumps')
+  .action(async (options) => {
+    const { upgrade } = await import('../src/commands/upgrade.js');
+    await upgrade(options);
+  });
+
+// config validate command
+const configCmd = program
+  .command('config')
+  .description('Pipeline configuration commands');
+
+configCmd
+  .command('validate')
+  .description('Validate pipeline-config.yaml against the schema')
+  .action(async () => {
+    const { validate } = await import('../src/commands/validate.js');
+    await validate();
+  });
+
+// db commands
+const dbCmd = program
+  .command('db')
+  .description('Knowledge database commands');
+
+dbCmd
+  .command('init')
+  .description('Initialize the SQLite knowledge database')
+  .action(async () => {
+    const { dbInit } = await import('../src/commands/db-init.js');
+    await dbInit();
+  });
+
+dbCmd
+  .command('rebuild')
+  .description('Rebuild the knowledge database from story artifacts')
+  .action(async () => {
+    const { dbRebuild } = await import('../src/commands/db-rebuild.js');
+    await dbRebuild();
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "valent-pipeline",
+  "version": "0.1.0",
+  "description": "v3 multi-agent AI pipeline for software development lifecycle",
+  "type": "module",
+  "bin": {
+    "valent-pipeline": "./bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "pipeline/",
+    "skills/"
+  ],
+  "scripts": {
+    "test": "node scripts/test-local.js",
+    "prepublishOnly": "node scripts/test-local.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "inquirer": "^9.0.0",
+    "better-sqlite3": "^11.0.0",
+    "sqlite-vec": "^0.1.0"
+  },
+  "keywords": [
+    "ai",
+    "pipeline",
+    "multi-agent",
+    "sdlc",
+    "claude"
+  ],
+  "license": "MIT"
+}

package/skills/v3-debug-export/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: v3-debug-export
+description: 'Export pipeline diagnostic context for debugging in another session. Use when the user says "debug export", "export context", or "v3 debug"'
+---
+
+# v3 Debug Export
+
+Generate a concise diagnostic dump of the current pipeline state. The user will paste this into another Claude session for debugging assistance.
+
+## Output Format
+
+Print the following to the conversation as a single fenced code block (```yaml). Do NOT write to a file.
+
+```yaml
+v3_debug_export:
+  timestamp: {ISO-8601}
+  cwd: {current working directory}
+
+  install:
+    valent_version: {contents of v3/.valent-version, or "MISSING"}
+    config_exists: {true/false}
+    manifest_exists: {true/false for v3/agents-manifest.yaml}
+    skills_installed: {list which v3-* skills exist under .claude/skills/}
+    knowledge_mode: {from pipeline-config.yaml, or "NO CONFIG"}
+    db_exists: {true/false for v3/pipeline.db}
+    project_type: {from pipeline-config.yaml}
+
+  files:
+    prompts: {count of .md files in v3/prompts/}
+    step_dirs: {list of directories in v3/steps/}
+    step_files: {total count of .md files across v3/steps/}
+    task_graphs: {list of .yaml files in v3/task-graphs/}
+    templates: {count of .md files in v3/templates/}
+    spawn_templates: {count of .md files in v3/spawn-templates/}
+
+  config_summary:
+    tech_stack: {language, backend_framework, frontend_framework from config}
+    models: {opus, sonnet, haiku agent lists from config}
+    quality: {max_rejection_cycles, retrospective_every_n_stories}
+    knowledge: {mode, sqlite_db_path or chromadb_host}
+
+  backlog:
+    exists: {true/false}
+    total_items: {count}
+    pending: {count}
+    shipped: {count}
+
+  pipeline_state:
+    exists: {true/false for pipeline-state.json}
+    current_story: {id and status if exists, or "none"}
+    stories_since_retro: {count}
+
+  git:
+    branch: {current branch}
+    clean: {true/false}
+    recent_commits: {last 3 one-line commits}
+
+  errors: {list any missing expected files, parse errors, or anomalies found during export}
+```
+
+## How to Generate
+
+1. Read `v3/.valent-version`
+2. Read `v3/pipeline-config.yaml` — parse key fields
+3. Count/list files in v3/prompts/, v3/steps/, v3/task-graphs/, v3/templates/, v3/spawn-templates/
+4. Read `pipeline-backlog.yaml` — count items by status
+5. Read `pipeline-state.json` — extract current story
+6. Check `.claude/skills/` for v3-* directories
+7. Check if `v3/pipeline.db` exists
+8. Run `git branch --show-current` and `git status --short` and `git log --oneline -3`
+9. Collect any missing files or parse errors into the `errors` list
+
+## Rules
+
+- Output ONLY the YAML block. No preamble, no explanation, no suggestions.
+- Keep it under 80 lines. This is a paste target, not a report.
+- If a file is missing, note it in `errors` — don't fail.
+- If config can't be parsed, set fields to "PARSE_ERROR" and add to errors.

package/skills/v3-help/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: v3-help
+description: 'Answer questions about the v3 pipeline — how it works, how to use it, agent roles, configuration, troubleshooting. Use when the user says "v3 help", "how does the pipeline work", "explain v3", or asks any question about the pipeline.'
+---
+
+# v3 Pipeline Help
+
+You are a helpful guide for the v3 multi-agent pipeline. Answer the user's question by reading the pipeline documentation and configuration.
+
+## How to Answer
+
+1. Read the user's question
+2. Search the relevant docs and config files below for the answer
+3. Give a clear, concise answer with file references so they can dig deeper
+4. If the question is about their specific setup, read their `v3/pipeline-config.yaml`
+
+## Documentation Sources
+
+Read these as needed to answer questions:
+
+| Topic | File |
+|---|---|
+| Pipeline overview, agent roles, execution flow | `v3/docs/pipeline-overview.md` |
+| Agent reference (all agents, models, inputs/outputs) | `v3/docs/agent-reference.md` |
+| Lead lifecycle (kick-off, monitoring, ship/teardown) | `v3/docs/lead-lifecycle.md` |
+| Task graphs and dependency flow | `v3/docs/task-graph.md` |
+| Communication protocol (inbox, message types) | `v3/docs/communication-standard.md` |
+| Knowledge system (curated files, SQLite, ChromaDB) | `v3/docs/knowledge-system.md` |
+| Pipeline state and crash recovery | `v3/docs/pipeline-state-schema.md` |
+| NPX package and installation | `v3/docs/npx-packaging.md` |
+| Template skeleton for handoff docs | `v3/docs/template-skeleton.md` |
+| Agent manifest (definitions, model tiers) | `v3/agents-manifest.yaml` |
+| Project configuration | `v3/pipeline-config.yaml` |
+
+## Common Questions — Quick Answers
+
+**"How do I run a story?"**
+→ `/v3-run-story STORY-ID` or just `/v3-run-story` to auto-pick the next from the backlog.
+
+**"How do I run an epic?"**
+→ `/v3-run-epic EPIC-ID` — runs all stories tagged with that epic sequentially.
+
+**"How do I configure the pipeline?"**
+→ `/v3-configure` for interactive wizard, or edit `v3/pipeline-config.yaml` directly.
+
+**"How do I add a story to the backlog?"**
+→ Add an entry to `pipeline-backlog.yaml` with id, type: story, status: pending, priority, and epic field.
+
+**"What agents run and in what order?"**
+→ REQS → UXA → QA-A → JUDGE-G1 Pass 1 → BEND + FEND (parallel) → CRITIC → QA-B → JUDGE-G1 Pass 2 → JUDGE-G2. Agents are filtered by project type and testing profiles. See `v3/docs/agent-reference.md`.
+
+**"How do agents communicate?"**
+→ Peer-to-peer via inbox. Terse messages: `[HANDOFF]`, `[BLOCKER]`, `[KNOWLEDGE-QUERY]`, etc. Lead monitors but doesn't relay. See `v3/docs/communication-standard.md`.
+
+**"What does each agent do?"**
+→ Read `v3/docs/agent-reference.md` for the full roster, or check individual prompts in `v3/prompts/`.
+
+**"How does the knowledge system work?"**
+→ Knowledge agent answers `[KNOWLEDGE-QUERY]` messages by searching correction directives, curated files, and the SQLite database (if configured). See `v3/docs/knowledge-system.md`.
+
+**"How do I change which model an agent uses?"**
+→ Edit the `models` section in `v3/pipeline-config.yaml`. Agents are assigned to opus/sonnet/haiku tiers.
+
+**"What happens when an agent gets rejected?"**
+→ Peer-to-peer: JUDGE-G1 rejects specs back to authors, CRITIC rejects code to devs, QA-B routes bugs to devs. Lead only handles G2 rejections and circuit breaker (after max_rejection_cycles). See `v3/docs/lead-lifecycle.md`.
+
+**"How do correction directives work?"**
+→ The Retrospective Agent (every N stories) analyzes patterns and writes directives to `knowledge/correction-directives.yaml`. These are loaded at the next story's kick-off and passed to all agents. See `v3/docs/knowledge-system.md`.
+
+**"How do I upgrade the pipeline?"**
+→ `npx valent-pipeline upgrade` — replaces infrastructure files, never touches your config or knowledge files.
+
+**"How do I initialize the SQLite database?"**
+→ `npx valent-pipeline db init` to create it, `npx valent-pipeline db rebuild` to re-index from existing story artifacts.
+
+## Answer Format
+
+Keep answers short and actionable. Reference specific files so the user can read more. Example:
+
+> Stories execute in this order: REQS → UXA → QA-A → JUDGE-G1 → BEND/FEND → CRITIC → QA-B → JUDGE-G2. Agents spawn in 4 waves to avoid idle token waste. Your project type (`fullstack-web`) runs all agents. See `v3/docs/agent-reference.md` for details on each agent's role.
+
+If you don't know the answer, say so and point them to the most relevant doc file to search manually.

package/src/commands/db-init.js

@@ -0,0 +1,107 @@
+import { join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+export async function dbInit() {
+  const projectRoot = process.cwd();
+  const configPath = join(projectRoot, 'v3', 'pipeline-config.yaml');
+
+  if (!existsSync(configPath)) {
+    console.error('Error: v3/pipeline-config.yaml not found. Run "valent-pipeline init" first.');
+    process.exit(1);
+  }
+
+  // Read db path from config (simple extraction)
+  const content = readFileSync(configPath, 'utf-8');
+  const dbPathMatch = content.match(/sqlite_db_path:\s*"?([^"\n]+)"?/);
+  const dbPath = dbPathMatch ? dbPathMatch[1].trim() : './v3/pipeline.db';
+  const fullDbPath = join(projectRoot, dbPath);
+
+  let Database;
+  let sqliteVec;
+  try {
+    Database = (await import('better-sqlite3')).default;
+    sqliteVec = await import('sqlite-vec');
+  } catch (err) {
+    console.error('Error: better-sqlite3 or sqlite-vec not installed.');
+    console.error('Run: npm install better-sqlite3 sqlite-vec');
+    process.exit(1);
+  }
+
+  const db = new Database(fullDbPath);
+
+  // Load sqlite-vec extension
+  try {
+    sqliteVec.load(db);
+    console.log('Loaded sqlite-vec extension');
+  } catch (err) {
+    console.warn(`Warning: Could not load sqlite-vec: ${err.message}`);
+    console.warn('Vector search will not be available. FTS5 will still work.');
+  }
+
+  // Create tables
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS artifacts (
+      id TEXT PRIMARY KEY,
+      story_id TEXT NOT NULL,
+      agent TEXT NOT NULL,
+      artifact_type TEXT NOT NULL,
+      content TEXT NOT NULL,
+      metadata TEXT,
+      created_at TEXT DEFAULT (datetime('now')),
+      UNIQUE(story_id, artifact_type)
+    );
+
+    CREATE TABLE IF NOT EXISTS correction_directives (
+      id TEXT PRIMARY KEY,
+      target_agent TEXT NOT NULL,
+      directive TEXT NOT NULL,
+      reason TEXT,
+      status TEXT DEFAULT 'active',
+      created_batch INTEGER,
+      metadata TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_artifacts_story ON artifacts(story_id);
+    CREATE INDEX IF NOT EXISTS idx_artifacts_type ON artifacts(artifact_type);
+    CREATE INDEX IF NOT EXISTS idx_artifacts_agent ON artifacts(agent);
+    CREATE INDEX IF NOT EXISTS idx_cd_target ON correction_directives(target_agent);
+    CREATE INDEX IF NOT EXISTS idx_cd_status ON correction_directives(status);
+  `);
+
+  // Create FTS5 virtual table
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS artifacts_fts USING fts5(
+      content,
+      story_id UNINDEXED,
+      agent UNINDEXED,
+      artifact_type UNINDEXED,
+      content=artifacts,
+      content_rowid=rowid
+    );
+  `);
+
+  // Create FTS triggers for auto-sync
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS artifacts_ai AFTER INSERT ON artifacts BEGIN
+      INSERT INTO artifacts_fts(rowid, content, story_id, agent, artifact_type)
+      VALUES (new.rowid, new.content, new.story_id, new.agent, new.artifact_type);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS artifacts_ad AFTER DELETE ON artifacts BEGIN
+      INSERT INTO artifacts_fts(artifacts_fts, rowid, content, story_id, agent, artifact_type)
+      VALUES ('delete', old.rowid, old.content, old.story_id, old.agent, old.artifact_type);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS artifacts_au AFTER UPDATE ON artifacts BEGIN
+      INSERT INTO artifacts_fts(artifacts_fts, rowid, content, story_id, agent, artifact_type)
+      VALUES ('delete', old.rowid, old.content, old.story_id, old.agent, old.artifact_type);
+      INSERT INTO artifacts_fts(rowid, content, story_id, agent, artifact_type)
+      VALUES (new.rowid, new.content, new.story_id, new.agent, new.artifact_type);
+    END;
+  `);
+
+  console.log(`Database initialized at ${fullDbPath}`);
+  console.log('Tables: artifacts, artifacts_fts, correction_directives');
+
+  db.close();
+}

package/src/commands/db-rebuild.js

@@ -0,0 +1,124 @@
+import { join } from 'path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+
+// Artifact files we index (filename -> artifact_type mapping)
+const ARTIFACT_MAP = {
+  'reqs-brief.md': { type: 'reqs-brief', agent: 'REQS' },
+  'uxa-spec.md': { type: 'uxa-spec', agent: 'UXA' },
+  'qa-test-spec.md': { type: 'qa-test-spec', agent: 'QA-A' },
+  'bend-handoff.md': { type: 'bend-handoff', agent: 'BEND' },
+  'fend-handoff.md': { type: 'fend-handoff', agent: 'FEND' },
+  'critic-review.md': { type: 'critic-review', agent: 'CRITIC' },
+  'execution-report.md': { type: 'execution-report', agent: 'QA-B' },
+  'bugs.md': { type: 'bugs', agent: 'QA-B' },
+  'traceability-matrix.md': { type: 'traceability-matrix', agent: 'QA-B' },
+  'judge-g1-review.md': { type: 'judge-g1-review', agent: 'JUDGE-G1' },
+  'judge-g2-decision.md': { type: 'judge-g2-decision', agent: 'JUDGE-G2' },
+  'story-report.md': { type: 'story-report', agent: 'JUDGE-G2' },
+  'pmcp-evidence.md': { type: 'pmcp-evidence', agent: 'PMCP' },
+  'visual-validation-checklist.md': { type: 'visual-validation-checklist', agent: 'QA-A' },
+};
+
+export async function dbRebuild() {
+  const projectRoot = process.cwd();
+  const configPath = join(projectRoot, 'v3', 'pipeline-config.yaml');
+
+  if (!existsSync(configPath)) {
+    console.error('Error: v3/pipeline-config.yaml not found. Run "valent-pipeline init" first.');
+    process.exit(1);
+  }
+
+  // Read db path from config
+  const content = readFileSync(configPath, 'utf-8');
+  const dbPathMatch = content.match(/sqlite_db_path:\s*"?([^"\n]+)"?/);
+  const dbPath = dbPathMatch ? dbPathMatch[1].trim() : './v3/pipeline.db';
+  const fullDbPath = join(projectRoot, dbPath);
+
+  if (!existsSync(fullDbPath)) {
+    console.error('Error: Database not found. Run "valent-pipeline db init" first.');
+    process.exit(1);
+  }
+
+  let Database;
+  try {
+    Database = (await import('better-sqlite3')).default;
+  } catch (err) {
+    console.error('Error: better-sqlite3 not installed. Run: npm install better-sqlite3');
+    process.exit(1);
+  }
+
+  const db = new Database(fullDbPath);
+
+  // Find stories directory
+  const storyDirMatch = content.match(/story_directory:\s*"?([^"\n]+)"?/);
+  const storyDir = storyDirMatch ? storyDirMatch[1].trim() : './stories';
+  const fullStoryDir = join(projectRoot, storyDir);
+
+  if (!existsSync(fullStoryDir)) {
+    console.log('No stories directory found. Nothing to rebuild.');
+    db.close();
+    return;
+  }
+
+  // Scan for story directories
+  const storyDirs = readdirSync(fullStoryDir).filter(name => {
+    const storyPath = join(fullStoryDir, name);
+    return statSync(storyPath).isDirectory();
+  });
+
+  console.log(`Found ${storyDirs.length} story directories`);
+
+  // Prepare insert statement
+  const insert = db.prepare(`
+    INSERT OR REPLACE INTO artifacts (id, story_id, agent, artifact_type, content, metadata)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `);
+
+  let indexedCount = 0;
+
+  const insertMany = db.transaction((items) => {
+    for (const item of items) {
+      insert.run(item.id, item.storyId, item.agent, item.type, item.content, item.metadata);
+      indexedCount++;
+    }
+  });
+
+  const allItems = [];
+
+  for (const storyName of storyDirs) {
+    const outputDir = join(fullStoryDir, storyName, 'output');
+    if (!existsSync(outputDir)) continue;
+
+    const storyId = storyName.toUpperCase();
+
+    for (const [filename, info] of Object.entries(ARTIFACT_MAP)) {
+      const filePath = join(outputDir, filename);
+      if (!existsSync(filePath)) continue;
+
+      const fileContent = readFileSync(filePath, 'utf-8');
+      // Skip pass-through/skipped files
+      if (fileContent.includes('status: skipped')) continue;
+
+      allItems.push({
+        id: `${storyId}:${info.type}`,
+        storyId,
+        agent: info.agent,
+        type: info.type,
+        content: fileContent,
+        metadata: JSON.stringify({ source: 'rebuild', file: filePath }),
+      });
+    }
+  }
+
+  insertMany(allItems);
+  console.log(`Indexed ${indexedCount} artifacts from ${storyDirs.length} stories`);
+
+  // Rebuild correction directives
+  const cdPath = join(projectRoot, 'knowledge', 'correction-directives.yaml');
+  if (existsSync(cdPath)) {
+    console.log('Note: Correction directives should be re-indexed separately via the Retrospective Agent.');
+  }
+
+  db.close();
+  console.log('Rebuild complete.');
+}

package/src/commands/init.js

@@ -0,0 +1,227 @@
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { defaults } from '../lib/config-schema.js';
+import { copyDir, writeFileSafe, appendToGitignore, fileExists } from '../lib/file-ops.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+export async function init(options = {}) {
+  const projectRoot = process.cwd();
+  const configPath = join(projectRoot, 'v3', 'pipeline-config.yaml');
+
+  // Guard: warn if config already exists
+  if (fileExists(configPath) && !options.force) {
+    console.error('Error: v3/pipeline-config.yaml already exists.');
+    console.error('Use --force to overwrite, or run "valent-pipeline config validate" to check the existing config.');
+    process.exit(1);
+  }
+
+  let config;
+  if (options.yes) {
+    config = { ...defaults };
+    console.log('Using default configuration (--yes flag).');
+  } else {
+    config = await runWizard();
+  }
+
+  console.log('\nInitializing v3 pipeline...\n');
+
+  // 1. Copy pipeline infrastructure
+  const pipelineSrc = join(PACKAGE_ROOT, 'pipeline');
+  const pipelineDest = join(projectRoot, 'v3');
+  if (existsSync(pipelineSrc)) {
+    copyDir(pipelineSrc, pipelineDest);
+    console.log('  Copied pipeline infrastructure to v3/');
+  } else {
+    console.warn('  Warning: pipeline/ directory not found in package. Skipping infrastructure copy.');
+  }
+
+  // 2. Generate pipeline-config.yaml
+  const configContent = generateConfigYaml(config);
+  writeFileSafe(configPath, configContent);
+  console.log('  Generated v3/pipeline-config.yaml');
+
+  // 3. Initialize backlog
+  const backlogPath = join(projectRoot, config.project?.backlog_path || 'pipeline-backlog.yaml');
+  if (!fileExists(backlogPath)) {
+    writeFileSafe(backlogPath, `# Pipeline Backlog\n# Add stories and bugs here. See v3/docs/pipeline-overview.md for format.\n\nitems: []\n`);
+    console.log('  Created pipeline-backlog.yaml');
+  }
+
+  // 4. Install skills
+  const skillsSrc = join(PACKAGE_ROOT, 'skills');
+  const skillsDest = join(projectRoot, '.claude', 'skills');
+  if (existsSync(skillsSrc)) {
+    copyDir(skillsSrc, skillsDest);
+    console.log('  Installed skills to .claude/skills/');
+  }
+
+  // 5. Create knowledge directories
+  const curatedPath = join(projectRoot, 'knowledge', 'curated');
+  if (!existsSync(curatedPath)) {
+    writeFileSafe(join(curatedPath, 'README.md'),
+      '# Curated Knowledge Files\n\nAdd project-specific knowledge files here. These are indexed by the Knowledge Agent at story startup.\n\nExamples:\n- `api-reference.md` — API endpoint specifications\n- `code-conventions.md` — language and framework conventions\n- `project-context.md` — project identity and architecture\n');
+    console.log('  Created knowledge/curated/ with README');
+  }
+
+  // 6. Create correction directives
+  const cdPath = join(projectRoot, 'knowledge', 'correction-directives.yaml');
+  if (!fileExists(cdPath)) {
+    writeFileSafe(cdPath, '# Correction Directives\n# Populated by the Retrospective Agent after batch analysis.\n\ndirectives: []\n');
+    console.log('  Created knowledge/correction-directives.yaml');
+  }
+
+  // 7. Initialize SQLite DB if sqlite mode
+  if (config.knowledge?.mode === 'sqlite') {
+    console.log('  SQLite knowledge mode selected. Run "valent-pipeline db init" to create the database.');
+  }
+
+  // 8. Update .gitignore
+  appendToGitignore(projectRoot, 'v3/pipeline.db');
+  appendToGitignore(projectRoot, 'v3/pipeline.db-*');
+  appendToGitignore(projectRoot, 'v3/chromadb-data/');
+  console.log('  Updated .gitignore');
+
+  // 9. Write version file
+  const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
+  writeFileSafe(join(projectRoot, 'v3', '.valent-version'), pkg.version);
+  console.log(`  Wrote v3/.valent-version (${pkg.version})`);
+
+  console.log('\nPipeline initialized. Run /v3-run-story to execute your first story.\n');
+}
+
+async function runWizard() {
+  const inquirer = (await import('inquirer')).default;
+  const config = JSON.parse(JSON.stringify(defaults));
+
+  console.log('\n  valent-pipeline init\n');
+
+  // Project type
+  const { projectType } = await inquirer.prompt([{
+    type: 'list',
+    name: 'projectType',
+    message: 'Project type:',
+    choices: [
+      'fullstack-web', 'backend-api', 'frontend-only',
+      'data-pipeline', 'mcp-server', 'document-generation', 'library'
+    ],
+    default: 'fullstack-web',
+  }]);
+  config.project.type = projectType;
+
+  // Tech stack
+  const { language } = await inquirer.prompt([{
+    type: 'input', name: 'language', message: 'Language:', default: 'TypeScript',
+  }]);
+  config.tech_stack.language = language;
+
+  const { backendFramework } = await inquirer.prompt([{
+    type: 'input', name: 'backendFramework', message: 'Backend framework:', default: 'Express',
+  }]);
+  config.tech_stack.backend_framework = backendFramework;
+
+  if (!['backend-api', 'data-pipeline', 'mcp-server', 'library'].includes(projectType)) {
+    const { frontendFramework } = await inquirer.prompt([{
+      type: 'input', name: 'frontendFramework', message: 'Frontend framework:', default: 'React',
+    }]);
+    config.tech_stack.frontend_framework = frontendFramework;
+  } else {
+    config.tech_stack.frontend_framework = 'none';
+  }
+
+  const { databaseOrm } = await inquirer.prompt([{
+    type: 'input', name: 'databaseOrm', message: 'Database/ORM:', default: 'Prisma',
+  }]);
+  config.tech_stack.database_orm = databaseOrm;
+
+  const { testUnit } = await inquirer.prompt([{
+    type: 'input', name: 'testUnit', message: 'Unit test framework:', default: 'Vitest',
+  }]);
+  config.tech_stack.test_framework_unit = testUnit;
+
+  const { testE2e } = await inquirer.prompt([{
+    type: 'input', name: 'testE2e', message: 'E2E test framework:', default: 'Playwright',
+  }]);
+  config.tech_stack.test_framework_e2e = testE2e;
+
+  // Knowledge mode
+  const { knowledgeMode } = await inquirer.prompt([{
+    type: 'list',
+    name: 'knowledgeMode',
+    message: 'Knowledge store:',
+    choices: [
+      { name: 'SQLite (recommended — local, zero infrastructure)', value: 'sqlite' },
+      { name: 'None (curated files only)', value: 'none' },
+      { name: 'ChromaDB (local Docker)', value: 'local-docker' },
+      { name: 'ChromaDB (connect to existing)', value: 'connect-to-existing' },
+    ],
+    default: 'sqlite',
+  }]);
+  config.knowledge.mode = knowledgeMode;
+
+  if (knowledgeMode === 'local-docker' || knowledgeMode === 'connect-to-existing') {
+    const { chromadbHost } = await inquirer.prompt([{
+      type: 'input', name: 'chromadbHost', message: 'ChromaDB host:', default: 'http://localhost:8000',
+    }]);
+    config.knowledge.chromadb_host = chromadbHost;
+  }
+
+  return config;
+}
+
+function generateConfigYaml(config) {
+  return `# v3 Pipeline Configuration
+# Generated by: npx valent-pipeline init
+# To regenerate with the interactive wizard: npx valent-pipeline init --force
+# To validate this file: npx valent-pipeline config validate
+
+project:
+  type: "${config.project.type}"
+  root: "${config.project.root}"
+  story_directory: "${config.project.story_directory}"
+  story_output_directory: "${config.project.story_output_directory}"
+  backlog_path: "${config.project.backlog_path}"
+
+tech_stack:
+  language: "${config.tech_stack.language}"
+  backend_framework: "${config.tech_stack.backend_framework}"
+  frontend_framework: "${config.tech_stack.frontend_framework}"
+  database_orm: "${config.tech_stack.database_orm}"
+  test_framework_unit: "${config.tech_stack.test_framework_unit}"
+  test_framework_e2e: "${config.tech_stack.test_framework_e2e}"
+  browser_automation_mcp: "${config.tech_stack.browser_automation_mcp || 'playwright-mcp'}"
+  state_management: "${config.tech_stack.state_management || 'React Context'}"
+
+models:
+  opus: [${(config.models.opus || defaults.models.opus).map(a => `"${a}"`).join(', ')}]
+  sonnet: [${(config.models.sonnet || defaults.models.sonnet).map(a => `"${a}"`).join(', ')}]
+  haiku: [${(config.models.haiku || defaults.models.haiku).map(a => `"${a}"`).join(', ')}]
+
+quality:
+  max_rejection_cycles: ${config.quality.max_rejection_cycles}
+  retrospective_every_n_stories: ${config.quality.retrospective_every_n_stories}
+  stall_threshold_minutes: ${config.quality.stall_threshold_minutes}
+
+git:
+  target_branch: "${config.git.target_branch}"
+  story_branch_prefix: "${config.git.story_branch_prefix}"
+
+communication:
+  handoff_format: "${config.communication.handoff_format}"
+  inbox_message_max_tokens: ${config.communication.inbox_message_max_tokens}
+
+knowledge:
+  mode: "${config.knowledge.mode}"
+${config.knowledge.mode === 'sqlite' ? `  sqlite_db_path: "${config.knowledge.sqlite_db_path}"` : ''}${config.knowledge.chromadb_host ? `  chromadb_host: "${config.knowledge.chromadb_host}"
+  chromadb_collection_prefix: "${config.knowledge.chromadb_collection_prefix || 'v3-'}"` : ''}
+  curated_files_path: "${config.knowledge.curated_files_path}"
+  correction_directives_path: "${config.knowledge.correction_directives_path}"
+
+orchestration:
+  recommended_context_window: "${config.orchestration?.recommended_context_window || '200k'}"
+  epic_progress_path: "${config.orchestration?.epic_progress_path || './epic-progress.md'}"
+`;
+}

package/src/commands/upgrade.js

@@ -0,0 +1,129 @@
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, copyFileSync } from 'fs';
+import { copyDir, writeFileSafe, fileExists, readFile } from '../lib/file-ops.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+// Files that are NEVER overwritten during upgrade (project-specific)
+const PROTECTED_FILES = [
+  'pipeline-config.yaml',
+  'knowledge/curated',
+  'knowledge/correction-directives.yaml',
+];
+
+export async function upgrade(options = {}) {
+  const projectRoot = process.cwd();
+  const versionFile = join(projectRoot, 'v3', '.valent-version');
+
+  if (!fileExists(versionFile)) {
+    console.error('Error: v3/.valent-version not found. Run "valent-pipeline init" first.');
+    process.exit(1);
+  }
+
+  const installedVersion = readFile(versionFile).trim();
+  const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
+  const packageVersion = pkg.version;
+
+  console.log(`Installed version: ${installedVersion}`);
+  console.log(`Package version:   ${packageVersion}`);
+
+  if (installedVersion === packageVersion) {
+    console.log('\nAlready up to date.');
+    return;
+  }
+
+  // Check for major version bump
+  const installedMajor = parseInt(installedVersion.split('.')[0], 10);
+  const packageMajor = parseInt(packageVersion.split('.')[0], 10);
+  if (packageMajor > installedMajor && !options.force) {
+    console.error(`\nMajor version upgrade (${installedMajor} -> ${packageMajor}) requires --force flag.`);
+    console.error('Review migration notes at https://github.com/valent/valent-pipeline/releases');
+    process.exit(1);
+  }
+
+  const pipelineSrc = join(PACKAGE_ROOT, 'pipeline');
+  const pipelineDest = join(projectRoot, 'v3');
+  const skillsSrc = join(PACKAGE_ROOT, 'skills');
+  const skillsDest = join(projectRoot, '.claude', 'skills');
+
+  if (options.dryRun) {
+    console.log('\n--- Dry run: files that would be updated ---\n');
+    if (existsSync(pipelineSrc)) {
+      listChanges(pipelineSrc, pipelineDest, 'v3/');
+    }
+    if (existsSync(skillsSrc)) {
+      listChanges(skillsSrc, skillsDest, '.claude/skills/');
+    }
+    console.log('\n--- End dry run ---');
+    return;
+  }
+
+  // Copy infrastructure files (skip protected)
+  if (existsSync(pipelineSrc)) {
+    copyDirFiltered(pipelineSrc, pipelineDest, PROTECTED_FILES);
+    console.log('\nUpdated pipeline infrastructure in v3/');
+  }
+
+  // Copy skills
+  if (existsSync(skillsSrc)) {
+    copyDir(skillsSrc, skillsDest);
+    console.log('Updated skills in .claude/skills/');
+  }
+
+  // Update version file
+  writeFileSafe(versionFile, packageVersion);
+  console.log(`Updated v3/.valent-version to ${packageVersion}`);
+
+  console.log('\nUpgrade complete.');
+}
+
+function copyDirFiltered(src, dest, protectedPaths) {
+  const entries = readdirSync(src);
+  for (const entry of entries) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    const relativePath = entry;
+
+    // Skip protected files/dirs
+    if (protectedPaths.some(p => relativePath.startsWith(p))) {
+      continue;
+    }
+
+    const stat = statSync(srcPath);
+    if (stat.isDirectory()) {
+      copyDirFiltered(srcPath, destPath, protectedPaths.map(p => {
+        if (p.startsWith(entry + '/')) return p.slice(entry.length + 1);
+        return p;
+      }).filter(p => p.length > 0));
+    } else {
+      mkdirSync(dirname(destPath), { recursive: true });
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function listChanges(src, dest, prefix) {
+  const entries = readdirSync(src);
+  for (const entry of entries) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      listChanges(srcPath, destPath, prefix + entry + '/');
+    } else {
+      if (!existsSync(destPath)) {
+        console.log(`  + ${prefix}${entry} (new)`);
+      } else {
+        const srcContent = readFileSync(srcPath, 'utf-8');
+        const destContent = readFileSync(destPath, 'utf-8');
+        if (srcContent !== destContent) {
+          console.log(`  ~ ${prefix}${entry} (modified)`);
+        }
+      }
+    }
+  }
+}

package/src/commands/validate.js

@@ -0,0 +1,92 @@
+import { join } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { validateConfig } from '../lib/config-schema.js';
+
+export async function validate() {
+  const projectRoot = process.cwd();
+  const configPath = join(projectRoot, 'v3', 'pipeline-config.yaml');
+
+  if (!existsSync(configPath)) {
+    console.error('Error: v3/pipeline-config.yaml not found.');
+    console.error('Run "valent-pipeline init" to create one.');
+    process.exit(1);
+  }
+
+  // Simple YAML parser (avoids adding yaml dependency)
+  const content = readFileSync(configPath, 'utf-8');
+  let config;
+  try {
+    config = parseSimpleYaml(content);
+  } catch (err) {
+    console.error(`Error parsing v3/pipeline-config.yaml: ${err.message}`);
+    process.exit(1);
+  }
+
+  const result = validateConfig(config);
+
+  if (result.valid) {
+    console.log('v3/pipeline-config.yaml is valid.');
+    process.exit(0);
+  } else {
+    console.error('Validation errors:');
+    for (const error of result.errors) {
+      console.error(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Minimal YAML parser for pipeline-config.yaml.
+ * Handles the specific structure we generate (flat sections with string/number/array values).
+ * For complex YAML, users should install yaml package.
+ */
+function parseSimpleYaml(content) {
+  const result = {};
+  let currentSection = null;
+
+  for (const line of content.split('\n')) {
+    // Skip comments and empty lines
+    if (line.trim().startsWith('#') || line.trim() === '') continue;
+
+    // Top-level section (no indentation)
+    const sectionMatch = line.match(/^(\w+):\s*$/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1];
+      result[currentSection] = {};
+      continue;
+    }
+
+    // Key-value pair (indented)
+    const kvMatch = line.match(/^\s+(\w+):\s+(.+)$/);
+    if (kvMatch && currentSection) {
+      const key = kvMatch[1];
+      let value = kvMatch[2].trim();
+
+      // Remove quotes
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      // Parse arrays [a, b, c]
+      if (value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1).split(',').map(s => {
+          s = s.trim();
+          if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+            s = s.slice(1, -1);
+          }
+          return s;
+        }).filter(s => s.length > 0);
+      }
+
+      // Parse numbers
+      if (typeof value === 'string' && /^\d+$/.test(value)) {
+        value = parseInt(value, 10);
+      }
+
+      result[currentSection][key] = value;
+    }
+  }
+
+  return result;
+}

package/src/lib/config-schema.js

@@ -0,0 +1,117 @@
+/**
+ * Validates a pipeline-config.yaml object against the expected schema.
+ * Returns { valid: boolean, errors: string[] }
+ */
+export function validateConfig(config) {
+  const errors = [];
+
+  // Required top-level sections
+  const requiredSections = ['project', 'tech_stack', 'models', 'quality', 'git', 'communication', 'knowledge'];
+  for (const section of requiredSections) {
+    if (!config[section]) {
+      errors.push(`Missing required section: ${section}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+
+  // Project section
+  const validProjectTypes = ['fullstack-web', 'backend-api', 'frontend-only', 'data-pipeline', 'mcp-server', 'document-generation', 'library'];
+  if (config.project?.type && !validProjectTypes.includes(config.project.type)) {
+    errors.push(`Invalid project.type: "${config.project.type}". Must be one of: ${validProjectTypes.join(', ')}`);
+  }
+  if (!config.project?.root) {
+    errors.push('Missing required field: project.root');
+  }
+
+  // Models section
+  const modelTiers = ['opus', 'sonnet', 'haiku'];
+  for (const tier of modelTiers) {
+    if (!config.models?.[tier]) {
+      errors.push(`Missing model tier: models.${tier}`);
+    }
+  }
+
+  // Quality section
+  const qualityFields = ['max_rejection_cycles', 'retrospective_every_n_stories', 'stall_threshold_minutes'];
+  for (const field of qualityFields) {
+    if (config.quality?.[field] !== undefined && typeof config.quality[field] !== 'number') {
+      errors.push(`quality.${field} must be a number, got: ${typeof config.quality[field]}`);
+    }
+  }
+
+  // Communication section
+  const validFormats = ['distilled', 'verbose'];
+  if (config.communication?.handoff_format && !validFormats.includes(config.communication.handoff_format)) {
+    errors.push(`Invalid communication.handoff_format: "${config.communication.handoff_format}". Must be: ${validFormats.join(' or ')}`);
+  }
+
+  // Knowledge section
+  const validModes = ['none', 'sqlite', 'local-docker', 'connect-to-existing'];
+  if (config.knowledge?.mode && !validModes.includes(config.knowledge.mode)) {
+    errors.push(`Invalid knowledge.mode: "${config.knowledge.mode}". Must be one of: ${validModes.join(', ')}`);
+  }
+
+  if (config.knowledge?.mode === 'sqlite' && !config.knowledge?.sqlite_db_path) {
+    errors.push('knowledge.sqlite_db_path is required when knowledge.mode is "sqlite"');
+  }
+
+  if ((config.knowledge?.mode === 'local-docker' || config.knowledge?.mode === 'connect-to-existing') && !config.knowledge?.chromadb_host) {
+    errors.push('knowledge.chromadb_host is required when knowledge.mode is "local-docker" or "connect-to-existing"');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Default configuration values.
+ */
+export const defaults = {
+  project: {
+    type: 'fullstack-web',
+    root: '.',
+    story_directory: './stories',
+    story_output_directory: './stories/{story_id}/output',
+    backlog_path: './pipeline-backlog.yaml',
+  },
+  tech_stack: {
+    language: 'TypeScript',
+    backend_framework: 'Express',
+    frontend_framework: 'React',
+    database_orm: 'Prisma',
+    test_framework_unit: 'Vitest',
+    test_framework_e2e: 'Playwright',
+    browser_automation_mcp: 'playwright-mcp',
+    state_management: 'React Context',
+  },
+  models: {
+    opus: ['BEND', 'FEND', 'CRITIC'],
+    sonnet: ['REQS', 'UXA', 'QA-A', 'QA-B', 'JUDGE-G1', 'JUDGE-G2', 'PMCP', 'Retrospective'],
+    haiku: ['Knowledge', 'Embed', 'Help'],
+  },
+  quality: {
+    max_rejection_cycles: 5,
+    retrospective_every_n_stories: 5,
+    stall_threshold_minutes: 15,
+  },
+  git: {
+    target_branch: '',
+    story_branch_prefix: 'story/',
+  },
+  communication: {
+    handoff_format: 'distilled',
+    inbox_message_max_tokens: 500,
+  },
+  knowledge: {
+    mode: 'sqlite',
+    sqlite_db_path: './v3/pipeline.db',
+    curated_files_path: './knowledge/curated',
+    correction_directives_path: './knowledge/correction-directives.yaml',
+  },
+  orchestration: {
+    recommended_context_window: '200k',
+    epic_progress_path: './epic-progress.md',
+  },
+};

package/src/lib/file-ops.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, copyFileSync, writeFileSync, readFileSync, readdirSync, statSync, appendFileSync } from 'fs';
+import { join, dirname, relative } from 'path';
+
+/**
+ * Recursively copy a directory's contents to a destination.
+ * Creates directories as needed.
+ */
+export function copyDir(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  const entries = readdirSync(src);
+  for (const entry of entries) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    const stat = statSync(srcPath);
+    if (stat.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Write a file, creating parent directories as needed.
+ */
+export function writeFileSafe(filePath, content) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Append a line to .gitignore if not already present.
+ */
+export function appendToGitignore(projectRoot, line) {
+  const gitignorePath = join(projectRoot, '.gitignore');
+  let content = '';
+  if (existsSync(gitignorePath)) {
+    content = readFileSync(gitignorePath, 'utf-8');
+  }
+  if (!content.includes(line)) {
+    const separator = content.endsWith('\n') || content === '' ? '' : '\n';
+    appendFileSync(gitignorePath, `${separator}${line}\n`, 'utf-8');
+  }
+}
+
+/**
+ * Check if a file exists.
+ */
+export function fileExists(filePath) {
+  return existsSync(filePath);
+}
+
+/**
+ * Read a file as UTF-8 string.
+ */
+export function readFile(filePath) {
+  return readFileSync(filePath, 'utf-8');
+}