architecture-knowledge-toolkit

Apply the architecture-knowledge-toolkit baseline for architecture documentation, traceability, metadata, quality scenarios, risks, ADRs, and adapter boundaries. Use before architecture-sensitive work or when creating derived agent adapters from canonical skills.

Enforce Living Documentation through Behaviour-Driven Development by writing a language-agnostic Gherkin feature specification for any new or changed observable behaviour and mapping each scenario to at least one automated verification, even when the target language has no native BDD framework. This is the strict default for features, behavioural enhancements, and behaviour-changing bug fixes; relax it only with an explicit recorded human waiver. Use when Codex is asked to specify feature or behaviour, write or update .feature files, add BDD or acceptance tests, keep behaviour specs and tests in sync, bridge Gherkin scenarios to classic tests, or apply a scenario-to-test naming convention with Given/When/Then structure.

Analyze and document architecture impact for feature requests, Epic issues, UserStory issues, refactoring tasks, issue implementation, and review tasks. Use when Codex is asked to handle a feature request, decide whether feature work should become an Epic or UserStory, create or refine an Epic, mark a UserStory or refactoring issue, implement feature or refactoring work, review a pull request or review task, assess whether code changes affect architecture documentation, update affected arc42 sections, connect features or refactorings to ADRs, quality goals, quality scenarios, risks, components, runtime scenarios, deployment views, or create follow-up ADRs with diagrams.

Implement GitHub issue work using the repository workflow: start from the latest main branch, create an issue_<number> branch, make focused changes, verify, commit using the commit-message skill, push, and open a pull request. Use when Codex is asked to implement or fix a GitHub issue, continue issue work, prepare a PR for issue work, or address pull request review comments.

Create proposed Architecture Decision Records and analyze their impact on related architecture artifacts. Use when Codex needs to draft or update ADRs, inspect existing architecture documentation and source code, compare options with a Pugh matrix, identify affected risks and quality scenarios, propose traceability metadata relations, update impacted artifacts only when justified, or produce an ADR impact report.

Create proposed quality scenarios and analyze their traceability to quality objectives, ADRs, risks, requirements, architecture artifacts, and code evidence. Use when Codex needs to draft or update measurable quality scenarios, inspect existing arc42 Chapter 10 quality requirements, derive scenarios from source evidence without inventing targets, propose metadata relations, or produce a quality scenario impact report.

Create proposed architecture risk artifacts and analyze their traceability to ADRs, quality scenarios, requirements, components, controls, and evidence. Use when Codex needs to identify, draft, update, prioritize, or review architecture risks, separate risks from issues and decisions, propose mitigations, or produce a risk impact report without deciding acceptance.

Bootstrap a new repository so its product clarification and architecture documentation follow the architecture-knowledge-toolkit structure instead of a generic arc42 document. Use when an agent is asked to create, initialize, migrate, or repair architecture documentation for a new project, especially when the user says the project should follow the architecture-knowledge-toolkit skills, contracts, docs-as-code conventions, arc42 structure, ADR/risk/quality scenario formats, traceability metadata, generator contracts, or generated include-fragment approach.

Review GitHub pull requests and proposed branch changes for correctness, regressions, missing tests, documentation-contract violations, traceability gaps, and reviewability. Use when an AI assistant is asked to review a PR, review pull request changes, inspect a PR branch before merge, or produce PR review comments.

Review explicit architecture traceability metadata for gaps, inconsistencies, unsupported claims, stale links, dangling references, and metamodel violations. Use when Codex needs to inspect artifact relations, validate ADR-to-risk or quality-scenario coverage, propose relation updates, or produce an evidence-backed traceability review report.

Create or update docs-as-code presentation material as AsciiDoc reveal.js decks rendered with docs-toolbox. Use when Codex needs to prepare talks, meetup or conference proposals, speaker notes, demo scripts, event-specific artifacts under talks/, or slide decks that must remain repository-native rather than PowerPoint or Google Slides files.

Interview the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.

Synchronize a local checkout after a pull request has been integrated: verify a clean worktree, switch to the base branch, fast-forward from the remote, confirm the PR changes are present, and clean up local and remote PR branches when safe. Use when an agent is asked to clean up after an integrated PR or return the repository to the latest base branch.

Slice GitHub parent issues into reviewable real sub-issues. Use when Codex is asked to split, slice, decompose, refine, or plan a GitHub issue into child issues, sub-issues, implementation slices, or reviewable follow-up issues before implementation work begins.

Write repository commit messages. Use when an agent creates commits, prepares commit text, reviews commit history, or updates workflow guidance that mentions commit messages.

Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.

A relentless interview to sharpen a plan or design.

A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.