Techdocs

techdocs — Technical Architecture Documentation

CodeOps Skills Version: 3.20.0

Create and maintain a living, VitePress-compatible technical architecture documentation set in the project's docs/ directory, capturing accumulated design knowledge across requirements and planning phases. The body branches by phrasing and arguments:

What this is (and is NOT)

Product documentation is a separate concern. If the project needs user-facing docs, the user should request them explicitly. They live elsewhere (e.g. docs/product/) and are NOT governed by this skill.

Opt-in, then auto-update

Technical documentation is not mandatory by default, but once opted in it is automatically maintained.

The opt-in marker

The presence of docs/index.md with this frontmatter marker means techdocs are active:

---
techdocs: true
---

If docs/index.md exists but lacks this marker, it is NOT a techdocs-managed file — do not auto-update it.

Detection & ask-once protocol

When this skill fires as an auto-update hook (from the exec_plan or make_requirements skills):

1. Does docs/index.md exist with the techdocs: true marker?
   • Yes → run the appropriate auto-update (incremental or comprehensive — see the mode table).
   • No → ask the user once: "Would you like to create technical architecture docs for this project?"
     • Yes → run the create flow (Phases 1–6).
     • No → skip, and do not ask again until the next plan completes.

Auto-update triggers

Once opted in, update techdocs at these checkpoints:

Incremental = quick pass; add new ADRs, update changed sections only. Comprehensive = full pass; review every section against actual codebase state.

🚨 Design Intent Preservation is non-negotiable. Auto-updates MUST NOT silently overwrite documented design intent (ADR decisions) with observed code behavior. The full rule, including the divergence-flagging protocol, lives in authoring-and-update.md — read it before any comprehensive update.

Relationship to other skills

Phase overview

Phase 1 — Information gathering

Gather from: existing requirements/, existing plans/*/, the current codebase (structure, patterns, dependencies), and the project's CLAUDE.md (or detected project conventions). In a nested-layout repo these sources live under codeops/features/<f>/{requirements,plans}/ (resolve via ../../_shared/layout-convention.md); in flat layout they are the top-level requirements/ and plans/*/ as before. If this skill runs right after make_requirements or exec_plan, most of this is already in context.

Ask clarifying questions only on a true first run with no requirements/plans: system purpose, key stakeholders and their experience level, architecture style (monolith / microservices / serverless / hybrid), key integrations, deployment model. If requirements/plans exist, extract these from the documents — do not re-ask.

Phase 2 — Document structure

Create only the sections relevant to the project type — empty placeholders add noise, not value. Full VitePress directory layout:

docs/
├── .vitepress/
│   └── config.ts                # VitePress configuration
├── index.md                     # System overview + techdocs opt-in marker (ENTRY POINT)
├── architecture/
│   ├── system-overview.md       # High-level architecture, component diagram
│   ├── data-model.md            # Domain model, entity relationships, schemas
│   ├── api-design.md            # API contracts, endpoints, protocols
│   ├── infrastructure.md        # Deployment, Docker, CI/CD, networking
│   └── security.md              # Security architecture, threat model
├── decisions/
│   ├── index.md                 # ADR log (chronological)
│   ├── ADR-001-[short-name].md  # Individual decision records
│   └── ...
├── guides/
│   ├── getting-started.md       # Developer setup, prerequisites, first run
│   ├── development.md           # Dev workflow, coding patterns, conventions
│   └── deployment.md            # How to deploy, environments, configuration
└── reference/
    ├── configuration.md         # Config options, env vars, feature flags
    └── integrations.md          # External system connections, protocols, auth

Adapting to project type (create required sections; add optional ones as warranted):

Then proceed to Phase 3 (vitepress-setup.md) and Phase 4 (templates.md).

review_techdocs (health check)

When the user asks for review_techdocs, run the read-only 7-dimension health check (staleness, completeness, accuracy, ADR coverage, link health, diagram accuracy, getting-started) and produce a diagnostic report. It changes no files. The full check table and report template are in authoring-and-update.md.

Session resume

Techdocs authoring can be lengthy. If you need to stop mid-run, save all completed documents to docs/, record which sections remain in docs/_draft/techdocs-progress.md, and tell the user to resume with make_techdocs --continue. On --continue, read docs/_draft/techdocs-progress.md, read the existing completed documents, and continue from the next section. (Claude Code auto-compacts context — no manual threshold handling is needed.)

Conventions

• Follow your project's coding standards and your project's testing standards (the project's CLAUDE.md, or detected project conventions) when documenting development and testing guides.
• Document security architecture against your project's security coding standards (CLAUDE.md).
• When new pages are added (ADRs, sections), update .vitepress/config.ts sidebar — see vitepress-setup.md.
• Related skills: make_requirements, make_plan, exec_plan, retro_requirements.

Reference files

• templates.md — all VitePress file templates (index, architecture/, ADR log + ADR template, guides/, reference/*). Read when writing any document in Phase 4.
• vitepress-setup.md — Phase 3 install, config.ts, npm scripts, .gitignore, and sidebar auto-update. Read when scaffolding VitePress or adding pages.
• authoring-and-update.md — Phase 5 authoring guidelines + Mermaid types, Phase 6 incremental/comprehensive update protocol with the Design Intent Preservation rule, and the review_techdocs health check. Read before authoring, before any auto-update, and for review_techdocs.