Documentation governance¶

English | 日本語

Purpose¶

Documentation preserves knowledge that cannot be reconstructed reliably from code and gives people a coherent view for understanding, supervising, and governing AI Teams. It is not a second implementation or project tracker.

Canonical language and translation¶

English is normative and canonical. Japanese is an official reader-facing translation maintained for owner review and comprehension, not an unreviewed machine-translation artifact. When the two conflict, English governs.

Every authored Japanese page in site navigation has a corresponding English path and reciprocal language links. A change to normative English content must update its Japanese page in the same outcome or explicitly remove that page from the official translated surface. Generated pages are regenerated in both locations from one machine source. The docs validator enforces path pairing and language links; review enforces semantic fidelity.

What to preserve¶

Hand-maintained documentation is appropriate for:

• product intent and engineering principles;
• current accepted architecture and system-level sequences;
• responsibility and trust boundaries;
• design constraints and major invariants;
• decision rationale, agreement history, and revisit conditions; and
• user tasks whose safe completion cannot be inferred from code alone.

Function, class, file, option, schema, and supported-value facts that can be reconstructed from code/config/tests are generated or linked, not restated.

Source-of-truth model¶

Documentation → intent, policy, current accepted architecture
Tests/gates   → enforceable invariants
Code/config   → actual behavior and reconstructable facts
GitHub        → decisions, agreement history, and mutable project state

If documentation states a mechanically enforceable invariant, the owning change adds or identifies a test or quality gate. Documentation explains why the invariant exists; tests prove representative success and failure paths; code implements the behavior.

Architecture and decisions¶

Architecture pages describe the currently accepted system in the present tense: major components, sequences, responsibility and trust boundaries, invariants, external dependencies, and the relationship among runtime, verification, and delivery. They do not contain function- or class-level manuals.

Design rationale and agreement history live in GitHub Issues with the decision label. A Decision Issue contains Context, Problem, Options considered, Decision, Rationale, Trade-offs, Rejected alternatives, Revisit conditions, Affected architecture, and Status. Status is one of Proposed, Accepted, or Superseded; when superseded, the Issue links to its successor.

The reciprocal-link contract is:

Architecture → Why? → Decision Issue
Decision Issue → Current state? → Architecture page and stable heading

Add the Architecture link to the Decision Issue before setting it to Accepted. Add or update the Issue link in the same architecture pull request. The Issue records the pull request or accepted commit. The Decision template collects the required fields. GitHub remains canonical even when a site link is temporarily unavailable.

Diagram policy¶

The primary purpose of an architecture diagram is to help a person understand, review, and discuss a system or change quickly and correctly. Agent context is a useful secondary benefit, not the reason to create a diagram. Use the smallest living view that answers one important question when prose alone makes responsibility, boundaries, ordering, state, domain semantics, or trust flow easy to misunderstand.

Select the view from the difficult question:

Question	Preferred view
Structure, responsibility, system boundary, or high-level topology	C4 Context or Container
Interaction and effects over time	UML Sequence
Lifecycle and transition conditions	UML State
Material domain relationships, ownership, or cardinality	UML Class or domain diagram
Credentials, untrusted inputs, identities, privilege, or data movement	Data-flow or trust-boundary diagram

C4 is the first choice for architecture overview. Context shows people, the system boundary, and external systems. Container shows the responsibilities of major applications, runtimes, services, and data stores. Use Component only when an internal responsibility, security, or authority boundary is material; do not mechanically draw every component. Do not keep Code views or exhaustive class diagrams as durable documentation by default because code-level structure is usually reconstructable and prone to drift.

Sequence, State, domain, and data-flow views complement C4. Use Sequence when caller order and effect timing matter, State when transition conditions would be ambiguous in prose, and Class/domain only for complex domain semantics—not to copy the codebase. For security-sensitive changes, prefer an explicit trust boundary whenever it clarifies credential, process identity, privilege, or authority transitions better than C4 or UML alone. Authors choose the notation from the question; they do not ask readers to design the diagram method.

Minimal and proportional use¶

Diagrams are recommended for cross-component architecture, asynchronous or distributed interaction, lifecycle state machines, security or authority boundaries, deployment topology, multiple external providers, complex domain relationships, or structures with high onboarding cost. They are normally unnecessary for a trivial or single-component change, code-obvious structure, a question answered precisely in a few lines, copied implementation detail, or detail too volatile to remain current.

Documentation risk tiers guide consideration rather than impose artifacts:

• Tier 0 normally needs no diagram.
• Tier 1 uses one only when it materially improves understanding.
• Tier 2 considers the narrowest useful C4, Sequence, State, domain, or data-flow view for material design review.
• Tier 3 strongly considers a trust, state, or interaction view when it enables independent security or authority review.

Never require C4 merely because a change is Tier 2. Ask whether a diagram would materially improve human understanding or independent review. Prefer one Container view for an unclear responsibility split or one Sequence view for an unclear release flow over a full set of Context, Container, Component, Class, Sequence, and State diagrams.

Format, authority, and maintenance¶

Follow an existing project diagram standard. Otherwise prefer Mermaid, then PlantUML, then another maintainable version-controlled text format. The source should be both human-readable and machine-editable. A project may override the selection or format in its existing policy; when it does not, the compact default is:

documentation:
  diagrams:
    architecture_default: c4
    text_format: mermaid
    uml:
      sequence: preferred_for_interaction
      state: preferred_for_lifecycle
      class: optional

Do not expand configuration just to restate these defaults. Keep each view high-level enough to remain stable and detailed enough to answer its one question. Follow the existing documentation structure; create docs/architecture/ only when it fits that structure. Keep the README to at most one high-level Context or Container view plus links to detailed pages.

Principles, Decision records, contracts, schemas, code, and tests retain their authority. A diagram is visual compression and is never the sole contract for a security invariant, API, schema, or behavior. Link material architecture views to their Decision Issue so the reason is not lost. Label proposed architecture explicitly and keep it separate from the current accepted view; never present a proposal as current fact.

Check relevant diagrams when a component or service is added, a responsibility or boundary moves, a provider or external integration changes, a state transition changes, a security flow changes, or deployment topology changes. Do not inspect every diagram for every code edit. Update, simplify, delete, or supersede a stale view instead of preserving misinformation.

Review an AI-generated view against the actual implementation and authority contracts. Confirm ownership, arrow meaning, trust boundaries, component existence, and current/proposed status. Syntax, link, and referenced-file checks are useful lightweight validation; architecture correctness remains a semantic review. This policy does not introduce strict UML enforcement, a modeling tool, a diagram database, automatic generation, or repository-wide image creation.

Human and machine documentation boundary¶

Human-facing docs explain purpose, concepts, accepted structure, task journeys, and governance. Distributed SKILL.md and one-level references/ files remain machine-facing canonical execution contracts. Tests remain the enforceable boundary. Link across these layers only where a reader or agent must cross the boundary; do not copy whole procedures between them.

AGENTS.md and SKILL.md are maps, not manuals. They contain repository or Skill purpose, essential constraints, validation entry points, authoritative source locations, and task routing. Detailed conditional guidance belongs in a linked canonical document.

Generated reference¶

Human-readable reference is required even when the facts are machine-derived. The current generation target is the installed capability surface: Plugin identity, Skills, MCP servers, and accepted provider operations. Its inputs are the Plugin manifest, Skill front matter, MCP manifest, and versioned capability registries. python3 scripts/docs.py generate writes the English and Japanese reference pages; python3 scripts/docs.py check rejects stale output.

Future candidates include CLI, configuration, schema, compatibility, and supported profile values. Add a target only when it has one authoritative machine source, deterministic ordering, a freshness check, and a human use case.

Mutable project state¶

Backlog, active work, short-term migration status, release preparation, unresolved defects, and planned changes live in GitHub Issues, pull requests, milestones, and releases. Permanent docs may state stable policy and link to the relevant tracker query, but never mirror this state.

Maintenance decision¶

For every documentation change, choose one disposition:

• KEEP: unique durable intent remains in its canonical location;
• MOVE: the content belongs to a clearer canonical location;
• MERGE: another source already owns the same intent;
• GENERATE: facts have a deterministic machine source;
• LINK: another canonical source should remain authoritative; or
• DELETE: content is obsolete, temporary, reconstructable, or valueless.

Deletion and supersession are normal maintenance. Git history and Decision Issues preserve evidence; obsolete pages do not remain indefinitely “just in case.”

Before creating a page, ask whether the information is reconstructable, mutable project state, rationale, current system intent, already canonical elsewhere, and likely to remain valuable. Generate, move to GitHub, link, merge, or omit it when those answers indicate a better owner.

Initial inventory disposition¶

Existing source	Purpose	Disposition	Result
README.md	USER plus mixed operations/development detail	MERGE/MOVE	concise English entry point; detail routes into docs or machine contracts
former Japanese README.md	USER plus mixed detail	MOVE/MERGE	official concise README.ja.md
former docs/self-hosting.md	USER operations	MOVE	paired docs/en|ja/user/self-hosting.md; old path deleted
plugins/ai-teams/skills/*/SKILL.md	MACHINE CONTRACT and routing	KEEP/LINK	remains distributed and links to conditional references
plugins/ai-teams/skills/*/references/*.md	MACHINE CONTRACT	KEEP/LINK	remains canonical for executable task contracts; human docs link selectively
plugins/ai-teams/capabilities/**/references/*.md	MACHINE CONTRACT	KEEP/LINK	remains beside the owning capability
Plugin manifest, MCP manifest, capability registries	REFERENCE source	GENERATE	produces paired capability reference
integration/deployment references	MACHINE CONTRACT	KEEP/LINK	remains beside optional runtime components
release-management references	MACHINE CONTRACT	KEEP/LINK	remains beside the release Skill
evaluation fixture Markdown	test fixture	KEEP	excluded from reader navigation and treated as test data
backlog, migration status, release preparation	PROJECT STATE	DELETE from docs/LINK	GitHub objects remain authoritative

No current machine contract was identified as obsolete solely from its content location. Retired capability or architecture divergence found later receives a separate Issue instead of being silently rewritten during documentation work.

Site and validation¶

Markdown is the source. MkDocs builds disposable HTML with explicit English and Japanese navigation, search, anchor permalinks, and code highlighting. Generated HTML is not committed or edited.

Publication policy¶

AI Teams publishes the validated MkDocs site/ artifact to GitHub Pages from accepted main documentation state. Repository Markdown and maintained machine-readable/generated sources remain canonical; GitHub Pages is a discoverable distribution projection, not a second documentation source. scripts/docs.py build is the only documentation build command used by the deployment workflow, so it preserves the existing generated-reference, translation, navigation, link, and strict-rendering checks. The Pages search surface publishes the maintained English and Japanese documentation selected by this repository's language policy.

The workflow can build and submit the artifact, but it cannot assume authority to enable GitHub Pages, choose its deployment source, grant repository permissions, configure a domain, or change DNS. If GitHub Pages is not already configured for GitHub Actions after an accepted change, the repository administrator must enable that deployment source before a hosted result can be verified. Until the default Pages URL is observable, the publication path is configured but not published; any custom domain remains separate work.

The required quality path checks generated-reference freshness, paired translations and language links, navigation coverage, safe internal Markdown links and anchors, then runs mkdocs build --strict. External URL availability and semantic translation quality remain review concerns; CI does not crawl the network or claim that matching paths mean equivalent meaning.