@mrciphersmith/keryx 0.2.9

package/src/gdskills/bundled/skills/planning/autodoc-assembler/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: autodoc-assembler
+description: >
+  Phase 5 subagent for autodoc-orchestrator. Assembles all documentation sections
+  into a cohesive package: main README.md and navigation index.
+  Use when: dispatched by autodoc-orchestrator Phase 5.
+  NOT for: direct user invocation.
+version: 1.0.0
+---
+
+# autodoc-assembler
+
+## Purpose
+
+Produce the final documentation entry point. Read all generated sections,
+verify cross-references, write the main README and navigation index.
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | Read ALL docs/*.md before writing — no section may be skipped |
+| 2 | README.md must be self-contained enough to orient a new developer |
+| 3 | All cross-links between docs must use relative paths |
+| 4 | Do NOT repeat content from sections — summarize and link |
+
+---
+
+## Input Contract
+
+```yaml
+docs_sections: ".metaproject/jobs/<job>/docs/*.md"   # all generated sections
+project_map: ".metaproject/jobs/<job>/artifacts/project-map.md"
+architecture: ".metaproject/jobs/<job>/artifacts/architecture.md"
+JOB_DIR: "<job directory>"
+PROJECT_DIR: "<project path>"
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "DONE_WITH_CONCERNS"
+summary: "<2-3 sentences: what's in the final package, any gaps>"
+concerns: ["<missing info, broken cross-refs, TODO items left by writers>"]
+artifact_path: ".metaproject/jobs/<job>/docs/README.md"
+```
+
+---
+
+## Workflow
+
+### Step 1: Inventory All Sections
+
+Read each `docs/*.md` file. Note:
+- What sections were successfully written
+- Any `[TODO: ...]` markers left by writers (collect into concerns)
+- Missing sections that were expected but not generated
+
+### Step 2: Write docs/README.md
+
+```markdown
+# <Project Name>
+
+> <one-line description from project-map>
+
+## Overview
+<2-3 paragraphs: what the project is, who it's for, main capabilities>
+
+## Architecture
+<3-5 bullet summary of architectural style and key components>
+→ Full details: [Architecture](architecture.md)
+
+## Quick Start
+<condensed 4-step setup: clone → install → configure → run>
+→ Full guide: [Onboarding](onboarding.md)
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](onboarding.md) | Setup, local dev, common tasks |
+| [Architecture](architecture.md) | System design, components, data flow |
+| [Module Reference](modules.md) | Per-module breakdown |
+| [API Reference](api-reference.md) | Endpoint documentation |
+| [Data Models](data-models.md) | Schemas and database structure |
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+<from project-map>
+
+## Generated By
+This documentation was generated automatically by [autodoc](https://github.com/MrCipherSmith/keryx).
+Generated: <date>
+```
+
+### Step 3: Write docs/index.md
+
+```markdown
+# Documentation Index
+
+## <Project Name> — Documentation
+
+Generated: <date> | Source: `<project path>`
+
+### Contents
+
+- **[README](README.md)** — Project overview and quick start
+- **[Getting Started](onboarding.md)** — Full setup guide
+- **[Architecture](architecture.md)** — System design
+- **[Module Reference](modules.md)** — Module-by-module breakdown
+- **[API Reference](api-reference.md)** — REST/gRPC/GraphQL endpoints
+- **[Data Models](data-models.md)** — Database schemas
+
+### Modules Documented
+<list of modules from analysis>
+
+### Coverage Notes
+<any TODOs or gaps noted during generation>
+```
+
+### Step 4: Return Summary
+
+In the response summary, include:
+- Total sections generated
+- Any TODO items that need human review
+- Suggested next steps (e.g., "API reference has 3 endpoints marked TODO: add description")

package/src/gdskills/bundled/skills/planning/autodoc-orchestrator/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: autodoc-orchestrator
+description: >
+  Autonomous reverse-engineering documentation pipeline — scans an existing codebase
+  and produces comprehensive developer documentation without user involvement after initial setup.
+  Use when: "autodoc", "generate docs for my project", "document this codebase",
+  "reverse engineer documentation", "create project documentation from code",
+  "сгенерируй документацию проекта", "задокументируй кодовую базу",
+  "автодок", "autodoc".
+  Trigger on: user provides a repo path, asks to document existing code, wants
+  onboarding docs, API reference, or architecture overview generated automatically.
+  NOT for: writing new PRDs or planning new features (use gproject-orchestrator).
+version: 1.0.0
+---
+
+<!-- SUBAGENT-STOP: If you are a subagent dispatched by another orchestrator, HALT.
+     Return STATUS: BLOCKED — autodoc-orchestrator must run as top-level agent only. -->
+
+# autodoc-orchestrator
+
+## Purpose
+
+Thin orchestrator that drives a 5-phase autonomous documentation pipeline.
+Takes an existing codebase as input, dispatches specialized subagents to scan,
+analyze, and write documentation, and produces a complete documentation package
+with no human gates.
+
+---
+
+## Execution metrics (opt-in)
+
+When a USER runs this orchestrator directly (not as a dispatched subagent), at
+the start ask "Collect execution statistics for this run? (yes/no)" per
+`.metaproject/rules/core/execution-metrics.md`. If yes, append the
+`## Execution Metrics` section at the end and save it under the run's artifact
+dir (`.metaproject/data/gdwiki/metrics/` or the docs output dir). Never ask or
+emit it when dispatched as a subagent.
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | Orchestrator NEVER reads or summarizes code itself — only subagents do |
+| 2 | Orchestrator NEVER writes documentation content — only subagents do |
+| 3 | Every phase MUST produce artifact files before proceeding |
+| 4 | Phase 2 analysts run in PARALLEL — one per detected module/domain |
+| 5 | Phase 4 writers run in PARALLEL — one per documentation section |
+| 6 | Subagents receive ONLY artifacts listed in their dispatch contract |
+| 7 | If a subagent returns NEEDS_CONTEXT, resolve autonomously before re-dispatching |
+
+---
+
+## Pipeline Overview
+
+```
+Phase 0  Interview (if needed)      → collect project path + focus areas
+Phase 1  autodoc-scanner            → artifacts/project-map.md
+Phase 2  autodoc-analyst × N        → artifacts/analysis/<module>.md  [parallel]
+Phase 3  autodoc-architect          → artifacts/architecture.md
+Phase 4  autodoc-writer × N         → docs/<section>.md               [parallel]
+Phase 5  autodoc-assembler          → docs/README.md + docs/index.md
+```
+
+---
+
+## Phase 0: Initialization
+
+### Job Directory Setup
+
+1. Create `jobs/autodoc-<slugified-project-name>/`
+2. Create subdirectories: `artifacts/`, `artifacts/analysis/`, `docs/`, `ai/`
+3. Initialize `state.json`
+
+### Input Assessment
+
+Evaluate what the user provided:
+
+```
+SUFFICIENT — proceed directly to Phase 1 if ALL of:
+  ✓ Project directory path (absolute) is provided
+  ✓ Path exists and contains code files
+
+NEEDS_INPUT — ask questions if ANY of:
+  ✗ No project path given
+  ✗ Multiple repos mentioned without clear scope
+  ✗ User specified unusual focus (e.g., "only the auth module")
+```
+
+### Interview (only when NEEDS_INPUT)
+
+Ask ONLY what is missing. Maximum 4 questions, always with options:
+
+```
+I need a few details to get started:
+
+1. Project path?
+   ○ Type the absolute path to the project root
+
+2. Which parts to document? (default: everything)
+   A) Full project — backend + frontend + shared
+   B) Backend only
+   C) Frontend only
+   D) Specific path — [type it]
+
+3. Output language?
+   A) English (default)
+   B) Russian
+   C) Both
+
+4. Existing docs to incorporate? (default: none)
+   ○ Path to existing docs/README, or skip
+```
+
+Save answers to `state.json.config`.
+
+---
+
+## Dispatch Protocol
+
+Every subagent dispatch follows this contract:
+
+```
+Agent({
+  description: "<phase>: <task>",
+  prompt: |
+    ## Your Role
+    You are <agent_role>. Load skill: skills/<skill-name>/SKILL.md
+
+    ## Task
+    <specific task>
+
+    ## Input Artifacts
+    <list of file paths to read>
+
+    ## Job Context
+    JOB_DIR: <absolute path to job directory>
+    PROJECT_DIR: <absolute path to project>
+    CONFIG: <from state.json.config>
+
+    ## Output Contract
+    1. Write artifact to: <output path>
+    2. Return ONLY:
+       STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT
+       summary: (3-5 sentences)
+       concerns: (if DONE_WITH_CONCERNS)
+       questions: (if NEEDS_CONTEXT — with A/B/C/D options)
+       next_phase_hints: (key findings for orchestrator routing)
+})
+```
+
+### Status Handling
+
+```
+STATUS: DONE
+  → Save summary to state.json.phase_summaries
+  → Proceed to next phase
+
+STATUS: DONE_WITH_CONCERNS
+  → Log concerns in state.json
+  → Proceed (documentation pipeline continues; concerns noted in final report)
+
+STATUS: NEEDS_CONTEXT
+  → IF resolvable autonomously (file exists, can be read):
+      → Dispatch context-collector or read file directly
+      → Re-dispatch subagent with answer
+  → IF requires user input:
+      → Ask user with A/B/C/D options
+      → Re-dispatch with answer
+  → Max 2 resolution rounds per phase
+```
+
+---
+
+## Phase 1: Project Scanning
+
+**Subagent**: `autodoc-scanner`
+**Input**: `PROJECT_DIR`, `CONFIG`
+**Output**: `artifacts/project-map.md`
+
+After completion, parse `next_phase_hints.modules[]` from the scanner's response.
+This list drives how many parallel analysts to launch in Phase 2.
+
+---
+
+## Phase 2: Deep Analysis (Parallel)
+
+**Subagent**: `autodoc-analyst` — one instance per module from project-map
+**Input**: `artifacts/project-map.md` + module path
+**Output**: `artifacts/analysis/<module-slug>.md`
+
+Launch ALL analysts simultaneously:
+```
+Agent × N in parallel, one per module:
+  module: frontend  → artifacts/analysis/frontend.md
+  module: backend   → artifacts/analysis/backend.md
+  module: shared    → artifacts/analysis/shared.md
+  ...
+```
+
+Wait for ALL to complete before Phase 3.
+
+---
+
+## Phase 3: Architecture Synthesis
+
+**Subagent**: `autodoc-architect`
+**Input**: `artifacts/project-map.md` + ALL `artifacts/analysis/*.md`
+**Output**: `artifacts/architecture.md`
+
+---
+
+## Phase 4: Documentation Writing (Parallel)
+
+**Subagent**: `autodoc-writer` — one instance per documentation section
+
+Determine sections from Phase 3 output and CONFIG. Standard sections:
+
+| Section | Output file | Always? |
+|---------|------------|---------|
+| Onboarding | `docs/onboarding.md` | Yes |
+| Architecture overview | `docs/architecture.md` | Yes |
+| Module reference | `docs/modules.md` | Yes |
+| API reference | `docs/api-reference.md` | Only if APIs detected |
+| Data models | `docs/data-models.md` | Only if schemas detected |
+
+Launch ALL writers simultaneously. Wait for ALL to complete.
+
+---
+
+## Phase 5: Assembly
+
+**Subagent**: `autodoc-assembler`
+**Input**: ALL `docs/*.md` + `artifacts/architecture.md` + `artifacts/project-map.md`
+**Output**: `docs/README.md` + `docs/index.md`
+
+The assembler creates the main entry-point document with links to all sections,
+a brief project overview, and a quick-start section.
+
+---
+
+## State Resumption
+
+Check for interrupted jobs on start:
+
+```
+IF jobs/autodoc-*/state.json exists AND status == "in_progress":
+  → Show: "Found interrupted autodoc job: <name> at Phase <N>"
+  → Ask: A) Resume  B) Start fresh  C) Show state
+```
+
+---
+
+## Output Structure
+
+```
+jobs/autodoc-<project>/
+├── state.json                    # Pipeline state
+├── artifacts/
+│   ├── project-map.md            # Phase 1
+│   └── analysis/                 # Phase 2
+│       ├── frontend.md
+│       ├── backend.md
+│       └── <module>.md
+├── docs/                         # Final documentation
+│   ├── README.md                 # Main entry point (Phase 5)
+│   ├── index.md                  # Navigation index (Phase 5)
+│   ├── onboarding.md             # Phase 4
+│   ├── architecture.md           # Phase 4
+│   ├── modules.md                # Phase 4
+│   ├── api-reference.md          # Phase 4 (if applicable)
+│   └── data-models.md            # Phase 4 (if applicable)
+└── ai/
+    └── context.md                # Internal context snapshot
+```
+
+---
+
+## Final Report
+
+After Phase 5, present to user:
+
+```
+autodoc complete for: <project name>
+
+Documentation generated:
+  ✓ docs/README.md         — main entry point
+  ✓ docs/onboarding.md     — setup + dev workflow
+  ✓ docs/architecture.md   — system architecture
+  ✓ docs/modules.md        — module reference
+  ✓ docs/api-reference.md  — API contracts
+  ✓ docs/data-models.md    — data schemas
+
+Modules analyzed: <N> (<list>)
+Concerns: <none | list>
+
+Full docs: jobs/autodoc-<name>/docs/
+```
+
+---
+
+## state.json Template
+
+```json
+{
+  "job_name": "autodoc-<slug>",
+  "created_at": "<ISO>",
+  "current_phase": 0,
+  "status": "in_progress",
+  "config": {
+    "project_dir": null,
+    "scope": "full",
+    "language": "en",
+    "existing_docs": null
+  },
+  "detected_modules": [],
+  "detected_sections": [],
+  "phase_summaries": {},
+  "concerns": [],
+  "history": []
+}
+```

package/src/gdskills/bundled/skills/planning/autodoc-scanner/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: autodoc-scanner
+description: >
+  Phase 1 subagent for autodoc-orchestrator. Scans project structure,
+  detects stack, identifies module boundaries, entry points, and dependencies.
+  Use when: dispatched by autodoc-orchestrator Phase 1.
+  NOT for: direct user invocation.
+version: 1.0.0
+---
+
+# autodoc-scanner
+
+## Purpose
+
+Produce a complete structural map of the project that downstream analysts
+and writers can rely on without re-scanning the codebase.
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | Scan file tree — do NOT read full file contents (use directory listings and targeted reads of package.json, tsconfig, Makefile, etc.) |
+| 2 | Detect module boundaries from directory structure and build config, not from code semantics |
+| 3 | Always list entry points (main files, index files, app bootstraps) |
+| 4 | Return module list in `next_phase_hints.modules[]` — orchestrator uses this to spawn analysts |
+
+---
+
+## Input Contract
+
+```yaml
+PROJECT_DIR: "<absolute path>"
+CONFIG:
+  scope: "full | backend | frontend | <custom path>"
+  language: "en | ru | both"
+  existing_docs: "<path or null>"
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "NEEDS_CONTEXT"
+summary: "<3-5 sentences: project type, module count, stack summary>"
+next_phase_hints:
+  modules:
+    - slug: "backend"
+      path: "<absolute path>"
+      type: "backend | frontend | shared | mobile | infra | other"
+      language: "TypeScript | Python | Go | ..."
+      framework: "NestJS | Express | React | ..."
+      entry_points: ["<file>"]
+    - slug: "frontend"
+      path: "<absolute path>"
+      ...
+  has_api: true | false
+  has_schemas: true | false
+  has_tests: true | false
+artifact_path: ".metaproject/jobs/<job>/artifacts/project-map.md"
+```
+
+---
+
+## Workflow
+
+### Step 1: Project Tree Scan
+
+Read top-level directory structure. Identify:
+- Build/package files: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `Makefile`
+- Workspace configs: `nx.json`, `turbo.json`, `lerna.json`, `pnpm-workspace.yaml`
+- Entry points: `main.*`, `index.*`, `app.*`, `server.*`, `cmd/`
+- Config files: `tsconfig.json`, `vite.config.*`, `webpack.config.*`, `docker-compose.yml`
+- Existing documentation: `README.md`, `docs/`, `CONTRIBUTING.md`
+
+### Step 2: Module Boundary Detection
+
+From the directory structure and workspace config, identify module boundaries:
+
+```
+Monorepo (nx/turbo/lerna) → each package/app is a module
+Single repo → detect by: apps/, packages/, src/modules/, src/features/
+Backend indicators: api/, server/, backend/, services/
+Frontend indicators: web/, client/, frontend/, ui/
+Shared/lib indicators: lib/, shared/, common/, packages/
+```
+
+For each detected module, read its `package.json` or equivalent to extract:
+- Name, description
+- Dependencies (framework detection)
+- Scripts (build, test, dev commands)
+
+### Step 3: Stack Detection
+
+For each module, determine:
+
+| Signal | Detected |
+|--------|---------|
+| `"next"` in deps | Next.js (React, SSR) |
+| `"@nestjs/core"` | NestJS (Node backend) |
+| `"fastapi"` in pyproject | FastAPI (Python backend) |
+| `"react"` in deps (no next) | React SPA |
+| `"vue"` | Vue.js |
+| `go.mod` exists | Go |
+| `Cargo.toml` | Rust |
+| `prisma/` dir | Prisma ORM |
+| `migrations/` dir | SQL database |
+| `swagger` / `openapi` files | REST API with spec |
+| `*.proto` files | gRPC |
+| `graphql/` or `*.graphql` | GraphQL |
+
+### Step 4: Entry Points
+
+For each module, find entry point files:
+- Node: `main.ts`, `index.ts`, `app.ts`, `server.ts`
+- Python: `main.py`, `app.py`, `__main__.py`
+- Go: `cmd/*/main.go`, `main.go`
+- Frontend: `main.tsx`, `_app.tsx`, `App.tsx`, `index.html`
+
+### Step 5: API + Schema Detection
+
+```
+has_api = true IF:
+  - `swagger.json` / `openapi.yaml` found
+  - `*.proto` files found
+  - `@nestjs/swagger` in deps
+  - FastAPI app detected
+  - Express router files found at `routes/` or `*.routes.ts`
+
+has_schemas = true IF:
+  - `prisma/schema.prisma` found
+  - `migrations/` directory found
+  - `models/` directory with *.py or *.ts files
+  - `*.graphql` schema files found
+```
+
+### Step 6: Write project-map.md
+
+```markdown
+# Project Map: <Project Name>
+
+## Overview
+- **Type**: monorepo | single-repo
+- **Modules**: <N>
+- **Languages**: <list>
+- **Has API**: yes | no
+- **Has DB schemas**: yes | no
+
+## Modules
+
+### <Module Name> (`<path>`)
+- **Type**: backend | frontend | shared
+- **Language**: <lang>
+- **Framework**: <framework + version>
+- **Entry point**: `<file>`
+- **Key dependencies**: <list>
+- **Build command**: `<cmd>`
+- **Dev command**: `<cmd>`
+
+## Project Structure (condensed)
+<top-2-level directory tree>
+
+## Existing Documentation
+<list of found docs, or "none">
+
+## Detected Integrations
+<databases, queues, external APIs, auth providers>
+```