Appearance

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 ​

CapabilityInvocation / Entry PointScoping InstructionSupporting SkillOutput Artifact
Spec from CodeExplicit prompt / agentDomain instructionsspec-from-codedocs/specs/*.md (OpenAPI, DB schemas, async jobs)
VitePress Docs Site/vitepress-docsvitepress-docsvitepress-docs-examplesFull VitePress site (website/docs/, Docker, CI)

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:
    1. Inspects route definitions, controller parameters, middleware validation schemas, and database entity models.
    2. Extracts public endpoints, HTTP methods, headers, payload schemas, query parameters, response structures, and error codes.
    3. Formulates technical specifications conforming to the skills/spec-from-code/references/spec-contract.md contract.
    4. 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-docs-examples to supply pre-configured scaffolding assets:
    • package.json with pinned VitePress, Mermaid, and Markdown plugins.
    • .vitepress/config.mjs pre-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 build generates static HTML with 0 errors.
    • ./scripts/start-dev.sh runs cleanly in Docker.
    • All pages and mermaid diagrams render cleanly in dark and light themes.

Published and maintained by ALTEN