opencode-codeops 1.4.0

package/skills/techdocs/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: techdocs
+description: >-
+  Creates and maintains VitePress-compatible technical architecture documentation and
+  architecture decision records (ADRs). Use when the user says "make_techdocs",
+  "review_techdocs", "techdocs", "document the architecture", "create architecture docs",
+  "write ADRs", or "architecture decision records". Covers two modes: make_techdocs to
+  create or comprehensively regenerate the docs/ set (system overview, data model, API
+  design, infrastructure, security, ADRs, developer guides, reference), and review_techdocs
+  to run a 7-dimension health check (staleness, completeness, accuracy, ADR coverage, link
+  health, diagram accuracy, getting-started) and produce a diagnostic report. Also fires
+  automatically as an incremental or comprehensive update when an exec-plan phase or plan
+  completes, or when make-requirements completes — but only if the project has opted in.
+  Scope is technical/architectural docs for developers, NOT product/end-user documentation.
+---
+
+# techdocs — Technical Architecture Documentation
+
+> **CodeOps Artifact Schema**: 1
+
+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:
+
+| Phrasing / argument | Mode | Action |
+|---|---|---|
+| `make_techdocs`, "document the architecture", "create architecture docs" | **Create / regenerate** | Phases 1–6: comprehensive create or full regeneration |
+| `make_techdocs --continue` | **Resume** | Pick up an interrupted authoring session (see Session resume) |
+| `review_techdocs`, "review the techdocs", "health check the docs" | **Health check** | 7-dimension diagnostic report (no file changes) |
+| *(auto)* exec-plan phase complete | **Incremental** | Add ADRs / update changed sections only |
+| *(auto)* exec-plan plan complete | **Comprehensive** | Full pass over every section vs. codebase |
+| *(auto)* make-requirements complete | **Incremental** | New design decisions → ADRs |
+
+## What this is (and is NOT)
+
+| In scope — TECHNICAL docs (this skill) | Out of scope — PRODUCT docs |
+|---|---|
+| Architecture, design decisions, data models, API contracts, infrastructure, security | End-user guides, tutorials, FAQ, release notes, marketing |
+| Developer onboarding, dev workflow, deployment procedures | Feature announcements, user-facing changelogs |
+
+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:
+
+```yaml
+---
+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:
+
+| Trigger (from another skill) | Update type | What to update |
+|---|---|---|
+| exec-plan **phase** completion | Incremental | New ADRs for decisions made; sections that changed |
+| exec-plan **plan** completion | Comprehensive | Full review of all sections; consistency; diagrams |
+| make-requirements completion | Incremental | New design decisions, updated scope, integration points |
+| Manual `make_techdocs` | Comprehensive | Full review and regeneration |
+
+**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](authoring-and-update.md) — read it before any comprehensive update.
+
+## Relationship to other skills
+
+| Skill | Relationship |
+|---|---|
+| the make-requirements skill | **Upstream.** Requirements define WHAT. Techdocs capture architectural decisions made during requirements discovery. On completion → incremental techdocs update. |
+| the make-plan skill | **Parallel.** Plans define HOW for one feature; techdocs capture SYSTEM-LEVEL architecture spanning features. make-plan reads techdocs as context. |
+| the exec-plan skill | **Downstream.** Architecture evolves during execution. Phase complete → incremental; plan complete → comprehensive. Auto-update hooks fire from it. |
+| the retro-requirements skill | **Upstream.** When reverse-engineering an existing system, techdocs capture the discovered architecture. |
+
+## Phase overview
+
+| Phase | What happens | Reference |
+|---|---|---|
+| **1. Information gathering** | Read `requirements/`, `plans/*/`, the codebase, the project's AGENTS.md (or detected conventions). Ask clarifying questions only on a first run with no requirements/plans. | below |
+| **2. Document structure** | Lay out the VitePress `docs/` tree; adapt sections to the project type (only create relevant sections). | below |
+| **3. VitePress setup** | Install VitePress, generate `.vitepress/config.ts`, add npm scripts, update `.gitignore`. | [vitepress-setup.md](vitepress-setup.md) |
+| **4. Document templates** | Write each section from the canonical templates. | [templates.md](templates.md) |
+| **5. Authoring guidelines** | Apply writing style, Mermaid diagram conventions, cross-referencing, and what NOT to document. | [authoring-and-update.md](authoring-and-update.md) |
+| **6. Incremental update protocol** | Auto-update after phase/plan/requirements completion, including Design Intent Preservation. | [authoring-and-update.md](authoring-and-update.md) |
+
+### Phase 1 — Information gathering
+
+Gather from: existing `requirements/`, existing `plans/*/`, the current codebase (structure,
+patterns, dependencies), and the project's AGENTS.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](../../_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):
+
+| Project type | Required | Optional |
+|---|---|---|
+| Web App / SaaS | All | — |
+| API / Backend | system-overview, data-model, api-design, security, infrastructure | — |
+| Library / SDK | system-overview, api-design, getting-started, development | data-model, infrastructure |
+| CLI Tool | system-overview, getting-started, development | data-model, infrastructure |
+| Microservices | All (esp. infrastructure, integrations) | — |
+| Mobile App | system-overview, data-model, api-design, security | infrastructure |
+| Infrastructure | system-overview, infrastructure, security, deployment | data-model, api-design |
+
+Then proceed to Phase 3 ([vitepress-setup.md](vitepress-setup.md)) and Phase 4
+([templates.md](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](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. (OpenCode
+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
+  AGENTS.md, or detected project conventions) when documenting development and testing guides.
+- Document security architecture against your project's security coding standards (AGENTS.md).
+- When new pages are added (ADRs, sections), update `.vitepress/config.ts` sidebar — see
+  [vitepress-setup.md](vitepress-setup.md).
+- Related skills: make-requirements, make-plan, exec-plan, retro-requirements.
+
+## Reference files
+
+- [templates.md](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](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](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.

package/skills/techdocs/authoring-and-update.md

@@ -0,0 +1,178 @@
+# techdocs — Authoring, Update Protocol & Health Check (Phases 5–6 + review_techdocs)
+
+> **CodeOps Artifact Schema**: 1
+
+Read this before authoring any document, before any auto-update, and when running
+`review_techdocs`.
+
+---
+
+## Phase 5 — Authoring guidelines
+
+### Writing style
+
+Technical documentation must be:
+
+- **Clear** — Written for a developer who has never seen the project. No assumed context.
+- **Concise** — Say what needs saying, nothing more. Prefer tables over paragraphs for structured data.
+- **Current** — Every document has a "Last Updated" date. Stale docs are worse than no docs.
+- **Concrete** — Include code examples, diagrams, and specific values. Avoid vague statements like "uses best practices."
+- **Correct** — Every statement must reflect the actual codebase. Don't document aspirations as reality.
+
+### Diagrams (Mermaid)
+
+Use Mermaid syntax — rendered via `vitepress-plugin-mermaid`, which the setup step installs (vanilla VitePress does not render Mermaid):
+
+- **Architecture diagrams**: `graph TB` or `graph LR`
+- **Entity relationships**: `erDiagram`
+- **Sequences**: `sequenceDiagram`
+- **State machines**: `stateDiagram-v2`
+
+### Cross-referencing
+
+- Use relative links between doc pages (e.g. `[System Overview](/architecture/system-overview)`).
+- Reference ADRs by number when explaining design choices (e.g. "See [ADR-003](/decisions/ADR-003-chosen-database)").
+- Link to source code files when documenting specific implementations.
+
+### What NOT to document
+
+- **Secrets, credentials, or API keys** — Never. Not even examples that look real.
+- **Auto-generated code** — Don't document what can be read from the code itself.
+- **Temporary decisions** — If something is likely to change next week, don't write an ADR for it.
+- **Obvious code** — Don't explain what `getUserById()` does. Document the *why*, not the *what*.
+
+---
+
+## Phase 6 — Incremental update protocol
+
+### 6.1 After phase completion (incremental)
+
+When an exec-plan phase completes and techdocs exist:
+
+1. **Scan for architectural changes** — Did this phase introduce: new components/services? New
+   data entities or relationships? New API endpoints? New external integrations? Infrastructure
+   changes? Significant design decisions?
+2. **If YES to any** → update the relevant sections:
+   - New components → `system-overview.md`
+   - New entities → `data-model.md`
+   - New endpoints → `api-design.md`
+   - New integrations → `integrations.md`
+   - Significant decisions → create ADRs
+3. **If NO** → skip (not every phase changes architecture).
+4. **Update "Last Updated"** dates on modified documents.
+
+For incremental updates, check new/changed code against the ADRs covering the affected area, and
+apply the Design Intent Preservation check (6.4) for any relevant ADR.
+
+### 6.2 After plan completion (comprehensive)
+
+When all exec-plan tasks are complete and techdocs exist:
+
+1. **Review every section** against the current codebase.
+2. **Update all diagrams** to reflect current architecture.
+3. **Verify all links** work.
+4. **🚨 Check for design intent divergence** — see 6.4 below.
+5. **Check for stale content** — anything no longer reflecting reality.
+6. **Update the VitePress sidebar** if new pages were added.
+7. **Update "Last Updated"** dates on all modified documents.
+8. **Create ADRs** for any undocumented decisions from plan execution.
+
+### 6.3 After make-requirements completion (incremental)
+
+When make-requirements completes and techdocs exist:
+
+1. **Extract design decisions** from the requirements documents.
+2. **Create ADRs** for each significant decision (technology choices, architecture patterns, integration decisions).
+3. **Update architecture sections** if the requirements imply architectural changes.
+4. **Update the decision log** in `decisions/index.md`.
+
+### 6.4 🚨 Design Intent Preservation — NON-NEGOTIABLE
+
+**Auto-updates MUST NOT silently overwrite design intent with observed code behavior.** This rule
+prevents the documentation tautology — where code changes (including bugs, regressions, and
+architectural violations) get automatically documented as the new "intended architecture,"
+erasing the original design rationale.
+
+**The problem this solves:** If exec-plan introduces an architectural violation (e.g. a service
+that should call through an API layer instead directly accesses the database), a naive auto-update
+would change the architecture diagram and component description to match the violation. The next
+make-plan run would then read the updated techdocs and treat the violation as the established
+architecture. The original design intent is permanently lost.
+
+**During every comprehensive update (6.2), you MUST:**
+
+1. **Read all existing ADRs** — these are the documented design decisions.
+2. **Compare the current codebase against ADR decisions** — does the code still follow them?
+3. **If code MATCHES the ADR decisions** → update documentation normally (describe what exists).
+4. **If code DIVERGES from an ADR decision** → DO NOT silently update. Instead:
+
+   a. **Flag the divergence** to the user:
+
+   ```
+   ⚠️ Design Intent Divergence Detected
+
+   ADR-003 decided: "All database access goes through the repository layer"
+   Current code: UserController directly queries the database in src/controllers/user.ts:47
+
+   Options:
+   (A) Code is wrong — this is a violation that should be fixed
+   (B) Decision changed — create a new ADR superseding ADR-003
+   (C) Partial exception — document the exception with rationale
+   ```
+
+   b. **Ask the user** and wait for their decision before updating the affected section.
+   c. **If option (B)** → create a new ADR with status "Supersedes ADR-XXX" and update docs accordingly.
+   d. **If option (A)** → do NOT update the architecture docs to match the violation. Note it in a
+      `⚠️ Known Violations` section for the next exec-plan run to fix.
+
+**Rules:**
+
+- ❌ NEVER silently change an architecture description to match code that contradicts an existing ADR.
+- ❌ NEVER delete or modify an ADR's Decision/Rationale section during auto-update.
+- ✅ ADR status can change to "Deprecated" or "Superseded" ONLY with user approval.
+- ✅ New ADRs can be created to document evolved decisions, with explicit supersession references.
+
+---
+
+## review_techdocs — Health check
+
+When the user asks for `review_techdocs`, perform a read-only health check (it changes no files):
+
+1. Read all documents in `docs/`.
+2. Analyze the current codebase structure.
+3. Run the 7-dimension check:
+
+| Check | What to look for |
+|-------|-----------------|
+| **Staleness** | "Last Updated" dates older than the most recent code changes |
+| **Completeness** | Missing sections for existing components, entities, endpoints, integrations |
+| **Accuracy** | Documented architecture doesn't match actual code structure |
+| **ADR coverage** | Significant technology/pattern choices without corresponding ADRs |
+| **Link health** | Broken internal links between documentation pages |
+| **Diagram accuracy** | Mermaid diagrams that don't match actual architecture |
+| **Getting started** | Setup guide works with current project state |
+
+4. Produce a diagnostic report:
+
+```markdown
+## Techdocs Health Check: [Project Name]
+
+**Documents Analyzed:** X files
+**Date:** [Date]
+
+### ✅ Passing
+- [Check that passed]
+
+### ⚠️ Warnings (Stale or Incomplete)
+- [Section] — Last updated [date], but [component] was modified on [date]
+- [Section] — Missing documentation for [component/entity/endpoint]
+
+### ❌ Issues Found (Incorrect or Broken)
+- [Specific inaccuracy or broken link]
+
+### 📝 Missing ADRs
+- [Decision that should have an ADR but doesn't]
+
+### Suggestions
+- [Improvement opportunity]
+```