diff --git a/AGENTS.md b/AGENTS.md index 303cf107..1fae8c12 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,6 @@ - `AGENTS.md` is our constitution. Propose useful amendments. - Resilient parser with user-friendly error messages called "diagnostics" (see `diagnostics/`) - Stability via invariants: `panic!`/`assert!`/`.expect()` for simple cases, `invariants.rs` otherwise -- AI agents create ADRs when architectural decisions are made # Documentation @@ -141,29 +140,6 @@ A = (foo (B)) B = (bar (A)) ; OK: descends each step Tree-sitter: `((a) (b))` — Plotnik: `{(a) (b)}`. The #1 syntax error. -# Architecture Decision Records (ADRs) - -- **Location**: `docs/adr/` -- **Naming**: `ADR-XXXX-short-title-in-kebab-case.md` (`XXXX` is a sequential number). -- **Index**: - - _(no ADRs yet)_ -- **Template**: - -```markdown -# ADR-XXXX: Title - -- **Status**: Proposed | Accepted | Deprecated | Superseded by [ADR-YYYY](ADR-YYYY-...) -- **Date**: YYYY-MM-DD - -## Context - -## Decision - -## Consequences - -- **Positive** | **Negative** | **Alternatives Considered** -``` - # Project Structure ``` @@ -185,7 +161,6 @@ crates/ plotnik-langs/ # Tree-sitter language bindings plotnik-macros/ # Proc macros docs/ - adr/ # Architecture Decision Records binary-format/ # Bytecode format specification lang-reference.md # Language specification ``` diff --git a/docs/README.md b/docs/README.md index e1d87558..2e53a79a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,7 +20,7 @@ Plotnik is a strongly-typed pattern matching language for tree-sitter syntax tre ## Document Map ``` -AGENTS.md # Project constitution (coding rules, testing, ADRs) +AGENTS.md # Project constitution (coding rules, testing) docs/ ├── README.md # You are here ├── cli.md # CLI tool usage guide @@ -58,4 +58,3 @@ Building tooling: Contributing: 1. `AGENTS.md` — Required reading -2. ADRs in `docs/adr/` — Architectural context diff --git a/docs/adr/README.md b/docs/adr/README.md deleted file mode 100644 index f2a74138..00000000 --- a/docs/adr/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# The Plotnik ADR System - -An ADR system documents important architectural decisions, their context, and their consequences. This helps maintain architectural consistency and provides valuable context for current and future contributors. - -## 1. Location - -As hinted at in your `AGENTS.md`, the best place for these is `docs/adr/`. - -## 2. Naming Convention - -Files should be named `ADR-XXXX-short-title-in-kebab-case.md`, where `XXXX` is a sequential number (e.g., `0001`, `0002`). - -## 3. ADR Template - -Create a file named `ADR-0000-template.md` in the `docs/adr/` directory with the following content. This makes it easy for anyone to start a new record. - -```markdown -# ADR-XXXX: Title of the Decision - -- **Status**: Proposed | Accepted | Deprecated | Superseded by [ADR-YYYY](ADR-YYYY-...) -- **Date**: YYYY-MM-DD - -## Context - -Describe the issue, problem, or driving force that led to this decision. What are the constraints and requirements? What is the scope of this decision? This section should be understandable to someone without deep project knowledge. - -## Decision - -Clearly and concisely state the decision that was made. This is the "what," not the "why." - -## Consequences - -This is the most critical section. Describe the results, outcomes, and trade-offs of the decision. - -### Positive Consequences - -- What benefits does this decision provide? -- How does it align with the project's goals (e.g., resilience, user experience, performance)? - -### Negative Consequences - -- What are the drawbacks or costs? -- What trade-offs were made? -- What future challenges might this decision introduce? - -### Considered Alternatives - -- **Alternative 1:** A brief description of a rejected option. - - _Pros_: Why was it considered? - - _Cons_: Why was it rejected? -- **Alternative 2:** ... -```