Governed project templates

Templates let you make scaffold intent explicit without changing the governed protocol. They add planning structure and prompt guidance for a project shape, then record that choice in agentxchain.json.

This is the contract:

• Template choice is scaffold intent, not runtime magic.
• The selected template is stored in the top-level template field in agentxchain.json.
• Templates add planning artifacts and guidance; they do not fork the protocol, role schema, or gate model.
• Existing governed repos without a template field are treated as generic.

Built-in templates

Template	Best fit	Planning artifacts added
generic	Baseline governed scaffold, manual-first cold start	No extra project-type files
api-service	Backend services and APIs	api-contract.md, operational-readiness.md, error-budget.md
cli-tool	Command-line tools and packaged CLIs	command-surface.md, platform-support.md, distribution-checklist.md
library	Reusable packages and shared modules	public-api.md, compatibility-policy.md, release-adoption.md
web-app	Product UIs and browser-facing apps	user-flows.md, ui-acceptance.md, browser-support.md
full-local-cli	Human-gated automation with all core roles on local_cli	No extra planning files; changes the runtime/authority topology at init time
enterprise-app	Multi-role delivery with architecture and security review	integration-boundaries.md, data-classification.md, risk-register.md

If you cannot justify one of the specialized templates honestly, stay on generic. The point is clearer planning, not decorative metadata. generic is also the lowest-friction cold-start option: it keeps pm, dev, and qa on manual runtimes until you opt into automation.

full-local-cli and enterprise-app are blueprint-backed init-time templates. They are intentionally init-only because they change governed team topology or runtime authority posture instead of merely appending planning files.

Use a template at init time

The init-time command surface is:

agentxchain init --governed --template <id>

For a new governed repo, choose the template up front:

agentxchain init --governed --template web-app --goal "Build a governed web application" --dir my-project -y
cd my-project

That writes the governed scaffold plus the template-specific planning files. The config then records:

{
  "schema_version": "1.0",
  "template": "web-app"
}

Inspect available templates

Use template list when you want the built-in descriptions instead of guessing from docs:

agentxchain template list
agentxchain template list --json

The JSON mode exposes the operator-relevant shape directly:

• template id
• display_name
• description
• planning artifact filenames
• roles with prompt overrides
• scaffold blueprint roles
• acceptance hints

Prove the template surface instead of assuming it

Use template validate when you need actual proof, not a guess based on docs or remembered scaffold intent:

agentxchain template validate
agentxchain template validate --json

This checks five things:

• the built-in registry is coherent: every registered template manifest exists, parses, and validates
• the current project template is coherent: the repo's agentxchain.json template value resolves under the installed CLI
• the governed workflow kit is coherent: the scaffold-owned planning files exist and preserve their minimum structural markers
• planning artifact completeness: every file the template's planning_artifacts array requires exists in .planning/
• acceptance hint completion: every template-defined acceptance hint in acceptance-matrix.md is checked off

Important truths:

• if a governed repo omits template, validation treats it as implicit generic
• if the repo names a template the installed CLI does not recognize, validation fails
• if the core workflow-kit scaffold loses its minimum contract (Approved:, ## Phases, ## Purpose, ## Interface, ## Acceptance Tests, | Req # |, ## Verdict:), validation fails
• if the template requires planning artifacts (e.g., library requires public-api.md, compatibility-policy.md, release-adoption.md) and any are missing from .planning/, validation fails
• if the template defines acceptance hints and any remain unchecked in acceptance-matrix.md, validation emits warnings (not errors) — this is QA-layer signal, not a hard gate

The JSON output exposes a dedicated workflow_kit block so automation can distinguish:

• core workflow-kit failures
• template-specific artifact failures
• acceptance-hint warnings

The workflow-kit proof now includes .planning/SYSTEM_SPEC.md. First-party governed planning is not allowed to exit with no subsystem contract at all.

Template Choice Does Not Change The Evidence Boundary

Templates change scaffold intent and planning artifacts. They do not create a separate audit/report mode.

Use the same evidence commands regardless of whether the repo is generic, cli-tool, web-app, or a blueprint-backed enterprise-app:

agentxchain audit --format markdown
agentxchain export --format json > governance-export.json
agentxchain report --input governance-export.json --format markdown

The contract stays the same:

• audit inspects the live current repo or workspace
• export writes the portable governed or coordinator artifact
• report --input reads an existing export artifact, not live repo state

Template-specific planning files and workflow-kit artifacts show up through those same surfaces. If a template adds ARCHITECTURE.md, SECURITY_REVIEW.md, command-surface.md, or other planning files, audit sees them from live state and report --input renders them from the saved artifact.

That same rule applies in coordinator workspaces too. Partial artifacts remain readable: audit and report keep repo_ok_count / repo_error_count export-health visibility plus the failed repo row and error, but they do not invent failed-child drill-down when a nested child export is unavailable.

Explicit workflow_kit for custom phases

If you explicitly declare workflow_kit in agentxchain.json, template validate stops pretending the built-in 3-phase scaffold is your whole contract. It uses your declared artifacts instead.

{
  "workflow_kit": {
    "phases": {
      "design": {
        "artifacts": [
          {
            "path": ".planning/DESIGN_DOC.md",
            "semantics": "section_check",
            "semantics_config": {
              "required_sections": ["## Architecture", "## Interfaces", "## Trade-offs"]
            },
            "required": true
          }
        ]
      }
    }
  }
}

You can also reference the shipped workflow-kit phase templates instead of rewriting the same artifact blocks by hand:

{
  "workflow_kit": {
    "phases": {
      "planning": {
        "template": "planning-default"
      },
      "architecture": {
        "template": "architecture-review"
      },
      "implementation": {
        "template": "implementation-default"
      },
      "security_review": {
        "template": "security-review"
      },
      "qa": {
        "template": "qa-default"
      }
    }
  }
}

Use the CLI to enumerate the shipped phase templates and their artifact contracts:

agentxchain template list --phase-templates
agentxchain template list --phase-templates --json

The shipped phase-template ids are:

• planning-default
• implementation-default
• qa-default
• architecture-review
• security-review

In explicit mode:

• workflow_kit.required_files comes from the declared artifact paths plus any gate requires_files
• workflow_kit.phases.<phase>.template expands to the built-in artifact bundle for that phase contract
• when a phase declares both template and artifacts, a same-path explicit artifact overrides the built-in template fields instead of duplicating the file contract
• explicit artifacts with new paths are still appended after the built-in template artifacts
• section_check entries generate structural checks from required_sections
• built-in semantic IDs on canonical files still reuse the shipped structural markers where they exist
• re-running agentxchain init --governed --dir . -y scaffolds newly declared custom artifact files that were not part of the default governed starter

If workflow_kit is absent, template validate falls back to the built-in scaffold contract. If workflow_kit: {} is explicit, that is an opt-out of per-phase workflow artifacts rather than a hidden fallback to the defaults.

Important boundary: built-in phase templates do not infer owned_by. If a custom phase needs role-bound artifact authorship, declare the same artifact path explicitly with owned_by so the template semantics stay intact while ownership is layered on top. enterprise-app now uses this exact composition pattern for ARCHITECTURE.md and SECURITY_REVIEW.md.

Each non-generic template also carries a system_spec_overlay that replaces the generic placeholder text in SYSTEM_SPEC.md with project-shape-specific guidance. For example, api-service prompts for endpoint contracts and error budgets, while library prompts for public API surface and compatibility policy. The generic template produces the baseline spec with universal placeholders.

Registry, workflow-kit, and artifact failures are errors. Unchecked acceptance hints are warnings. Silent tolerance on either would hide governance gaps, but the severity distinction reflects that acceptance hints are guidance obligations, not structural requirements.

Blueprint-backed templates — custom roles and phases

enterprise-app and full-local-cli are intentionally not just artifact bundles. They are init-only blueprint-backed templates.

full-local-cli keeps the standard 4-role team but moves every role onto authoritative local_cli execution while preserving human gate approvals. See Automation Patterns for the exact operator path.

enterprise-app scaffolds a full custom governed team:

Role	Phase owned	Gate artifact
pm	planning	PM_SIGNOFF.md, ROADMAP.md, SYSTEM_SPEC.md
architect	architecture	ARCHITECTURE.md (requires ## Context, ## Proposed Design, ## Trade-offs, ## Risks; ownership enforced via owned_by: "architect")
dev	implementation	IMPLEMENTATION_NOTES.md
security_reviewer	security_review	SECURITY_REVIEW.md (requires ## Threat Model, ## Findings, ## Verdict; ownership enforced via owned_by: "security_reviewer")
qa	qa	acceptance-matrix.md, ship-verdict.md, RELEASE_NOTES.md
eng_director	— (escalation)	—

The phase order is: planning → architecture → implementation → security_review → qa.

This is the shipped proof that built-in governed templates are no longer locked to pm, dev, qa, and eng_director. Any well-formed role ID (^[a-z0-9_-]+$) is accepted across the config, prompt, and validation surfaces.

Scaffolding an enterprise-app repo

agentxchain init --governed --template enterprise-app --goal "Enterprise delivery with extended team topology" --dir my-enterprise -y
cd my-enterprise

This produces:

.planning/
  PM_SIGNOFF.md
  ROADMAP.md
  SYSTEM_SPEC.md
  IMPLEMENTATION_NOTES.md
  ARCHITECTURE.md          ← architect owns this
  SECURITY_REVIEW.md       ← security_reviewer owns this
  acceptance-matrix.md
  ship-verdict.md
  RELEASE_NOTES.md
  integration-boundaries.md   ← enterprise planning artifact
  data-classification.md      ← enterprise planning artifact
  risk-register.md             ← enterprise planning artifact

.agentxchain/
  prompts/
    pm.md
    architect.md             ← includes owned phase, gate, artifact context, and ownership enforcement
    dev.md
    security_reviewer.md     ← includes owned phase, gate, artifact context, and ownership enforcement
    qa.md
    eng_director.md

The generated prompt files for custom roles (architect.md, security_reviewer.md) include their owned phase, exit gate ID, workflow artifacts, and the explicit ownership rule: the gate will not pass unless that role has an accepted turn in the phase.

Running through the enterprise phases

After planning approval, the architect role owns the architecture phase:

agentxchain step --role architect
# fill .planning/ARCHITECTURE.md with ## Context, ## Proposed Design, ## Trade-offs, ## Risks
agentxchain approve-transition

After implementation, the security_reviewer role owns the security_review phase:

agentxchain step --role security_reviewer
# fill .planning/SECURITY_REVIEW.md with ## Threat Model, ## Findings, ## Verdict
agentxchain approve-transition

Both ARCHITECTURE.md and SECURITY_REVIEW.md are structurally validated by template validate via section_check semantics. The gate will not pass if required sections are missing, and it also stays blocked if the wrong role tried to satisfy an ownership-enforced artifact.

Validation proof

agentxchain template validate --json

The JSON output includes per-phase workflow-kit proof:

{
  "ok": true,
  "workflow_kit": {
    "required_files": [".planning/ARCHITECTURE.md", ".planning/SECURITY_REVIEW.md", "..."],
    "missing": [],
    "structural_checks": [
      { "file": ".planning/ARCHITECTURE.md", "sections": ["## Context", "## Proposed Design", "## Trade-offs", "## Risks"], "ok": true },
      { "file": ".planning/SECURITY_REVIEW.md", "sections": ["## Threat Model", "## Findings", "## Verdict"], "ok": true }
    ]
  }
}

Important boundary

• init --governed --template enterprise-app is supported and writes the custom team topology
• template set enterprise-app is intentionally rejected because rewriting roles, runtimes, routing, gates, and workflow_kit inside an existing repo is not additive work

The error is deliberate:

Error: Template "enterprise-app" defines a custom governed team blueprint.
Use agentxchain init --governed --template enterprise-app for new repos.

Authoring a new blueprint-backed template

This is a CLI-source extension point today, not a runtime operator command. New governed templates are built into the CLI from manifest files under cli/src/templates/governed/ and registered in VALID_GOVERNED_TEMPLATE_IDS.

The honest authoring path is:

1. Add cli/src/templates/governed/<id>.json
2. Register <id> in cli/src/lib/governed-templates.js
3. Define the base manifest fields: id, display_name, description, version, protocol_compatibility, planning_artifacts, prompt_overrides, acceptance_hints, and system_spec_overlay
4. Add scaffold_blueprint only when the template really changes team topology

If you define scaffold_blueprint, its five governed config blocks are the contract:

• roles
• runtimes
• routing
• gates
• workflow_kit

Those blocks are validated through the same governed config validator used by the product. That means:

• role IDs must stay within ^[a-z0-9_-]+$
• phase IDs in routing and workflow_kit.phases must agree
• each exit_gate must exist under gates
• gate requires_files and workflow-kit artifact paths should describe the same phase contract instead of drifting apart

Use the shipped enterprise-app manifest as the reference implementation:

agentxchain template list --json | jq '.[] | select(.id == "enterprise-app")'

Then prove the new template end to end instead of trusting the JSON by inspection:

agentxchain init --governed --template <id> --dir /tmp/template-proof -y
cd /tmp/template-proof
agentxchain template validate --json

Important boundary: if the new template rewrites roles, runtimes, routing, gates, or workflow_kit, keep it init-only. template set is only honest for additive templates until a dedicated migrator exists.

Apply a template to an existing governed repo

The mutation command surface is:

agentxchain template set <id> [--yes] [--dry-run]

If a repo was initialized as generic, annotate it later:

agentxchain template set api-service --yes

template set is intentionally conservative:

• updates the top-level template field in agentxchain.json
• creates missing planning artifacts from the target template
• appends prompt guidance once per role when no ## Project-Type-Specific Guidance section exists
• appends acceptance hints once when acceptance-matrix.md has no ## Template Guidance section
• appends template-specific guidance to SYSTEM_SPEC.md when no ## Template-Specific Guidance section exists
• records a template_set entry in .agentxchain/decision-ledger.jsonl

Use --dry-run when you want the exact mutation plan before writing anything:

agentxchain template set cli-tool --dry-run

The CLI prints what would change and what would be skipped, for example WILL CREATE, WILL APPEND override, ALREADY HAS guidance (skip), and No changes written. Use without --dry-run to apply.

What it does not do:

• overwrite existing planning docs
• replace an existing ## Project-Type-Specific Guidance block in role prompts
• replace an existing ## Template Guidance block in acceptance-matrix.md
• replace an existing ## Template-Specific Guidance block in SYSTEM_SPEC.md
• delete old template files when switching templates
• infer a template from repo contents

Important boundary: blueprint-backed templates stay init-only under template set. Today that includes enterprise-app and the manual-first generic baseline. Retrofitting an existing repo into either shape needs an explicit migrator because the change is not additive.

Switching from one non-generic template to another is therefore additive, not destructive. If you want to rewrite prior docs manually, do it explicitly.

See template intent in status

Template choice stays visible in routine operator commands:

agentxchain status
agentxchain status --json

Human-readable status shows:

Template: web-app

JSON status includes both:

• top-level template
• config.template

That makes scaffold intent visible to operators, scripts, and future migration logic without hiding it in run state.

Choosing honestly

Use api-service when the repo's risk is mostly API contract and operability.

Use cli-tool when the repo's risk is command surface, install path, and distribution quality.

Use library when the repo's risk is public API stability, compatibility guarantees, and consumer adoption.

Use web-app when the repo's risk is user flow, browser behavior, and UI acceptance proof.

Use enterprise-app when the repo needs architecture and security review as first-class governed phases instead of burying those concerns inside generic PM or QA notes.

Use generic when none of those specializations fit cleanly or when you want the base manual-first governed scaffold first.

Related docs

• Quickstart
• CLI Reference