AI-Architecture-Toolkit: Instructions file for Codex

AGENTS

When creating agents, use the create-an-agent skill.

When creating or updating agents:

• Update the Agents table in the top-level README.md.
• Update the public homepage at www/index.html when the visible agent list or agent positioning changes.
• Keep agent briefs under agents/.
• Do not create real-company agent variants in this public repository.

EXAMPLES

GOVERNANCE

Do not add company-confidential information, customer names, internal system names, proprietary architecture details, credentials, or non-public business context to this repository. Use a separate private company lab repository for real-world testing.

Generated artifacts that contain real company context belong in a private company lab repository, not in this public toolkit. This includes real glossaries, ADRs, capability overviews, target architecture documents, solution architecture designs, diagrams, roadmaps, and review findings.

Toolkit-aware scripts and agents should honor .toolkitignore when deciding what counts as active toolkit content.

READABILITY

When creating stakeholder-facing documents:

• Treat non-technical business stakeholders as the primary audience.
• Start with the business outcome, the decision or recommendation, and the operational impact.
• Use plain language first. Add technical detail only when it changes a decision, risk, cost, ownership, timeline, or support model.
• Prefer short sentences, short paragraphs, clear headings, and concrete trade-offs.
• Prefer short sections and bullet lists over tables. Tables are often harder for people to read, especially when cells contain full sentences or detailed explanations.
• Use a table only when it makes a compact comparison, repeated field mapping, or index materially easier to scan. Move detailed explanation into prose, bullets, or an appendix.
• Keep dense implementation detail in later sections or appendices after the stakeholder summary.
• Avoid unnecessary technical jargon. Explain acronyms and domain-specific terms when first used.
• Make recommendations, decisions, owners, risks, and open questions easy to find.
• Before finishing, reread the opening sections and simplify any sentence that a business reader would need to parse twice.