diff --git a/README.md b/README.md index ea71e15..2dc619a 100644 --- a/README.md +++ b/README.md @@ -2,31 +2,8 @@ This repository is a [Copier](https://copier.readthedocs.io/) template that generates a language-independent, contract-first AI coding harness: an `AGENTS.md` agent contract, a `decisions/` directory of durable workflow contracts, a `docs/` boundary, and a .gitignored `notes_local/` private-notes convention. -
-Why this harness? - -- **Contract before code.** Establish a reviewable source of truth before implementation. - - [**Clarify requirements.**](decisions/development.md): Turn uncertain goals and domain knowledge into a design before execution. Use dialogue—such as Superpowers' brainstorming workflow[^superpowers]. - - [**Test before implementation.**](decisions/testing-policy.md): Verifiability over readability[^shinaoka] moves trust from line-by-line reading to tests and external oracles; readable intent remains in the contract. - - **Make the ontology explicit.** Name the domain entities, relationships, responsibilities, and reasons before implementation mechanics. ("Why" constrains future "how"; "how" alone only describes today's code.) -- **Give the agent a map, not the whole repository.** Self-describing files and linked maps of content keep concerns decoupled, help humans navigate, and spend limited context tokens only on the contracts and decisions relevant to the current task. -- **Improve the production line.** Agents necessitate a new craftsmanship: review and improve the production line, not only each product. Generalize recurring failures into repository-resident contracts, tests, decisions, or procedures so the next run is constrained by what the project has learned.[^shinaoka][^sustainable-automation] - -
- **This template owns only the harness layer.** It ships no language tooling; when overlaid onto an existing project you review and resolve the resulting diff yourself. -## Prerequisite: uv - -[`uv`](https://docs.astral.sh/uv/) is the modern Python package and project manager written in Rust. Here, its `uvx` command runs Copier in an isolated temporary environment, so Copier need not be installed globally. Install `uv` with the commands: - -```bash -# macOS and Linux -curl -LsSf https://astral.sh/uv/install.sh | sh -# Windows PowerShell -powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -``` - ## Standalone generation Generate a fresh project from the harness (swap `gh:…` for a local path to render from a clone): @@ -66,34 +43,51 @@ Pull a newer harness version independently of the host's own templates: uvx copier update -a .copier-answers.harness.yml ``` -### Why a separate answers file +### Why a separate harness answers file -A host project generated from another template already owns `.copier-answers.yml`; the `-a` flag stores this harness's answers in `.copier-answers.harness.yml`, keeping both template layers independently updateable, while standalone generation without `-a` still uses the default file. +A host project generated from a language or native Copier template already owns `.copier-answers.yml`. Writing the harness's answers to a dedicated `.copier-answers.harness.yml` keeps the two layers from colliding, so each can be applied, re-answered, and updated with `copier update` on its own. The answers filename is templated as `{{ _copier_conf.answers_file }}.jinja`, so the `-a` flag chooses the layer; standalone generation with no flag still produces the default `.copier-answers.yml`. | Answers file | Owns | Written by | | --- | --- | --- | | `.copier-answers.yml` | the host project's own template | standalone generation, or the host's native template | | `.copier-answers.harness.yml` | this harness layer | `copier copy`/`update -a .copier-answers.harness.yml` | +## Generated topology + +``` +new-project/ +├── README.md # project boundary sentence and contributor pointers +├── AGENTS.md # executable contract for coding agents +├── CLAUDE.md # shim: @AGENTS.md +├── .gitignore # .DS_Store, .claude, notes_local/ +├── .copier-answers.yml # enables `copier update` +├── decisions/ # durable development-process contracts +│ ├── README.md +│ ├── development.md # four-role workflow loop and change control +│ ├── documentation-style.md +│ └── testing-policy.md +├── docs/README.md # public-result boundary, empty until results exist +└── notes_local/ # private notes placeholder; omit via include_notes_local +``` + ## Develop the template -Files under `template/` are copied verbatim unless their names end in `.jinja`, in which case Copier renders them. Validate with: +Generated files live under `template/`; `.jinja` files are rendered, and other files are copied verbatim. Validate with: ```bash uv run --with copier --with pytest --with pyyaml -- pytest tests/ ``` -## Project map +## [Roadmap](docs/roadmap.md) + +Incremental milestones and their status. + +## For contributors -- [Roadmap](docs/roadmap.md) tracks incremental milestones and their status. - [AGENTS.md](AGENTS.md) is the executable contract for coding agents. - [decisions/](decisions/) records durable development-process decisions. - [docs/](docs/) presents the public project result. - `notes_local/` holds private local notes; it is gitignored and must not define project behavior. -- [User-level agent config](docs/user-level-agent-config.md) shows where advanced users can keep personal defaults. - -## References and suggested reading -[^superpowers]: obra, [*Superpowers*](https://github.com/obra/superpowers): composable, enforceable workflows for agentic software development. -[^shinaoka]: Hiroshi Shinaoka, [*Agentic AI Coding × Rust*](https://shinaoka.github.io/docs/agentic-ai-coding-rust): growing computational-physics code through mechanical verification and an evolving source of truth. -[^sustainable-automation]: Quantum Bay, [*Sustainable Automation: Programming the Programmer*](https://www.jinguo-group.science/sustainable-automation/): persistent instructions and reusable skills for human–AI collaboration across sessions. +> [!NOTE] +> Advanced users can keep personal defaults in user-level agent config; see [user-level agent config](docs/user-level-agent-config.md). diff --git a/docs/roadmap.md b/docs/roadmap.md index d466b40..aa533a9 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -19,9 +19,9 @@ This file tracks milestones for proving the harness as a reusable agent-governan ## Near-term reliability - [ ] Dogfood existing projects - - [x] Julia - - [x] Python/PyTorch - - [ ] Rust + - [ ] Julia + - [ ] Python/PyTorch + - [ ] Obsidian - [ ] CI drift-check that self-reference stays in sync with `template/` - [ ] Add rendered-fixture tests for standalone and overlay generation diff --git a/template/AGENTS.md.jinja b/template/AGENTS.md.jinja index 0c615f5..582181d 100644 --- a/template/AGENTS.md.jinja +++ b/template/AGENTS.md.jinja @@ -8,24 +8,76 @@ When instructions conflict, follow this priority: user prompt > AGENTS.md > loca ## Project governance -Read the relevant durable contract before working in its area: - -- [development.md](decisions/development.md): roles, uncertainty routing, and workflow change control; -- [implementation-policy.md](decisions/implementation-policy.md): topology evolution, complexity boundaries, and redesign evidence; -- [testing-policy.md](decisions/testing-policy.md): public behavior and independent acceptance evidence; -- [documentation-style.md](decisions/documentation-style.md): documentation ownership and authoring rules; -- [delivery.md](decisions/delivery.md): completion, validation, reporting, and repository actions. +Read [development.md](decisions/development.md) before making workflow-level changes. Do not modify project scope, dependencies, or public contracts without explicit maintainer approval. -{% if include_notes_local %}Private local notes belong in `notes_local/` and should not be committed.{% endif %} +- Public project documentation belongs in [docs/](docs/). +- Development-process decisions belong in [decisions/](decisions/).{% if include_notes_local %} +- Private local notes belong in `notes_local/` and should not be committed.{% endif %} + +## Contract-first workflow + +Contract precedes implementation. + +For code: + +- define public input/output behavior first; +- write tests against the public boundary before relying on internals; +- if a test must depend on hidden implementation details, refactor until the real boundary is explicit; +- create skeletons before internal logic. + +For docs: + +- create headings before prose; +- pseudo-code is preferred over prose in planning for clarifying language-independent design before real code implementation. + +## Documentation budget + +Markdown files should stay under 100 lines. If a file grows beyond that, apply: + +1. pruning — delete stale, repeated, or non-actionable text; +2. refactor — split durable subtopics into linked files; +3. compress — shorten language without weakening the contract. + +## Formatting policy -## Core boundaries +- Do not manually reflow code only for visual alignment. +- Do not hard-wrap anything beyond code, such as Markdown, comments, git commit messages, and docstrings, merely to satisfy a visual line length. +- For prose, prefer semantic line breaks: one sentence or one logical clause per line when helpful. -Contract precedes implementation; "why" precedes "how". +## Implementation policy + +- Execution briefs must optimize for the smallest conceptual diff, not the cleanest-looking architecture. +- Prefer a correct plain-code first pass. +- After the code works, simplify by removing unnecessary helpers, wrappers, and dead structure. +- Do not add abstraction before two concrete uses or an explicit contract boundary. +- When implementation friction appears, produce the smallest failing evidence before proposing a broader redesign. + +## Definition of done + +A task is done only when: -- do not weaken tests, oracles, or acceptance thresholds to make an implementation pass; - the diff is limited to the requested scope; -- do not commit, push, or open pull requests unless explicitly requested. +- relevant tests were added or updated; +- validation commands ran or the reason for not running is stated. + +This project has no language tooling yet; record its validation commands here once it does, following the change control in [development.md](decisions/development.md). + +If a command is not run, state why. + +## Completion report + +Do not commit, push, or open pull requests unless explicitly requested. + +After completing a task, report: + +- what changed; +- what was validated; +- what was not validated and why; +- any remaining blocker; +- a suggested commit message. + +Suggested commit messages, and any commit made when explicitly asked, use an `Assisted-By:` trailer naming the executing agent (for example `Assisted-By: `), never `Co-Authored-By:`. -Complete work according to [delivery.md](decisions/delivery.md), including validation and reporting requirements. +The developer reviews the diff and performs the commit manually. diff --git a/template/README.md.jinja b/template/README.md.jinja index c20be49..c6cb762 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -2,13 +2,9 @@ {{ description }} -## Project Map +## For contributors - [AGENTS.md](AGENTS.md) is the executable contract for coding agents. -- The [development workflow](decisions/development.md) defines roles, stages, and uncertainty routing. -- The [delivery policy](decisions/delivery.md) defines completion, validation, and repository-action boundaries. -- The [implementation policy](decisions/implementation-policy.md) defines how topology may evolve without unnecessary expansion. -- The [testing policy](decisions/testing-policy.md) defines public acceptance evidence. -- The [documentation style](decisions/documentation-style.md) defines how the repository keeps its source of truth readable. +- [decisions/](decisions/) records durable development-process decisions. - [docs/](docs/) presents the public project result.{% if include_notes_local %} - `notes_local/` holds private local notes; it is gitignored and must not define project behavior.{% endif %} diff --git a/template/decisions/README.md.jinja b/template/decisions/README.md.jinja index 23b225e..301725d 100644 --- a/template/decisions/README.md.jinja +++ b/template/decisions/README.md.jinja @@ -9,9 +9,7 @@ If the rationale only matters at one location, it belongs as a `NOTE` comment th ## Map of Contents - [development.md](development.md): AI-assisted development roles and workflow change control. -- [delivery.md](delivery.md): completion, validation, reporting, and repository-action policy. - [documentation-style.md](documentation-style.md): documentation style choices including markdown conventions. -- [implementation-policy.md](implementation-policy.md): topology evolution, complexity boundaries, and redesign evidence. - [testing-policy.md](testing-policy.md): what tests must and must not specify about public boundaries. ## See also diff --git a/template/decisions/delivery.md b/template/decisions/delivery.md deleted file mode 100644 index 0090331..0000000 --- a/template/decisions/delivery.md +++ /dev/null @@ -1,31 +0,0 @@ -# Delivery Policy - -This file defines when work is complete and how an agent hands it back to the developer. - -## Definition of Done - -A task is done only when: - -- the diff is limited to the requested scope; -- relevant tests were added or updated; -- validation commands ran or the reason for not running is stated. - -Record the project's validation commands in [AGENTS.md](../AGENTS.md) once language tooling exists, following the change control in [development.md](development.md). - -## Repository Actions - -The developer reviews the diff and normally performs the commit manually. - -## Completion Report - -After completing a task, report: - -- what changed; -- what was validated; -- what was not validated and why; -- any remaining blocker; -- a suggested commit message. - -## Commit Attribution - -Suggested commit messages, and any commit made when explicitly requested, use an `Assisted-By:` trailer naming the executing agent (for example `Assisted-By: `), never `Co-Authored-By:`. diff --git a/template/decisions/development.md.jinja b/template/decisions/development.md.jinja index 7df5bcb..51896bb 100644 --- a/template/decisions/development.md.jinja +++ b/template/decisions/development.md.jinja @@ -15,20 +15,7 @@ Use a four-role loop for nontrivial development work where the role boundary is - Architecture reviewer: topology, contracts, documentation boundaries - Execution agent: executable identity, local API details, tests, and concrete diffs -The pipeline is allowed to iterate. - -- If implementation exposes a wrong abstraction or repeated failure, return to *the Architecture reviewer*; - - accepted lessons update the appropriate contract, decision, test, or rule. -- If architecture review exposes missing theory or package-level uncertainty, return to *the Exploration agent*. -- If exploration produces multiple plausible routes, the Human selects or rejects based on project taste and observed cost. - -## Exploration and Brainstorming - -Exploration is a role for knowledge-surface uncertainty: theory, domain facts, existing methods, and dependency ecosystems. Its provider binding records who performs that role. - -Brainstorming is a procedure for design uncertainty: use dialogue and human review to clarify goals, constraints, alternatives, and acceptance criteria. Any role or tool may perform it. - -Exploration may supply evidence to brainstorming and may recur when architecture review exposes a knowledge gap. +The pipeline is allowed to iterate. If implementation exposes a wrong abstraction, return to *the Architecture reviewer*. If architecture review exposes missing theory or package-level uncertainty, return to *the Exploration agent*. If exploration produces multiple plausible routes, the Human selects or rejects based on project taste and observed cost. ## Current Bindings diff --git a/template/decisions/documentation-style.md b/template/decisions/documentation-style.md index 06516c2..90d0174 100644 --- a/template/decisions/documentation-style.md +++ b/template/decisions/documentation-style.md @@ -10,23 +10,6 @@ This file defines the conventions for all natural-language documentation in this - Content belongs in a file only when that file's boundary explains why it belongs there. - Delete prose that changes no decision, behavior, or reader action. -## Authoring Workflow - -- Create headings before prose. -- Prefer pseudo-code to prose in planning when it clarifies language-independent design before implementation. - -## Budget and Formatting - -Markdown files should stay under 100 lines. If a file grows beyond that, apply: - -1. pruning — delete stale, repeated, or non-actionable text; -2. refactor — split durable subtopics into linked files; -3. compress — shorten language without weakening the contract. - -- Do not manually reflow code only for visual alignment. -- Do not hard-wrap Markdown, comments, git commit messages, or docstrings merely to satisfy a visual line length. -- For prose, prefer semantic line breaks: one sentence or one logical clause per line when helpful. - ## Markdown file references - Use Markdown links, `[name](path)`, for repository files that function as documentation nodes. diff --git a/template/decisions/implementation-policy.md b/template/decisions/implementation-policy.md deleted file mode 100644 index 6c8a8f9..0000000 --- a/template/decisions/implementation-policy.md +++ /dev/null @@ -1,24 +0,0 @@ -# Implementation Policy - -This file defines how implementation topology evolves from declared structure into working semantics without unnecessary expansion. - -## Topology Evolution - -Treat structure and behavior as coupled axes: - -- Vertical evolution creates skeletons before internal logic so syntactic topology exists before unit semantics fill it. -- Horizontal evolution follows 3M principle: - - make it work — write the smallest plain-code implementation that satisfies the contract; - - make it right — simplify the working code and align its units with the declared topology; - - make it fast — optimize only against explicit performance evidence and a relevant benchmark. - -## Complexity Boundary - -- Optimize execution briefs for the smallest conceptual diff (keep it stay simple). If the requested scope is over-designed, surface the simpler route before implementation. -- Add abstraction only when required by multiple concrete uses or an explicit contract boundary. - -## Redesign Gate - -When implementation friction appears, produce the smallest failing evidence before proposing a broader redesign. - -A broader redesign must identify which existing boundary fails and why a local correction is insufficient. diff --git a/template/decisions/testing-policy.md b/template/decisions/testing-policy.md index 68dc093..8d3313d 100644 --- a/template/decisions/testing-policy.md +++ b/template/decisions/testing-policy.md @@ -8,8 +8,7 @@ Tests should specify: - observable outputs; - invariants; - error behavior; -- minimal integration paths; -- acceptance thresholds and external oracles when relevant. +- minimal integration paths. Tests should not specify: @@ -17,7 +16,3 @@ Tests should not specify: - incidental intermediate state; - implementation ordering; - formatting-only behavior. - -Write tests against the public boundary before relying on internals. If a test must depend on hidden implementation details, refactor until the real boundary is explicit. - -An implementation must not change expected results, acceptance thresholds, or external oracles merely to make itself pass. diff --git a/tests/test_generation.py b/tests/test_generation.py index aeb043c..a9cd22c 100644 --- a/tests/test_generation.py +++ b/tests/test_generation.py @@ -20,10 +20,8 @@ ".gitignore", ".copier-answers.yml", "decisions/README.md", - "decisions/delivery.md", "decisions/development.md", "decisions/documentation-style.md", - "decisions/implementation-policy.md", "decisions/testing-policy.md", "docs/README.md", "notes_local/README.md",