Arguments: `/codebase-documentation:document-codebase [FLAGS]`
Generates a complete documentation system for AI agents to navigate your codebase. Use this to create structured docs, domain guides, and utility commands after major codebase changes.
/plugin marketplace add olioapps/claude-code-plugins/plugin install codebase-documentation@olio-pluginsArguments: /codebase-documentation:document-codebase [FLAGS]
This command generates a complete documentation system for AI agents to efficiently navigate the codebase.
Display progress to the user at each phase transition:
## š Generating Codebase Documentation...
**Progress:**
- [ ] Phase 0: Clarification
- [ ] Phase 0.5: Checking existing docs
- [ ] Phase 1: Analyzing codebase structure
- [ ] Phase 2: Generating documentation files
- [ ] Phase 3: Creating utility commands
- [ ] Phase 4: Summary report
Update checkboxes as each phase completes:
[x] for completed phases[ ] for pending phasesā [ ] Phase 1: Analyzing...)Skip if --skip-clarification flag is present.
Use AskUserQuestion to gather context:
Question 1: Application Type
Question 2: Architecture Notes
Store user responses for agent context.
Before proceeding to analysis, check if documentation already exists:
Check for: .claude/docs/codebase-schema.yaml
If file exists, use AskUserQuestion:
If user selects Regenerate, proceed to Phase 1. If Cancel, abort with message: "Documentation generation cancelled. Existing documentation preserved."
Use Task tool to invoke codebase-analyzer agent:
Analyze this codebase to understand its structure, technology stack, and organizational patterns.
{IF USER PROVIDED APP TYPE:}
Application Type: {user's answer}
{IF USER PROVIDED ARCHITECTURE NOTES:}
Architecture Notes:
"""
{user's notes}
"""
Return your analysis in the structured format specified in your instructions.
Parse the returned analysis. Expect format:
---ANALYSIS---
{YAML content}
---END---
Validate that analysis contains:
If validation fails, report error and abort.
Only execute this phase if --dry-run flag is present.
Display a comprehensive preview of what would be generated:
## š Dry Run Preview
**Files to be created:**
- `.claude/docs/codebase-schema.yaml`
- `.claude/docs/INDEX.md`
{For each domain in analysis:}
- `.claude/docs/domains/{domain_name}.md`
{For each significant pattern in analysis:}
- `.claude/docs/patterns/{pattern_name}.md`
- `.claude/commands/prime.md`
- `.claude/commands/audit-docs.md`
- `.claude/commands/map-domain.md`
- `CLAUDE.md` (update)
**Domains identified ({count}):**
| Domain | Location | Purpose | Confidence |
|--------|----------|---------|------------|
{For each domain from analysis:}
| {name} | `{location}` | {purpose} | {confidence} |
**Patterns to document ({count}):**
{For each pattern from analysis:}
- {pattern_name}: `{pattern}` ({count} files)
**Schema preview:**
```yaml
metadata:
project: {from analysis}
type: {from analysis}
stack:
language: {from analysis}
framework: {from analysis}
architecture: {from analysis}
domains:
{first 2-3 domain names}:
...
Then use AskUserQuestion:
- "Proceed with documentation generation?"
- Options:
- **Yes** - Generate all documentation files
- **No** - Cancel without creating files
If Yes, proceed to Phase 2. If No, abort with message:
"Dry run complete. No files were created."
### Phase 2: Invoke Documentation Generator
Use Task tool to invoke `documentation-generator` agent:
Generate documentation for this codebase based on the following analysis.
---ANALYSIS--- {paste complete analysis from Phase 1} ---END---
Create all documentation files as specified in your instructions:
Return confirmation of files created.
**Parse the returned confirmation.** Expect format:
---FILES_CREATED--- {file list} ---END---
### Phase 2.5: Completeness Verification (Optional)
**Skip if analysis had <5 domains.**
Before proceeding, verify the analysis captured structural boundaries appropriately.
**Check for potential missed domains:**
1. Review directories that were NOT made into domains
2. For each, verify it's appropriately covered by another domain
3. Check for file patterns that span multiple directories (cross-cutting concerns)
**Check for over-combined domains:**
1. Review any domain with `confidence: low` or `confidence: medium`
2. Review any domain with count >50 files
3. Verify sub-directories don't have distinct conventions
**If issues found:**
- Note them in observations for the documentation generator
- The generator will add them to the INDEX as "potential areas for further documentation"
**This check is about structural boundaries, not specific domain names.**
### Phase 3: Report Summary
Present final summary to user:
```markdown
## Documentation Generated Successfully
**Application Type**: {from analysis}
**Technology Stack**:
- Language: {language}
- Framework: {framework}
{other stack items}
**Structure Summary:**
- Domains documented: {count}
- File patterns covered: {count}
- Task mappings created: {count}
**Documentation Created**:
- `.claude/commands/prime.md`
- `.claude/docs/codebase-schema.yaml`
- `.claude/docs/INDEX.md`
- `.claude/docs/domains/` - {count} domain docs
- `.claude/docs/patterns/` - {count} pattern guides
- Updated `CLAUDE.md`
**Domains Documented**:
| Domain | Purpose | Files |
|--------|---------|-------|
| {name} | {purpose} | {count} |
{list all domains}
**Quality Checks**:
- [x] All structural boundaries captured
- [x] All patterns mapped to domains
- [x] INDEX table is complete
- [x] No overlapping domains
**Potential Gaps** (if any):
- {List any directories that might warrant separate docs in the future}
- {List any patterns without clear domain ownership}
- {List any medium/low confidence domains that may need review}
**Architecture Summary**:
{from analysis.metadata.architecture}
---
**Maintenance Commands** (from plugin):
- `/codebase-documentation:audit-docs` - Check for documentation drift
- `/codebase-documentation:map-domain <name>` - Deep-dive domain analysis
- `/codebase-documentation:update-docs` - Refresh documentation intelligently
**Next Steps**:
1. Run `/prime` to load codebase context
2. Review any noted "Potential Gaps" and decide if additional documentation needed
3. Use `/codebase-documentation:audit-docs` periodically to check for drift
4. Use `/codebase-documentation:update-docs` to refresh docs after major changes
YOU (handler):
codebase-analyzer agent:
documentation-generator agent:
You do NOT explore codebase directly - agents do the exploration.
/codebase-documentation:document-codebase
# Asks clarifying questions, then generates full documentation
/codebase-documentation:document-codebase --skip-clarification
# Auto-detects everything, no questions asked
/codebase-documentation:document-codebase --dry-run
# Shows preview of what would be generated, asks for confirmation
/codebase-documentation:document-codebase --skip-clarification --dry-run
# Auto-detect + preview before generating
After successful run:
.claude/
āāā commands/
ā āāā prime.md
āāā docs/
ā āāā codebase-schema.yaml
ā āāā INDEX.md
ā āāā domains/
ā ā āāā components.md
ā ā āāā services.md
ā ā āāā utils.md
ā āāā patterns/
ā āāā components.md
ā āāā services.md
CLAUDE.md (updated)
Note: Utility commands (audit-docs, map-domain, update-docs) are provided by the plugin and invoked via /codebase-documentation:* namespace.
.claude/ directory is writable--skip-clarification to bypass auto-detection issues/codebase-documentation:map-domain <name> command--dry-run to preview changes without risk--skip-clarification to save time on repeated runs