software-factory-cookiecutter 0.4.0a1

Cookiecutter template for Python software-factory projects with optional agent SDLC governance.

Software Factory Cookiecutter

Alpha (v0.4.0a1 for PyPI / v0.4.0-alpha Git tag): The core "agent-run software factory" model is implemented, tested, and documented. It is usable today for early adopters and dogfooding on real projects (including this meta-repository). Expect iteration on details, ceremony tuning, and possibly minor breaking changes based on feedback. We strongly recommend starting new software_factory projects with the built-in bootstrap.

Cookiecutter template for Python projects, with opt-in profiles ranging from a minimal package scaffold to the full software-factory agent/SDLC workflow.

The default profile is quality_python: a production-ready Python scaffold with quality tooling and CI, but without agent or SDLC ceremony.

What It Generates

• Python package scaffold managed with uv
• pytest test scaffold
• Optional ruff, mypy, make check, and GitHub Actions CI
• Optional protected-main / agent-worktree policy
• Optional Claude, Codex/GitHub Copilot, Cursor, and Gemini instruction surfaces
• Optional GitHub issue template for governed work items
• Optional SDLC documentation, ready criteria, and file-backed work-item folders
• Optional software-factory role prompts for PM, spec, issue planning, coding, review, and drift monitoring
• Optional quality-control scripts for drift, docstrings, markdown links, test value, prompt alignment, and SDLC work-item wiring

The full software_factory profile is deliberately opinionated: it is designed to make agent-driven development traceable, reviewable, and high-quality through worktree isolation, role-routed work items, rendered role prompts, and drift checks.

Requirements

• Python 3.11+
• uv
• cookiecutter
• Git
• GitHub CLI (gh) for GitHub-backed work-item commands

You can run the template without installing Cookiecutter globally:

uvx cookiecutter gh:tomanizer/software-factory-cookiecutter

For environments with no GitHub access, install or run the packaged template from PyPI or an internal PyPI-compatible repository:

uvx software-factory-cookiecutter --no-input --output-dir /tmp/sfc-factory template_profile=software_factory

The package exposes both software-factory-cookiecutter and the shorter sfc-cookiecutter console script. These commands use the template bundled inside the wheel, so rendering does not need GitHub access. They still create a normal generated project; any generated GitHub-backed work-item commands only need gh later if you choose github_issues or hybrid as the backend.

For private package indexes:

uvx --index-url https://pypi.example.com/simple software-factory-cookiecutter --no-input template_profile=software_factory

For a local checkout:

uvx cookiecutter /path/to/software-factory-cookiecutter

Template Options

Important prompts:

• project_name: display name
• project_slug: repository / directory name
• package_slug: Python import package
• github_org: GitHub owner or organization
• python_version: generated project Python baseline
• material_change_domain: ADR gate wording
• template_profile: generated project feature bundle
• enable_agent_worktrees: override profile default for agent worktrees
• enable_github_work_items: override profile default for governed work items
• enable_role_prompts: override profile default for software-factory prompts
• enable_protected_main_hooks: override profile default for local hooks
• enable_quality_drift_checks: override profile default for drift checks
• enable_ci: override profile default for GitHub Actions CI
• work_item_backend: live work-item source when work items are enabled
• enable_mutation_testing: include mutation workflow
• enable_benchmarks: include benchmark workflow
• enable_sbom: include SBOM workflow

Template Profiles

Profile	Includes
minimal_python	package scaffold, uv, pytest, basic README
quality_python	minimal plus ruff, mypy, make check, CI
agent_assisted	quality plus AGENTS.md, tool wrappers, agent worktrees, protected-main hooks
github_sdlc	agent-assisted plus GitHub/file-backed work items, readiness criteria, PR traceability
software_factory	github-sdlc plus role prompt pack, docs/ROLE_PROMPTS.md, make agent-prompt, drift checks, and dependency audit

Override flags use profile_default unless explicitly set to yes or no.

Examples:

uvx cookiecutter --no-input . --output-dir /tmp/sfc-quality
uvx cookiecutter --no-input . --output-dir /tmp/sfc-minimal template_profile=minimal_python
uvx cookiecutter --no-input . --output-dir /tmp/sfc-agent template_profile=agent_assisted
uvx cookiecutter --no-input . --output-dir /tmp/sfc-sdlc template_profile=github_sdlc
uvx cookiecutter --no-input . --output-dir /tmp/sfc-factory template_profile=software_factory

What The Software-Factory Profile Is (and Is Not)

The full software_factory profile is for Python projects that are designed to be worked on primarily by AI coding agents while still meeting production engineering standards. Lighter profiles intentionally omit some or all of this ceremony.

The software_factory profile is not the lightweight starter path. Use minimal_python or quality_python when you want a smaller package scaffold. Use software_factory when you want a deliberately opinionated agent-run software factory with:

• Protected main + agent worktrees by default
• Explicit role-based work items (PM, spec, issue planner, coding, review, drift monitor)
• Canonical role-specific standing instructions (prompts/agents/)
• A governed role prompt path for each work item: make agent-prompt ROLE=... ISSUE=... for GitHub/hybrid backends, or the returned WORK_ITEM=... file plus prompts/agents/*_instruction.md for file-backed work
• Strong local quality gates and drift detection (complexity, wrappers, dead code, prompt alignment, work-item wiring, etc.)
• Full SDLC policy, readiness criteria, and GitHub-backed (or file-based) work-item tracking

The goal is to make large amounts of agent-driven development traceable, reviewable, and high-quality instead of chaotic.

What It Is Good For

• Teams or individuals who want to use AI agents as first-class participants in a disciplined engineering process.
• Projects that will have significant ongoing agent work and need guardrails against scope creep, invented processes, untraceable changes, and prompt drift.
• Organizations that are intentionally adopting "agent-assisted" or "agent-first" development and want a coherent operating model rather than ad-hoc prompting.
• Long-lived internal platforms, services, or tools where auditability and consistent quality matter more than raw speed of the first commit.

What It Is Not Good For

• Throwaway scripts, one-off prototypes, or weekend projects (use minimal_python or an even lighter starter).
• Teams that want fully autonomous agents with zero human oversight or process.
• Projects that strongly reject any form of work-item tracking or prefer completely free-form "vibe coding" with agents.
• People looking for a full web framework, specific domain starter (e.g. FastAPI + SQLAlchemy + Alembic template), or production infrastructure (this only scaffolds the Python package + process overlay).

Why It Is Opinionated (and How)

Without strong defaults and enforced steps, agent-driven development tends to produce:

• Agents that invent their own (inconsistent) processes every session
• Work that slowly widens scope because "it seemed related"
• Changes that are hard to review because there is no clear contract (PRD/ADR/WI)
• Prompt and process drift that only becomes visible after damage is done

The software_factory profile is opinionated precisely to prevent those failure modes at scale.

Core Opinionated Mechanisms

• Protected main + agent worktrees — No agent (or human) is allowed to edit directly on main. All work happens in isolated worktrees created with make agent-ensure.
• Work items as the atomic unit of work — Everything starts from a bounded, reviewable work item with explicit scope, out-of-scope, acceptance criteria, test intent, and stop conditions.
• Role-based routing + mandatory role prompts — Work is explicitly routed to a role (PM, spec, coding, etc.). For GitHub/hybrid work items, the agent starts with make agent-prompt ROLE=... ISSUE=... and uses the rendered prompt as its system prompt. For file-backed work items, the agent reads the returned WORK_ITEM=... file and the matching prompts/agents/*_instruction.md. Both paths force the agent to read the exact standing instruction and current contract.
• Project initiation bootstrap — New software_factory projects are expected to start with make show-bootstrap-sequence, run the grillme skill for Mission/Purpose/Goals, then write a (possibly phase-limited) Initial PRD. Architecture, data models, etc. are expected to emerge from real spec work, not be written as empty stubs on day one.
• Continuous verification — A suite of local + CI checks for code drift, prompt alignment, work-item wiring, dead code, test value, etc. The drift-monitor role exists to surface divergence between stated process and reality.
• Profile system — You can opt into increasing levels of ceremony (minimal_python → quality_python → agent_assisted → github_sdlc → software_factory). The software_factory profile is the full model; lighter profiles deliberately omit parts of the ceremony.

The opinionation is not "we like process for its own sake." It is the minimal set of constraints we have found necessary to make agent-driven development reliable, reviewable, and maintainable when the volume of agent work becomes large.

How a Software-Factory Project Is Set Up and How Development Works

See the generated project's README.md (after scaffolding) for the user-facing guide. Highlights include:

• AGENTS.md — the single source of truth every agent must read
• prompts/agents/ + make agent-prompt — the role prompt system
• Worktree isolation commands (make agent-ensure, make agent-guard, ...)
• docs/SDLC.md, docs/ROLE_PROMPTS.md, and work_items/READY_CRITERIA.md
• Quality control suite (make quality-control, make check)
• GitHub Actions that understand roles and governance changes

The generated docs/ROLE_PROMPTS.md is the deep reference for the entire role-based agent system (what each role does, best practices, customization, and many worked examples).

Typical Development Flow (Software Factory Profile)

1. Initiation (new project)

   • make show-bootstrap-sequence
   • make bootstrap-initiation-issues (GitHub mode) or use the pre-seeded files (file-system mode)
   • PM role + grillme skill → Mission/Purpose/Goals
   • Initial PRD (can be deliberately phase-limited)

2. Normal cycle (any role)

   • make work-item-next ROLE=<role>
   • GitHub/hybrid: make agent-prompt ROLE=<role> ISSUE=<n>, then paste the full rendered prompt into your agent
   • File-system: read the returned WORK_ITEM=... file and the matching prompts/agents/*_instruction.md
   • Claim the item, make agent-ensure ..., enter the worktree
   • Work only inside the contract given by the WI + linked PRD/ADR
   • GitHub/hybrid: ship via PR + make work-item-status ... STATUS=in-review
   • File-system: ship via PR and move the WORK_ITEM file to the appropriate stage directory
   • Review role (or human) reviews against the original contract
   • Merge → done (or drift-monitor pass)

All of this is designed so that a human or an agent can pick up any work item and have a high chance of doing the right thing without "figuring out the process" from scratch every time.

Full details and the exact commands live in the generated project's documentation (especially AGENTS.md, docs/SDLC.md, and docs/ROLE_PROMPTS.md).

For a concrete end-to-end example before rendering your own project, see docs/WALKTHROUGH.md.

Development of the Template Itself

See the "Developing the Template Itself" section below for how changes to the cookiecutter are validated and released.

Work-Item Backends

work_item_backend is only meaningful when governed work items are enabled, either through github_sdlc, software_factory, or enable_github_work_items=yes.

github_issues is the default backend. GitHub Issues are the canonical live backlog; repo files define SDLC policy, templates, and checks. Agents use labels as the machine-readable routing contract:

• work-item
• status:ready, status:in-progress, status:blocked, status:in-review, status:done
• role:pm, role:spec, role:issue-planner, role:coding, role:review, role:drift-monitor

Generated commands when GitHub work items are enabled:

make work-item-labels
make work-items-ready
make work-item-next ROLE=coding
make work-item-claim ISSUE=123 AGENT=codex
make work-item-status ISSUE=123 STATUS=in-review

These commands require the GitHub CLI (gh) to be installed and authenticated. In software_factory renders, make agent-prompt ROLE=coding ISSUE=123 also renders the role-specific prompt pack.

file_system keeps live work items under work_items/ready, work_items/in_progress, work_items/blocked, work_items/done, and work_items/archived.

hybrid uses GitHub Issues for live status while allowing selected work-item artifacts to be mirrored in the repo for audit history.

Software-Factory Project Initiation

The software_factory profile includes an optional but recommended initiation bootstrap:

make show-bootstrap-sequence

For github_issues and hybrid, the generated project provides make bootstrap-initiation-issues to create the Mission/Purpose/Goals and Initial PRD issues explicitly after GitHub labels exist. Cookiecutter rendering never creates GitHub issues.

For file_system, the two initiation items render under work_items/ready/ as canonical WI-001/002 files. Hybrid keeps those files as auditable mirrors while GitHub Issues remain the live status board.

First Run In A Generated Project

cd <project_slug>
uv sync
# Commit the lockfile for reproducible CI
git add uv.lock
make check
git add -A
git commit -m "chore: initial scaffold"

For agent-assisted profiles, initialize local worktree policy:

make setup-agent-policy

For GitHub-backed work items, create labels after pushing the generated repo:

make work-item-labels

For the full software-factory workflow, read AGENTS.md, docs/ROLE_PROMPTS.md, and prompts/agents/README.md before letting any agent do work.

Typical Software-Factory Agent Flow

In software_factory renders:

1. make work-item-next ROLE=coding
2. GitHub/hybrid: make agent-prompt ROLE=coding ISSUE=123, then paste the rendered prompt into your agent
3. File-system: read the returned WORK_ITEM=... file and prompts/agents/coding_agent_instruction.md
4. Claim or move the work item as your backend requires, then enter the worktree
5. Implement only what the prompt/instruction and work-item contract authorize
6. Open a PR and move the work item to review (make work-item-status ISSUE=123 STATUS=in-review for GitHub/hybrid)

Full details live in the generated project's AGENTS.md, docs/SDLC.md, docs/ROLE_PROMPTS.md, and prompts/agents/README.md.

Development

The fastest way to validate the template is with the automated render + checklist tests:

make test-template

This exercises all profiles, work-item backends, feature flags, post-gen hook (executable bits, conditional removal), generated validation scripts, and a full generated software_factory uv sync && make check run.

Manual verification:

uvx cookiecutter --no-input . --output-dir /tmp/sfc-render
cd /tmp/sfc-render/my-project
uv sync
make check

Check non-default profiles and work-item backends:

uvx cookiecutter --no-input . --output-dir /tmp/sfc-minimal template_profile=minimal_python
uvx cookiecutter --no-input . --output-dir /tmp/sfc-file template_profile=github_sdlc work_item_backend=file_system
uvx cookiecutter --no-input . --output-dir /tmp/sfc-hybrid template_profile=github_sdlc work_item_backend=hybrid

For the PyPI/no-GitHub distribution path, build the wheel and render from the installed console script:

uv build
uvx --from ./dist/software_factory_cookiecutter-<version>-py3-none-any.whl \
  software-factory-cookiecutter --no-input --output-dir /tmp/sfc-wheel \
  template_profile=software_factory

Developing the Template Itself

This repository is the source for the cookiecutter. In addition to the generated project structure, the root includes meta tooling for developing and testing the template:

• pyproject.toml + uv for the meta dev environment
• Makefile with make test-template
• tests/test_render.py for all profiles, backends, and feature flags
• src/software_factory_cookiecutter/ for the PyPI console wrapper
• Root .github/workflows/test-template.yml for CI of the template source

Run make test-template or uv run --group dev pytest tests/ to validate changes to the template without manually rendering every time. The automated suite includes the full generated software_factory check path.

The uv.lock at root is for reproducible meta tests, separate from any generated project's lockfile.

Release Checklist

1. Run the automated template tests (exercises all profiles, backends, bootstrap artifacts, and the full generated software_factory uv sync && make check path):

   make test-template
   

2. Build the PyPI distribution and smoke-test rendering from the wheel, not only from the source checkout:

   uv build
   uvx --from ./dist/software_factory_cookiecutter-<version>-py3-none-any.whl \
     software-factory-cookiecutter --no-input --output-dir /tmp/sfc-wheel \
     template_profile=software_factory
   

3. For difficult changes, optionally render extra manual scenarios (e.g. software_factory + each work_item_backend) to debug, but do not substitute them for make test-template.
4. Update CHANGELOG.md (if this is a new feature or fix release) and ensure the root README.md philosophy + docs/WALKTHROUGH.md (source + generated) reflect current state.
5. Add or update "Alpha" / status notices in root README (and consider templated notice in generated README.md for software_factory renders).
6. Commit changes (preferably via the project's own bootstrap process on the meta-repo for future releases).
7. Tag the release (e.g. v0.4.0a1 for PyPI alpha builds or v0.4.0 once stable) and push tag.
8. Publish the wheel/sdist to PyPI or the internal PyPI-compatible repository used by downstream environments.
9. (Optional but recommended) Create a GitHub Release using the CHANGELOG section as body. Announce on the tracking issue (#20) and encourage dogfooding + feedback.
10. Immediately after release: Use the new bootstrap on this cookiecutter source itself for any remaining meta-work (e.g. full self-hosting of the factory for template development).