ai-factory

Central factory for a 12-agent software factory pattern. Generates platform-specific files (Claude Code, Kiro, Codex CLI) for many polyrepos from a single source of truth.

Designed for the case: many repos, many techs, many AI platforms.

What it is

• Prompts library — 12 agent + 3 skill prompts written once, platform-neutral and stack-neutral.
• Profile library — pre-written rule packs per stack (Next.js, Node+Fastify, Go+Echo, Python+FastAPI, etc.).
• Platform adapters — code that renders prompts + profile + per-repo manifest into the right files for each AI platform.
• CLI — factory install reads .factory.yaml in any repo and generates everything.

Architecture: AI and human collaboration

The chain is structured so the human stays in the loop where judgment matters, and steps out where the AI is reliable. Three layers, two roles, three checkpoints.

Layers

The Tier 3 flow (full chain)

sequenceDiagram
    actor Human
    participant Orchestrator
    participant Agents as Specialist Agents

    Human->>Orchestrator: /feature-factory <request>
    Note over Orchestrator: triage gate
    Orchestrator->>Agents: invoke researcher (read-only)
    Agents-->>Orchestrator: relevant files, patterns, risks
    Orchestrator->>Agents: invoke story-writer (read-only)
    Agents-->>Orchestrator: user story + acceptance criteria

    Note over Human,Orchestrator: ⏸ CHECKPOINT 1
    Orchestrator->>Human: present story
    Human->>Orchestrator: approved

    Orchestrator->>Agents: invoke spec-writer (read-only)
    Agents-->>Orchestrator: technical brief<br/>(files-that-will-change, API, tests)

    Note over Human,Orchestrator: ⏸ CHECKPOINT 2
    Orchestrator->>Human: present brief
    Human->>Orchestrator: approved

    Orchestrator->>Agents: invoke migration-author (scoped to migrations)
    Agents-->>Orchestrator: migration files + safety notes<br/>(or "Not applicable" if no schema changes)
    Orchestrator->>Agents: invoke backend-builder (scoped edit)
    Agents-->>Orchestrator: files + API contract + test results
    Orchestrator->>Agents: invoke frontend-builder (scoped edit)<br/>(passes API contract verbatim)
    Agents-->>Orchestrator: files + test results
    Orchestrator->>Agents: invoke devops-builder (scoped to infra)
    Agents-->>Orchestrator: CI/IaC files<br/>(or "Not applicable" if no infra changes)
    Orchestrator->>Agents: invoke test-verifier (test files only)
    Agents-->>Orchestrator: pass/fail per acceptance criterion

    opt any AC fails (max 3 iterations)
        Orchestrator->>Agents: re-invoke responsible builder
        Agents-->>Orchestrator: fixed
        Orchestrator->>Agents: re-invoke test-verifier
        Agents-->>Orchestrator: pass/fail
    end

    Orchestrator->>Agents: invoke security-reviewer (read-only)
    Agents-->>Orchestrator: security findings (Critical / Important / Minor)
    Orchestrator->>Agents: invoke performance-reviewer (read-only)
    Agents-->>Orchestrator: perf findings (Critical / Important / Minor)
    Orchestrator->>Agents: invoke validator (read-only)
    Agents-->>Orchestrator: project-rule findings (Critical / Important / Minor)

    opt Critical findings from any reviewer (max 3 iterations)
        Orchestrator->>Agents: re-invoke responsible builder
        Agents-->>Orchestrator: fixed
        Orchestrator->>Agents: re-invoke the reviewer that flagged it
        Agents-->>Orchestrator: findings
    end

    Orchestrator->>Agents: invoke doc-writer (scoped to docs/)
    Agents-->>Orchestrator: CHANGELOG + README + migration guide<br/>+ suggested PR description

    Note over Human,Orchestrator: ⏸ CHECKPOINT 3
    Orchestrator->>Human: final summary + suggested PR title/body
    Note over Human: review diff, open PR

Who decides what

Why this split

• Humans are better at: business judgment, ambiguous trade-offs, catching missing requirements, taste.
• AI agents are better at: breadth (reading many files quickly), discipline (checking the same 30 things every time), patience (writing the boring fixtures and edge-case tests).
• The chain is bad at: anything not covered by the validator's checklist. That's why the validator's checklist is the most important prompt to keep tuning — every gap the validator misses becomes a new line in its checklist.

The three checkpoints are not bureaucracy. They are where wrong assumptions cost the least to fix. A mistake caught at CHECKPOINT 2 (brief approval) costs a re-prompt. The same mistake caught after the builders run costs hours of rework.

Repo layout

ai-factory/
├── prompts/
│   ├── agents/         ← researcher, story-writer, ... (platform-neutral)
│   └── skills/         ← feature-factory, quick-fix, spike
├── profiles/           ← stack rule packs (nextjs, node-fastify, go-echo, ...)
├── src/
│   ├── cli.ts          ← CLI entrypoint
│   ├── manifest.ts     ← .factory.yaml parsing + validation
│   ├── render.ts       ← prompt/profile composition
│   ├── commands/       ← install, init, sync, feature
│   └── platforms/      ← adapters: one per AI platform
└── examples/           ← sample .factory.yaml manifests

Path examples in this README assume the checkout directory is named ai-factory. Adjust paths if you cloned it under a different name (e.g., ai-software-factory).

Each project repo gets a small .factory.yaml manifest (~20 lines) declaring layer, stack profile, commands, paths, and target platforms. factory install generates the platform files.

Install

cd ai-factory
pnpm install            # or `npm install`
pnpm link --global      # or `npm link` — exposes `factory` globally
factory --version       # should print the version

That makes factory available from any directory. Skip the link step if you'd rather invoke via npx tsx src/cli.ts <command> from inside the ai-factory checkout.

Commands at a glance

After installing and linking the CLI globally, invoke any of these with just factory <command> from any directory. Otherwise run them as npx tsx /path/to/ai-factory/src/cli.ts <command>.

Usage

Learn the design: docs/book/ — the architecture book.
Explains the fundamentals and the why behind every major decision, so the system is
easy to learn and to extend. Start there if you're new or planning a change.

Walkthroughs:

• docs/walkthrough.md — one feature through the full Tier 3 chain in a single repo. What to type at each checkpoint, what the AI returns, common mistakes.
• docs/cross-repo.md — a feature spanning multiple repos via the contract bridge (backend repo → contracts → frontend repo).

In each project repo, create .factory.yaml (either run factory init, or copy from examples/ and edit):

name: billing-api                          # repo identifier (required)
layer: backend                             # backend | frontend | worker | mobile | fullstack (required)
profile: node-fastify                      # file in profiles/ without .md (required)
# factory-repo: omitted on purpose — the global `factory` binary knows where it is.
# Only set this if you want to pin a specific local checkout for an unusual workflow.
contracts-repo: ../ai-factory-contracts    # cross-repo contract dir (optional, Phase B)

commands:                                  # required — agents read these
  typecheck: pnpm typecheck
  lint: pnpm lint
  test: pnpm test
  acceptance: pnpm test:integration        # optional — separate acceptance/e2e command

paths:                                     # path scoping for agents (all lists optional)
  backend:                                 # Backend Builder may edit
    - src/routes/**
    - src/services/**
  frontend: []                             # Frontend Builder may edit
  migrations:                              # Migration Author may edit
    - prisma/**
  infra:                                   # DevOps Builder may edit
    - .github/workflows/**
  docs:                                    # Doc Writer may edit
    - docs/**
    - CHANGELOG.md
  shared:                                  # readable by either builder
    - packages/shared/**
  tests:                                   # Test Verifier may edit
    - tests/integration/**
  forbidden:                               # no agent may edit
    - .env*
    - "**/secrets.*"

dont-do:                                   # optional — appended to CLAUDE.md
  - Do not call the legacy /v1 endpoints.

platforms:                                 # required — which adapters to run
  - claude-code
  - kiro
  - codex

notes: |                                   # optional — free-form prose appended to CLAUDE.md
  This repo is the authoritative source for billing API contracts.

Then run from your project repo:

factory install        # if you ran `pnpm link --global`
# or:
npx tsx /path/to/ai-factory/src/cli.ts install

This reads your manifest, loads the matching profile, and writes platform-specific files (e.g., .claude/agents/*.md + CLAUDE.md for Claude Code).

Keeping things in sync (updating)

Three layers can drift over time: the central ai-factory checkout, the global factory binary, and the per-repo generated files. Update flow:

Refresh the central factory

cd /path/to/ai-factory
git pull                # pulls new prompts, profiles, adapter changes
pnpm install            # only if dependencies changed

The pnpm link --global from initial setup still points at this directory, so the global factory command picks up new code automatically — no re-link needed unless you blew away node_modules.

Refresh one project

In any repo that already has .factory.yaml:

cd /path/to/your-project
factory install
git status                                    # see what changed
git add CLAUDE.md .claude .factory.yaml       # whatever the diff shows
git commit -m "chore: update factory artifacts"

That's it. Re-running install regenerates everything from the current state of the central factory. The new agents / prompts / profile rules land in place.

Refresh many projects at once

If you maintain a workspace file listing your repos:

factory sync               # re-installs every listed repo
factory sync --dry-run     # preview what would happen

Useful when a central prompt or profile change needs to propagate across 5+ repos.

What gets preserved vs overwritten

Hard rule: never hand-edit generated files. Edit the manifest, the profile, or the central prompts — then re-run factory install. Otherwise your edits are lost next sync.

When you need to change something — where to edit

After editing anything in the central ai-factory/: git push → in each project: factory install (or one-shot factory sync).

TL;DR

(cd /path/to/ai-factory && git pull)        # 1. refresh central
cd /path/to/your-project                    # 2. enter project
factory install                             # 3. regenerate

Status

Phase A — foundation (shipped)

• ✅ Manifest parsing + validation (.factory.yaml)
• ✅ Render engine (template substitution + context-file composition)
• ✅ Platform-neutral agent prompts (12 agents, 3 skills)
• ✅ Stack profiles: Next.js App Router, Node+Fastify, Go+Echo, Python+FastAPI, Bun+Hono, Quarkus Reactive (Java), React + Vite, React + rsbuild + Module Federation (micro-frontend), Python library
• ✅ Claude Code adapter — generates CLAUDE.md + .claude/agents/* + .claude/skills/*/SKILL.md, plus a PreToolUse path-guard hook (.claude/hooks/factory-guard.mjs + .claude/hooks/factory-scope.json + merged .claude/settings.json) that enforces the manifest's forbidden: list and per-agent allow-lists at the tool level — out-of-scope edits are blocked, not just discouraged by prose
• ✅ factory install command

Phase B — multi-platform + multi-repo (shipped)

• ✅ Kiro adapter — generates .kiro/steering/* (IDE) + .kiro/agents/*.json (Kiro CLI) + .kiro/FACTORY.md. Path scoping is enforced on the CLI via a preToolUse hook on fs_write (same guard as Claude Code); the IDE flow stays prompt-only
• ✅ Codex CLI adapter — generates AGENTS.md + .codex/agents/* + executable bash orchestrators in .codex/orchestrator/*.sh + .codex/FACTORY.md. Path scoping is enforced by a post-run git-diff check (.codex/factory-check.mjs) that reverts out-of-scope edits and halts the chain
• ✅ factory init — interactive manifest wizard with stack auto-detection
• ✅ factory sync — workspace-wide refresh driven by factory.workspace.yaml
• ✅ factory feature start / pull / ship / list / status — cross-repo contract bridge (MVP)
• ✅ Documentation: docs/walkthrough.md (single repo) + docs/cross-repo.md (polyrepo)

Build-on-demand (not blockers)

These are deferred until you actually need them. Each is straightforward to add when the use case shows up.

Adapters

• ⏳ Cursor / Windsurf — not implemented. Both are rules-file (context-injection) tools with no generatable enforcement hook, so an adapter would be prompt-only (like the Kiro IDE flow). Add one by implementing PlatformAdapter in src/platforms/ and registering it in src/platforms/index.ts — see Chapter 8 of the book.

More stack profiles — add by writing a markdown file under profiles/ matching the shape of the existing profiles (architecture rules, don't-do, default commands, default paths). Likely candidates when you hit them:

• Rust + Axum / Actix
• SvelteKit (fullstack)
• Nuxt 3 (fullstack)
• Django (Python)
• React Native / Flutter (mobile)
• Ruby on Rails
• Spring Boot (Java, blocking)
• .NET / ASP.NET Core

Chain ↔ contract-bridge integration — currently the user invokes factory feature pull / ship manually around the chain. A future iteration can have the skill orchestrator auto-pull on start and auto-ship on completion.

Contract-format validation — ensure the backend repo's emitted contract format (OpenAPI, proto, Zod, etc.) matches what the frontend repo's spec-writer expects.

Status locking — protect against two developers running feature ship on the same repo simultaneously (rare in practice).

Global factory binary — shipped. bin/factory.mjs is a tsx-spawn shim; pnpm link --global (or npm link) installs it globally so factory <command> works from any directory.

How prompts work

Each prompt in prompts/agents/ and prompts/skills/ is platform-neutral. References to the project context document use the template variable {{CONTEXT_FILE}}, which the adapter substitutes at install time (e.g., CLAUDE.md, AGENTS.md, .kiro/steering/project.md).

Stack-specific content (commands, paths, conventions) does NOT live in the prompts. It comes from:

• Manifest (per-repo) — commands, paths, layer, repo-specific don't-do rules.
• Profile (shared) — architecture rules, conventions, don't-do, default paths/commands.

The render engine in src/render.ts composes manifest + profile into the platform's context file. The adapter writes that file plus the agent/skill files in the platform's format.

How profiles work

A profile is a markdown file under profiles/. It contains:

• Architecture rules
• Don't-do list
• Conventions
• Default paths (seed values for factory init — see note below)
• Default commands (seed values for factory init — see note below)

The profile body is inlined verbatim into CLAUDE.md (or the platform's context file) under the ## Profile rules section, including its own markdown headings. When you write a profile, structure it as a self-contained section because its ## Architecture rules heading ends up nested inside CLAUDE.md's ## Profile rules.

The "Default paths" and "Default commands" YAML blocks in the profile are read only by factory init, which parses them (src/util/profile-defaults.ts) to pre-fill the wizard's answers and the generated manifest. factory install never reads them: at install time the real values come from the manifest's own paths: and commands: blocks.

Two consequences worth knowing:

• Editing a profile's defaults changes nothing in repos that already have a .factory.yaml — install won't pick them up, and the manifest is never overwritten. Existing repos must copy the new values in by hand (or re-run init --force).
• A path key the profile suggests but the manifest omits is not enforced — the scope guard is generated from the manifest's keys only.

To add a profile for a new stack:

1. Create profiles/<your-stack>.md.
2. Follow the structure of profiles/nextjs-app-router.md as a template.
3. Reference it in a manifest with profile: <your-stack>.

How adapters work

Each adapter implements PlatformAdapter in src/platforms/index.ts:

export interface PlatformAdapter {
  name: Platform;
  contextFileName: string;
  generate(args: {
    targetRoot: string;
    manifest: Manifest;
    agents: PromptFile[];
    skills: PromptFile[];
    profileBody: string;
  }): Promise<PlatformWriteResult>;
}

src/platforms/claude-code.ts is the reference implementation; kiro.ts and codex.ts are the other two. To add a platform, implement PlatformAdapter and register it in src/platforms/index.ts.

Enforced path scoping (Claude Code)

On Claude Code, path scoping is enforced, not just advised:

• The forbidden: list is blocked session-wide by a PreToolUse hook
  (.claude/hooks/factory-guard.mjs + a merged .claude/settings.json).
• Each editing agent (backend, frontend, tests, migrations, infra,
  docs) gets a per-agent PreToolUse hook in its frontmatter that blocks
  edits outside its allow-list. Lists are opt-in: an agent with no list in
  the manifest is unenforced (prompt-only); an empty list means "edit nothing".

Opt-in / upgrading existing repos: the guard is generated from the keys
present in your .factory.yaml, which is never overwritten by install. A
manifest written before these keys existed gains enforcement only for the keys
it already has. To enforce migrations/infra/docs in an existing repo, add
those keys to .factory.yaml (copy the profile's "Default paths" as a starting
point) and re-run factory install.

Limitations: enforcement covers Write/Edit/MultiEdit/NotebookEdit only —
a builder's Bash access can still write files, so the guard is a guardrail, not
a sandbox.

Enforced path scoping (Kiro CLI and Codex)

The same forbidden: list and per-agent allow-lists are enforced on the other two
platforms — the mechanism differs, the end state doesn't:

• Codex's post-run check catches Bash-written files too (it diffs the working
  tree), so it's slightly stronger on that axis than the pre-edit hooks. It
  self-disables unless node and a git repo are present.
• Kiro IDE stays prompt-only. The IDE advertises a Pre Tool Use hook but its
  on-disk/block contract isn't documented, and declarative allowedPaths is
  reportedly not enforced (kirodotdev/Kiro#7799). Use the CLI agents for enforced
  scoping.
• All three are opt-in per agent in the same way: no allow-list in the manifest
  means that agent is prompt-only.

See Chapter 4 of the book for why it's shaped
this way.

Cross-repo coordination

For features that touch multiple repos (e.g., backend repo emits a contract, frontend repo consumes it), the factory uses a separate contracts repo as the bridge — the place where the user story lives once and where the API contract is exchanged between repos.

Workflow:

# 1. In the backend repo (or wherever the story originates):
factory feature start invoice-reminders
# → scaffolds <contracts-repo>/features/invoice-reminders/story.md + status.yaml
# Edit story.md, then commit + push the contracts repo.

# 2. In the backend repo, pull the (now-committed) story:
factory feature pull invoice-reminders
# → copies story.md into .factory/features/invoice-reminders/
# Then run the chain (Tier 3) referencing that story as input.

# 3. When the backend chain produces an API contract artifact:
factory feature ship invoice-reminders \
  --contract docs/api/invoice-reminders.openapi.yaml \
  --commit $(git rev-parse HEAD)
# → copies the contract into the contracts repo
# → appends this repo to status.yaml's shipped list
# Commit + push the contracts repo.

# 4. In the frontend repo:
factory feature pull invoice-reminders
# → pulls story.md AND api.openapi.yaml into .factory/features/<name>/
# Run the chain with the story + contract as inputs.

# 5. When the frontend ships:
factory feature ship invoice-reminders --commit $(git rev-parse HEAD)
# → marks this repo shipped in status.yaml

On-disk in the contracts repo:

<contracts-repo>/
└── features/
    └── invoice-reminders/
        ├── story.md            # authored once, shared
        ├── api.openapi.yaml    # backend writes; frontend reads
        └── status.yaml         # append-only ship log

See docs/cross-repo.md for the full worked example with two repos and the orchestrator skill flow.

Current scope: The chain consumes a pulled feature bundle — the orchestrator reads story.md and any published api.* contract from .factory/features/<name>/, and the spec-writer/frontend-builder build on that contract. What's still manual is the pull/ship invocation itself: you run factory feature pull / ship by hand around the chain; the orchestrator doesn't auto-pull on start or auto-ship on completion. Auto-pull/ship is a follow-up (see "Build-on-demand" under Status).

License

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.