# Create Architecture Document

> Creates or updates ARCHITECTURE.md from repository evidence. Use when a project needs to define, repair, or review its structural organization, boundaries, and dependency rules.

- Skill: `egohygiene/create-architecture-document` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add egohygiene/create-architecture-document`
- Raw SKILL.md: https://api.skillmd.com/api/skills/egohygiene/create-architecture-document/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: egohygiene (https://skillmd.com/u/egohygiene)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/egohygiene/create-architecture-document

---


# Create Architecture Document

<!-- aether-continuity-disposition: reader-writer -->

## Repository continuity composition

For repository-scoped work, compose `maintain-repository-continuity` in
**Resume** mode before selecting work. After an authorized repository change
passes domain validation, compose **Refresh** and **Verify** immediately before
presenting the pull request, and include the reconciled root `CONTINUITY.md` in
the same change. A policy-permitted no-change or exemption result must be
documented instead of fabricating an edit.

- **Contribute:** Observed structural boundaries, dependencies, decisions, validation, and open questions
- **Never claim:** That unverified current architecture or proposed decisions are established fact

## Purpose

Create, update, or validate `ARCHITECTURE.md` in conformance with
`architecture-architecture`.

Primary question:

> How is this project structurally organized to accomplish its purpose?

## Use This Skill When

- the canonical document is missing
- structural boundaries are unclear or conflicting
- major subsystems or dependency directions changed
- `SYSTEM.md` exists but the structural organization is still implicit
- architecture review needs a canonical explanation of layers, boundaries, or communication patterns

## Do Not Use This Skill For

- redefining which major systems exist when `SYSTEM.md` is the real gap
- documenting deployment topology, provisioning, or infrastructure operations
- recording decision rationale owned by `DECISIONS.md`
- writing detailed APIs, algorithms, or source-file walkthroughs
- producing an implementation plan or roadmap

## Required Inputs

Resolve:

- governing specification and version
- `SYSTEM.md`
- relevant upstream identity and foundation documents
- current repository or system boundary evidence
- known architectural constraints, contradictions, and open questions

## Optional Inputs

Use when available:

- `DESIGN.md`
- `ONTOLOGY.md`
- existing diagrams or decomposition notes
- accepted ADRs that constrain structure

Missing evidence must be recorded rather than invented.

## Workflow

1. Read `library/organization/specs/architecture/foundation/architecture.spec.md`.
2. Read the upstream documents that define purpose, foundations, and the current system model.
3. Identify the stable structural units, layers, or subsystems that actually organize the project.
4. Separate system inventory from structural organization so `SYSTEM.md` and `ARCHITECTURE.md` do not become duplicates.
5. Make boundaries, dependency direction, coordination patterns, and important constraints explicit.
6. Keep tactical implementation, deployment, and ADR rationale out of the document unless the specification requires a concise reference.
7. If evidence conflicts, preserve the conflict, label assumptions, and report provisional or blocked completion.
8. Draft or update `ARCHITECTURE.md` using `templates/ARCHITECTURE.template.md`.
9. Validate with `references/validation-checklist.md` and `references/authoring-guide.md`.

## Output Contract

Produce or update:

- `ARCHITECTURE.md`
- governing specification identifier and version
- explicit assumptions, contradictions, and open questions
- validation results
- downstream review recommendations for affected documents such as `SYSTEM.md`, `DESIGN.md`, or ADRs

## Boundaries

`ARCHITECTURE.md` owns structural organization, boundaries, dependency direction,
and communication patterns.

It does not own system decomposition best handled by `SYSTEM.md`, durable
rationale owned by `DECISIONS.md`, roadmap sequencing, or implementation detail.

## Validation

Use [references/validation-checklist.md](references/validation-checklist.md)
for mandatory checks and
[references/authoring-guide.md](references/authoring-guide.md) for
boundary, evidence, and anti-pattern guidance.

## Blocked or Provisional Outcomes

If the system model is missing, structure is contradicted by evidence, or major
boundaries cannot be justified, do not fabricate a final architecture. Report
whether the outcome is blocked, provisional, or limited to a partial update.

## Completion Criteria

- [ ] `architecture-architecture` is identified as the governing specification.
- [ ] Required upstream evidence has been read.
- [ ] The primary question is answered directly.
- [ ] Structural boundaries and dependency direction are explicit.
- [ ] Ownership boundaries with `SYSTEM.md` and `DECISIONS.md` are respected.
- [ ] Assumptions, contradictions, and open questions are visible.
- [ ] Acceptance criteria and package-level validation checks pass.