swfactory

A method, five agent skills and a CLI to build software with coding agents (Claude Code and Codex) on local Orca: design and approve a change, implement each task in its own Orca workspace, review it and publish it with evidence, follow everything on a live board, and keep what was learned in the project's memory.

Orca runs the agents and the workspaces; the Factory brings the method and keeps its state in readable files under .factory/. You talk to the agent in natural language (Spanish or English); everything it writes to the repository is in English.

The user guide explains every step in detail: what each skill does, what you decide, task states, notes and recovery, configuration and what to do when something goes wrong.

Requirements

• Linux, macOS or Windows, with Git.
• Orca 1.4.229 or later, running locally (remote hosts are refused), with its orca CLI on your PATH.
• Claude Code and/or Codex, available as agents in Orca.
• uv (it provides Python 3.11+), with ~/.local/bin on your PATH (uv tool update-shell adds it).
• Optional: gh, authenticated, to open pull requests. Without it the Factory pushes the task branch and leaves the PR to you.

Install

Once per machine, with uv (recommended):

uv tool install swfactory   # the `swfactory` command, in ~/.local/bin
swfactory install-skill     # copies /factory-init to ~/.claude/skills/ and ~/.agents/skills/

It is a regular Python package, so pipx install swfactory or pip install swfactory (inside a virtual environment) work too. The skills call swfactory, so it has to be installed, not only run once. To try it without installing: uvx swfactory --version.

Upgrade: uv tool upgrade swfactory (or pipx upgrade swfactory), then swfactory install-skill, then /factory-init in each project to update its skills.

The five skills

The skills call the swfactory CLI for everything that must be exact. You do not need to use it, but you can: swfactory --help lists every command.

Five-minute walkthrough

In a Claude Code (or Codex) terminal in Orca, at the root of your repository:

1. Prepare the repo.

   /factory-init
   

   Read the plan and confirm it. It registers the repo in Orca with its base branch, installs the five skills in the repo, writes AGENTS.md, docs/ and .factory/config.toml with your test, lint and typecheck commands, and leaves everything uncommitted. Review the diff and commit it on the base branch (or ask the agent to).

2. Design a change.

   /factory-design add weekly recurrence to bookings
   

   Say OK to the outline; it writes .factory/changes/CHG-0001/design.md and tasks.yaml. Read it and approve it:

   apruebo CHG-0001
   

   Accept the permission prompt. "vale" or "ok" is not an approval.

3. Implement a task.

   /factory-implement CHG-0001-01 con claude, revisa claude
   

   ("with claude, review claude": the lead agent and the conformance reviewer.) A new workspace appears in Orca's sidebar with its agent; your main session is free. Open the workspace to watch it or talk to the agent.

4. Follow it.

   /factory-status
   /factory-board
   

   You see each task's state, acceptance criteria verified, reviews and the next step. The board is a live kanban in an Orca tab (and in your browser, at the address swfactory board status prints) with every agent and subagent running in each task. When the task is done, the lead offers to push the branch and open the PR.

5. Integrate. Review the PR and merge it yourself; the Factory never merges. Tasks that depend on it move from pending to ready once it is on the base branch.

Good to know

• Approving or rejecting a design always needs your explicit message. Claude Code and Codex also ask for permission before running it (.claude/settings.json and .codex/rules/factory.rules; Codex reads project rules only if you trust the project in Codex).
• A task is done only when every acceptance criterion has evidence, the checks pass and the required reviews passed on the final commit.
• The Factory only pushes the task branch: no force push, merge or branch deletion.
• Orca may launch Claude with --dangerously-skip-permissions (its agentDefaultArgs setting). The approval rule still asks in that mode. swfactory doctor warns when Claude's own settings skip permission prompts (bypassPermissions); it cannot read Orca's setting.
• Orca does not say whether the agent inside a terminal is still running: /factory-status marks a task interrupted only when its terminal is closed. An agent that exited in an open terminal looks alive; more than 10 minutes without a checkpoint only gives a warning.
• Orca does not report the model an agent used; the Factory records the --model it passed.
• Platforms: verified end to end on Linux with Claude Code and Orca 1.4.229. The CI runs every test on Linux, macOS and Windows; macOS and Windows have not been used with a real Orca yet. On Windows you can also work inside WSL, which behaves like Linux.
• Codex (skills in .agents/skills/, the approval rule, reviews) is implemented but has not been checked on a real machine yet.
• If orca or gh is not on your PATH, point SWFACTORY_ORCA or SWFACTORY_GH at the program (a path, or a JSON list such as ["C:\\Orca\\resources\\bin\\orca.exe"]).

Development

git clone https://github.com/MarianodelRio/swfactory && cd swfactory
uv sync                 # create the environment with dev tools
uv run pytest -q        # tests
uv run ruff check .     # lint
uv run mypy src         # typecheck
uv tool install .       # install the `swfactory` command from this checkout

Changes are listed in CHANGELOG.md; how to publish a version is in docs/releasing.md. License: MIT.