@haposoft/cafekit 0.8.12 → 0.8.14

package/src/claude/skills/docs/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: hapo:docs
+description: "Create, update, summarize, or reconstruct project/system documentation from source code. Use reconstruct mode for as-is documentation of existing or legacy systems with evidence and uncertainty tracking."
+version: 1.0.0
+argument-hint: "[init|update|summarize|reconstruct] [scope]"
+---
+
+# Docs
+
+Project documentation workflow for CafeKit.
+
+`hapo:docs` covers two related but distinct jobs:
+
+1. **Normal project docs** — create, update, or summarize living project documentation.
+2. **As-is reconstruction** — rebuild current-state system documentation from source code, especially for existing or legacy systems with missing documents.
+
+## Command Forms
+
+```text
+/hapo:docs
+/hapo:docs init
+/hapo:docs update
+/hapo:docs summarize
+/hapo:docs reconstruct <scope>
+```
+
+## Default Behavior
+
+Parse the user intent before selecting a mode.
+
+| Intent signal | Mode |
+|---|---|
+| Existing system, legacy system, source-to-docs, as-is, reverse documentation, or requirement reconstruction | `reconstruct` |
+| Missing docs, initialize docs, bootstrap docs | `init` |
+| Existing docs need refresh after code changes | `update` |
+| Short overview, quick codebase summary, summarize docs | `summarize` |
+
+When `/hapo:docs` has no clear mode:
+
+1. Read the docs root from `.claude/runtime.json`.
+2. If the docs root is missing, choose `init`.
+3. If the docs root exists and user did not request only a summary, choose `update`.
+4. Ask one concise clarification only when choosing between normal docs and as-is reconstruction would change the output materially.
+
+Do not show a menu when prompt intent is already clear.
+
+## Output Roots
+
+Read `.claude/runtime.json` first. Use:
+
+```json
+{
+  "paths": {
+    "docs": "docs"
+  }
+}
+```
+
+Default docs root: `docs/`.
+
+Normal docs live directly under the docs root:
+
+```text
+docs/
+├── project-overview-pdr.md
+├── codebase-summary.md
+├── system-architecture.md
+├── code-standards.md
+├── design-guidelines.md
+├── deployment-guide.md
+└── project-roadmap.md
+```
+
+Reconstructed as-is docs live under:
+
+```text
+docs/as-is/<scope-slug>/
+├── overview.html
+├── reconstruction.json
+├── system-overview.md
+├── requirements-as-is.md
+├── roles-and-permissions.md
+├── entities-and-statuses.md
+├── business-rules.md
+├── integrations.md
+├── architecture-c4.md
+├── constraints-risks-and-decisions.md
+├── glossary.md
+├── evidence-map.md
+└── unknowns-and-assumptions.md
+```
+
+## Subcommands
+
+### `init`
+
+Create the standard project docs set from the current source code.
+
+Use when:
+- the repository has code but no useful docs
+- the user asks to create project docs
+- SessionStart docs-sync reports missing documentation
+
+Load:
+- `references/standard-docs-workflow.md`
+- `references/init-workflow.md`
+
+### `update`
+
+Refresh existing docs after code changes.
+
+Use when:
+- docs exist and source code changed
+- the user asks to update or refresh docs
+- docs-sync reports stale docs
+
+Load:
+- `references/standard-docs-workflow.md`
+- `references/update-workflow.md`
+
+### `summarize`
+
+Create or update only `codebase-summary.md`.
+
+Use when:
+- the user asks for a quick project summary
+- downstream work needs orientation but not full docs
+
+Load:
+- `references/standard-docs-workflow.md`
+- `references/summarize-workflow.md`
+
+### `reconstruct`
+
+Rebuild current-state, as-is system documentation from source code.
+
+Use when the user asks for:
+- legacy system documentation
+- source-code-to-documentation
+- current system requirements
+- as-is requirements
+- requirement reconstruction
+- reverse documentation
+- Japanese-style legacy system modernization discovery
+
+Load:
+- `references/reconstruct-workflow.md`
+- `templates/reconstruction.json`
+- `templates/requirements-as-is.md`
+- `templates/evidence-map.md`
+- `templates/unknowns-and-assumptions.md`
+- `templates/reconstruct-overview.html`
+
+## Reconstruction Is Not Specs
+
+`hapo:docs reconstruct` MUST NOT:
+
+- design future behavior
+- add new requirements
+- create implementation tasks
+- create `specs/<feature>/`
+- run `/hapo:develop`
+- claim full business intent from code alone
+
+Correct handoff:
+
+```text
+/hapo:docs reconstruct <scope>
+-> human review of as-is docs
+-> /hapo:specs <modernization or change request>
+-> /hapo:develop <feature>
+```
+
+## Reconstruction Evidence Rules
+
+Every major finding in reconstructed docs MUST be classified:
+
+```text
+Type: Observed | Inferred | Unknown
+Confidence: High | Medium | Low
+Evidence: file path, symbol, route, schema, test, or config
+```
+
+Definitions:
+
+- `Observed`: directly visible in source code, tests, schemas, route definitions, config, or docs.
+- `Inferred`: likely behavior derived from multiple signals, but not directly proven.
+- `Unknown`: cannot be established from available evidence.
+
+Do not hide uncertainty. Preserving unknowns is part of the output.
+
+## Scope Discipline
+
+Start with the narrowest useful scope.
+
+For broad inputs such as `.`, `/`, `whole repo`, or `entire system`:
+
+1. Run a lightweight structure scout first.
+2. Split the project into modules or bounded contexts.
+3. Ask the user to pick a module if the first pass cannot safely choose one.
+
+Prefer:
+
+```text
+/hapo:docs reconstruct apps/admin
+/hapo:docs reconstruct modules/expense-approval
+/hapo:docs reconstruct src/features/order
+```
+
+Avoid reconstructing a large monolith in one pass unless the user explicitly accepts lower precision.
+
+## Agent And Tool Fit
+
+Normal docs workflows reuse the CafeKit docs stack already shipped in the package:
+
+- use `hapo:inspect` or targeted reads to scout source scope
+- use `docs-keeper` for evidence-backed docs writing when delegation is available
+- use `.claude/scripts/validate-docs.cjs <docs-root>` after create/update work
+- use `.claude/scripts/validate-docs-reconstruct.cjs <docs-root>/as-is/<scope-slug>` before a reconstructed bundle is handed to human review
+
+The upstream Research docs workflow names a `docs-manager` agent. CafeKit ships `docs-keeper` instead; keep the same scouting, size-check, and validation discipline while using the packaged agent contract.
+
+`reconstruct` may use the same scout patterns, but it writes a scoped as-is bundle and must keep uncertainty visible.
+
+## Best-Practice Basis
+
+Use these documentation principles:
+
+- **Docs as Code**: docs live in the repo and are reviewed like code.
+- **C4 Model**: use system context/container/component views when architecture is relevant.
+- **arc42**: capture context, building blocks, runtime behavior, deployment, risks, and decisions when useful.
+- **Diataxis**: separate explanation, reference, and how-to content instead of dumping one long file.
+- **ADR discipline**: if code reveals important architectural decisions, record them as recovered decision notes, not guesses.
+
+## Required Final Report
+
+For any `hapo:docs` run, report:
+
+- files created or updated
+- scope analyzed
+- evidence quality
+- unresolved questions
+- recommended next command, if any
+
+For `reconstruct`, the recommended next command is usually:
+
+```text
+/hapo:specs <change request based on approved as-is docs>
+```
+
+## References
+
+- `references/standard-docs-workflow.md`
+- `references/init-workflow.md`
+- `references/update-workflow.md`
+- `references/summarize-workflow.md`
+- `references/reconstruct-workflow.md`
+- `templates/reconstruction.json`
+- `templates/requirements-as-is.md`
+- `templates/evidence-map.md`
+- `templates/unknowns-and-assumptions.md`
+- `templates/reconstruct-overview.html`

package/src/claude/skills/docs/references/init-workflow.md

@@ -0,0 +1,132 @@
+# Init Workflow
+
+Use with `/hapo:docs init`.
+
+## Goal
+
+Create a first evidence-backed documentation baseline for a repository that already has source code but lacks useful project docs.
+
+The first run should make future agents faster without presenting guesses as project truth.
+
+## Inputs
+
+Resolve the docs root from `.claude/runtime.json` first. Default to `docs/`.
+
+Read or scout:
+
+- `README.md`, `CLAUDE.md`, `AGENTS.md`, and root instructions that exist
+- package/workspace manifests, lock files, build config, runtime config
+- source directories that actually exist
+- tests, migrations, schemas, routes, CI, deployment config
+- current docs root if it exists but is incomplete
+
+Do not hardcode `src/` when a project uses `apps/`, `packages/`, `cmd/`, `internal/`, `modules/`, or another structure.
+
+## Required Baseline
+
+Create or update the useful core docs below:
+
+| File | Purpose | Creation rule |
+|---|---|---|
+| `README.md` | Entry point and quick commands | Update if needed; keep concise |
+| `<docs-root>/project-overview-pdr.md` | Product purpose, actors, capabilities, constraints | Core |
+| `<docs-root>/codebase-summary.md` | Project structure, tech stack, major runtime paths | Core |
+| `<docs-root>/code-standards.md` | Observed conventions, commands, code quality rules | Core |
+| `<docs-root>/system-architecture.md` | Boundaries, components, runtime/data flow | Core |
+| `<docs-root>/project-roadmap.md` | Current state, milestones, known follow-up areas | Core when evidence exists |
+| `<docs-root>/deployment-guide.md` | Build/deploy/runtime config | Optional when deployment evidence exists |
+| `<docs-root>/design-guidelines.md` | UI/design conventions | Optional when UI evidence exists |
+
+Do not create a large document solely to fill the table. If a core file cannot be grounded yet, create the smallest useful shell and put unresolved questions at the end.
+
+## Workflow
+
+### Phase 0: Preflight
+
+1. Read repo instructions and runtime docs root.
+2. Detect whether docs already exist.
+3. If user specifically asked `init` and docs exist, preserve existing content:
+   - read it first
+   - merge or add missing baseline sections
+   - do not overwrite human-written docs blind
+4. Build a no-scan list for ignored, generated, vendor, cache, secret, and credential paths.
+
+### Phase 1: Structure Scout
+
+Run a lightweight source scout before deep reading:
+
+1. List top-level directories and key manifests.
+2. Count file/LOC shape by existing source areas where practical.
+3. Identify project type:
+   - language/framework
+   - package manager/build system
+   - app/service boundaries
+   - UI/API/worker/job/deployment surfaces
+4. Split large repositories into scoped source areas.
+
+Use `hapo:inspect` when source discovery spans multiple directories. Prefer targeted reads when the repo is small.
+
+### Phase 2: Evidence Scout
+
+Collect evidence for docs authorship:
+
+| Topic | Evidence examples |
+|---|---|
+| Tech stack | package manifests, `go.mod`, `pyproject.toml`, build files |
+| Commands | scripts, Makefiles, CI jobs |
+| Runtime entry points | app bootstrap, routes, controllers, server main files |
+| Data model | schemas, migrations, models, DTOs |
+| Architecture | imports between modules, service boundaries, deploy config |
+| Testing | test commands, test directories, fixtures |
+| UI/design | shared components, tokens, styles, screenshots when present |
+
+Merge scout results into a concise context summary. Keep file references with each important claim.
+
+### Phase 3: Docs Authoring
+
+Delegate the merged context to `docs-keeper` when available. Otherwise follow its verification discipline in the main context.
+
+Authoring rules:
+
+1. Read code before documenting code.
+2. Verify referenced paths, commands, config keys, endpoints, and symbols before naming them.
+3. Record observed conventions as observed; do not turn folder guesses into standards.
+4. Use relative links among docs only after confirming targets exist.
+5. Add unresolved questions to any doc whose important claim is not yet verifiable.
+
+### Phase 4: Size Discipline
+
+After generation:
+
+1. Check markdown LOC in the docs root.
+2. Use `docs.maxLoc` from session/runtime context when provided; default to 800 lines.
+3. If a file crosses the limit:
+   - split on semantic boundaries
+   - make an `index.md` for the topic when a document becomes a folder
+   - keep links from the original entry point
+4. Report any intentionally accepted oversized file.
+
+### Phase 5: Validation And Tracking
+
+1. Run `.claude/scripts/validate-docs.cjs <docs-root>` when available.
+2. Fix broken internal doc links that can be resolved from evidence.
+3. If docs-sync uses `<docs-root>/.sync_hash`, update it only after the docs reflect current source state.
+
+## Required Final Report
+
+Report:
+
+- docs root used
+- source areas scouted
+- files created or updated
+- validation result
+- evidence gaps
+- unresolved questions
+
+Recommended next command:
+
+```text
+/hapo:docs update
+```
+
+after meaningful source changes.