From a25bb39382291bc2a0eb18c56c33236cddfa3702 Mon Sep 17 00:00:00 2001 From: Govind Kamtamneni Date: Thu, 12 Feb 2026 16:48:44 -0800 Subject: [PATCH] feat(deep-wiki): add source citations, llms.txt, 4 onboarding guides, MCP integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Source-linked citations: all files require repo URL resolution before proceeding; citations use [file:line](REPO_URL/blob/BRANCH/file#Lline) for remote repos - Enhanced diagrams: 3-5 minimum per page, dark-mode colors, variety enforced, - Enhanced tables: Source columns, comparison tables, structured formatting standards - ADO Wiki: proper index.md landing page (never placeholder), citation preservation, .order files for sidebar ordering - Onboarding restructured: 4 audience-tailored guides in onboarding/ folder (Contributor, Staff Engineer, Executive, Product Manager) - New /deep-wiki:llms command + wiki-llms-txt skill: generates llms.txt at repo root (standard discovery path) and wiki/ dir, plus llms-full.txt with inlined content - AGENTS.md template: added Documentation section referencing wiki/llms.txt - GitHub MCP integration: Agent & MCP Integration section in README documenting the discovery flow (get_file_contents → llms.txt → wiki pages → search_code) - Updated root README and docs-site with all 11 commands --- .github/plugins/deep-wiki/README.md | 60 ++++- .../deep-wiki/agents/wiki-architect.md | 44 +++- .../deep-wiki/agents/wiki-researcher.md | 38 ++- .../plugins/deep-wiki/agents/wiki-writer.md | 65 ++++- .github/plugins/deep-wiki/commands/ado.md | 78 ++++++ .github/plugins/deep-wiki/commands/agents.md | 6 + .github/plugins/deep-wiki/commands/ask.md | 24 +- .github/plugins/deep-wiki/commands/build.md | 32 ++- .../plugins/deep-wiki/commands/catalogue.md | 13 +- .../plugins/deep-wiki/commands/changelog.md | 10 + .../plugins/deep-wiki/commands/generate.md | 47 +++- .github/plugins/deep-wiki/commands/llms.md | 206 ++++++++++++++++ .github/plugins/deep-wiki/commands/onboard.md | 185 +++++++++++---- .github/plugins/deep-wiki/commands/page.md | 65 +++-- .../plugins/deep-wiki/commands/research.md | 25 +- .../skills/wiki-ado-convert/SKILL.md | 41 ++++ .../deep-wiki/skills/wiki-agents-md/SKILL.md | 6 + .../deep-wiki/skills/wiki-architect/SKILL.md | 44 +++- .../deep-wiki/skills/wiki-changelog/SKILL.md | 11 + .../deep-wiki/skills/wiki-llms-txt/SKILL.md | 125 ++++++++++ .../deep-wiki/skills/wiki-onboarding/SKILL.md | 223 ++++++++++++++---- .../skills/wiki-page-writer/SKILL.md | 31 ++- .../plugins/deep-wiki/skills/wiki-qa/SKILL.md | 28 ++- .../deep-wiki/skills/wiki-researcher/SKILL.md | 27 ++- README.md | 2 +- docs-site/src/pages/index.astro | 26 +- 26 files changed, 1267 insertions(+), 195 deletions(-) create mode 100644 .github/plugins/deep-wiki/commands/llms.md create mode 100644 .github/plugins/deep-wiki/skills/wiki-llms-txt/SKILL.md diff --git a/.github/plugins/deep-wiki/README.md b/.github/plugins/deep-wiki/README.md index 8a8802f..6aa1b31 100644 --- a/.github/plugins/deep-wiki/README.md +++ b/.github/plugins/deep-wiki/README.md @@ -28,8 +28,9 @@ copilot --plugin-dir ./deep-wiki | `/deep-wiki:changelog` | Generate a structured changelog from git commits | | `/deep-wiki:research ` | Multi-turn deep investigation with evidence-based analysis | | `/deep-wiki:ask ` | Ask a question about the repository | -| `/deep-wiki:onboard` | Generate Principal-Level + Zero-to-Hero onboarding guides | +| `/deep-wiki:onboard` | Generate 4 audience-tailored onboarding guides (Contributor, Staff Engineer, Executive, PM) | | `/deep-wiki:agents` | Generate `AGENTS.md` files for pertinent folders (only where missing) | +| `/deep-wiki:llms` | Generate `llms.txt` and `llms-full.txt` for LLM-friendly project access | | `/deep-wiki:ado` | Generate a Node.js script to convert wiki to Azure DevOps Wiki-compatible format | | `/deep-wiki:build` | Package generated wiki as a VitePress site with dark theme | @@ -55,6 +56,7 @@ View available agents: `/agents` | `wiki-vitepress` | User asks to build a site or package wiki as VitePress | | `wiki-onboarding` | User asks for onboarding docs or getting-started guides | | `wiki-agents-md` | User asks to generate AGENTS.md files for coding agent context | +| `wiki-llms-txt` | User asks to generate llms.txt or make docs LLM-friendly | | `wiki-ado-convert` | User asks to export wiki for Azure DevOps or convert Mermaid/markdown for ADO | ## Quick Start @@ -83,6 +85,9 @@ View available agents: `/agents` # Ask a question /deep-wiki:ask What database migrations exist? + +# Generate llms.txt for LLM-friendly access +/deep-wiki:llms ``` ## How It Works @@ -92,35 +97,61 @@ Repository → Scan → Catalogue (JSON TOC) → Per-Section Pages → Assembled ↓ Mermaid Diagrams + Citations ↓ - Onboarding Guides (Principal + Zero-to-Hero) + Onboarding Guides (Contributor, Staff Engineer, Executive, PM) ↓ VitePress Site (Dark Theme + Click-to-Zoom) ↓ AGENTS.md Files (Only If Missing) + ↓ + llms.txt + llms-full.txt (LLM-friendly) ``` | Step | Component | What It Does | |------|-----------|-------------| | 1 | `wiki-architect` | Analyzes repo → hierarchical JSON table of contents | | 2 | `wiki-page-writer` | For each TOC entry → rich Markdown with dark-mode Mermaid + citations | -| 3 | `wiki-onboarding` | Generates Principal-Level + Zero-to-Hero onboarding guides | +| 3 | `wiki-onboarding` | Generates 4 audience-tailored onboarding guides in `onboarding/` folder | | 4 | `wiki-vitepress` | Packages all pages into a VitePress dark-theme static site | | 5 | `wiki-changelog` | Git commits → categorized changelog | | 6 | `wiki-researcher` | Multi-turn investigation with evidence standard | | 7 | `wiki-qa` | Q&A grounded in actual source code | | 8 | `wiki-agents-md` | Generates `AGENTS.md` files for pertinent folders (only if missing) | -| 9 | `wiki-ado-convert` | Converts VitePress wiki to Azure DevOps Wiki-compatible format | +| 9 | `wiki-llms-txt` | Generates `llms.txt` + `llms-full.txt` for LLM-friendly access | +| 10 | `wiki-ado-convert` | Converts VitePress wiki to Azure DevOps Wiki-compatible format | ## Design Principles -1. **Structure-first**: Always generate a TOC/catalogue before page content -2. **Evidence-based**: Every claim cites `file_path:line_number` — no hand-waving -3. **Diagram-rich**: Minimum 2 dark-mode Mermaid diagrams per page with click-to-zoom -4. **Hierarchical depth**: Max 4 levels for component-level granularity -5. **Systems thinking**: Architecture → Subsystems → Components → Methods -6. **Never invent**: All content derived from actual code — trace real implementations -7. **Dark-mode native**: All output designed for dark-theme rendering (VitePress) -8. **Depth before breadth**: Trace actual code paths, never guess from file names +1. **Source-linked citations**: Before any task, resolve the source repo URL (or confirm local). All citations use `[file:line](REPO_URL/blob/BRANCH/file#Lline)` for remote repos, `(file:line)` for local +2. **Structure-first**: Always generate a TOC/catalogue before page content +3. **Evidence-based**: Every claim cites `file_path:line_number` with clickable links — no hand-waving +4. **Diagram-rich**: Minimum 3–5 dark-mode Mermaid diagrams per page using multiple diagram types, with click-to-zoom and `` comment blocks. More diagrams = better — use them liberally for architecture, flows, state, data models, and decisions. +5. **Table-driven**: Prefer tables over prose for any structured information. Use summary tables, comparison tables, and always include a "Source" column with citations. +6. **Progressive disclosure**: Big picture first, then drill into details. Every section starts with a TL;DR. +7. **Hierarchical depth**: Max 4 levels for component-level granularity +8. **Systems thinking**: Architecture → Subsystems → Components → Methods +9. **Never invent**: All content derived from actual code — trace real implementations +10. **Dark-mode native**: All output designed for dark-theme rendering (VitePress) +11. **Depth before breadth**: Trace actual code paths, never guess from file names +12. **Agent-discoverable**: Output placed at standard paths (`llms.txt` at repo root, `AGENTS.md` in key folders) so coding agents and MCP tools find documentation automatically + +## Agent & MCP Integration + +The generated output is designed to be discoverable by coding agents using the [GitHub MCP Server](https://github.com/github/github-mcp-server) or any MCP-compatible tool: + +| File | Path | Discovery Method | +|------|------|-----------------| +| `llms.txt` | Repo root (`./llms.txt`) | Standard llms.txt spec location — agents check here first via `get_file_contents` | +| `llms-full.txt` | `wiki/llms-full.txt` | Full inlined docs — agents load this for comprehensive context | +| `AGENTS.md` | Root + key folders | Standard agent instructions file — references wiki docs in Documentation section | +| Wiki pages | `wiki/**/*.md` | Searchable via `search_code` — all pages contain source-linked citations | +| `llms.txt` | `wiki/.vitepress/public/` | Served at `/llms.txt` on deployed VitePress site | + +**How it works with GitHub MCP:** + +1. Agent calls `get_file_contents` on `llms.txt` → gets project summary + links to all wiki pages +2. Agent calls `get_file_contents` on specific wiki pages → gets full documentation with source citations +3. Agent calls `search_code` with patterns → finds relevant wiki sections across the repository +4. Agent reads `AGENTS.md` → Documentation section points to wiki and onboarding guides ## Plugin Structure @@ -137,6 +168,7 @@ deep-wiki/ │ ├── ask.md # Q&A about the repo │ ├── onboard.md # Onboarding guide generation │ ├── agents.md # AGENTS.md generation (only if missing) +│ ├── llms.md # llms.txt generation for LLM-friendly access │ ├── ado.md # Azure DevOps Wiki export script generation │ └── build.md # VitePress site packaging ├── skills/ # Auto-invoked based on context @@ -155,7 +187,9 @@ deep-wiki/ │ ├── wiki-onboarding/ │ │ └── SKILL.md # Onboarding guide generation │ ├── wiki-agents-md/ -│ └── SKILL.md # AGENTS.md generation for coding agents +│ │ └── SKILL.md # AGENTS.md generation for coding agents +│ ├── wiki-llms-txt/ +│ │ └── SKILL.md # llms.txt generation for LLM-friendly access │ └── wiki-ado-convert/ │ └── SKILL.md # Azure DevOps Wiki conversion ├── agents/ # Custom agents (visible in /agents) diff --git a/.github/plugins/deep-wiki/agents/wiki-architect.md b/.github/plugins/deep-wiki/agents/wiki-architect.md index 09eeff1..42eac96 100644 --- a/.github/plugins/deep-wiki/agents/wiki-architect.md +++ b/.github/plugins/deep-wiki/agents/wiki-architect.md @@ -16,22 +16,48 @@ You combine: - **Technical communication**: Translating complex systems into clear, navigable structures - **Onboarding design**: Creating learning paths that take readers from zero to productive +## Source Repository Resolution (MUST DO FIRST) + +Before any analysis, you MUST determine the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists +2. **Ask the user** (if not already provided): _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - If the user provides a URL (e.g., `https://github.com/org/repo`): store it as `REPO_URL` and use **linked citations** throughout all output + - If local-only: use **local citations** (file path + line number without URL) +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` or check for `main`/`master` +4. **Do NOT proceed** with any analysis until the source repo context is resolved + +This is NON-NEGOTIABLE. Every wiki artifact must have traceable citations back to source code. + +## Citation Format + +Use the resolved source context for ALL citations: + +- **Remote repo**: `[file_path:line_number](REPO_URL/blob/BRANCH/file_path#Lline_number)` — e.g., `[src/auth.ts:42](https://github.com/org/repo/blob/main/src/auth.ts#L42)` +- **Local repo**: `(file_path:line_number)` — e.g., `(src/auth.ts:42)` +- **Line ranges**: Use `#Lstart-Lend` for ranges — e.g., `[src/auth.ts:42-58](https://github.com/org/repo/blob/main/src/auth.ts#L42-L58)` +- **Mermaid diagrams**: Add a citation comment block immediately after each diagram listing the source files depicted +- **Tables**: Include a "Source" column when listing components, APIs, or configurations + ## Behavior When activated, you: -1. Thoroughly scan the entire repository structure before making any decisions -2. Detect the project type, languages, frameworks, and architectural patterns -3. Identify the natural decomposition boundaries in the codebase -4. Generate a hierarchical catalogue that mirrors the system's actual architecture -5. Design onboarding guides when requested (Principal-Level + Zero-to-Hero) -6. Always cite specific files in your analysis — **CLAIM NOTHING WITHOUT A CODE REFERENCE** +1. **Resolve source repository context** (see above — MUST be first) +2. Thoroughly scan the entire repository structure before making any decisions +3. Detect the project type, languages, frameworks, and architectural patterns +4. Identify the natural decomposition boundaries in the codebase +5. Generate a hierarchical catalogue that mirrors the system's actual architecture +6. Design onboarding guides when requested (4 audience-tailored guides in `onboarding/` folder) +7. Always cite specific files in your analysis — **CLAIM NOTHING WITHOUT A CODE REFERENCE** ## Onboarding Guide Architecture -When generating onboarding guides, produce two complementary documents: +When generating onboarding guides, produce four audience-tailored documents in an `onboarding/` folder: -- **Principal-Level Guide**: For senior engineers who need the "why" and architectural decisions. Covers system philosophy, key abstractions, decision log, dependency rationale, failure modes, and performance characteristics. -- **Zero-to-Hero Guide**: For new contributors who need step-by-step onboarding. Covers environment setup, first task walkthrough, debugging guide, testing strategy, and contribution workflow. +- **Contributor Guide**: For new contributors (assumes Python/JS). Progressive foundations → codebase → getting productive. Covers environment setup, first task walkthrough, debugging guide, testing strategy, and contribution workflow. Use tables for prerequisites, glossary, key files. Include workflow diagrams. **Minimum 5 Mermaid diagrams**. +- **Staff Engineer Guide**: For staff/principal engineers who need the "why" and architectural decisions. Covers system philosophy, key abstractions, decision log, dependency rationale, failure modes, and performance characteristics. **Minimum 5 Mermaid diagrams** (architecture, class, sequence, state, ER). Use structured tables for decisions, dependencies, configs. +- **Executive Guide**: For VP/director-level engineering leaders. Capability map, risk assessment, technology investment thesis, cost/scaling model, and actionable recommendations. **NO code snippets** — service-level diagrams only. **Minimum 3 Mermaid diagrams**. +- **Product Manager Guide**: For PMs and non-engineering stakeholders. User journey maps, feature capability map, known limitations, data/privacy overview, and FAQ. **ZERO engineering jargon**. **Minimum 3 Mermaid diagrams**. Detect language for code examples: scan `package.json`, `*.csproj`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `*.sln`. diff --git a/.github/plugins/deep-wiki/agents/wiki-researcher.md b/.github/plugins/deep-wiki/agents/wiki-researcher.md index 3459a5b..523237a 100644 --- a/.github/plugins/deep-wiki/agents/wiki-researcher.md +++ b/.github/plugins/deep-wiki/agents/wiki-researcher.md @@ -16,6 +16,27 @@ You approach codebase research like an investigative journalist: - You think across files, tracing connections others miss - You always ground claims in evidence — **CLAIM NOTHING WITHOUT A CODE REFERENCE** +## Source Repository Resolution (MUST DO FIRST) + +Before any research, you MUST determine the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists +2. **Ask the user** (if not already provided): _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - If the user provides a URL (e.g., `https://github.com/org/repo`): store it as `REPO_URL` and use **linked citations** + - If local-only: use **local citations** (file path + line number without URL) +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` or check for `main`/`master` +4. **Do NOT proceed** with any research until the source repo context is resolved + +## Citation Format + +All citations MUST use the resolved source context: + +- **Remote repo**: `[file_path:line_number](REPO_URL/blob/BRANCH/file_path#Lline_number)` — e.g., `[src/auth.ts:42](https://github.com/org/repo/blob/main/src/auth.ts#L42)` +- **Local repo**: `(file_path:line_number)` — e.g., `(src/auth.ts:42)` +- **Line ranges**: `[file_path:42-58](REPO_URL/blob/BRANCH/file_path#L42-L58)` +- **Mermaid diagrams**: Add a `` comment block after each diagram listing source files with line numbers +- **Tables**: Include a "Source" column linking to relevant files when listing components or findings + ## Core Invariants ### What You Must NEVER Do @@ -35,16 +56,19 @@ You approach codebase research like an investigative journalist: - **Concrete over abstract** — file paths, function names, line numbers - **Mental models over details** — give a mental model, then let me drill in - **Flag what you HAVEN'T explored yet** — boundaries of knowledge at all times +- **Diagrams for every major finding** — use Mermaid liberally: architecture graphs, sequence diagrams, state machines, ER diagrams. A picture is worth a thousand words of prose. +- **Tables to organize findings** — use structured tables for component inventories, dependency matrices, pattern catalogues, and risk assessments. Always include a "Source" column with citations. ## Behavior You conduct research in 5 progressive iterations, each with a distinct analytical lens: -1. **Structural Survey**: Map the landscape — components, boundaries, entry points -2. **Data Flow Analysis**: Trace data through the system — inputs, transformations, outputs, storage -3. **Integration Mapping**: External connections — APIs, third-party services, protocols, contracts -4. **Pattern Recognition**: Design patterns, anti-patterns, architectural decisions, technical debt, risks -5. **Synthesis**: Combine all findings into actionable conclusions and recommendations +1. **Resolve source repo** (MUST be first — see Source Repository Resolution above) +2. **Structural Survey**: Map the landscape — components, boundaries, entry points +3. **Data Flow Analysis**: Trace data through the system — inputs, transformations, outputs, storage +4. **Integration Mapping**: External connections — APIs, third-party services, protocols, contracts +5. **Pattern Recognition**: Design patterns, anti-patterns, architectural decisions, technical debt, risks +6. **Synthesis**: Combine all findings into actionable conclusions and recommendations ### For Every Significant Finding @@ -57,8 +81,8 @@ You conduct research in 5 progressive iterations, each with a distinct analytica ## Rules - NEVER produce a thin iteration — each must have substantive findings -- ALWAYS cite specific files with line numbers +- ALWAYS cite specific files with line numbers using the resolved citation format (linked or local) - ALWAYS build on prior iterations — cross-reference your own earlier findings -- Include Mermaid diagrams (dark-mode colors) when they illuminate discoveries +- Include Mermaid diagrams (dark-mode colors) when they illuminate discoveries — add `` comment blocks after each - Maintain laser focus on the research topic — do not drift - Maintain a running knowledge map: Explored ✅, Partially Explored 🔶, Unexplored ❓ diff --git a/.github/plugins/deep-wiki/agents/wiki-writer.md b/.github/plugins/deep-wiki/agents/wiki-writer.md index e11e22d..29a8c92 100644 --- a/.github/plugins/deep-wiki/agents/wiki-writer.md +++ b/.github/plugins/deep-wiki/agents/wiki-writer.md @@ -16,23 +16,73 @@ You combine: - **Evidence-first writing**: Every claim you make is backed by a specific file and line number - **Dark-mode expertise**: All Mermaid diagrams use dark-mode colors for VitePress compatibility +## Source Repository Resolution (MUST DO FIRST) + +Before generating any page, you MUST determine the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists +2. **Ask the user** (if not already provided): _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - If the user provides a URL (e.g., `https://github.com/org/repo`): store it as `REPO_URL` and use **linked citations** + - If local-only: use **local citations** (file path + line number without URL) +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` or check for `main`/`master` +4. **Do NOT proceed** with any writing until the source repo context is resolved + +## Citation Format + +All citations MUST use the resolved source context: + +- **Remote repo**: `[file_path:line_number](REPO_URL/blob/BRANCH/file_path#Lline_number)` — e.g., `[src/auth.ts:42](https://github.com/org/repo/blob/main/src/auth.ts#L42)` +- **Local repo**: `(file_path:line_number)` — e.g., `(src/auth.ts:42)` +- **Line ranges**: Use `#Lstart-Lend` for ranges — e.g., `[src/auth.ts:42-58](https://github.com/org/repo/blob/main/src/auth.ts#L42-L58)` +- **Mermaid diagrams**: Add a `` comment block immediately after each diagram listing the source files depicted with line numbers +- **Tables**: Include a "Source" column linking to the relevant file and line when listing components, APIs, or configurations +- **Code blocks**: Add a citation comment above each code snippet — `` + ## Behavior When generating a documentation page, you ALWAYS follow this sequence: -1. **Plan** (10% of effort): Determine scope, set word/diagram budget -2. **Analyze** (40% of effort): Read all relevant files, identify patterns, map dependencies — trace actual implementations -3. **Write** (40% of effort): Generate structured Markdown with dark-mode diagrams and citations -4. **Validate** (10% of effort): Check citations are accurate, diagrams render, no shallow claims +1. **Resolve source repo** (MUST be first — see above) +2. **Plan** (10% of effort): Determine scope, set word/diagram budget +3. **Analyze** (40% of effort): Read all relevant files, identify patterns, map dependencies — trace actual implementations +4. **Write** (40% of effort): Generate structured Markdown with dark-mode diagrams and linked citations +5. **Validate** (10% of effort): Check citations are accurate and link correctly, diagrams render, no shallow claims ## Mandatory Requirements -- Minimum 2 Mermaid diagrams per page -- Minimum 5 source file citations per page using `(file_path:line_number)` format +- **Minimum 3–5 Mermaid diagrams per page** (scaled by scope), each followed by a `` comment block +- **Diagram variety**: Each page MUST use at least 2 different diagram types — don't just repeat `graph TB`. Mix architecture graphs, sequence diagrams, class diagrams, state machines, ER diagrams, and flowcharts as appropriate +- Minimum 5 source file citations per page using linked format (see Citation Format above) - Use `autonumber` in all sequence diagrams - Explain WHY, not just WHAT - Every section must add value — no filler content +## Diagram Selection Guide + +Choose diagram types strategically — each type communicates different information: + +| Diagram Type | Use When Documenting | Example | +|---|---|---| +| `graph TB/LR` | System architecture, component relationships, dependency graphs | How modules connect | +| `sequenceDiagram` | Request flows, API interactions, multi-step processes | User login flow | +| `classDiagram` | Class hierarchies, interfaces, type relationships | Domain model | +| `stateDiagram-v2` | Lifecycle, state machines, workflow states | Order status transitions | +| `erDiagram` | Data models, database schema, entity relationships | Database tables | +| `flowchart` | Decision trees, data pipelines, conditional logic | Error handling paths | + +**Rule of thumb**: If a section describes structure → use a graph. If it describes behavior → use a sequence or state diagram. If it describes data → use an ER diagram. If it describes decisions → use a flowchart. + +## Table Formatting Standards + +Tables are a primary tool for making documentation scannable and engaging. Follow these rules: + +- **Use tables aggressively** — prefer tables over prose for any structured information (APIs, configs, components, comparisons, parameters) +- **Descriptive headers**: Use clear, specific column names — not "Name" and "Description" but "Component", "Responsibility", "Key File", "Source" +- **Include a "Source" column** with linked citations when listing code artifacts +- **Consistent formatting**: Align columns, use inline code for file paths and identifiers, use bold for key terms +- **Summary tables**: Start each major section with an at-a-glance summary table before diving into details +- **Comparison tables**: When introducing technologies, patterns, or alternatives — always compare side-by-side + ## Dark-Mode Mermaid Rules All Mermaid diagrams MUST use these inline styles for dark-mode rendering: @@ -60,8 +110,11 @@ Use `
` not `
` in Mermaid labels (Vue compatibility). ## Validation Checklist Before finishing any page: +- [ ] Source repository context resolved (remote URL or confirmed local) - [ ] Every Mermaid block parses without errors +- [ ] Every Mermaid block has a `` comment block listing depicted source files - [ ] No `(file_path)` citation points to a non-existent file +- [ ] All citations use correct format (linked for remote repos, local otherwise) - [ ] At least 2 Mermaid diagrams present - [ ] At least 5 different source files cited - [ ] No claims without code references diff --git a/.github/plugins/deep-wiki/commands/ado.md b/.github/plugins/deep-wiki/commands/ado.md index eb322e2..a218953 100644 --- a/.github/plugins/deep-wiki/commands/ado.md +++ b/.github/plugins/deep-wiki/commands/ado.md @@ -6,6 +6,16 @@ description: Generate a Node.js build script that converts the VitePress wiki to You are a Technical Documentation Engineer. Generate a Node.js build script that converts the VitePress wiki output into Azure DevOps (ADO) Wiki-compatible markdown. +## Source Repository Resolution (MUST DO FIRST) + +Before generating the build script, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL`, preserve linked citations in converted output + - Local → preserve local citations as-is +3. **Do NOT proceed** until resolved + ## Context Azure DevOps Wikis use a markdown dialect that differs from GFM/VitePress in critical ways. This command creates a preprocessing script that reads the generated wiki `.md` files, applies targeted transformations, and writes ADO-compatible copies to `dist/ado-wiki/`. @@ -99,6 +109,7 @@ After generating the script, run it and verify: 5. Parent-relative links converted to plain text 6. Same-directory `.md` links preserved 7. Directory structure preserved +8. `index.md` exists at `dist/ado-wiki/` root and is a proper wiki home page (NOT a placeholder) ## ADO Wiki Incompatibility Reference @@ -125,4 +136,71 @@ After generating the script, run it and verify: ✅ `sequenceDiagram`, `gantt`, `graph`, `classDiagram`, `stateDiagram`, `journey`, `pie`, `erDiagram`, `gitGraph`, `timeline` ❌ `flowchart` (use `graph`), `mindmap`, `sankey`, `quadrantChart`, `xychart`, `block` +## Index Page Generation (CRITICAL) + +The ADO Wiki's `index.md` (root home page) **MUST be a proper wiki landing page**, NOT a generic placeholder. The build script must handle this: + +### Logic + +1. **If the VitePress source has an `index.md`**: Transform it (strip VitePress-specific hero/features blocks, strip front matter) and use it as the ADO wiki home page +2. **If no VitePress `index.md` exists, or it's a VitePress hero-only page**: Generate a proper `index.md` at `dist/ado-wiki/` root with: + - **Project title** as `# heading` (from `package.json` name, README, or repo name) + - **Overview paragraph** — what the project does (from README or generated wiki overview) + - **Table of Contents** — linked list of all wiki sections/pages with descriptions + - **Quick Navigation table** — Section, Description, Link columns for the top-level wiki sections + - **Links to onboarding guides** (if they exist) +3. **NEVER leave `index.md` as a generic "TODO" placeholder** — if the existing `index.md` contains placeholder text like "TODO:", "Give a short introduction", or "TSA bug filing", **replace it entirely** with a proper generated landing page + +### Generated Index Template + +```markdown +# [Project Name] — Wiki + +[1-2 sentence project description] + +## Quick Navigation + +| Section | Description | +|---------|-------------| +| [Onboarding Hub](./onboarding/index.md) | Guide selector for all audiences | +| [Contributor Guide](./onboarding/contributor-guide.md) | For new contributors (assumes Python/JS) | +| [Staff Engineer Guide](./onboarding/staff-engineer-guide.md) | Architectural deep-dive for senior engineers | +| [Executive Guide](./onboarding/executive-guide.md) | Capability & risk overview for engineering leaders | +| [Product Manager Guide](./onboarding/product-manager-guide.md) | Feature-focused guide for PMs | +| [Getting Started](./01-getting-started/...) | Setup, installation, first steps | +| [Architecture](./02-architecture/...) | System design and component overview | +| ... | ... | + +## Wiki Contents + +- [Full table of contents with links to all pages] +``` + +### VitePress Hero Block Stripping + +VitePress `index.md` files often contain YAML `hero:` and `features:` blocks inside front matter. The script must: +- Strip the entire YAML front matter (already handled) +- If the remaining content is empty or only whitespace after stripping, generate the landing page from the template above +- If meaningful markdown content remains after stripping, use that content + +## Citation & Diagram Preservation + +The ADO conversion must preserve the quality of the generated wiki: + +- **Linked citations** (`[file:line](URL)`) MUST be preserved — these are standard markdown links and work in ADO +- **`` comment blocks** after Mermaid diagrams MUST be preserved (HTML comments are compatible with ADO) +- **Tables with "Source" columns** MUST be preserved — standard markdown tables work in ADO +- **Mermaid diagrams** are converted (fences only) but the diagram content and structure are preserved +- **All diagram types** that work in ADO (graph, sequenceDiagram, classDiagram, stateDiagram, erDiagram, etc.) are preserved + +## ADO Wiki Page Ordering + +ADO Wikis use a `.order` file in each directory to control page order in the sidebar. The build script should generate `.order` files: + +```javascript +// For each directory in dist/ado-wiki/, create a .order file +// listing page names (without .md extension) in desired order +// Onboarding guides first, then numbered sections +``` + $ARGUMENTS diff --git a/.github/plugins/deep-wiki/commands/agents.md b/.github/plugins/deep-wiki/commands/agents.md index fc687bc..d81cb88 100644 --- a/.github/plugins/deep-wiki/commands/agents.md +++ b/.github/plugins/deep-wiki/commands/agents.md @@ -100,6 +100,12 @@ For each folder where AGENTS.md is missing, generate a file covering the **six c - ✅ **Always do:** [safe operations the agent can freely perform] - ⚠️ **Ask first:** [operations needing confirmation — schema changes, dependency additions] - 🚫 **Never do:** [hard rules — commit secrets, modify vendor, touch production configs] + +## Documentation +[If wiki/ directory or llms.txt exists, list them here] +- Wiki: `wiki/` — Generated documentation with architecture, onboarding, and API reference +- LLM Context: `llms.txt` — Quick project summary for LLMs (see also `wiki/llms-full.txt` for full content) +- Onboarding: `wiki/onboarding/` — Audience-tailored guides (contributor, staff engineer, executive, PM) ``` ### Step 4: Root AGENTS.md vs Nested diff --git a/.github/plugins/deep-wiki/commands/ask.md b/.github/plugins/deep-wiki/commands/ask.md index 18cf6e0..d0ba596 100644 --- a/.github/plugins/deep-wiki/commands/ask.md +++ b/.github/plugins/deep-wiki/commands/ask.md @@ -6,6 +6,17 @@ description: Ask a question about the repository using wiki context and source f Answer a question about this repository grounded in actual source code. +## Source Repository Resolution (MUST DO FIRST) + +Before answering, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL`, use linked citations: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local → use `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until resolved + ## Question $ARGUMENTS @@ -25,14 +36,15 @@ $ARGUMENTS [1-2 paragraph direct answer] ### How It Works -[Detailed explanation with inline code citations] +[Detailed explanation with inline code citations and at least 1 Mermaid diagram when the answer involves architecture, flow, or relationships] ### Key Files -| File | Purpose | -|------|---------| -| `src/path/file.ts` | [Role in the system] | +| File | Purpose | Source | +|------|---------|--------| +| `src/path/file.ts` | [Role in the system] | [linked citation] | ### Code Example + [Relevant snippet from actual source, if helpful] ### Related @@ -43,6 +55,8 @@ $ARGUMENTS - ONLY use information from actual source files in this repository - NEVER invent, guess, or use external knowledge -- ALWAYS cite source files inline: `(src/path/file.ts:42)` +- ALWAYS cite source files inline using the resolved citation format: + - **Remote**: `[src/path/file.ts:42](REPO_URL/blob/BRANCH/src/path/file.ts#L42)` + - **Local**: `(src/path/file.ts:42)` - Think step by step through complex questions - If information is insufficient, say so explicitly and suggest which files to examine diff --git a/.github/plugins/deep-wiki/commands/build.md b/.github/plugins/deep-wiki/commands/build.md index 771f23e..75b55b2 100644 --- a/.github/plugins/deep-wiki/commands/build.md +++ b/.github/plugins/deep-wiki/commands/build.md @@ -18,21 +18,43 @@ Create a `wiki/` directory with this structure: wiki/ ├── package.json ├── .gitignore -├── index.md # Landing page -├── onboarding-guide.md # Principal-level guide (if exists) -├── zero-to-hero-guide.md # Zero-to-hero guide (if exists) +├── index.md # Wiki home page (NOT a placeholder — see below) +├── llms.txt # LLM-friendly links + descriptions +├── llms-full.txt # LLM-friendly full inlined content +├── onboarding/ # Audience-tailored onboarding guides +│ ├── index.md # Onboarding hub with guide selector +│ ├── contributor-guide.md # For new contributors (assumes Python/JS) +│ ├── staff-engineer-guide.md # For staff/principal engineers +│ ├── executive-guide.md # For VP/director-level leaders +│ └── product-manager-guide.md # For product managers ├── {NN}-{section-name}/ # Numbered section folders │ ├── {page-name}.md │ └── ... ├── .vitepress/ │ ├── config.mts # Full VitePress config │ ├── public/ -│ │ └── logo.svg # Brand logo +│ │ ├── logo.svg # Brand logo +│ │ ├── llms.txt # Served at /llms.txt on deployed site +│ │ └── llms-full.txt # Served at /llms-full.txt on deployed site │ └── theme/ │ ├── index.ts # Theme setup (zoom handlers) │ └── custom.css # Complete dark theme + Mermaid + zoom CSS ``` +### index.md — Wiki Landing Page (CRITICAL) + +The `index.md` MUST be a proper, content-rich wiki home page — **NEVER a generic placeholder**. It serves as the main entry point for both VitePress and ADO Wiki exports. + +Generate `index.md` with: +- **Project title** as `# heading` +- **Overview paragraph** — what the project does, its purpose, key technologies (1-2 sentences) +- **Quick Navigation table** — Section, Description columns linking to all top-level wiki sections +- **Links to onboarding guides** (if they exist) — prominently placed +- **Architecture overview diagram** — a high-level Mermaid `graph LR` showing major system components (reuse from the architecture page) +- **Key technologies table** — Technology, Purpose, Source columns + +For VitePress, the `index.md` can optionally include a `hero:` block in front matter, but the markdown body below it must contain the full landing page content (so it survives ADO conversion which strips front matter). + ### package.json ```json @@ -128,7 +150,7 @@ mermaid: { ### Dynamic Sidebar Generation Scan the generated markdown files and build sidebar config: -- ONBOARDING section always first (uncollapsed) with Principal-Level Guide and Zero to Hero Guide +- ONBOARDING section always first (uncollapsed) with four audience-tailored guides: Contributor, Staff Engineer, Executive, Product Manager - Then numbered sections: `01-getting-started`, `02-architecture`, etc. - Each section becomes a collapsible group - First 3-4 sections uncollapsed, rest collapsed diff --git a/.github/plugins/deep-wiki/commands/catalogue.md b/.github/plugins/deep-wiki/commands/catalogue.md index a555fbc..81176a6 100644 --- a/.github/plugins/deep-wiki/commands/catalogue.md +++ b/.github/plugins/deep-wiki/commands/catalogue.md @@ -6,6 +6,17 @@ description: Generate only the hierarchical wiki structure (table of contents) a Analyze this repository and generate a hierarchical JSON documentation structure. +## Source Repository Resolution (MUST DO FIRST) + +Before any analysis, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL`, use linked citations: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local → use `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until resolved + ## Analysis Phase 1. Read the repository file tree and README @@ -46,7 +57,7 @@ Generate a JSON structure following this schema: ### Rules - Max nesting depth: 4; ≤8 children per section -- Cite real files using `file_path:line_number` in every prompt +- Cite real files using the resolved citation format (linked or local) in every prompt - Getting Started: overview, setup, basic usage, quick reference - Deep Dive layers: Architecture → Subsystems → Components → Key methods/interfaces - Component analysis: classes, services, controllers; dependencies; design patterns (Repository, Factory, Strategy, Observer) diff --git a/.github/plugins/deep-wiki/commands/changelog.md b/.github/plugins/deep-wiki/commands/changelog.md index e492bbc..84a21e1 100644 --- a/.github/plugins/deep-wiki/commands/changelog.md +++ b/.github/plugins/deep-wiki/commands/changelog.md @@ -6,6 +6,16 @@ description: Generate a structured changelog from recent git commits, categorize Analyze the git commit history of this repository and generate a structured changelog. +## Source Repository Resolution (MUST DO FIRST) + +Before generating any changelog, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL`, link commit hashes: `[abc1234](REPO_URL/commit/abc1234)` + - Local → use plain commit hashes +3. **Do NOT proceed** until resolved + ## Process 1. Examine recent git commits (messages, dates, authors) diff --git a/.github/plugins/deep-wiki/commands/generate.md b/.github/plugins/deep-wiki/commands/generate.md index c15ef4b..85a9a1d 100644 --- a/.github/plugins/deep-wiki/commands/generate.md +++ b/.github/plugins/deep-wiki/commands/generate.md @@ -10,6 +10,22 @@ You are a Technical Documentation Architect. Generate a complete, comprehensive Execute the following steps in order: +### Step 0: Source Repository Resolution (MUST DO FIRST) + +Before any analysis, you MUST determine the source repository context. **Do NOT skip this step.** + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote URL exists +2. **Ask the user** (if not already provided): _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - If the user provides a URL (e.g., `https://github.com/org/repo`): store it as `REPO_URL` and use **linked citations** throughout ALL output + - If local-only: use **local citations** (file path + line number without URL) +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` or check for `main`/`master` +4. **Store the citation format** for use in all subsequent steps: + - **Remote**: `[file_path:line_number](REPO_URL/blob/BRANCH/file_path#Lline_number)` — e.g., `[src/auth.ts:42](https://github.com/org/repo/blob/main/src/auth.ts#L42)` + - **Local**: `(file_path:line_number)` — e.g., `(src/auth.ts:42)` + - **Line ranges**: `#Lstart-Lend` — e.g., `[src/auth.ts:42-58](https://github.com/org/repo/blob/main/src/auth.ts#L42-L58)` + - **Mermaid diagrams**: Every diagram MUST be followed by a `` comment block + - **Tables**: Include a "Source" column with linked citations when listing components, APIs, or configurations + ### Step 1: Repository Scan Examine the repository structure. Identify: @@ -38,11 +54,15 @@ Output the catalogue as a JSON code block. ### Step 3: Generate Onboarding Guides -Generate **two** onboarding guides: +Generate **four** audience-tailored onboarding guides in an `onboarding/` folder: + +1. **Contributor Guide** (1000–2500 lines) — For new contributors (assumes Python/JS proficiency). Progressive: Part I (language/framework foundations with cross-language comparisons), Part II (this codebase's architecture and domain model), Part III (getting productive — setup, testing, contributing). Includes glossary, key file reference, and appendices. -1. **Principal-Level Guide** (800–1200 lines) — For senior/principal ICs. Dense, opinionated, architectural. Includes pseudocode in a DIFFERENT language, comparison tables, the ONE core architectural insight, system diagrams, and design tradeoff discussion. +2. **Staff Engineer Guide** (800–1200 lines) — For staff/principal engineers. Dense, opinionated, architectural. Includes pseudocode in a DIFFERENT language, comparison tables, the ONE core architectural insight, system diagrams, design tradeoff discussion, and decision log. -2. **Zero-to-Hero Learning Path** (1000–2500 lines) — For engineers new to the language. Progressive: Part I (foundations with cross-language comparisons), Part II (this codebase), Part III (getting productive). Includes glossary, key file reference, and appendices. +3. **Executive Guide** (400–800 lines) — For VP/director-level engineering leaders. Capability map, risk assessment, technology investment thesis, cost/scaling model, and actionable recommendations. NO code snippets — service-level diagrams only. + +4. **Product Manager Guide** (400–800 lines) — For PMs and non-engineering stakeholders. User journey maps, feature capability map, known limitations, data/privacy overview, and FAQ. ZERO engineering jargon. ### Step 4: Generate Pages @@ -50,10 +70,12 @@ For each leaf node in the catalogue, generate a full documentation page: - Add VitePress frontmatter: `title` and `description` - Start with an Overview paragraph explaining WHY this component exists -- Include **minimum 2 Mermaid diagrams** per page (architecture, sequence, class, state, ER, or flowchart) +- Start with an **at-a-glance summary table** (component, responsibility, key file, source) so readers grasp the system in 30 seconds +- Include **minimum 3–5 Mermaid diagrams** per page using at least 2 different diagram types (architecture, sequence, class, state, ER, or flowchart) - Use `autonumber` in all `sequenceDiagram` blocks -- Cite at least 5 different source files per page using `(file_path:line_number)` inline -- Use Markdown tables for APIs, config options, and component summaries +- Cite at least 5 different source files per page using the resolved citation format (linked or local) +- Use Markdown tables for APIs, config options, and component summaries — include "Source" column with citations +- **Tables over prose**: Convert any list of structured items into a table. Use comparison tables for technologies and alternatives. - End with a References section ### Step 5: Post-Processing & Validation @@ -73,6 +95,7 @@ Scaffold a complete VitePress project in `wiki/` with: - Click-to-zoom for diagrams (custom SVG overlay with pan/zoom) and images (medium-zoom) - Dynamic sidebar from catalogue structure - Onboarding section first (uncollapsed) +- **Proper `index.md` landing page** — NOT a placeholder. Must contain project title, overview, quick navigation table linking to all sections, and links to onboarding guides. See `/deep-wiki:build` for full VitePress packaging details. @@ -93,6 +116,18 @@ Generate `AGENTS.md` files for pertinent repository folders. These files provide See `/deep-wiki:agents` for full AGENTS.md generation details. +### Step 8: Generate llms.txt Files + +Generate `llms.txt` files — LLM-friendly project summaries following the [llms.txt specification](https://llmstxt.org/). + +1. **`./llms.txt`** (repo root) — Standard discovery location. Coding agents and tools (GitHub MCP `get_file_contents`, `search_code`) look here first. Contains H1 project name, blockquote summary, and H2 sections with links into `wiki/` directory. +2. **`wiki/llms.txt`** — Same structure but with wiki-relative paths (for VitePress deployment). +3. **`wiki/llms-full.txt`** — Full page content inlined in `` blocks. Strip YAML frontmatter, preserve Mermaid diagrams and citations. +4. **Section order**: Onboarding → Architecture → Getting Started → Deep Dive → Optional (changelog, contributing) +5. **"Optional" H2** has special meaning — content there can be skipped for shorter context windows + +See `/deep-wiki:llms` for full llms.txt generation details. + ## Mermaid Diagram Rules (ALL diagrams) - Use dark-mode colors: node fills `#2d333b`, borders `#6d5dfc`, text `#e6edf3` diff --git a/.github/plugins/deep-wiki/commands/llms.md b/.github/plugins/deep-wiki/commands/llms.md new file mode 100644 index 0000000..4158c6f --- /dev/null +++ b/.github/plugins/deep-wiki/commands/llms.md @@ -0,0 +1,206 @@ +--- +description: Generate llms.txt and llms-full.txt files for the wiki — LLM-friendly project summaries following the llms.txt specification +--- + +# Deep Wiki: Generate llms.txt + +You are generating `llms.txt` and `llms-full.txt` files that provide LLM-friendly access to the wiki documentation. These follow the [llms.txt specification](https://llmstxt.org/). + +## Source Repository Resolution (MUST DO FIRST) + +Before generating, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL`, use linked references: `[Title](REPO_URL/blob/BRANCH/path)` + - Local → use relative paths to wiki files +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until resolved + +## What is llms.txt + +`llms.txt` is a standardized markdown file that helps LLMs quickly understand a project. It provides: + +- A concise project summary +- Links to key documentation files with brief descriptions +- Structured sections (Onboarding, Architecture, API, etc.) + +Two files are generated: + +| File | Purpose | Size | +|------|---------|------| +| `llms.txt` | Links + brief descriptions — fits in small context windows | Small (1-5 KB) | +| `llms-full.txt` | Full inlined content of all linked pages | Large (50-500 KB) | + +## Step 1: Gather Project Context + +Scan the repository and existing wiki (if generated) to collect: + +1. **Project identity** — name, one-sentence description, primary language, key technologies +2. **Wiki pages** — scan `wiki/` directory for all generated `.md` files +3. **Onboarding guides** — check for `onboarding/` folder with audience-tailored guides +4. **README** — extract the core project description +5. **Key entry points** — main files, API surface, configuration + +## Step 2: Generate `llms.txt` + +Create `wiki/llms.txt` following the llms.txt spec format: + +```markdown +# {Project Name} + +> {One-paragraph summary: what it does, who it's for, key technologies. Dense and informative.} + +{2-3 paragraphs of important context: architectural philosophy, key constraints, what makes this project different. Include things an LLM needs to know to give accurate answers about this project.} + +## Onboarding + +- [{Contributor Guide}](./onboarding/contributor-guide.md): Step-by-step guide for new contributors — environment setup, first task, testing, and coding conventions +- [{Staff Engineer Guide}](./onboarding/staff-engineer-guide.md): Architectural deep-dive for senior engineers — design decisions, domain model, component types, and failure modes +- [{Executive Guide}](./onboarding/executive-guide.md): Capability overview for engineering leaders — risk assessment, technology investment, and scaling model +- [{Product Manager Guide}](./onboarding/product-manager-guide.md): Feature-focused guide for PMs — user journeys, capabilities, limitations, and data/privacy + +## Architecture + +- [{Architecture Overview}](./02-architecture/overview.md): System architecture, component boundaries, and deployment topology +- [{Data Model}](./02-architecture/data-model.md): Core entities, relationships, and data invariants +- [{API Reference}](./02-architecture/api-reference.md): Endpoints, authentication, and wire format + +## Getting Started + +- [{Setup Guide}](./01-getting-started/setup.md): Prerequisites, installation, and first run +- [{Configuration}](./01-getting-started/configuration.md): Environment variables, feature flags, and config files + +## Deep Dive + +- [{Component Name}](./03-deep-dive/component.md): Description of component purpose and scope +- ...additional pages... + +## Optional + +- [{Changelog}](./changelog.md): Recent changes and version history +- [{Contributing}](./contributing.md): How to contribute to the project +``` + +### llms.txt Rules + +1. **H1** — Project name (REQUIRED, only one) +2. **Blockquote** — Dense one-paragraph summary (REQUIRED) +3. **Context paragraphs** — Important notes, constraints, non-obvious things (optional but recommended) +4. **H2 sections** — Each contains a markdown list of `[Title](url): Description` entries +5. **"Optional" section** — Special meaning: these links can be skipped for shorter context. Put changelog, contributing guides, and supplementary material here. +6. **All links are relative** to the wiki directory (e.g., `./onboarding/contributor-guide.md`) +7. **Descriptions are concise** — one sentence per link, informative not generic +8. **Order matters** — put the most important sections first (Onboarding → Architecture → Getting Started → Deep Dive → Optional) +9. **Dynamic content** — derive ALL section names and page titles from the actual generated wiki catalogue, not from templates + +### Content Quality + +- The blockquote summary should be **dense and specific** — not "A project for doing things" but "A distributed task orchestration engine built on Orleans virtual actors, providing reliable workflow execution with at-least-once delivery guarantees for Azure-hosted microservices" +- Context paragraphs should include **non-obvious constraints** — things an LLM would get wrong without being told (e.g., "Although the API surface resembles FastAPI, it uses a custom router that does not support dependency injection") +- Link descriptions should tell the reader **what they'll learn**, not just restate the title + +## Step 3: Generate `llms-full.txt` + +Create `wiki/llms-full.txt` — same structure as `llms.txt` but with full page content inlined using XML-style tags. + +### Format + +```markdown +# {Project Name} + +> {Same blockquote summary as llms.txt} + +{Same context paragraphs as llms.txt} + +## Onboarding + + +{Full markdown content of contributor-guide.md} + + + +{Full markdown content of staff-engineer-guide.md} + + +... + +## Architecture + + +{Full markdown content of overview.md} + + +... + +## Optional + + +{Full markdown content of changelog.md} + +``` + +### llms-full.txt Rules + +1. **Same H1, blockquote, and context** as `llms.txt` +2. **Replace link lists** with `` blocks containing full page content +3. **Each `` tag** has `title` and `path` attributes +4. **Strip VitePress frontmatter** (YAML `---` blocks) from inlined content +5. **Preserve Mermaid diagrams** — keep them as-is inside `` blocks +6. **Preserve citations** — all `[file:line](URL)` links stay intact +7. **Preserve tables** — all markdown tables stay intact +8. **Same section order** as `llms.txt` +9. **"Optional" section** — still present but readers/tools may skip it for context savings + +## Step 4: Validate + +After generating both files, verify: + +1. **All links in `llms.txt` point to files that exist** in the wiki directory +2. **All `` blocks in `llms-full.txt` contain actual content** (not empty or placeholder) +3. **The blockquote summary is specific** to this project (not generic) +4. **Section ordering** matches: Onboarding → Architecture → Getting Started → Deep Dive → Optional +5. **No duplicate entries** — each wiki page appears in exactly one section +6. **File sizes are reasonable** — `llms.txt` should be 1-5 KB, `llms-full.txt` should contain all wiki pages + +## Output + +Generate three files: + +``` +./llms.txt # Root-level discovery file (repo standard path) +wiki/ +├── llms.txt # Links + descriptions (for VitePress site) +└── llms-full.txt # Full inlined content (comprehensive reference) +``` + +### Root `./llms.txt` (Discovery File) + +The root `./llms.txt` is the **standard discovery location** per the llms.txt spec. Coding agents and tools (including the GitHub MCP server's `get_file_contents` and `search_code`) look for `/llms.txt` at the repository root. This file should be identical to `wiki/llms.txt` but with paths adjusted to point into the `wiki/` directory: + +```markdown +- [{Page Title}](./wiki/onboarding/contributor-guide.md): Description +``` + +If a root `llms.txt` already exists and was NOT generated by deep-wiki, do NOT overwrite it — report that it was skipped. + +Report a summary: + +``` +## llms.txt Generation Report + +- `./llms.txt` — Root discovery file, {N} sections, {M} linked pages +- `wiki/llms.txt` — {N} sections, {M} linked pages, {size} KB +- `wiki/llms-full.txt` — {N} sections, {M} inlined pages, {size} KB + +### Sections +| Section | Pages | Notes | +|---------|-------|-------| +| Onboarding | 4 | All audience-tailored guides | +| Architecture | 3 | Core architecture pages | +| Getting Started | 2 | Setup and configuration | +| Deep Dive | {N} | Component documentation | +| Optional | {N} | Changelog, contributing | +``` + +$ARGUMENTS diff --git a/.github/plugins/deep-wiki/commands/onboard.md b/.github/plugins/deep-wiki/commands/onboard.md index fd1e4a6..944e729 100644 --- a/.github/plugins/deep-wiki/commands/onboard.md +++ b/.github/plugins/deep-wiki/commands/onboard.md @@ -1,10 +1,21 @@ --- -description: Generate two onboarding guides for the repository — a Principal-Level guide and a Zero-to-Hero learning path +description: Generate four audience-tailored onboarding guides in an onboarding/ folder — Contributor, Staff Engineer, Executive, and Product Manager --- # Deep Wiki: Onboarding Guide Generation -You are creating onboarding documentation for this codebase. Generate **two** comprehensive guides. +You are creating onboarding documentation for this codebase. Generate **four** audience-tailored guides in an `onboarding/` folder. + +## Source Repository Resolution (MUST DO FIRST) + +Before generating any guides, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL`, use linked citations: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local → use `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until resolved ## Step 1: Language & Technology Detection @@ -23,72 +34,153 @@ Before writing anything, detect: - Redis → Caching, Kafka/RabbitMQ/ServiceBus → Messaging, gRPC/GraphQL → API protocol - Docker/K8s → Containers -## Step 2: Generate Principal-Level Onboarding Guide +## Output Structure -**Audience**: Senior/Principal IC or engineering leader. Deep systems experience, not necessarily familiar with this repo's language. -**Length**: 800–1200 lines. Dense, opinionated, architectural. +``` +onboarding/ +├── index.md # Onboarding hub with guide selector table +├── contributor-guide.md # For new contributors (assumes Python or JS) +├── staff-engineer-guide.md # For staff/principal engineers +├── executive-guide.md # For VP/director-level engineering leaders +└── product-manager-guide.md # For product managers +``` -### Required Sections +### `onboarding/index.md` — Onboarding Hub -1. **Executive Summary** — What the system is in one dense paragraph. What it owns vs delegates. Business context. -2. **The Core Architectural Insight** — The SINGLE most important concept. Include pseudocode in a DIFFERENT language from the repo (e.g., Python pseudocode for a C# codebase). -3. **System Architecture** — Full Mermaid diagram (middleware → controllers → services → storage → external). Call out the "heart" of the system. -4. **Domain Model** — ER diagram (Mermaid) of core entities. Data invariants table. -5. **Component Types & Execution Paths** — Table of all major component variants with code path per variant. -6. **Strategic Direction / Roadmap** — Business model context, engineering workstreams, value propositions. -7. **Storage & Data Architecture** — Stores used, data access layer, consistency model. -8. **API Surface & Protocols** — Endpoints table, wire format, auth model. -9. **Configuration & Feature Flags** — How config is layered, feature gating. -10. **Testing & Development** — Test types, dev setup quickstart, key commands. -11. **Key Design Decisions & Tradeoffs** — Why things are the way they are. -12. **Where to Go Deep** — Reading order for source files, links to wiki sections. - -### Key Rules -- Use **pseudocode in a different language** to explain concepts -- Use **comparison tables** to map unfamiliar concepts (e.g., `Task` = `Awaitable[T]`) -- Use **Engine vs Car** analogies — what the system delegates vs owns -- Dense prose with tables, NOT shallow bullet lists -- Every claim has a file reference: `(file_path:line_number)` +Generate a landing page with project summary and a guide selector table linking to all 4 guides with audience descriptions and estimated reading times. -## Step 3: Generate Zero-to-Hero Learning Path +## Step 2: Generate Contributor Guide -**Audience**: Engineer possibly new to the repo's primary language. Assumes experience in SOME other language. +**File**: `onboarding/contributor-guide.md` +**Audience**: Engineers joining the project. Assumes proficiency in Python or JavaScript. **Length**: 1000–2500 lines. Progressive — each section builds on the last. ### Required Structure -**Part I: Foundation Skills** -1. **{Primary Language} for {Other Language} Engineers** — Syntax side-by-side tables, async model, collections, DI, type system. Concrete code comparisons, NOT abstract descriptions. +**Part I: Foundations** (skip if repo uses Python or JS) +1. **{Primary Language} for Python/JS Engineers** — Syntax side-by-side tables, async model, collections, DI, type system. Concrete code comparisons, NOT abstract descriptions. 2. **{Primary Framework} for Web Framework Users** — Compare to equivalent frameworks. Request pipeline, controllers, routing, config, DI container. -3. **{Key Technology 1} from First Principles** — The problem it solves (story format), core concepts with comparisons, how THIS system uses it specifically. +3. **{Key Technology 1} from First Principles** — The problem it solves, core concepts with comparisons, how THIS system uses it. 4. **{Key Technology 2} from First Principles** — Same approach for second key technology. -5. **Distributed Systems Essentials** (if applicable) — CAP theorem choices, concurrency, idempotency, streaming. **Part II: This Codebase** -6. **The Big Picture** — One-sentence summary, Engine vs Car analogy, core entities table. -7. **Architecture Deep Dive** — N-layer pattern, the "heart" file, feature flags. -8. **Domain Model & Data Flow** — ER diagram, data invariants, primary request lifecycle. -9. **Component Types & Execution Paths** — Component variants table, code paths. -10. **Strategic Context** — Roadmap, strategy, product direction (if available). +5. **The Big Picture** — One-sentence summary, core entities table, architecture `graph TB` diagram. +6. **Domain Model & Data Flow** — `erDiagram`, data invariants, `sequenceDiagram` for primary request lifecycle. +7. **Key Patterns** — "If you want to add X, follow this pattern" templates with real code. **Part III: Getting Productive** -11. **Development Environment Setup** — Prerequisites table, step-by-step setup, common mistakes. -12. **Running Tests** — Unit/integration/E2E commands, log querying. -13. **Navigating the Codebase** — "Start here" file reading order, how to trace a request. -14. **Contributing: Conventions & Patterns** — How to add an endpoint, config flag, etc. +8. **Development Environment Setup** — Prerequisites table (Tool, Version, Install Command), step-by-step setup, common mistakes. +9. **Your First Task** — End-to-end walkthrough of adding a simple feature. +10. **Development Workflow** — Branch strategy, commit conventions, PR process. Use `flowchart` diagram. +11. **Running Tests** — All tests, single file, single test, coverage commands. +12. **Debugging Guide** — Common issues table: Symptom, Cause, Fix. +13. **Common Pitfalls** — Mistakes every new contributor makes and how to avoid them. **Appendices** - **Glossary** (40+ terms) -- **Key File Reference** (path, purpose, why it matters) -- **Further Reading** (links to wiki sections) +- **Key File Reference** (Path, Purpose, Why It Matters, Source) +- **Quick Reference Card** — Cheat sheet of most-used commands ### Key Rules - **Progressive depth**: Part I → Part II → Part III. Never reference something before explaining it. -- **First-principles**: Start with "why does this problem exist?" before the solution. - **Concrete over abstract**: Code examples from the actual codebase. -- **Tables for comparisons**: Language A vs Language B, SQL vs NoSQL, etc. +- **Minimum 5 Mermaid diagrams** — each followed by `` comment block +- Every claim has a linked citation +- Every command must be copy-pasteable with expected output + +## Step 3: Generate Staff Engineer Guide + +**File**: `onboarding/staff-engineer-guide.md` +**Audience**: Staff/principal engineers. Deep systems experience, may not know this repo's language. +**Length**: 800–1200 lines. Dense, opinionated, architectural. + +### Required Sections + +1. **Executive Summary** — What the system is in one dense paragraph. What it owns vs delegates. +2. **The Core Architectural Insight** — The SINGLE most important concept. Include pseudocode in a DIFFERENT language from the repo. +3. **System Architecture** — Full Mermaid `graph TB` diagram (middleware → controllers → services → storage → external). Call out the "heart" of the system. +4. **Domain Model** — Mermaid `erDiagram` of core entities. Data invariants table: Entity, Invariant, Enforced By, Source. +5. **Component Types & Execution Paths** — Table: Component, Type, Execution Path, Key File, Source. +6. **Request Lifecycle** — Mermaid `sequenceDiagram` (with `autonumber`) showing typical request. +7. **State Transitions** — Mermaid `stateDiagram-v2` for domain entities with lifecycle states. +8. **Decision Log** — Table: Decision, Alternatives Considered, Rationale, Source. +9. **Dependency Rationale** — Table: Dependency, Purpose, What It Replaced, Source. +10. **Storage & Data Architecture** — Stores used, data access layer, consistency model. Comparison table. +11. **Failure Modes & Error Handling** — `flowchart` for error propagation. +12. **API Surface & Protocols** — Table: Method, Path, Handler, Auth, Source. +13. **Configuration & Feature Flags** — Table: Key, Default, Description, Source. +14. **Performance Characteristics** — Bottlenecks, scaling limits, hot paths. +15. **Security Model** — Auth, authorization, trust boundaries. +16. **Testing Strategy** — What's tested, what isn't. +17. **Known Technical Debt** — Table: Issue, Risk Level, Affected Files, Source. +18. **Where to Go Deep** — Recommended source file reading order. + +### Key Rules +- Use **pseudocode in a different language** to explain concepts +- Use **comparison tables** to map unfamiliar concepts (e.g., `Task` = `Awaitable[T]`) +- Dense prose with tables, NOT shallow bullet lists +- Every claim has a linked citation + `` comment blocks after each diagram +- **Minimum 5 Mermaid diagrams** (architecture, ER, class, sequence, state/flowchart) +- Focus on WHY decisions were made, not just WHAT exists + +## Step 4: Generate Executive Guide + +**File**: `onboarding/executive-guide.md` +**Audience**: VP/director of engineering. Needs capability overview, risk assessment, and investment context — NOT code-level details. +**Length**: 400–800 lines. Strategic, concise, decision-oriented. + +### Required Sections + +1. **System Overview** — What it does, who uses it, business value (2-3 sentences) +2. **Capability Map** — Table: Capability, Status (Built/Partial/Planned), Maturity, Dependencies +3. **Architecture at a Glance** — High-level Mermaid `graph LR` diagram. Services and deployment units ONLY — no internal code. Focus on team boundaries. +4. **Team Topology** — Table: Component, Owner, Criticality, Bus Factor +5. **Technology Investment Thesis** — Table: Technology, Purpose, Alternatives Considered, Risk Level +6. **Risk Assessment** — Table: Risk, Likelihood, Impact, Mitigation, Owner. Cover reliability, security, scalability, compliance. +7. **Cost & Scaling Model** — How costs scale with usage. Bottlenecks. When next scaling investment is needed. +8. **Dependency Map** — Mermaid `graph TB` showing critical external dependencies. Table: Dependency, Type (Service/Library/Platform), Risk if Unavailable. +9. **Key Metrics & Observability** — Table: Metric, Current Value, Target, Source +10. **Roadmap Alignment** — Engineering workstreams mapped to business priorities +11. **Technical Debt Summary** — Table: Issue, Business Impact, Effort to Fix, Priority (top 5 items) +12. **Recommendations** — 3-5 actionable recommendations for next quarter, prioritized by impact + +### Key Rules +- **NO code snippets** — this guide is for engineering leaders, not coders +- **Diagrams at service/team level**, not class/function level +- **Business language** — translate technical concepts into impact (reliability, velocity, cost, risk) +- Tables for every structured finding +- **Minimum 3 Mermaid diagrams** (architecture overview, dependency map, capability map) +- Every claim backed by evidence — cite wiki sections or source files + +## Step 5: Generate Product Manager Guide + +**File**: `onboarding/product-manager-guide.md` +**Audience**: Product managers and non-engineering stakeholders. Needs to understand capabilities and boundaries — NOT implementation. +**Length**: 400–800 lines. User-centric, feature-focused, constraint-aware. + +### Required Sections + +1. **What This System Does** — 2-3 sentence elevator pitch in plain language (zero jargon) +2. **User Journey Map** — Mermaid `graph LR` or `journey` diagram showing primary user flows +3. **Feature Capability Map** — Table: Feature, Status (Live/Beta/Planned/Not Possible), User Behavior, Limitations +4. **Data Model (Product View)** — Simplified Mermaid `erDiagram` in business terms (e.g., "A Project has many Documents") +5. **Configuration & Feature Flags** — Table: Flag, What It Controls, Default, Who Can Change It +6. **API Capabilities** — Table: Capability, Method, Authentication, Rate Limits (written for integration partners) +7. **Performance & SLAs** — Table: Operation, Expected Latency, Throughput Limit, Current SLA +8. **Known Limitations & Constraints** — Table: Limitation, User Impact, Workaround, Planned Fix +9. **Data & Privacy** — Table: Data Type, Storage Location, Retention, Compliance +10. **Glossary** — Domain terms in plain language +11. **FAQ** — 10+ common PM questions, answered concisely + +### Key Rules +- **ZERO engineering jargon** — no "middleware", "dependency injection", "ORM" +- **User-centric framing** — everything described in terms of user experience +- **Minimum 3 Mermaid diagrams** (user journey, data model, feature map) +- Tables for every structured finding +- If a technical concept must be mentioned, explain it in one plain sentence +- Every claim grounded in evidence -## Mermaid Diagram Rules +## Mermaid Diagram Rules (ALL guides) ALL diagrams must use dark-mode colors: - Node fills: `#2d333b`, borders: `#6d5dfc`, text: `#e6edf3` @@ -103,6 +195,7 @@ After generating each guide, verify: - All file paths mentioned actually exist in the repo - All class/method names are accurate (not hallucinated) - Mermaid diagrams render (no syntax errors) -- No bare HTML-like tags (generics like `List`) outside code fences — wrap in backticks +- No bare HTML-like tags outside code fences — wrap in backticks +- Each guide is appropriate for its audience — no code in Executive/PM guides, no jargon in PM guide $ARGUMENTS diff --git a/.github/plugins/deep-wiki/commands/page.md b/.github/plugins/deep-wiki/commands/page.md index 4ff75c9..4f0f48d 100644 --- a/.github/plugins/deep-wiki/commands/page.md +++ b/.github/plugins/deep-wiki/commands/page.md @@ -6,6 +6,17 @@ description: Generate a single wiki page with dark-mode Mermaid diagrams, source Generate a comprehensive wiki page for the specified topic. +## Source Repository Resolution (MUST DO FIRST) + +Before generating any page, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL`, use linked citations: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local → use `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until resolved + ## Inputs The user will provide a topic/title and optionally specific file paths. Use $ARGUMENTS to determine what to document. @@ -28,9 +39,9 @@ The user will provide a topic/title and optionally specific file paths. Use $ARG - 50–300 files: prioritize critical paths - >300 files: tiered sampling (entry points, domain models, data access, integration edges) 3. Set documentation budget: - - Small scope: ~2,000–3,000 words, 1–3 diagrams - - Medium scope: ~3,000–5,000 words, 2–4 diagrams - - Large/Complex: ~5,000–8,000+ words, 3–6 diagrams + - Small scope: ~2,000–3,000 words, 3 diagrams (2+ types) + - Medium scope: ~3,000–5,000 words, 4 diagrams (3+ types) + - Large/Complex: ~5,000–8,000+ words, 5–8 diagrams (4+ types) ### Phase 2: Deep Code Analysis @@ -45,25 +56,37 @@ Structure the page with: - **VitePress frontmatter**: `title` and `description` - **Overview**: purpose, scope, executive summary — explain WHY this exists +- **At-a-glance summary table**: Key components/concepts with one-line descriptions and source links — readers should grasp the system in 30 seconds - **Architecture / System Design**: with `graph TB/LR` Mermaid diagram -- **Core Components**: purpose, implementation, design patterns, citations per component +- **Core Components**: purpose, implementation, design patterns — use a table per component group with "Component", "Responsibility", "Key File", "Source" columns - **Data Flow / Interactions**: with `sequenceDiagram` (use `autonumber`) +- **State / Lifecycle**: with `stateDiagram-v2` if the system has meaningful state transitions +- **Data Model**: with `erDiagram` if the system has entities or database tables - **Implementation Details**: key algorithms, error handling, state management -- **Configuration & Deployment**: if applicable -- **References**: inline citations throughout using `(file_path:line_number)` +- **Configuration & Deployment**: use tables for config options (Key, Default, Description, Source) +- **References**: inline citations throughout using resolved format + +### Content Organization Rules + +- **Progressive disclosure**: Big picture first → drill into specifics. Don't front-load implementation details. +- **Distill, don't dump**: Every paragraph should earn its place. If a section is just listing things, convert it to a table. +- **Tables over prose**: For any structured data (APIs, parameters, configs, components, comparisons), ALWAYS use a table. +- **One idea per paragraph**: Keep paragraphs focused and scannable. Use bold for key terms. +- **Section summaries**: Start complex sections with a 1-2 sentence TL;DR before the details. +- **Visual rhythm**: Alternate between prose, diagrams, tables, and code blocks — avoid long walls of text. ### Mermaid Requirements -Include **minimum 2 diagrams**, choosing from: +Include **minimum 3 diagrams** using at least 2 different types. More is better — aim for one diagram per major section: -| Type | Best For | -|------|----------| -| `graph TB/LR` | Architecture, component relationships | -| `sequenceDiagram` | API flows, interactions (always use `autonumber`) | -| `classDiagram` | Class hierarchies, interfaces | -| `stateDiagram-v2` | State machines, lifecycle | -| `erDiagram` | Database schema, entities | -| `flowchart` | Data pipelines, decision trees | +| Type | Best For | When to Use | +|------|----------|-------------| +| `graph TB/LR` | Architecture, component relationships | Structural overviews, dependency graphs | +| `sequenceDiagram` | API flows, interactions (always use `autonumber`) | Multi-step processes, request lifecycles | +| `classDiagram` | Class hierarchies, interfaces | Domain models, type relationships | +| `stateDiagram-v2` | State machines, lifecycle | Status transitions, workflow states | +| `erDiagram` | Database schema, entities | Data models, table relationships | +| `flowchart` | Data pipelines, decision trees | Conditional logic, error handling paths | **Dark-mode colors (MANDATORY)**: - Node fills: `#2d333b`, borders: `#6d5dfc`, text: `#e6edf3` @@ -74,10 +97,15 @@ Include **minimum 2 diagrams**, choosing from: ### Citation Rules (MANDATORY) -- Every non-trivial claim: `(src/path/file.ts:42)` -- Approximate: `(src/path/file.ts:~ClassName)` +- Every non-trivial claim uses the resolved citation format: + - **Remote**: `[src/path/file.ts:42](REPO_URL/blob/BRANCH/src/path/file.ts#L42)` + - **Local**: `(src/path/file.ts:42)` + - **Line ranges**: `[src/path/file.ts:42-58](REPO_URL/blob/BRANCH/src/path/file.ts#L42-L58)` +- Approximate: `[src/path/file.ts:~ClassName](REPO_URL/blob/BRANCH/src/path/file.ts)` or `(src/path/file.ts:~ClassName)` - Missing evidence: `(Unknown – verify in path/to/check)` - Minimum 5 different source files cited per page +- **Mermaid diagrams**: Add `` comment block after each diagram +- **Tables**: Include a "Source" column with linked citations when listing components, APIs, or configurations ### VitePress Compatibility @@ -88,8 +116,11 @@ Include **minimum 2 diagrams**, choosing from: ## Validation Checklist Before finalizing, verify: +- [ ] Source repository context resolved (remote URL or confirmed local) - [ ] All file paths mentioned actually exist in the repo - [ ] All class/method names are accurate (not hallucinated) +- [ ] All citations use correct format (linked for remote, local otherwise) +- [ ] Every Mermaid diagram has a `` comment block - [ ] Mermaid diagrams use dark-mode colors - [ ] No bare generics outside code fences - [ ] Every architectural claim has a file reference diff --git a/.github/plugins/deep-wiki/commands/research.md b/.github/plugins/deep-wiki/commands/research.md index da82346..1970840 100644 --- a/.github/plugins/deep-wiki/commands/research.md +++ b/.github/plugins/deep-wiki/commands/research.md @@ -6,6 +6,17 @@ description: Conduct multi-turn deep research on a specific topic — traces act Conduct a comprehensive, multi-turn investigation of a specific topic within this codebase. You are a **researcher and analyst** — your outputs are understanding, maps, explanations, and actionable insights. +## Source Repository Resolution (MUST DO FIRST) + +Before any research, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL`, use linked citations: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local → use `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until resolved + ## Research Topic $ARGUMENTS @@ -34,15 +45,16 @@ You will perform 5 progressive research iterations. Each builds on all previous ### Iterations 2–4: Progressive Deep Dives Each iteration takes a different analytical lens: -- **Iteration 2**: Data flow and state management — trace inputs → transformations → outputs → storage -- **Iteration 3**: Integration, dependency, and API contract perspective — external connections, coupling -- **Iteration 4**: Pattern analysis — design patterns, anti-patterns, trade-offs, risks, technical debt +- **Iteration 2**: Data flow and state management — trace inputs → transformations → outputs → storage. Include `sequenceDiagram` and/or `stateDiagram-v2`. +- **Iteration 3**: Integration, dependency, and API contract perspective — external connections, coupling. Include dependency graph and integration table. +- **Iteration 4**: Pattern analysis — design patterns, anti-patterns, trade-offs, risks, technical debt. Use tables to catalogue patterns and rank risks. For each: - Build upon ALL previous iterations - Focus on one specific unexplored aspect -- Provide new insights with `(file_path:line_number)` citations -- Include Mermaid diagrams (dark-mode colors) when they clarify discoveries +- Provide new insights with linked citations +- **Include at least 1 Mermaid diagram per iteration** (dark-mode colors) — use the diagram type that best fits the analytical lens +- **Include at least 1 structured table per iteration** — organize findings so they're scannable at a glance - Rate confidence for every finding - End with remaining areas to investigate @@ -79,7 +91,8 @@ Maintain this throughout all iterations: ## Rules - NEVER respond with just "Continue the research" — always provide substantive findings -- ALWAYS cite specific files: `(file_path:line_number)` +- ALWAYS cite specific files using the resolved citation format: `[file_path:line_number](REPO_URL/blob/BRANCH/file_path#Lline_number)` (remote) or `(file_path:line_number)` (local) - ALWAYS build on previous iterations — do not repeat - Stay focused on the specific topic — do not drift - Call out the weird stuff — surprising patterns are the most valuable findings +- Include Mermaid diagrams (dark-mode colors) with `` comment blocks after each diff --git a/.github/plugins/deep-wiki/skills/wiki-ado-convert/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-ado-convert/SKILL.md index d84475a..62a3f5c 100644 --- a/.github/plugins/deep-wiki/skills/wiki-ado-convert/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-ado-convert/SKILL.md @@ -7,6 +7,16 @@ description: Converts VitePress/GFM wiki markdown to Azure DevOps Wiki-compatibl Generate a Node.js build script that transforms VitePress/GFM markdown documentation into Azure DevOps Wiki-compatible format. The source files remain untouched — the script produces transformed copies in `dist/ado-wiki/`. +## Source Repository Resolution (MUST DO FIRST) + +Before generating the build script, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL`, preserve linked citations in converted output + - Local → preserve local citations as-is +3. **Do NOT proceed** until resolved + ## Why This Is Needed Azure DevOps Wikis use a markdown dialect that differs from GFM and VitePress in several critical ways. Documentation that renders perfectly in VitePress will have broken diagrams, raw front matter, dead links, and rendering issues when published as an ADO Wiki. @@ -193,6 +203,37 @@ After the script runs, verify: 6. Same-directory `.md` links preserved 7. Directory structure preserved 8. Non-markdown files (images, etc.) copied as-is +9. `index.md` at root is a proper wiki home page (NOT a placeholder) + +## Index Page Generation (CRITICAL) + +The ADO Wiki's `index.md` **MUST be a proper wiki landing page**, NOT a generic placeholder with "TODO" text. + +### Logic + +1. **If VitePress source has `index.md`**: Transform it (strip front matter, strip VitePress hero/features blocks). If meaningful content remains, use it. +2. **If no meaningful content remains** (empty after stripping, or only VitePress hero markup): Generate a proper landing page with: + - Project title as `# heading` + - Overview paragraph (from README or wiki overview page) + - Quick Navigation table (Section, Description columns linking to wiki sections) + - Links to onboarding guides if they exist +3. **NEVER leave a placeholder** — if `index.md` contains "TODO:", "Give a short introduction", or similar placeholder text, **replace it entirely** + +### ADO Wiki `.order` Files + +Generate `.order` files in each directory to control sidebar ordering: +- Onboarding guides first, then numbered sections +- List page names without `.md` extension, one per line + +## Citation & Diagram Preservation + +The converted ADO wiki must maintain the same quality standards: + +- **Linked citations** (`[file:line](URL)`) are standard markdown — preserve them as-is +- **`` comment blocks** after Mermaid diagrams — preserve (HTML comments work in ADO) +- **Tables with "Source" columns** — preserve as-is (standard markdown tables) +- **Mermaid diagrams** — convert fences only; diagram content, types, and structure are preserved +- All Mermaid diagram types supported by ADO (graph, sequenceDiagram, classDiagram, stateDiagram, erDiagram, etc.) pass through unchanged ## Important Notes diff --git a/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md index cb2be98..4706577 100644 --- a/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md @@ -252,6 +252,12 @@ Before writing the file: - ✅ **Always do:** [safe operations] - ⚠️ **Ask first:** [risky operations] - 🚫 **Never do:** [dangerous operations] + +## Documentation +[Only include if wiki/, llms.txt, or docs/ exist in the repo] +- Wiki: `wiki/` — architecture, API, onboarding guides +- LLM Context: `llms.txt` — project summary for coding agents (full version: `wiki/llms-full.txt`) +- Onboarding: `wiki/onboarding/` — guides for contributors, staff engineers, executives, PMs ``` Omit any section that doesn't apply. A 20-line AGENTS.md with real commands beats a 200-line one with generic filler. diff --git a/.github/plugins/deep-wiki/skills/wiki-architect/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-architect/SKILL.md index acbcd10..3d68c34 100644 --- a/.github/plugins/deep-wiki/skills/wiki-architect/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-architect/SKILL.md @@ -14,32 +14,52 @@ You are a documentation architect that produces structured wiki catalogues and o - User asks for a table of contents or documentation plan - User asks for an onboarding guide or "zero to hero" path +## Source Repository Resolution (MUST DO FIRST) + +Before any analysis, you MUST determine the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - Remote URL provided → store as `REPO_URL`, use **linked citations**: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local-only → use **local citations**: `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until source repo context is resolved + ## Procedure -1. **Scan** the repository file tree and README -2. **Detect** project type, languages, frameworks, architectural patterns, key technologies -3. **Identify** layers: presentation, business logic, data access, infrastructure -4. **Generate** a hierarchical JSON catalogue with: - - **Onboarding**: Principal-Level Guide, Zero to Hero Guide +1. **Resolve source repo** (see above — MUST be first) +2. **Scan** the repository file tree and README +3. **Detect** project type, languages, frameworks, architectural patterns, key technologies +4. **Identify** layers: presentation, business logic, data access, infrastructure +5. **Generate** a hierarchical JSON catalogue with: + - **Onboarding**: Contributor Guide, Staff Engineer Guide, Executive Guide, Product Manager Guide (in `onboarding/` folder) - **Getting Started**: overview, setup, usage, quick reference - **Deep Dive**: architecture → subsystems → components → methods -5. **Cite** real files in every section prompt using `file_path:line_number` +6. **Cite** real files in every section prompt using linked or local citation format ## Onboarding Guide Architecture The catalogue MUST include an Onboarding section (always first, uncollapsed) containing: -1. **Principal-Level Guide** — For senior/principal ICs. Dense, opinionated. Includes: - - The ONE core architectural insight with pseudocode in a different language - - System architecture Mermaid diagram, domain model ER diagram - - Design tradeoffs, strategic direction, "where to go deep" reading order - -2. **Zero-to-Hero Learning Path** — For newcomers. Progressive depth: +1. **Contributor Guide** — For new contributors (assumes Python/JS). Progressive depth: - Part I: Language/framework/technology foundations with cross-language comparisons - Part II: This codebase's architecture and domain model - Part III: Dev setup, testing, codebase navigation, contributing - Appendices: 40+ term glossary, key file reference +2. **Staff Engineer Guide** — For staff/principal ICs. Dense, opinionated. Includes: + - The ONE core architectural insight with pseudocode in a different language + - System architecture Mermaid diagram, domain model ER diagram + - Design tradeoffs, decision log, dependency rationale, "where to go deep" reading order + +3. **Executive Guide** — For VP/director-level leaders. NO code snippets. Includes: + - Capability map, risk assessment, technology investment thesis + - Cost/scaling model, dependency map, actionable recommendations + +4. **Product Manager Guide** — For PMs. ZERO engineering jargon. Includes: + - User journey maps, feature capability map, known limitations + - Data/privacy overview, configuration/feature flags, FAQ + ## Language Detection Detect primary language from file extensions and build files, then select a comparison language: diff --git a/.github/plugins/deep-wiki/skills/wiki-changelog/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-changelog/SKILL.md index d94d7dc..c3aaf77 100644 --- a/.github/plugins/deep-wiki/skills/wiki-changelog/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-changelog/SKILL.md @@ -7,6 +7,16 @@ description: Analyzes git commit history and generates structured changelogs cat Generate structured changelogs from git history. +## Source Repository Resolution (MUST DO FIRST) + +Before generating any changelog, you MUST determine the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - Remote URL provided → store as `REPO_URL`, use **linked citations** for commit hashes and file references + - Local-only → use plain commit hashes and file references +3. **Do NOT proceed** until source repo context is resolved + ## When to Activate - User asks "what changed recently", "generate a changelog", "summarize commits" @@ -25,3 +35,4 @@ Generate structured changelogs from git history. - Merge related commits into coherent descriptions - Use project terminology from README - Highlight breaking changes prominently with migration notes +- When `REPO_URL` is available, link commit hashes: `[abc1234](REPO_URL/commit/abc1234)` and changed files: `[file_path](REPO_URL/blob/BRANCH/file_path)` diff --git a/.github/plugins/deep-wiki/skills/wiki-llms-txt/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-llms-txt/SKILL.md new file mode 100644 index 0000000..55d531f --- /dev/null +++ b/.github/plugins/deep-wiki/skills/wiki-llms-txt/SKILL.md @@ -0,0 +1,125 @@ +--- +name: wiki-llms-txt +description: Generates llms.txt and llms-full.txt files for LLM-friendly project documentation following the llms.txt specification. Use when the user wants to create LLM-readable summaries, llms.txt files, or make their wiki accessible to language models. +--- + +# llms.txt Generator + +Generate `llms.txt` and `llms-full.txt` files that provide LLM-friendly access to wiki documentation, following the [llms.txt specification](https://llmstxt.org/). + +## When This Skill Activates + +- User asks to generate `llms.txt` or mentions the llms.txt standard +- User wants to make documentation "LLM-friendly" or "LLM-readable" +- User asks for a project summary file for language models +- User mentions `llms-full.txt` or context-expanded documentation + +## Source Repository Resolution (MUST DO FIRST) + +Before generating, resolve the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_ + - Remote URL → store as `REPO_URL` + - Local → use relative paths only +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until resolved + +## llms.txt Format (Spec-Compliant) + +The file follows the [llms.txt specification](https://llmstxt.org/): + +```markdown +# {Project Name} + +> {Dense one-paragraph summary — what it does, who it's for, key technologies} + +{Important context paragraphs — constraints, architectural philosophy, non-obvious things} + +## {Section Name} + +- [{Page Title}]({relative-path-to-md}): {One-sentence description of what the reader will learn} + +## Optional + +- [{Page Title}]({relative-path-to-md}): {Description — these can be skipped for shorter context} +``` + +### Key Rules + +1. **H1** — Project name (exactly one, required) +2. **Blockquote** — Dense, specific summary (required). Must be unique to THIS project. +3. **Context paragraphs** — Non-obvious constraints, things LLMs would get wrong without being told +4. **H2 sections** — Organized by topic, each with a list of `[Title](url): Description` entries +5. **"Optional" H2** — Special meaning: links here can be skipped for shorter context +6. **Relative links** — All paths relative to wiki directory +7. **Dynamic** — ALL content derived from actual wiki pages, not templates +8. **Section order** — Most important first: Onboarding → Architecture → Getting Started → Deep Dive → Optional + +### Description Quality + +| ❌ Bad | ✅ Good | +|--------|---------| +| "Architecture overview" | "System architecture showing how Orleans grains communicate via message passing with at-least-once delivery" | +| "Getting started guide" | "Prerequisites, local dev setup with Docker Compose, and first API call walkthrough" | +| "The API reference" | "REST endpoints with auth requirements, rate limits, and request/response schemas" | + +## llms-full.txt Format + +Same structure as `llms.txt` but with full content inlined: + +```markdown +# {Project Name} + +> {Same summary} + +{Same context} + +## {Section Name} + + +{Full markdown content — frontmatter stripped, citations and diagrams preserved} + +``` + +### Inlining Rules + +- **Strip YAML frontmatter** (`---` blocks) from each page +- **Preserve Mermaid diagrams** — keep `` ```mermaid `` fences intact +- **Preserve citations** — all `[file:line](URL)` links stay as-is +- **Preserve tables** — all markdown tables stay intact +- **Preserve `` comments** — these provide diagram provenance + +## Prerequisites + +This skill works best when wiki pages already exist (via `/deep-wiki:generate` or `/deep-wiki:page`). If no wiki exists yet: + +1. Suggest running `/deep-wiki:generate` first +2. OR generate a minimal `llms.txt` from README + source code scan (without wiki page links) + +## Output Files + +Generate three files: + +| File | Purpose | Discoverability | +|------|---------|-----------------| +| `./llms.txt` | Root discovery file | Standard path per llms.txt spec. GitHub MCP `get_file_contents` and `search_code` find this first. | +| `wiki/llms.txt` | Wiki-relative links | For VitePress deployment and wiki-internal navigation. | +| `wiki/llms-full.txt` | Full inlined content | Comprehensive reference for agents needing all docs in one file. | + +The root `./llms.txt` links into `wiki/` (e.g., `[Guide](./wiki/onboarding/contributor-guide.md)`). The `wiki/llms.txt` uses wiki-relative paths (e.g., `[Guide](./onboarding/contributor-guide.md)`). + +If a root `llms.txt` already exists and was NOT generated by deep-wiki, do NOT overwrite it. + +## Validation Checklist + +Before finalizing: + +- [ ] All linked files in `llms.txt` actually exist +- [ ] All `` blocks in `llms-full.txt` have real content (not empty) +- [ ] Blockquote is specific to this project (not generic boilerplate) +- [ ] Sections ordered by importance +- [ ] No duplicate page entries across sections +- [ ] "Optional" section only contains truly optional content +- [ ] `llms.txt` is concise (1-5 KB) +- [ ] `llms-full.txt` contains all wiki pages diff --git a/.github/plugins/deep-wiki/skills/wiki-onboarding/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-onboarding/SKILL.md index 6ee3e85..93b6601 100644 --- a/.github/plugins/deep-wiki/skills/wiki-onboarding/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-onboarding/SKILL.md @@ -1,11 +1,22 @@ --- name: wiki-onboarding -description: Generates two complementary onboarding guides — a Principal-Level architectural deep-dive and a Zero-to-Hero contributor walkthrough. Use when the user wants onboarding documentation for a codebase. +description: Generates four audience-tailored onboarding guides in an onboarding/ folder — Contributor, Staff Engineer, Executive, and Product Manager. Use when the user wants onboarding documentation for a codebase. --- # Wiki Onboarding Guide Generator -Generate two complementary onboarding documents that together give any engineer — from newcomer to principal — a complete understanding of a codebase. +Generate four audience-tailored onboarding documents in an `onboarding/` folder, each giving a different stakeholder exactly the understanding they need. + +## Source Repository Resolution (MUST DO FIRST) + +Before generating any guides, you MUST determine the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - Remote URL provided → store as `REPO_URL`, use **linked citations**: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local-only → use **local citations**: `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until source repo context is resolved ## When to Activate @@ -13,6 +24,32 @@ Generate two complementary onboarding documents that together give any engineer - User runs `/deep-wiki:onboard` command - User wants to help new team members understand a codebase +## Output Structure + +Generate an `onboarding/` folder with these files: + +``` +onboarding/ +├── index.md # Onboarding hub — links to all 4 guides with audience descriptions +├── contributor-guide.md # For new contributors (assumes Python or JS background) +├── staff-engineer-guide.md # For staff/principal engineers +├── executive-guide.md # For VP/director-level engineering leaders +└── product-manager-guide.md # For product managers and non-engineering stakeholders +``` + +### `index.md` — Onboarding Hub + +A landing page with: +- **One-paragraph project summary** +- **Guide selector table**: + +| Guide | Audience | What You'll Learn | Time | +|-------|----------|-------------------|------| +| [Contributor Guide](./contributor-guide.md) | New contributors with Python/JS experience | Setup, first PR, codebase patterns | ~30 min | +| [Staff Engineer Guide](./staff-engineer-guide.md) | Staff/principal engineers | Architecture, design decisions, system boundaries | ~45 min | +| [Executive Guide](./executive-guide.md) | VP/directors of engineering | Capabilities, risks, team topology, investment thesis | ~20 min | +| [Product Manager Guide](./product-manager-guide.md) | Product managers | Features, user journeys, constraints, data model | ~20 min | + ## Language Detection Scan the repository for build files to determine the primary language for code examples: @@ -23,55 +60,161 @@ Scan the repository for build files to determine the primary language for code e - `go.mod` → Go - `pom.xml` / `build.gradle` → Java -## Guide 1: Principal-Level Onboarding +--- + +## Guide 1: Contributor Guide -**Audience**: Senior/staff+ engineers who need the "why" behind decisions. +**File**: `onboarding/contributor-guide.md` +**Audience**: Engineers joining the project. Assumes proficiency in Python or JavaScript and general software engineering experience. +**Length**: 1000–2500 lines. Progressive — each section builds on the last. ### Required Sections -1. **System Philosophy & Design Principles** — What invariants does the system maintain? What were the key design choices and why? -2. **Architecture Overview** — Component map with Mermaid diagram. What owns what, communication patterns. -3. **Key Abstractions & Interfaces** — The load-bearing abstractions everything depends on -4. **Decision Log** — Major architectural decisions with context, alternatives considered, trade-offs -5. **Dependency Rationale** — Why each major dependency was chosen, what it replaced -6. **Data Flow & State** — How data moves through the system (traced from actual code, not guessed) -7. **Failure Modes & Error Handling** — What breaks, how errors propagate, recovery patterns -8. **Performance Characteristics** — Bottlenecks, scaling limits, hot paths -9. **Security Model** — Auth, authorization, trust boundaries, data sensitivity -10. **Testing Strategy** — What's tested, what isn't, testing philosophy -11. **Operational Concerns** — Deployment, monitoring, feature flags, configuration -12. **Known Technical Debt** — Honest assessment of shortcuts and their risks +**Part I: Foundations** (skip if repo uses Python or JS) +1. **{Primary Language} for Python/JS Engineers** — Syntax comparison tables, async model, collections, type system, package management. Concrete code side-by-side, NOT abstract descriptions. +2. **{Primary Framework} Essentials** — Compare to equivalent Python/JS frameworks (e.g., FastAPI, Express). Request pipeline, routing, DI, config. + +**Part II: This Codebase** +3. **What This Project Does** — 2-3 sentence elevator pitch +4. **Project Structure** — Annotated directory tree (what lives where and why). Include `graph TB` architecture overview. +5. **Core Concepts** — Domain-specific terminology explained with code examples. Use `erDiagram` for data model. +6. **Request Lifecycle** — `sequenceDiagram` (with `autonumber`) tracing a typical request end-to-end. +7. **Key Patterns** — "If you want to add X, follow this pattern" templates with real code + +**Part III: Getting Productive** +8. **Prerequisites & Setup** — Table: Tool, Version, Install Command. Step-by-step with expected output at each step. +9. **Your First Task** — End-to-end walkthrough of adding a simple feature +10. **Development Workflow** — Branch strategy, commit conventions, PR process. Use `flowchart` diagram. +11. **Running Tests** — All tests, single file, single test, coverage commands +12. **Debugging Guide** — Common issues table: Symptom, Cause, Fix +13. **Common Pitfalls** — Mistakes every new contributor makes and how to avoid them + +**Appendices** +- **Glossary** (40+ terms) +- **Key File Reference** — Table: Path, Purpose, Why It Matters, Source +- **Quick Reference Card** — Cheat sheet of most-used commands and patterns ### Rules -- Every claim backed by `(file_path:line_number)` citation -- Minimum 3 Mermaid diagrams (architecture, data flow, dependency graph) -- All Mermaid diagrams use dark-mode colors (see wiki-vitepress skill) +- All code examples in the detected primary language +- Every command must be copy-pasteable with expected output +- **Minimum 5 Mermaid diagrams** (architecture, ER, sequence, flowchart, state) +- Use Mermaid for workflow diagrams (dark-mode colors) — add `` comment block after each +- Ground all claims in actual code — cite using linked format + +--- + +## Guide 2: Staff Engineer Guide + +**File**: `onboarding/staff-engineer-guide.md` +**Audience**: Staff/principal engineers who need the "why" behind every decision. Deep systems experience, may not know this repo's language. +**Length**: 800–1200 lines. Dense, opinionated, architectural. + +### Required Sections + +1. **Executive Summary** — What the system is in one dense paragraph. What it owns vs delegates. +2. **The Core Architectural Insight** — The SINGLE most important concept. Include pseudocode in a DIFFERENT language from the repo. +3. **System Architecture** — Full Mermaid `graph TB` diagram. Call out the "heart" of the system. +4. **Domain Model** — Mermaid `erDiagram` of core entities. Data invariants table: Entity, Invariant, Enforced By, Source. +5. **Key Abstractions & Interfaces** — `classDiagram` showing load-bearing abstractions. +6. **Request Lifecycle** — `sequenceDiagram` (with `autonumber`) showing typical request from entry to response. +7. **State Transitions** — `stateDiagram-v2` for entities with meaningful lifecycle states. +8. **Decision Log** — Table: Decision, Alternatives Considered, Rationale, Source. +9. **Dependency Rationale** — Table: Dependency, Purpose, What It Replaced, Source. +10. **Data Flow & State** — How data moves through the system. Storage comparison table. +11. **Failure Modes & Error Handling** — `flowchart` for error propagation paths. +12. **Performance Characteristics** — Bottlenecks, scaling limits, hot paths. +13. **Security Model** — Auth, authorization, trust boundaries, data sensitivity. +14. **Testing Strategy** — What's tested, what isn't, testing philosophy. +15. **Known Technical Debt** — Table: Issue, Risk Level, Affected Files, Source. +16. **Where to Go Deep** — Recommended reading order of source files, links to wiki sections. + +### Rules +- Use **pseudocode in a different language** to explain concepts +- Use **comparison tables** to map unfamiliar concepts (e.g., `Task` = `Awaitable[T]`) +- Dense prose with tables, NOT shallow bullet lists +- Every claim backed by linked citation +- **Minimum 5 Mermaid diagrams** (architecture, ER, class, sequence, state, flowchart) +- Each diagram followed by `` comment block +- **Use tables aggressively** — decisions, dependencies, debt should ALL be tables with Source columns - Focus on WHY decisions were made, not just WHAT exists -## Guide 2: Zero-to-Hero Contributor Guide +--- + +## Guide 3: Executive Guide -**Audience**: New contributors who need step-by-step practical guidance. +**File**: `onboarding/executive-guide.md` +**Audience**: VP/director of engineering. Needs capability overview, risk assessment, and investment context — NOT code-level details. +**Length**: 400–800 lines. Strategic, concise, decision-oriented. ### Required Sections -1. **What This Project Does** — 2-3 sentence elevator pitch -2. **Prerequisites** — Tools, versions, accounts needed -3. **Environment Setup** — Step-by-step with exact commands, expected output at each step -4. **Project Structure** — Annotated directory tree (what lives where and why) -5. **Your First Task** — End-to-end walkthrough of adding a simple feature -6. **Development Workflow** — Branch strategy, commit conventions, PR process -7. **Running Tests** — How to run tests, what to test, how to add a test -8. **Debugging Guide** — Common issues and how to diagnose them -9. **Key Concepts** — Domain-specific terminology explained with code examples -10. **Code Patterns** — "If you want to add X, follow this pattern" templates -11. **Common Pitfalls** — Mistakes every new contributor makes and how to avoid them -12. **Where to Get Help** — Communication channels, documentation, key contacts -13. **Glossary** — Terms used in the codebase that aren't obvious -14. **Quick Reference Card** — Cheat sheet of most-used commands and patterns +1. **System Overview** — What it does, who uses it, business value in 2-3 sentences +2. **Capability Map** — Table: Capability, Status (Built/Partial/Planned), Maturity, Dependencies. What the system can and cannot do today. +3. **Architecture at a Glance** — High-level Mermaid `graph LR` diagram. Services, data stores, external integrations — NO internal code details. Focus on deployment units and team boundaries. +4. **Team Topology** — Which team/person owns which components. Table: Component, Owner, Criticality, Bus Factor. +5. **Technology Investment Thesis** — Why these technologies were chosen. Table: Technology, Purpose, Alternatives Considered, Risk Level. +6. **Risk Assessment** — Table: Risk, Likelihood, Impact, Mitigation, Owner. Cover reliability, security, scalability, compliance. +7. **Cost & Scaling Model** — How costs scale with usage. What the bottlenecks are. When the next scaling investment is needed. +8. **Dependency Map** — `graph TB` showing critical external dependencies. Table: Dependency, Type (Service/Library/Platform), Risk if Unavailable. +9. **Key Metrics & Observability** — What's measured, what dashboards exist, alerting coverage. Table: Metric, Current Value, Target, Source. +10. **Roadmap Alignment** — Engineering workstreams mapped to business priorities. What's in progress, what's planned, what's blocked. +11. **Technical Debt Summary** — Top 5 debt items with business impact. Table: Issue, Business Impact, Effort to Fix, Priority. +12. **Recommendations** — 3-5 actionable recommendations for the next quarter, prioritized by impact. ### Rules -- All code examples in the detected primary language -- Every command must be copy-pasteable -- Include expected output for verification steps -- Use Mermaid for workflow diagrams (dark-mode colors) -- Ground all claims in actual code — cite `(file_path:line_number)` +- **NO code snippets** — this guide is for engineering leaders, not coders +- **Diagrams at service/team level**, not class/function level +- **Every claim backed by evidence** — cite wiki sections, architecture docs, or source files +- **Minimum 3 Mermaid diagrams** (architecture overview, dependency map, capability/roadmap) +- Tables for every structured finding — this audience reads tables, not prose +- **Business language** — translate technical concepts into impact (reliability, velocity, cost, risk) + +--- + +## Guide 4: Product Manager Guide + +**File**: `onboarding/product-manager-guide.md` +**Audience**: Product managers and non-engineering stakeholders. Needs to understand what the system does, what's possible, and where the boundaries are — NOT how it's built. +**Length**: 400–800 lines. User-centric, feature-focused, constraint-aware. + +### Required Sections + +1. **What This System Does** — 2-3 sentence elevator pitch in user-facing language (no jargon) +2. **User Journey Map** — Mermaid `graph LR` or `journey` diagram showing primary user flows through the system +3. **Feature Capability Map** — Table: Feature, Status (Live/Beta/Planned/Not Possible), User-Facing Behavior, Limitations. Comprehensive map of what's built and what's not. +4. **Data Model (Product View)** — Simplified Mermaid `erDiagram` showing entities users interact with. Explain in business terms (e.g., "A Project has many Documents" not "FK relationship"). +5. **Configuration & Feature Flags** — Table: Flag/Config, What It Controls, Default, Who Can Change It. What can be toggled without engineering work. +6. **API Capabilities** — What integrations are possible. Table: Capability, Endpoint/Method, Authentication, Rate Limits. Written for integration partners, not developers. +7. **Performance & SLAs** — Response times, throughput limits, availability targets. Table: Operation, Expected Latency, Throughput Limit, Current SLA. +8. **Known Limitations & Constraints** — Honest list of what the system can't do or does poorly. Table: Limitation, User Impact, Workaround, Planned Fix. +9. **Data & Privacy** — What data is collected, where it's stored, retention policies, compliance status. Table: Data Type, Storage Location, Retention, Compliance. +10. **Glossary** — Domain terms explained in plain language (not engineering jargon) +11. **FAQ** — 10+ common questions a PM would ask, answered concisely + +### Rules +- **ZERO engineering jargon** — no "middleware", "dependency injection", "ORM". Use plain language. +- **User-centric framing** — describe everything in terms of what users experience, not how code works +- **Minimum 3 Mermaid diagrams** (user journey, data model, feature map/capability overview) +- Tables for every structured finding — PMs scan tables, not prose +- If a technical concept must be mentioned, explain it in one sentence (e.g., "Feature flags — toggles that let us turn features on/off without deploying code") +- Every claim grounded in evidence — cite wiki sections or source files for verification + +--- + +## Mermaid Diagram Rules (ALL guides) + +ALL diagrams must use dark-mode colors: +- Node fills: `#2d333b`, borders: `#6d5dfc`, text: `#e6edf3` +- Subgraph backgrounds: `#161b22`, borders: `#30363d` +- Lines: `#8b949e` +- If using inline `style` directives, use dark fills with `,color:#e6edf3` +- Do NOT use `
` in Mermaid labels (use `
` or line breaks) + +## Validation + +After generating each guide, verify: +- All file paths mentioned actually exist in the repo +- All class/method names are accurate (not hallucinated) +- Mermaid diagrams render (no syntax errors) +- No bare HTML-like tags (generics like `List`) outside code fences — wrap in backticks +- Each guide is appropriate for its audience — no code in Executive/PM guides diff --git a/.github/plugins/deep-wiki/skills/wiki-page-writer/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-page-writer/SKILL.md index c2afc7a..874ad2f 100644 --- a/.github/plugins/deep-wiki/skills/wiki-page-writer/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-page-writer/SKILL.md @@ -13,6 +13,17 @@ You are a senior documentation engineer that generates comprehensive technical d - User wants a technical deep-dive with diagrams - A wiki catalogue section needs its content generated +## Source Repository Resolution (MUST DO FIRST) + +Before generating any page, you MUST determine the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - Remote URL provided → store as `REPO_URL`, use **linked citations**: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local-only → use **local citations**: `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until source repo context is resolved + ## Depth Requirements (NON-NEGOTIABLE) 1. **TRACE ACTUAL CODE PATHS** — Do not guess from file names. Read the implementation. @@ -40,24 +51,34 @@ description: "One-line description" ``` ### Mermaid Diagrams -- **Minimum 2 per page** +- **Minimum 3–5 per page** (scaled by scope: small=3, medium=4, large=5+) +- **Use at least 2 different diagram types** — don't repeat the same type. Mix `graph`, `sequenceDiagram`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `flowchart` as appropriate - Use `autonumber` in all `sequenceDiagram` blocks -- Choose appropriate types: `graph`, `sequenceDiagram`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `flowchart` - **Dark-mode colors (MANDATORY)**: node fills `#2d333b`, borders `#6d5dfc`, text `#e6edf3` - Subgraph backgrounds: `#161b22`, borders `#30363d`, lines `#8b949e` - If using inline `style`, use dark fills with `,color:#e6edf3` - Do NOT use `
` (use `
` or line breaks) +- **Diagram selection**: structure → graph; behavior → sequence/state; data → ER; decisions → flowchart ### Citations -- Every non-trivial claim needs `(file_path:line_number)` +- Every non-trivial claim needs a citation with the resolved format: + - **Remote repo**: `[src/path/file.ts:42](REPO_URL/blob/BRANCH/src/path/file.ts#L42)` + - **Local repo**: `(src/path/file.ts:42)` + - **Line ranges**: `[src/path/file.ts:42-58](REPO_URL/blob/BRANCH/src/path/file.ts#L42-L58)` - Minimum 5 different source files cited per page - If evidence is missing: `(Unknown – verify in path/to/check)` +- **Mermaid diagrams**: Add a `` comment block immediately after each diagram +- **Tables**: Include a "Source" column with linked citations when listing components, APIs, or configurations ### Structure - Overview (explain WHY) → Architecture → Components → Data Flow → Implementation → References -- Use Markdown tables for APIs, configs, and component summaries -- Use comparison tables when introducing technologies +- **Use tables aggressively** — prefer tables over prose for any structured information (APIs, configs, components, comparisons) +- **Summary tables first**: Start each major section with an at-a-glance summary table before details +- Use comparison tables when introducing technologies or patterns — always compare side-by-side +- Include a "Source" column with linked citations in tables listing code artifacts +- Use bold for key terms, inline code for identifiers and paths - Include pseudocode in a familiar language when explaining complex code paths +- **Progressive disclosure**: Start with the big picture, then drill into specifics — don't front-load details ### VitePress Compatibility - Escape bare generics outside code fences: `` `List` `` not bare `List` diff --git a/.github/plugins/deep-wiki/skills/wiki-qa/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-qa/SKILL.md index d0869f5..74aba51 100644 --- a/.github/plugins/deep-wiki/skills/wiki-qa/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-qa/SKILL.md @@ -13,18 +13,34 @@ Answer repository questions grounded entirely in source code evidence. - User wants to understand a specific file, function, or component - User asks "how does X work" or "where is Y defined" +## Source Repository Resolution (MUST DO FIRST) + +Before answering any question, you MUST determine the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - Remote URL provided → store as `REPO_URL`, use **linked citations**: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local-only → use **local citations**: `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until source repo context is resolved + ## Procedure -1. Detect the language of the question; respond in the same language -2. Search the codebase for relevant files -3. Read those files to gather evidence -4. Synthesize an answer with inline citations +1. Resolve source repo context (see above) +2. Detect the language of the question; respond in the same language +3. Search the codebase for relevant files +4. Read those files to gather evidence +5. Synthesize an answer with inline linked citations ## Response Format - Use `##` headings, code blocks with language tags, tables, bullet lists -- Cite sources inline: `(src/path/file.ts:42)` -- Include a "Key Files" table mapping files to their roles +- Cite sources inline using resolved format: + - **Remote**: `[src/path/file.ts:42](REPO_URL/blob/BRANCH/src/path/file.ts#L42)` + - **Local**: `(src/path/file.ts:42)` +- Include a "Key Files" table mapping files to their roles (with linked citations in the "File" column) +- **Include at least 1 Mermaid diagram** when the answer involves architecture, data flow, or relationships — a diagram makes the answer 10x more useful +- **Use tables** for any structured data in the answer (component lists, API endpoints, config options, comparisons) - If information is insufficient, say so and suggest files to examine ## Rules diff --git a/.github/plugins/deep-wiki/skills/wiki-researcher/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-researcher/SKILL.md index 83e29e5..7d33e38 100644 --- a/.github/plugins/deep-wiki/skills/wiki-researcher/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-researcher/SKILL.md @@ -13,6 +13,17 @@ You are an expert software engineer and systems analyst. Your job is to deeply u - User wants to understand a complex system spanning many files - User asks for architectural analysis or pattern investigation +## Source Repository Resolution (MUST DO FIRST) + +Before any research, you MUST determine the source repository context: + +1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists +2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ + - Remote URL provided → store as `REPO_URL`, use **linked citations**: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` + - Local-only → use **local citations**: `(file_path:line_number)` +3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` +4. **Do NOT proceed** until source repo context is resolved + ## Core Invariants (NON-NEGOTIABLE) ### Depth Before Breadth @@ -41,11 +52,13 @@ You are an expert software engineer and systems analyst. Your job is to deeply u Each iteration takes a different lens and builds on all prior findings: -1. **Structural/Architectural view** — map the landscape, identify components, entry points -2. **Data flow / State management view** — trace data through the system -3. **Integration / Dependency view** — external connections, API contracts -4. **Pattern / Anti-pattern view** — design patterns, trade-offs, technical debt, risks -5. **Synthesis / Recommendations** — combine all findings, provide actionable insights +1. **Structural/Architectural view** — map the landscape, identify components, entry points. Include a `graph TB` architecture diagram. +2. **Data flow / State management view** — trace data through the system. Include `sequenceDiagram` and/or `stateDiagram-v2`. +3. **Integration / Dependency view** — external connections, API contracts. Include dependency graph and integration table. +4. **Pattern / Anti-pattern view** — design patterns, trade-offs, technical debt, risks. Use tables to catalogue patterns found. +5. **Synthesis / Recommendations** — combine all findings, provide actionable insights. Include summary tables ranking findings by impact. + +**Each iteration should include at least 1 Mermaid diagram and 1 structured table** to make findings scannable and engaging. ### For Every Significant Finding @@ -58,8 +71,8 @@ Each iteration takes a different lens and builds on all prior findings: ## Rules - NEVER repeat findings from prior iterations -- ALWAYS cite files: `(file_path:line_number)` +- ALWAYS cite files using the resolved citation format (linked for remote repos, local otherwise): `[file_path:line_number](REPO_URL/blob/BRANCH/file_path#Lline_number)` or `(file_path:line_number)` - ALWAYS provide substantive analysis — never just "continuing..." -- Include Mermaid diagrams (dark-mode colors) when they clarify architecture or flow +- Include Mermaid diagrams (dark-mode colors) when they clarify architecture or flow — add `` comment block after each diagram - Stay focused on the specific topic - Flag what you HAVEN'T explored — boundaries of your knowledge at all times diff --git a/README.md b/README.md index 51b3820..b4d5193 100644 --- a/README.md +++ b/README.md @@ -545,7 +545,7 @@ Plugins are installable packages containing curated sets of agents, commands, an | Plugin | Description | Commands | |--------|-------------|----------| -| [deep-wiki](.github/plugins/deep-wiki/) | AI-powered wiki generator with Mermaid diagrams, architecture analysis, and source citations | `/deep-wiki:generate`, `/deep-wiki:catalogue`, `/deep-wiki:page`, `/deep-wiki:changelog`, `/deep-wiki:research`, `/deep-wiki:ask` | +| [deep-wiki](.github/plugins/deep-wiki/) | AI-powered wiki generator with Mermaid diagrams, source citations, onboarding guides, AGENTS.md, and llms.txt | `/deep-wiki:generate`, `/deep-wiki:catalogue`, `/deep-wiki:page`, `/deep-wiki:research`, `/deep-wiki:ask`, `/deep-wiki:onboard`, `/deep-wiki:agents`, `/deep-wiki:llms`, `/deep-wiki:changelog`, `/deep-wiki:ado`, `/deep-wiki:build` | --- diff --git a/docs-site/src/pages/index.astro b/docs-site/src/pages/index.astro index e442654..055fced 100644 --- a/docs-site/src/pages/index.astro +++ b/docs-site/src/pages/index.astro @@ -53,7 +53,7 @@ import mcpServers from '../data/mcp-servers.json'; 🌊

Deep Wiki

-

AI-powered wiki generator — Mermaid diagrams, architecture analysis, and source citations for any codebase

+

AI-powered wiki generator — Mermaid diagrams, source citations, onboarding guides, AGENTS.md, and llms.txt for any codebase

@@ -66,11 +66,11 @@ import mcpServers from '../data/mcp-servers.json';
🌊

Deep Wiki

- v1.0.0 + v2.0.0
-

AI-powered wiki generator for code repositories. Generates comprehensive, Mermaid-rich structured documentation with architecture diagrams, component analysis, and source citations.

+

AI-powered wiki generator for code repositories. Generates comprehensive, Mermaid-rich documentation with source-linked citations, onboarding guides, AGENTS.md, llms.txt, and dark-mode VitePress sites.

Install in Copilot CLI

@@ -111,6 +111,26 @@ import mcpServers from '../data/mcp-servers.json'; /deep-wiki:ask Q&A grounded in source code
+
+ /deep-wiki:onboard + 4 audience-tailored onboarding guides +
+
+ /deep-wiki:agents + Generate AGENTS.md for key folders +
+
+ /deep-wiki:llms + Generate llms.txt for LLM-friendly access +
+
+ /deep-wiki:build + Package as VitePress dark-theme site +
+
+ /deep-wiki:ado + Export to Azure DevOps Wiki format +