add-to-roadmap

/add-to-roadmap

Add a new task item to a named phase or section in ROADMAP.md.

Arguments: $ARGUMENTS

Parse $ARGUMENTS by splitting on the first occurrence of :: (space, double-colon, space). Left side (trimmed) → <phase-or-section>. Right side (trimmed) → <task-text>. If :: is absent, stop immediately with:

"Malformed arguments: expected <phase-or-section> :: <task-text> — the :: separator is missing."

---

Locating ROADMAP.md

Start at CWD and walk up the directory tree, checking each directory for a file named exactly ROADMAP.md. Stop walking at the git repository root:

REPO_ROOT=$(git rev-parse --show-toplevel) || exit 1

If git rev-parse fails (not a git repository), stop with:

"Not a git repository. /add-to-roadmap requires a git repo at CWD."

Walking up: check $CWD/ROADMAP.md, then $CWD/../ROADMAP.md, and so on, stopping at $REPO_ROOT inclusive. If ROADMAP.md is not found in any of those directories, stop with:

"ROADMAP.md not found anywhere between CWD and the repository root ($REPO_ROOT). Create one or move to a subdirectory of a repo that has one."

---

Address-space resolution

Parsing headers

Scan every line of ROADMAP.md. Collect all addressable headers:

• ## Phase N — ... lines → Phase headers (level 2).
• ### ... lines → Subsection headers (level 3).

Build an ordered list of (header_text, start_line) tuples. header_text is the full text after ## or ### (without the # prefix or trailing whitespace).

Fuzzy contains-match

Normalize the operator-supplied <phase-or-section> by lowercasing it. For each header in the collected list, lowercase header_text and check whether the normalized input is a substring of the normalized header text. This match is case-insensitive.

Example: input "phase 2" matches ## Phase 2 — Skill hardening because "phase 2" is contained in "phase 2 — skill hardening".

Example: input "measurement" matches ### Measurement & perception because "measurement" is contained in "measurement & perception".

Match outcomes

Zero matches: Stop with:

"No headers matched <phase-or-section>. Available headers: <bulleted list of all header_text values>."

Multiple matches (disambiguation): Stop with:

"Ambiguous: <phase-or-section> matched more than one header. Please narrow the input:

• <header_text_1> (line N)
• <header_text_2> (line N) ..."

List every matching header so the operator can refine the input.

Exactly one match: Proceed to insertion.

Nested-section name collision precedence

A Phase-2 header might contain the same substring as one of its child Subsection headers — for example, if a Phase is named ## Phase 5 — Skill catalog expansion and a subsection under it is ### Skill-testing & operator-mode skills, then the input "skill" matches both. This is treated as an ambiguous match (multiple matches) regardless of nesting depth — there is no automatic promotion of Phase headers over Subsection headers or vice versa. The operator must supply a more specific input to resolve it.

---

Item formatting

Schema (from ROADMAP.md)

New items follow the checkbox format observed in the existing roadmap:

- [ ] **<bold-name>** — <description>

The separator between the bold name and description is an em dash (—), not a hyphen or en dash. A single space precedes and follows the em dash.

Deriving <bold-name> and <description>

Split <task-text> on the first — (space, em dash, space) if present:

• Left side → <bold-name> (strip backtick-wrapped skill names if relevant).
• Right side → <description>.

If no em dash is found in <task-text>, use the entire text as <bold-name> and leave <description> empty, yielding - [ ] **<task-text>**.

Multi-line wrap

If the formatted item line exceeds 80 characters, wrap at a word boundary and continue subsequent lines with a 6-space continuation indent (six space characters). The leading - [ ] prefix is 6 characters, so continuation lines align visually with the text start.

Example (wrapping a long description):

- [ ] **`/my-skill`** — a long description that needs to wrap at the 80-char
      column so the continuation is indented six spaces to align with the
      text start.

Backtick-wrapped names such as `/skill-name` or `tool.py` should be preserved as-is inside the bold span.

---

Insertion

Finding the bottom of the section

After resolving the target header at start_line, scan forward line-by-line to find the end of that section's checkbox list. The section ends at the first line that matches any of:

• Another ##-level header (same or higher level).
• End of file.

The "bottom of the section's checkbox list" is the last line that begins with - [ ] or - [x] before the section boundary. Insert the new item on the line immediately following that last checkbox line.

If the section contains no checkbox lines at all, insert the new item immediately after any blank line following the header (or directly after the header if there are no blank lines), creating the first checkbox entry.

Confirmation before writing

Before modifying the file, compute a unified diff between the current content and the proposed new content:

--- ROADMAP.md (original)
+++ ROADMAP.md (modified)
@@ ...

Show the diff to the operator and require explicit confirmation before writing. If the operator declines, abort with no changes made.

After confirmation, write the modified file.

---

Examples

Phase match

/add-to-roadmap "Phase 2 :: **`/audit-skill`** — spot-check every SKILL.md for missing argument-hint fields"

Matches ## Phase 2 — Skill hardening. Inserts the formatted item at the bottom of the Phase 2 checkbox list.

Subsection match

/add-to-roadmap "Measurement :: **`/latency`** — help Claude reason about latency budgets"

Matches ### Measurement & perception (because "measurement" is a substring of "measurement & perception", case-insensitively). Inserts at the bottom of that subsection's checkbox list.

Ambiguous match

/add-to-roadmap "skill :: **`/foo`** — example"

If both ## Phase 1 — Plugin packaging and ### Skill-testing & operator-mode skills contain the substring "skill", the skill stops with a disambiguation listing showing both headers and their line numbers.

Malformed args

/add-to-roadmap "Phase 2 — missing the double-colon separator"

Stops immediately: " :: " separator is missing.

---

Error reference

Scenario	Error message
Not a git repo	"Not a git repository..."
ROADMAP.md not found	"ROADMAP.md not found anywhere..."
Missing :: separator	"Malformed arguments: expected ... :: ..."
Zero matches	"No headers matched <input>. Available:..."
Multiple matches	"Ambiguous: <input> matched more than one..."