ADR 0003: org-level config lives in <org>/.fullsend repo

[ralphbean]

Summary

• Adds ADR 0003 establishing the convention that adopting organizations create an <org>/.fullsend repo as the single entry point for all fullsend configuration — pointers to intent/architecture repos, agent runtime defaults, infrastructure/sandbox config, workflow overrides, org-specific agents and skills, per-repo overrides, and org-wide guardrails.
• Evaluates seven options including non-git alternatives (external config stores like Consul/Vault, forge-native org settings, hosted SaaS control plane) and explains why version-controlled, CODEOWNERS-governed configuration in a conventional repo is the right fit.
• The convention is forge-agnostic — works for GitHub orgs, GitLab groups, and Forgejo orgs.
• Updates docs/architecture.md to reference the .fullsend repo as the configuration home for six components (Agent Infrastructure, Agent Sandbox, Agent Harness, Policy Store, Intent Source, Agent Registry), closing several previously-open questions.

Relates to #75.

Test plan

• Review ADR structure against the template in docs/ADRs/0000-adr-template.md
• Verify frontmatter relates_to entries match existing problem doc filenames
• Review architecture.md changes for consistency with the ADR's decision
• Validate that ADR linting CI passes

🤖 Generated with Claude Code

[qodo-code-review]

Review Summary by Qodo

ADR 0003: Establish org-level config in .fullsend repo convention

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Establishes ADR 0003 defining <org>/.fullsend repo convention for org-level configuration
• Evaluates seven alternatives (external stores, forge-native settings, SaaS) and justifies
  git-based approach
• Updates docs/architecture.md to reference .fullsend repo as configuration home for six
  components
• Removes open questions answered by the ADR decision (policy location, registry formality, harness
  per-role)

Diagram

flowchart LR
  A["Adopting Org"] -->|creates| B["<org>/.fullsend repo"]
  B -->|contains| C["config.yaml"]
  B -->|contains| D["agents/ skills/ workflows/"]
  B -->|contains| E["repos/ per-repo overrides"]
  C -->|points to| F["intent_repo"]
  C -->|points to| G["architecture_repo"]
  C -->|defines| H["runtime defaults"]
  C -->|defines| I["infrastructure config"]
  B -->|governs| J["Agent Harness"]
  B -->|governs| K["Policy Store"]
  B -->|governs| L["Agent Registry"]
  M["fullsend defaults"] -->|layered with| B
  B -->|layered with| E

Loading

File Changes

1. docs/ADRs/0003-org-config-repo-convention.md 📝 Documentation +314/-0

New ADR 0003 org-level config repo convention

• New ADR document establishing <org>/.fullsend as the conventional location for org-level
 fullsend configuration
• Evaluates seven options including external config stores, forge-native settings, and SaaS control
 planes
• Defines decision rationale: version-controlled, CODEOWNERS-governed, org-owned configuration in a
 discoverable repo
• Specifies initial repo structure with config.yaml, agents/, skills/, workflows/, and
 repos/ directories
• Documents inheritance model layering fullsend defaults, org config, and per-repo overrides
• Outlines consequences including security implications and bootstrapping benefits

docs/ADRs/0003-org-config-repo-convention.md

---

2. docs/architecture.md 📝 Documentation +13/-4

Reference ADR 0003 config convention in architecture

• Adds references to ADR 0003 for six architecture components: Agent Infrastructure, Agent Sandbox,
 Agent Harness, Policy Store, Intent Source, and Agent Registry
• Removes open questions answered by ADR 0003 decision (policy location, registry formality, harness
 per-role configuration)
• Clarifies that infrastructure platform choice, sandbox defaults, harness configuration, policy
 rules, intent source pointer, and agent definitions all live in <org>/.fullsend repo
• Updates Intent Source section to reference "forge issues" instead of "GitHub issues" for
 forge-agnostic language
• Establishes .fullsend repo as the root of dependency graph for org-level fullsend configuration

docs/architecture.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📐 Spec deviations (0)

1. Misleading CODEOWNERS granularity ☑ 🐞 Bug ⛨ Security

Description

ADR 0003 states that “CODEOWNERS on the guardrails section of config prevents” weakening guardrails,
but this repo defines CODEOWNERS enforcement in terms of guarded file paths, not sections within a
file. This can cause orgs to structure guardrails inside a shared config.yaml and incorrectly assume
they can apply stricter review requirements to only that subsection (or be forced to over-guard the
entire file).

Code

docs/ADRs/0003-org-config-repo-convention.md[R283-285]

+Org config can add agents, skills, and workflows. It can override defaults. It
+cannot weaken org-wide guardrails (that's a governance enforcement, not a
+technical one — CODEOWNERS on the guardrails section of config prevents it).

Evidence

ADR 0003 explicitly references CODEOWNERS applying to a “guardrails section” inside configuration,
while the autonomy model documented in this repo describes CODEOWNERS as requiring human approval
for specific file paths. ADR 0003’s proposed repo layout also centralizes configuration into a
single config.yaml, which makes section-level review-gating infeasible without splitting guardrails
into separate files/paths.

docs/ADRs/0003-org-config-repo-convention.md[283-286]
docs/ADRs/0003-org-config-repo-convention.md[232-242]
docs/ADRs/0003-org-config-repo-convention.md[244-265]
docs/problems/autonomy-spectrum.md[7-12]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
ADR 0003 implies CODEOWNERS can protect a "guardrails section" within a config file, but CODEOWNERS review enforcement is described in this repo as operating on file paths. The ADR should not imply subsection-level enforcement; instead it should either (a) recommend placing guardrails in their own file/directory path that can be CODEOWNERS-guarded, or (b) state that guarding requires applying CODEOWNERS to the entire relevant file(s).

## Issue Context
- ADR 0003 proposes a `.fullsend` repo structure with a top-level `config.yaml` containing multiple kinds of configuration. If guardrails require stricter review than other settings, they need a separate path to be meaningfully CODEOWNERS-gated.
- Repo documentation describes CODEOWNERS gating as applying to specific file paths.

## Fix Focus Areas
- docs/ADRs/0003-org-config-repo-convention.md[232-242]
- docs/ADRs/0003-org-config-repo-convention.md[244-265]
- docs/ADRs/0003-org-config-repo-convention.md[283-286]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[waynesun09]

Nice ADR — thorough options analysis with principled rejection of non-git alternatives. A few items to consider:

Should Address Before Merge

Issue	Detail
CODEOWNERS on YAML sections	ADR says "CODEOWNERS on the guardrails section of config" but CODEOWNERS operates on file paths, not YAML sections. Suggest separate guardrails.yaml file
Agent modification enforcement	Specify how "agents cannot modify this repo" is enforced (bot exclusion from write access + CODEOWNERS)
Secrets management clarity	Add note that .fullsend contains structural config only; secrets (API keys, credentials) are managed separately
Schema versioning	Add version: field to config.yaml example for future schema evolution
Status field	Should this be "Accepted" upon merge, or remain "Proposed" pending community review?

Nice-to-Have Suggestions

Suggestion
Add per-repo-only config as an explicitly rejected alternative (Option 8)
Add migration path consequence for existing adopters
Clarify runtime.default vs runtime.model — redundant keys in YAML example
Replace .editorconfig (a file) with .gitlab (a repo) as dot-prefix precedent example
Add config discovery algorithm pseudo-code for tooling
Note that .fullsend should have the most restrictive branch protection in the org
Add per-repo override discovery mechanism sentence
Clarify forge-agnosticism: "platforms that support org/group-level repositories"
Multi-org hierarchy scenarios (large companies with sub-groups) — flag as future work

[waynesun09]

All review feedback addressed in 426d433 — guardrails split to separate file for CODEOWNERS, agent enforcement clarified, secrets/versioning/naming cleaned up, and override gap tracked in #84. LGTM.

[rh-hemartin]

I think credential management will have its own ADR in the future, so I'm fine with this.

[ralphbean]

I created empty repos at https://github.com/fullsend-ai/.fullsend and https://github.com/nonflux/.fullsend