Software Factory 101

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 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 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.

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 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 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 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 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}

Docker Desktop is probably not running, or it has not finished starting. Open Docker Desktop, wait until it reports that the engine is running, then try docker version and docker compose version again.

Check that Docker Desktop is using the WSL 2 backend and that your WSL distro is enabled under Docker Desktop integration settings. If this is your first attempt, run the tutorial from a normal project folder and avoid unusual synced-drive paths until Docker is proven. ^{Docker Desktop}

Confirm the file is named tests/factory.test.mjs and that you are running the command from the project root. Node’s test runner discovers common test filenames, but it cannot find a file that was placed in the wrong folder or given a different extension. ^Node

The token is missing or does not have enough permission. In GitHub Actions, start with the built-in GITHUB_TOKEN and explicit workflow permissions. For local scripts, use a fine-grained PAT with only the repository, issues, and pull-request access required for the script. ^{GitHub PATsGitHub Actions}

Run from the project directory, keep the path simple, and avoid moving the tutorial between cloud-synced folders, network drives, and WSL paths during the first pass. Once the command works once, you can move it into your preferred workspace and debug path-specific behaviour separately.

Run npx wrangler whoami. If it fails locally, authenticate with Wrangler before debugging GitLab CI. In CI, use a Cloudflare API token stored as a masked GitLab CI/CD variable, not an interactive login. ^{WranglerGitLab variables}

Check that CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID exist in Settings > CI/CD > Variables. If a variable is protected, it is available only to protected branches or tags, so an ordinary merge-request branch may not receive it. ^{GitLab variablesProtected environments}

Commit the lockfile produced by your package manager. npm ci is designed for repeatable CI installs and expects the repository to contain a matching lockfile.

Run npx wrangler check locally, confirm wrangler.jsonc is committed, and confirm the GitLab job has the Cloudflare account ID and API token. If production deploys are manual or protected, also check the job’s environment and branch rules. ^{WranglerGitLab CIProtected environments}

Start in the Cloudflare dashboard under Workers & Pages, then open the Worker deployment details. For the first attempt, use the default workers.dev route before adding a custom domain or route. ^Workers

No. A coding assistant mainly improves the act of writing code. A software factory encodes the broader delivery workflow: intake, context, decomposition, execution, testing, approvals, deployment, and learning. That is why sources like XHawk and Alex Op emphasise systems, loops, and workflow integration rather than only autocomplete or chat. ^{XHawkAlex OpCopilot}

No. Start with one orchestrated lane. A single assistant plus a planner-like step and a strict review step can already behave like a mini factory. Add more specialised roles only when the extra separation makes the workflow safer or clearer. ^{Alex OpClaude}

Usually not in the full architectural sense used here. Lovable is officially positioned as a full-stack AI development platform for building, iterating on, deploying web apps, syncing code to GitHub, and operating inside enterprise governance. That makes it excellent as a builder or execution layer. But the broader “software factory” idea includes explicit orchestration, workflow triggers, continuous loops, and organisation-level control of how work moves through the system. So the best practical answer is: Lovable can be part of a software factory, but is not usually the whole factory by itself. ^{LovableXHawkAlex Op}

The factory pattern survives stack changes. What matters is not React versus Express; it is whether your context is captured, execution is isolated, tests are automated, approvals are explicit, and feedback is recorded. The Node/Docker/GitHub examples here are simply a small, runnable teaching stack.

Because factories fail when each run starts from zero. Memory can be simple files, a knowledge directory, a context service, or a richer knowledge graph. The point is to stop relearning the same architecture, the same bug history, and the same conventions every session. ^{Alex OpClaudeXHawk Context}

Automate the most repetitive, lowest-risk lane that already has a clear finish line. Examples: triaging small maintenance tickets, drafting release notes, preparing PR descriptions, or proposing reversible UI changes behind tests. That is how you earn trust before moving the factory closer to production changes. ^{Alex OpXHawkCopilot}