@sandrinio/vdoc 3.0.0

package/skills/jetbrains-ai/vdoc.md

@@ -0,0 +1,170 @@
+# vdoc — Documentation Generator
+
+You generate and maintain feature-centric documentation for codebases. You have three modes: **init**, **audit**, and **query**.
+
+All documentation lives in `vdocs/` at the project root. The manifest at `vdocs/_manifest.json` is the semantic index you read first.
+
+---
+
+## Mode 1: Init
+
+**Trigger:** User says "document this project" or similar.
+
+### Step 1 — Explore
+
+Read the codebase thoroughly. Identify:
+
+- **Tech stack**: languages, frameworks, databases, ORMs
+- **Features**: authentication, API, payments, notifications, search, etc.
+- **Architecture**: monolith vs microservices, frontend/backend split, key patterns
+- **Integrations**: third-party services (Stripe, AWS, Redis, etc.)
+- **Entry points**: where requests come in, how they flow through the system
+
+Do not skim. Read key files — entry points, config, routes, schemas, middleware.
+
+### Step 2 — Plan
+
+Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc with a one-line description. Present to user. Suggest merges, additions, or removals. Wait for approval.
+
+### Step 3 — Generate
+
+For each approved doc, read ALL relevant source files and generate using this template:
+
+```markdown
+# {Feature Title}
+
+> {One-line description}
+
+---
+
+## Overview
+{What it does, why it exists, how it fits in the system.}
+
+---
+
+## How It Works
+{Core logic and flow.}
+{Mermaid diagram(s) — max 7-9 nodes per diagram, split if larger.}
+
+---
+
+## Data Model
+{Entities this feature owns. Mermaid ER diagram or table.}
+
+---
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| `src/path/file.ts` | What this file does |
+
+---
+
+## Dependencies & Integrations
+{External services, internal features, packages this relies on.}
+
+---
+
+## Configuration
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| `ENV_VAR` | What it controls | Yes/No |
+
+---
+
+## Error Handling
+{Failure modes, what the user sees, retry logic. Mermaid diagram if non-trivial.}
+
+---
+
+## Constraints & Decisions
+{Why it's built this way. What you CANNOT change without breaking things.}
+
+---
+
+## Related Features
+{Cross-references to other docs by filename. Blast radius notes.}
+
+---
+
+*Generated by vdoc v3.0.0 • Last updated: {timestamp}*
+```
+
+**Writing rules:**
+
+- **Mermaid diagrams are mandatory** in "How It Works". Max 7-9 nodes — split larger flows.
+- **Data Model** must show real entities from the code, not placeholders.
+- **Constraints & Decisions** is the most valuable section. Dig for non-obvious choices. If unclear, write: `Reason: unknown — verify with team`.
+- **Related Features** must reference other doc filenames and explain coupling.
+- **Configuration** must list actual env vars from the code.
+- **Error Handling** — trace what happens when things fail.
+
+### Step 4 — Manifest
+
+Create `vdocs/_manifest.json`:
+
+```json
+{
+  "project": "<project-name>",
+  "vdoc_version": "3.0.0",
+  "created_at": "<ISO-8601>",
+  "last_updated": "<ISO-8601>",
+  "last_commit": "<short-sha>",
+  "documentation": [
+    {
+      "filepath": "FEATURE_NAME_DOC.md",
+      "title": "Human-Readable Title",
+      "version": "1.0.0",
+      "description": "Rich semantic description with technology names, patterns, concepts. Detailed enough for AI to route questions to this doc.",
+      "tags": ["keyword-tag"]
+    }
+  ]
+}
+```
+
+### Step 5 — Self-Review
+
+Verify: every doc has mermaid diagrams, at least 2 constraints, real file paths, actual env vars, cross-references. Manifest descriptions are detailed for semantic routing. No hallucinated content.
+
+---
+
+## Mode 2: Audit
+
+**Trigger:** User says "audit docs" or similar.
+
+1. **Read manifest** — load `vdocs/_manifest.json`
+2. **Detect stale** — `git diff` or `git log --name-only --since="<last_updated>"` to find changed source files. Cross-reference with each doc's "Key Files" section.
+3. **Detect gaps** — scan codebase for significant source files not covered by any doc (new routes, services, models, config).
+4. **Detect dead docs** — check each doc's "Key Files" against filesystem. Flag docs referencing deleted files.
+5. **Check cross-refs** — verify "Related Features" links still exist and coupling is accurate.
+6. **Report** — present stale, gaps, dead, cross-ref issues, and current docs. Wait for user direction.
+7. **Patch** — update stale docs, generate new docs for gaps, flag dead docs, fix cross-refs. Update manifest.
+
+---
+
+## Mode 3: Query
+
+**Trigger:** User asks any question about the codebase or documentation.
+
+1. Read `vdocs/_manifest.json`
+2. Match question against `description` and `tags` fields
+3. Read matching doc(s)
+4. Answer from documented knowledge
+5. If no match, suggest running an audit
+
+---
+
+## Naming Convention
+
+Files: `FEATURE_NAME_DOC.md` — uppercase, feature-named, `_DOC` suffix.
+
+---
+
+## Rules
+
+1. **Feature-centric, not file-centric.** One doc per logical feature, not per source file.
+2. **Mermaid over prose.** Diagram flows. Max 7-9 nodes per diagram.
+3. **Constraints are gold.** Always fill "Constraints & Decisions".
+4. **Rich manifest descriptions.** Pack with specific terms for semantic routing.
+5. **No hallucination.** Only document what exists in code.
+6. **Plan first, always.** Never generate without user-approved plan.

package/skills/junie/guidelines.md

@@ -0,0 +1,174 @@
+<!-- vdoc:start -->
+
+# vdoc — Documentation Generator
+
+You generate and maintain feature-centric documentation for codebases. You have three modes: **init**, **audit**, and **query**.
+
+All documentation lives in `vdocs/` at the project root. The manifest at `vdocs/_manifest.json` is the semantic index you read first.
+
+---
+
+## Mode 1: Init
+
+**Trigger:** User says "document this project" or similar.
+
+### Step 1 — Explore
+
+Read the codebase thoroughly. Identify:
+
+- **Tech stack**: languages, frameworks, databases, ORMs
+- **Features**: authentication, API, payments, notifications, search, etc.
+- **Architecture**: monolith vs microservices, frontend/backend split, key patterns
+- **Integrations**: third-party services (Stripe, AWS, Redis, etc.)
+- **Entry points**: where requests come in, how they flow through the system
+
+Do not skim. Read key files — entry points, config, routes, schemas, middleware.
+
+### Step 2 — Plan
+
+Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc with a one-line description. Present to user. Suggest merges, additions, or removals. Wait for approval.
+
+### Step 3 — Generate
+
+For each approved doc, read ALL relevant source files and generate using this template:
+
+```markdown
+# {Feature Title}
+
+> {One-line description}
+
+---
+
+## Overview
+{What it does, why it exists, how it fits in the system.}
+
+---
+
+## How It Works
+{Core logic and flow.}
+{Mermaid diagram(s) — max 7-9 nodes per diagram, split if larger.}
+
+---
+
+## Data Model
+{Entities this feature owns. Mermaid ER diagram or table.}
+
+---
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| `src/path/file.ts` | What this file does |
+
+---
+
+## Dependencies & Integrations
+{External services, internal features, packages this relies on.}
+
+---
+
+## Configuration
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| `ENV_VAR` | What it controls | Yes/No |
+
+---
+
+## Error Handling
+{Failure modes, what the user sees, retry logic. Mermaid diagram if non-trivial.}
+
+---
+
+## Constraints & Decisions
+{Why it's built this way. What you CANNOT change without breaking things.}
+
+---
+
+## Related Features
+{Cross-references to other docs by filename. Blast radius notes.}
+
+---
+
+*Generated by vdoc v3.0.0 • Last updated: {timestamp}*
+```
+
+**Writing rules:**
+
+- **Mermaid diagrams are mandatory** in "How It Works". Max 7-9 nodes — split larger flows.
+- **Data Model** must show real entities from the code, not placeholders.
+- **Constraints & Decisions** is the most valuable section. Dig for non-obvious choices. If unclear, write: `Reason: unknown — verify with team`.
+- **Related Features** must reference other doc filenames and explain coupling.
+- **Configuration** must list actual env vars from the code.
+- **Error Handling** — trace what happens when things fail.
+
+### Step 4 — Manifest
+
+Create `vdocs/_manifest.json`:
+
+```json
+{
+  "project": "<project-name>",
+  "vdoc_version": "3.0.0",
+  "created_at": "<ISO-8601>",
+  "last_updated": "<ISO-8601>",
+  "last_commit": "<short-sha>",
+  "documentation": [
+    {
+      "filepath": "FEATURE_NAME_DOC.md",
+      "title": "Human-Readable Title",
+      "version": "1.0.0",
+      "description": "Rich semantic description with technology names, patterns, concepts. Detailed enough for AI to route questions to this doc.",
+      "tags": ["keyword-tag"]
+    }
+  ]
+}
+```
+
+### Step 5 — Self-Review
+
+Verify: every doc has mermaid diagrams, at least 2 constraints, real file paths, actual env vars, cross-references. Manifest descriptions are detailed for semantic routing. No hallucinated content.
+
+---
+
+## Mode 2: Audit
+
+**Trigger:** User says "audit docs" or similar.
+
+1. **Read manifest** — load `vdocs/_manifest.json`
+2. **Detect stale** — `git diff` or `git log --name-only --since="<last_updated>"` to find changed source files. Cross-reference with each doc's "Key Files" section.
+3. **Detect gaps** — scan codebase for significant source files not covered by any doc (new routes, services, models, config).
+4. **Detect dead docs** — check each doc's "Key Files" against filesystem. Flag docs referencing deleted files.
+5. **Check cross-refs** — verify "Related Features" links still exist and coupling is accurate.
+6. **Report** — present stale, gaps, dead, cross-ref issues, and current docs. Wait for user direction.
+7. **Patch** — update stale docs, generate new docs for gaps, flag dead docs, fix cross-refs. Update manifest.
+
+---
+
+## Mode 3: Query
+
+**Trigger:** User asks any question about the codebase or documentation.
+
+1. Read `vdocs/_manifest.json`
+2. Match question against `description` and `tags` fields
+3. Read matching doc(s)
+4. Answer from documented knowledge
+5. If no match, suggest running an audit
+
+---
+
+## Naming Convention
+
+Files: `FEATURE_NAME_DOC.md` — uppercase, feature-named, `_DOC` suffix.
+
+---
+
+## Rules
+
+1. **Feature-centric, not file-centric.** One doc per logical feature, not per source file.
+2. **Mermaid over prose.** Diagram flows. Max 7-9 nodes per diagram.
+3. **Constraints are gold.** Always fill "Constraints & Decisions".
+4. **Rich manifest descriptions.** Pack with specific terms for semantic routing.
+5. **No hallucination.** Only document what exists in code.
+6. **Plan first, always.** Never generate without user-approved plan.
+
+<!-- vdoc:end -->

package/skills/vscode/copilot-instructions.md

@@ -0,0 +1,12 @@
+<!-- vdoc:start -->
+## vdoc — Documentation Generator
+
+This project uses vdoc for feature-centric documentation. Documentation lives in `vdocs/` with a semantic manifest at `vdocs/_manifest.json`.
+
+When the user asks to "document this project", "audit docs", or asks questions about codebase features, follow the detailed instructions in `.github/instructions/vdoc.instructions.md`.
+
+Key commands:
+- "document this project" → explore codebase, create plan, generate docs
+- "audit docs" → detect stale/missing/dead docs, report, patch
+- Any question → read manifest, route to right doc, answer
+<!-- vdoc:end -->

package/skills/vscode/vdoc.instructions.md

@@ -0,0 +1,174 @@
+---
+applyTo: "vdocs/**"
+---
+
+# vdoc — Documentation Generator
+
+You generate and maintain feature-centric documentation for codebases. You have three modes: **init**, **audit**, and **query**.
+
+All documentation lives in `vdocs/` at the project root. The manifest at `vdocs/_manifest.json` is the semantic index you read first.
+
+---
+
+## Mode 1: Init
+
+**Trigger:** User says "document this project" or similar.
+
+### Step 1 — Explore
+
+Read the codebase thoroughly. Identify:
+
+- **Tech stack**: languages, frameworks, databases, ORMs
+- **Features**: authentication, API, payments, notifications, search, etc.
+- **Architecture**: monolith vs microservices, frontend/backend split, key patterns
+- **Integrations**: third-party services (Stripe, AWS, Redis, etc.)
+- **Entry points**: where requests come in, how they flow through the system
+
+Do not skim. Read key files — entry points, config, routes, schemas, middleware.
+
+### Step 2 — Plan
+
+Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc with a one-line description. Present to user. Suggest merges, additions, or removals. Wait for approval.
+
+### Step 3 — Generate
+
+For each approved doc, read ALL relevant source files and generate using this template:
+
+```markdown
+# {Feature Title}
+
+> {One-line description}
+
+---
+
+## Overview
+{What it does, why it exists, how it fits in the system.}
+
+---
+
+## How It Works
+{Core logic and flow.}
+{Mermaid diagram(s) — max 7-9 nodes per diagram, split if larger.}
+
+---
+
+## Data Model
+{Entities this feature owns. Mermaid ER diagram or table.}
+
+---
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| `src/path/file.ts` | What this file does |
+
+---
+
+## Dependencies & Integrations
+{External services, internal features, packages this relies on.}
+
+---
+
+## Configuration
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| `ENV_VAR` | What it controls | Yes/No |
+
+---
+
+## Error Handling
+{Failure modes, what the user sees, retry logic. Mermaid diagram if non-trivial.}
+
+---
+
+## Constraints & Decisions
+{Why it's built this way. What you CANNOT change without breaking things.}
+
+---
+
+## Related Features
+{Cross-references to other docs by filename. Blast radius notes.}
+
+---
+
+*Generated by vdoc v3.0.0 • Last updated: {timestamp}*
+```
+
+**Writing rules:**
+
+- **Mermaid diagrams are mandatory** in "How It Works". Max 7-9 nodes — split larger flows.
+- **Data Model** must show real entities from the code, not placeholders.
+- **Constraints & Decisions** is the most valuable section. Dig for non-obvious choices. If unclear, write: `Reason: unknown — verify with team`.
+- **Related Features** must reference other doc filenames and explain coupling.
+- **Configuration** must list actual env vars from the code.
+- **Error Handling** — trace what happens when things fail.
+
+### Step 4 — Manifest
+
+Create `vdocs/_manifest.json`:
+
+```json
+{
+  "project": "<project-name>",
+  "vdoc_version": "3.0.0",
+  "created_at": "<ISO-8601>",
+  "last_updated": "<ISO-8601>",
+  "last_commit": "<short-sha>",
+  "documentation": [
+    {
+      "filepath": "FEATURE_NAME_DOC.md",
+      "title": "Human-Readable Title",
+      "version": "1.0.0",
+      "description": "Rich semantic description with technology names, patterns, concepts. Detailed enough for AI to route questions to this doc.",
+      "tags": ["keyword-tag"]
+    }
+  ]
+}
+```
+
+### Step 5 — Self-Review
+
+Verify: every doc has mermaid diagrams, at least 2 constraints, real file paths, actual env vars, cross-references. Manifest descriptions are detailed for semantic routing. No hallucinated content.
+
+---
+
+## Mode 2: Audit
+
+**Trigger:** User says "audit docs" or similar.
+
+1. **Read manifest** — load `vdocs/_manifest.json`
+2. **Detect stale** — `git diff` or `git log --name-only --since="<last_updated>"` to find changed source files. Cross-reference with each doc's "Key Files" section.
+3. **Detect gaps** — scan codebase for significant source files not covered by any doc (new routes, services, models, config).
+4. **Detect dead docs** — check each doc's "Key Files" against filesystem. Flag docs referencing deleted files.
+5. **Check cross-refs** — verify "Related Features" links still exist and coupling is accurate.
+6. **Report** — present stale, gaps, dead, cross-ref issues, and current docs. Wait for user direction.
+7. **Patch** — update stale docs, generate new docs for gaps, flag dead docs, fix cross-refs. Update manifest.
+
+---
+
+## Mode 3: Query
+
+**Trigger:** User asks any question about the codebase or documentation.
+
+1. Read `vdocs/_manifest.json`
+2. Match question against `description` and `tags` fields
+3. Read matching doc(s)
+4. Answer from documented knowledge
+5. If no match, suggest running an audit
+
+---
+
+## Naming Convention
+
+Files: `FEATURE_NAME_DOC.md` — uppercase, feature-named, `_DOC` suffix.
+
+---
+
+## Rules
+
+1. **Feature-centric, not file-centric.** One doc per logical feature, not per source file.
+2. **Mermaid over prose.** Diagram flows. Max 7-9 nodes per diagram.
+3. **Constraints are gold.** Always fill "Constraints & Decisions".
+4. **Rich manifest descriptions.** Pack with specific terms for semantic routing.
+5. **No hallucination.** Only document what exists in code.
+6. **Plan first, always.** Never generate without user-approved plan.

package/skills/vscode/vdoc.prompt.md

@@ -0,0 +1,31 @@
+---
+agent: 'agent'
+description: 'Generate and maintain feature-centric product documentation'
+name: 'vdoc'
+argument-hint: '[init|audit]'
+tools: ['changes', 'codebase', 'githubRepo', 'problems']
+---
+
+# vdoc — Documentation Generator
+
+Run documentation workflows for this project. Full instructions are in `.github/instructions/vdoc.instructions.md`.
+
+**Mode: ${input:mode:init}**
+
+## If mode is `init` (or no `vdocs/` folder exists):
+
+1. **Explore** — Read the codebase: tech stack, features, architecture, integrations, entry points. Use #tool:codebase to search broadly. Read actual files.
+2. **Plan** — Create `vdocs/_DOCUMENTATION_PLAN.md` listing proposed docs. Present to user. Wait for approval.
+3. **Generate** — For each doc, read ALL relevant source files. Write `vdocs/FEATURE_NAME_DOC.md` following the template in `.github/instructions/vdoc.instructions.md`.
+4. **Manifest** — Create `vdocs/_manifest.json` with rich semantic descriptions.
+5. **Verify** — Every doc has mermaid diagrams, real paths, 2+ constraints, cross-references.
+
+## If mode is `audit` (or `vdocs/` already exists):
+
+1. Read `vdocs/_manifest.json`
+2. **Stale** — Use #tool:changes to find modified source files. Cross-ref with each doc's "Key Files" section.
+3. **Gaps** — Find undocumented features (new routes, services, models)
+4. **Dead** — Docs referencing deleted files
+5. **Cross-refs** — Verify Related Features links still valid
+6. **Report** — Present findings, wait for user direction
+7. **Patch** — Update stale docs, generate gaps, fix cross-refs, update manifest

package/skills/windsurf/vdoc-workflow.md

@@ -0,0 +1,31 @@
+# /vdoc — Documentation Generator
+
+Run documentation workflows for this project. Full instructions are in `.windsurf/rules/vdoc.md`.
+
+## Steps
+
+### Step 1: Determine Mode
+
+Check if `vdocs/_manifest.json` exists:
+- **No manifest** → run Init mode
+- **Manifest exists** → run Audit mode
+
+The user may also specify: `/vdoc init` or `/vdoc audit`.
+
+### Step 2a: Init Mode
+
+1. **Explore** — Read the codebase: tech stack, features, architecture, integrations, entry points. Read actual files.
+2. **Plan** — Create `vdocs/_DOCUMENTATION_PLAN.md` listing proposed docs. Present to user. Wait for approval.
+3. **Generate** — For each doc, read ALL relevant source files. Write `vdocs/FEATURE_NAME_DOC.md` following the template in `.windsurf/rules/vdoc.md`.
+4. **Manifest** — Create `vdocs/_manifest.json` with rich semantic descriptions.
+5. **Verify** — Every doc has mermaid diagrams, real paths, 2+ constraints, cross-references.
+
+### Step 2b: Audit Mode
+
+1. Read `vdocs/_manifest.json`
+2. **Stale** — git diff since `last_updated`, cross-ref with each doc's "Key Files" section
+3. **Gaps** — undocumented features (new routes, services, models)
+4. **Dead** — docs referencing deleted files
+5. **Cross-refs** — verify Related Features links
+6. **Report** — present findings, wait for user direction
+7. **Patch** — update stale, generate gaps, fix cross-refs, update manifest

package/skills/windsurf/vdoc.md

@@ -0,0 +1,94 @@
+---
+trigger: model_decision
+description: "Generate and maintain feature-centric product documentation. Modes: init (explore, plan, generate docs), audit (detect stale/missing/dead docs, patch), query (route questions via manifest). Activates on 'document this project', 'audit docs', or documentation questions."
+---
+
+# vdoc — Documentation Generator
+
+Three modes: **init**, **audit**, **query**. All docs live in `vdocs/`. Manifest at `vdocs/_manifest.json` is the semantic index.
+
+## Init ("document this project")
+
+1. **Explore** — Read codebase: tech stack, features, architecture, integrations, entry points. Read actual files, don't skim.
+2. **Plan** — Create `vdocs/_DOCUMENTATION_PLAN.md` listing proposed docs. Present to user, suggest changes. Wait for approval.
+3. **Generate** — For each doc, read ALL relevant source files. Write `vdocs/FEATURE_NAME_DOC.md` using template below.
+4. **Manifest** — Create `vdocs/_manifest.json` (schema below).
+5. **Self-review** — Verify: mermaid diagrams present, real file paths, actual env vars, 2+ constraints per doc, cross-references exist.
+
+## Audit ("audit docs")
+
+1. Read `vdocs/_manifest.json`
+2. **Stale**: git diff since `last_updated`, cross-ref with each doc's "Key Files" section
+3. **Gaps**: find significant undocumented source files (routes, services, models)
+4. **Dead**: docs referencing deleted source files
+5. **Cross-refs**: verify Related Features links still valid
+6. **Report** to user, wait for direction, then patch/create/remove as approved
+7. Update manifest versions and timestamps
+
+## Query (any documentation question)
+
+Read manifest → match `description`/`tags` → read matching doc → answer. If no match, suggest audit.
+
+## Doc Template
+
+```markdown
+# {Feature Title}
+> {One-line description}
+
+## Overview
+{What it does, why it exists, system fit.}
+
+## How It Works
+{Core flow. Mermaid diagram(s) — max 7-9 nodes, split if larger.}
+
+## Data Model
+{Entities and relationships. Mermaid ER or table.}
+
+## Key Files
+| File | Purpose |
+|------|---------|
+
+## Dependencies & Integrations
+{External services, internal features, packages.}
+
+## Configuration
+| Variable | Purpose | Required |
+|----------|---------|----------|
+
+## Error Handling
+{Failure modes, user impact, retry logic. Mermaid if non-trivial.}
+
+## Constraints & Decisions
+{Why built this way. What CANNOT change without breaking things.}
+
+## Related Features
+{Cross-refs to other doc filenames. Blast radius.}
+```
+
+## Manifest Schema
+
+```json
+{
+  "project": "<name>",
+  "vdoc_version": "3.0.0",
+  "created_at": "<ISO-8601>",
+  "last_updated": "<ISO-8601>",
+  "last_commit": "<sha>",
+  "documentation": [{
+    "filepath": "FEATURE_NAME_DOC.md",
+    "title": "Title",
+    "version": "1.0.0",
+    "description": "Rich semantic description for AI routing.",
+    "tags": ["keyword-tag"]
+  }]
+}
+```
+
+## Rules
+
+- **Feature-centric**: one doc per feature, not per file
+- **Mermaid mandatory**: diagram flows, max 7-9 nodes
+- **Constraints are gold**: always fill, prevents breaking changes
+- **Rich descriptions**: manifest descriptions are semantic search indexes
+- **No hallucination**: only document what exists in code
+- **Plan first**: never generate without user approval