From 8c9851542a49473de793c946e76314118ecf9b12 Mon Sep 17 00:00:00 2001 From: WilcoLouwerse Date: Mon, 11 May 2026 16:33:13 +0200 Subject: [PATCH 1/4] docs: ADR ownership split and PR-size guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/claude/writing-adrs.md: add "ADRs in practice" section — explains the ownership split (hydra/openspec/architecture/ = org-wide, /openspec/architecture/ = repo-specific), how containers and in-IDE agents see org-wide ADRs, the rule of thumb for where to add a new ADR, and a linked table of the 29 org-wide ADRs currently in hydra/openspec/architecture/ (026-028 reserved). - CONTRIBUTING.md: add PR-size subsection — prefer one PR per logically-coherent finding/feature; consider splitting past ~10 commits / ~30 files; release-promotion PRs are the exception. Refs #56 Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 8 +++++ docs/claude/writing-adrs.md | 58 +++++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 421b1d4a..b2a4ecd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,6 +37,14 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme * Make sure your code lints (`composer cs:check`) * Create a pull request! +### PR Size + +Prefer **one PR per logically-coherent finding or feature**. Each PR's commit message, checkbox, and inline-comment chain should map to a single change unit — reviewers (human and agent) hold a clearer mental model on focused PRs than on large ones. + +* When a PR's scope grows past **~10 commits or ~30 files**, consider splitting it before requesting review. The per-finding commits stay; the PR boundary moves. +* **Exception:** release-promotion PRs (`development → beta`, `beta → main`) aggregate every change since the last cut and are expected to be larger. +* PRs touching many files across unrelated subsystems tend to get reviewed paragraph-by-paragraph rather than holistically — that's a signal to split, not to push through. + ## Branch Protection & Git Flow We use a structured branching model to ensure stability across environments. All branches are protected via **organization-wide rulesets** on the ConductionNL GitHub organization — direct pushes are not allowed. Every change flows through a pull request with peer review and CI checks. diff --git a/docs/claude/writing-adrs.md b/docs/claude/writing-adrs.md index 08220d9b..5ad945f8 100644 --- a/docs/claude/writing-adrs.md +++ b/docs/claude/writing-adrs.md @@ -152,3 +152,61 @@ Before merging an ADR change: - [ ] No paragraphs — bullets only - [ ] Total ADR file is under 200 lines - [ ] Added rules have been tested by running the agent and verifying it follows them + +--- + +## ADRs in practice — where they live + +Every Conduction app repo follows a clean split: + +| Location | Scope | Who writes | +|---|---|---| +| [`hydra/openspec/architecture/`](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) | **Org-wide ADRs** — apply to every Conduction app | Humans (architecture-level decisions) | +| `/openspec/architecture/` | **Repo-specific ADRs** — apply only to that app (data model choices, domain standards, storage decisions) | Authored by Specter during research; evolved by humans | + +App repos do **NOT** carry copies of the org-wide ADRs. Earlier they had stale duplicates that drifted (e.g. a copy saying `fetch()` while hydra's master said `axios`) — those copies were removed across every app repo that had them. + +**How agents see org-wide ADRs:** +- Reviewer + builder containers copy the relevant ADRs from the hydra repo at image-build time. +- Agents operating in an app repo outside a container (IDE humans, manual `/opsx-ff` runs) read them from hydra's `main` branch directly. +- `specter-prepare-context` surfaces the applicable org-wide ADRs in `context-brief.md` for each spec so the builder sees them pre-loaded. + +**Rule of thumb for where a new ADR belongs:** +- Applies to ≥2 Conduction apps → org-wide, in `hydra/openspec/architecture/`. +- Applies only to one app's domain/storage/auth choice → app-specific, in `/openspec/architecture/`. + +## The org-wide ADRs + +| ADR | Topic | +|---|---| +| [001](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-001-data-layer.md) | Data layer (OpenRegister, entities, mappers) | +| [002](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-002-api.md) | API design (REST, Common Ground, NL API) | +| [003](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-003-backend.md) | Backend (PHP, Nextcloud, services, spec traceability) | +| [004](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-004-frontend.md) | Frontend (Vue, components, settings) | +| [005](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-005-security.md) | Security (auth, CORS, input validation) | +| [006](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-006-metrics.md) | Metrics & observability | +| [007](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-007-i18n.md) | i18n (English primary, Dutch required) | +| [008](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-008-testing.md) | Testing (PHPUnit, Newman, Playwright) | +| [009](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-009-docs.md) | Documentation | +| [010](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-010-nl-design.md) | NL Design System (government theming) | +| [011](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-011-schema-standards.md) | Schema standards (schema.org, DCAT) | +| [012](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-012-deduplication.md) | Deduplication | +| [013](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-013-container-pool.md) | Container pool (model selection, turns, no-loop policy) | +| [014](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-014-licensing.md) | Licensing (EUPL-1.2) | +| [015](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-015-common-patterns.md) | Common patterns (rate-limit retry, dep enforcement) | +| [016](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-016-routes.md) | Routes (`appinfo/routes.php` is the only registration path) | +| [017](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-017-component-composition.md) | Component composition | +| [018](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-018-widget-header-actions.md) | Widget header actions | +| [019](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-019-integration-registry.md) | Integration registry | +| [020](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-020-gate-scope-to-pr-diff.md) | Gate scope is the PR diff, not the whole repo | +| [021](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-021-bounded-fix-scope-by-shape.md) | Reviewer bounded-fix scope is defined by change shape, not line count | +| [022](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-022-apps-consume-or-abstractions.md) | Apps consume OpenRegister abstractions (RBAC, audit trail, archival, relations) | +| [023](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-023-action-authorization.md) | Action-level authorization via admin-configured action/group mappings | +| [024](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-024-app-manifest.md) | App manifest (fleet-wide adoption) | +| [025](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-025-i18n-source-of-truth.md) | i18n source-of-truth | +| [029](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-029-route-reachability-gate.md) | Route reachability gate | +| [030](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-030-journeydoc-pattern.md) | Journeydoc — capture-driven user documentation | +| [031](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-031-schema-declarative-business-logic.md) | Schema-declarative business logic over service classes | +| [032](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-032-spec-sizing-and-chaining.md) | Spec sizing taxonomy and chained-spec routing | + +ADRs 026–028 are reserved for in-flight numbering. From 2bdedff9dc4d2d4d7e7f12f21d0a1b866c781036 Mon Sep 17 00:00:00 2001 From: WilcoLouwerse Date: Mon, 11 May 2026 16:32:07 +0200 Subject: [PATCH 2/4] docs(hydra): fix stale facts and point Related section at /hydra/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/claude/README.md: - Drop the stale 3-agent Related: Hydra section table and replace with a link to the existing /hydra/ doc. docs/hydra/README.md (existing doc, factual corrections only): - Builder model: "uses Opus for implementation" → default Sonnet with Haiku fallback (verified against hydra/agents/al-gorithm/config.yaml). - Reviewer / Applier fallback: deeper model (Opus) when Sonnet quota runs out, not shallower. - No-loop policy: reviewer fix retries removed in favour of bounded in-container fix authority + needs-input + retry:queued/rebuild:queued (ADR-013). - "full-auto label" → "yolo" label (current name; explains it removes the human approval gate but still runs every phase). - ADR count "20+" → 29; reference newer ADRs (bounded fix scope, app manifest, journeydoc, schema-declarative, spec sizing). Earlier in this branch I started a separate docs/claude/hydra-pipeline.md file before noticing docs/hydra/README.md existed. That new file is removed. Refs #56 Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/claude/README.md | 10 +--------- docs/hydra/README.md | 19 +++++++++---------- 2 files changed, 10 insertions(+), 19 deletions(-) diff --git a/docs/claude/README.md b/docs/claude/README.md index 60696f9f..7748e6da 100644 --- a/docs/claude/README.md +++ b/docs/claude/README.md @@ -512,15 +512,7 @@ See [usage-tracker/README.md](../../usage-tracker/README.md) for full documentat [Hydra](https://github.com/ConductionNL/hydra) is Conduction's agentic CI/CD platform that runs the same spec-driven workflow autonomously in Docker containers. It transforms OpenSpec change proposals into validated, security-scanned code on feature branches — with final human approval before merging. -Hydra maintains its own skills, personas, and OpenSpec workflows in its repository, running them through three specialized agent containers: - -| Agent | Role | Permissions | -|-------|------|-------------| -| **Al Gorithm** (Builder) | Reads OpenSpec change, implements code, opens draft PR | Full: Read, Write, Edit, Bash | -| **Juan Claude van Damme** (Reviewer) | Code review for correctness, style, architecture | Read-only | -| **Clyde Barcode** (Security) | SAST analysis, secret detection, security hardening | Read-only | - -The workflow and commands documented in this guide apply to both interactive development and Hydra's automated agents. See the [Hydra repository](https://github.com/ConductionNL/hydra) for container architecture, agent configuration, deployment models, and operational guides. +For an overview of the pipeline stages, the label-based triggers (`ready-to-build`, `code-review:queued`, `security-review:queued`), and how to put Hydra to work on your PR, see the **[Hydra docs](../hydra/README.md)**. For container architecture, image builds, orchestrator internals, and operator-level material, see the [Hydra repository](https://github.com/ConductionNL/hydra). --- diff --git a/docs/hydra/README.md b/docs/hydra/README.md index 18c40233..b9a7f750 100644 --- a/docs/hydra/README.md +++ b/docs/hydra/README.md @@ -24,21 +24,20 @@ Builder — implements the change, pushes branch early, Quality tests — lint, phpcs, phpmd, psalm, phpstan, │ phpmetrics, composer audit, eslint, │ stylelint, npm audit, PHPUnit, Newman - │ fail → Builder fix-quality (max 2 retries) + │ fail → Builder fix-quality (bounded, pre-review) │ ▼ Browser UI tests — Playwright MCP runs the GIVEN/WHEN/THEN │ acceptance criteria against a live NC - │ fail → Builder fix-browser (max 2 retries) + │ fail → Builder fix-browser (bounded, pre-review) │ ├── Code Reviewer ─┐ - └── Security Reviewer ─┘ parallel — halves wall time + └── Security Reviewer ─┘ sequential — reviewers hold bounded fix authority │ - │ fail → Builder fix CRITICAL+WARNING (max 3 retries) - │ If fix budget exhausted → needs-input label + │ either fails → needs-input (no loop — ADR-013) ▼ Draft PR (ready-for-review) — human reviews and merges - │ with full-auto label: pipeline approves and merges automatically + │ with the `yolo` label: pipeline approves and merges automatically │ ▼ (after human merge) Archive — sync specs, generate test scenarios, update changelog @@ -46,7 +45,7 @@ Archive — sync specs, generate test scenarios, update changelog **Traceability.** Every line of code traces to its spec via two paths: a `@spec` PHPDoc tag pointing at `openspec/changes/{name}/tasks.md#task-N`, and `git blame` → commit `(#N)` → PR `Closes #N` → issue → spec. Branch naming is `feature/{issue-number}/{change-name}` and every commit includes `(#N)`. -**Model selection.** Builder uses Opus for implementation and Sonnet for fix modes. Reviewers and the Browser UI Tester use Sonnet. +**Model selection.** Default model for every persona is Sonnet, with a deeper-model fallback (Haiku for the Builder; Opus for the reviewers and the Applier) when the weekly Sonnet quota runs out. Authoritative configuration lives in each persona's `agents//config.yaml` in the hydra repo. ## How to use Hydra on your PR @@ -58,8 +57,8 @@ You don't run Hydra yourself — you trigger it with labels. - `security-review:queued` — queue a security review. Reviews are **sequential** by design (the security review consumes the code review's git state). Setting both queued labels at once is not supported and will produce conflicts. Trigger them one at a time. -3. **Crashes escalate to `needs-input`** rather than auto-retrying. If a Hydra container fails, you'll see a `needs-input` label so a human can investigate the root cause instead of looping. -4. **PRs that only touch Markdown auto-merge.** Documentation-only changes don't need the full review cycle. +3. **Crashes escalate to `needs-input`** rather than auto-retrying. If a Hydra container fails, or either reviewer emits a fail verdict, you'll see a `needs-input` label so a human can investigate. There is no retry loop ([ADR-013](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-013-container-pool.md)) — recovery is explicit via the `retry:queued` (fix the flagged findings) or `rebuild:queued` (start over) labels. +4. **The `yolo` label means auto-merge after the pipeline passes.** All phases still run; `yolo` only removes the human approval gate at the end. ## Where to learn more @@ -67,7 +66,7 @@ The deep technical detail stays in the [hydra repo](https://github.com/Conductio - [hydra/README.md](https://github.com/ConductionNL/hydra/blob/main/README.md) — quickstart and full pipeline overview. - [hydra/docs/](https://github.com/ConductionNL/hydra/tree/main/docs) — pipeline-overview, agentic-workflow, container-architecture, github-workflow, deployment-models, agent-configuration. -- [hydra/openspec/architecture/](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) — 20+ ADRs covering data layer, API, backend, frontend, security, metrics, i18n, testing, docs, NL Design, schema standards, deduplication, container pool, licensing, common patterns, routes, component composition, widget header actions, integration registry, gate scope. +- [hydra/openspec/architecture/](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) — 29 ADRs covering data layer, API, backend, frontend, security, metrics, i18n, testing, docs, NL Design, schema standards, deduplication, container pool (model selection, no-loop policy), licensing, common patterns, routes, component composition, widget header actions, integration registry, gate scope, bounded fix scope, app manifest, journeydoc, schema-declarative business logic, and spec sizing. - [hydra/.claude/skills/](https://github.com/ConductionNL/hydra/tree/main/.claude/skills) — every gate (`hydra-gate-*`), every opsx command (`opsx-*`), and the Hydra-specific tooling. For how Hydra fits into the broader Claude-driven development workflow, see [Claude workflow](/claude/). From e50926664f4f49157095f8d952a38924be1f09dd Mon Sep 17 00:00:00 2001 From: WilcoLouwerse Date: Mon, 11 May 2026 17:19:42 +0200 Subject: [PATCH 3/4] docs(hydra): fix misleading 'deeper-model fallback' + parallel-looking reviewer diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two issues in the PR #57 update to docs/hydra/README.md that surfaced during a fact-check against the actual hydra repo: 1. The phrase "deeper-model fallback (Haiku for the Builder; Opus for the reviewers and the Applier)" was technically wrong — Haiku is *shallower* than Sonnet, not deeper. The Builder falls back to Haiku for cap-friendliness (it's pattern-following work), and the reviewers/Applier fall back to Opus for depth (judgment work, last line of defense). Split the sentence so each direction is clear, and add the `*_FALLBACK_MODEL` env vars. 2. The pipeline diagram still drew the two reviewers with a parallel- looking branch structure (├── / └──) while labelling them "sequential" — confusing and inconsistent with reality. hydra/CLAUDE.md explicitly says "Either verdict triggers → security-review:queued (sequential hand-off)". Redraw as two consecutive linear steps with the sequential note inline. Verified against: - hydra/agents/al-gorithm/config.yaml (sonnet/haiku, 2026-04-21 switch) - hydra/scripts/hydra-supervisor.sh:78 (BUILDER_FALLBACK_MODEL=haiku) - hydra/scripts/hydra-supervisor.sh:1521 (REVIEWER fallback opus) - hydra/scripts/orchestrate.sh:519 ("Reviewers → sonnet preferred, opus fallback") - hydra/CLAUDE.md:71 ("sequential hand-off") Refs #56 Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/hydra/README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/hydra/README.md b/docs/hydra/README.md index b9a7f750..a3b2f1c6 100644 --- a/docs/hydra/README.md +++ b/docs/hydra/README.md @@ -31,10 +31,15 @@ Browser UI tests — Playwright MCP runs the GIVEN/WHEN/THEN │ acceptance criteria against a live NC │ fail → Builder fix-browser (bounded, pre-review) │ - ├── Code Reviewer ─┐ - └── Security Reviewer ─┘ sequential — reviewers hold bounded fix authority - │ - │ either fails → needs-input (no loop — ADR-013) + ▼ +Code Reviewer — reviews + applies bounded in-scope fixes + │ directly to the PR branch + │ fail → needs-input (no loop — ADR-013) + ▼ +Security Reviewer — runs after the code reviewer hands off + │ (sequential — reviewers share git state); + │ same bounded fix authority + │ fail → needs-input ▼ Draft PR (ready-for-review) — human reviews and merges │ with the `yolo` label: pipeline approves and merges automatically @@ -45,7 +50,7 @@ Archive — sync specs, generate test scenarios, update changelog **Traceability.** Every line of code traces to its spec via two paths: a `@spec` PHPDoc tag pointing at `openspec/changes/{name}/tasks.md#task-N`, and `git blame` → commit `(#N)` → PR `Closes #N` → issue → spec. Branch naming is `feature/{issue-number}/{change-name}` and every commit includes `(#N)`. -**Model selection.** Default model for every persona is Sonnet, with a deeper-model fallback (Haiku for the Builder; Opus for the reviewers and the Applier) when the weekly Sonnet quota runs out. Authoritative configuration lives in each persona's `agents//config.yaml` in the hydra repo. +**Model selection.** Default model for every persona is Sonnet. When the weekly Sonnet quota runs out, the Builder falls back to **Haiku** (cheaper, still good at pattern-following from `tasks.md`/`design.md`); the Reviewers and the Applier fall back to **Opus** (deeper, since judgment work is the last line of defense before human approval). Authoritative configuration lives in each persona's `agents//config.yaml` in the hydra repo; runtime overrides via `HYDRA_BUILDER_MODEL`, `HYDRA_REVIEWER_MODEL`, `HYDRA_APPLIER_MODEL`, and their `*_FALLBACK_MODEL` counterparts. ## How to use Hydra on your PR From c1cf117f7c020d3921ec7b223c5e3d404f774f3e Mon Sep 17 00:00:00 2001 From: WilcoLouwerse Date: Tue, 12 May 2026 11:02:50 +0200 Subject: [PATCH 4/4] docs: drop ADR list + reviewer nits, point at hydra directory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses review on PR #57: - writing-adrs.md: remove the 27-row ADR table and the "026-028 reserved" footer. The directory at hydra/openspec/architecture/ is now the only pointer — GitHub renders it as a browsable index and it can't drift out of sync. - CONTRIBUTING.md: drop the "(human and agent)" parenthetical from the PR Size section so the framing reads naturally for external contributors. - docs/hydra/README.md: same rotting-topic-list smell — collapse the long inline ADR-topic enumeration into a brief pointer plus the "directory is authoritative" framing. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 2 +- docs/claude/writing-adrs.md | 38 ++----------------------------------- docs/hydra/README.md | 2 +- 3 files changed, 4 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b2a4ecd7..9207a3ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,7 +39,7 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme ### PR Size -Prefer **one PR per logically-coherent finding or feature**. Each PR's commit message, checkbox, and inline-comment chain should map to a single change unit — reviewers (human and agent) hold a clearer mental model on focused PRs than on large ones. +Prefer **one PR per logically-coherent finding or feature**. Each PR's commit message, checkbox, and inline-comment chain should map to a single change unit — reviewers hold a clearer mental model on focused PRs than on large ones. * When a PR's scope grows past **~10 commits or ~30 files**, consider splitting it before requesting review. The per-finding commits stay; the PR boundary moves. * **Exception:** release-promotion PRs (`development → beta`, `beta → main`) aggregate every change since the last cut and are expected to be larger. diff --git a/docs/claude/writing-adrs.md b/docs/claude/writing-adrs.md index 5ad945f8..fef0fba8 100644 --- a/docs/claude/writing-adrs.md +++ b/docs/claude/writing-adrs.md @@ -164,6 +164,8 @@ Every Conduction app repo follows a clean split: | [`hydra/openspec/architecture/`](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) | **Org-wide ADRs** — apply to every Conduction app | Humans (architecture-level decisions) | | `/openspec/architecture/` | **Repo-specific ADRs** — apply only to that app (data model choices, domain standards, storage decisions) | Authored by Specter during research; evolved by humans | +The authoritative org-wide list is the directory itself — [`hydra/openspec/architecture/`](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) on `main`. GitHub renders it as a browsable index, so we don't mirror it here (the mirror would drift the moment a new ADR lands). + App repos do **NOT** carry copies of the org-wide ADRs. Earlier they had stale duplicates that drifted (e.g. a copy saying `fetch()` while hydra's master said `axios`) — those copies were removed across every app repo that had them. **How agents see org-wide ADRs:** @@ -174,39 +176,3 @@ App repos do **NOT** carry copies of the org-wide ADRs. Earlier they had stale d **Rule of thumb for where a new ADR belongs:** - Applies to ≥2 Conduction apps → org-wide, in `hydra/openspec/architecture/`. - Applies only to one app's domain/storage/auth choice → app-specific, in `/openspec/architecture/`. - -## The org-wide ADRs - -| ADR | Topic | -|---|---| -| [001](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-001-data-layer.md) | Data layer (OpenRegister, entities, mappers) | -| [002](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-002-api.md) | API design (REST, Common Ground, NL API) | -| [003](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-003-backend.md) | Backend (PHP, Nextcloud, services, spec traceability) | -| [004](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-004-frontend.md) | Frontend (Vue, components, settings) | -| [005](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-005-security.md) | Security (auth, CORS, input validation) | -| [006](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-006-metrics.md) | Metrics & observability | -| [007](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-007-i18n.md) | i18n (English primary, Dutch required) | -| [008](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-008-testing.md) | Testing (PHPUnit, Newman, Playwright) | -| [009](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-009-docs.md) | Documentation | -| [010](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-010-nl-design.md) | NL Design System (government theming) | -| [011](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-011-schema-standards.md) | Schema standards (schema.org, DCAT) | -| [012](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-012-deduplication.md) | Deduplication | -| [013](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-013-container-pool.md) | Container pool (model selection, turns, no-loop policy) | -| [014](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-014-licensing.md) | Licensing (EUPL-1.2) | -| [015](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-015-common-patterns.md) | Common patterns (rate-limit retry, dep enforcement) | -| [016](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-016-routes.md) | Routes (`appinfo/routes.php` is the only registration path) | -| [017](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-017-component-composition.md) | Component composition | -| [018](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-018-widget-header-actions.md) | Widget header actions | -| [019](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-019-integration-registry.md) | Integration registry | -| [020](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-020-gate-scope-to-pr-diff.md) | Gate scope is the PR diff, not the whole repo | -| [021](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-021-bounded-fix-scope-by-shape.md) | Reviewer bounded-fix scope is defined by change shape, not line count | -| [022](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-022-apps-consume-or-abstractions.md) | Apps consume OpenRegister abstractions (RBAC, audit trail, archival, relations) | -| [023](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-023-action-authorization.md) | Action-level authorization via admin-configured action/group mappings | -| [024](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-024-app-manifest.md) | App manifest (fleet-wide adoption) | -| [025](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-025-i18n-source-of-truth.md) | i18n source-of-truth | -| [029](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-029-route-reachability-gate.md) | Route reachability gate | -| [030](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-030-journeydoc-pattern.md) | Journeydoc — capture-driven user documentation | -| [031](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-031-schema-declarative-business-logic.md) | Schema-declarative business logic over service classes | -| [032](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-032-spec-sizing-and-chaining.md) | Spec sizing taxonomy and chained-spec routing | - -ADRs 026–028 are reserved for in-flight numbering. diff --git a/docs/hydra/README.md b/docs/hydra/README.md index a3b2f1c6..5fb101ce 100644 --- a/docs/hydra/README.md +++ b/docs/hydra/README.md @@ -71,7 +71,7 @@ The deep technical detail stays in the [hydra repo](https://github.com/Conductio - [hydra/README.md](https://github.com/ConductionNL/hydra/blob/main/README.md) — quickstart and full pipeline overview. - [hydra/docs/](https://github.com/ConductionNL/hydra/tree/main/docs) — pipeline-overview, agentic-workflow, container-architecture, github-workflow, deployment-models, agent-configuration. -- [hydra/openspec/architecture/](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) — 29 ADRs covering data layer, API, backend, frontend, security, metrics, i18n, testing, docs, NL Design, schema standards, deduplication, container pool (model selection, no-loop policy), licensing, common patterns, routes, component composition, widget header actions, integration registry, gate scope, bounded fix scope, app manifest, journeydoc, schema-declarative business logic, and spec sizing. +- [hydra/openspec/architecture/](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) — the org-wide ADRs (data layer, API, backend, frontend, security, container pool, and more). GitHub renders the directory as a browsable index; the directory itself is the authoritative list. - [hydra/.claude/skills/](https://github.com/ConductionNL/hydra/tree/main/.claude/skills) — every gate (`hydra-gate-*`), every opsx command (`opsx-*`), and the Hydra-specific tooling. For how Hydra fits into the broader Claude-driven development workflow, see [Claude workflow](/claude/).