Integration
Software Factory Codex
By Reusable Software Factory Codex plugin and OpenClaw ACP integration guide.
Configuration Example
{
"name": "software-factory",
"source": {
"source": "local",
"path": "./plugins/software-factory"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}README
# Software Factory Codex Plugin
Reusable Software Factory workflows packaged as Codex skills for OpenClaw ACP orchestration.
## What This Is
This plugin turns the useful role behavior from the Software Factory Intensive repo into Codex skills:
- `$sf-planner`
- `$sf-designer`
- `$sf-coder`
- `$sf-reviewer`
- `$sf-validator`
- `$sf-fix-loop`
- `$sf-pr-writer`
OpenClaw can spawn Codex through ACP/acpx and ask Codex to use one skill per phase. The plugin keeps the role playbooks, templates, and validation rules close to Codex while leaving orchestration to OpenClaw.
## Why It Exists
The original repo teaches a factory pattern through Gas City packs, Beads labels, formulas, and order gates. Those are useful for the curriculum, but OpenClaw already has agent spawning, session management, retries, and routing.
For v1, this plugin migrates the reusable parts:
- role boundaries
- phase gates
- artifact contracts
- review and validation separation
- fix-loop discipline
- final handoff structure
It intentionally does not require Beads, Gas City, or the `actual` CLI.
## Architecture
```text
User / Slack / Discord / CLI
|
v
OpenClaw main agent: Factory Supervisor
|
| ACP/acpx spawn/steer/resume
v
Codex CLI
|
| Codex plugin: software-factory
|
|-- $sf-planner
|-- $sf-designer
|-- $sf-coder
|-- $sf-reviewer
|-- $sf-validator
|-- $sf-fix-loop
|-- $sf-pr-writer
|
v
Repo branch / tests / PR / final report
```
OpenClaw owns phase order, run IDs, retries, and session lifecycle. Codex owns repeatable role behavior and repo work inside each phase.
## Plugin Layout
```text
plugins/software-factory/
.codex-plugin/
plugin.json
README.md
MIGRATION.md
skills/
sf-planner/
sf-designer/
sf-coder/
sf-reviewer/
sf-validator/
sf-fix-loop/
sf-pr-writer/
_shared/
scripts/
init_factory_run.py
validate_skill_pack.py
summarize_factory_run.py
templates/
factory-run/
openclaw/
README.md
factory-supervisor-prompt.md
acp-config.example.jsonc
acp-invocations.md
```
## Installation and Local Usage
For repo-local development, keep the plugin at:
```bash
plugins/software-factory/
```
For a home-local Codex plugin install using the local plugin marketplace convention, copy or symlink it to `~/plugins/software-factory` and register that path from your local marketplace configuration:
```bash
mkdir -p ~/plugins
cp -Rf plugins/software-factory ~/plugins/software-factory
```
Example marketplace entry:
```json
{
"name": "software-factory",
"source": {
"source": "local",
"path": "./plugins/software-factory"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
```
If your Codex build uses the plugin picker, install or enable the local plugin from the plugin UI. The manifest is at `.codex-plugin/plugin.json`.
## Skill List
| Skill | Purpose | Main outputs |
|-------|---------|--------------|
| `$sf-planner` | Convert a vague request into a bounded plan. | `spec.md`, `acceptance-criteria.md`, `implementation-plan.md`, `validation-contract.md` |
| `$sf-designer` | Create or review technical design before coding. | `design.md`, affected files, risks, testing strategy |
| `$sf-coder` | Implement the approved plan. | code changes, tests, `implementation-log.md` |
| `$sf-reviewer` | Review implementation quality before validation. | `review-report.md`, must-fix findings |
| `$sf-validator` | Independently verify the branch. | `validation-report.md`, PASS/FAIL, `fix-brief.md` on fail |
| `$sf-fix-loop` | Repair only failed validation criteria. | targeted code/test changes, updated `implementation-log.md` |
| `$sf-pr-writer` | Prepare final handoff and PR text. | `final-report.md`, PR title/body |
## Factory Run Artifacts
Default folder:
```text
factory-runs/<run-id>/
```
Default files:
```text
manifest.md
user-request.md
spec.md
acceptance-criteria.md
design.md
implementation-plan.md
implementation-log.md
review-report.md
validation-contract.md
validation-report.md
fix-brief.md
final-report.md
```
Create a run:
```bash
python3 plugins/software-factory/scripts/init_factory_run.py \
--run-id 20260425-demo \
--request "Add a small export button to the reports page."
```
Summarize a run:
```bash
python3 plugins/software-factory/scripts/summarize_factory_run.py 20260425-demo
```
Validate the plugin:
```bash
python3 plugins/software-factory/scripts/validate_skill_pack.py
```
## OpenClaw ACP Usage
OpenClaw should spawn Codex with `runtime: "acp"` and `agentId: "codex"`.
Planner:
```json
{
"task": "Use $sf-planner. Create a bounded implementation plan and validation contract for the user request. Write artifacts under factory-runs/<run-id>/. Do not edit production code.",
"runtime": "acp",
"agentId": "codex",
"mode": "run",
"cwd": "/path/to/repo",
"streamTo": "parent"
}
```
Coder:
```json
{
"task": "Use $sf-coder. Implement factory-runs/<run-id>/implementation-plan.md. Run relevant tests and write implementation-log.md.",
"runtime": "acp",
"agentId": "codex",
"mode": "session",
"thread": true,
"cwd": "/path/to/repo",
"label": "factory-run-<run-id>"
}
```
Validator:
```json
{
"task": "Use $sf-validator. Independently validate the current branch against factory-runs/<run-id>/validation-contract.md. Do not fix code. Write validation-report.md with PASS or FAIL and evidence.",
"runtime": "acp",
"agentId": "codex",
"mode": "run",
"cwd": "/path/to/repo",
"streamTo": "parent"
}
```
More examples live in `openclaw/acp-invocations.md`.
## Example Workflow
```text
1. OpenClaw creates run id: 20260425-export-button
2. OpenClaw spawns Codex: Use $sf-planner...
3. OpenClaw spawns Codex: Use $sf-designer...
4. OpenClaw starts persistent Codex session: Use $sf-coder...
5. OpenClaw spawns Codex: Use $sf-reviewer...
6. OpenClaw spawns fresh Codex session: Use $sf-validator...
7. If FAIL: OpenClaw starts $sf-fix-loop and returns to step 6.
8. If PASS: OpenClaw spawns Codex: Use $sf-pr-writer...
```
## What Was Migrated
- Planner scope, acceptance criteria, and decomposition discipline from `packs/planner`.
- Architect/designer implementation-readiness and risk guidance from `packs/architect` and `packs/designer`.
- Builder focus on existing patterns, narrow scope, and test evidence from `packs/builder`.
- Validator quality and evidence discipline from `packs/validator`.
- Reviewer style/security/spec-compliance rubric from `packs/reviewer`.
- Release-gate and improver concepts were collapsed into validation, fix-loop, and PR handoff rather than shipped as separate v1 roles.
- Fired Up Pizza examples informed artifact templates and report shapes.
Full mapping is in `MIGRATION.md`.
## What Was Intentionally Omitted
- Beads label queue and `bd` commands.
- Gas City packs, formulas, orders, mail, hooks, and sessions.
- `actual` CLI ADR sync.
- Custom Codex slash commands such as `/planner`.
- A second task graph or orchestration state machine.
- Continuous deployment automation.
OpenClaw is expected to own orchestration and retries for v1.
## Known Limitations
- The OpenClaw config fragment is an example; adapt it to the deployed OpenClaw config shape.
- The plugin does not enforce phase order by itself. OpenClaw must do that.
- Validation commands are project-specific and must be inferred or supplied in the validation contract.
- The copied source prompt archive includes old Beads/Gas City language for provenance only.
integration
Comments
Sign in to leave a comment