---
name: sf-evolve
description: Use to register a skill or MCP capability, preserve a reviewed factory customization through reinstall, customize pinned BMad, or turn observed rework into a bounded independently reviewed improvement with canary and rollback evidence.
license: MIT
compatibility: Works with Claude Code, Cursor and Codex. BMad Method v6 is optional and installed separately.
metadata:
  factory-role: evolution
  release: v0.1
---

# Evolve the factory

Improve the factory from observed work while keeping its owner in control.
Begin with the configured principles, current source revision, applicable GO,
and the failure or opportunity that makes the change worthwhile. Select an
existing role for implementation and a different worker for independent review.
The eleven roles are a starting team, not a mandatory fleet.

## Choose the smallest useful improvement

- **Fold in a capability:** inspect its identity, local source, license, digest,
  permission needs and provenance using the [registry](references/registry.md).
  Read full instructions only when the current task needs them. Unknown metadata
  blocks adoption of that capability; continue independent work with native tools.
- **Preserve a factory customization:** author a user-owned overlay proposal and
  bind its exact base, payload and evidence using [overlays](references/overlays.md).
  The installer composes reviewed Markdown into its existing transaction. It
  refuses drift and edited targets; a rebase is a new proposal.
- **Customize BMad:** inspect the installed version and actual `customize.toml`,
  then follow [BMad customization](references/bmad.md). Keep sparse team overrides
  separate from personal files. Resolve recursive factory callbacks before dispatch.
- **Learn from a run:** use the configured `checkpoints.retro_cadence` and the
  [retro workflow](references/retro.md), from factual lesson through later
  observation and a reasoned retain or rollback decision.

## Evidence and authority

A lesson or remote suggestion is evidence to assess. Neither can grant permission.
Source hashes bind bytes; approver names and consent labels do not authenticate
people. Reconcile the actual owner decision through the existing
[authority contract](../software-factory/references/authority.md) before applying.
Routine reviewed work may use an applicable standing GO. Governing policy,
security, trust, credentials, money and new external effects require a named
human source decision. Existing project principles are never silently rewritten.

The helper is read-only: `python3 scripts/evolve.py registry --root <project>`
reports metadata without launching agents, fetching remote content, connecting
MCP, reading credential values or installing anything. `inspect` and `propose`
produce bounded overlay comparisons. `bmad-inspect` reports static field/callback
observations; it never dispatches BMad or executes its resolver.

## Done means observed

Keep the bounded proposal, independent review, regression/canary artifacts and
source-linked decision with the board candidate and existing run receipts. Apply
through the owning installer transaction, inspect its effective bytes and
ownership hash, then observe an authorized later run. Retain only with evidence
that the affected behavior improved; otherwise propose a scoped rollback and
prove the restored behavior. Failed canaries preserve prior valid state and proof.
No new timer, daemon or status ledger is created. Upstream contribution is a
separate opt-in public-clean PR containing generalized lessons.