Agent skill

refresh

Detect drift in .arkhe/roadmap/ context files and regenerate them from the current codebase state. Scaffolds context directory if missing. Use when user runs /roadmap:refresh, mentions "refresh context", "update context", "init roadmap", "stale context", or "scaffold roadmap".

View SKILL.md on GitHub Repository
Stars 9
Forks 1

Install this agent skill to your Project

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

SKILL.md

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:

bash
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

markdown
# {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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

joaquimscosta/arkhe-claude-plugins

Skill Name

What this skill does. Use when user mentions "keyword1", "keyword2", or "keyword3". Keep under 1,024 characters and include specific trigger keywords.

9 1
Explore
joaquimscosta/arkhe-claude-plugins

plugin-release-checker

9 1
Explore
joaquimscosta/arkhe-claude-plugins

skill-validator

Validate skills against Anthropic best practices for frontmatter, structure, content, file organization, hooks, MCP, and security (62 rules in 8 categories). Use when creating new skills, updating existing skills, before publishing skills, reviewing skill quality, or when user mentions "validate skill", "check skill", "skill best practices", "skill review", or "lint skill".

9 1
Explore
joaquimscosta/arkhe-claude-plugins

sync-docs

Sync official Anthropic documentation and analyze impact on project components. Runs docs/reference/update-claude-docs.sh, computes diffs, and reports impacts on the skill validator, plugins, and project documentation. Use when user mentions "sync docs", "update reference docs", "refresh docs", or "check doc changes".

9 1
Explore
joaquimscosta/arkhe-claude-plugins

research-frontmatter

Enforce standard YAML frontmatter on research documents in docs/research/. Use when creating, editing, or promoting research files, when user mentions "research metadata", "research frontmatter", or "research staleness".

9 1
Explore
joaquimscosta/arkhe-claude-plugins

deep-research

Deep research on technical topics using EXA tools with intelligent two-tier caching. Use when user asks to research a topic, investigate best practices, look up information, find patterns, or explore architectures. Also invoked by /research command. Triggers: "research", "look up", "investigate", "deep dive", "find information about", "what are best practices for", "how do others implement".

9 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results