diff --git a/AGENTS.md b/AGENTS.md index 1cb85c3..d676687 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,10 +10,11 @@ If an agent starts in this repository, it must orient by these files, not by hid 2. `ARCHITECTURE.md` 3. `OPERATIONS.md` 4. `PRINCIPLES.md` -5. `STATE.md` if it exists; otherwise create it from `STATE.template.md` -6. `targets/README.md` if work touches an external repository -7. the active `targets/.local.md` target-pack if selected -8. the concrete `tasks/TASK-XXX.md` task file if assigned +5. `EVOLUTION.md` +6. `STATE.md` if it exists; otherwise create it from `STATE.template.md` +7. `targets/README.md` if work touches an external repository +8. the active `targets/.local.md` target-pack if selected +9. the concrete `tasks/TASK-XXX.md` task file if assigned ## Roles diff --git a/EVOLUTION.md b/EVOLUTION.md new file mode 100644 index 0000000..88b2e40 --- /dev/null +++ b/EVOLUTION.md @@ -0,0 +1,82 @@ +# EVOLUTION — Framework Evolution Protocol + +## Purpose + +This document defines how `multiagentsystem` adopts external ideas, research findings, and design patterns into its canonical layer. + +Without a formal evolution mechanism, good ideas either disappear into chat history or enter canon without review. This protocol ensures every meaningful external input leaves a traceable artifact. + +## Read-Order Position + +Required reading for all agents. Position in read-order: after `PRINCIPLES.md`, before `OPERATIONS.md`. + +An agent that does not know the evolution mechanism will either propose changes chaotically or ignore valuable external ideas. + +## The Four Stages + +### 1. Intake + +External ideas enter via: +- GitHub Issues with label `type:proposal` +- `research/` folder for source-level reviews +- GitHub Discussions (informal only --- no canonical decisions here) + +Rule: an idea without a GitHub artifact does not exist in the system. + +### 2. Research + +For any non-trivial idea: +1. Create a source review file in `research/` using `SOURCE_REVIEW_TEMPLATE.md` +2. Document: source, what it proposes, what fits our model, what conflicts, risk assessment +3. Reference the review from the intake issue + +### 3. Decision + +Accepted or rejected ideas become decisions: +1. Create a decision file in `decisions/` using `DECISION_TEMPLATE.md` +2. Status: `accepted` or `rejected` +3. Link to source review and intake issue +4. For `accepted`: add implementation tasks + +Rule: no external feature enters canon without a decision artifact. + +### 4. Promotion + +Accepted decisions are promoted into canon via Pull Requests: +- PR must reference the decision file +- PR must reference the source review +- PR must update affected canonical docs (AGENTS.md, OPERATIONS.md, etc.) +- PR must not introduce machine-local paths or product-specific references + +## What Goes Into `research/` + +Source reviews for: +- external repositories with patterns we might adopt +- articles, papers, or posts that propose architectural approaches +- internal experiments that should be documented before adoption + +Format: see `research/SOURCE_REVIEW_TEMPLATE.md`. + +## What Goes Into `decisions/` + +One file per design decision. Both accepted and rejected decisions are recorded. + +Rejected decisions are equally important --- they prevent re-litigating the same ground. + +Format: see `decisions/DECISION_TEMPLATE.md`. + +## Evolution vs Dispute + +Evolution: adopting or rejecting an external pattern. +Dispute: disagreement between agents or roles about an internal framework rule. + +Use `type:dispute` issues for disputes. Use `type:proposal` issues for evolution intake. + +## Canon Stability Rule + +During v5 evolution, existing canon is stable unless: +1. A decision artifact explicitly changes it +2. The change is implemented via PR with review +3. Affected docs are updated in the same PR + +Do not patch canon docs in side PRs without a linked decision. diff --git a/decisions/DECISION_TEMPLATE.md b/decisions/DECISION_TEMPLATE.md new file mode 100644 index 0000000..e3bdbdf --- /dev/null +++ b/decisions/DECISION_TEMPLATE.md @@ -0,0 +1,49 @@ +# DECISION-NNN: Short Title + +## Status + +`accepted` / `rejected` / `deferred` + +## Date + +YYYY-MM-DD + +## Context + +*(What problem or opportunity prompted this decision)* + +## Options considered + +### Option A + +*(Description)* + +Pros: +- + +Cons: +- + +### Option B + +*(Description)* + +Pros: +- + +Cons: +- + +## Decision + +*(What was decided and why)* + +## Consequences + +*(What changes as a result --- canonical docs, scripts, templates)* + +## Related + +- Source review: *(link to research/SOURCE-NNN.md if applicable)* +- Proposal issue: *(link)* +- Implementation PR: *(link when available)* diff --git a/decisions/README.md b/decisions/README.md new file mode 100644 index 0000000..11cd4d3 --- /dev/null +++ b/decisions/README.md @@ -0,0 +1,19 @@ +# decisions/ + +One file per design decision. Both accepted and rejected decisions are recorded here. + +## Naming + +`DECISION-NNN-short-title.md` (e.g. `DECISION-001-worktree-isolation-scope.md`) + +## Status values + +- `accepted` --- adopted into canon or implementation planned +- `rejected` --- explicitly not adopted, with rationale recorded +- `deferred` --- valid idea, not prioritized now, revisit condition noted + +## Index + +| Decision | Status | Summary | +|----------|--------|---------| +| *(none yet --- first decisions pending)* | | | diff --git a/research/README.md b/research/README.md new file mode 100644 index 0000000..ab99a86 --- /dev/null +++ b/research/README.md @@ -0,0 +1,23 @@ +# research/ + +Source reviews for external repositories, articles, and patterns considered for adoption into `multiagentsystem`. + +## When to create a review + +Create a source review when: +- you encounter an external repository with patterns worth evaluating +- a proposal issue references an external source +- you want to formally document why an external idea was rejected + +## How to create a review + +1. Copy `SOURCE_REVIEW_TEMPLATE.md` +2. Name it `SOURCE-NNN-short-name.md` (e.g. `SOURCE-001-oh-my-claudecode.md`) +3. Fill in all sections +4. Reference it from the related proposal issue + +## Completed reviews + +| File | Source | Decision | +|------|--------|----------| +| *(none yet --- first reviews pending)* | | | diff --git a/research/SOURCE_REVIEW_TEMPLATE.md b/research/SOURCE_REVIEW_TEMPLATE.md new file mode 100644 index 0000000..13dd0bc --- /dev/null +++ b/research/SOURCE_REVIEW_TEMPLATE.md @@ -0,0 +1,42 @@ +# SOURCE-NNN: Short Name + +## Source + +- Repository / URL: +- Author: +- License: +- Reviewed on: +- Reviewed by: + +## What it proposes + +*(2--4 sentences describing the core idea)* + +## What fits our model + +*(List of ideas that are compatible with multiagentsystem principles)* + +- + +## What conflicts + +*(List of ideas that conflict, with reason)* + +- + +## Risk assessment + +- Breaking changes to existing canon: yes / no +- Complexity: low / medium / high +- License compatibility: yes / no / unknown + +## Recommendation + +`adopt` / `adapt` / `reject` / `defer` + +*(One paragraph rationale)* + +## Related + +- Proposal issue: +- Decision file: *(fill after decision is made)*