Software Factory

Software Factory

One invocation, full pipeline. Turns a brief into shipped software by chaining superpowers (discipline) + karpathy (code restraint) + ruflo (swarm engine) + ECC (agent catalog + security) + open-design (frontend) + Obsidian (durable memory).

When to use

User says "build me X", "make a full website/app for Y", "/factory ...". For a 1-2 file fix, do NOT use this — just edit directly. This is for real multi-file builds.

Locating the orchestrator

This plugin ships its glue script at scripts/orchestrate.mjs. Resolve it as:

• Installed as a plugin: "$CLAUDE_PLUGIN_ROOT/scripts/orchestrate.mjs" (Windows cmd/PowerShell: "%CLAUDE_PLUGIN_ROOT%\scripts\orchestrate.mjs" / "$env:CLAUDE_PLUGIN_ROOT\scripts\orchestrate.mjs").
• Project-local copy: scripts/factory/orchestrate.mjs. Pick whichever exists. Below, <ORCH> means that resolved path.

The pipeline (follow in order; each phase gates the next)

Phase 0 — Readiness check

0. Run node "<ORCH>" doctor. It reports which tools are present (node/git/npx required; ruflo + superpowers core; agentshield gate; obsidian + open-design optional). If a required item is missing, stop and tell the user. Missing core/optional tools are fine — note which phases will run degraded and continue.

Phase 1 — Design gate (superpowers + karpathy)

1. Invoke superpowers:brainstorming. Do NOT skip. Ask one question at a time, propose 2-3 approaches, converge on a written design. karpathy rules stay active on every turn: surface assumptions, simplest thing that works, no bloat.
2. Write the approved design to docs/superpowers/specs/<date>-<feature>-design.md.
3. Mirror the design to the Obsidian vault as the durable spec (if obsidian-cli is installed): obsidian create path="projects/<feature>" template="spec" then append the design body. Skip silently if Obsidian is not running.

Phase 2 — Plan (superpowers)

4. Invoke superpowers:writing-plans. Produce a task-broken plan at docs/superpowers/plans/<date>-<feature>.md using ## Task N: headers, **Files:** blocks, and - [ ] steps. No placeholders, exact paths.

Phase 3 — Dispatch manifest (the glue script)

5. Parse the plan into an agent dispatch manifest:

   node "<ORCH>" plan docs/superpowers/plans/<date>-<feature>.md --seed-memory
   

   It writes .swarm/dispatch/<slug>.json (tasks + assigned agent type + model tier) and a .brief.md. Read the manifest JSON — it is your task queue.

Phase 4 — Swarm execution (ruflo + ECC + TDD)

6. Init the swarm topology once: npx ruflo@latest swarm init (or the mcp__ruflo__swarm_init tool with topology=hierarchical).
7. Execute via superpowers:subagent-driven-development. For EACH task in the manifest, in dependency order:
   • Spawn an Agent of the manifest's agent type (coder / frontend-dev / backend-dev / tester / security-reviewer / architect / documenter), named task-<N>, using the suggested model tier.
   • Tell each agent: work TDD-first (superpowers:test-driven-development); obey karpathy surgical-changes; before coding, recall prior decisions from ruflo memory (mcp__ruflo__agentdb_hierarchical-recall query="<feature> <topic>"); after finishing, store what worked back to memory.
   • Independent tasks: dispatch in parallel (superpowers:dispatching-parallel-agents), each in its own git worktree (superpowers:using-git-worktrees) to avoid conflicts.
   • Frontend tasks: if open-design is running (daemon on :7456), route UI generation through it against an active DESIGN.md brand spec, then pull the emitted HTML/components from .od/artifacts/ into the repo. Otherwise build directly with the frontend-dev agent.
8. Each agent reports DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED. Run the spec-compliance then code-quality review subagents per task. Repair and re-dispatch on concerns before moving on.

Phase 5 — Security gate (ECC AgentShield)

9. Run the gate. Exit code 2 = critical = STOP, do not ship:

   node "<ORCH>" gate .
   

   Deep adversarial pass: node "<ORCH>" gate . --opus. Also run mcp__ruflo__aidefence_scan for leaked secrets/PII. Fix all criticals, re-run until clean.

Phase 6 — Verify + ship (superpowers)

10. Invoke superpowers:verification-before-completion. Actually run the app / build / tests and observe real output. No "should work" — show evidence.
11. npm run build && npm test (or the project's equivalent) must pass.
12. superpowers:finishing-a-development-branch → PR. Write decisions/lessons back to the Obsidian vault and store the run's patterns in ruflo memory.

Rules

• Phases are gates. Never start Phase N+1 until Phase N's exit criteria pass.
• The design gate (Phase 1) and the security gate (Phase 5) are hard blocks.
• Degrade gracefully: obsidian / open-design / agentshield / ruflo absent → note it, skip that enrichment, continue. superpowers discipline is the irreducible core.
• Report progress per phase. Do not silently batch.

Dependencies (optional, auto-detected; the skill degrades if absent)

• superpowers plugin (process discipline) — strongly recommended.
• ruflo MCP server (the swarm engine + HNSW memory).
• ECC ecc-agentshield (security gate) — npm i -g ecc-agentshield.
• karpathy-guidelines, obsidian-cli, open-design — multipliers. Node 20+ required for the orchestrator script.