mjmorales/docs

docs

Dispatches by subcommand. Follows references/interaction-patterns.md for all AskUserQuestion usage.

| Subcommand | Purpose | |------------|---------| | human [subject] | Human-readable docs — delegates to technical-writer agent | | agent [subject] | LLM-optimized agent/API/module docs | | both [subject] (default) | Auto-docs: resolve scope, run both audiences | | claude-md generate | Full CLAUDE.md generation via claude-prove claude-md CLI |

Parse first token of $ARGUMENTS as subcommand. If absent, default to both with empty subject (session context).

For single-directive growth of CLAUDE.md outside the prove-managed block, defer to /prove:remember <directive> — it owns optimize + certify + safe-insertion.

---

Subcommand: human

Delegate to technical-writer subagent. One-pass gather, one-pass delegate.

Subject + Audience

AskUserQuestion header "Subject" if ambiguous (include "Research & proceed" with <=3 options):

| Subject | Indicators | Key Sections | |---------|------------|--------------| | Project | Root dir, package.json, multiple components | Quick start, usage, architecture, config | | API | HTTP handlers, REST/GraphQL endpoints | Endpoints, request/response, errors, examples | | Module | Package exports, public interfaces | Install, API surface, examples | | Script | Executable file, CLI flags | Usage, flags table, examples | | Workflow | Multi-step process, multiple tools | Prerequisites, steps, troubleshooting |

AskUserQuestion header "Audience" if ambiguous:

| Audience | Tone | Depth | Assumes | |----------|------|-------|---------| | Contributor | Casual, direct | Deep on internals | Tech stack familiarity | | Consumer | Precise, professional | Interface-level only | No internal knowledge | | Operator | Practical, task-oriented | Config and operations | Infra/deployment experience | | End user | Friendly, no jargon | Surface-level | Minimal technical background |

Context Gathering

• Grep to locate targets, then read specific lines
• Document public interface only — never follow imports recursively
• Complete all reads before delegating

Delegation Prompt

Invoke technical-writer agent with:

Document [SUBJECT_TYPE]: [SUBJECT_NAME]
Audience: [AUDIENCE_TYPE]

Source: [FILE_PATH]:[LINE_RANGE]

Context:
[MINIMAL RELEVANT CODE/CONFIG]

Requirements:
- Output: [project-readme | api-reference | module-docs | script-docs | workflow-guide]
- Audience: [contributor | consumer | operator | end-user]
- Include: [subject-specific sections the template does not cover by default]
- Format: Markdown, no YAML frontmatter unless docs system requires it

Validation

• [ ] Title states what the subject is
• [ ] First paragraph answers "what is this and why use it?"
• [ ] Examples are concrete and runnable (no foo/bar/...)
• [ ] Headings create a scannable outline
• [ ] Structured data uses tables, not prose
• [ ] No unexplained jargon on first use
• [ ] Tone matches target audience

AskUserQuestion header "Quality": "Approve" / "Revise".

---

Subcommand: agent

Generate machine-parseable, LLM-consumable documentation. Delegate to technical-writer with agent-doc output flag.

Subject Identification

AskUserQuestion header "Subject" if ambiguous:

| Subject | Indicators | Required Contracts | |---------|------------|-------------------| | Agent | .md in agents dir, tools: frontmatter | Triggers, input contract, output contract, workflow steps (numbered), tool permissions | | API | HTTP handlers, REST/GraphQL endpoints | Request schema (params, body, headers), response schema (success + error), validation rules, error codes | | Module | Package exports, public interfaces | Public interface (exports only), parameter types/constraints, return types, side effects (I/O, state) | | Code | Functions, classes, complex logic | Types, behavior, edge cases |

Delegation Prompt

Document [SUBJECT_TYPE]: [SUBJECT_NAME]

Source: [FILE_PATH]:[LINE_RANGE]

Context:
[MINIMAL RELEVANT CODE/CONFIG]

Requirements:
- Output: [agent-doc | api-doc | module-doc]
- Include: [specific contracts from table above]
- Format: YAML frontmatter + structured markdown

Validation

• [ ] YAML frontmatter has name, type
• [ ] All contracts from Subject table addressed
• [ ] Examples use concrete values (no .../foo/bar)
• [ ] Error/failure conditions documented

AskUserQuestion header "Quality": "Approve" / "Revise".

---

Subcommand: both (default)

Resolve scope, classify subjects, run agent docs first (define contracts), then human docs.

Step 1 — Resolve Scope

| Input | Resolution | |-------|------------| | No argument | Session context: files created, modified, or discussed in the current session | | Topic name | Grep/Glob for matching files/packages/modules | | Directory path | All exported/public code in that directory | | File path(s) | Those specific files |

Session priority: new files > significantly modified > new agents/skills/commands > scripts. Skip: test files, lock files, build artifacts, self-documenting configs.

If ambiguous: AskUserQuestion header "Scope": "This session" / "Directory" / "Specific files".

Step 2 — Classify Subjects

| Subject Type | Indicators | Human Docs | Agent Docs | |-------------|------------|------------|------------| | Agent (agents/.md) | tools:/model: frontmatter | No | Yes | | Skill (skills//SKILL.md) | name: frontmatter, workflow | Yes | Yes | | Command (commands/.md) | description: frontmatter | Yes | No | | Script (scripts/.sh) | Executable, CLI flags | Yes | Only if agents invoke it | | Package/Module (src/, lib/) | Exports, public API | Yes | Yes | | Config (.json, .yaml) | Schema, options | Yes | Only if agents read it |

Step 3 — Confirm

AskUserQuestion header "Doc Types":

• "Both human & agent docs (Recommended)"
• "Human docs only"
• "Agent docs only"
• "Let me pick per subject"

If human docs selected and audience non-obvious: AskUserQuestion header "Audience": "Contributor" / "Consumer" / "Operator".

AskUserQuestion header "Output":

• "Alongside source (Recommended)"
• "Centralized docs/"
• "Let me specify"

Step 4 — Delegate

Order: agent docs first (establish contracts), human docs second (can reference them). Within each type: core modules before consumers. Dispatch to human and agent subcommand workflows above.

Step 5 — Review

Present summary table (subject, human/agent, path, file count).

AskUserQuestion header "Review": "Approve all" / "Revise" / "Discard".

---

Subcommand: claude-md generate

Full CLAUDE.md regeneration. Scans codebase (tech stack, conventions, structure), reads .claude/.prove.json, composes deterministic output.

Execution

1. $PLUGIN = absolute path to this plugin's root (parent of skills/)
2. $CWD = user's cwd (target project, not plugin dir)
3. Run: claude-prove claude-md generate --project-root $CWD --plugin-dir $PLUGIN
4. Display CLI output

Related CLI Subcommands

| Command | Purpose | |---------|---------| | claude-md scan --project-root $CWD --plugin-dir $PLUGIN | Scanner only, JSON output | | claude-md subagent-context --project-root $CWD --plugin-dir $PLUGIN | Compact context for subagent injection |

Safe to re-run — the CLI owns the file.

---

Anti-Patterns

| Anti-Pattern | Instead | |--------------|---------| | Reading entire files | Grep target, read specific lines | | Interleaving gathering and writing | Complete all reads before delegating | | Omitting audience from human prompt | Always include Audience: | | Verbose examples with inline commentary (agent docs) | Minimal working examples | | Line-by-line code explanation (agent docs) | Document behavior and contracts | | Writing raw user directive to CLAUDE.md | Route through /prove:remember (optimize + certify + safe-insert) |

Committing

Delegate to commit skill. Example messages:

• docs(docs): add README for cafi tool
• docs(docs): document validation-agent interface
• docs(docs): regenerate CLAUDE.md