@sandrinio/vdoc 3.0.1 → 3.3.1

package/skills/agents/references/exploration-strategies.md

@@ -0,0 +1,289 @@
+# Exploration Strategies
+
+Smart, targeted codebase exploration. Two phases: fingerprint the project, then follow the right archetype playbook.
+
+## Phase 1 — Fingerprint
+
+Read these high-signal files first (whichever exist) to classify the project. **3-5 reads max.**
+
+### Package / Config Files (read 1-2)
+
+| File | Ecosystem |
+|------|-----------|
+| `package.json` | Node.js / JavaScript / TypeScript |
+| `pyproject.toml` / `setup.py` / `requirements.txt` | Python |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `Gemfile` | Ruby |
+| `pom.xml` / `build.gradle` | Java / Kotlin |
+| `composer.json` | PHP |
+| `*.csproj` / `*.sln` | .NET |
+| `pubspec.yaml` | Dart / Flutter |
+
+### Structure Scan
+
+- List root directory
+- List `src/` or `app/` or `lib/` (whichever exists)
+
+### Entry Points (read 1-2)
+
+- README.md (first 50 lines)
+- Main entry file (e.g., `src/index.ts`, `main.py`, `cmd/main.go`)
+
+### Determine
+
+1. **Primary language(s)** and framework(s)
+2. **Project archetype** — match to a playbook below
+3. **Rough scope** — small (< 20 files), medium (20-100), large (100+)
+
+If the project spans multiple archetypes (e.g., monorepo with frontend + API), apply multiple playbooks.
+
+---
+
+## Phase 2 — Archetype Playbooks
+
+Match the detected archetype and follow its playbook. Each defines:
+- **Glob patterns** — files to read, in priority order
+- **What to extract** — what each file category reveals
+- **Feature signals** — patterns that indicate documentable features
+
+---
+
+### Web API
+
+**Signals:** Express, FastAPI, Django REST, Rails, Spring Boot, Gin, Actix, Phoenix, Hono, NestJS
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/routes/**`, `**/router.*`, `**/urls.py` | Endpoints, HTTP methods, URL structure |
+| 2 | `**/middleware/**`, `**/middleware.*` | Auth, CORS, rate limiting, logging, error handling |
+| 3 | `**/models/**`, `**/schema*`, `**/migrations/**` | Data model, entities, relationships |
+| 4 | `**/controllers/**`, `**/handlers/**`, `**/views/**` | Business logic per endpoint |
+| 5 | `**/services/**`, `**/lib/**` | Shared logic, external integrations |
+| 6 | `**/config/**`, `.env*`, `**/settings*` | Environment config, feature flags |
+| 7 | `**/tests/**` (skim 2-3) | What's tested reveals what matters |
+
+**Feature signals:**
+- Auth routes/middleware → Authentication doc
+- Payment/billing routes → Payments doc
+- File upload handlers → File Management doc
+- WebSocket/SSE handlers → Real-time doc
+- Background jobs/queues → Background Processing doc
+- Email/notification services → Notifications doc
+- Search endpoints → Search doc
+- Admin routes → Admin Panel doc
+
+---
+
+### Frontend SPA
+
+**Signals:** React (CRA/Vite), Vue, Svelte, Angular, Solid
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/pages/**`, `**/views/**`, `**/routes*` | Page tree, routing structure |
+| 2 | `**/store/**`, `**/context/**`, `**/state/**`, `**/*slice*` | State shape, data flow |
+| 3 | `**/api/**`, `**/services/**`, `**/hooks/use*` | API integration, data fetching |
+| 4 | `**/components/**` (skim top-level) | Component architecture, shared vs feature |
+| 5 | `**/types/**`, `**/interfaces/**`, `**/*.d.ts` | Data contracts, shared types |
+| 6 | `**/utils/**`, `**/helpers/**` | Shared utilities |
+| 7 | `**/config/**`, `.env*` | Feature flags, API URLs, build config |
+
+**Feature signals:**
+- Auth context/store + login pages → Authentication doc
+- Form components + validation → Forms doc
+- Data tables with pagination → Data Display doc
+- Charts/dashboards → Analytics doc
+- Theming/i18n files → Theming / Internationalization doc
+- File upload components → Media Management doc
+
+---
+
+### Full-Stack Framework
+
+**Signals:** Next.js, Nuxt, SvelteKit, Remix, RedwoodJS, Blitz, Astro (SSR)
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/app/**/page.*`, `**/pages/**`, `**/routes/**` | UI pages AND API routes — the router is the architecture |
+| 2 | `**/api/**`, `**/server/**`, `**/actions/**` | Server-side logic, server actions |
+| 3 | `**/models/**`, `**/schema*`, `**/prisma/**`, `**/drizzle/**` | Data layer, ORM config |
+| 4 | `**/middleware.*`, `**/middleware/**` | Request pipeline, auth, redirects |
+| 5 | `**/components/**` (skim top-level) | Shared UI components |
+| 6 | `**/lib/**`, `**/utils/**`, `**/services/**` | Shared server + client utilities |
+| 7 | `**/config/**`, `.env*`, `next.config.*`, `nuxt.config.*` | Framework and environment config |
+
+**Feature signals:**
+- All Web API signals + all Frontend SPA signals
+- Server actions / mutations → Data Mutation doc
+- ISR/SSG configuration → Rendering Strategy doc
+- Edge functions / middleware → Edge Computing doc
+
+---
+
+### CLI Tool
+
+**Signals:** Commander, Yargs, Click, Typer, Cobra, Clap, oclif, Argparse
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/commands/**`, `**/cmd/**`, `**/cli.*` | Command tree, subcommands |
+| 2 | Main entry (`bin/*`, `src/index.*`, `src/main.*`) | Argument parsing, top-level flow |
+| 3 | `**/config*`, `**/*rc*`, `**/settings*` | Config file formats, defaults |
+| 4 | `**/utils/**`, `**/lib/**`, `**/core/**` | Core logic behind commands |
+| 5 | `**/output*`, `**/format*`, `**/display*` | Output formatting (JSON, table, etc.) |
+| 6 | `**/templates/**`, `**/scaffolds/**` | Code generation templates |
+
+**Feature signals:**
+- Multiple subcommands → one doc per command group
+- Config file handling → Configuration doc
+- Plugin/extension system → Plugin Architecture doc
+- Interactive prompts → User Interaction doc
+- File I/O operations → File Processing doc
+
+---
+
+### Library / SDK
+
+**Signals:** Published package with `main`/`exports` in package.json, `lib/` with clear public API, type declarations
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | Main export (`src/index.*`, `lib/index.*`, `__init__.py`) | Public API surface |
+| 2 | `**/*.d.ts`, `**/types.*`, `**/interfaces.*` | Type contracts, input/output shapes |
+| 3 | `**/core/**`, `**/lib/**` | Internal implementation |
+| 4 | `**/utils/**`, `**/helpers/**` | Supporting utilities |
+| 5 | `**/examples/**`, `**/demo/**` | Usage patterns |
+| 6 | `**/plugins/**`, `**/adapters/**`, `**/providers/**` | Extension points |
+| 7 | `**/tests/**` (skim 2-3) | Edge cases, expected behavior |
+
+**Feature signals:**
+- Multiple exported classes/functions → Core API doc
+- Plugin/adapter pattern → Extension Architecture doc
+- Multiple output formats → Serialization doc
+- Caching layer → Performance doc
+
+---
+
+### Mobile App
+
+**Signals:** React Native, Flutter, SwiftUI, Jetpack Compose, Expo, Ionic, Capacitor
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/screens/**`, `**/pages/**`, `**/views/**` | Screen tree, navigation structure |
+| 2 | `**/navigation/**`, `**/router*` | Navigation graph, deep linking |
+| 3 | `**/store/**`, `**/state/**`, `**/providers/**` | State management, data flow |
+| 4 | `**/api/**`, `**/services/**`, `**/network/**` | Backend communication, offline sync |
+| 5 | `**/components/**` (skim) | Shared UI components |
+| 6 | `**/native/**`, `**/platform/**`, `**/ios/**`, `**/android/**` | Platform-specific code, native modules |
+| 7 | `**/assets/**` (list only) | Bundled resources |
+
+**Feature signals:**
+- Push notification setup → Notifications doc
+- Camera/media access → Media Capture doc
+- Offline storage (SQLite, Realm, AsyncStorage) → Data Persistence doc
+- Deep linking / universal links → Navigation doc
+- Platform-specific native modules → Platform Integration doc
+
+---
+
+### Data Pipeline / ML
+
+**Signals:** Airflow, dbt, Prefect, Dagster, Luigi, Pandas, Spark, TensorFlow, PyTorch, scikit-learn, Jupyter notebooks
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/dags/**`, `**/pipelines/**`, `**/flows/**`, `**/workflows/**` | Pipeline definitions, DAGs, task graph |
+| 2 | `**/models/**` (ML or dbt) | Model definitions, training logic or SQL transforms |
+| 3 | `**/sources/**`, `**/extractors/**`, `**/connectors/**` | Data sources, ingestion logic |
+| 4 | `**/transforms/**`, `**/processors/**` | Data transformation logic |
+| 5 | `**/schemas/**`, `**/contracts/**` | Data contracts, validation |
+| 6 | `**/notebooks/**`, `*.ipynb` | Exploratory analysis, experiments |
+| 7 | `**/config/**`, `**/profiles*` | Connection strings, environment config |
+
+**Feature signals:**
+- Multiple DAGs/pipelines → one doc per pipeline
+- ML model training → Model Training doc
+- Feature engineering → Feature Store doc
+- Data validation (Great Expectations, Pandera) → Data Quality doc
+- Scheduled runs → Orchestration doc
+
+---
+
+### Monorepo
+
+**Signals:** Turborepo, Nx, Lerna, Rush, Bazel, pnpm workspaces — has `packages/`, `apps/`, or `workspace` config
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | Root config (`turbo.json`, `nx.json`, `lerna.json`, `pnpm-workspace.yaml`) | Workspace structure, build pipeline |
+| 2 | `packages/*/package.json` or `apps/*/package.json` | All packages/apps and their dependencies |
+| 3 | `**/shared/**`, `**/common/**`, `**/core/**` | Shared packages that others depend on |
+| 4 | Each app/package entry point (skim) | Purpose of each workspace member |
+
+**Then apply the matching sub-archetype playbook** to each significant package/app (e.g., Web API for the backend, Frontend SPA for the frontend, Library for shared packages).
+
+**Feature signals:**
+- Shared packages → Shared Infrastructure doc
+- Build/deploy pipeline → Build System doc
+- Inter-package dependencies → Architecture Overview doc (dependency graph)
+
+---
+
+### Microservices
+
+**Signals:** Docker Compose, Kubernetes manifests, multiple services with separate entry points, API gateway, service mesh
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `docker-compose*`, `**/k8s/**`, `**/helm/**`, `**/terraform/**` | Service topology, infrastructure |
+| 2 | API gateway config, `**/gateway/**` | Routing, load balancing, auth gateway |
+| 3 | Each service's entry point and routes (skim) | Service responsibilities, API surface |
+| 4 | `**/proto/**`, `**/graphql/**`, `**/schemas/**` | Inter-service contracts (gRPC, GraphQL) |
+| 5 | `**/queues/**`, `**/events/**`, `**/messaging/**` | Async communication, event bus |
+| 6 | `**/shared/**`, `**/common/**` | Shared libraries across services |
+
+**Then apply the Web API playbook** to each significant service.
+
+**Feature signals:**
+- Service discovery → Service Mesh doc
+- Event-driven communication → Event Architecture doc
+- Shared vs per-service database → Data Architecture doc
+- Health checks / circuit breakers → Resilience doc
+
+---
+
+### Infrastructure / IaC
+
+**Signals:** Terraform, Pulumi, CloudFormation, Ansible, CDK, Serverless Framework
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/main.tf`, `**/stacks/**`, `**/lib/**` (CDK) | Resource definitions, stack structure |
+| 2 | `**/variables*`, `**/inputs*`, `**/config*` | Parameterization, environment configs |
+| 3 | `**/modules/**`, `**/constructs/**` | Reusable infrastructure modules |
+| 4 | `**/environments/**`, `**/stages/**` | Environment-specific overrides |
+| 5 | `**/outputs*`, `**/exports*` | Cross-stack references |
+| 6 | CI/CD config (`.github/workflows/`, `Jenkinsfile`) | Deployment pipeline |
+
+**Feature signals:**
+- Networking (VPC, subnets, security groups) → Networking doc
+- Compute (ECS, Lambda, EC2) → Compute Architecture doc
+- Data stores (RDS, DynamoDB, S3) → Data Infrastructure doc
+- CI/CD pipeline → Deployment Pipeline doc
+- Monitoring (CloudWatch, Datadog) → Observability doc
+
+---
+
+## Fallback — Unknown Archetype
+
+If the project doesn't clearly match any archetype:
+
+1. List the root directory and `src/` (or equivalent)
+2. Read the top 5 largest files by line count
+3. Read any files with "main", "app", "server", "index", or "core" in the name
+4. Check test files — they reveal what developers think is important
+5. Check CI/CD config (`.github/workflows/`, `Jenkinsfile`) — pipeline steps reveal build/deploy architecture
+
+Then propose an archetype to the user: *"This looks like a [X] project. I'll explore it using the [X] playbook. Sound right?"*

package/skills/agents/references/init-workflow.md

@@ -0,0 +1,123 @@
+# Init Workflow
+
+## Step 1 — Explore
+
+Follow the two-phase exploration strategy in `references/exploration-strategies.md`:
+
+**Phase 1 — Fingerprint** (3-5 file reads max)
+Read package/config files and directory structure to identify the project's language, framework, and archetype (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+
+**Phase 2 — Targeted Exploration** (archetype-specific)
+Apply the matching archetype playbook from `references/exploration-strategies.md`. Read files in priority order using the glob patterns listed. Identify feature signals — each signal maps to a documentable feature.
+
+If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+
+Do not skim. Understand how the system actually works before proposing docs.
+
+**Important:** Use your built-in file-reading tools to explore. Do NOT create scanner scripts, shell scripts, or any tooling. vdoc is purely AI-driven — no scripts, no build steps, no infrastructure.
+
+**Phase 3 — Write Exploration Log**
+After exploring, write `vdocs/_exploration_log.md` documenting what you found:
+
+```markdown
+# Exploration Log
+
+## Fingerprint
+- **Language(s):** e.g., TypeScript, Python
+- **Framework(s):** e.g., Next.js 14, FastAPI
+- **Archetype(s):** e.g., Full-stack Framework
+- **Scope:** e.g., ~85 files, medium
+
+## Files Read
+| # | File | Why | What I Found |
+|---|------|-----|--------------|
+| 1 | package.json | Fingerprint | Next.js 14, Prisma, NextAuth |
+| 2 | src/app/ (listing) | Page tree | 12 routes, 3 API routes |
+| ... | ... | ... | ... |
+
+## Feature Signals Detected
+| Signal | Source File(s) | Proposed Doc |
+|--------|---------------|--------------|
+| Auth middleware + login page | middleware.ts, app/login/page.tsx | AUTHENTICATION_DOC.md |
+| Prisma schema with 8 models | prisma/schema.prisma | DATA_MODEL_DOC.md |
+| ... | ... | ... |
+
+## Ambiguities / Open Questions
+- Could not determine why Redis is in dependencies — no usage found. Ask user.
+- Payments folder exists but appears incomplete / WIP.
+```
+
+This log is your working memory. It feeds directly into Step 2 (Plan).
+
+## Step 2 — Plan
+
+Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
+
+```markdown
+# Documentation Plan
+
+## Proposed Documents
+
+1. **PROJECT_OVERVIEW_DOC.md** — Tech stack, architecture, project structure, dev setup
+2. **AUTHENTICATION_DOC.md** — OAuth2 flow, JWT lifecycle, session management, RBAC
+3. **API_REFERENCE_DOC.md** — All endpoints, request/response shapes, error codes
+...
+
+## Notes
+- Each doc covers one logical feature, not one file
+- Docs should be useful for onboarding AND as AI context for planning changes
+```
+
+Present the plan to the user. Actively suggest changes:
+- "Should I merge X and Y into one doc?"
+- "I found a websocket system — want that documented separately?"
+- "Any internal/legacy systems I should skip?"
+
+Wait for user approval before proceeding.
+
+## Step 3 — Generate
+
+For each approved doc:
+
+1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
+2. Follow the template in `.agents/vdoc/doc-template.md` exactly
+3. Write to `vdocs/FEATURE_NAME_DOC.md`
+
+**Writing rules:**
+
+- **Mermaid diagrams are mandatory** in "How It Works". Show the actual flow — request lifecycle, state transitions, data pipeline. If a flow has more than 7-9 nodes, split into multiple diagrams.
+- **Data Model** must show real entities from the code, not generic placeholders. Use mermaid ER diagrams for relational data, tables for simpler models.
+- **Constraints & Decisions** is the most valuable section. Dig into the code for non-obvious choices: "Uses polling instead of websockets because...", "Auth tokens expire in 15min because...". If you can't find the reason, state the constraint and mark it: `Reason: unknown — verify with team`.
+- **Related Features** must reference other docs by filename and explain the coupling: "Changes to the JWT schema will require updates to API_REFERENCE_DOC.md (auth middleware affects all endpoints)."
+- **Configuration** must list actual env vars/secrets from the code, not hypothetical ones.
+- **Error Handling** — trace what happens when things fail. What does the user see? What gets logged? Is there retry logic?
+
+## Step 4 — Manifest
+
+Create `vdocs/_manifest.json` using the schema in `.agents/vdoc/manifest-schema.json`.
+
+The `description` field is critical — write it rich enough that you can route any user question to the right doc by matching against descriptions. Include specific technology names, patterns, and concepts.
+
+Example:
+
+```json
+{
+  "filepath": "AUTHENTICATION_DOC.md",
+  "title": "Authentication - OAuth2 & JWT",
+  "version": "1.0.0",
+  "description": "OAuth2 flow with Google/GitHub providers, JWT token lifecycle, session management via NextAuth.js, route protection middleware, and role-based access control.",
+  "tags": ["oauth2", "jwt", "session-management", "rbac"]
+}
+```
+
+## Step 5 — Self-Review
+
+Before finishing, verify:
+
+- [ ] Every doc has at least one mermaid diagram in "How It Works"
+- [ ] Every doc has at least 2 entries in "Constraints & Decisions"
+- [ ] Every doc's "Key Files" lists real paths that exist in the codebase
+- [ ] Every doc's "Configuration" lists actual env vars from the code
+- [ ] Every doc's "Related Features" references other doc filenames
+- [ ] Manifest `description` is detailed enough for semantic routing
+- [ ] No doc is just a shallow restatement of file names — each explains WHY and HOW

package/skills/agents/references/manifest-schema.json

@@ -0,0 +1,16 @@
+{
+  "project": "<project-name>",
+  "vdoc_version": "3.0.0",
+  "created_at": "<ISO-8601>",
+  "last_updated": "<ISO-8601>",
+  "last_commit": "<short-sha>",
+  "documentation": [
+    {
+      "filepath": "FEATURE_NAME_DOC.md",
+      "title": "Human-Readable Feature Title",
+      "version": "1.0.0",
+      "description": "Rich semantic description with specific technology names, patterns, and concepts. Detailed enough that an AI can route any user question to this doc by matching against this field.",
+      "tags": ["keyword-1", "keyword-2"]
+    }
+  ]
+}

package/skills/claude/SKILL.md

@@ -1,55 +1,28 @@
 ---
 name: vdoc
-description: "Use when user says /vdoc, 'document this project', 'audit docs', or asks questions about codebase documentation. Generates feature-centric docs in vdocs/ with semantic manifest for AI routing."
-argument-hint: "[init|audit] or ask any documentation question"
-user-invocable: true
-allowed-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
+description: "Query existing project documentation. Use when user asks questions about the codebase and vdocs/ exists. For generating docs use /vdoc-init, for auditing use /vdoc-audit."
 ---
 
-# vdoc — Documentation Generator
+# vdoc — Documentation Query
 
-Three modes: **init**, **audit**, **query**. All docs live in `vdocs/`. Manifest at `vdocs/_manifest.json` is the semantic index.
+Answer questions about the codebase using existing documentation in `vdocs/`.
 
-## Init (`/vdoc init`)
+## Other Commands
 
-Generate feature-centric documentation from source code.
+- **`/vdoc-init`** — Generate documentation from source code (explore → plan → generate)
+- **`/vdoc-audit`** — Audit docs for stale, missing, or dead entries
 
-**Workflow:** Explore → Plan → Generate → Manifest → Self-review
-
-For detailed steps, read [references/init-workflow.md](references/init-workflow.md).
-
-**Key rules:**
-- Follow the template in [references/doc-template.md](references/doc-template.md) exactly
-- Manifest schema in [references/manifest-schema.json](references/manifest-schema.json)
-- Never generate without user-approved plan
-- Mermaid diagrams mandatory (max 7-9 nodes)
-- Only document what exists in code
-
-## Audit (`/vdoc audit`)
-
-Detect stale, missing, and dead documentation. Report and patch.
-
-**Workflow:** Read manifest → Detect stale → Detect gaps → Detect dead → Check cross-refs → Report → Patch
-
-For detailed steps, read [references/audit-workflow.md](references/audit-workflow.md).
-
-## Query (any documentation question)
+## How to Answer Questions
 
 1. Read `vdocs/_manifest.json`
-2. Match question against `description` and `tags` fields
-3. Read matching doc(s)
+2. Match the question against `description` and `tags` fields
+3. Read matching doc(s) from `vdocs/`
 4. Answer from documented knowledge
-5. If no match, suggest running `/vdoc audit`
-
-## Naming Convention
-
-Files: `FEATURE_NAME_DOC.md` — uppercase, feature-named, `_DOC` suffix.
+5. If no match or no `vdocs/` folder, suggest running `/vdoc-init`
+6. If docs seem outdated, suggest running `/vdoc-audit`
 
 ## Rules
 
-1. **Feature-centric, not file-centric.** One doc per logical feature, not per source file.
-2. **Mermaid over prose.** Diagram flows. Max 7-9 nodes per diagram.
-3. **Constraints are gold.** Always fill "Constraints & Decisions" — prevents breaking changes.
-4. **Rich manifest descriptions.** Pack with specific terms for semantic routing.
-5. **No hallucination.** Only document what exists in code.
-6. **Plan first, always.** Never generate without user-approved plan. Report before patching.
+- Only answer from what's documented — do not hallucinate
+- Reference specific doc filenames in your answers
+- If the question spans multiple docs, read all relevant ones