software factory

Open source / Pre-release · v0.1.0 target

Your whole software factory.

From an idea to continuously shipped improvements. Plan with BMad epics and stories; agents build, test, review, ship and learn from feedback—then start the next eligible cycle.

Claude Code · Cursor · Codex   /   MIT licensed

SF / DELIVERY SYSTEM01 — ILLUSTRATIVE
Software Factory system overviewThe orchestrator spans grounded planning, concurrent story work, independent proof and single-owner delivery. Per-story failures return to repair or replanning. Authorized feedback returns to triage. Human decisions branch from any phase when risk, affected assets or agreed autonomy require them. Decide, then resume the affected step.
Illustrative workflow. Your active coding host runs the loop with its available capabilities. Each proven story can advance while others repair. You set scope and autonomy.
11 skills for the delivery loop
11 roles, staffed as needed
1 project, one source of status

Start with your own project

A small first lap.

Have a trusted local checkout? Choose your host, then copy the setup prompt into your agent. It starts with a dry run and grounded onboarding.

Compare installation routes
python3 -I -B install.py install --host claude-code --skip-bmad --project "<this-project>" --profile full --dry-run

Preview from the pack checkout; replace <this-project> with your project path. After install, invoke /software-factory. Python ≥3.11; POSIX helpers.

Read or select the complete prompt

01 / The complete delivery system

Many stories. One continuing direction.

The orchestrator keeps the ready work moving across planning, parallel delivery, independent proof and feedback. These views explain the architecture; recorded status lives in the project board.

The complete Software Factory system mapThe active host orchestrates risk-sized BMad planning, independent plan review, dependency readiness and parallel claimed story work. Independent QA, evals, actual-diff review and CI gate each story before one integration owner merges it. Delivery proves exact identity and affected behavior within approved authority. Failed or unknown evidence returns to repair or replanning. Authorized signals enter bug triage: confirmed fixes return to planning, unknown causes need separating experiments, and evidence-backed no-fix closure receives independent review. Interruptions reconcile checkpoints and actual state before resuming. Reviewed improvement proposals join the same loop. Human decisions hold affected dependents only. The following reading guide explains every path.
Read the system paths below or Open the full system map (SVG) ↗ · Solid arrows carry work and feedback; rust returns carry repair and reconciliation; dashed paths are conditional.

01 / Ground → ready frontier

Reuse context. Review the plan.

Ground the outcome in current code, principles and existing requirements and architecture. Use risk-sized BMad epics and stories with acceptance criteria, dependencies and proof. An independent plan reviewer sends material gaps back for revision; missing product or contract decisions get the expertise they need.

The orchestrator selects the ready frontier from dependency evidence, reuses applicable authority and replans when evidence changes.

02 / Independent eligible stories

Staff parallel work as capacity opens.

The orchestrator chooses available agents and models, claims exact paths and owns budgets and recovery. Each worker implements, tests, self-reviews and repairs. Independent stories progress concurrently; conflicting paths and shared resources serialize only the contending phase.

Host capabilities vary. The eleven roles are a starting team staffed as needed.

03 / Per-story evidence + return paths

Prove each result independently.

Independent QA exercises actual effects and story evals. Actual-diff review, CI and configured review dispositions bind to the current subject. Failed, missing, stale or unknown proof returns to the owning worker for corrective work and fresh proof, or to planning when the approach must change.

One proven story can advance while another repairs. There is no global all-workers barrier.

04 / Single-owner integration → proven effect

Integrate in order. Prove delivery.

One owner integrates proven stories sequentially after dependency closure and checks the combined result. Release, deployment or approved local staging needs approved authority, exact artifact identity and affected-behavior proof.

Failed or unknown delivery proof reopens affected work. Reconcile the provider’s actual state before retrying an uncertain external effect. Epic acceptance follows current proof, agreed policy and reserved human decisions.

05 / Authorized signals → triage → plan

Turn evidence into the next priority.

Observation is scoped and off by default. Within approved access and a bounded window, attribute signals, deduplicate reports and reproduce safely. Confirmed bugs enter a risk-sized fix with regression proof. Unknown mechanisms lead to separating experiments and fresh evidence.

Evidence-backed no-fix closure receives independent disposition review without fabricated implementation, merge or deployment. New needs enter planning; recurrence creates linked follow-up work. Re-observe affected behavior after delivery.

06 / Interruption → reconcile → resume

Resume from facts that still hold.

Save bounded checkpoints at meaningful transitions. After interruption, reconcile Git, workers, claims, decisions, provider outcomes and evidence freshness before resuming authorized work. A checkpoint preserves context; it grants no new authority.

Repeated rework can become a bounded factory improvement proposal: independent review and canaries precede authorized application, then observation supports retention or rollback through the same delivery loop.

Shared throughout / durable project facts

One owner for each kind of record.

Principles, architecture and BMad sources ground the work. Board records own live story status; claims own path assignments. Git subjects, receipts, decisions and checkpoints preserve proof and continuity.

The active coding host executes. The derived board and lifecycle graph provide evidence navigation and never dispatch agents. A diagram illustrates these relationships; it does not prove runtime behavior.

02 / Features and failures

Progress includes the return path.

A failed test, uncertain effect or confirmed review finding is work to resolve. The same evidence standard holds from a new feature to a production signal.

A / Feature loop

From intent to an observed result.

  1. Ground the outcome, then plan BMad epics, stories and acceptance criteria.
  2. Review the plan; reconcile scoped GO.
  3. Claim work, implement, test and review.
  4. Independently prove effects on the actual HEAD.
  5. Integrate, prove the deployed identity and behavior.
  6. Use verified results and authorized feedback to prioritize the next eligible story.

↳ Failed or unknown proof → corrective work → fresh proof.

B / Bug loop

Evidence before a theory.

  1. Record the bug and preserve primary evidence.
  2. Reproduce safely; separate mechanism from hypothesis.
  3. If no fix is needed, independently review the evidence-backed disposition and close that branch here.
  4. For confirmed fixes only: plan the root-cause fix, capture a failing regression, repair and review.
  5. For those fixes, prove the original reproduction against the resulting artifact.
  6. Close confirmed fixes with receipts and re-observe within approved access.

↳ Unknown cause → separating experiment. Recurrence → linked follow-up.

03 / Evidence has an address

“Done” deserves a receipt.

Accepted assertions come before implementation. Bind test and effect evidence to the exact subject, then have someone independent inspect what actually happened.

Eval first.

Use fail-to-pass cases for the new behavior and pass-to-pass cases for what must survive. Calibrate qualitative rubrics with known good and bad canaries.

One master board.

Per-story records hold live story status. Dashboards and the lifecycle graph are derived views. Claims describe assignment; they do not establish a worker is running.

A graph of recorded facts.

Trace requirements, code surfaces, claims, receipts, findings and deployed identities. Provenance exposes stale subjects and missing proof. A declared link or bare commit identity does not prove a shipped effect.

Synthetic specimen / not a live run

Story: preserve an interrupted draft
Accepted assertiondraft survives resume
Regression before changeFAIL → captured
Current artifact regressionPASS → receipt
Independent effect reviewpending
Deployment + affected behaviorunknown
Human decision needed?assess risk + agreed autonomy
Example states illustrate distinct proof obligations. No worker activity, deployment or acceptance is claimed here.

04 / Grounded onboarding

An interview that starts by listening.

sf-help reads existing project context and prefills twenty decisions in five groups. Known answers get a short confirmation; unresolved material choices get one focused question at a time.

Review the exact proposal, defaults and unknowns before setup is applied. Re-onboarding preserves confirmed answers and existing documents.

Explore sf-help

The setup path / illustrative

Discover project factsread-only observations
Prefill the decision catalog20 decisions / 5 groups
Resolve material unknownsone focused question
Review exact proposed filesowner approval
Apply, then take a first lapapproved digest only

05 / Eleven portable skills

A palette. Use what the work needs.

Small entry points, detailed references and deterministic Python helpers. Expand a skill to see its job. These are a starting palette; existing project principles remain authoritative.

software-factoryOrchestrate / delivery

Own the whole cycle: discover, plan with BMad, staff, build, prove, ship and improve. Involve humans when risk, authority or reserved decisions require it.

Declared source target ↗

Source publication pending verification.

sf-helpGround / setup

Discover context, prefill twenty grouped decisions, propose exact setup files and apply the approved proposal.

Declared source target ↗

Source publication pending verification.

sf-principlesGround / principles

Establish and maintain the project context home: principles, architecture, conventions and decisions.

Declared source target ↗

Source publication pending verification.

sf-crawlGround / codebase

Read the codebase into a bounded factual map. Preserve unknown relationships rather than infer runtime behavior.

Declared source target ↗

Source publication pending verification.

sf-agentsStaff / capability

Observe available capabilities, explain risk-aware routes and prepare optional review-bot rules from approved principles.

Declared source target ↗

Source publication pending verification.

sf-evalProve / acceptance

Define accepted assertions, fail-to-pass and pass-to-pass cases, calibrated rubrics and story evidence gates.

Declared source target ↗

Source publication pending verification.

sf-designDesign / judgment

Start with the smallest complete design. Reuse what exists and connect the plan to the project’s actual constraints.

Declared source target ↗

Source publication pending verification.

sf-smell-auditDesign / diagnosis

Identify source-grounded design smells and prioritize by observed effect, risk and proof.

Declared source target ↗

Source publication pending verification.

sf-refactorDesign / change

Choose a focused behavior-preserving transformation, remove obsolete paths and prove the result.

Declared source target ↗

Source publication pending verification.

sf-patternsDesign / structure

Use a pattern only when it solves a demonstrated problem; consider a simpler implementation first.

Declared source target ↗

Source publication pending verification.

sf-evolveImprove / learning

Fold in reviewed capabilities and customizations, then use canaries and later observation to retain or roll back improvements.

Declared source target ↗

Source publication pending verification.

06 / Eleven role prompts

Staff for the problem in front of you.

The orchestrator chooses expertise by risk and likely rework. Roles run through available host workers and inherit actual permissions. Eleven prompts do not imply eleven concurrent agents.

04 / IMPLEMENTATION

Engineer

Build the smallest complete change, including error and recovery paths.

Role source

Declared source target ↗ · publication pending verification.

Eleven roles grouped into framing outcomes, building and delivering, and challenging and proving work.
Open role-team card at full size (PNG) ↗

07 / Your host, your permissions

Portable source. Honest host limits.

Choose the route for the capability you need. Format and fixture checks establish local contracts; they do not establish live host loading, marketplace acceptance or public availability.

Claude Code

Project projections include skills, roles, policies and recovery hooks. Native bundles also package role prompts.

/software-factory

Cursor

Project projections include skills, roles, rules and hooks. Combined Cursor/Codex loading remains unverified.

/software-factory

Codex

Use project setup for custom agents. Plugin role TOMLs remain manual/reference use; registration is unverified. Hooks require user trust.

$software-factory
01

Full project setup RECOMMENDED

From an existing trusted local pack checkout, install into your project. Projects skills, roles, policies and hooks with ownership records, backups and safe uninstall. BMad planning uses a separately installed, pinned Method v6; verify its availability during setup.

python3 -I -B install.py install --host claude-code --skip-bmad --project "<this-project>" --profile full --dry-run

Review the dry run; omit --dry-run to install. Replace the host argument for Cursor or Codex. Host permissions and trust still apply.

Choose your host and copy the setup prompt ↑
02

Native plugin bundles

Generate self-contained marketplace roots from the same canonical source with install.py project. Claude/Cursor package native roles; Codex plugin role registration is unverified.

Bundles do not perform full consumer-project setup. Avoid overlapping project/plugin hooks. Public marketplace availability is not established; hook-bearing OpenAI plugins are excluded from the public directory.

03

Portable skills discovery

The root plugin.json and canonical skills CLI route expose eleven skills. This route is skills-only.

It does not establish native roles, hooks, invocation controls, project setup or trust. Use the full installer when you need those lifecycle capabilities.

Platform note: the installer and local helpers use POSIX filesystem primitives. Python ≥3.11 alone does not establish native Windows support; native Windows helper execution is unverified. macOS/Python 3.12 is the observed execution environment. Linux/WSL execution remains unobserved here.

Claude Code, Cursor and Codex: full project setup, native plugin bundles and skills-only discovery, with host limits stated.
Open host and installation-route card at full size (PNG) ↗

08 / How the pieces fit

A clear division of responsibility.

The pack is Markdown and standard-library Python. Your active coding host supplies execution and judgment; optional integrations extend a scoped capability.

Responsibilities by layer. Optional integrations are not enabled by default.
ResponsibilitySoftware Factory packCoding hostOptional integration
Plan and contextSkills, templates, project principlesGrounded priorities, epics and storiesSeparately installed pinned BMad
Work executionRole prompts and path claimsNative workers, tools and permissionsApproved coding-agent capability
Independent proofEval contracts and subject-bound receiptsTests, actual effects, independent reviewConfigured CI or review bots
RecoveryCheckpoints, records, derived viewsReconcile current facts on resumeProvider state where authorized
ObservationSignal and continuity guidanceAvailable capability, scoped windowExplicitly authorized host schedule

09 / Before your first lap

The practical questions.

BMad plans, the factory ships.
Proof and human judgment stay in the loop.

Does this give an agent more permissions?

No. Actual host permissions and project trust apply. Prompts, hooks and local locks are conveniences; reviewer prose does not enforce an independent sandbox. Production writes require explicit human GO.

What counts as evidence?

Current subject-bound test results, independently inspected effects and actual-diff review. A declared coverage link, successful command, local done status or bare commit identity is insufficient to prove a shipped result. Failed, missing and unknown evidence remain visible.

Can I choose the model and agents?

The host determines available models and execution tools. Staffing follows capability, risk and likely rework, with a native fallback. Record requested models separately from observed effective models; unknown attribution stays unknown. The pack contains no model gateway.

What happens when a session ends?

Records and checkpoints preserve context. On resume, the host reconciles repository state, ownership, provider outcomes and evidence before continuing. Hooks assist recovery; they do not start workers. There is no pack scheduler, daemon or hosted service.

Does it monitor my project continuously?

Observation requires an available supported capability, approved source/read scope and window, attributable observations and separate repair authority. Without an explicitly authorized and observed host schedule, observation ends with the active session. Monitoring is off by default; no telemetry is added.

How does BMad fit? What about review bots?

BMad skills are central to planning structured epics and stories. Method v6 is installed separately through its official pinned installer; the pack never vendors it. Verify the actual planning capability; if unavailable, report that limit rather than imply BMad ran. Greptile, CodeRabbit, Bugbot and Copilot review integrations are optional and disabled by default. Available tooling and account access must be observed.

Can I uninstall or keep my customizations?

The installer records ownership and backups. Use its uninstall path to remove owned projections safely; edited files require reconciliation rather than destructive cleanup. The sf-evolve workflow supports reviewed overlays that survive reinstalls with drift checks and rollback evidence.

Is the skills-only route enough?

It supplies the portable skill source. It does not establish native roles, hooks, project setup, invocation controls or trust. Choose full project setup for those capabilities; plugin custom-agent registration and combined host loading have their stated limits.

Is this a released, hosted product?

This showcase describes a pre-release pack targeting v0.1.0. Release artifacts, public source availability, marketplace acceptance and Pages deployment are not established by this page. The declared repository links are publication targets pending verification. You can inspect and use an existing trusted local checkout.

Keep the next step concrete.

Your next idea.
Your next shipped improvement.

Start with a grounded story. Ship with proof. Learn and continue.

Set up your project