--- name: create-docs description: Analyze any codebase and generate an Obsidian-ready knowledge vault (AGENTS.md, specs/, per-domain business-logic notes, integrations, rules), language- and framework-agnostic. Discovers every functional domain, extracts its core business logic (calculations, dates, thresholds, states, configuration) with code citations, and verifies each rule against the code. Use when the user asks to create docs, generate documentation, document the project or a domain, build an Obsidian vault from code, or set up AGENTS.md. Use ONLY when the task is about generating project documentation, not for writing app code docs inline. --- # Create Docs Analyze a codebase and create a structured, verified documentation vault for Obsidian that other agents and colleagues query through an Obsidian MCP server. ## Locations The vault and the codebase are separate: - `source=` — the codebase. **Read-only**: never create, edit or delete any file in it (no AGENTS.md, no specs/, no notes). Default: current working directory. - `vault=` — the Obsidian vault, outside the codebase. Every file this skill writes goes here. Required: terminate if missing or if it resolves inside `source`. All paths below (`AGENTS.md`, `specs/…`) are relative to `vault`. All `path:line` citations and `sources` entries are relative to `source`. ## Params This skill needs exactly one of these modes (plus `source` / `vault`): - `new` — create AGENTS.md and the vault structure (inventory first, then domains). - `review` — read and follow directions in `specs-reviewer.md` to review and update the docs. - `domain ` — deep-dive a single domain from the inventory and write/update only its notes. - `continue` — process the next `todo` domains of the inventory (resume after an interruption). Terminate if the user does not provide one of these modes. ## Process 1. **Detect existing docs** — if the vault already has notes, UPDATE in place: preserve content that is still accurate, add missing sections, remove stale references. Do NOT recreate from scratch unless the user explicitly asks for a full regeneration. In an existing vault: - **Generated notes** — notes produced by scripts (declared in the vault's AGENTS.md, marked `GENERATED`, or written by generators in the vault's tools folder) are never hand-edited: a regeneration would overwrite the change. Link to them instead. - **Existing AGENTS.md** — keep its audience, language and structure; only add entries pointing to new notes. - **Existing conventions** — follow the vault's link style, folder layout and note naming; do not convert existing notes to a different format. 2. **Scan the codebase** — directory structure, project/build manifests of any ecosystem (package.json, *.csproj/*.vbproj/*.sln, pom.xml, go.mod, composer.json, Cargo.toml, …), config files, entry points, source and test directories, CI/CD configs, database scripts. 3. **Identify** — tech stack, architecture pattern, entry points, UI/API/job surfaces, persistence, lint/format config, build scripts, deploy targets, external integrations, trust boundaries. 4. **Inventory domains** — build `specs/domains/domain-inventory.md` (see **Domain discovery**) before writing any domain note. 5. **Deep-dive domains** — process inventory domains one at a time (see **Domain deep-dive**). Never document all domains in a single shallow pass; depth per domain beats breadth. 6. **Verify** — every domain note passes **Verification** before its status becomes `verified`. 7. **Link** — update MOC notes and cross-links (see **Obsidian format**). 8. **Do NOT invent anything** — base everything exclusively on existing code. 9. **Language** — all documentation in English; domain terms found in the UI or data keep their original wording (quoted) and go into `aliases`. ## 1. `AGENTS.md` in the vault root Entry file for agents querying the vault. If it already exists, see Process step 1. A new one contains: - **Project Overview** — project name and 1-2 line description - **Tech Stack** — technologies used (framework, languages, main libraries) - **Architecture** — folder structure, entry points, main architectural pattern - **Commands** — dev, build, test, deploy, lint commands (most used, inline) - **Code Style** — preferred syntax, naming convention, formatting - **Coding Rules** — critical conventions the agent must respect (max 5-8 bullets, only non-obvious things) - **Design System** — tokens, UI libraries, component patterns (only if a frontend exists) - **Constraints / What to avoid** — things the agent must never do in this project - **Workflow** — operational order (e.g. typecheck after changes, single tests not full suite) - Self-maintenance rule: > "When the codebase changes, run `create-docs review` to re-verify the affected notes" - **References** — list of `specs/` notes with a brief description of each **AGENTS.md must be short and scannable** — for every line ask: "if I remove this, would the agent make mistakes?" — if no, cut it. ## 2. Domain discovery A **domain** is a functional subsystem with its own data and non-obvious business rules (e.g. billing, scheduling, training compliance, inventory). Utilities, type-only modules and thin wrappers are NOT domains. Combine these language-agnostic signals to find domains: | Signal | Where to look | |---|---| | Functional folder / module / namespace names | directory tree, project files | | Persistent entities | tables, ORM models, migrations, SQL scripts, stored procedures | | User-facing surfaces | menus, forms/screens, routes, API groups, reports | | Configuration | option/setting keys, feature flags, per-tenant or per-customer switches | | Scheduled / batch work | jobs, recalculation routines, imports/exports | | Vocabulary | recurring domain terms in identifiers, UI labels, resource/translation files | Write `specs/domains/domain-inventory.md` with one row per domain: | Domain | Paths | Entities | Surfaces | Tier | Status | Note | - **Tier** — 1 heavily customized core logic / 2 business logic with boilerplate / 3 standard framework usage / 4 thin or generated / 5 reference-only. When uncertain, default to Tier 2. - **Status** — `todo` → `draft` → `verified` (or `blocked: `). - Order rows by Tier, then by size. Deep-dive Tier 1 and 2; Tier 3-5 get only the inventory summary. ## 3. Domain deep-dive For each domain, in order: 1. **Locate** — search (`rg`) the domain keywords, including localized UI labels, in code, constants, option keys, resources and SQL. 2. **Find logic hotspots** — code that decides or computes something: - date arithmetic, deadlines, validity periods, cut-off dates - thresholds, percentages, quantities, scoring - status assignment and state transitions - validations and eligibility/exemption rules - branching on configuration, feature flags, tenant/customer codes - SQL/queries that compute values (including SQL built in strings) Rank hotspots by number of branches, hard-coded constants and inbound references; read the top ones first. 3. **Trace** — follow each flow end-to-end: surface (UI/API/job) → configuration read → computation → persistence. Read only the relevant blocks of large files. 4. **Active code only** — ignore commented-out code and unreachable branches. Comments may explain active code, but never document a rule found only in commented-out code. 5. **Extract** — write each computation as numbered steps: inputs → conditions/thresholds → output. 6. **Cite** — every business rule ends with its source as `path:line` (repo-relative). 7. **Behavior, not norm** — describe what the code does, not what laws, standards or specs say it should do. If they appear to differ, record it under **Inconsistencies**; never "fix" it in the doc. ### Domain note: `specs/domains/.md` Main note of the domain (hub). If it grows beyond ~300 lines, split topics into `specs/domains/ - .md` and link them from the hub. Link existing notes (flows, schema, UI, imports) instead of repeating their content. - **Summary** — 2-3 lines in plain language: what the domain does, for whom. Must make sense on its own. - **Data model** — entities with key fields, types, notes (tables) - **Business rules** — numbered with stable IDs (`-R01`, `-R02`, …). Each rule: one plain sentence + steps if it is a computation + source. These are contracts the code respects, not code patterns. - **Configuration** — `Option key | Constant | Effect | Default | Default per tenant/customer | Location`. Record the default where the computation reads it, and also where the UI shows it, if different. - **Dates & thresholds** — every hard-coded date, duration, percentage, limit: value, meaning, location. - **States** — status codes, meaning, condition that sets them. - **Flows** — numbered end-to-end flows (surface → computation → persistence). - **Inconsistencies** — mismatches found (UI default ≠ computation default, boundary dates off by one day, same rule implemented differently in two places). Facts with locations only; never resolve them silently. - **Related** — wikilinks to other domains, integrations and rules notes. Create a domain note ONLY for domains whose rules are non-obvious from reading the code. ## 4. `specs/integrations/` — external system boundaries For every integration with an external system (HTTP, DB, IPC, filesystem, third-party import/export, message queue, AI/OCR services, etc.): - `integrations.md` — MOC table: name, direction (IN/OUT/BIDIRECTIONAL), protocol, implementing files, link - One note per integration: - **Implementing files** — table: file → key symbols - **Flow** — numbered steps end-to-end - **Trust boundaries** — `Boundary | Mechanism | Location`. Most important section: what NOT to relax and WHERE the guard lives. - **Config** — timeouts, pool sizes, client settings (never secrets: names of settings only) Create this folder ONLY if the project has at least one integration with a trust boundary. ## 5. `specs/rules/` — patterns and recipes Recurring programming patterns go as rule notes in `specs/rules/` (e.g. `add-option.md`, `error-handling.md`). Each answers "how do I add/change X?" with numbered steps and a minimal code snippet — a recipe, not a description. ## 6. Other `specs/` notes (only the needed ones) - `file-structure.md` — map of main directories and files - `commands.md` — extended commands - `conventions-backend.md`, `conventions-frontend.md`, `conventions-database.md` - `api-routes.md` — interface table adapted to the real interface type (HTTP, IPC, CLI, events, forms) - `glossary.md` — domain terms (original wording) → meaning → domain note link - `module-index.md` — `Module | Path | Tier | Summary | Note` ## 7. Obsidian format Every note this skill creates (and every hand-written note it updates, except generated notes): - Starts with YAML frontmatter (first line of the file): ```yaml --- read_when: "" type: domain | integration | rule | convention | index | glossary domain: tier: 1 status: draft | verified aliases: ["", ""] tags: [domain/, type/] sources: ["path/to/file.ext", "path/to/other.ext"] verified_date: --- ``` - Has a **globally unique file name** for new notes (Obsidian resolves wikilinks by name): never `spec.md` or `index.md` repeated across folders. - Links other notes in the vault's existing style: relative Markdown links `[text](../path/note.md#heading)` if the vault already uses them, otherwise wikilinks `[[note name#Heading]]`. Both work in Obsidian. Rules are linked by heading or block id (`^domain-r01`). - Uses plain Markdown tables, no embedded images for information, no content only in callouts. - Is self-contained: the first paragraph answers "what is this" without opening other notes, because MCP clients often retrieve a single note. MOC (map of content) notes: - `specs/home.md` — entry point: project summary + links to every MOC - `specs/domains/domain-inventory.md` — doubles as the domains MOC - `specs/integrations/integrations.md`, `specs/rules/rules.md` ## 8. Verification After drafting a domain note, verify it with a separate subagent that did not write it: 1. For each rule, open the cited `path:line` and confirm the code does exactly what the rule states (conditions, boundary operators `<` vs `<=`, dates, defaults, units). 2. Confirm the cited code is active (not commented out, reachable). 3. Mark failing rules: fix them, or move them under **Inconsistencies** with the reason. 4. When every rule passes, set `status: verified`, `verified_date` (today), and update the inventory row. Base verification only on the files present in `source`: no version-control commands. Never mark a note `verified` without running this pass. ## General rules - English only (original domain terms quoted, see Process step 9) - Document only what is not obvious from reading the code (business rules, implicit conventions, architectural decisions, gotchas, trust boundaries, invariants) - Be concise: every note is a reference, not a tutorial - Use markdown tables where possible - Do NOT invent anything — base everything exclusively on existing code - Never copy secrets, credentials, connection strings or personal data into the vault - **Separation of concerns between notes:** - `conventions-*.md` → HOW to write code (style, naming, patterns) - `rules/*.md` → HOW to add/change a feature (recipe with steps + snippet) - `domains/.md` → WHAT the code guarantees (business rules, data model, configuration, states) - `integrations/*.md` → WHERE the trust boundaries are - `module-index.md` / `domain-inventory.md` → WHICH modules/domains exist and how critical they are - **No duplication:** if a rule already lives in one note, link to it with a wikilink instead of repeating it. - **Cross-link aggressively:** an agent or colleague navigating one note must discover the next relevant one without guessing.