Skip to content

docs(architecture): sweep every chapter for the chapter style #2422

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
braboj merged 1 commit into from
Oct 31, 2026
Merged

docs(architecture): sweep every chapter for the chapter style #2422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions docs/architecture/02-constraints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ The givens the design accepts rather than chooses.

| # | Constraint | In practice | Source |
|---|------------|-------------|--------|
| 1 | Plain Markdown, no build step | A template is read as written; nothing compiles or packages it. Python is needed only for the tools and checks | ADR-007, FR-05-01 |
| 1 | Plain Markdown, no build step required | A template is read as written, and nothing compiles or packages it. Python runs the tools, the checks and the optional emitter | ADR-007, FR-05-01 |
| 2 | Agent-agnostic | Any agent that reads a Markdown context file can use the output, such as Claude Code, Codex CLI, Cursor or GitHub Copilot | FR-05-04 |
| 3 | Generation is an agent reading Markdown | No compiler sits between the fork and the context file; instructions use neutral wording ("ask the user") | ADR-007, FR-05-01 |
| 3 | An agent can generate by reading Markdown | No tool is needed between the templates and the context file, and instructions use neutral wording ("ask the user"). The emitter, where a project runs it, builds the same files | ADR-007, FR-05-01; ADR-058, proposed |
| 4 | Context windows are finite | Every rule in the root file is read on every turn by every project on that chain. A task's procedures load only when that task starts | ADR-041, ADR-058, QG-02-02 |

## 2.2 Compatibility constraints
Expand All @@ -20,18 +20,18 @@ The givens the design accepts rather than chooses.

## 2.3 Organisational constraints

| # | Constraint | In practice |
|---|------------|-------------|
| 1 | One maintainer | Automated checks carry the review load, the maintainer approves every merge, and triage runs in batches |
| 2 | MIT licence | Anyone may fork the templates, use them commercially and keep the fork private, so upstream cannot rely on seeing its forks |
| 3 | Built by agents | Agents develop and review this repository, and the maintainer specifies and approves. Every procedure is one an agent can follow |
| 4 | Hosted on GitHub | Issues, pull requests, CI and the fork model all run on GitHub |
| # | Constraint | In practice | Source |
|---|------------|-------------|--------|
| 1 | One maintainer | Automated checks carry the review load, the maintainer approves every merge, and triage runs in batches | Chapter 1, Maintainer |
| 2 | MIT licence | Anyone may fork the templates, use them commercially and keep the fork private, so upstream cannot rely on seeing its forks | `LICENSE` |
| 3 | Built by agents | Agents develop and review upstream, and the maintainer specifies and approves. Every procedure is one an agent can follow | Chapter 1, Team |
| 4 | Hosted on GitHub | Issues, pull requests, CI and the fork model all run on GitHub | - |

## 2.4 Conventions

| # | Convention | In practice |
|---|------------|-------------|
| 1 | arc42 | The architecture is one chapter per file, indexed by `docs/spec.md` |
| 2 | RFC 2119 | A rule is a plain imperative or carries MUST, SHOULD or MAY |
| 3 | Kebab-case file names | Every document under `docs/` and every template |
| 4 | Line width 88 | Declared in `.editorconfig` and the markdownlint config, and enforced on every Markdown file |
| # | Convention | In practice | Source |
|---|------------|-------------|--------|
| 1 | arc42 | The architecture is one chapter per file, indexed by `docs/spec.md` | `docs/spec.md` |
| 2 | RFC 2119 | A rule is a plain imperative or carries MUST, SHOULD or MAY | FR-01-01 |
| 3 | Kebab-case file names | Every document under `docs/` and every template | - |
| 4 | Line width 88 | Declared in `.editorconfig` and the markdownlint config, and enforced on every Markdown file | `.editorconfig` |
42 changes: 21 additions & 21 deletions docs/architecture/03-context-and-scope.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@
Upstream as one box, with the people and systems on its boundary. In and
out are seen from upstream.

![Upstream as one box with its neighbours. A fork maintainer sends reports and proposals in and takes the engine, templates and checks out by merge. An upstream contributor sends rule changes with evidence in and gets admission or a reasoned decline. A team using agents gets the templates and tools, from upstream or a fork, by clone or submodule. A coding agent gets the chain, the output contract and the task skills, and writes the context file from them. solid-ai-dirigent takes the rules as a pinned submodule. solid-ai-benchmark takes a tagged ref and returns efficacy results. pre-commit in a project's CI takes the shipped hooks. GitHub holds the repository and returns issues, pull requests and CI runs](../diagrams/context-business.png)
![Upstream as one box with its neighbours. A fork maintainer sends reports and proposals in and takes the engine, templates and checks out by merge. A contributor sends rule changes with evidence in and gets admission or a reasoned decline. A team gets the templates and tools, from upstream or a fork, by submodule, clone or copy. A coding agent gets the chain, the output contract and the task skills, and writes the context file from them. solid-ai-dirigent takes the rules as a pinned submodule. solid-ai-benchmark takes a tagged ref and returns efficacy results. pre-commit in a project's CI takes the shipped hooks. GitHub holds the repository and returns issues, pull requests and CI runs](../diagrams/context-business.png)

| Neighbour | Gives upstream | Gets from upstream | Source |
|-----------|----------------|--------------------|--------|
| Fork maintainer | Reports and proposals for shared rules | The engine, the shared templates and the checks, by merge | FR-08-01, FR-08-02, ADR-049 |
| Upstream contributor | A rule change with evidence that it helps | Admission, or a decline with its reason | FR-10-01, FR-10-02 |
| Team using agents | - | The templates and tools, from upstream or from a fork for its stacks, by clone or submodule | FR-08-04 |
| Contributor | A rule change with evidence that it helps | Admission, or a decline with its reason | FR-10-01, FR-10-02 |
| Team | - | The templates and tools, from upstream or from a fork for its stacks, by submodule, clone or copy, or only the generated files or the hooks | FR-08-04 |
| Coding agent | - | The chain, the output contract and the task skills, from which it writes the project's context file | FR-05-01, FR-05-02, FR-05-04, FR-06-04 |
| solid-ai-dirigent | - | The rules its developer and reviewer agents follow, as a pinned submodule | FR-08-04 |
| solid-ai-benchmark | Efficacy results for a release | A tagged ref to measure | QG-01-02 |
Expand All @@ -22,24 +22,24 @@ out are seen from upstream.

Each exchange of 3.1, the channel that carries it and who opens it.

| Exchange | Transport | Opened by |
|----------|-----------|-----------|
| Upstream changes to a fork | `git fetch upstream` from GitHub | The fork maintainer |
| Reports and proposals | An issue on GitHub, through an issue form | The reporter |
| A rule change with evidence | A pull request on GitHub | The contributor |
| Templates and tools to a project, solid-ai-dirigent among them | A clone, or a submodule pinned to a released tag, from upstream or a fork | The project |
| Chain and task skills to an agent | Files in the project's checkout, read through `tools/resolve_chain.py` | The agent |
| Hooks to a project's CI | pre-commit fetches upstream at a pinned revision | The project's pre-commit |
| A release to the benchmark | A clone of upstream or a fork at the release registered for the round | The benchmark |
| Efficacy results to upstream | A pull request adding the round's report under `docs/audits/` | The maintainer |
| Repository and CI runs | `git push` to GitHub, and Actions on every pull request and push to `main` | The maintainer and CI |
| Exchange | Transport | Opened by | Source |
|----------|-----------|-----------|--------|
| Upstream changes to a fork | `git fetch upstream` from GitHub | The fork maintainer | FR-08-01 |
| Reports and proposals | An issue on GitHub, through an issue form | The reporter | - |
| A rule change with evidence | A pull request on GitHub | The contributor | FR-10-01 |
| Templates and tools to a project, solid-ai-dirigent among them | A submodule, clone or copy at a released tag, from upstream or a fork | The project | FR-08-04 |
| Chain and task skills to an agent | Files in the project's checkout, read through `tools/resolve_chain.py` | The agent | FR-04-01, FR-05-01 |
| Hooks to a project's CI | pre-commit fetches upstream at a pinned revision | The project's pre-commit | FR-07-02, ADR-055 |
| A release to the benchmark | A clone of upstream or a fork at the release registered for the round | The benchmark | QG-01-02 |
| Efficacy results to upstream | A pull request adding the round's report under `docs/audits/` | The maintainer | QG-01-02 |
| Repository and CI runs | `git push` to GitHub, and Actions on every pull request and push to `main` | The maintainer and CI | FR-10-01 |

## 3.3 Out of scope

| Out of scope | Handled by |
|--------------|------------|
| Product requirements and specifications | The team |
| Issue tracking and project management | GitHub, or the team's own tracker |
| Task planning and multi-agent orchestration | An orchestrator, such as solid-ai-dirigent |
| General-purpose procedures and prompt libraries, beyond the task skills built from template rules | A skill set, such as solid-ai-skills |
| CI infrastructure | The project's CI, such as GitHub Actions |
| Out of scope | Handled by | Source |
|--------------|------------|--------|
| Product requirements and specifications | The team | Chapter 1, Team |
| Issue tracking and project management | GitHub, or the team's own tracker | - |
| Task planning and multi-agent orchestration | An orchestrator, such as solid-ai-dirigent | Chapter 1 |
| General-purpose procedures and prompt libraries, beyond the task skills built from template rules | A skill set, such as solid-ai-skills | Chapter 1 |
| CI infrastructure | The project's CI, such as GitHub Actions | - |
8 changes: 3 additions & 5 deletions docs/architecture/04-solution-strategy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ catch it, copied into its context; any other rule may stay a reference.
| A rule whose breach is silent, and which no tool enforces, reaches the agent copied in. Any other rule may stay a reference | Nothing loads a referenced file, so a silent rule left there is missed, while a visible one still shows | ADR-052 |
| Each section declares where its rules load, on every turn or for a named task | The root file stays short, and a procedure loads only when its task starts | ADR-058, proposed; FR-06-01, QG-02-02 |
| A tool builds the root file and the task skills from the resolved chain | The same templates give every project the same files | ADR-058, proposed; FR-06-03, FR-06-06 |
| A mechanically checkable rule names its command and pass condition. This repository gives every such check a disposition, and runs each one that applies here | A rule upstream ships is one upstream obeys, and a skip states its reason | ADR-030, ADR-031, FR-07-01, QG-01-01 |
| A mechanically checkable rule names its command and pass condition. Upstream gives every such check a disposition, and runs each one that applies to it | A rule upstream ships is one upstream obeys, and a skip states its reason | ADR-030, ADR-031, FR-07-01, QG-01-01 |
| The 3.x line freezes its contract, and a removal waits for the next major, except for a security fix | A project pins a release and moves the pin without rework | ADR-051, FR-09-01, FR-09-02, QG-03-02 |

## 4.2 Delivery model
Expand All @@ -24,15 +24,13 @@ catch it, copied into its context; any other rule may stay a reference.

A rule whose breach is silent, with no test, linter or CI step to catch it,
is copied into the context file. A rule that fails visibly, or that a tool
enforces, may stay a reference to the file that holds it. ADR-058 proposes
the next step, in which each section declares its load and a tool places
it.
enforces, may stay a reference to the file that holds it.

## 4.3 Technology decisions

| Decision | Why | Source |
|----------|-----|--------|
| Plain Markdown for the templates | Any agent reads them, and no build step stands between a rule and the agent | ADR-007, FR-05-01, FR-05-04 |
| Plain Markdown for the templates | Any agent reads them, and no build step is required between a rule and the agent | ADR-007, FR-05-01, FR-05-04 |
| YAML for the manifest | A person and a tool read the same file | FR-03-01 |
| Python for the resolver, the tests and the hooks | One language for every tool and check, on every platform the maintainer and CI use | Chapter 2, 2.1 #1 |
| pre-commit to ship a check over 15 lines | A project runs a shipped check in its own CI, at a pinned revision | ADR-055, FR-07-02 |
Expand Down
Loading
Loading