This directory contains the Architecture Decision Records (ADRs) for Decepticon — short, numbered, append-only documents that capture non-obvious architectural decisions, their context, and their consequences.
Write an ADR when the answer to "why is the code shaped this way?" needs to be available to a future maintainer (human or AI) who was not in the room when the decision was made. Concretely:
- A trade-off between two viable designs where the loser is not obviously bad (e.g. middleware composition order, sandbox transport mechanism, C2 framework selection, prompt-cache boundary placement).
- A constraint that the code relies on but does not test (e.g. an invariant about which services share a Docker network).
- A reversal of a previous decision — the old ADR is marked
Supersededand the new one explains why. - A policy that governs how the project is operated (e.g. which merge and release gates exist, the AI-assisted contribution charter).
Do not write an ADR for:
- Decisions that are obvious from reading the code.
- Bug fixes that do not change architecture.
- Style or formatting decisions (the project's lint config is the source of truth).
- Feature scoping (open an issue).
Each ADR follows the Michael Nygard format:
- Title — short, imperative, present tense.
- Status —
Proposed/Accepted/Deprecated/Superseded by ADR-NNNN. - Context — the forces at play; what makes this decision non-obvious.
- Decision — what we are doing.
- Consequences — what becomes easier, what becomes harder, what is given up.
- Alternatives considered — the designs that lost, with one sentence each on why.
Use template.md as the starting point.
- Numbered sequentially, four digits, never renumbered:
0001-...,0002-.... The number is allocated when the PR opens; if your draft PR sits for a while and another ADR lands first, renumber yours. - File name kebab-case, derived from the title:
0007-c2-framework-selection.md. - Append-only. To change a decision, write a new ADR that supersedes
the old one; do not edit the old one except to flip its
StatustoSuperseded by ADR-NNNN. - Anyone may open an ADR. Landing one at
Status: Acceptedis a maintainer decision, by convention rather than by a branch rule — see ADR-0012 for why the repo no longer enforces per-path review.
| # | Title | Status |
|---|---|---|
| 0001 | Record architecture decisions | Accepted |
| 0002 | PR tiering by blast radius | Superseded by 0012 |
| 0003 | AI-assisted contribution self-review charter | Accepted |
| 0004 | Zero AI-slop policy — the 100% quality bar | Accepted |
| 0005 | Integrate BloodHound via the official BHCE REST API, not via in-house reimplementation | Accepted |
| 0006 | Agent-driven domain-tool container lifecycle via an ops-control sidecar | Proposed |
| 0007 | Add a Technology KG node kind for AI-surface / tech-detection signals | Accepted |
| 0008 | Skillogy hard path-prefix ACL (Phase 1a) | Accepted |
| 0009 | Migrate HITL to LangGraph-native interrupt() + explicit-policy sets |
Proposed |
| 0010 | Acquire open-web content with a sandbox-side, RoE-gated fetch engine | Proposed |
| 0011 | Skillogy find_skill uses LightRAG-style hybrid retrieval over the existing graph | Proposed |
| 0012 | Retire the CODEOWNERS merge gate; keep required CI and the release environment | Accepted |
| 0013 | Expose live Blue Cell observations through MCP | Proposed |
| 0014 | Expose plugin bundles through MCP | Proposed |
| 0018 | Preserve requested workspace before destructive uninstall | Proposed |
| 0019 | Separate specialist capabilities from business workflows | Proposed |
| 0020 | Operator provisioning of a missing RoE | Proposed |
Keep this index in sync when you land a new ADR.