Metadata-Version: 2.4
Name: software-factory-cookiecutter
Version: 0.4.0a1
Summary: Cookiecutter template for Python software-factory projects with optional agent SDLC governance.
Requires-Python: >=3.11
Requires-Dist: cookiecutter>=2.6.0
Description-Content-Type: text/markdown

# 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:

```bash
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:

```bash
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:

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

For a local checkout:

```bash
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:

```bash
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`](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:

```bash
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:

```bash
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

```bash
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:

```bash
make setup-agent-policy
```

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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):
   ```bash
   make test-template
   ```
2. Build the PyPI distribution and smoke-test rendering from the wheel, not only from the source checkout:
   ```bash
   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).
