Spec-kit workflow command: speckit-onboard-trail
/onboard trail <feature> [--format text|mermaid]
<feature> (required): name of the feature to map--format: output format — text (default) or mermaidYou are executing the /onboard trail command of the spec-kit-onboard extension. Follow the steps below.
Read .onboard/profile.json. If it does not exist, create it with default values (level junior, empty lists, all badges in , current timestamps).
lockedCheck whether features/<feature>/ exists.
If not, respond: "Feature [feature] not found. Available features: [list folders in features/]."
Read the following files:
features/<feature>/spec.md — identify cross-references to other features (mentions of feature names, relative links to features/)features/<feature>/tasks.md — extract all tasks with:
[x] / open [ ])blocked-by, depends-on fields, or patterns like "depends on T-XXX" in the textfeatures/<feature>/plan.md — read if it exists; extract additional phase information.speckit/extensions.json — identify which hooks are active and which extensions have after-implement, after-spec, before-implement hooksIf --format text (default):
Generate the map in the following format:
✦ trail — features/<feature>
Spec
└── features/<feature>/spec.md
[cross-references found, if any]
Tasks (N total, N open)
├── [X] T-001 [title]
├── [X] T-002 [title]
├── [ ] T-003 [title] ← next [if it is the next unblocked task]
│ depends on → T-00X ✓
└── [ ] T-004 [title]
depends on → T-003
Hooks that will fire
[list of identified hooks, format: event → extension (brief description)]
Extensions involved
[list of extensions relevant to this feature]
Rules for the task tree:
[X][ ]← next✓, pending ones withoutIf --format mermaid:
Generate an interactive Mermaid diagram with color coding, click handlers, and subgraphs.
Color coding by task status:
style T001 fill:#22c55e,color:#fff)style T003 fill:#3b82f6,color:#fff)style T004 fill:#ef4444,color:#fff)Click handlers: add a click directive for each task linking to its position in features/<feature>/tasks.md:
click T003 "features/<feature>/tasks.md" "View task"
Subgraphs: group tasks by status using subgraph blocks:
flowchart TD
subgraph done["✓ Completed"]
T001["T-001 · [title]"]
T002["T-002 · [title]"]
end
subgraph open["○ Open"]
T003["T-003 · [title] ← next"]
T004["T-004 · [title] 🔒 blocked"]
T005["T-005 · [title] 🔒 blocked"]
end
T001 --> T002
T002 --> T003
T003 --> T004
T003 --> T005
style T001 fill:#22c55e,color:#fff
style T002 fill:#22c55e,color:#fff
style T003 fill:#3b82f6,color:#fff
style T004 fill:#ef4444,color:#fff
style T005 fill:#ef4444,color:#fff
click T003 "features/<feature>/tasks.md" "View task"
click T004 "features/<feature>/tasks.md" "View task"
click T005 "features/<feature>/tasks.md" "View task"
Generation rules:
flowchart TD (not graph TD) for better layout support.EXT_feat["features/[other-feature]"] with a dashed arrow: EXT_feat -. depends on .-> T001.Include the diagram inside a markdown code block with the mermaid tag.
Save the generated map to .onboard/trails/<feature>.md with the following header:
# Trail — features/<feature>
Generated at: [date]
---
[map content]
Update .onboard/profile.json:
<feature> to the trails_generated[] array if not already there.last_updated.map-reader: if trails_generated had length 0 before this execution, move "map-reader" from locked to earned.full-trail: check if trails_generated now contains all features with open tasks. If so, move "full-trail" from locked to earned.If a new badge was unlocked, display:
🏅 Badge unlocked: [badge-name]
Report at the end: Trail saved to .onboard/trails/<feature>.md
tasks.md does not exist: show only the Spec section and report "No tasks found for this feature."/onboard mentor --feature <feature> to get a suggestion for the next task."