From on-loop
Manages roadmap state files — initialization, phase transitions, step tracking, and schema validation
How this skill is triggered — by the user, by Claude, or both
Slash command
/on-loop:roadmap-stateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill manages the `roadmap/.state/<feature>.json` lifecycle: creation, phase transitions, step tracking, and validation.
This skill manages the roadmap/.state/<feature>.json lifecycle: creation, phase transitions, step tracking, and validation.
roadmap/<feature-slug>.mdroadmap/.state/<feature-slug>.jsonroadmap/.state/_global.jsonAll paths are relative to the project root.
{
"version": "1.0",
"feature": "<feature-slug>",
"feature_title": "<Human Readable Feature Title>",
"roadmap_file": "roadmap/<feature-slug>.md",
"created_at": "<ISO 8601>",
"updated_at": "<ISO 8601>",
"current_phase": 1,
"total_phases": 4,
"phases": {
"1": {
"title": "Phase Title",
"status": "not-started",
"branch": "feature/<slug>-phase-1",
"depends_on": [],
"started_at": null,
"completed_at": null,
"steps": {
"1": {
"title": "Step description",
"status": "not-started",
"parallel": true,
"exclusive": false,
"conflicts_with": [],
"files": ["path/to/file.py"],
"assigned_session": null,
"started_at": null,
"completed_at": null
}
},
"steps_total": 5,
"steps_completed": 0
}
},
"locks": {},
"sessions": {},
"last_activity": "<ISO 8601>"
}
| Status | Meaning |
|---|---|
not-started | Step has not been picked up |
in-progress | Step is locked by a session and being worked on |
complete | Step finished successfully |
failed | Step failed after agent pipeline execution |
blocked | Step cannot proceed due to dependency |
| Status | Meaning |
|---|---|
not-started | No steps have been started |
in-progress | At least one step is in-progress or complete, but not all |
complete | All steps are complete |
blocked | Phase depends on an incomplete phase |
When /on-prepare creates a new roadmap:
<feature-slug> by slugifying the feature title (lowercase, hyphens, max 50 chars)roadmap/.state/<feature-slug>.json with all phases set to not-startedcurrent_phase to 1When any command reads state:
roadmap/.state/<feature-slug>.jsonversion field is "1.0"If the file does not exist or is invalid JSON, report an error and suggest running /on-prepare first.
When /on-continue needs the next available step:
current_phase index)complete, advance current_phase to the next non-complete phasecomplete, in-progress, or blocked
b. For each not-started step, check parallelism constraints:
exclusive: true and any other step in the phase is in-progress, skipconflicts_with lists step IDs that are in-progress, skipparallel: true (and not exclusive/conflicting), it is eligible
c. Return the first eligible stepWhen /on-continue starts a step:
in-progressassigned_session to the current session IDstarted_at to current timestampin-progress and phase started_atWhen /on-continue finishes a step:
completecompleted_at to current timestampsteps_completedassigned_sessionsteps_completed equals steps_total, set phase status to complete and completed_atWhen a step's agent pipeline fails:
failedassigned_sessionThe step can be retried by a subsequent /on-continue invocation (it will be treated like not-started).
When all steps in a phase are complete:
completecompleted_atdepends_on phases are completecurrent_phase to that phase indexEvery write to the state file must:
updated_at to current ISO 8601 timestamplast_activity to current ISO 8601 timestampversion must be "1.0"feature must be a non-empty string matching the slug formatroadmap_file must point to an existing filecurrent_phase must reference a valid phase keysteps_completed must equal the actual count of steps with status completedepends_on must reference valid phase keysinput: "User Management API v2"
1. lowercase: "user management api v2"
2. replace non-alphanumeric with hyphens: "user-management-api-v2"
3. collapse multiple hyphens: "user-management-api-v2"
4. trim leading/trailing hyphens: "user-management-api-v2"
5. truncate to 50 chars: "user-management-api-v2"
output: "user-management-api-v2"
To find which features exist:
.json files in roadmap/.state/ (excluding _global.json)npx claudepluginhub joestein/on-loop --plugin on-loopProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.