# Blueprint Derive Plans > Derive PRDs, ADRs, and PRPs from git history, codebase structure, and existing documentation Use when this capability is needed. - Skill: `tomevault-io/blueprint-derive-plans` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/blueprint-derive-plans` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/blueprint-derive-plans/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/blueprint-derive-plans --- # /blueprint:derive-plans Retroactively generate Blueprint documentation (PRDs, ADRs, PRPs) from an existing established project by analyzing git history, codebase structure, and existing documentation. **Use case**: Onboarding established projects into the Blueprint Development system when PRD/ADR/PRP documents don't exist but the project has implementation history. ## When to Use This Skill | Use this skill when... | Use alternative when... | |------------------------|-------------------------| | Project has git history but no PRDs/ADRs/PRPs | Starting a brand new project with no history | | Onboarding an established project to Blueprint | Creating a fresh PRD from scratch with user guidance | | Need to extract features from commit history | Project lacks conventional commits and clear history | | Want to document architecture decisions retroactively | Decisions are already fully documented | ## Context - Git repository: !`git rev-parse --git-dir` - Blueprint initialized: !`find docs/blueprint -maxdepth 1 -name 'manifest.json' -type f` - Total commits: !`git rev-list --count HEAD` - First commit: !`git log --reverse --format=%ai --max-count=1` - Latest commit: !`git log --max-count=1 --format=%ai` - Project type: !`find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'pom.xml' \) -type f -print -quit` - Documentation files: !`find . -maxdepth 2 \( -name "README.md" -o -name "ARCHITECTURE.md" -o -name "DESIGN.md" \)` ## Parameters Parse these from `$ARGUMENTS`: - `--quick`: Fast scan (last 50 commits only) - `--since DATE`: Analyze commits from specific date (e.g., `--since 2024-01-01`) Default behavior without flags: Standard analysis (last 200 commits with scope estimation). For detailed templates, manifest format, and report examples, see [REFERENCE.md](REFERENCE.md). ## Execution Execute this retroactive documentation generation workflow: ### Step 1: Verify prerequisites Check context values above: 1. If git repository = "NO" → Error: "This directory is not a git repository. Run from project root." 2. If total commits = "0" → Error: "Repository has no commit history" 3. If Blueprint initialized = "NO" → Ask user: "Blueprint not initialized. Initialize now (Recommended) or minimal import only?" - If "Initialize now" → Use Task tool to invoke `/blueprint:init`, then continue with this step 1 - If "Minimal import only" → Create minimal directory structure: `mkdir -p docs/prds docs/adrs docs/prps` ### Step 2: Determine analysis scope Parse `$ARGUMENTS` for `--quick` or `--since`: 1. If `--quick` flag present → scope = last 50 commits 2. If `--since DATE` present → scope = commits from DATE to now 3. Otherwise → Present options to user: - Quick scan (last 50 commits) - Standard analysis (last 200 commits) - Full history analysis (all commits) - Custom date range Use selected scope for all subsequent git analysis. ### Step 3: Analyze git history quality For commits in scope, calculate: 1. Count total commits: `git log --oneline {scope} | wc -l` 2. Count conventional commits: `git log --format="%s" {scope} | grep -cE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\(?.*\)?:" || echo 0` 3. Calculate percentage and assign quality score (see [REFERENCE.md](REFERENCE.md#git-quality-scoring)) Report: "Git history quality: {score}/10 ({percentage}% conventional commits)" ### Step 4: Extract features and architecture decisions Using methods from [REFERENCE.md](REFERENCE.md#git-analysis-patterns): 1. Extract feature boundaries from conventional commit scopes 2. Identify architecture decisions (migrations, major dependencies, breaking changes) 3. Find issue references and future work items (TODOs, skipped tests) 4. Identify release boundaries from git tags Collect findings in structured format for user confirmation. ### Step 5: Analyze codebase and existing documentation 1. Use Explore agent to analyze architecture: directory structure, components, frameworks, patterns, entry points, data layer, API layer, testing structure 2. Extract dependencies from manifest files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.) 3. Read and extract from existing documentation: README.md, docs/, ARCHITECTURE.md, DESIGN.md, CONTRIBUTING.md 4. Detect future work: TODOs in code, open GitHub issues, skipped tests ### Step 6: Clarify project context with user Ask for clarifications on: 1. **Project purpose** (if not clear from README): Present inferred description for confirmation or ask user to provide 2. **Target users**: Who are the primary users (developers, end users, both)? 3. **Feature confirmation**: Present {N} features extracted from git for review/prioritization 4. **Architecture rationale**: For each identified decision, ask what was the main driver 5. **Generation confirmation**: Show summary with metrics and ask if ready to generate For confirmation step, present: - Git history quality: {score}/10 - Features identified: {N} - Architecture decisions: {N} - Future work items: {N} - Proposed documents: PRD, {N} ADRs, {N} PRPs ### Step 7: Generate documents Create directory structure: `mkdir -p docs/prds docs/adrs docs/prps` For each document type, use templates and patterns from [REFERENCE.md](REFERENCE.md): 1. **Generate PRD** as `docs/prds/project-overview.md` - Use sections and structure from REFERENCE.md - Include extracted features with priorities and sources - Mark sections with confidence scores 2. **Generate ADRs** as `docs/adrs/{NNNN}-{title}.md` (one per decision) - Use ADR template from REFERENCE.md - Include git evidence (commit SHA, date, files changed) - Mark with confidence score 3. **Create ADR index** at `docs/adrs/README.md` - Table of all ADRs with status and dates - Link to MADR template for new ADRs 4. **Generate PRPs** as `docs/prps/{feature}.md` (one per future work item) - Use PRP template from REFERENCE.md - Include source reference and confidence score - Suggest implementation based on codebase patterns ### Step 8: Update manifest and report results 1. Update `docs/blueprint/manifest.json` with import metadata: timestamp, commits analyzed, confidence scores, generated artifacts ### Step 9: Update task registry Update the task registry entry in `docs/blueprint/manifest.json`: ```bash jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ --arg sha "$(git rev-parse HEAD 2>/dev/null)" \ --argjson analyzed "${COMMITS_ANALYZED:-0}" \ --argjson created "${DOCS_GENERATED:-0}" \ '.task_registry["derive-plans"].last_completed_at = $now | .task_registry["derive-plans"].last_result = "success" | .task_registry["derive-plans"].context.commits_analyzed_up_to = $sha | .task_registry["derive-plans"].context.commits_analyzed_count = $analyzed | .task_registry["derive-plans"].stats.runs_total = ((.task_registry["derive-plans"].stats.runs_total // 0) + 1) | .task_registry["derive-plans"].stats.items_processed = $analyzed | .task_registry["derive-plans"].stats.items_created = $created' \ docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json ``` 2. Create summary report showing: - Commits analyzed with date range - Git quality score - Documents generated (PRD, ADR count, PRP count) - Sections needing review (confidence < 7) - Recommended next steps 3. Prompt user for next action: - Review and refine documents - Generate project rules from PRD - Generate workflow commands - Exit (documents saved) ## Agentic Optimizations | Context | Command | |---------|---------| | Check git status | `git rev-parse --git-dir 2>/dev/null && echo "YES" \|\| echo "NO"` | | Count commits | `git rev-list --count HEAD 2>/dev/null \|\| echo "0"` | | Conventional commits count | `git log --format="%s" \| grep -cE "^(feat\|fix\|docs)" \|\| echo 0` | | Extract scopes | `git log --format="%s" \| grep -oE '\([^)]+\)' \| sort \| uniq -c` | | Fast analysis | Use `--quick` flag for last 50 commits only | --- For detailed templates, git analysis patterns, document generation examples, and error handling guidance, see [REFERENCE.md](REFERENCE.md). --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/laurigates) — claim your Tome and manage your conversions.