refactor: align harness boundaries with reusable agent workflows

[swanchristmas]

Summary

Refine the harness boundary so repository-resident files define project-specific contracts and governance, while reusable development procedures can be supplied by external agent skills such as Superpowers.

Changes

• Reduce AGENTS.md to executable project constraints, precedence rules, and links to durable policies.
• Separate exploration roles from brainstorming and other reusable workflow procedures.
• Add an implementation policy covering topology evolution, the 3M sequence, complexity boundaries, and redesign gates.
• Add a delivery policy covering the definition of done, validation reporting, repository actions, and commit attribution.
• Clarify the ownership boundaries between executable agent rules, durable development decisions, public documentation, and transient execution state.
• Update the project README and roadmap to document the refined harness model and reference Superpowers as an optional workflow provider.
• Extend template-generation tests to include the new policy files.

Rationale

The harness should preserve project-specific knowledge, constraints, and reviewable decisions without duplicating general-purpose agent workflows.

This separation:

• keeps generated agent context smaller and more stable;
• prevents tool-specific procedures from becoming repository policy;
• allows workflows such as brainstorming, test-driven development, and verification to evolve independently;
• preserves explicit human review before commits, pushes, or pull requests.

Superpowers is therefore treated as a compatible workflow layer rather than a vendored or mandatory dependency.

Validation

uv run --with copier --with pytest --with pyyaml -- pytest tests/

[Copilot]

Pull request overview

Refines the “harness boundary” so repository-resident files capture project-specific contracts/governance, while reusable workflows can be supplied externally (e.g., via agent skills), and updates the template + docs to reflect and test that model.

Changes:

• Re-scopes AGENTS.md to core executable constraints and pushes durable workflow policy into decisions/ (including new delivery + implementation policy docs).
• Updates project maps (root README and templated README) to point at the refined contract/policy files.
• Extends template-generation tests to assert the new durable policy files are rendered.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/test_generation.py	Ensures generated projects include the new durable decision/policy files.
template/README.md.jinja	Updates the generated project README “map” to reference the refined decision/policy boundaries.
template/decisions/testing-policy.md	Expands testing contract language around acceptance thresholds/oracles and boundary-first testing.
template/decisions/README.md.jinja	Adds new decision/policy documents to the decisions directory index.
template/decisions/implementation-policy.md	Introduces an implementation/topology evolution policy (3M, complexity boundary, redesign gate).
template/decisions/documentation-style.md	Adds authoring workflow + formatting/budget rules for documentation.
template/decisions/development.md.jinja	Clarifies iteration routing and separates “exploration” (role) from “brainstorming” (procedure).
template/decisions/delivery.md	Adds delivery/completion, validation reporting, and commit attribution policy.
template/AGENTS.md.jinja	Narrows AGENTS.md to executable boundaries and links to the durable contracts in decisions/.
README.md	Documents the refined harness model and adds uv prerequisite + expanded project map/references.
docs/roadmap.md	Updates near-term dogfooding checklist items/status.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.