dark-factory 0.1.0

package/README.md

@@ -0,0 +1,276 @@
+# Dark Factory
+
+**Specs in, production-grade features out.**
+
+Dark Factory is an open-source multi-agent framework for Claude Code. Feed it a raw idea or a bug report — it assembles a team of AI specialists (BA, principal engineer, developer, QA) who research, challenge, implement, and validate autonomously. No agent can cut corners because no agent has the full picture.
+
+> Inspired by [The Dark Factory Pattern](https://hackernoon.com/the-dark-factory-pattern-moving-from-ai-assisted-to-fully-autonomous-coding) — moving from AI-assisted to fully autonomous coding.
+
+```
+                          ┌─────────────┐
+  /df-onboard      ──────▶│   Onboard   │──▶ project-profile.md
+                          └─────────────┘
+                          ┌─────────────┐     ┌───────────────┐
+  /df-intake       ──────▶│  Spec Agent │────▶│   Architect   │──▶ APPROVED
+                          │  (BA)       │◀────│  (Principal)  │    │
+                          └─────────────┘  3+ │   3+ rounds   │    │
+                                           rounds └──────────────┘    ▼
+                          ┌─────────────┐     ┌─────────────┐   ┌──────────┐
+                          │ Code Agent  │────▶│ Test Agent  │──▶│ Promote  │──▶ Archive
+                          │ (Dev)       │◀────│ (QA)        │   │ + Archive│
+                          └─────────────┘  max└─────────────┘   └──────────┘
+                                           3 rounds
+```
+
+---
+
+## Quick Start
+
+**Prerequisites**: [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed + Node.js 18+
+
+```bash
+npx dark-factory init
+```
+
+Then open Claude Code and run `/df-onboard` to map your project.
+
+To update to the latest version later:
+
+```bash
+npx dark-factory update
+```
+
+---
+
+## Usage
+
+### 1. Onboard your project (once)
+
+```
+/df-onboard
+```
+
+Maps your tech stack, architecture, conventions, and quality bar into `dark-factory/project-profile.md`. Every agent reads this before starting work.
+
+### 2. Add a feature
+
+```
+/df-intake I need an API endpoint that lets users export their data as CSV
+```
+
+1. **Spec-agent** researches the codebase, asks focused questions, proposes scope (IN/OUT), writes spec + scenarios
+2. You review holdout scenarios in `dark-factory/scenarios/holdout/`
+3. `/df-orchestrate user-csv-export` — architect reviews (3+ rounds), code-agent implements, test-agent validates
+4. On success: holdout tests promoted into your permanent test suite, artifacts archived
+
+### 3. Fix a bug
+
+```
+/df-debug Users get 500 errors when exporting CSV with special characters in the filename
+```
+
+1. **Debug-agent** traces root cause (not just the symptom), maps impact, writes debug report
+2. You confirm the diagnosis
+3. `/df-orchestrate csv-special-chars-fix` — architect reviews, then strict red-green cycle:
+   - Write a failing test that **proves** the bug (no source code changes)
+   - Implement the minimal fix (no test changes)
+   - Failing test now passes, all existing tests still pass
+4. Holdout validation, promote, archive
+
+### 4. Maintenance
+
+```
+/df-cleanup
+```
+
+Retries stuck promotions, completes archival, lists stale features.
+
+---
+
+## Why Dark Factory?
+
+AI coding assistants write code fast, but fast code on a flawed spec is fast failure. They skip architecture review, miss security concerns, and can't validate their own work honestly — they wrote both the code and the tests.
+
+Dark Factory separates concerns into independent agents with strict information barriers:
+
+| What goes wrong without it | How Dark Factory prevents it |
+|---|---|
+| AI guesses the scope instead of asking | Spec-agent runs structured discovery — asks focused questions, proposes IN/OUT scope, waits for confirmation |
+| AI skips architecture review | Architect-agent reviews every spec for security, performance, data integrity — 3+ rounds before any code |
+| AI writes tests that match its own implementation | Test-agent uses **holdout scenarios** the code-agent has never seen — can't teach to the test |
+| Bug fixes that mask symptoms | Debug-agent traces root cause forensically; code-agent must write a failing test FIRST, then fix WITHOUT changing the test |
+| AI doesn't understand the existing codebase | Onboard-agent maps architecture, conventions, and quality bar before any work begins |
+| Specs and test artifacts pile up forever | Auto-promote holdout tests into permanent suite, then archive artifacts |
+
+---
+
+## How It Works
+
+### The 7 Agents
+
+| Agent | Role | Analogy |
+|-------|------|---------|
+| **Onboard** | Maps the project before any work begins | New team lead's first week |
+| **Spec** | Discovers scope, challenges assumptions, writes specs | Senior BA who asks hard questions |
+| **Debug** | Forensic root cause analysis, impact assessment | The engineer who reads stack traces for breakfast |
+| **Architect** | Reviews specs for architecture, security, performance | Principal engineer who blocks bad designs |
+| **Code** | Implements features and fixes | Senior dev who follows the spec exactly |
+| **Test** | Validates with hidden scenarios | QA who writes tests the dev has never seen |
+| **Promote** | Moves holdout tests into permanent test suite | Release engineer |
+
+### Information Barriers
+
+The key innovation. Each agent has **strict boundaries** on what it can see:
+
+```
+                    ┌─────────────────────────────────────────────┐
+                    │              Project Profile                 │
+                    │  (all agents except test/promote can read)   │
+                    └─────────────────────────────────────────────┘
+
+    ┌──────────┐          ┌──────────┐          ┌──────────┐
+    │   Spec   │          │   Code   │          │   Test   │
+    │  Agent   │          │  Agent   │          │  Agent   │
+    │          │          │          │          │          │
+    │ Sees:    │          │ Sees:    │          │ Sees:    │
+    │ codebase │          │ spec,    │          │ spec,    │
+    │ docs     │          │ PUBLIC   │          │ HOLDOUT  │
+    │          │          │ scenarios│          │ scenarios│
+    │ Cannot:  │          │          │          │          │
+    │ holdout  │          │ Cannot:  │          │ Cannot:  │
+    │ results  │          │ HOLDOUT  │          │ PUBLIC   │
+    └──────────┘          │ results  │          │ scenarios│
+                          └──────────┘          └──────────┘
+
+    ┌──────────┐
+    │Architect │  Can see: spec, codebase, project profile
+    │  Agent   │  CANNOT see: ANY scenarios (public or holdout)
+    │          │  CANNOT discuss tests with other agents
+    └──────────┘
+```
+
+The code-agent can't "teach to the test" because it never sees the holdout scenarios. The architect can't compromise test coverage because it never sees tests at all. The test-agent can't soften its validation because it doesn't know what the code-agent was told to build.
+
+### Red-Green Cycle (Bugfixes)
+
+Dark Factory enforces strict discipline that prevents the most common AI failure mode: fixing the symptom instead of the root cause.
+
+```
+Phase 1 (Red):   Write test   →  Test FAILS  ✓  (bug is real)
+                 ⚠ Zero source code changes allowed
+
+Phase 2 (Green): Implement fix →  Test PASSES ✓  (fix works)
+                 ⚠ Zero test file changes allowed
+                 ⚠ All existing tests must still pass
+```
+
+If the test doesn't fail in Phase 1, the test is wrong — not the bug. If existing tests break in Phase 2, the fix has regression — revise the fix, not the tests.
+
+### Feature Lifecycle
+
+Every feature is tracked in `dark-factory/manifest.json`:
+
+```
+active → passed → promoted → archived
+  │         │         │          │
+  │         │         │          └── Specs + scenarios in dark-factory/archive/
+  │         │         └── Holdout tests in permanent test suite
+  │         └── All holdout tests passed
+  └── Spec created, awaiting implementation
+```
+
+`/df-cleanup` recovers features stuck in intermediate states.
+
+---
+
+## Reference
+
+### Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/df-onboard` | Map project architecture, conventions, quality bar |
+| `/df-intake {desc}` | Create feature spec (discovers scope, writes scenarios) |
+| `/df-debug {desc}` | Investigate bug (root cause, impact, debug report) |
+| `/df-orchestrate {name}` | Implement (architect review → code → test → promote → archive) |
+| `/df-cleanup` | Recover stuck features, list stale work |
+| `/df-spec` | Show spec templates for manual writing |
+| `/df-scenario` | Show scenario templates for manual writing |
+
+### Project Structure
+
+```
+your-project/
+├── .claude/
+│   ├── agents/                    # 7 agent definitions
+│   │   ├── onboard-agent.md
+│   │   ├── spec-agent.md
+│   │   ├── debug-agent.md
+│   │   ├── architect-agent.md
+│   │   ├── code-agent.md
+│   │   ├── test-agent.md
+│   │   └── promote-agent.md
+│   └── skills/                    # 7 slash commands
+│       ├── df-onboard/SKILL.md
+│       ├── df-intake/SKILL.md
+│       ├── df-debug/SKILL.md
+│       ├── df-orchestrate/SKILL.md
+│       ├── df-spec/SKILL.md
+│       ├── df-scenario/SKILL.md
+│       └── df-cleanup/SKILL.md
+├── dark-factory/
+│   ├── project-profile.md         # Project map (from /df-onboard)
+│   ├── manifest.json              # Feature lifecycle tracking
+│   ├── specs/features/            # Feature specs
+│   ├── specs/bugfixes/            # Debug reports
+│   ├── scenarios/public/          # Visible to code-agent
+│   ├── scenarios/holdout/         # Hidden from code-agent
+│   ├── results/                   # Test output (gitignored)
+│   └── archive/                   # Completed feature artifacts
+└── CLAUDE.md                      # Project instructions (auto-updated)
+```
+
+### Configuration
+
+The init script auto-detects your project type:
+
+```bash
+# Force a project type
+node scripts/init-dark-factory.js --dir . --project-type nestjs
+node scripts/init-dark-factory.js --dir . --project-type node
+node scripts/init-dark-factory.js --dir . --project-type generic
+
+# Scaffold a first feature
+node scripts/init-dark-factory.js --dir . --feature user-auth
+```
+
+Supported project types affect agent prompts (e.g., NestJS agents know about modules, decorators, and DTOs).
+
+---
+
+## Design Decisions
+
+**Why holdout scenarios?** — Without them, the AI writes code and tests from the same understanding. Holdout scenarios are written by the spec-agent (who understands the requirements) and validated by the test-agent (who never talks to the code-agent). The code-agent must implement correctly to pass tests it's never seen.
+
+**Why architect review?** — A spec written by a BA may miss performance concerns, security gaps, or architectural inconsistencies. The architect-agent reviews every spec with principal-engineer rigor — but is banned from seeing tests, so it can't influence what gets tested.
+
+**Why strict red-green for bugs?** — The most dangerous AI bug fix is one that makes the test pass by changing the test. Dark Factory enforces: write the test first (Phase 1, no code changes allowed), then fix the code (Phase 2, no test changes allowed). If the test doesn't fail, the test is wrong.
+
+**Why project onboarding?** — An AI dropped into an unknown codebase will follow "best practices" instead of "this project's practices." The onboard-agent maps reality — messy or clean — so every agent works WITH the existing patterns instead of against them.
+
+**Why auto-promote and archive?** — Dark Factory artifacts (specs, scenarios) accumulate forever. After holdout tests pass, they're automatically promoted into the permanent test suite (preserving regression coverage) and artifacts are archived.
+
+---
+
+## Contributing
+
+Contributions welcome. The test suite is the source of truth — if the tests pass, the pipeline is intact.
+
+```bash
+# Run all tests (no dependencies — uses Node.js built-in test runner)
+node --test tests/dark-factory-setup.test.js
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+
+/**
+ * Dark Factory CLI
+ *
+ * Usage:
+ *   npx dark-factory init          Install Dark Factory into current project
+ *   npx dark-factory update        Update agents/skills/rules to latest version
+ *   npx dark-factory init --dir /path/to/project
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+
+function log(msg) { console.log(msg); }
+function info(msg) { console.log(`  ${GREEN}+${RESET} ${msg}`); }
+function update(msg) { console.log(`  ${YELLOW}~${RESET} ${msg}`); }
+function skip(msg) { console.log(`  ${DIM}-${RESET} ${DIM}${msg}${RESET}`); }
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+    return true;
+  }
+  return false;
+}
+
+function touchGitkeep(dirPath) {
+  ensureDir(dirPath);
+  const keepPath = path.join(dirPath, ".gitkeep");
+  if (!fs.existsSync(keepPath)) {
+    fs.writeFileSync(keepPath, "", "utf8");
+  }
+}
+
+function copyFileWithLog(src, dest) {
+  const rel = path.relative(process.cwd(), dest);
+  ensureDir(path.dirname(dest));
+
+  if (fs.existsSync(dest)) {
+    const existing = fs.readFileSync(dest, "utf8");
+    const incoming = fs.readFileSync(src, "utf8");
+    if (existing === incoming) {
+      skip(`${rel} (unchanged)`);
+      return;
+    }
+    update(rel);
+  } else {
+    info(rel);
+  }
+
+  fs.copyFileSync(src, dest);
+}
+
+function copyDirRecursive(src, dest) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      copyFileWithLog(srcPath, destPath);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// .gitignore management
+// ---------------------------------------------------------------------------
+
+function updateGitignore(dir) {
+  const gitignorePath = path.join(dir, ".gitignore");
+  let content = "";
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, "utf8");
+  }
+
+  let modified = false;
+
+  // .claude selective tracking
+  const claudeEntries = [
+    "/.claude/*",
+    "!/.claude/agents/",
+    "!/.claude/rules/",
+    "!/.claude/skills/",
+  ];
+
+  const claudeLineRegex = /^[/#]*\s*\.?\/?\.claude\s*$/m;
+  if (claudeLineRegex.test(content)) {
+    content = content.replace(claudeLineRegex, claudeEntries.join("\n"));
+    modified = true;
+  } else if (!content.includes("/.claude/*")) {
+    content += "\n# Claude Code — selectively track agents, rules, and skills\n" + claudeEntries.join("\n") + "\n";
+    modified = true;
+  }
+
+  // Ensure !/.claude/rules/ is present (may be missing from older installs)
+  if (content.includes("/.claude/*") && !content.includes("!/.claude/rules/")) {
+    content = content.replace("!/.claude/skills/", "!/.claude/rules/\n!/.claude/skills/");
+    modified = true;
+  }
+
+  // dark-factory/results
+  if (!content.includes("dark-factory/results")) {
+    content += "\n# Dark Factory results (local test output)\ndark-factory/results/\n";
+    modified = true;
+  }
+
+  if (modified) {
+    fs.writeFileSync(gitignorePath, content, "utf8");
+    update(".gitignore");
+  } else {
+    skip(".gitignore (already configured)");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+function cmdInit(targetDir, opts = {}) {
+  const templateDir = path.join(__dirname, "..", "template");
+
+  log("");
+  log(`${BOLD}Dark Factory${RESET} — installing into ${CYAN}${targetDir}${RESET}`);
+  log("");
+
+  // 1. Copy .claude/ (agents, skills, rules) — always overwrite to latest
+  log(`${BOLD}Agents & Skills${RESET}`);
+  copyDirRecursive(
+    path.join(templateDir, ".claude"),
+    path.join(targetDir, ".claude"),
+  );
+
+  // 2. Create dark-factory/ working directories — never overwrite existing content
+  log("");
+  log(`${BOLD}Working directories${RESET}`);
+  const dfDir = path.join(targetDir, "dark-factory");
+  const dirs = [
+    "specs/features",
+    "specs/bugfixes",
+    "scenarios/public",
+    "scenarios/holdout",
+    "results",
+    "archive",
+  ];
+  for (const d of dirs) {
+    const full = path.join(dfDir, d);
+    if (ensureDir(full)) {
+      info(`dark-factory/${d}/`);
+    } else {
+      skip(`dark-factory/${d}/ (exists)`);
+    }
+    touchGitkeep(full);
+  }
+
+  // 3. Create manifest.json if missing
+  const manifestPath = path.join(dfDir, "manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    fs.writeFileSync(manifestPath, JSON.stringify({ version: 1, features: {} }, null, 2) + "\n", "utf8");
+    info("dark-factory/manifest.json");
+  } else {
+    skip("dark-factory/manifest.json (exists)");
+  }
+
+  // 4. Update .gitignore
+  log("");
+  log(`${BOLD}Git config${RESET}`);
+  updateGitignore(targetDir);
+
+  // Done
+  log("");
+  log(`${GREEN}${BOLD}Done!${RESET} Dark Factory is ready.`);
+  log("");
+  log(`${BOLD}Next steps:${RESET}`);
+  log(`  1. Run ${CYAN}/df-onboard${RESET} in Claude Code to map your project`);
+  log(`  2. Describe a feature or bug — Dark Factory activates automatically`);
+  log(`  3. Or use ${CYAN}/df {description}${RESET} explicitly`);
+  log("");
+}
+
+function cmdUpdate(targetDir) {
+  const templateDir = path.join(__dirname, "..", "template");
+
+  log("");
+  log(`${BOLD}Dark Factory${RESET} — updating agents, skills & rules in ${CYAN}${targetDir}${RESET}`);
+  log("");
+
+  log(`${BOLD}Agents & Skills${RESET}`);
+  copyDirRecursive(
+    path.join(templateDir, ".claude"),
+    path.join(targetDir, ".claude"),
+  );
+
+  // Also update .gitignore in case new entries were added
+  log("");
+  log(`${BOLD}Git config${RESET}`);
+  updateGitignore(targetDir);
+
+  log("");
+  log(`${GREEN}${BOLD}Updated!${RESET} Agents, skills, and rules are now at the latest version.`);
+  log(`  Your specs, scenarios, and manifest were not touched.`);
+  log("");
+}
+
+function cmdHelp() {
+  log(`
+${BOLD}Dark Factory${RESET} — AI-powered development pipeline for Claude Code
+
+${BOLD}Usage:${RESET}
+  npx dark-factory init              Install into current project
+  npx dark-factory update            Update agents/skills/rules to latest
+  npx dark-factory help              Show this help
+
+${BOLD}Options:${RESET}
+  --dir <path>                       Target directory (default: current dir)
+
+${BOLD}What gets installed:${RESET}
+  .claude/agents/     7 specialized AI agents
+  .claude/skills/     8 slash command skills (/df, /df-intake, etc.)
+  .claude/rules/      Auto-detection rules
+  dark-factory/       Working directory (specs, scenarios, results)
+
+${BOLD}After install:${RESET}
+  1. Open Claude Code in your project
+  2. Run /df-onboard to map your project
+  3. Just describe what you need — Dark Factory activates automatically
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+  let command = null;
+  let targetDir = process.cwd();
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--dir" && args[i + 1]) {
+      targetDir = path.resolve(args[++i]);
+    } else if (args[i] === "--help" || args[i] === "-h") {
+      command = "help";
+    } else if (!args[i].startsWith("-")) {
+      command = args[i];
+    }
+  }
+
+  switch (command) {
+    case "init":
+      cmdInit(targetDir);
+      break;
+    case "update":
+      cmdUpdate(targetDir);
+      break;
+    case "help":
+      cmdHelp();
+      break;
+    default:
+      // No command = init (most common use case)
+      if (!command) {
+        cmdInit(targetDir);
+      } else {
+        log(`Unknown command: ${command}`);
+        log(`Run 'npx dark-factory help' for usage.`);
+        process.exit(1);
+      }
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "dark-factory",
+  "version": "0.1.0",
+  "description": "AI-powered development pipeline for Claude Code — specs in, production-grade features out",
+  "bin": {
+    "dark-factory": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "development",
+    "pipeline",
+    "agents",
+    "spec",
+    "testing"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nguyenhuynhkhanh/dark-factory.git"
+  }
+}