maintain-project-architecture

name: maintain-project-architecture description: Maintain docs/architecture/ARCHITECTURE.md, SLICES.md, and architecture.json for a repository's product/module architecture and provable code slices. Use when a repo needs architecture docs that explain Swift products, Codex plugins, skills, MCP configs, modules, construction, ownership, evidence, stale claims, and slice inventory without generic diagrams or ungrounded architecture claims.

Maintain Project Architecture

Maintain the repo-local architecture documentation under docs/architecture/.

This skill is related to explain-code-slice, but it owns the durable architecture files. explain-code-slice explains or records one end-to-end path. This skill keeps the repo-wide product/module map and the slice index coherent.

Inputs

• Required: --project-root <path>
• Required: --run-mode <check-only|apply>
• Optional: --architecture-dir <path>

Workflow

1. Resolve the project root and architecture directory.
2. Detect Swift package products and targets when Package.swift exists:
   • prefer swift package dump-package when it succeeds
   • fall back to conservative Package.swift text scanning
3. Detect Codex plugin repository surfaces when plugin metadata exists:
   • treat .codex-plugin/plugin.json manifests as plugin products
   • treat .agents/plugins/marketplace.json catalogs as marketplace products that expose plugin entries
   • treat skills/*/SKILL.md files and declared .mcp.json files as module targets
   • record only manifest-backed or marketplace-backed relationships
4. Build or refresh docs/architecture/architecture.json with product, target, relationship, evidence, and slice placeholders.
5. In check-only, audit required files, required sections, and stale product or target facts in architecture.json.
6. In apply, create missing architecture files and refresh generated model facts without inventing symbols, data flows, or ownership claims.
7. Leave SLICES.md present even when no provable slices have been recorded yet.
8. Re-run the same audit and report remaining findings.

Required Files

• docs/architecture/ARCHITECTURE.md
• docs/architecture/SLICES.md
• docs/architecture/architecture.json

Writing Expectations

• ARCHITECTURE.md is descriptive. Put preferences, constraints, and "do not" rules in AGENTS.md, not here.
• Use fixed section names so Gale can ask for a specific section without ambiguity.
• Treat Swift Package Manager products and targets as first-class architecture facts when available.
• Treat Codex plugin manifests, plugin marketplaces, skills, and declared MCP configs as first-class architecture facts when available.
• Explain products/modules in terms of what they do, who creates or consumes them, what they own, and what code evidence proves that claim.
• Do not use Mermaid, generic graph diagrams, unlabeled arrows, curved-line diagrams, centered text, or diagram labels that interrupt connector lines.
• Keep visual claims in structured architecture.json until a purpose-built viewer can render them with Gale-readable layout.
• Every generated claim should have evidence: a file path, manifest entry, symbol, command output, or explicit "unverified" marker.

Visual Grammar

Use references/visual-grammar.md when shaping any generated visual model or future viewer output.

Core rules:

• vertical flow dominates
• left/top start position, never center-first reading
• no center-aligned text
• no unlabeled or ambiguous connectors
• connectors must represent one explicit relationship kind such as creates, passes, stores, calls, returns, owns, or depends-on
• data models appear before slice steps
• code nodes must include symbol names and file anchors when known

Slices

SLICES.md is always created. It may remain mostly empty until provable flows are discovered.

When the user asks for a new slice explanation, use explain-code-slice for the walkthrough and update docs/architecture/SLICES.md with the slice if the path is provable from code.

Codex Subagent Fit

When the user explicitly requests subagents, or applicable workflow guidance tells the agent to ask and the user grants explicit permission, use them for read-heavy discovery. Good jobs include scanning package manifests, listing products and targets, finding entrypoints, or tracing one candidate slice. Keep writes to ARCHITECTURE.md, SLICES.md, and architecture.json in the main thread so the architecture story stays coherent.

Output Contract

• Return Markdown plus JSON with:
  • run_context
  • detected_model
  • schema_violations
  • stale_claims
  • fixes_applied
  • post_fix_status
  • errors
• If there are no issues and no errors, output exactly No findings.

Guardrails

• Never auto-commit, auto-push, or open a PR.
• Never invent products, modules, slices, symbols, data models, or code relationships.
• Never edit files outside the architecture directory.
• Never use generic architecture diagrams as filler.
• Treat stale product or target facts as audit failures.

References

• assets/ARCHITECTURE.template.md
• assets/SLICES.template.md
• references/visual-grammar.md
• references/architecture-json.md
• scripts/maintain_project_architecture.py