Templates

The plugin ships 10 template files in templates/. Commands like /harness-init and /superpowers-init read these templates, fill in project-specific values, and write the result to the target project. Templates are never copied verbatim — placeholders are replaced and commented sections are pruned during generation.

Templates fall into three groups: Habitat Files (the living documents that agents and hooks read at runtime), CI Workflows (GitHub Actions and shell scripts for the middle enforcement loop), and Assets (static resources used by observability output).

Habitat Files

These templates produce the core documents that make up a project’s AI literacy habitat. Each file is read by agents, hooks, and commands throughout a session.

HARNESS.md

  • Template: templates/HARNESS.md
  • Generated by: /harness-init
  • Purpose: Source of truth for the project’s harness — conventions, constraints, garbage collection rules, and enforcement status

Key sections:

  • Context — Stack details (languages, build system, test framework, container strategy) and conventions (naming, file structure, error handling, documentation style). Each convention must be concrete enough that a reviewer could objectively evaluate compliance.
  • Constraints — Each constraint becomes a verification slot. Fields per constraint: Rule, Enforcement (deterministic, agent, or unverified), Tool, and Scope (commit, pr, or scheduled). Ships with starter constraints and includes the spec-scoped changes constraint (Human Pace) as of v0.9.3.
  • Garbage Collection — Periodic checks that fight entropy. Each rule has: What it checks, Frequency, Enforcement type, Tool, and Auto-fix flag. Includes the change cadence drift rule (Human Pace) as of v0.9.3.
  • Status — Auto-updated by /harness-audit. Tracks last audit date, constraints enforced ratio, GC rules active, and drift detection.

CLAUDE.md

  • Template: templates/CLAUDE.md
  • Generated by: /superpowers-init
  • Purpose: Project conventions file that Claude reads on every session start

Contains placeholder sections for literate programming rules, CUPID code review properties, workflow conventions (spec-first, TDD, branching, commit messages), build and test commands, learnings pointers, and project-specific constraints. Instructions tell the user to replace every placeholder and delete comment markers.

AGENTS.md

  • Template: templates/AGENTS.md
  • Generated by: /superpowers-init
  • Purpose: Compound learning file — persistent memory across AI sessions

Sections: STYLE (patterns that work), GOTCHAS (traps and surprises), ARCH_DECISIONS (key decisions with reasoning), TEST_STRATEGY (test structure conventions), DESIGN_DECISIONS (stable contracts). All sections start empty with commented examples and accumulate entries over time through /reflect and human curation.

MODEL_ROUTING.md

  • Template: templates/MODEL_ROUTING.md
  • Generated by: /superpowers-init
  • Purpose: Guides the orchestrator when dispatching agents to different model tiers

Contains an agent routing table mapping each agent to a tier (Flagship, Balanced, Efficient) with rationale, token budget guidance per task type, and rules for when to override the default tier. Teams replace tier names with actual model identifiers.

REFLECTION_LOG.md

  • Template: templates/REFLECTION_LOG.md
  • Generated by: /superpowers-init
  • Purpose: Append-only log for post-session reflections

Entry format: Date, Agent, Task, Surprise, Proposal, Improvement, Constraint. Reflections provide raw material for AGENTS.md curation — humans decide what to promote.

CI Workflows

These templates produce CI pipeline files that enforce constraints from HARNESS.md in the middle loop (pull requests and scheduled runs).

ci-github-actions.yml

  • Template: templates/ci-github-actions.yml
  • Generated by: /harness-init
  • Purpose: GitHub Actions workflow for PR-scoped deterministic constraint enforcement

Triggers on pull_request and workflow_dispatch. Checks for HARNESS.md existence before running. Ships as a skeleton — deterministic tool steps are added as constraints are promoted via /harness-constrain. Uses read-only permissions.

ci-auto-enforcer.yml

  • Template: templates/ci-auto-enforcer.yml
  • Generated by: /harness-init (offered when auto-enforcer is selected)
  • Purpose: GitHub Actions workflow that runs both deterministic and agent-based PR constraints

Deterministic failures block the PR; agent findings are posted as advisory PR comments. Parses HARNESS.md to extract PR-scoped constraints, splits them into deterministic and agent arrays, and processes each type appropriately. Configurable via environment variables: INCLUDE_CONSTRAINTS, EXCLUDE_CONSTRAINTS, AGENT_MODEL, COMMENT_MODE, MAX_DIFF_SIZE. Requires ANTHROPIC_API_KEY as a GitHub Actions secret for agent constraints. Uses pinned action versions (SHA references) for supply chain safety.

ci-generic.sh

  • Template: templates/ci-generic.sh
  • Generated by: /harness-init (offered for non-GitHub-Actions CI systems)
  • Purpose: Shell script fallback for enforcing PR-scoped constraints in any CI system (Jenkins, GitLab CI, CircleCI, etc.)

Uses set -euo pipefail strict mode. Ships as a skeleton — deterministic tool invocations are added as constraints are promoted. No dependencies beyond bash.

ci-mutation-testing.yml

  • Template: templates/ci-mutation-testing.yml
  • Generated by: /superpowers-init (offered during CI setup)
  • Purpose: Weekly mutation testing job that verifies the test suite catches real defects

Scheduled weekly (Monday 07:00 UTC) with manual dispatch option. Provides commented job blocks for four language ecosystems: Go (go-mutesting), Kotlin/JVM (PIT via Maven), Python (mutmut), and C#/.NET (Stryker.NET). Each block includes setup, tool installation, mutation run with configurable score threshold, and artifact upload.

Assets

harness-health-icon.svg

  • Template: templates/harness-health-icon.svg
  • Generated by: /harness-health
  • Purpose: SVG icon for harness health output — a pulse line inside a shield shape

The shield represents the harness (enforcement and protection), while the pulse line represents observability and monitoring.

How templates are used

Templates are consumed by commands, not by users directly:

  1. A command reads a template from ${CLAUDE_PLUGIN_ROOT}/templates/.
  2. The command replaces placeholders with values discovered from the project (stack detection, user answers to prompts).
  3. The command writes the result to the project root or a subdirectory (e.g. .github/workflows/).
  4. The generated file becomes a living document — the user and subsequent commands edit it freely.

Templates are not referenced at runtime after generation. All runtime behaviour reads the generated files in the project directory.