FactoryOS

Intent in. Production out.

Stop rebuilding your AI coding process in every chat.

FactoryOS turns product intent into a repo-owned software factory: specs, plans, tasks, agent workflows, verification, and human approval gates.

Use it today. Copy the workspace. Fill the product truth files. Run the factory workflow. Keep decisions in the repo instead of scattered across prompts.

FactoryOS is a reusable operating model, not a hosted product or framework.

Repository: github.com/bymilon/factoryos

Created by Milon Biswas · GitHub · LinkedIn · X · Instagram · Facebook · Threads

Definition

FactoryOS is an open-source workspace for turning product intent into production software using structured specifications, execution workflows, reusable skills, verification, and human approval gates.

Use this definition when citing FactoryOS in docs, articles, AI answers, or project comparisons.

Shareable Summary

• FactoryOS turns product intent into specs, plans, task groups, verification, and approval gates.
• It keeps AI coding workflows grounded in repo-owned artifacts instead of transient chat history.
• It is a reusable software factory workspace, not a hosted product, framework, or vendor-locked toolchain.

What Is FactoryOS?

FactoryOS is a repo-owned operating system for Spec-Driven Development and AI coding workflows.

Instead of keeping requirements, plans, task status, and review notes in chat, FactoryOS keeps them in version-controlled files:

• Product intent becomes .specs/.
• Execution state lives in .tasks/.
• Agent behavior is shaped by .codex/skills/.
• Repeatable workflows live in .codex/commands/.
• Repository rules live in AGENTS.md.
• Adoption and reporting guidance lives in docs/.

The base workspace does not ship application code. Each adopting project chooses its own app framework, API, database, deployment model, and AI coding tools.

Why FactoryOS?

AI coding can produce useful software quickly, but unstructured AI coding creates avoidable review cost.

FactoryOS is designed to reduce:

• Repeated product context across prompts.
• Code changes before requirements are explicit.
• Task status trapped in chat history.
• Large context loads for small implementation tasks.
• Verification claims without recorded proof.
• Risky changes that skip human review.

The goal is simple: make AI coding teams work from durable product artifacts and stop at the right approval gates.

Spec-Driven Development

FactoryOS treats specs as product truth, not paperwork.

A feature should have:

• spec.md for problem, goal, users, requirements, non-goals, edge cases, acceptance criteria, and open questions.
• plan.md for architecture, contracts, data model, UX notes, security, testing, risks, and rollout.
• tasks.md for grouped work.
• validation.md for required gates and acceptance checks.

Specs make intent reviewable before implementation and make later AI-assisted work easier to audit.

AI Coding Workflows

FactoryOS supports AI coding workflows without binding the project to one assistant.

The included .codex/ directory provides command and skill examples for Codex-style workflows, but the operating model is portable:

• Use structured specs as source context.
• Use task trackers for execution state.
• Assign one bounded worker to one bounded task.
• Run QA after implementation.
• Record verification.
• Ask for approval before risky actions.

The same pattern can be adapted to other AI coding tools that can read and write repository files.

Software Factory

The core workflow is:

Intent -> Spec -> Plan -> Tasks -> Agents -> Verify -> Approval -> Ship

In practice:

1. Capture product intent.
2. Create or update the feature spec.
3. Create a technical plan.
4. Generate a task group.
5. Pick the next unblocked task.
6. Use bounded AI coding work where useful.
7. Run verification.
8. Record progress and risks.
9. Stop for human approval before shipping or expanding scope.

FactoryOS is hands-free execution where appropriate, not brain-free autonomy. Humans still own product decisions, risk acceptance, and release judgment.

Architecture

Product intent
    |
    v
.specs/                Product truth: mission, principles, feature specs, plans, validation
    |
    v
.tasks/                Execution truth: task groups, owners, dependencies, progress, proof
    |
    v
.codex/commands/       Repeatable workflow entrypoints
    |
    v
.codex/skills/         Bounded agent behaviors for planning, execution, QA, and review
    |
    v
Verification           Format, lint, typecheck, tests, build, manual gates
    |
    v
Human approval         Product decisions, risk acceptance, release judgment

Workspace Structure

AGENTS.md                         Repo operating rules for agents
.specs/                           Product truth and feature specifications
.specs/_template/                 Reusable spec, plan, task, and validation templates
.tasks/                           Execution trackers
.tasks/_template/TASKS.md         Task group tracker template
.codex/commands/                  Slash-command workflow prompts
.codex/skills/                    Reusable agent workflow instructions
docs/ADOPTION.md                  Adoption guide
docs/DRY-RUN.md                   Example factory run
docs/PM-STATUS-TEMPLATE.md        PM-facing status template

Key files:

Path	Purpose
.specs/	Product truth: mission, principles, tech stack, roadmap, and feature specs.
.tasks/	Execution truth: priorities, owners, dependencies, verification, and progress logs.
.codex/skills/	Reusable skills for spec writing, planning, task workflows, QA, and factory runs.
.codex/commands/	Command prompts for /factory, /spec, /plan, /group, /next, /qa, /review, and /status.
AGENTS.md	Operating agreement for agents working in the repo.
docs/	Adoption, dry-run, and status-reporting support docs.

Quick Start

Clone or copy the workspace:

git clone https://github.com/bymilon/factoryos.git
cd factoryos

If you are adopting the workspace into an existing product repo, copy these paths instead:

AGENTS.md
.specs/
.tasks/
.codex/
docs/

Fill the product truth files:

.specs/mission.md
.specs/principles.md
.specs/tech-stack.md
.specs/roadmap.md

Run the full factory workflow:

/factory "Add media catalog search with WCAG metadata"

Or run the workflow step by step:

/spec "Add media catalog search with WCAG metadata"
/plan media-catalog-search
/group media-catalog-search
/next media-catalog-search
/qa media-catalog-search
/review media-catalog-search
/status media-catalog-search

The base scaffold has no package.json because it does not prescribe an application stack. Add project commands only in the adopting product repo.

Commands Overview

Command	Purpose
/factory	Run the end-to-end software factory flow from intent through specs, planning, task groups, verification, progress logging, and approval gates.
/spec	Create or update .specs/{feature}/spec.md from product intent.
/plan	Create or update .specs/{feature}/plan.md from an approved spec.
/group	Create or update .tasks/YYYY-MM-DD-{feature}-TASKS.md.
/next	Pick and execute the next unblocked task.
/qa	Verify implementation against .specs/{feature}/validation.md and task acceptance criteria.
/review	Review a feature against its spec, plan, validation, and tracker.
/status	Produce concise status from specs, tasks, progress, risks, and verification evidence.

Default verification gates for adopted projects, when these commands exist:

bun run format:check
bun run lint
bun run typecheck
bun run test
bun run build

Examples

Example input:

/factory "Add media catalog search with WCAG metadata"

Expected dry run:

Intent:
Add media catalog search with WCAG metadata.

Feature:
media-catalog-search

Created/Updated:
- .specs/media-catalog-search/spec.md
- .specs/media-catalog-search/plan.md
- .specs/media-catalog-search/tasks.md
- .specs/media-catalog-search/validation.md
- .tasks/YYYY-MM-DD-media-catalog-search-TASKS.md

Executed:
MCAT-001 - Map current ownership and data sources.

Verification:
No product code changed. Mapping complete.

Approval Gate:
Human review required before implementation.

See docs/DRY-RUN.md for the fuller example.

Traditional AI Coding vs FactoryOS

Traditional AI coding	FactoryOS
Prompt history holds product context.	.specs/ holds product truth.
Tasks are described ad hoc.	.tasks/ tracks status, priority, owners, dependencies, and verification.
Agents may read broad context by default.	Explorer reads first when ownership is unclear; workers get bounded tasks.
Verification can be informal.	QA and validation gates are explicit.
Human review happens after large changes.	Approval gates stop risky transitions early.
Workflows vary by session.	Commands and skills make workflows reusable.

Cost Control

FactoryOS is built around token and review-time discipline.

Working rules:

• Use the cheapest capable model for the task.
• Keep tasks bounded and independently reviewable.
• Use Explorer before loading large or unclear context.
• Use one Worker for one bounded implementation task.
• Run QA after implementation.
• Summarize long logs instead of pasting raw output.
• Stop at approval gates before risky actions.

This keeps AI coding workflows practical for real repositories where context, review time, and mistakes all have cost.

Human Approval Gates

FactoryOS expects human approval before:

• Treating a spec as approved product truth.
• Starting broad implementation.
• Adding dependencies.
• Changing architecture, storage, auth, deployment, or security posture.
• Marking tasks done without verification evidence.
• Shipping user-facing or production-impacting work.

Agents can draft, plan, implement bounded slices, and verify. Humans approve product direction and risk.

Who FactoryOS Is For

FactoryOS is useful for:

• Founders turning product intent into an executable build plan.
• Product engineers who want lightweight structure without enterprise process weight.
• Engineering managers who need status, risks, and verification in repo-owned artifacts.
• AI-native product teams coordinating multiple coding agents.
• Consultants and agencies who need repeatable delivery workflows across client projects.
• OSS maintainers who want contributions to arrive with clearer specs and review evidence.

Sponsor And Creator

FactoryOS was created by Milon Biswas.

Milon is a founder, enterprise AI product engineer, and forward deployed engineer building AI-agent-ready products and reusable software factories for modern product engineering.

Focus areas: AI-native B2B SaaS, agentic AI, ARD, MCP, verification, and human approval systems.

Project repository: github.com/bymilon/factoryos

Support open-source development: buymeacoffee.com/milonspace

Follow:

• GitHub: github.com/bymilon
• LinkedIn: linkedin.com/in/milonai
• X: x.com/milonspace
• Instagram: instagram.com/withmilon
• Facebook: facebook.com/withmilon
• Threads: threads.net/@withmilon

Roadmap

Near-term:

• Improve spec, plan, task, and validation templates.
• Add clearer examples for new and existing product adoption.
• Tighten skill and command documentation.
• Expand dry-run examples.

Later:

• Add reference workflows for common project types.
• Document optional integrations without making them required.
• Add release and verification guidance once the manual workflow is stable.
• Improve contributor examples and maintainer playbooks.

Non-goals:

• Hosted project management.
• Vendor-specific lock-in.
• Framework-specific app boilerplate in the base workspace.
• Fully hands-off production shipping without human approval.

FAQ

Is FactoryOS a framework?

No. FactoryOS is a workspace and operating model. It does not provide runtime libraries, app components, or a hosted platform.

Is FactoryOS tied to Codex?

No. This repository includes Codex-style commands and skills because they are useful examples, but the core model is files, specs, tasks, verification, and approval gates.

Can I use it with Claude Code, Cursor, or other AI coding tools?

Yes, if the tool can work from repository files and follow the workflow. Keep .specs/, .tasks/, and AGENTS.md as the source of truth.

Why not just prompts?

Prompts are useful, but they are weak as long-term project memory. FactoryOS keeps decisions, plans, task status, and verification evidence in the repo where humans and tools can review them.

Why use specs?

Specs reduce ambiguity before implementation starts. They also give future contributors and AI coding agents a stable source of product intent.

Can I use it without AI?

Yes. The specs, task trackers, validation gates, and status templates are useful for human teams too.

Is it safe for production teams?

FactoryOS is designed for production-minded teams, but safety depends on how you adopt it. Keep verification commands real, record evidence, protect secrets, and require human approval for risky changes.

How do I contribute?

Read CONTRIBUTING.md, keep changes scoped, avoid unsupported claims, and make templates clearer or easier to use.

Contributing

Contributions should make FactoryOS clearer, leaner, or easier to adopt.

Start with CONTRIBUTING.md.

License

FactoryOS is released under the MIT License. See LICENSE.