theseus-runtheseus-run/theseus/.agents/skills/roadmap-management/SKILL.md

roadmap-management

Skill1 starsChanged 6 months agoMITView on GitHub

Use when creating, updating, reviewing, or promoting Theseus roadmap items, including public roadmap notes, internal roadmap status maps, planning lanes, GitHub issue readiness, and OSS roadmap hygiene.

4 other projects use a version of this.

Adopted by

Most recently taken up by

insight68/Skillstheir own version, first seen Nov 8, 2026
akachandan1/proofstacktheir own version, first seen Oct 11, 2026
Luis85/agentic-workflowtheir own version, first seen May 9, 2026
ichuan/skillstheir own version, first seen Feb 3, 2026

Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
insight68/Skills★ 5same name
ichuan/skills★ 1same name
akachandan1/proofstack★ 0same name
Luis85/agentic-workflow★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-self-checkSkill
- biome-grit-rulesSkill
- biome-toolingSkill
- bun-testSkill
- bun-workspaceSkill
- cleanup-auditSkill
- code-reviewSkill
- dispatch-satelliteSkill
- docs-managementSkill
- docs-readingSkill
- effect-concurrency-lifecycleSkill
- effect-errors-schemaSkill
- effect-observability-timeSkill
- effect-services-layersSkill
- effect-testing-runtimeSkill
- effect-v4Skill
- jsx-md-authoringSkill
- monorepo-maintenanceSkill
- refactoring-disciplineSkill
- runtime-engineSkill
- server-runtimeSkill
- testing-patternsSkill
- theseus-designSkill
- tool-authoringSkill
- typescript-strictSkill
- ui-layout-disciplineSkill
- theseus-designSkill

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 6 are distinctive, and 11 are very specific to this project.

0
Common
Most of the 4 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Use this skill when roadmap or planning work changes what Theseus says it is building next.
line 8
Very specific:
If an item concerns implementation, verify against source before marking it shipped, active, or next.
line 24
Very specific:
Do not put loose ideation in the roadmap.
line 34
Distinctive:
Use one status per item:
line 39
Very specific:
Avoid future. It hides whether an item is designed, research, blocked, or parked.
line 50
Distinctive:
Do not promote directly from brainstorm to active.
line 61
Very specific:
Do not mark next without a done when test.
line 62
Very specific:
Do not mark active without an owner and evidence that work has started.
line 63
Very specific:
Do not mark shipped unless code, tests/checks, and docs agree.
line 64
Very specific:
When promoting or demoting, update roadmap-status-map.md in the same pass.
line 65
Distinctive:
Every roadmap-ready item needs:
line 69
Very specific:
If done when cannot be written, the item belongs in research, drafts, or brainstorms, not next.
line 78
Very specific:
Prefer Now / Next / Later / Not Planned over dates.
line 85
Distinctive:
Do not imply timelines unless the project intends to carry timeline pressure.
line 88
Distinctive:
Keep roadmap items tied to user-visible or contributor-visible value.
line 89
Distinctive:
After roadmap doc edits, run:
line 93
Very specific:
Use docs-management rules for links, frontmatter, folder placement, and status separation.
line 99

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Theseus Roadmap Management

Use this skill when roadmap or planning work changes what Theseus says it is building next.

Roadmap work is status management, not aspiration capture. Keep current truth, planned work, research, and rejected paths separate.

Read Order

Start with:

docs/direction/roadmap.md
docs/maps/roadmap-status-map.md
docs/maps/runtime-truth-map.md
docs/maps/not-real-yet.md
the owning concept note for the roadmap item

If an item concerns implementation, verify against source before marking it shipped, active, or next.

Roadmap Artifacts

docs/direction/roadmap.md: concise public-facing roadmap.
docs/maps/roadmap-status-map.md: internal evidence table and promotion state.
GitHub issues: execution units only after the item is actionable.
GitHub milestones/projects: sequencing containers, not doctrine.

Do not put loose ideation in the roadmap. Move it to docs/brainstorms or docs/drafts first.

Status Vocabulary

Use one status per item:

shipped: implemented and verified.
active: currently being built.
next: intended soon and clear enough to plan.
designed: accepted direction, not scheduled.
research: needs investigation, prototype, or decision.
blocked: dependency or unresolved decision is known.
parked: not rejected, but not worth attention now.
rejected: deliberately not doing.

Avoid future. It hides whether an item is designed, research, blocked, or parked.

Promotion Pipeline

brainstorm -> draft -> designed -> next -> active -> shipped

Promotion rules:

Do not promote directly from brainstorm to active.
Do not mark next without a done when test.
Do not mark active without an owner and evidence that work has started.
Do not mark shipped unless code, tests/checks, and docs agree.
When promoting or demoting, update roadmap-status-map.md in the same pass.

Item Shape

Every roadmap-ready item needs:

status
owner
source docs
evidence or current implementation note
dependency or blocker, if any
done when criteria

If done when cannot be written, the item belongs in research, drafts, or brainstorms, not next.

OSS Posture

For public docs:

Prefer Now / Next / Later / Not Planned over dates.
Publish less than the internal status map knows.
State non-promises explicitly.
Do not imply timelines unless the project intends to carry timeline pressure.
Keep roadmap items tied to user-visible or contributor-visible value.

Verification

After roadmap doc edits, run:

bun run docs:check

Use docs-management rules for links, frontmatter, folder placement, and status separation.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free