Implement Roadmap Version

Implement Roadmap Version

Structured, self-driving workflow for implementing every item in a specific pg_trickle release milestone. The skill continues working through items sequentially, updates plan and roadmap status as it goes, surfaces blockers to the user with concrete questions, and produces a completion report at the end.

When to Use

• Starting work on a planned milestone
• Resuming an in-progress milestone after a pause
• Verifying how far along a release is and continuing from where it left off

Inputs to Gather First

Before any implementation begins, read these files in parallel:

1. ROADMAP.md — find the target version section: theme, item list, status
2. plans/PLAN_0_<version_underscored>.md — implementation order, phases, item IDs, effort estimates, exit criteria (if the file exists)
3. CHANGELOG.md (last 200 lines) — avoid re-implementing already-shipped work
4. AGENTS.md — coding conventions, error handling rules, SPI rules
5. plans/INDEX.md — cross-reference any linked sub-plans

If plans/PLAN_0_<version_underscored>.md does not exist, create it following the template in Step 1b before proceeding.

Procedure

Step 0 — Establish Context

Run the following in parallel:

# What version are we on?
cat pg_trickle.control | grep '^default_version'
grep '^version' Cargo.toml | head -1

# Are there uncommitted changes?
git status --short

# Which branch are we on?
git branch --show-current

Determine:

• Target version (from the argument or user's message)
• Current version (from pg_trickle.control)
• Full details file: roadmap/v<VERSION>.md-full.md
  • Example: v0.34.0 → roadmap/v0.34.0.md-full.md
• Branch: if on main, a new branch must be created before making any changes: git checkout -b <version>-implementation

Step 1a — Parse the Full Details File

Read roadmap/v<VERSION>.md-full.md and extract:

1. All item IDs and titles (e.g. DOG-1, PG17-3)
2. Current status of each item in the Implementation Status table (⬜ Not started / 🔄 In progress / ✅ Done / ⏭ Skipped)
3. Phase groupings — respect the recommended implementation order
4. Exit criteria — the checklist at the bottom of the full details file
5. Items already done — skip these, but record them for the completion report

Step 1b — Create the Full Details File if Missing

If roadmap/v<VERSION>.md-full.md does not exist:

1. Read the roadmap section for the target version from ROADMAP.md.
2. Create roadmap/v<VERSION>.md-full.md using this skeleton:

> **Plain-language companion:** [v<VERSION>.md](v<VERSION>.md)

## v<VERSION> — <Theme from ROADMAP>

**Status: Planned.** Derived from [ROADMAP.md](../ROADMAP.md).

> **Release Theme**
> <one-paragraph summary>

---

### Correctness

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
<rows>

### Ease of Use

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
<rows>

### Test Coverage

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
<rows>

---

### Recommended Implementation Order

<phases derived from roadmap items, ordered by dependency>

---

### Implementation Status

| ID | Title | Status |
|----|-------|--------|
<one row per item, all "⬜ Not started" initially>

---

### Exit Criteria

- [ ] All P0 items ✅ Done
- [ ] `just test-all` passes
- [ ] `just check-version-sync` exits 0
- [ ] CHANGELOG.md entry written
- [ ] ROADMAP.md v<VERSION> row marked ✅ Released

3. Also create the plain-language companion roadmap/v<VERSION>.md if missing.
4. Add both files to git staging:

   git add roadmap/v<VERSION>.md roadmap/v<VERSION>.md-full.md

Step 2 — Build the Work Queue

Construct an ordered list of items to implement:

1. Take all items from the full details file in phase order.
2. Skip items already marked ✅ Done or ⏭ Skipped.
3. Mark the first actionable item as 🔄 In progress in the full details file.
4. Use manage_todo_list to track all items, using the item ID as the todo ID.

If no items remain (all ✅ / ⏭), jump directly to Step 6 — Completion Report.

Step 3 — Implement Each Item (Loop)

For each item in the work queue, repeat this inner loop:

3a. Understand the Item

Read the roadmap description for the item. Identify:

• What code/SQL/test/doc changes are needed
• Which files are affected
• Whether a schema change is required (SQL migration needed)
• Dependencies on other items (check they are ✅ Done first)

If a dependency is not yet done, reorder: implement the dependency first.

3b. Ask Before Ambiguous Work

Before making any irreversible change, if the item is ambiguous or has multiple valid approaches, ask the user a focused question:

"For item <ID> — <title>, I'm planning to <approach>. Does that match your intent, or should I <alternative>?"

Keep questions concrete and binary where possible. Never ask about more than two items at once.

For straightforward, clearly-specified items: do not ask — just implement.

3c. Implement

Apply changes following AGENTS.md conventions:

After each item's changes are applied:

just fmt          # Always
just lint         # Must pass with zero warnings

For items that add or modify SQL-facing code, also run the appropriate tier:

just test-unit           # Always run after Rust changes
just test-integration    # Run if catalog or SPI changes

Do not run just test-e2e or just test-all after every item — reserve these for phase boundaries (see Step 3e).

3d. Update Status

Immediately after each item is implemented and lint passes:

1. Update the item's row in the full details file's Implementation Status table: ⬜ Not started → ✅ Done
2. If the item was in-progress (🔄), also update that row.
3. Update the Status line at the top of the full details file.

<!-- Example update in Implementation Status table -->
| DOG-3 | Create `pgtrickle.self_monitor()` stream table | ✅ Done |