Refresh

Name: Refresh
Author: joaquimscosta

joaquimscosta/arkhe-claude-plugins

1 installs
21 repo stars
Updated August 5, 2026
joaquimscosta/arkhe-claude-plugins

Detects drift in .arkhe/roadmap/ context files and regenerates them from current codebase state, scaffolding the directory if missing.

About

Detects staleness in roadmap context files (project, architecture, documents) and regenerates them from the current codebase. A developer uses it to keep project context docs in sync or to scaffold them for the first time.

Drift detection script over .arkhe/roadmap/
Regenerates project, architecture, and documents files

Refresh by the numbers

1 all-time installs (skills.sh)
Ranked #1,361 of 1,879 Documentation skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/joaquimscosta/arkhe-claude-plugins --skill refresh

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/joaquimscosta/arkhe-claude-plugins/refresh.svg)](https://skillselion.com/skills/joaquimscosta/arkhe-claude-plugins/refresh)

Installs	1
repo stars	★ 21
Last updated	August 5, 2026
Repository	joaquimscosta/arkhe-claude-plugins ↗

What it does

Detects drift in .arkhe/roadmap/ context files and regenerates them from current codebase state, scaffolding the directory if missing.

Files

SKILL.mdMarkdownGitHub ↗

Context Directory Refresh

Detect drift in .arkhe/roadmap/ context files and regenerate them using a hybrid format (condensed summary + references to authoritative docs).

Arguments

Parse from $ARGUMENTS:

Mode	Description
`init`	Scaffold `.arkhe/roadmap/` with all 3 files from scratch
`check`	Detect drift only — report staleness, don't write
`all`	Regenerate all 3 context files
`project`	Regenerate only project.md
`architecture`	Regenerate only architecture.md
`documents`	Regenerate only documents.md
_(none)_	Run `check`, then ask which files to refresh

Step 1: Run Drift Detection

Run the detection script:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/refresh/scripts/detect_context_drift.py .

Parse the JSON output. Present a drift report table:

## Context Directory Status

| File | Exists | Staleness | Days | Commits Since | feat/fix |
|------|--------|-----------|------|---------------|----------|
| project.md | Yes/No | fresh/aging/stale/very_stale | N | N | N |
| architecture.md | Yes/No | ... | ... | ... | ... |
| documents.md | Yes/No | ... | ... | ... | ... |

New modules not in architecture.md: {list or "none"}

For `check` mode: Stop here. Present the report and suggest which files need attention.

Step 2: Context Discovery

For init, all, or single-file modes, run the shared context discovery protocol from CONTEXT_DISCOVERY.md. Gather:

From README.md: project purpose, target users
From CLAUDE.md: constraints, conventions, tech stack
From build files: tech stack detection via TECH_STACK_DETECTION.md
From docs/**/*.md: documentation inventory
From module globs: module inventory with file counts
From docs/adr/**/*.md: ADR titles and status
From arkhe/specs/*/spec.md: spec pipeline

Step 3: Generate Files

Generate each requested file using the hybrid format below. See WORKFLOW.md for detailed generation protocol per file.

Hybrid Format Template

# {Title}
_Auto-generated by /roadmap:refresh on {date}. Edit freely — regenerate with `/roadmap:refresh {file}`._

## Summary
{3-5 bullet points, <300 tokens — the essential facts}

## Details
{Structured data: tables, lists}

## References
{Pointers to authoritative docs}
- `{doc_path}` — {one-line description}

Generation Sources

File	Primary Sources
`project.md`	README.md, CLAUDE.md, gap analyses, existing project.md
`architecture.md`	Build files, module globs, ADRs, CLAUDE.md architecture section
`documents.md`	Phase 5 doc scan results, spec files, gap analyses, ADRs

Step 4: Confirm and Write

Before writing each file:

1. Show current content (if exists) or "Does not exist" 2. Show proposed new content 3. Ask: "Write this to `{context_dir}/{filename}`?"

Create the .arkhe/roadmap/ directory if it doesn't exist.

Never overwrite without confirmation.

References

WORKFLOW.md — Detailed generation protocol per file
EXAMPLES.md — Usage examples
TROUBLESHOOTING.md — Common issues

Refresh Skill — Examples

Example 1: First-Time Init

Command: /roadmap:refresh init

Context: New project with no .arkhe/roadmap/ directory.

Output:

## Context Directory Status

| File | Exists | Staleness |
|------|--------|-----------|
| project.md | No | — |
| architecture.md | No | — |
| documents.md | No | — |

Scaffolding `.arkhe/roadmap/` with all 3 context files...

[Runs context discovery, generates project.md]

**Write this to `.arkhe/roadmap/project.md`?**
> Yes

[Generates architecture.md]

**Write this to `.arkhe/roadmap/architecture.md`?**
> Yes

[Generates documents.md]

**Write this to `.arkhe/roadmap/documents.md`?**
> Yes

Context directory scaffolded with 3 files.

Example 2: Check Mode — Detecting Stale Files

Command: /roadmap:refresh check

Output:

## Context Directory Status

| File | Exists | Staleness | Days | Commits Since | feat/fix |
|------|--------|-----------|------|---------------|----------|
| project.md | Yes | fresh | 3 | 2 | 0 |
| architecture.md | Yes | stale | 45 | 18 | 12 |
| documents.md | Yes | aging | 15 | 6 | 3 |

New modules not in architecture.md: payments, notifications

**Recommendations:**
- `architecture.md` is **stale** (45 days, 12 feat/fix commits). 2 new modules discovered.
  Run `/roadmap:refresh architecture` to regenerate.
- `documents.md` is **aging** (15 days, 3 feat/fix commits). Consider refreshing.
- `project.md` is **fresh**. No action needed.

Example 3: Refreshing architecture.md After Adding Modules

Command: /roadmap:refresh architecture

Output:

## Current architecture.md
[shows current content]

## Proposed architecture.md
[shows new content with updated module inventory, new ADRs, refreshed tech stack]

**Changes detected:**
- Added modules: payments (12 source, 4 test), notifications (8 source, 2 test)
- New ADR: ADR-0015 Payment Gateway Selection
- Updated module file counts

**Write this to `.arkhe/roadmap/architecture.md`?**
> Yes

architecture.md updated.

Example 4: Full Refresh After Major Release

Command: /roadmap:refresh all

Output:

## Context Directory Status

| File | Exists | Staleness | Days | Commits Since | feat/fix |
|------|--------|-----------|------|---------------|----------|
| project.md | Yes | stale | 60 | 45 | 22 |
| architecture.md | Yes | stale | 60 | 45 | 22 |
| documents.md | Yes | stale | 60 | 45 | 22 |

All files are stale. Regenerating all 3 files...

[Shows project.md diff, asks confirmation]
[Shows architecture.md diff, asks confirmation]
[Shows documents.md diff, asks confirmation]

All 3 context files regenerated.

#!/usr/bin/env python3
"""
Detect drift in .arkhe/roadmap/ context files.

Checks existence, staleness, and codebase changes since last update.
Outputs JSON report to stdout.

Usage:
    python3 detect_context_drift.py [project_root]
"""

import json
import sys
from datetime import datetime, timezone
from pathlib import Path

# Sibling import
sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import (
    CONTEXT_FILES,
    classify_staleness,
    detect_tech_stack,
    discover_modules,
    git_commits_since,
    git_feat_fix_commits_since,
    git_is_available,
    git_last_modified_date,
    git_latest_commit_date,
    load_config,
)


def parse_iso_date(iso_str: str) -> datetime:
    """Parse an ISO 8601 date string to datetime."""
    # Handle timezone offset format from git
    # Python 3.8 doesn't have datetime.fromisoformat for all formats
    clean = iso_str.strip()
    # Replace timezone offset like +00:00 or -04:00 for Python 3.8 compat
    if "+" in clean[10:] or clean.endswith("Z"):
        if clean.endswith("Z"):
            clean = clean[:-1] + "+00:00"
    try:
        # Python 3.10+ handles this natively
        return datetime.fromisoformat(clean)
    except ValueError:
        # Fallback: strip timezone for date-only comparison
        date_part = clean[:10]
        return datetime.strptime(date_part, "%Y-%m-%d").replace(tzinfo=timezone.utc)


def days_between(date_str: str) -> int:
    """Calculate days between a date string and now."""
    dt = parse_iso_date(date_str)
    now = datetime.now(timezone.utc)
    # Make both timezone-aware for comparison
    if dt.tzinfo is None:
        dt = dt.replace(tzinfo=timezone.utc)
    return max(0, (now - dt).days)


def check_file(file_name: str, context_dir: Path, project_root: str) -> dict:
    """Check a single context file for existence and staleness."""
    file_path = context_dir / file_name
    rel_path = str(file_path.relative_to(Path(project_root)))

    if not file_path.exists():
        return {"exists": False}

    result: dict = {"exists": True}

    last_mod = git_last_modified_date(rel_path, project_root)
    if last_mod:
        days = days_between(last_mod)
        result["last_modified"] = last_mod[:10]  # Date only
        result["staleness"] = classify_staleness(days)
        result["days_since_update"] = days
        result["commits_since"] = git_commits_since(rel_path, project_root)
        result["feat_fix_commits_since"] = git_feat_fix_commits_since(
            rel_path, project_root
        )
    else:
        # File exists but not in git (uncommitted)
        result["last_modified"] = None
        result["staleness"] = "uncommitted"
        result["days_since_update"] = 0
        result["commits_since"] = 0
        result["feat_fix_commits_since"] = 0

    return result


def detect_new_modules(
    context_dir: Path, project_root: Path, modules: list
) -> list:
    """Find modules not mentioned in architecture.md."""
    arch_file = context_dir / "architecture.md"
    if not arch_file.exists():
        return modules  # All modules are "new" if no architecture.md

    try:
        content = arch_file.read_text(encoding="utf-8").lower()
    except Exception:
        return modules

    new = []
    for mod in modules:
        if mod.lower() not in content:
            new.append(mod)
    return new


def main():
    """Main entry point."""
    project_root = sys.argv[1] if len(sys.argv) > 1 else "."
    project_root_path = Path(project_root).resolve()

    # Load config
    config = load_config(project_root_path)
    context_dir = project_root_path / config["context_dir"]

    # Check git availability
    has_git = git_is_available(str(project_root_path))

    # Build report
    report: dict = {
        "context_dir": config["context_dir"],
        "exists": context_dir.is_dir(),
        "git_available": has_git,
        "files": {},
        "new_modules": [],
        "tech_stack": detect_tech_stack(project_root_path),
        "config": config,
    }

    # Check each context file
    if has_git:
        for file_name in CONTEXT_FILES:
            report["files"][file_name] = check_file(
                file_name, context_dir, str(project_root_path)
            )

        # Detect new modules
        modules = discover_modules(project_root_path)
        report["discovered_modules"] = modules
        report["new_modules"] = detect_new_modules(
            context_dir, project_root_path, modules
        )
    else:
        # Without git, just check existence
        for file_name in CONTEXT_FILES:
            file_path = context_dir / file_name
            report["files"][file_name] = {"exists": file_path.exists()}
        report["discovered_modules"] = discover_modules(project_root_path)
        report["new_modules"] = report["discovered_modules"]

    # Latest codebase commit
    if has_git:
        latest = git_latest_commit_date(str(project_root_path))
        if latest:
            report["latest_commit"] = latest[:10]

    print(json.dumps(report, indent=2))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Shared utilities for the refresh skill scripts.

Config loading and git helpers. Python 3.8+, stdlib only.
"""

import subprocess
from pathlib import Path
from typing import Dict, List, Optional, Set


# Module directory patterns to discover
MODULE_DIR_PATTERNS: List[str] = [
    "apps/*", "src/*", "packages/*", "libs/*", "modules/*",
    "internal/*", "cmd/*",
]

# Build files that indicate tech stack
BUILD_FILES: Dict[str, str] = {
    "build.gradle.kts": "Java/Kotlin (Gradle)",
    "build.gradle": "Java/Kotlin (Gradle)",
    "pom.xml": "Java/Kotlin (Maven)",
    "package.json": "JavaScript/TypeScript (Node)",
    "Cargo.toml": "Rust",
    "go.mod": "Go",
    "pyproject.toml": "Python",
    "setup.py": "Python",
    "Gemfile": "Ruby",
    "mix.exs": "Elixir",
}

# Context files expected in the context directory
CONTEXT_FILES: List[str] = ["project.md", "architecture.md", "documents.md"]

# Staleness thresholds (days)
STALENESS_THRESHOLDS = {
    "fresh": 7,
    "aging": 30,
    "stale": 90,
}


def classify_staleness(days: int) -> str:
    """Classify staleness based on days since update."""
    if days <= STALENESS_THRESHOLDS["fresh"]:
        return "fresh"
    elif days <= STALENESS_THRESHOLDS["aging"]:
        return "aging"
    elif days <= STALENESS_THRESHOLDS["stale"]:
        return "stale"
    return "very_stale"


def read_yaml_section(path: Path, section: str) -> Optional[dict]:
    """Read a YAML file and extract a top-level section.

    Simple line-based parser (no PyYAML dependency).
    """
    try:
        content = path.read_text(encoding="utf-8")
    except Exception:
        return None

    lines = content.splitlines()
    in_section = False
    result: dict = {}
    current_key = None
    current_list: List[str] = []
    base_indent = 2

    for line in lines:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue

        indent = len(line) - len(line.lstrip())

        if indent == 0 and stripped.endswith(":"):
            if in_section:
                if current_key and current_list:
                    result[current_key] = current_list
                break
            if stripped == f"{section}:":
                in_section = True
            continue

        if not in_section:
            continue

        if indent < base_indent and not stripped.startswith("-"):
            if current_key and current_list:
                result[current_key] = current_list
            break

        if ":" in stripped and not stripped.startswith("-"):
            if current_key and current_list:
                result[current_key] = current_list
                current_list = []
            key, _, value = stripped.partition(":")
            current_key = key.strip()
            value = value.strip().strip('"').strip("'")
            if value:
                result[current_key] = value
                current_key = None
        elif stripped.startswith("- "):
            item = stripped[2:].strip().strip('"').strip("'")
            current_list.append(item)

    if in_section and current_key and current_list:
        result[current_key] = current_list

    return result if result else None


def load_config(project_root: Path) -> dict:
    """Load roadmap configuration from .arkhe.yaml."""
    config_path = project_root / ".arkhe.yaml"
    section = read_yaml_section(config_path, "roadmap")
    defaults = {
        "context_dir": ".arkhe/roadmap",
        "output_dir": "arkhe/roadmap",
        "status_file": "docs/PROJECT-STATUS.md",
    }
    if section:
        defaults.update(section)
    return defaults


def git_is_available(project_root: str) -> bool:
    """Check if git is available and the directory is a git repo."""
    try:
        result = subprocess.run(
            ["git", "rev-parse", "--is-inside-work-tree"],
            capture_output=True, text=True, timeout=5,
            cwd=project_root,
        )
        return result.returncode == 0
    except (subprocess.TimeoutExpired, FileNotFoundError):
        return False


def git_last_modified_date(file_path: str, project_root: str) -> Optional[str]:
    """Get the last commit date for a file (ISO 8601)."""
    try:
        result = subprocess.run(
            ["git", "log", "-1", "--format=%aI", "--", file_path],
            capture_output=True, text=True, timeout=10,
            cwd=project_root,
        )
        if result.returncode == 0 and result.stdout.strip():
            return result.stdout.strip()
    except (subprocess.TimeoutExpired, FileNotFoundError):
        pass
    return None


def git_latest_commit_date(project_root: str) -> Optional[str]:
    """Get the latest commit date in the repo (ISO 8601)."""
    try:
        result = subprocess.run(
            ["git", "log", "-1", "--format=%aI"],
            capture_output=True, text=True, timeout=10,
            cwd=project_root,
        )
        if result.returncode == 0 and result.stdout.strip():
            return result.stdout.strip()
    except (subprocess.TimeoutExpired, FileNotFoundError):
        pass
    return None


def git_commits_since(file_path: str, project_root: str) -> int:
    """Count commits since a file was last modified."""
    last_hash = _git_last_hash(file_path, project_root)
    if not last_hash:
        return 0
    try:
        result = subprocess.run(
            ["git", "log", f"{last_hash}..HEAD", "--oneline", "--no-merges"],
            capture_output=True, text=True, timeout=10,
            cwd=project_root,
        )
        if result.returncode == 0:
            lines = [l for l in result.stdout.strip().splitlines() if l.strip()]
            return len(lines)
    except (subprocess.TimeoutExpired, FileNotFoundError):
        pass
    return 0


def git_feat_fix_commits_since(file_path: str, project_root: str) -> int:
    """Count feat/fix commits since a file was last modified."""
    last_hash = _git_last_hash(file_path, project_root)
    if not last_hash:
        return 0
    try:
        result = subprocess.run(
            ["git", "log", f"{last_hash}..HEAD", "--oneline", "--no-merges"],
            capture_output=True, text=True, timeout=10,
            cwd=project_root,
        )
        if result.returncode == 0:
            count = 0
            for line in result.stdout.strip().splitlines():
                # Match conventional commits: hash feat: or hash fix:
                parts = line.split(" ", 1)
                if len(parts) > 1:
                    msg = parts[1]
                    if msg.startswith("feat") or msg.startswith("fix"):
                        count += 1
            return count
    except (subprocess.TimeoutExpired, FileNotFoundError):
        pass
    return 0


def _git_last_hash(file_path: str, project_root: str) -> Optional[str]:
    """Get the last commit hash for a file."""
    try:
        result = subprocess.run(
            ["git", "log", "-1", "--format=%H", "--", file_path],
            capture_output=True, text=True, timeout=10,
            cwd=project_root,
        )
        if result.returncode == 0 and result.stdout.strip():
            return result.stdout.strip()
    except (subprocess.TimeoutExpired, FileNotFoundError):
        pass
    return None


def discover_modules(project_root: Path) -> List[str]:
    """Discover top-level module directories."""
    modules: Set[str] = set()
    for pattern in MODULE_DIR_PATTERNS:
        for path in project_root.glob(pattern):
            if path.is_dir():
                modules.add(path.name)
    return sorted(modules)


def detect_tech_stack(project_root: Path) -> List[str]:
    """Detect tech stack from build files."""
    found: List[str] = []
    for filename, stack in BUILD_FILES.items():
        if (project_root / filename).exists():
            found.append(stack)
    return found

Refresh Skill — Troubleshooting

"No git history found"

Symptom: Script outputs "git_available": false or all staleness values are missing.

Cause: The project is not a git repository, or git is not installed.

Fix: Initialize git (git init && git add . && git commit -m "initial") or run in a git-managed project. Without git, the refresh skill can still scaffold files but cannot detect drift.

"Context files not detected" / Wrong path

Symptom: Script reports files don't exist, but you created them at a different path.

Cause: The context directory defaults to .arkhe/roadmap/. If your files are elsewhere, the script won't find them.

Fix: Set the custom path in .arkhe.yaml:

roadmap:
  context_dir: path/to/your/context

"Generated content is too generic"

Symptom: Context files have placeholder text instead of real project details.

Cause: The project lacks a README.md or CLAUDE.md with project information.

Fix: Create a README.md with project purpose, tech stack, and target audience before running /roadmap:refresh init. The more information in README.md and CLAUDE.md, the richer the generated context.

"No modules discovered"

Symptom: Module inventory is empty in architecture.md.

Cause: The project doesn't use standard directory patterns (apps/*, src/*, packages/*, etc.).

Fix: The skill will still generate architecture.md from build files and other sources. For non-standard layouts, manually add module information to the generated architecture.md after scaffolding.

"New modules listed but they're not real modules"

Symptom: Drift check reports "new modules" that are utility directories, not actual modules.

Cause: The detection script uses directory globs that may match non-module directories.

Fix: After refreshing architecture.md, review and remove irrelevant entries. The hybrid format is designed to be edited — the header notes "Edit freely."

"Permission denied running script"

Symptom: bash: permission denied when running the detection script.

Fix: Make scripts executable:

chmod +x plugins/roadmap/skills/refresh/scripts/*.py

Refresh Skill — Workflow

Detailed generation protocol and mode workflows for the Context Directory Refresh skill.

Drift Detection Algorithm

The detect_context_drift.py script checks:

1. Directory existence: Does .arkhe/roadmap/ exist? 2. File existence: Does each context file exist (project.md, architecture.md, documents.md)? 3. Git-based staleness: For each existing file:

Last modification date via git log -1 --format="%aI" -- {file}
Days since update compared to now
Classification: fresh (≤7d), aging (7-30d), stale (30-90d), very_stale (90+d)

4. Commit activity: Count total commits and feat/fix commits since file's last update 5. Module drift: Discover modules via directory globs and check if they appear in architecture.md

Mode Workflows

`check`

1. Run drift detection script 2. Present drift report table 3. Highlight files needing attention:

Missing files: "Not found — run /roadmap:refresh init to create"
Stale files (30+ days): "Stale — {N} feat/fix commits since last update"
New modules: "New modules not in architecture.md: {list}"

4. Stop — no writes

`init`

1. Run drift detection script 2. If .arkhe/roadmap/ already exists with files, warn: "Context directory already exists. Use all to regenerate or check to see drift." 3. Run full context discovery (CONTEXT_DISCOVERY.md Phases 1-7) 4. Generate all 3 files using the generation protocol below 5. Confirm and write each file

`all` / `project` / `architecture` / `documents`

1. Run drift detection script 2. Run full context discovery 3. If the target file exists, read current content for comparison 4. Generate the requested file(s) 5. Show diff (current vs proposed) and confirm before writing

_(no argument)_

1. Run drift detection script 2. Present drift report 3. Ask user which files to refresh (AskUserQuestion with multiSelect) 4. For each selected file, run generation + confirmation

Generation Protocol

project.md

Sources: README.md, CLAUDE.md, .arkhe/roadmap/project.md (if exists), gap analyses

Generation steps: 1. Read README.md — extract: project name, description, target audience, key features 2. Read CLAUDE.md — extract: project overview section, constraints, conventions 3. Glob for gap analyses — extract: user personas, pain points, domain terms 4. If existing project.md exists, preserve any user-added sections (## Custom sections) 5. Generate using hybrid format:

# Project Context
_Auto-generated by /roadmap:refresh on {date}. Edit freely — regenerate with `/roadmap:refresh project`._

## Summary
- **Project**: {name} — {one-sentence description}
- **Target users**: {personas or audience}
- **Domain**: {problem domain}
- **Current phase**: {phase/milestone if identifiable}
- **Key constraint**: {most important constraint}

## Personas
| Persona | Description | Key Needs |
|---------|-------------|-----------|
| {derived from README, gap analyses, or CLAUDE.md} |

## Domain & Constraints
- {constraint 1}
- {constraint 2}

## Project Phases
| Phase | Description | Status |
|-------|-------------|--------|
| {if identifiable from docs} |

## References
- `README.md` — Project overview and setup
- `CLAUDE.md` — Conventions and constraints
- {other relevant docs discovered}

architecture.md

Sources: Build files, module globs, ADRs, CLAUDE.md, framework detection

Generation steps: 1. Detect tech stack from build files (TECH_STACK_DETECTION.md) 2. Glob module directories — count source files and test files per module 3. Read ADR titles and status from docs/adr/**/*.md 4. Read CLAUDE.md — extract architecture overview, conventions 5. Detect framework patterns (TECH_STACK_DETECTION.md § Architecture-Specific Scanning) 6. Generate:

# Architecture Context
_Auto-generated by /roadmap:refresh on {date}. Edit freely — regenerate with `/roadmap:refresh architecture`._

## Summary
- **Stack**: {tech stack one-liner}
- **Architecture**: {pattern — e.g., "Modular monolith with hexagonal architecture"}
- **Modules**: {count} modules ({list top 5})
- **Database**: {DB type and migration tool}
- **Key pattern**: {most important architectural convention}

## Tech Stack
| Layer | Technology |
|-------|-----------|
| Backend | {framework, language} |
| Frontend | {framework, language} |
| Database | {DB, migration tool} |
| Build | {build tool} |
| CI/CD | {if detected} |

## Module Inventory
| Module | Source Files | Test Files | Notes |
|--------|------------|-----------|-------|
| {module} | {count} | {count} | {brief note} |

## Key Decisions (ADRs)
| ADR | Title | Status |
|-----|-------|--------|
| {number} | {title} | Accepted/Proposed/Superseded |

## Patterns & Conventions
- {pattern from CLAUDE.md or codebase detection}

## References
- `CLAUDE.md` — Project conventions and architecture overview
- `docs/adr/` — Architecture Decision Records
- {build file path} — Build configuration

documents.md

Sources: Phase 5 documentation scan, spec files, gap analyses, ADRs

Generation steps: 1. Glob all documentation files (docs, plan, specs patterns) 2. Categorize each file (status docs, gap analyses, specs, ADRs, research, reports) 3. Generate:

# Document Map
_Auto-generated by /roadmap:refresh on {date}. Edit freely — regenerate with `/roadmap:refresh documents`._

## Summary
- **Total docs**: {count} markdown files discovered
- **Categories**: {list of categories with counts}
- **Key docs**: {top 3-5 most important docs}

## Document Inventory

### Status Documents
| Document | Path | Description |
|----------|------|-------------|
| {name} | `{path}` | {one-line description} |

### Specifications
| Spec | Path | Status |
|------|------|--------|
| {name} | `{path}` | Proposed/Ready/In Progress/Complete |

### Architecture Decision Records
| ADR | Path | Status |
|-----|------|--------|
| {name} | `{path}` | Accepted/Proposed |

### Gap Analyses
| Document | Path | Description |
|----------|------|-------------|
| {name} | `{path}` | {one-line description} |

### Research
| Document | Path | Description |
|----------|------|-------------|
| {name} | `{path}` | {one-line description} |

## References
- {key doc paths with descriptions}

Preserving User Edits

When regenerating an existing context file: 1. Read the current file 2. Identify any sections NOT in the template (user-added custom sections) 3. Preserve those sections at the end of the regenerated file under ## Custom Sections (Preserved) 4. Always show the diff before writing