Project Docs Diagram

Create architecture, workflow, sequence, state, and data diagrams from repository evidence or a system description. Deliver editable sources and validated exports using Mermaid, PlantUML, draw.io, or Archify, while distinguishing implemented behavior from proposed designs.

中文文档 / Chinese documentation

若当前 Skill 目录下存在 .bundle 且其 ../../ 不是本集合的 Git 检出，先读取 .bundle/skills/project-docs-diagram/GUIDE.md 并以该目录为 Skill 真实目录；其中的共享脚本、资料和其他 Skill 均来自同一快照。通过 npx skills update <已安装的本集合 Skill 名称> 更新此类安装，按实际作用域加 -g 或 -p；不运行快照内依赖 Git 检出的更新命令。

按读者与用途约定选择讲解深度、图例与总览/细节视图；保留用户指定记法、必需标签、关系及证据，不因读者层次删改业务含义。

Produce auditable diagrams from repository evidence. A short request such as “根据代码生成架构图” is sufficient; infer scope, view, engine, and export without requiring a reference image or a detailed prompt. The agent interprets architecture and business meaning; scripts validate source anchors and supported diagram semantics. Keep generated files outside the analyzed repository unless the user asks to commit them. Read the diagram standard when selecting a profile. The draw.io landscape theme and GitHub template decision are documented in the template research.

Archify explainer 是独立的一页文档模式；用户要求项目说明页面时读取 project-docs-overview，不将它作为 typed JSON 图型传入本 Skill 的原生脚本。

Workflow

First distinguish a repository-current-state diagram from a concept/proposal diagram. For “根据代码／当前项目画图”, follow the source workflow below. For “按描述画 Mem0 架构／设计方案图”, use the supplied components and relationships to author a native diagram and follow the native export path below; skip repository context, inventory and source-evidence requirements. Label the deliverable as a concept/proposal based on the user's description, with assumptions separate from supplied facts. Do not claim it describes the current repository. A generic concept architecture defaults to editable draw.io + PNG; honor an explicit engine or notation. Mixed requests verify current-state claims from source and distinguish proposed additions.

1. Resolve this skill's real directory. The CLI is ../../scripts/generate_architecture.py relative to that directory. Run python3 <cli> context --source <repo> --output <workdir>/context.json. For a relevant symbol discovered in the first pass, repeat --focus <qualified-method> to include its CodeGraph callees. Do not create a CodeGraph index on the user's behalf.
2. Inspect the complete context. files, symbols, routes, configKeys, and tables are never capped; scans are candidates to verify. When codeGraph is present, start from its structured classes, routes, and focused calls; use codegraph explore/node to follow relevant paths. A freshness warning means graph data is only a lead: verify against current source. If knowledgeGraph or domainGraph exists, use its IDs/flows as navigation and semantic draft, with the same freshness caveat. Graph calls are code facts, not automatically architecture relationships. For a large context, inspect by module without silently discarding modules.
3. Choose a semantic profile before an engine. A short “项目／模块架构图” request defaults to architecture-landscape; C4, BPMN, UML sequence, and ERD follow their own notation. Write typed IR v2 using the view contract, cite source for every element and relation, and reserve EXTRACTED for labels literal on cited lines. Do not infer infrastructure or future components from examples.
4. For a new landscape overview, run python3 <cli> inventory --source <repo> --output <workdir>/candidates.json (use --scope-prefix only for an explicit module scope). Review every generated candidate and its members against current source and CodeGraph, add source-backed manualCandidates for important relationships the scanner missed, and give each candidate one overview, detail, or reasoned excluded decision. A mapped element or relation must cite every member line of that candidate. Usage candidates require a relation and detail decisions require nearby detail IRs. See the coverage schema. Do not exclude an in-scope dependency merely to reduce density.
5. For a new landscape, run python3 <cli> validate --source <repo> --ir <workdir>/architecture-ir.json --strict-coverage, then python3 <cli> deliver --source <repo> --ir <workdir>/architecture-ir.json --output <workdir>/bundle --format drawio --export-for drawio:png. deliver renders every declared detail before publishing the bundle. coverageCheck: pass is required; declared_only and not_declared are legacy compatibility states. For other profiles use render and the selected official engine. Supported exports remain Mermaid/PlantUML svg|png|pdf, draw.io svg|png|jpg|pdf, and Archify svg|png|jpg|webp|webm|pdf. Unsupported combinations fail rather than silently changing notation. If the selected official renderer is missing, run python3 <repository>/scripts/install_renderers.py --auto --engine <engine> once and retry. This uses the shared Codex/Claude Code renderer setup. An explicit install.sh --no-engines disables this automatic step; report that choice or an installation error instead of silently switching engines or export formats.
6. Inspect drawioQuality before treating a draw.io output as checked: failures stop rendering; partial lists unchecked automatic routes or unsupported geometry. Text measurements are estimates, not actual font layout. Open every exported image and inspect scope, arrow direction, full text, labels, overlap, and unexplained IDs. geometryCheck: pass remains the landscape card-bounds check. The landscape limit is 12 elements and 12 relations per view, so split dense diagrams with traceable candidate decisions. Never shorten required labels or drop relationships just to pass a check.

For all source and native diagrams, allow at most two targeted correction rounds per diagram after the first render. Re-run applicable checks and inspect changed exports after each repair; reuse unchanged reviewed outputs. Two identical failures require changing the approach within that budget (for example widening or splitting the view). At the limit, report the remaining defects and the draft files; do not claim completion or silently weaken checks. Report structural/engine checks separately from actual visualReview: passed|failed|skipped; use skipped with the reason when image viewing is unavailable. Script output visualReview: required is a pending check, never a visual pass.

Official native diagrams outside IR v2

Read the renderer capability audit and the native authoring contract when the user requests another diagram type supported by Mermaid, PlantUML, draw.io, or Archify. For an existing native .mmd, .puml, .drawio, or Archify .json, run python3 ../../scripts/render_native_diagram.py --engine <engine> --input <file> --output <dir> --export png (repeat --export for desired formats). The command runs the actual official engine; Archify 3.2.0 accepts all ten official typed modes: architecture, workflow, sequence, dataflow, lifecycle, erd, tree, class, timeline, and waterfall. Follow the native authoring contract for material-item pointers and timing evidence.

For a new diagram outside IR v2, choose the notation, verify source, author official native syntax, and attach a version 2 evidence manifest when it makes repository claims. Local PlantUML includes are inventoried and packaged. Standard-library or remote includes report claimCoverage: partial; disclose that limitation or use a self-contained source before claiming complete coverage. Review inferred claims and the exported image. claimSemantics: not_proven remains even when anchors and item coverage pass.

The source-line check proves that a cited snippet exists at that location. It does not prove a business interpretation, runtime route, or relationship. Review INFERRED and AMBIGUOUS claims against multiple code paths before presenting them as conclusions.