From devflow
Systematically analyzes and documents a legacy codebase using size-aware progressive disclosure. Generates CLAUDE.md, component rules, architecture documentation, and selective ADRs. Use this when inheriting an undocumented codebase that needs understanding before new work begins.
npx claudepluginhub joshuarweaver/cascade-code-general-misc-4 --plugin codingthefuturewithai-claude-code-primitivesThis skill is limited to using the following tools:
**Say exactly:** "SKILL INVOKED: foundation/document-legacy-codebase"
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Say exactly: "SKILL INVOKED: foundation/document-legacy-codebase"
You are helping the user systematically document a legacy codebase that lacks adequate documentation. Your goal is to make the codebase understandable and maintainable through strategic analysis and clear documentation.
Produce structured documentation that separates concerns correctly:
Progress:
- [ ] Phase 1: Quick assessment — scan metrics, classify complexity, get approval
- [ ] Phase 2: Generate root CLAUDE.md
- [ ] Phase 3: Component-level rules (one per major component)
- [ ] Phase 4: Architecture documentation
- [ ] Phase 5: Identify ADR candidates
- [ ] Phase 6: Quiz user and draft approved ADRs
- [ ] Phase 7: Review and iterate
- [ ] Phase 8: Update project manifest
Scan for size and complexity using the codebase-scanner agent (via Task tool):
This is a fast metrics-gathering operation that benefits from context isolation. The agent uses tokei or simple bash commands to gather data without reading code deeply.
Classify complexity:
Present strategy to user:
Create lean, imperative documentation:
# [Project Name]
[One-line description from README or package.json]
## Quick Start
[Exact commands to run the project]
## Project Structure
[List major directories with one-line descriptions and pointers to rules files]
## Important Notes
[Non-obvious gotchas, prerequisites, setup quirks]
Critical: Do NOT regurgitate obvious facts. Focus on what Claude can't easily infer:
For each major component (backend, frontend, infrastructure, etc.):
Use the component-analyzer agent (via Task tool) to analyze patterns and conventions. When multiple components are identified, run Task tool calls in parallel — one per component:
Generate .claude/rules/[component].md:
Follow references/component-analysis-guide.md for structure.
Remember: These are RULES for working with code, NOT architecture descriptions.
Use the architecture-mapper agent (via Task tool) to understand system structure:
Generate .devflow/architecture.md:
Remember: This is DESCRIPTIVE (what exists), not PRESCRIPTIVE (how to work with it).
Use the decision-detector agent (via Task tool) to identify major architectural decisions from code:
Present candidates to user: "I detected these major architectural decisions in the code:
Should I document any of these as ADRs? (Requires your input on WHY these decisions were made)"
For each approved ADR candidate, quiz the user using references/adr-quiz-template.md:
Questions to ask:
Draft the ADR combining:
Get approval before storing.
Present summary:
Documentation Generated:
- CLAUDE.md (root)
- .claude/rules/backend.md (FastAPI patterns)
- .claude/rules/frontend.md (React patterns)
- .claude/rules/infrastructure.md (deployment patterns)
- .devflow/architecture.md (system design)
- .devflow/adrs/ADR-001-kafka.md
- .devflow/adrs/ADR-002-fastapi.md
- .devflow/adrs/ADR-003-zustand.md
What am I missing? Should I dive deeper on anything?
Iterate if needed.
Update .devflow/project.md with links to all generated documentation:
documentation:
claude_md: CLAUDE.md
rules:
- .claude/rules/backend.md
- .claude/rules/frontend.md
- .claude/rules/infrastructure.md
architecture: .devflow/architecture.md
adrs:
- .devflow/adrs/ADR-001-kafka.md
- .devflow/adrs/ADR-002-fastapi.md
Detect from context:
.devflow/ already exists → Enhancement mode (add missing docs)This skill produces DOCUMENTATION, not new code.
✅ IN SCOPE:
❌ OUT OF SCOPE:
After this skill completes, the user can:
/devflow:build:create-issue to create new work items/playground to generate an interactive visual code map alongside these docs — useful for navigating the codebase structure in a browserSkill complete.