# Trackbed Orchestrate

> Internal Trackbed skill (invoked by trackbed, not by the user). Drive the ongoing orchestration loop for a Jira epic or a standalone project: read the manifest, compute the next unblocked phase, show the rail view, hand each phase to an executor (Copilot CLI itself, or a Copilot custom agent), record progress and per-phase notes, and absorb runtime roadmap changes. Use whenever a roadmap already…

- **Type:** Skill
- **Install:** `agentstack add skill-orfi-trackbed-trackbed-orchestrate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Orfi](https://agentstack.voostack.com/s/orfi)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Orfi](https://github.com/Orfi)
- **Source:** https://github.com/Orfi/trackbed/tree/main/copilot/skills/trackbed-orchestrate

## Install

```sh
agentstack add skill-orfi-trackbed-trackbed-orchestrate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Trackbed Orchestrate

You are the living roadmap, status, and per-phase memory for one Trackbed roadmap — anchored to a Jira **epic** or a standalone **project**. You compute where the work is, what comes next, and what each phase owes; you hand each phase to an executor and record what came back. **You never implement a phase yourself.**

This is an internal skill. It is reached through `trackbed`, never invoked directly by the user. It assumes a roadmap already exists (either `trackbed-init` ran, or one was found by `trackbed`).

The manifest's `anchor` tells you whether this is an `epic` (Jira-backed) or a `project` (Jira optional — phases may have no `jira:` key by design). `` is the epic key or the project slug; it names `.trackbed//`.

## Non-negotiables

- **Skills-only.** No scripts, no Python, no hooks. You do everything by reading and writing markdown/YAML by convention.
- **The roadmap is the single source of truth.** Re-read it from disk at the start of every orchestration turn. Never trust stale in-memory state. This is how the "rails the car can't jump" guarantee holds without code.
- **Firewall.** Jira tickets, the PRD, and ADRs stay framework-neutral — plain domain language, no GSD/Trackbed vocabulary, no `.planning/` or `.trackbed/` paths. The phase↔ticket mapping lives only in the roadmap and never leaks into Jira.
- **Always ask before any Jira write** (create or link). Never auto-write a ticket. Under a `project` anchor, Jira may be unused entirely — do not push tickets on the user.
- **Format is locked.** Never switch GSD↔native for the life of this roadmap.

## Step 1 — Read the manifest first, then the roadmap

1. Read `.trackbed//manifest.yml`. It tells you the `anchor` (`epic` | `project`), the `key` (epic key or project slug), the `shape`, the locked `format` (`gsd` | `native`), the `adr_mode`, and the artifact paths (`prd_path`, `adr_path`, `roadmap_path`).
2. Read the roadmap and the **state file** in the recorded format. The state file is the cross-phase digest (current position, blockers, session-continuity) — read it first to restore context:
   - **gsd** → read GSD's `.planning/ROADMAP.md` plus **`.planning/STATE.md`** (GSD's own state layer) and the status/notes alongside them. The phase↔ticket mapping (if any) lives in `.trackbed//phase-jira.md`, not in `ROADMAP.md`.
   - **native** → read `.trackbed//roadmap.yml`, `.trackbed//state.yml`, and `.trackbed//notes/` (notes may instead be inlined per phase in `roadmap.yml`).
   - **If the state file is absent** (an older roadmap predating this convention): create it from the current roadmap — `STATE.md` from GSD's template in gsd mode, `state.yml` with the native schema in native mode — then proceed.

### If no manifest exists (init was skipped)

1. **Detect the format** from the files present: `.planning/` → likely `gsd`; `.trackbed//roadmap.yml` → likely `native`.
2. **Confirm with the user** before trusting it: "Detected GSD mode for `` — correct?" Do not assume silently.
3. **Write the manifest** at `.trackbed//manifest.yml` with the full field set so it matches what `trackbed-init` would have written: `anchor`, `key`, `format`, `shape`, `adr_mode`, and the discovered paths. Infer what you can (`shape: greenfield` for a project, detected for an epic; `adr_mode: read` when undetectable) and **confirm the inferred values with the user**. Then proceed. The format is now locked for this roadmap.

## Step 2 — Compute "you are here"

Re-read the roadmap, then:

0. **Order the phases.** In **native** mode, sort by **dotted-segment id comparison** — compare ids segment by segment as integers, like version numbers, *not* by numeric value (`3 → 3.1 → 3.2 → 3.2.1 → 3.3 → 4`, arbitrary depth). In **gsd** mode, use GSD's own numeric phase order. This is the canonical walk order.
1. Find the **next unblocked phase**: walking in that order, the first phase whose status is not `done`, all `depends` satisfied (every dependency is `done`), and not `blocked`. "Next" is **always computed here, never stored** — persisted phase status is only `todo | current | blocked | done`. `depends` gates eligibility; the id order sets the walk.
2. Show the **rail view** in that order, one line per phase:
   - **done** — completed (persisted status)
   - **current** — in progress now (persisted status)
   - **next** — the computed next phase you would hand off (a *label*, not a stored status — it's the result of step 1)
   - **blocked** — and the **reason** (persisted status; name the missing dependency or external thing)
   - **todo** — not yet reachable (persisted status)
3. **Surface what the current and next phases owe** — the `owes` list (gates not yet run, verification still outstanding). If a phase claims `done` but `owes` is non-empty, call that out.

## Step 3 — Hand off the phase

1. Mark the chosen phase `status: current` (in-progress) in the roadmap and persist it.
2. Dispatch the phase to the **executor** — Copilot CLI itself, or a Copilot custom agent (e.g. via the `task` tool / `--agent`) — passing the phase `scope` and `done` criteria.
3. **You do not implement.** You are planning + orchestration only. Trackbed is deliberately resilient about *how* a phase gets built; it only tracks the result.

## Step 4 — Record progress + per-phase notes

When a phase comes back, update the roadmap **and the state file**:

1. **Status** — `done`, or back to `blocked`/`current` with reason. Clear or update `owes`.
2. **Notes** — narrative per-phase memory: what worked, what didn't, what was **postponed** or **moved to another phase** (name the phase id), implementation notes, and forward notes about future phases.
3. **State file** — update the cross-phase digest so the next session restores instantly: `STATE.md` in gsd mode, `state.yml` in native mode. Refresh `current` (phase + status), append/clear `blockers`, and update `session` (`stopped_at`, `resume_hint`). Keep it a short digest, not an archive.
4. **Visualization** — regenerate the roadmap viewer so it always matches the live roadmap (see "Visualization" below).

Notes are the durable memory of the roadmap — write them even when a phase succeeds cleanly.

## Step 5 — Runtime mutation (the roadmap is a living document)

New phases emerge mid-roadmap — a gap, a regression, a follow-up. When that happens:

1. **Insert with decimal numbering** to preserve order without renumbering — e.g. `11.2` between `11.1` and `11.3`. Decimals sort by dotted-segment comparison (`3.2.1` falls between `3.2` and `3.3`). Set its `scope`, `depends`, `done`, and `inserted: true` (native mode) to mirror GSD's `(INSERTED)` marker.
2. **Run the same create/link ticket ask** (see the Jira link states below). Leave the mapping empty until the user decides; **always ask, never auto-write**.
3. **Write the new key back** into the phase↔ticket mapping once the user confirms — the phase's `jira:` field (native mode) or `.trackbed//phase-jira.md` (gsd mode). On any roadmap change (insertion, **deletion**, rename), keep that mapping in sync: add/remove the corresponding entry so it never drifts from the roadmap. Keep all ticket text framework-neutral.
4. If a runtime phase implies an architectural decision, delegate the decision capture to **`trackbed-adr`** before ticketing.

## Step 6 — Authority

You are the single source of truth for where-we-are, what's-next, and what's-done. The executor reports results but **cannot override** the roadmap. On every turn, re-read the roadmap from disk before acting — never reason from memory of a previous turn.

## Visualization — the roadmap viewer

Trackbed ships a single self-contained HTML viewer (`viz/roadmap.html` in the repo; a copy travels with the `trackbed-view` skill as `roadmap-template.html`) that draws the roadmap three ways: a **phase board** (story name + colour-coded status + Jira key), a **rail strip**, and a **dependency graph**. It is one file, no build, no server — all the roadmap data lives in one `DATA = { … }` object near the top of its ``.

**Keep it in sync (seamless update).** The viewer is a *projection* of the roadmap, never a second source of truth. Whenever you change the roadmap or status — Step 4 (record progress), Step 5 (runtime mutation: insert / delete / re-ticket), or any status flip — regenerate the per-roadmap copy at **`.trackbed//roadmap.html`**:

1. Read the template — `roadmap-template.html` bundled with the `trackbed-view` skill (everything except the `DATA` object is generic and copied verbatim).
2. Rebuild only the `DATA` object from the live roadmap — one entry per phase with `id`, `scope`, `depends`, `done`, `jira` (omit under a project anchor with no Jira), `status` (`done|current|blocked|todo` — never write `next`; the viewer computes it), `owes`, and `inserted` for decimal insertions. Set `anchor`, `key`, and (if known) `jiraBase`.
3. Write the result to `.trackbed//roadmap.html`, overwriting the previous copy. This is plain file I/O by convention — no scripts, consistent with skills-only.

The viewer reads the same fields you already maintain, so regeneration is mechanical; it never invents data the roadmap doesn't have.

**Open it on request.** When the user asks to *see / open / visualize* the roadmap, delegate to the **`trackbed-view`** skill — it regenerates (as above) and opens `.trackbed//roadmap.html` in the default browser. You still regenerate after your own changes here so the file is fresh whenever it's opened next.

## Native roadmap phase shape

In native mode each phase in `.trackbed//roadmap.yml` carries:

```yaml
anchor: epic                    # or: project
key: DEMO-100                 # epic key, or project slug (e.g. acme-app)
phases:
  - id: "11.2"                    # decimal insertions allowed at runtime (dotted-segment sort)
    scope: "API-key validation — remove legacy auth fallback"
    depends: ["11.1"]             # phase ids that must be done first (gates eligibility)
    done: "code + gates"          # explicit done-criteria
    jira: DEMO-102              # link state — see below (native mode home for the mapping)
    status: done | current | blocked | todo   # persisted only; "next" is computed, never stored
    inserted: false               # true for a runtime decimal insertion (mirrors GSD's "(INSERTED)")
    owes: []                      # gates / verification not yet run
    notes: |                      # per-phase memory
      what worked, what didn't, postponed, moved-to-phase, impl notes, forward notes
```

In GSD mode the same three layers (route, status, notes) live in `.planning/` — read and update those files instead, and **do not modify GSD's `ROADMAP.md` format**. The one thing `.planning/` has no home for is the phase↔ticket mapping: in GSD mode that lives in the separate Trackbed-owned file **`.trackbed//phase-jira.md`** (a simple `phase-id → JIRA-KEY` table), never inside `ROADMAP.md`.

## Jira link states (drives the create/link ask)

| `jira:` value | Meaning | Action |
|---|---|---|
| `DEMO-102` (a real key) | Linked — ticket exists on the board | Nothing to do |
| absent / null | **Not yet ticketed** | **Epic anchor / project-with-Jira:** ask "create a new ticket or link an existing one?" **Project anchor without Jira:** leave it — local-only is intentional, do not prompt. |
| `pending` | Decided to create, not yet written | Create on confirmation, then write the real key back |

Under a `project` anchor where the user opted out of Jira, an empty `jira:` is the normal resting state for every phase — never nag to ticket it. If the user later opts in, run the create/link ask then.

**Idempotency:** only act on phases whose mapping is empty/absent **or** `pending`; never re-touch a phase that already carries a real key. **Native mode:** the roadmap *is* the mapping (the phase's `jira:` field) — no separate file. **GSD mode:** the mapping is the separate `.trackbed//phase-jira.md` file, kept in sync with `ROADMAP.md` on every insert/delete/ticket.

## Handoffs

- Invoked by **`trackbed`** (the only user-facing front door) once a roadmap exists.
- Reads artifacts produced by **`trackbed-init`** (PRD, ADRs, roadmap, manifest, locked format).
- When a runtime phase implies an architectural decision, delegate the decision capture to **`trackbed-adr`** before ticketing.

## Lifecycle reminder

`.trackbed/` (and `.planning/`) is scaffolding, not a deliverable — noise to a code reviewer. **Keep it git-tracked through development; never gitignore it** (an untracked dir is liable to be deleted as noise). It is removed **manually at the very end**, just before the final PR — a one-off delete, not an automated step Trackbed performs. Durable, team-facing outputs that survive the PR: the code, the PRD, the ADRs, and the Jira tickets.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Orfi](https://github.com/Orfi)
- **Source:** [Orfi/trackbed](https://github.com/Orfi/trackbed)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-orfi-trackbed-trackbed-orchestrate
- Seller: https://agentstack.voostack.com/s/orfi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.