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:
- Show current content (if exists) or "Does not exist"
- Show proposed new content
- 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