Parfii-bot 0be354a920 KeiSeiKit-public — clean state

Single-commit clean baseline after security scrub of niche-tells,
project codenames, internal jargon, and contributor-email leaks.

Contents:
- 100 Rust crates (_primitives/_rust/)
- 37 agent manifests (_manifests/) + generated specs (_generated/)
- 67 user-invocable skills (skills/)
- 33 hooks (hooks/)
- Composition blocks (_blocks/)
- Documentation (docs/, README.md)
- TS adapter packages (_ts_packages/)
- Assembler (_assembler/)
- Roles (_roles/)
- Templates (_templates/)
- Forgejo CI (.forgejo/)

Author: Denis Parfionovich <info@greendragon.info>

License: see LICENSE.

2026-05-01 12:09:03 +08:00

2.4 KiB

Raw Blame History

DOCS — Architecture diagrams (Mermaid)

Diagrams live beside the prose they describe. Mermaid renders natively on GitHub / Forgejo / Gitea / Obsidian — no extra tooling needed to view.

When to include

Any agent/skill that scaffolds documentation for a multi-component system
Any repo with ≥ 3 services / layers / subsystems

Four diagram patterns (use the right one)

1. System context (C4 level 1) — `flowchart LR`

flowchart LR
    U[User] -->|HTTP| API[API Gateway]
    API -->|gRPC| SVC[Service]
    SVC -->|SQL| DB[(PostgreSQL)]
    SVC -->|publish| Q[[Queue]]

Use for: one-page overview, onboarding, README architecture section.

2. Sequence — `sequenceDiagram`

sequenceDiagram
    Client->>API: POST /orders
    API->>DB: INSERT
    DB-->>API: id
    API-->>Client: 201 Created

Use for: request flow, auth handshake, error recovery sequence.

3. State machine — `stateDiagram-v2`

stateDiagram-v2
    [*] --> Pending
    Pending --> Running: start
    Running --> Done: success
    Running --> Failed: error
    Failed --> Pending: retry

Use for: job lifecycle, FSM-driven features, connection state.

4. ER / data model — `erDiagram`

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains

Use for: DB schema summary. Keep ≤ 10 entities per diagram.

Rules

Diagram-as-code, no binary exports. .mmd or fenced block, never .png
≤ 15 nodes / 20 edges per diagram. Over that → split
Labels are nouns. Edges are verbs. No prose inside nodes
One diagram = one concern. Don't mix system context + sequence in one chart
Preview locally with mmdc before commit: mmdc -i diagram.mmd -o /tmp/preview.svg
Link to source in caption — "See docs/diagrams/orders.mmd for source"

Forbidden

ASCII art for multi-node graphs (use Mermaid — renders everywhere)
Diagrams that contradict the code (stale → delete or fix)
Secrets / real hostnames / IPs in diagrams (use placeholders)

Install `mmdc` (preview tool)

npm install -g @mermaid-js/mermaid-cli    # one-time
mmdc -i docs/diagrams/context.mmd -o /tmp/preview.svg

References

Mermaid syntax — https://mermaid.js.org/intro/ [VERIFIED: https://mermaid.js.org/intro/]
C4 model — https://c4model.com/ [VERIFIED: https://c4model.com/]
~/.claude/rules/doc-conventions.md

2.4 KiB Raw Blame History