Software Factory 101

Executive summary

A software factory is not just “AI that helps write code”. It is a repeatable system for turning work requests into tested changes, pull requests, releases, or deployments while capturing the context and lessons that future runs need. The architecture below maps that idea as a continuous AI-native loop: human intent enters, workflow tools and project context guide the work, agents plan and execute inside controlled environments, checks and human review decide what can move forward, deployment paths hand off approved output, and feedback loops retain lessons for the next run. The “factory” part matters because work moves through structured stages, outputs are standardised, quality control exists, knowledge is retained, and throughput can improve over time. ^{GreenfieldXHawkAlex OpMCP}

A software factory is easiest to understand as a closed loop. A person or system asks for work, the factory loads the project context, agents plan and make the change in a controlled environment, automated checks and human review decide whether it is safe, approved output moves to a pull request, release, or deployment, and the result is recorded so the next run starts smarter. That loop is the key difference between a one-off coding prompt and a repeatable operating system for software delivery.

Human intent

Human intent is the intake point. In the diagram it includes engineers, PMs, designers, APIs, agents, and incidents. In plain English, intent is the problem statement that starts the run: "Add a watchlist page", "Investigate today's error spike", "Implement the approved design", or "Turn this bug report into a fix". ^{XHawkAlex Op}

Beginner's test: if you cannot write the request clearly enough for another person to act on it, you are not ready to hand it to a factory either. Good intake is boringly explicit: scope, constraints, protected areas, and what "done" means.

{
  "task_id": "task-001",
  "intent": "Add a watchlist page",
  "acceptance_criteria": [
    "Users can save favourite stocks locally",
    "Saved stocks remain after page refresh",
    "A PR summary is generated"
  ],
  "constraints": [
    "Do not change authentication",
    "Keep the change reversible"
  ],
  "context_paths": [
    "docs/product/watchlist.md",
    "src/routes",
    "tests"
  ]
}

Telemetry & logs

Telemetry and logs are the factory's stream of operational evidence: logs, metrics, traces, build output, customer complaints, analytics, failed tests, and incident signals. In the diagram, these signals arrive 24x7. XHawk describes live signals such as logs and metrics as context for agents; Alex Op describes support feedback, analytics dashboards, and error logs feeding the work backlog. The public XHawk material does not specify an exact telemetry schema or storage architecture, so those details are intentionally left unspecified here. ^{XHawkAlex Op}

For a beginner, telemetry answers three simple questions: what is happening, what broke, and did the last change help or hurt? Without telemetry, the factory can still build, but it cannot learn intelligently from real outcomes. With telemetry, production itself becomes an input back into development.

The dotted loop in the diagram is the same idea seen over time: completed work, production signals, and incident lessons feed the next run instead of being forgotten. ^{XHawk ContextAlex Op}

{
  "timestamp": "2026-05-24T09:15:00Z",
  "service": "web",
  "signal": "error-rate-spike",
  "severity": "warning",
  "details": {
    "route": "/api/watchlist",
    "count_last_5m": 42
  }
}

Workflow integration

Workflow integration is the adoption layer. The diagram names Slack, GitHub, Linear, and Jira; the broader pattern includes chat, issue trackers, CI failures, schedules, webhooks, incident systems, and cloud infrastructure events. GitHub Copilot's cloud-agent documentation shows the same pattern in product form: sessions can start from GitHub surfaces and integrated tools, with the issue or thread context passed into the run. ^{XHawkGitHub Copilot}

In practice, workflow integration matters because it removes "copy this from tool A into tool B" busywork. A factory should meet the team where the work already begins, then move the right context into the factory runtime.

Context layer

The context layer is the factory's memory and grounding system. It contains the relatively stable project knowledge that AI agents need before they can work effectively. This includes the codebase structure, feature specifications, architecture decisions, internal conventions, domain terminology, protected areas of the system, and deployment rules.

The key idea is that context provides long-lived understanding about how the project operates. Without this grounding, AI agents behave like generic assistants with no real understanding of the application they are modifying.

Telemetry and logs, covered above, are different from context. Telemetry is live operational evidence about what is happening right now inside the system.

XHawk describes context broadly as specs, past decisions, tickets, and live signals. In practice, specs, decisions, conventions, and architecture documents belong to the actual context layer. Live signals belong to the telemetry and logs layer. After review and validation, important operational learnings from telemetry may later be promoted into long-term context. ^XHawk

Platforms such as XHawk, Lovable, and Claude Code describe variations of the same core idea: workspace knowledge, project memory, codebase awareness, and context management. The shared principle is that context transforms a generic AI model into a project-specific engineering system. ^{XHawkLovableClaude}

Beginner's version: write down what your future self should not have to rediscover. Without context, agents hallucinate more easily, workflows become inconsistent, architecture drifts, and repeated mistakes return. With context, the system behaves more like an experienced engineer who already understands the project.

{
  "project_name": "Watchlist demo",
  "rules": [
    "Prefer small reversible changes",
    "Use feature flags for risky UI work"
  ],
  "domain_terms": {
    "watchlist": "A saved list of favourite stocks",
    "ticker": "Market symbol such as AAPL"
  },
  "protected_areas": [
    "authentication",
    "billing",
    "production secrets"
  ],
  "done_definition": [
    "Tests pass",
    "PR summary exists"
  ]
}

The software factory core

The software factory core is where the system turns intent and context into controlled work. In this simplified map, the core has two jobs: orchestrate specialised agents, and run their work inside a sandboxed execution environment. The orchestrator is the control system of the factory: it decides when tasks start, which agents execute, which tools are available, which approvals are required, and when workflows stop or retry. That is what separates a repeatable factory from disconnected AI tools or a one-off chat prompt. ^{XHawkClaudeReplit}

A software factory is therefore not just AI, not just coding, not just CI/CD, and not just DevOps. It is the combination of orchestration, context, execution, governance, memory, deployment, and learning into one operating system for repeatable software change.

1. Multi-agent orchestration

Multi-agent orchestration means coordinating specialised roles instead of expecting one agent to do everything well. XHawk names the planner, executor, and reviewer trio directly. Claude Code and Replit use different product language, but the runtime logic is similar: gather context, make a plan, act, verify, and repeat. ^{XHawkClaudeReplit}

The beginner lesson is important: splitting thinking, doing, and checking often makes a system easier to steer, audit, and improve. Smaller focused roles are easier to govern, failures are easier to diagnose, and automation becomes safer because each role has a clearer job.

1a. Planner

The planner turns intent and context into ordered work. It identifies affected systems, determines the implementation approach, breaks the job into steps, names acceptance criteria, calls out constraints, and marks risky areas before anything changes.

1b. Reviewer

The reviewer validates output against the plan, tests, linting, architecture rules, requirements, and likely failure modes. In a small factory this can be a strict review checklist; in a larger one it can be a specialised agent plus automated checks and human approval.

1c. Executor

The executor performs the work inside the allowed environment: writing code, editing files, running commands, updating tests, creating artifacts, recording outputs, and reporting what happened. The executor should not silently widen scope; it should work inside the plan, constraints, and sandbox.

2. Sandboxed execution

Sandboxed execution is the safety boundary for autonomous work. Agents should operate inside isolated environments rather than directly against production systems. Typical implementations include Docker containers, cloud devboxes, ephemeral virtual machines, isolated Git branches, restricted filesystem access, and restricted network access. XHawk describes isolated repo copies and cloud sandboxes or devboxes; GitHub Copilot's cloud agent uses an ephemeral development environment powered by GitHub Actions; Claude Code's sandboxing guidance is explicit that useful isolation needs both filesystem and network boundaries. Docker Compose is the most approachable beginner tool for modelling a repeatable isolated environment because it defines services, networks, and volumes in one YAML file. ^{XHawkGitHub CopilotClaudeDocker}

Safe autonomy means giving the system enough room to work without giving it uncontrolled access to production systems, secrets, or the whole machine. Devbox environments are one practical form of that boundary. The key beginner insight is blunt but useful: autonomy without isolation is dangerous, because autonomous systems will eventually make mistakes and the sandbox limits the blast radius.

Crucial beginner warning: Node's vm module is not a security mechanism for running untrusted code. If you need isolation, use real process, VM, or container boundaries instead. ^Node

Curated capabilities

Curated capabilities are the small approved toolbox the factory can use. In the diagram that toolbox includes APIs, tests, MCP, and docs; in practice it can also include approved databases, documentation systems, deployment interfaces, and other tightly scoped services. XHawk frames this as a curated capability set where tool quality matters more than tool quantity. MCP provides a standard way for servers to expose tools, resources, and prompts; GitHub Copilot also uses MCP to extend Copilot with other systems; Claude Code's hooks and subagents show how runtime actions can be attached to lifecycle points. ^{XHawkMCPCopilotClaude}

The beginner translation is simple: do not give the agent a random pile of tools. A good factory minimises unnecessary capabilities, tightly scopes permissions, and standardises interfaces. Start with file read and write inside the sandbox, test execution, repository operations, approved documentation access, and one path for opening a pull request or writing a review summary. Fewer, safer, higher-quality tools beat unlimited access.

Guardrails + human review

Guardrails and human review are the control layer. In the diagram this contains tests and PR generation, with review before production. Guardrails include automated tests, lint checks, security scans, branch protections, approval gates, deployment policies, permission systems, and human review requirements. XHawk describes agents generating PRs and running tests while humans define requirements and approve outputs. GitHub's Copilot guardrails guidance points to policy planning, branch rulesets, permissions, protected configuration ownership, and secure runner choices. OWASP's AI Agent Security guidance adds agent-specific controls such as validating tool use, limiting retries and tokens, and testing for approval bypass, privilege escalation, memory poisoning, and data exfiltration. ^{XHawkCopilotGitHub rulesOWASP Agent}

In plain English, guardrails answer three questions: what may happen automatically, what requires approval, and what is forbidden entirely? Good factories automate aggressively, but constrain aggressively too. Humans increasingly focus on intent, product judgement, risk management, approval of sensitive changes, architecture direction, and exception handling rather than only manual coding.

Production systems

Production systems are where approved work lands: applications, services, databases, infrastructure, scheduled jobs, and deployments that real users depend on. The diagram labels this simply as deployment. GitHub Actions is a straightforward primary-source example of the last mile: workflows live in .github/workflows, respond to repository events, and can run CI, deployments, and automations. ^{GitHub ActionsXHawk}

A beginner does not need a fancy deployment stack to understand this box. If a change can be tested, approved, and released through a repeatable path, you have the seed of the production end of the factory.

Every run should generate reusable knowledge: successful fixes, failed approaches, architecture decisions, incident resolutions, deployment lessons, and operational learnings. XHawk describes tasks being audited and remembered, with sessions, decisions, and context becoming indexed knowledge; Claude Code, Lovable, and similar tools expose memory-like runtime pieces for continuity. Public XHawk pages describe indexed knowledge and snapshots, but do not specify the exact persistence implementation. Memory is how the factory compounds. ^{XHawk ContextClaudeLovable}

How a software factory operates in practice

In practice, the factory works like a controlled loop. A task arrives from a human, from a schedule, or from another system. The factory loads the right context, breaks the job into steps, runs the change in an isolated environment, checks the result, asks for approval where needed, and then stores the outcome as new reusable knowledge. Modern agent products increasingly expose the building blocks for this pattern: subagents, hooks, schedules, custom agents, MCP connectors, cloud agents, version control, background tasks, and security policies. ^{XHawkAlex OpClaudeCopilotReplitLovable}

Choose your end-to-end software factory path

A path is not one tool. It is a complete loop: task in, context loaded, work produced, checks run, human review, deployment or handoff, and lessons recorded. Pick based on where your work already lives and how much setup you can tolerate.

Tool shopping list

Start with the smallest stack that proves the loop. You can add more capable agents later; the first win is a repeatable lane with context, isolation, checks, and review.

Day 0: install and verify

Before writing factory code, prove the command line can see the runtime, version control, and sandbox tools.

node --version    # expect v24.x
git --version
docker --version
docker compose version

Windows note: Docker Desktop on Windows should use the WSL 2 backend. If Docker commands fail, check WSL 2 and Docker Desktop distro integration before debugging the tutorial.

End-to-end setup steps by path

Each path below follows the same factory loop: intake, context, execution, checks, review, deployment or handoff, and memory.

Path navigation

## Task
Add a watchlist page.

## Acceptance criteria
- The page has a clear empty state.
- The change is small and reversible.
- Automated checks pass before merge.

## Context
- Avoid auth and billing files.
- Write a short PR summary explaining the change.

# Project context

Goal: Build small, reviewable product changes.

Rules:
- Prefer small pull requests.
- Do not edit auth, secrets, billing, or deployment files without explicit approval.
- Every factory task starts from a GitHub issue labelled `factory`.
- Every pull request needs automated checks and a human review.

Definition of done:
- Acceptance criteria are met.
- GitHub Actions pass.
- The PR records what changed and what the next run should remember.

name: factory-checks

on:
  pull_request:
  workflow_dispatch:

jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
      - run: npm ci
      - run: npm test

# Require a human owner for factory and deployment controls.
/factory/ @your-github-user
/.github/ @your-github-user
/infra/ @your-github-user

Path 3: GitLab + Cloudflare Workers end to end

This path uses GitLab as the workflow and review system, and Cloudflare Workers as the deploy target. The complete loop is: GitLab issue → merge request → GitLab CI checks → staging Worker deploy → manual production deploy → memory note. ^{GitLab CIMerge requestsVariablesWorkersWrangler}

Step 0: What you need

A GitLab account, a GitLab project, a Cloudflare account, Node.js, npm, Git, and Wrangler. First prove the CLI tools work.

node --version
git --version
npm --version
npx wrangler --version
npx wrangler whoami

Step 1: Create the workspace

Create a GitLab project, then create a tiny Cloudflare Worker locally and push the project to GitLab. Do not add factory automation until this basic project runs. ^{WorkersWrangler}

npm create cloudflare@latest software-factory-worker
cd software-factory-worker
npm run dev

Step 2: Define intake

In GitLab, create a label named factory. Create the first issue with a small task, acceptance criteria, and a note that production deploys require human approval. ^GitLab MRs

Step 3: Add context

Add factory/context/project-context.md or factory/context/project-context.json with project purpose, protected files, deployment rules, and definition of done. This is what keeps the factory from guessing.

Step 4: Add execution

For the first run, make one tiny Worker change on a branch and open a merge request. The Worker handler below is enough to prove the execution target.

export default {
  async fetch(request, env, ctx) {
    return Response.json({
      ok: true,
      path: new URL(request.url).pathname,
      factoryStage: "staging"
    });
  }
};

Step 5: Add checks

Keep non-secret Worker configuration in wrangler.jsonc, then use wrangler check, tests, and merge request pipelines as the quality gate. Store secrets with Cloudflare secrets or GitLab CI/CD variables, not in source code. ^{WranglerSecretsGitLab variables}

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "software-factory-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-23",
  "compatibility_flags": ["nodejs_compat"],
  "observability": {
    "enabled": true
  },
  "env": {
    "staging": {
      "name": "software-factory-worker-staging"
    },
    "production": {
      "name": "software-factory-worker"
    }
  }
}

Step 6: Add review

Open a GitLab merge request from your branch. The MR should link the issue, list acceptance criteria, show the pipeline result, and name the staging Worker URL once deployed. ^GitLab MRs

Step 7: Deploy or hand off

Deploy once by hand to prove Cloudflare is configured, then let GitLab CI repeat the deploy. Confirm staging before any manual production deploy. ^{Workers CI/CDGitLab CIProtected environments}

npx wrangler check
npx wrangler types
npx wrangler deploy --dry-run
npx wrangler deploy --env staging

In GitLab, add masked CI/CD variables for CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Protect production variables if production deploys only run from protected branches or tags. ^{GitLab variablesProtected environmentsCloudflare secrets}

image: node:24

stages:
  - test
  - deploy

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - .npm/

before_script:
  - npm ci --cache .npm --prefer-offline

test:
  stage: test
  script:
    - npm test
    - npx wrangler check
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'

deploy_staging:
  stage: deploy
  script:
    - npx wrangler deploy --env staging
  environment:
    name: staging
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

deploy_production:
  stage: deploy
  script:
    - npx wrangler deploy --env production
  environment:
    name: production
  when: manual
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

Step 8: Record memory

Add a short note to the merge request or factory/runs/<issue-number>.md: issue link, MR link, staging URL, production deploy decision, what failed, and what the next factory run should remember.

First safe upgrade

After the manual issue-to-MR-to-staging loop works, add a tiny issue importer or MR-summary generator. Keep production deploy manual until checks and review feel boring.

Path 4: DIY local factory end to end

You are here if you want to understand the factory mechanics directly before trusting a hosted product. The mini factory below is intentionally small and vendor-neutral. It uses Node.js built-ins for files, subprocesses, tests, and assertions; Docker Compose for isolation; and optional GitHub adapters only after the local loop works. The first version is deliberately conservative: instead of letting an agent rewrite your whole application immediately, it proves the workflow by planning work, producing a proposal artefact, running checks, and preparing a review summary. Once you trust the loop, you can swap in an actual coding model. ^{NodeDockerClaudeOpenAI Agents}

Step 0: What you need

Node.js, Git, Docker Desktop/Compose, a terminal, and a small practice project. Claude Code or another coding agent comes later, after the deterministic loop is test-gated.

Step 1: Create the workspace

Create the folder structure below: factory/context, factory/tasks, factory/agents, factory/runs, tests, and optional integration folders.

Step 2: Define intake

Start with factory/tasks/queue.json. A local queue is beginner-friendly because it avoids API tokens while teaching the same intake pattern.

Step 3: Add context

Add factory/context/project-context.json with project goal, protected files, coding rules, and definition of done.

Step 4: Add execution

Add planner, executor, and reviewer modules. The executor writes a proposal first; direct code edits are a later upgrade.

Step 5: Add checks

Add Node’s built-in test runner and make every factory run execute tests before a task is marked ready.

Step 6: Add review

Generate a review summary or PR body from the run. A human should be able to inspect what happened without reading logs line by line.

Step 7: Deploy or hand off

For the local DIY starter, the handoff is a proposal and review summary. Add GitHub, GitLab, or deployment automation only after this local handoff is reliable.

Step 8: Record memory

Write run artefacts into factory/runs/: proposal, review result, test result, and what the next run should remember.

First safe upgrade

Replace the deterministic planner or proposal-only executor with Claude Code, OpenAI Agents SDK, or another coding agent only after the local loop is observable, sandboxed, and test-gated.

Detailed build: first local automation lane

The recommended beginner lane is deliberately narrow: a local queued task becomes a plan, the factory produces a proposal and review summary, tests run, and a human decides what to do next. That is enough to be a factory because the work is repeatable, inspectable, isolated, and blocked by checks.

.
├─ package.json
├─ docker-compose.yml
├─ factory/
│  ├─ context/
│  │  └─ project-context.json
│  ├─ tasks/
│  │  └─ queue.json
│  ├─ runs/
│  ├─ lib/
│  │  └─ run-command.mjs
│  ├─ agents/
│  │  ├─ planner.mjs
│  │  ├─ executor.mjs
│  │  └─ reviewer.mjs
│  └─ orchestrator.mjs
├─ scripts/
│  └─ open-pr.mjs
├─ src/
│  └─ README.md
├─ tests/
│  └─ factory.test.mjs
└─ .github/
   └─ workflows/
      └─ mini-factory.yml

{
  "name": "mini-software-factory",
  "private": true,
  "type": "module",
  "scripts": {
    "factory": "node factory/orchestrator.mjs",
    "test": "node --test"
  }
}

{
  "projectName": "Watchlist demo",
  "goal": "A small web app that lets users save and view favourite stocks.",
  "protectedFiles": [
    "src/auth/",
    "infra/production/"
  ],
  "codingRules": [
    "Prefer small, reversible changes.",
    "Do not edit protected files without human approval.",
    "Record every proposed change in factory/runs/<task-id>/proposal.md."
  ],
  "definitionOfDone": [
    "Task has a clear plan.",
    "Automated checks run.",
    "A PR summary is ready for review."
  ]
}

[
  {
    "id": "task-001",
    "title": "Add a watchlist page",
    "status": "pending",
    "files": ["src/README.md"],
    "acceptanceCriteria": [
      "The change is described clearly.",
      "The review step runs tests.",
      "A PR body is generated."
    ]
  }
]

import { spawn } from "node:child_process";

export function runCommand(command, args = [], options = {}) {
  return new Promise((resolve, reject) => {
    const child = spawn(command, args, {
      cwd: options.cwd ?? process.cwd(),
      env: { ...process.env, ...(options.env ?? {}) },
      shell: false
    });

    let stdout = "";
    let stderr = "";

    child.stdout.on("data", chunk => { stdout += chunk.toString(); });
    child.stderr.on("data", chunk => { stderr += chunk.toString(); });
    child.on("error", reject);
    child.on("close", exitCode => {
      resolve({ command, args, exitCode, stdout, stderr });
    });
  });
}

function slugify(value) {
  return value
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-|-$/g, "")
    .slice(0, 40);
}

export async function planTask(task, context) {
  return {
    taskId: task.id,
    title: task.title,
    branch: `factory/${task.id}-${slugify(task.title)}`,
    filesToInspect: task.files ?? [],
    acceptanceCriteria: task.acceptanceCriteria ?? [],
    protectedFiles: context.protectedFiles ?? [],
    steps: [
      "Load project context and task details",
      "Inspect the files listed for the task",
      "Draft a reversible change proposal",
      "Run automated checks",
      "Prepare a pull request summary"
    ]
  };
}

import { mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { runCommand } from "../lib/run-command.mjs";

export async function executePlan(plan) {
  const runDir = join("factory", "runs", plan.taskId);
  await mkdir(runDir, { recursive: true });

  const proposalFile = join(runDir, "proposal.md");
  const proposalMarkdown = [
    `# ${plan.title}`,
    "",
    `**Suggested branch:** \`${plan.branch}\``,
    "",
    "## Files to inspect",
    ...(plan.filesToInspect.length ? plan.filesToInspect.map(file => `- ${file}`) : ["- No files specified"]),
    "",
    "## Acceptance criteria",
    ...(plan.acceptanceCriteria.length ? plan.acceptanceCriteria.map(item => `- ${item}`) : ["- None provided"]),
    "",
    "## Planned steps",
    ...plan.steps.map(step => `- ${step}`)
  ].join("\n");

  await writeFile(proposalFile, proposalMarkdown, "utf8");

  const smoke = await runCommand(process.execPath, ["--version"]);

  return {
    runDir,
    proposalFile,
    smoke
  };
}

import { runCommand } from "../lib/run-command.mjs";

export async function reviewRun() {
  const tests = await runCommand(process.execPath, ["--test"]);

  return {
    passed: tests.exitCode === 0,
    summary: tests.exitCode === 0 ? "All automated checks passed." : "Automated checks failed.",
    tests
  };
}

import { readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { planTask } from "./agents/planner.mjs";
import { executePlan } from "./agents/executor.mjs";
import { reviewRun } from "./agents/reviewer.mjs";

async function readJson(path) {
  return JSON.parse(await readFile(path, "utf8"));
}

async function writeJson(path, value) {
  await writeFile(path, JSON.stringify(value, null, 2) + "\n", "utf8");
}

async function main() {
  const contextPath = join("factory", "context", "project-context.json");
  const queuePath = join("factory", "tasks", "queue.json");

  const context = await readJson(contextPath);
  const queue = await readJson(queuePath);

  const nextTask = queue.find(task => task.status === "pending");

  if (!nextTask) {
    console.log("No pending tasks.");
    return;
  }

  const plan = await planTask(nextTask, context);
  const execution = await executePlan(plan);
  const review = await reviewRun();

  const prBodyPath = join(execution.runDir, "pr-body.md");
  const prBody = [
    `## ${plan.title}`,
    "",
    `**Branch:** \`${plan.branch}\``,
    "",
    "### Acceptance criteria",
    ...plan.acceptanceCriteria.map(item => `- ${item}`),
    "",
    "### Review result",
    `- ${review.summary}`,
    "",
    "### Proposal file",
    `- ${execution.proposalFile}`
  ].join("\n");

  await writeFile(prBodyPath, prBody, "utf8");

  nextTask.status = review.passed ? "ready-for-pr" : "failed-review";
  nextTask.lastRun = {
    proposalFile: execution.proposalFile,
    prBodyPath,
    smokeExitCode: execution.smoke.exitCode,
    testExitCode: review.tests.exitCode
  };

  await writeJson(queuePath, queue);

  console.log(JSON.stringify({
    task: nextTask.id,
    status: nextTask.status,
    proposalFile: execution.proposalFile,
    prBodyPath
  }, null, 2));
}

main().catch(error => {
  console.error(error);
  process.exit(1);
});

import test from "node:test";
import assert from "node:assert/strict";
import { planTask } from "../factory/agents/planner.mjs";

test("planner creates a branch name and keeps acceptance criteria", async () => {
  const task = {
    id: "task-001",
    title: "Add a watchlist page",
    acceptanceCriteria: ["PR summary exists"]
  };

  const context = { protectedFiles: ["src/auth/"] };
  const plan = await planTask(task, context);

  assert.match(plan.branch, /^factory\/task-001-/);
  assert.deepEqual(plan.acceptanceCriteria, ["PR summary exists"]);
  assert.ok(plan.steps.length > 0);
});

npm test
npm run factory

services:
  factory:
    image: node:24-alpine
    working_dir: /workspace
    volumes:
      - ./:/workspace
    command: ["sh", "-lc", "node --test && node factory/orchestrator.mjs"]

docker compose run --rm factory

name: mini-factory

on:
  pull_request:
  workflow_dispatch:
  schedule:
    - cron: "0 2 * * 1-5"

jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
      - run: node --test

  factory:
    if: github.event_name != 'pull_request'
    needs: checks
    permissions:
      contents: read
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
      - run: node factory/orchestrator.mjs

import { readFile } from "node:fs/promises";

const [owner, repo] = process.env.GITHUB_REPOSITORY.split("/");
const title = process.env.PR_TITLE;
const head = process.env.PR_HEAD;
const base = process.env.PR_BASE ?? "main";
const body = await readFile(process.env.PR_BODY_PATH, "utf8");

const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls`, {
  method: "POST",
  headers: {
    "Accept": "application/vnd.github+json",
    "Authorization": `Bearer ${process.env.GITHUB_TOKEN}`,
    "X-GitHub-Api-Version": "2022-11-28"
  },
  body: JSON.stringify({ title, head, base, body })
});

if (!response.ok) {
  throw new Error(await response.text());
}

const pr = await response.json();
console.log(`Created PR #${pr.number}: ${pr.html_url}`);

import { writeFile } from "node:fs/promises";

const [owner, repo] = process.env.GITHUB_REPOSITORY.split("/");
const url = new URL(`https://api.github.com/repos/${owner}/${repo}/issues`);
url.searchParams.set("state", "open");
url.searchParams.set("labels", "factory");

const response = await fetch(url, {
  headers: {
    "Accept": "application/vnd.github+json",
    "Authorization": `Bearer ${process.env.GITHUB_TOKEN}`,
    "X-GitHub-Api-Version": "2022-11-28"
  }
});

if (!response.ok) {
  throw new Error(await response.text());
}

const issues = await response.json();
const queue = issues
  .filter(issue => !issue.pull_request)
  .map(issue => ({
    id: `issue-${issue.number}`,
    title: issue.title,
    status: "pending",
    files: [],
    acceptanceCriteria: [
      "The issue has been reviewed.",
      "A plan or pull request summary is generated.",
      "Automated checks run before merge."
    ],
    source: issue.html_url
  }));

await writeFile("factory/tasks/queue.json", JSON.stringify(queue, null, 2) + "\n", "utf8");
console.log(`Imported ${queue.length} factory issues.`);

Compare the tool landscape and choose the right layer

The easiest way to get confused is to treat every AI coding product as the same thing. They are not. Some are builders, some are IDE assistants, some are runtime platforms, and some are closer to an actual “factory” control plane. The table below uses each product’s official positioning and features, then adds a practical interpretation of the role it can play.

The path section compares end-to-end setups; this table compares individual tools that may appear inside those paths.

Important note: the “best mental model” column is an interpretation based on product documentation and the software-factory definitions above. It is deliberately analytical, especially for the earlier question “Is Lovable a software factory?” The short answer remains: Lovable is usually better understood as a powerful builder inside a broader factory, not the whole factory. ^{LovableXHawkAlex Op}

Security, ethics, and guardrails

The most common beginner mistake is not “using too little AI”; it is giving the agent more authority than the controls deserve. OWASP’s LLM Top 10 specifically calls out prompt injection, insecure output handling, training-data poisoning, model denial of service, and supply-chain vulnerabilities. The OWASP AI Agent Security guidance then gets very practical: validate outputs before execution, prefer structured outputs, set scope and rate limits, and filter sensitive outputs. NIST’s AI Risk Management Framework adds the broader governance frame: manage risk to people, organisations, and society, not just to the codebase. ^{OWASP LLMOWASP AgentNIST}

Concrete examples from the official docs include Claude Code permission modes and sandboxing, GitHub’s cloud-agent guardrails, CODEOWNERS, rulesets, secret handling, Lovable’s security scans and training-data controls, and Docker isolation primitives. ^{ClaudeCopilotGitHub rulesLovableDocker}

Automation ladder: what to automate when

Treat sensitive automation as a ladder, not a wall. Each rung earns trust for the next one.

Checklist, FAQs, and next reads

Implementation checklist

Tick these off as you build. Progress is stored locally in your browser.

Checklist derived from the factory model, agent-runtime controls, GitHub CI patterns, and OWASP/NIST safety guidance. ^{XHawkClaudeCopilotGitHub ActionsGitHub rulesOWASP AgentNIST}

Visual regression checklist

Run these checks after any layout or content edit. A static page should not ship obvious overlaps.

Troubleshooting the first run

FAQs

Next reads and primary resources

Read the sources below in roughly this order: first the classic paper for the underlying idea, then Alex Op and XHawk for the modern AI-native interpretation, then official docs for the tooling layers you might combine.

If you only take one next step after reading this page, make it this: build one narrow, reviewable automation lane. Do not try to industrialise your whole engineering org in one jump. Start with one loop you can trust, then widen the conveyor.