auto-rolling-roadmap
Maintain ROADMAP.md as the project's living product, architecture, and long-horizon development checkpoint. Use when steering project direction, updating roadmap checkpoints, or resolving code soup drift.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-30
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- auto-rolling-roadmap
- description
- Maintain ROADMAP.md as the project's living product, architecture, and long-horizon development checkpoint. Use when steering project direction, updating roadmap checkpoints, or resolving code soup drift.
03 SKILL.md 正文
DietCode Skill: Auto-Rolling Roadmap Checkpoint System
Skill Purpose
Maintain an evolving ROADMAP.md file that acts as the project's living product, architecture, and long-horizon development checkpoint.
This skill exists to prevent code soup, preserve project coherence, and keep long-running development aligned around a clear center of gravity.
The roadmap is not a wishlist.
The roadmap is not a backlog.
The roadmap is not a promise.
The roadmap is the project's steering surface.
It should help humans and agents answer:
- What is this project becoming?
- What matters now?
- What should happen next?
- What should remain deferred?
- What changed recently?
- What risks are accumulating?
- Is the system becoming more coherent or more fragmented?
Primary Output
This skill must create or update:
ROADMAP.md
ROADMAP.md is the canonical checkpoint file for long-horizon project steering.
If the file does not exist, create it.
If the file exists, evolve it carefully.
Do not replace useful history with generic text.
Do not append endlessly.
Do not turn the roadmap into a backlog dump.
Each update should make the roadmap more useful, more current, and easier to navigate.
Prime Directive
Every roadmap pass must answer:
Did the latest work strengthen or weaken the project's center of gravity?
If the answer is unclear, the skill must investigate before adding or promoting roadmap items.
A roadmap item that does not connect to the project's center of gravity should remain in Discovery, be reframed, or be archived.
Definition: Center of Gravity
The project's center of gravity is the smallest set of concepts, workflows, abstractions, and operational paths that explain how the system fundamentally works.
A strong center of gravity means:
- there is one obvious way to perform core operations
- agents can predict where changes belong
- contributors can understand the system without reading everything
- new features attach to existing architecture instead of creating parallel systems
- operational behavior is inspectable
- maintenance burden stays bounded
- long-term development feels navigable
A weak center of gravity means:
- duplicate abstractions appear
- multiple workflows compete
- state ownership becomes unclear
- debugging paths fragment
- agents invent local patterns
- hidden orchestration grows
- roadmap direction becomes disconnected from implementation reality
Core Philosophy
Centralization does not mean giant files, giant classes, or rigid architecture.
Centralization means clear authority.
Modules may be distributed.
Authority should not be.
The roadmap should continuously protect:
- canonical workflows
- canonical mutation paths
- canonical runtime inspection
- canonical state ownership
- canonical terminology
- canonical architectural intent
The system should feel extensible without becoming incoherent.
Required Inputs
When invoked, inspect available project context before editing ROADMAP.md.
Use any available sources such as:
- existing
ROADMAP.md - README files
- architecture docs
- recent commits
- changed files
- tests
- scripts
- issue notes
- implementation summaries
- failing commands
- current user request
- agent output logs
- TODOs or FIXME markers
- package/config changes
Do not rely only on the user's latest request if project artifacts are available.
Do not invent project state.
If evidence is missing, mark uncertainty explicitly.
Per-Project Identity (DietCode native integration)
Every roadmap tool response is scoped to the Hermes project workspace, not
the DietCode plugin install tree. Read these fields before editing:
| Field | Use |
|---|---|
project_identity_line |
One-line header: project brief · stack · verify command |
project_steering_digest |
Entity card: CI, quality tools, governance, verify, bootstrap status |
project_fingerprint |
Raw signals in checkpoint evidence (README title, archetype, Makefile targets, …) |
bootstrap_fill_plan |
When template phrases remain — use tasks[].suggested_replacement |
Prefer evidence-backed replacements over generic text. When placeholders remain,
call roadmap(action='apply_bootstrap_fill') before manual edits.
Operator reference: docs/roadmap.md in the DietCode plugin tree.
Key doc sections for agents:
- 12-section schema — required headings and enumerated health/soup values
- Example payloads — shape of
guide,checkpoint, andvalidateresponses - Bootstrap fill —
bootstrap_fill_plan.tasks[].suggested_replacement - Write guard — ROADMAP.md only at
{workspace}/ROADMAP.md - Anti-patterns — backlog dumping, skipping §9 audit, plugin-tree writes
Required Update Algorithm
Follow this sequence on every roadmap pass:
- Read the existing
ROADMAP.md, if present. - Identify the current stated center of gravity.
- Inspect recent project changes and available evidence.
- Determine whether the project is coherent, accelerating, drifting, fragmenting, blocked, or overloaded.
- Compare current work against the existing roadmap.
- Preserve valid strategic intent.
- Remove duplicate or stale roadmap entries.
- Archive items that no longer deserve active attention.
- Promote items only when evidence supports promotion.
- Demote items when uncertainty, risk, or entropy increases.
- Add new items only when they connect to the center of gravity.
- Rewrite technical implementation details into clear product and architecture language.
- Run a centralization and code soup audit.
- Update the recent checkpoint.
- Add decision log entries for meaningful direction changes.
- Return a concise summary of what changed.
ROADMAP.md Required Structure
The file should use this structure.
# ROADMAP.md
## 1. Project Center of Gravity
## 2. Roadmap Health
## 3. Strategic Narrative
## 4. Now
## 5. Next
## 6. Later
## 7. Discovery
## 8. Maintenance Gravity
## 9. Centralization & Code Soup Audit
## 10. Decision Log
## 11. Recent Checkpoint
## 12. Archive
Do not rename these top-level sections unless the user explicitly requests a different schema.
The consistency of the schema is part of the skill's value.
Section Contract
1. Project Center of Gravity
Describe what the project fundamentally is.
This section should be understandable to a non-technical stakeholder while still useful to an engineer or agent.
Include:
## 1. Project Center of Gravity
**Core Purpose:**
<plain-language purpose>
**Primary Users / Operators:**
<who uses or operates this system>
**Canonical Architecture:**
<short description of the main architectural shape>
**Canonical Workflows:**
<the main flows agents and humans should preserve>
**Primary Runtime / Operational Center:**
<where operational truth lives>
**What This Project Must Not Become:**
<anti-goals that protect coherence>
The "must not become" field is mandatory.
It prevents drift.
Examples:
- must not become a scattered collection of scripts
- must not become another generic AI IDE
- must not create multiple competing orchestration systems
- must not hide mutations behind invisible automation
- must not trade inspectability for convenience
2. Roadmap Health
Give the current health state.
Allowed statuses:
Coherent
Accelerating
Drifting
Fragmenting
Blocked
Overloaded
Recovering
Use exactly one primary status.
Format:
## 2. Roadmap Health
**Status:** Coherent / Accelerating / Drifting / Fragmenting / Blocked / Overloaded / Recovering
**Summary:**
<brief explanation>
**Why This Status:**
- <evidence>
- <evidence>
- <evidence>
**Primary Risk:**
<single biggest risk>
**Primary Opportunity:**
<single biggest opportunity>
3. Strategic Narrative
Explain what the project is becoming.
This should be short, clear, and directional.
Avoid vague hype.
Format:
## 3. Strategic Narrative
<2-5 paragraphs explaining the current product / architecture direction>
The narrative should clarify:
- what changed recently
- what the system is converging toward
- what should be protected
- what should be avoided
4. Now
Active, committed, or already-in-motion work.
Only include items that are ready for execution or currently underway.
Do not include vague ideas.
Each item must use this format:
### N. <Item Title>
**Goal:**
<what this work accomplishes>
**Why It Matters:**
<product, architecture, user, or maintenance value>
**Current State:**
<known state from evidence>
**Next Concrete Action:**
<one specific next action>
**Success Signal:**
<how we know this worked>
**Gravity Impact:** Strengthens / Neutral / Weakens / Unknown
**Centralization Effect:** Centralizes / No Change / Decentralizes
**Entropy Risk:** Low / Medium / High
**Risk / Mitigation:**
<risk and mitigation>
Rules for Now:
- keep it small
- prefer 1-5 items
- each item must be actionable
- each item must have evidence
- each item must connect to the center of gravity
If there are more than 5 Now items, the roadmap is overloaded.
5. Next
Likely upcoming work.
These are prepared but not fully committed.
Format:
### N. <Item Title>
**Opportunity:**
<what could be unlocked>
**Why Soon:**
<why this may matter after Now>
**Dependency:**
<what must happen first>
**First Validation Step:**
<smallest way to test whether this deserves promotion>
**Confidence:** High / Medium / Low
**Gravity Impact:** Strengthens / Neutral / Weakens / Unknown
**Centralization Effect:** Centralizes / No Change / Decentralizes
**Entropy Risk:** Low / Medium / High
Rules for Next:
- do not pretend Next is committed
- include validation steps
- use confidence labels
- avoid implementation rabbit holes
6. Later
Long-horizon possibilities.
These are strategic directions, not promises.
Format:
### N. <Direction Title>
**Direction:**
<what this could become>
**Potential Upside:**
<why it may matter>
**Why Not Now:**
<why it remains deferred>
**Promotion Trigger:**
<what evidence would move this into Next>
**Entropy Risk:** Low / Medium / High
Rules for Later:
- keep speculative work out of Now
- preserve interesting possibilities without letting them hijack execution
- include promotion triggers so Later does not become a junk drawer
7. Discovery
Questions, experiments, unknowns, and ambiguous ideas.
Discovery exists to protect the roadmap from false certainty.
Format:
### N. <Question or Investigation>
**Question:**
<what needs to be understood>
**Evidence Needed:**
<what would clarify this>
**Possible Outcomes:**
- <outcome>
- <outcome>
- <outcome>
**Decision Needed:**
<what decision this discovery should eventually support>
Rules for Discovery:
- vague ideas belong here, not Now
- technical uncertainty belongs here
- product uncertainty belongs here
- architectural ambiguity belongs here
8. Maintenance Gravity
Track places where complexity, confusion, or fragility is accumulating.
Format:
## 8. Maintenance Gravity
### Hotspots
| Area | Symptom | Risk | Recommended Action |
|---|---|---|---|
| <area> | <symptom> | Low/Medium/High | <action> |
### Repeated Friction
- <bug, workflow issue, agent confusion, or maintenance pattern>
### Documentation Gaps
- <missing or stale docs>
### Agent Confusion Points
- <places agents are likely to patch incorrectly>
Maintenance gravity is not shame.
It is early warning.
The purpose is to detect entropy before it becomes structural collapse.
9. Centralization & Code Soup Audit
Evaluate whether the project is becoming more or less coherent.
Use this checklist:
## 9. Centralization & Code Soup Audit
**Overall Code Soup Risk:** Low / Medium / High
### Canonical Path Integrity
- Are there multiple ways to perform the same operation?
- Are there duplicate APIs, scripts, commands, or workflows?
- Is the correct path obvious?
**Assessment:**
<answer>
### Authority Boundaries
- Where does runtime authority live?
- Where does state authority live?
- Where does mutation authority live?
- Where does diagnostic authority live?
**Assessment:**
<answer>
### Structural Drift
- Did recent work introduce isolated patterns?
- Did it create one-off abstractions?
- Did it bypass existing architecture?
**Assessment:**
<answer>
### Agent Coherence
- Would a future agent know where to patch?
- Would a future agent reuse the canonical path?
- Did recent work make agent behavior safer or more chaotic?
**Assessment:**
<answer>
### Centralization Recommendation
<one recommendation to strengthen project gravity>
This section is mandatory.
If the roadmap does not audit code soup risk, the skill failed.
10. Decision Log
Record meaningful product, architecture, and workflow decisions.
Format:
## 10. Decision Log
### YYYY-MM-DD — <Decision Title>
**Decision:**
<what was decided>
**Reason:**
<why>
**Impact:**
<what changes because of this>
**Follow-up:**
<what should happen next>
Rules:
- add entries only for meaningful decisions
- do not log every tiny change
- do not rewrite history casually
- preserve old decisions unless they are clearly obsolete
- if a decision is reversed, add a new entry instead of deleting the old one
11. Recent Checkpoint
Summarize the latest roadmap update.
Format:
## 11. Recent Checkpoint
**Date:** YYYY-MM-DD
**Checkpoint Summary:**
<what changed this pass>
**Moved:**
- <item moved from one section to another>
**Added:**
- <new item>
**Updated:**
- <existing item updated>
**Archived:**
- <archived item>
**Code Soup Risk:** Low / Medium / High
<brief reason>
**Recommended Next Move:**
<one concrete action>
Only one Recent Checkpoint should exist.
When updating, replace the previous Recent Checkpoint with the latest one.
Older meaningful changes should be preserved in the Decision Log or Archive.
12. Archive
The archive stores removed, deferred, killed, or superseded roadmap items.
Format:
## 12. Archive
### <Archived Item>
**Archived Date:** YYYY-MM-DD
**Reason:**
<why it was removed from active attention>
**Restore Condition:**
<what would justify bringing it back>
Rules:
- archive instead of deleting when strategic memory matters
- delete only if the item was duplicate, noise, or clearly useless
- archive stale speculative work
- archive work that weakens center of gravity without sufficient upside
Roadmap Item Scoring
Every Now, Next, and Later item must include gravity metadata.
Use these exact labels.
Gravity Impact
Strengthens
Neutral
Weakens
Unknown
Meaning:
- Strengthens: reinforces the project center of gravity
- Neutral: does not meaningfully affect coherence
- Weakens: fragments authority, duplicates systems, or increases drift
- Unknown: not enough evidence yet
Centralization Effect
Centralizes
No Change
Decentralizes
Meaning:
- Centralizes: moves authority, diagnostics, workflow, or state closer to canonical surfaces
- No Change: does not affect centralization
- Decentralizes: creates new authority surfaces, parallel paths, or hidden behavior
Entropy Risk
Low
Medium
High
Meaning:
- Low: unlikely to create maintenance burden
- Medium: manageable but requires attention
- High: likely to create fragmentation, confusion, or long-term maintenance cost
Promotion and Demotion Rules
Promote Discovery to Next only when:
- the question is clear
- evidence exists
- the opportunity connects to the center of gravity
- the first validation step is known
- entropy risk is understood
Promote Next to Now only when:
- dependencies are resolved
- the next action is concrete
- success signal is clear
- the work is aligned with current strategy
- the roadmap has capacity
Demote Now to Next when:
- work is blocked
- confidence drops
- dependencies are missing
- implementation risk grows
- it no longer fits the current center of gravity
Move anything to Archive when:
- it is stale
- it duplicates another item
- it weakens project gravity
- it belongs to an older strategy
- it is not worth preserving in active attention
Anti-Bloat Rules
The roadmap must evolve by compression.
Do not allow ROADMAP.md to grow endlessly.
On every pass:
- merge duplicate items
- remove stale wording
- shorten old sections
- archive outdated ideas
- preserve only useful strategic memory
- keep Now small
- keep Next realistic
- keep Later intentional
- keep Discovery honest
If a section becomes too large, summarize it.
If an item has no next action, confidence, trigger, or evidence, it probably does not belong in Now or Next.
Non-Technical Navigation Rules
The roadmap must be readable by non-technical users.
Use plain language first.
Technical details may appear only when they clarify direction, risk, or ownership.
Prefer:
"Create one canonical patch pathway for agents."
Over:
"Refactor RPC mutation handler abstractions across adapter modules."
The implementation details can live in issues, commits, or engineering docs.
The roadmap should explain why the work matters.
Agent Governance Rules
Agents using this roadmap must optimize for coherence before completion.
Agents should:
- reuse existing architecture
- extend canonical systems
- preserve naming patterns
- avoid parallel workflows
- centralize diagnostics
- centralize mutation paths
- reduce hidden behavior
- improve inspectability
- document decisions
- archive stale ideas
Agents must avoid:
- inventing new architecture without justification
- creating duplicate utility layers
- creating local orchestration systems
- scattering state ownership
- hiding behavior behind convenience wrappers
- adding speculative roadmap items as commitments
- turning Discovery into Now without evidence
- treating the roadmap as a task dump
Code Soup Detection Heuristics
Flag code soup risk when any of the following appear:
- multiple files doing the same job
- multiple commands for the same workflow
- multiple sources of truth
- repeated helper functions
- unclear ownership of state
- new abstractions with no clear gravity well
- duplicated configuration
- inconsistent naming
- hidden side effects
- new scripts bypassing canonical runtime behavior
- agents repeatedly patching the same area differently
- debugging requires jumping across unrelated systems
When detected, recommend convergence.
Convergence may mean:
- merge duplicate paths
- document the canonical path
- delete dead paths
- create a single command surface
- route behavior through the existing runtime
- centralize diagnostics
- collapse abstractions
- rename for clarity
- archive roadmap work that causes fragmentation
Update Style
When editing ROADMAP.md:
- be concise
- be specific
- preserve useful history
- remove noise
- use stable headings
- avoid hype
- avoid generic PM language
- avoid massive bullet lists unless necessary
- prefer fewer, stronger items
- make uncertainty visible
- make next actions concrete
The tone should feel like a calm senior product strategist, staff engineer, and technical program manager reviewed the system together.
Required Final Assistant Response
After updating or drafting ROADMAP.md, respond with this summary:
## Roadmap Checkpoint Updated
**Health:** <status>
**Center of Gravity:**
<one-sentence summary>
**Moved:**
- <items moved between sections, or "None">
**Added:**
- <new items, or "None">
**Updated:**
- <updated items, or "None">
**Archived:**
- <archived items, or "None">
**Code Soup Risk:** Low / Medium / High
<brief reason>
**Recommended Next Move:**
<one concrete action>
Do not include the full roadmap in the final response unless the user asks for it.
The final response should summarize the checkpoint, not duplicate the file.
Failure Modes
This skill fails if it:
- creates a generic roadmap
- produces a giant backlog
- ignores center of gravity
- skips the code soup audit
- invents project state
- hides uncertainty
- promotes vague ideas into Now
- deletes strategic memory without reason
- decentralizes authority without mitigation
- makes the roadmap harder to read
- treats implementation activity as automatic strategic progress
Success Definition
This skill succeeds when ROADMAP.md becomes the project's living steering checkpoint.
A successful roadmap should:
- preserve strategic memory
- clarify current direction
- prevent code soup
- expose maintenance gravity
- guide agents toward canonical paths
- make long-term development navigable
- help non-technical users understand what matters
- help technical users understand where changes belong
- reduce cognitive burden over time
The highest goal is not more planning.
The highest goal is sustained coherence under long-horizon, agent-assisted development.
DietCode Plugin Integration
When the DietCode plugin is active:
- Call
roadmap(action='guide')to learn phase, health,_roadmap_operator_hints, andagent_next_call. - Call
roadmap(action='cockpit')or/roadmap cockpitfor a one-screen operator summary. - Call
roadmap(action='checkpoint', context=…)before editingROADMAP.md— returns evidence,code_soup_pre_audit, and the 16-step algorithm. - Call
roadmap(action='template')when bootstrapping the firstROADMAP.md— returnsproject_steering_digestandbootstrap_autofill_preview. - When bootstrap template phrases remain, call
roadmap(action='apply_bootstrap_fill')to preview evidence-backed replacements; passcontext='write'to apply, thenroadmap(action='validate'). - Use
project_steering_digestandbootstrap_fill_plan.tasks[].suggested_replacementfor per-project fill — each task maps template text to README/git/fingerprint evidence. - After editing, call
roadmap(action='validate')to confirm schema compliance before finishing. - Call
roadmap(action='doctor')to install the skill and run production health checks. - Call
roadmap(action='evidence')for a read-only evidence bundle withproject_fingerprint. - Call
roadmap(action='status')to parse the current roadmap without mutating it. - Call
roadmap(action='explain_gate')or/roadmap explain-gatewhen schema or freshness gates block progress (kernel explain-gate analogue). - Call
joyzoning(action='roadmap')for a native cockpit brief inside governed sessions.
Workspace state persists at .dietcode/roadmap-state.json after each validate pass.
The bundled default skill (auto-rolling-roadmap) ships with the extension and is registered automatically when dietcode.roadmap.auto_install_skills is enabled (default: true). It is not copied into workspaces.
Throughput model (industry-standard progressive disclosure):
- Metadata — listed in the SKILLS prompt section for optional user skills only; bundled roadmap is omitted when ROADMAP_STEERING is active (no duplicate surface).
- Instructions — loaded on-demand via
use_skill; bundled roadmap returns a lean execution digest (~30 lines), not the full 962-line reference. - Reference — full SKILL.md remains bundled for deep checkpoint algorithm detail when needed.
Execution authority: Continue the user's I/O loop. Roadmap governance clears at attempt_completion — no mid-task validate/doctor unless completion is blocked.
Operator smoke: python scripts/roadmap_smoke.py · python scripts/roadmap_operator_smoke.py
04 同仓库更多 Skills
starter-skill
Foundational skill template demonstrating procedural steps and safety guardrails.
security-sentinel
Security sentinel that analyzes ASTs for injection risks, verifies file path sandboxing, and prevents command tampering.
performance-auditor
A high-throughput performance auditor that verifies zero-GC boundaries, memory slab invariants, and hot-path execution latencies.
code-refactor
Clean architecture refactoring specialist enforcing SOLID principles, strict TypeScript interfaces, and zero barrel imports.
adversarial-auditor
Adversarial auditor that red-teams technical plans, asserts fail-closed factual provenance, decomposes cognitive token spend, and prevents premature completion.
golden-cartridge-protocol
Optimize for verified engineering value with finite context, execution, mutation, and review capacity.