ai-architecture-context-toolkit

Create or refresh the minimum AI-facing guidance (AI Architecture Context, AI Coding Guidelines, Brownfield Guardrails, source-map/root-file proposals) for safe AI-assisted delivery in a repository. Use when starting AI delivery in a repo, onboarding a new service/module/bounded-context/team, creating the first Context or Guidelines, or checking whether existing guidance is usable. Not for story-specific planning (use ai-context-check) or guidance evolution (use ai-guidance-update).

Check whether a story, analysis, implementation plan, pull request, diff, or solution note aligns with the approved AI Architecture Context and AI Coding Guidelines. A planning-time and review-time governance check that catches locally reasonable but directionally wrong solutions. Use before implementation when possible, or during PR review. Not for first-time context setup (use ai-context-bootstrap) or guidance evolution (use ai-guidance-update).

Analyze and apply controlled, approved updates to the AI Architecture Context, AI Coding Guidelines, and Brownfield Guardrails — so useful learnings don't die in chat, PRs, or solution notes, and unapproved learnings don't silently become governance rules. Use when a candidate learning could change future AI behavior — the AI makes a wrong assumption the guidance should prevent, a review surfaces an uncovered issue, a brownfield pattern misleads AI, a target direction becomes clear, an ADR/spec changes, or a reusable learning is found. Default mode is analyze-only; never applies governance-impacting updates without explicit approval.

Decide, for each relevant concern, whether an approved source already settles it (→ a final rule for the clean context) or it needs a human decision (→ a proposal in the clarifications ledger). Surfaces only concerns that matter — variation already evidenced, high impact if they vary, or a cross-cutting/framework standardization — never a catalog of every existing pattern. Use while drafting or refreshing the Context/Guidelines, or checking a work item for coverage gaps.

Locate a repo's AI-context inputs via the source map — the thin, structured map of where guidance, sources, and the clarifications ledger live, plus the authority order. When it's present, resolve each entry (explicit path, else search fallback); when it's absent, discover by convention and propose the map. Returns a structured source list, not prose. Use during discovery in bootstrap, check, or update.

How to draft or refresh the two thin AI-facing files — the AI Architecture Context and the AI Coding Guidelines: provenance header, rule shape, weighting, the ordered section lists, and what to exclude. Use while writing either file in bootstrap or guidance-update. Pairs with assess-coverage (what to cover); this skill is how to write it.

Decide, for each relevant concern, whether an approved source already settles it (→ a final rule for the clean context) or it needs a human decision (→ a proposal in the clarifications ledger). Surfaces only concerns that matter — variation already evidenced, high impact if they vary, or a cross-cutting/framework standardization — never a catalog of every existing pattern. Use while drafting or refreshing the Context/Guidelines, or checking a work item for coverage gaps.

Locate a repo's AI-context inputs via the source map — the thin, structured map of where guidance, sources, and the clarifications ledger live, plus the authority order. When it's present, resolve each entry (explicit path, else search fallback); when it's absent, discover by convention and propose the map. Returns a structured source list, not prose. Use during discovery in bootstrap, check, or update.

Write a Brownfield Guardrail when current code and target direction differ in a way that could mislead the AI — capturing what to use, what not to copy, and when to ask. Use when creating, updating, or applying one (in bootstrap, guidance updates, or brownfield review). A Guardrail records a divergence; it never originates an architecture decision.

How to draft or refresh the two thin AI-facing files — the AI Architecture Context and the AI Coding Guidelines: provenance header, rule shape, weighting, the ordered section lists, and what to exclude. Use while writing either file in bootstrap or guidance-update. Pairs with assess-coverage (what to cover); this skill is how to write it.

Write a Brownfield Guardrail when current code and target direction differ in a way that could mislead the AI — capturing what to use, what not to copy, and when to ask. Use when creating, updating, or applying one (in bootstrap, guidance updates, or brownfield review). A Guardrail records a divergence; it never originates an architecture decision.