Specs & Docs
The Specs & Docs domain provides automated capabilities to reverse-engineer technical specifications from existing source code and scaffold enterprise-grade product documentation websites.
TIP
For turning forward-looking business requirements and user stories into structured specifications, see the dedicated Think & Plan domain.
Domain Architecture
1. Reverse-Engineering Specifications (spec-from-code)
2. Documentation Website Pipeline
Capabilities Matrix
| Capability | Invocation / Entry Point | Scoping Instruction | Supporting Skill | Output Artifact |
|---|---|---|---|---|
| Spec from Code | Explicit prompt / agent | Domain instructions | spec-from-code | docs/specs/*.md (OpenAPI, DB schemas, async jobs) |
| VitePress Docs Site | /vitepress-docs | — | vitepress-docs | Full VitePress site (website/docs/, Docker, CI) |
| Product Demo Videos | /demo-videos | — | playwright-demo-videos | <docs-root>/docs/public/videos/<name>.mp4 + .jpg poster |
Capability Workflows
1. Reverse-Engineering Specifications: Spec from Code
- When to Run: Documenting legacy codebases, standardizing undocumented microservices, or preparing API catalogs.
- Agent:
Spec from Code(spec-from-code.agent.md) - Execution Methodology:
- Inspects route definitions, controller parameters, middleware validation schemas, and database entity models.
- Extracts public endpoints, HTTP methods, headers, payload schemas, query parameters, response structures, and error codes.
- Formulates technical specifications conforming to the
skills/spec-from-code/references/spec-contract.mdcontract. - Documents database tables, columns, indexes, foreign keys, triggers, and soft-delete policies.
- Falsifiable Done When:
- All public interfaces are documented without omissions.
- The specification passes automated validation via the skill script:bash
node .agents/skills/spec-from-code/scripts/spec-docs.mjs --dir docs/specs
2. Product Documentation Website: VitePress Docs
- When to Run: Launching or upgrading a product documentation site for an open-source library, microservice catalog, or company platform.
- Trigger:
/vitepress-docs [docs-root] - Agent:
VitePress Docs(vitepress-docs.agent.md) - Scaffolding Bundle: Uses
skills/vitepress-docsto supply site standards and pre-configured scaffolding assets:package.jsonwith pinned VitePress, Mermaid, and Markdown plugins..vitepress/config.mjspre-configured with theme settings, responsive SVG logo/favicon, Mermaid optimization, and dynamic base URL resolution for GitHub Pages / local dev.- Multi-service Docker Compose files (
scripts/start-dev.sh,scripts/stop-dev.sh,docker/docker-compose.yml) enabling hot-reloaded local editing on port 5174 without local Node.js dependencies. - GitHub Actions deployment workflow (
.github/workflows/deploy-docs.yml) with zero-downtime GitHub Pages deployment.
- Falsifiable Done When:
npm run buildgenerates static HTML with 0 errors../scripts/start-dev.shruns cleanly in Docker.- All pages and mermaid diagrams render cleanly in dark and light themes.
3. Product Demo Videos: Demo Videos
- When to Run: Showing a product's key user journeys (sign-in, editing, table settings) on its website or in a release note.
- Trigger:
/demo-videos [journeys] [output-dir] - Agent:
Demo Videos(demo-videos.agent.md) - Scaffolding Bundle: Uses
skills/playwright-demo-videos:- A dedicated
demos/playwright.config.tsrecording every scenario at a fixed 1440×900. - A
Directorinjecting a visible cursor with click rings, moving and typing at human speed, and marking the edit point that cuts login and setup. - Scenario templates resetting their data off camera, so a video can be filmed again on the same database.
to-mp4.mjsencoding H.264 MP4 + JPG poster with ffmpeg into the output folder, and a VitePress home section playing each video only while visible.
- A dedicated
- Falsifiable Done When:
- Each scenario passes twice in a row against the local dev stack.
- Each journey has a reviewed MP4 and poster in the output folder.