docs: multi-agent contributor onboarding sweep + Constitution v1.1.0. Principle XIII.#2932
Merged
ten9876 merged 1 commit intoMay 22, 2026
Conversation
… Principle XIII. Restructures AetherSDR's contributor-onboarding documentation around the project's actual multi-agent contribution model: at least six distinct AI tools touch the codebase (AetherClaude orchestrator, Claude Code, OpenAI Codex, GPT 5.5 Pro, GitHub Copilot, contributor- side IDE agents). Each tool has its own well-known file at a different path, and the previous topology (CLAUDE.md as the sole canonical) left every other agent reading conventions by accident. Changes: - AGENTS.md (new): canonical project guide. All previous CLAUDE.md content moved here, retitled to be agent-neutral. Single source of truth for project-wide guidance. - CLAUDE.md: slimmed 311 → 68 lines. Now a thin pointer to AGENTS.md plus Claude-Code-specific notes (git ship alias, ~/.claude paths). - GEMINI.md (new): thin pointer for Gemini Code Assist with 6 inline must-knows. - .github/copilot-instructions.md (new): same pattern for GitHub Copilot. - All tool-specific files point directly to AGENTS.md — no pointer-to-pointer chains. Constitution v1.0.1 → 1.1.0 (MINOR amendment): - Adopts 7 new principles from Cisco's Foundry Constitution (https://github.com/CiscoDevNet/foundry-security-spec): VIII Evidence Over Assertion, IX Surface Only What Survives, X Claims Are Atomic And Mortal, XI Fixes Are Demonstrated, XII Sandbox By Infrastructure Not By Prompt, XIII The Operator Outranks Every Agent (promoted from Governance), XIV Persist Atomically. - Total principle count: 7 → 14. First 7 unchanged (AetherSDR- domain conventions); last 7 codify defensive engineering for the multi-agent contribution model. - CONSTITUTION.md (new): byte-identical root mirror of .specify/memory/constitution.md so AI tools reading the repo root find it without spec-kit path knowledge. - Each new principle is grounded in a real AetherSDR incident (PR #2780 stale-snapshot revert → Principle X; PR #2816 alloc- free claim verification → Principle VIII; etc.). New: Issue / PR Claim Protocol (AGENTS.md): - AI agents reviewing/commenting on or merging PRs must assign themselves via gh issue edit / gh pr edit --add-assignee @me. - Carve-out: AetherClaude (@aethersdr-agent) auto-triages every new issue/PR, so adding yourself alongside its assignment is expected — only avoid double-assigning when another non-AetherClaude agent is already engaged. - Operational implementation of Principle X (Claims Are Atomic And Mortal): assignees list is the visible cross-agent claim signal. New: docs/COMMIT-SIGNING.md: - Walks contributors through SSH or GPG signing setup on Windows / macOS / Linux / WSL / Raspberry Pi. - Top of doc has explicit AI Assistant Instructions section so an agent pointed at the doc can walk the contributor through setup in their actual environment without further prompting. - Per-OS copy-paste prompts also included for contributors using AI IDEs (Claude Code, Cursor, Copilot chat, ChatGPT) who want a ready-made invocation. Updated: CONTRIBUTING.md + CLAUDE.md / AGENTS.md pointers: - Constitution reference promoted to step 2 in the Submitting Code checklist. - Commit signing section rewritten to lead with the new doc and AI-assistant invocation, with SSH quick-reference inline. - Principle counts updated everywhere (7 → 14). Principle XIII (Operator Outranks Every Agent) is cited because the entire restructure exists to ensure the operator's authoritative voice reaches every agent reading the project, regardless of which tool the agent runs as. Foundry-spec conformance verified: all 14 structural elements (SYNC IMPACT REPORT, Field table, Purpose, Core Principles, "Why inviolable" rationales, Governance subsections Amendment/Precedence/ Scope/Versioning/Compliance review/Downstream artifacts, MAJOR/MINOR/ PATCH versioning, Foundry reference) present in CONSTITUTION.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
G6PWY-Chris
pushed a commit
to G6PWY-Chris/AetherSDR
that referenced
this pull request
Jun 22, 2026
… Principle XIII. (aethersdr#2932) Restructures AetherSDR's contributor-onboarding documentation around the project's actual multi-agent contribution model: at least six distinct AI tools touch the codebase (AetherClaude orchestrator, Claude Code, OpenAI Codex, GPT 5.5 Pro, GitHub Copilot, contributor- side IDE agents). Each tool has its own well-known file at a different path, and the previous topology (CLAUDE.md as the sole canonical) left every other agent reading conventions by accident. Changes: - AGENTS.md (new): canonical project guide. All previous CLAUDE.md content moved here, retitled to be agent-neutral. Single source of truth for project-wide guidance. - CLAUDE.md: slimmed 311 → 68 lines. Now a thin pointer to AGENTS.md plus Claude-Code-specific notes (git ship alias, ~/.claude paths). - GEMINI.md (new): thin pointer for Gemini Code Assist with 6 inline must-knows. - .github/copilot-instructions.md (new): same pattern for GitHub Copilot. - All tool-specific files point directly to AGENTS.md — no pointer-to-pointer chains. Constitution v1.0.1 → 1.1.0 (MINOR amendment): - Adopts 7 new principles from Cisco's Foundry Constitution (https://github.com/CiscoDevNet/foundry-security-spec): VIII Evidence Over Assertion, IX Surface Only What Survives, X Claims Are Atomic And Mortal, XI Fixes Are Demonstrated, XII Sandbox By Infrastructure Not By Prompt, XIII The Operator Outranks Every Agent (promoted from Governance), XIV Persist Atomically. - Total principle count: 7 → 14. First 7 unchanged (AetherSDR- domain conventions); last 7 codify defensive engineering for the multi-agent contribution model. - CONSTITUTION.md (new): byte-identical root mirror of .specify/memory/constitution.md so AI tools reading the repo root find it without spec-kit path knowledge. - Each new principle is grounded in a real AetherSDR incident (PR aethersdr#2780 stale-snapshot revert → Principle X; PR aethersdr#2816 alloc- free claim verification → Principle VIII; etc.). New: Issue / PR Claim Protocol (AGENTS.md): - AI agents reviewing/commenting on or merging PRs must assign themselves via gh issue edit / gh pr edit --add-assignee @me. - Carve-out: AetherClaude (@aethersdr-agent) auto-triages every new issue/PR, so adding yourself alongside its assignment is expected — only avoid double-assigning when another non-AetherClaude agent is already engaged. - Operational implementation of Principle X (Claims Are Atomic And Mortal): assignees list is the visible cross-agent claim signal. New: docs/COMMIT-SIGNING.md: - Walks contributors through SSH or GPG signing setup on Windows / macOS / Linux / WSL / Raspberry Pi. - Top of doc has explicit AI Assistant Instructions section so an agent pointed at the doc can walk the contributor through setup in their actual environment without further prompting. - Per-OS copy-paste prompts also included for contributors using AI IDEs (Claude Code, Cursor, Copilot chat, ChatGPT) who want a ready-made invocation. Updated: CONTRIBUTING.md + CLAUDE.md / AGENTS.md pointers: - Constitution reference promoted to step 2 in the Submitting Code checklist. - Commit signing section rewritten to lead with the new doc and AI-assistant invocation, with SSH quick-reference inline. - Principle counts updated everywhere (7 → 14). Principle XIII (Operator Outranks Every Agent) is cited because the entire restructure exists to ensure the operator's authoritative voice reaches every agent reading the project, regardless of which tool the agent runs as. Foundry-spec conformance verified: all 14 structural elements (SYNC IMPACT REPORT, Field table, Purpose, Core Principles, "Why inviolable" rationales, Governance subsections Amendment/Precedence/ Scope/Versioning/Compliance review/Downstream artifacts, MAJOR/MINOR/ PATCH versioning, Foundry reference) present in CONSTITUTION.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Restructures AetherSDR's contributor-onboarding documentation around
the project's actual multi-agent contribution model: at least six
distinct AI tools touch the codebase (AetherClaude orchestrator,
Claude Code, OpenAI Codex, GPT 5.5 Pro, GitHub Copilot, contributor-
side IDE agents). Each tool has its own well-known file at a
different path, and the previous topology (CLAUDE.md as the sole
canonical) left every other agent reading conventions by accident.
Changes:
content moved here, retitled to be agent-neutral. Single source of
truth for project-wide guidance.
plus Claude-Code-specific notes (git ship alias, ~/.claude paths).
must-knows.
Copilot.
pointer-to-pointer chains.
Constitution v1.0.1 → 1.1.0 (MINOR amendment):
(https://github.com/CiscoDevNet/foundry-security-spec):
VIII Evidence Over Assertion, IX Surface Only What Survives,
X Claims Are Atomic And Mortal, XI Fixes Are Demonstrated,
XII Sandbox By Infrastructure Not By Prompt,
XIII The Operator Outranks Every Agent (promoted from Governance),
XIV Persist Atomically.
domain conventions); last 7 codify defensive engineering for the
multi-agent contribution model.
.specify/memory/constitution.md so AI tools reading the repo
root find it without spec-kit path knowledge.
(PR Fix panadapter layout and floating restore #2780 stale-snapshot revert → Principle X; PR feat(audio): RN2 (RNNoise) toggle on Aetherial Tube Pre-Amp TX (#2813) #2816 alloc-
free claim verification → Principle VIII; etc.).
New: Issue / PR Claim Protocol (AGENTS.md):
themselves via gh issue edit / gh pr edit --add-assignee @me.
new issue/PR, so adding yourself alongside its assignment is
expected — only avoid double-assigning when another non-AetherClaude
agent is already engaged.
Mortal): assignees list is the visible cross-agent claim signal.
New: docs/COMMIT-SIGNING.md:
macOS / Linux / WSL / Raspberry Pi.
agent pointed at the doc can walk the contributor through setup
in their actual environment without further prompting.
IDEs (Claude Code, Cursor, Copilot chat, ChatGPT) who want a
ready-made invocation.
Updated: CONTRIBUTING.md + CLAUDE.md / AGENTS.md pointers:
checklist.
AI-assistant invocation, with SSH quick-reference inline.
Principle XIII (Operator Outranks Every Agent) is cited because
the entire restructure exists to ensure the operator's authoritative
voice reaches every agent reading the project, regardless of which
tool the agent runs as.
Foundry-spec conformance verified: all 14 structural elements
(SYNC IMPACT REPORT, Field table, Purpose, Core Principles, "Why
inviolable" rationales, Governance subsections Amendment/Precedence/
Scope/Versioning/Compliance review/Downstream artifacts, MAJOR/MINOR/
PATCH versioning, Foundry reference) present in CONSTITUTION.md.
Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com