AI-Architecture-Toolkit

Imported from Future-CX/AI-Architecture-Toolkit (AGENTS.md). Install upstream with npx skills add Future-CX/AI-Architecture-Toolkit. Copyright stays with the author.

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.

PRINCIPLES

When creating principles, use the write-a-principle skill.

Generated principle documents belong under principles/ in the consuming repository. Do not add company-confidential principle examples to this public toolkit.

CAPABILITIES

When creating capability overviews, use the capability-overview skill.

Generated capability overviews belong under capabilities/<slug>/ in the consuming repository. Do not write real company capability context into this public toolkit.

SOLUTION ARCHITECTURES

When creating solution architecture designs, use the solution-architecture-design skill.

Solution architecture design outputs belong under solution-architectures/<slug>/ in the consuming repository, or under the private lab root when this toolkit is used as a submodule.

When a solution architecture design creates diagrams:

• Store each Draw.io source as a separate .drawio file under the design document's diagrams/ subfolder.
• Export a same-basename .svg file into the same diagrams/ subfolder for every .drawio file when the diagram must be embedded.
• Embed the .svg file in the design document.
• Link the .drawio source near the embedded SVG.

When creating any Draw.io diagram, use the create-drawio-diagram skill because it contains the diagram instructions, style rules, and templates. Always store generated .drawio files and same-basename .svg exports under a diagrams/ subfolder next to the document they support. Do not place diagram files beside the document.

When creating target architecture documents, use the target-architecture-document skill.

SKILLS

Skills are organized as folders under skills/.

When creating skills, use the create-a-skill skill.

Each skill entry in the top-level README.md must link the skill name to its SKILL.md.

The skills/README.md file must list every skill with a one-line description and link the skill name to its SKILL.md.

Each skill folder should include a README.md when the skill needs local usage notes, templates, scripts, or resources explained outside SKILL.md.

When updating skills, also update the public homepage at www/index.html if the visible skills list or skill positioning changes.

TEMPLATES

Use existing templates before creating new ones.

When changing a template, update the owning skill instructions so future generated documents replace placeholders completely and do not leave drafting guidance in final artifacts.

When a template change affects public-facing behavior, update the top-level README.md and www/index.html if needed.