AGENTS.md · git:20260724.013e5c9 · 2026-07-24 · sha256 bfcc5a05b6990b8e
AGENTS.md git:20260724.013e5c9B
Immutable. This exact content is served forever at /api/v1/blob/bfcc5a05b6990b8e.
<!-- Generated by scripts/sync-mirrors.sh from the canonical sources — do not edit. --> # Repository Instructions This file is generated from the canonical instructions and rules. The source of truth is the repository's canonical assistant configuration; regenerate the Codex mirror with `scripts/sync-mirrors.sh` after changing canonical instructions, commands, or skills. Reusable skills are in `.codex/skills/`, and equivalent command workflows are in `.codex/prompts/`. ## Agent instructions # Agent Instructions Issue tracking uses GitHub Issues via the `gh` CLI. The `/do-work` and `/git-issue-pop` commands handle the full workflow: fetching issues, assigning tasks, tracking sub-issues, and opening pull requests. ## Environment The skills that shell out to Python run in a pixi-managed environment that ships inside the agent directory (`pixi.toml` and `pixi.lock` at its root, provisioned by `scripts/ensure-env.sh`). Because the agent directory is symlinked into target repositories, the environment travels with it. On opening a repository — or at the latest before running any skill that invokes a Python script — run the preflight from the agent directory: ```bash scripts/ensure-env.sh ``` It checks for pixi (installing it if absent, unless `SKILL_ENV_NO_INSTALL` is set), then materializes the locked environment. It is idempotent and fast once provisioned. Run skill scripts through it with `pixi run --manifest-path <agent-dir>/pixi.toml python <script>`. The de-ai detectors need only bash and the Python stdlib, so they run without this step. ## Pre-Commit Quality Gate Before committing, run `mage audit` and fix all reported YAML schema errors. The audit target checks cross-artifact consistency (PRDs, use cases, test suites, roadmap) and validates YAML fields against Go structs. Unrecognized fields cause data loss in the measure prompt. Do not commit with audit errors. ## Commit After Every Edit After creating or editing any file, run `mage audit`, fix any errors, then commit. Do not accumulate uncommitted changes across multiple turns. Each round of edits gets its own commit before responding to the user. This applies to all file types: code, docs, rules, config. ## Code Implementation Go style and code standards are defined in `docs/constitutions/go-style.yaml` and `docs/constitutions/execution.yaml`. These are passed to Claude via the cobbler prompts and do not need to be duplicated here. ## Scaffolding This repository scaffolds orchestration into target Go repositories. - `mage scaffold:push <target>` installs the orchestrator (template, constitutions, prompts, config, go.mod wiring) - `mage scaffold:pop <target>` removes all scaffolded files from the target - Both accept `.` for the current directory, but self-targeting is blocked (push/pop refuse when the target resolves to the orchestrator repo) - `configuration.yaml` is auto-created with defaults if missing when any mage target runs ## Documentation Follow [documentation-standards.md](documentation-standards.md) (distilled from `docs/constitutions/design.yaml`): - Specification-driven: specs are source of truth, code serves specs - YAML-first for structured documents, markdown for prose - Active voice, concise, no forbidden terms - Traceability chain: Vision -> Architecture -> PRDs -> Use cases -> Test suites -> Code For README files specifically, see [readme-format.md](readme-format.md). ## Constitutions (Full Reference) - `docs/constitutions/planning.yaml` — Task sizing, issue structure, dependency ordering (measure phase) - `docs/constitutions/execution.yaml` — Code standards, design patterns, traceability (stitch phase) - `docs/constitutions/design.yaml` — Document types, format rules, completeness checklists (design phase) - `docs/constitutions/go-style.yaml` — Go coding style, patterns, code review checklist # Documentation Standards Distilled from `docs/constitutions/design.yaml`. Read the full constitution for document type schemas, completeness checklists, and naming conventions. ## Specification-Driven Development Specifications are the source of truth. Code serves specifications, not the other way around. No implementation code before the PRD and use case exist. No implementation issue before a test suite exists for its use case. ## Choosing a Document Type For documents aimed outside the repository (papers, whitepapers, RFCs, specifications, invention disclosures), pick the form from [technical-document-types.md](technical-document-types.md). The YAML types below govern documents inside the repository. ## YAML-First Use YAML for structured documents (VISION, ARCHITECTURE, PRDs, use cases, test suites). Use markdown for prose-heavy guidelines and specification summaries. YAML is machine-readable by design. ## Writing Style - Concise, active voice, specific and concrete language, no unnecessary words (Elements of Style). - Use the royal "we" in active voice. GOOD: "We implement the feature..." BAD: "This document describes..." - Paragraph form unless not possible. Vary sentence length. Short paragraphs only to emphasize. - Tables instead of lists for short entries. Name all tables. - Explain abbreviations at least once per document section. - Do not use bold text or horizontal rules in prose. ## Forbidden Terms Do not use: critical, critically, key, deliberate, strategic, precisely, absolutely, fundamental, breakthrough, principled, honest, at the heart of, grounded, standards-aligned. ## Diagrams All diagrams in Mermaid, defined inline in markdown fenced code blocks. Do not create separate image files. ## Document Types and Locations | Type | Location | Format | |------|----------|--------| | Vision | `docs/VISION.yaml` | vision-format | | Architecture | `docs/ARCHITECTURE.yaml` | architecture-format | | PRD | `docs/specs/product-requirements/prd[NNN]-[feature-name].yaml` | prd-format | | Use case | `docs/specs/use-cases/rel[NN].[N]-uc[NNN]-[short-name].yaml` | use-case-format | | Test suite | `docs/specs/test-suites/test-rel-[release-id].yaml` | test-case-format | | Engineering guideline | `docs/engineering/eng[NN]-[short-name].yaml` | engineering-guideline-format | | Specification | `docs/SPECIFICATIONS.yaml` | specification-format | | Roadmap | `docs/road-map.yaml` | — | ## Traceability Chain Vision (goals) -> Architecture (components) -> PRDs (numbered requirements) -> Use cases (tracer bullets) -> Test suites (validation) -> Code (implementation, traces to PRDs via commits). Every PRD traces to VISION and ARCHITECTURE. Every use case traces to PRDs via touchpoints. Every test suite traces to use cases via the traces field. ## Test Suite Linkage Every use case must have a corresponding test suite. The test suite validates the use case's success criteria with explicit inputs and expected outputs. ## Roadmap-Driven Releases Use cases are assigned to releases in `road-map.yaml`. Releases are numbered `rel[NN].[N]`. Minor releases validate completed major releases without renumbering existing use cases. # Git Workflow All work goes through issues and pull requests. Never commit directly to main. ## Rules - Never commit to `main` directly. All changes require an issue and a PR. - Use `/gh-issue-push` to create an issue before starting any work. In repos using beads, use `/bd-issue-push` instead. - Use `/gh-issue-pop` to pop the issue into a worktree branch and open the PR when done. In repos using beads, use `/bd-issue-pop` instead. - All implementation work happens inside the worktree (`../gh-<number>-<slug>` or `../bd-<id>-<slug>`), never in the main repo directory. - One issue per logical change. Small fixes still need an issue. - The only exceptions are an emergency hotfix explicitly authorized by the user in that session, and `exp/*` experiment branches which never merge to `main` and never get PRs or issues — keepers are distilled onto `gh-*` branches via the normal flow. # Pixi for Python We use pixi (https://pixi.sh/) to manage Python environments and dependencies. Do not use pip, pip3, conda, or virtualenv directly. ## Commands | Task | Command | |------|---------| | Create a new workspace | `pixi init` (creates pixi.toml in current directory) | | Add a conda package | `pixi add <package>` | | Add a PyPI package | `pixi add --pypi <package>` | | Enter the environment shell | `pixi shell` | | Run a command in the environment | `pixi run <command>` | ## Setting Up Python When Python is needed and no pixi.toml exists yet, initialize first: ```bash pixi init pixi add python pixi add <any-other-packages> ``` Then run Python scripts with `pixi run python3 script.py` or enter `pixi shell` for interactive use. ## Rules - Never run `pip install` or `pip3 install` outside of pixi. - Never create virtualenvs manually. Pixi manages environments. - Use `pixi add` to declare dependencies so they are tracked in pixi.toml and the lockfile. - Use `pixi add --pypi <package>` for packages only available on PyPI (not in conda channels). - Commit pixi.toml and pixi.lock to version control. # README Format README files are the public interface of a repository. They are read by engineers, hiring managers, and automated profile-correlation platforms. A README should read like a technical brief written by someone who builds production systems. ## Author Context The repository owner is a Principal Architect with over 20 years of production systems experience, a PhD in Computer Engineering, and 64 US patents. READMEs must reflect this level of experience: confident, precise, and substantive. Never write anything that reads like a tutorial, a sales pitch, or a job application. ## Structure Order matters. A reader who scans only the first three sections should understand what the project is, why it exists, and how it works at an architectural level. 1. **Title and one-line description** -- What the system does, in domain terms. No adjectives, no taglines. The title is the repository name; the description is a single sentence. 2. **Architectural thesis** -- The "why" in 2-4 sentences. What engineering problem does the approach solve? Methodology (e.g., spec-driven development, differential testing) is introduced here as the solution to a stated problem, not as a label. 3. **System diagram** -- Mermaid showing component relationships, the development pipeline, or the data flow. Architecture diagrams signal systems thinking more effectively than any paragraph. Use fenced code blocks with `mermaid` language tag. Do not use PlantUML (GitHub does not render it). 4. **Project scope and status** -- What is the target, what is built, what is planned. Use concrete numbers (e.g., "12 of 123 utilities specified"). Scope demonstrates ambition; status demonstrates execution. 5. **Methodology or approach** -- How the system is built, not how to use it. Describe the engineering pipeline or workflow. This section lets the approach speak for itself. Keep it factual. 6. **Repository structure** -- A brief tree showing the top-level layout. Annotate each entry with its role (one phrase, not a sentence). 7. **Technology choices** -- Brief, with rationale. "Go because X" is more informative than "Built with Go." Only include choices that are non-obvious or have an interesting reason behind them. 8. **Build and test instructions** -- The conventional README content. Last, not first. Engineers who need this will scroll; engineers who are evaluating the project need the sections above. ## Principles - **No buzzwords.** If a term would not survive a technical design review, do not use it. "Agentic orchestration" is acceptable if the system actually orchestrates agents. "Self-healing MLOps" is not acceptable unless the system literally does that. - **No emoji in headers or body text.** This is an engineering artifact. - **No keyword stuffing.** Do not add terms for discoverability. Let the description of the work contain the relevant terms naturally. - **Let the work demonstrate competence.** A README that explains a sophisticated approach clearly is more impressive than one that tells you it is impressive. - **Write for a 30-second scan.** The title, thesis, and diagram must stand alone for readers who go no further. - **Link to deeper documentation.** If the repository has architecture docs, specs, or design documents, link to them from the relevant sections. Do not reproduce their content in the README. - **Active voice, present tense.** "The harness compares outputs" not "Outputs are compared by the harness." - **Concrete over abstract.** Prefer "123 Unix utilities" over "a large number of tools." Prefer "runs both binaries with identical inputs and compares stdout byte-for-byte" over "performs comprehensive testing." # Technical Document Types We catalog the document types of standards bodies and engineering practice. Each entry gives a short purpose statement, where the type originates, when to choose it, and the structure to follow when one is established. We list types in roughly the order they arise in a project's life: from idea, to requirements, to design, to standardisation. This catalog covers the external and industry forms. For documents inside a repository following our conventions, the YAML document types in [documentation-standards.md](documentation-standards.md) (VISION, ARCHITECTURE, PRDs, use cases, test suites) take precedence; use this catalog to pick the right form when writing for an audience outside the repo. ## Concept Paper A concept paper proposes a new idea or primitive and argues for it. It is exploratory, not prescriptive. Length is typically a few pages to a short chapter. Origin. Common in academic and industrial research practice. The form has no single owning body. Funding agencies such as the US National Science Foundation and the European Commission use the term for short pre-proposals that precede a full grant application. When to use. Early-stage work where the goal is to establish a vocabulary, a problem framing, or a single design primitive. Useful for circulating to peers before committing to a full design or specification. Structure. There is no canonical template. A common shape is: - Motivation and problem statement - Background and related work - Proposed concept, named and defined - Worked scenario or example - Open questions and next steps ## Position Paper A position paper argues for a stance on a contested question. It is shorter and more polemical than a concept paper. The author takes a side and defends it. Origin. Standard format in academic workshops and standards bodies such as the IETF and W3C, where workshop calls often request 2 to 4 page position papers to seed discussion. When to use. To frame a debate, push back on a prevailing approach, or stake a claim in advance of a design effort. Structure. Even shorter than a concept paper. Typical elements: - The question or claim - The author's position, stated up front - Supporting arguments - Acknowledgement of counter-arguments - Implications if the position is accepted ## Whitepaper A whitepaper is an authoritative report that explains an issue, a technology, or a solution to a non-specialist technical audience. It is longer than a concept or position paper and reads as a finished piece. Origin. The term originated in British government practice in the 1920s for policy reports. The technology industry adopted the format in the 1990s, and vendors use it heavily. When to use. To communicate a mature view of a technology or architecture to customers, partners or executives. Whitepapers presume the reader is technical but not expert in the specific area. Structure. Publisher templates vary. A common structure is: - Executive summary - Problem statement and context - Proposed approach - Benefits and trade-offs - Case studies or worked examples - Conclusion and call to action - References ## Product Requirements Document (PRD) A PRD captures what a product should do, for whom, and why. It is written before design begins, and signed off by product, engineering and design stakeholders. Origin. The PRD is a product-management convention, popularised by Marty Cagan's *Inspired* and widely used at firms such as Google, Microsoft and Atlassian. There is no standards body. Atlassian, Aha! and ProductPlan publish reference templates. When to use. When a product or feature is being scoped, before architecture or implementation work starts. For PRDs inside a repository following our conventions, the repo's own PRD format (see documentation-standards.md) takes precedence; this entry describes the industry form. Structure. Typical sections: - Objective and success metrics - Target users and personas - User stories and use cases - Functional requirements - Non-functional requirements (performance, accessibility, security) - Out of scope - Open questions - Release criteria ## System Requirements Document (SRD) or Software Requirements Specification (SRS) An SRD or SRS captures the requirements a system must satisfy in normative form. Where the PRD speaks the language of the product, the SRD speaks the language of the system being built. Origin. The canonical reference is IEEE 830-1998, *Recommended Practice for Software Requirements Specifications*, superseded by ISO/IEC/IEEE 29148-2018, *Systems and software engineering — Life cycle processes — Requirements engineering*. The European Cooperation for Space Standardization publishes a parallel document, ECSS-E-ST-10-06C, for space systems. When to use. In regulated, safety-critical or contractually scoped projects where a normative baseline is required. Structure. IEEE 830 prescribes: 1. Introduction (purpose, scope, definitions, references, overview) 2. Overall description (product perspective, functions, user characteristics, constraints, assumptions) 3. Specific requirements (external interfaces, functions, performance, logical database requirements, design constraints, software system attributes) 4. Supporting information (appendices, index) Requirements are written with "shall" verbs and given identifiers for traceability. ## Architecture Requirements Document (ARD) An ARD captures the architecturally significant requirements (ASRs) that constrain the system design. It is a focused subset of the SRD, surfacing the requirements that drive architectural decisions. Origin. The ARD is less standardised than the SRD. The SEI's *Software Architecture in Practice* (Bass, Clements, Kazman) defines architecturally significant requirements as the centre of architecture work. Some organisations split the ARD out as a separate artefact; others fold it into the SRD or the architecture description. When to use. When the project is large enough that quality attributes (performance, security, scalability, modifiability) need explicit elaboration before design starts. Structure. A common shape: - Business goals and drivers - Stakeholders and concerns - Functional ASRs - Quality attribute scenarios (stimulus, source, environment, response, measure) - Constraints (technical, regulatory, organisational) - Assumptions ## Architecture Design Document (ADD) An ADD describes how a system is structured to meet its requirements. It covers components, interfaces, data, deployment and the rationale that ties the design to the requirements. Origin. ISO/IEC/IEEE 42010, *Systems and software engineering — Architecture description*, is the international standard for what an architecture description must contain. The IEEE 1471 predecessor introduced the multi-view concept formally in 2000. TOGAF and the SEI Views and Beyond approach both build on 42010. When to use. After requirements are stable and before implementation begins. Maintained through the life of the system as the source of truth for its structure. Structure. ISO/IEC/IEEE 42010 requires the description to identify: - Stakeholders and their concerns - Architecture viewpoints used - Architecture views, one per viewpoint - Correspondence rules between views - Architecture rationale - Architecture decisions (often captured as ADRs) Common views include functional, information, deployment, concurrency, operational and security. ## Architecture Decision Record (ADR) An ADR records a single architectural decision: the context that forced it, the decision taken, and the consequences. ADRs are short, dated and append-only. Origin. Michael Nygard introduced the ADR format in a 2011 blog post, *Documenting Architecture Decisions*. The format has been adopted widely; ThoughtWorks placed ADRs in the *Technology Radar* "adopt" ring, and GitHub hosts a community catalogue at `adr.github.io`. When to use. Every time a decision is made that future maintainers would otherwise have to reverse-engineer. ADRs accumulate in the repository over the life of the project. Structure. Nygard's original template: - Title (short noun phrase) - Status (proposed, accepted, deprecated, superseded by ADR-N) - Context (the forces at play) - Decision (the response to those forces) - Consequences (positive, negative and neutral outcomes) Variants such as MADR (Markdown Architectural Decision Records) add sections for considered options and decision drivers. ## Request for Comments (RFC) An RFC is a written proposal circulated for review before adoption. The term covers two related but distinct practices. Origin. The IETF RFC series began in 1969. Steve Crocker's RFC 1 documented the *Host Software* protocol for the ARPANET. The series is now managed by the RFC Editor and governed by RFC 2026, *The Internet Standards Process*. Internally, many technology companies (Squarespace, Uber, Oxide, Rust) run their own RFC processes adapted from the IETF model. When to use. - IETF RFCs document Internet protocols, formats and processes. They are authoritative once published. - Internal RFCs propose significant changes to a codebase or architecture before implementation begins. They sit between an ADR (which records a decision already taken) and a design document (which assumes the decision is made). Structure. The IETF RFC format is prescribed by RFC 7322. Common sections: - Abstract - Status of this memo - Copyright notice - Table of contents - Introduction - Conventions and terminology (often citing RFC 2119 for "MUST", "SHOULD") - Body (protocol mechanics, formats, behaviour) - Security considerations - IANA considerations - References (normative and informative) - Author addresses Internal RFC templates are lighter, typically: - Summary - Motivation - Proposed change - Alternatives considered - Drawbacks - Open questions - Adoption plan ## Engineering Design Document (EDD or Design Doc) The engineering design document, often just called a "design doc", is the working artefact engineers write before building a feature or service. It sits below the ADD and above the code. Origin. Google's internal design-doc culture, described publicly by Malte Ubl and others, popularised the form. The pattern predates Google and exists in most large engineering organisations under different names. When to use. Before writing non-trivial code. The design doc is the input to peer review and the artefact that captures the design that was actually built. Structure. A common shape: - Context and goals - Non-goals - Proposed design (data model, APIs, components) - Alternatives considered - Cross-cutting concerns (security, privacy, observability, rollback) - Migration and rollout - Testing strategy - Open questions - Appendix ## Specification A specification is a precise, normative description of an interface, format or protocol. It is the artefact an implementer reads in order to build a conforming implementation. Origin. Specifications come from many bodies. ISO, IEC, IEEE, ITU-T, 3GPP, ETSI, IETF, W3C, TM Forum and OASIS all publish specifications under their own processes and document conventions. When to use. When multiple independent implementations must interoperate, or when conformance is going to be tested. Structure. Varies by body. Common elements: - Scope and conformance criteria - Normative references - Terms and definitions - Symbols and abbreviations - Body (normative requirements, often with "shall" and "should") - Conformance clause - Annexes (normative and informative) ## Invention Disclosure An invention disclosure is filed inside a company to describe an invention before a patent application is drafted. It is internal, confidential and written to a template the patent committee can evaluate. Origin. Each company maintains its own template; there is no external standards body. When to use. Whenever an invention is made and the company wants to consider patenting it. The [patent-disclosure skill](../skills/patent-disclosure/SKILL.md) writes disclosures to an eleven-section template with a four-axis self-assessment. Structure. Company templates typically include: - Title and claim - Inventors - Problem and prior art - Proposed solution - Embodiments and variations - Advantages - Evidence of novelty ## Quick Reference | Document | Primary purpose | Authoritative source | |---|---|---| | Concept paper | Propose an idea | None | | Position paper | Argue a stance | Workshop conventions | | Whitepaper | Explain to a wide audience | Publisher template | | PRD | Capture product intent | Industry practice | | SRD / SRS | Capture normative system requirements | ISO/IEC/IEEE 29148-2018 | | ARD | Capture architecturally significant requirements | SEI practice | | ADD | Describe the architecture | ISO/IEC/IEEE 42010 | | ADR | Record one decision | Nygard (2011) | | RFC (IETF) | Standardise a protocol | RFC 7322, RFC 2026 | | RFC (internal) | Propose a significant change | Local convention | | Design doc / EDD | Plan an implementation | Local convention | | Specification | Define an interface for conformance | SDO of origin | | Invention disclosure | Seed a patent application | Company template; patent-disclosure skill | ## References - ISO/IEC/IEEE 29148-2018, *Systems and software engineering — Life cycle processes — Requirements engineering*. - ISO/IEC/IEEE 42010:2022, *Software, systems and enterprise — Architecture description*. - IEEE 830-1998, *Recommended Practice for Software Requirements Specifications* (superseded). - IETF RFC 2026, *The Internet Standards Process — Revision 3*, S. Bradner, 1996. - IETF RFC 7322, *RFC Style Guide*, H. Flanagan and S. Ginoza, 2014. - IETF RFC 2119, *Key words for use in RFCs to Indicate Requirement Levels*, S. Bradner, 1997. - M. Nygard, *Documenting Architecture Decisions*, blog post, 2011. - L. Bass, P. Clements, R. Kazman, *Software Architecture in Practice*, 4th ed., Addison-Wesley, 2021. - M. Cagan, *Inspired: How to Create Tech Products Customers Love*, 2nd ed., Wiley, 2017. - The Open Group, *TOGAF Standard, 10th Edition*, 2022. - MADR project, *Markdown Architectural Decision Records*, https://adr.github.io.