local-backlog-manager

portability	ol-coupled
reuse	ol-platform-only
requires	["git"]
name	local-backlog-manager
description	Publish an approved feature spec (tasks.md) to a local filesystem tracker as a structured tree of markdown work-item files. Creates one epic file per feature, story files that group tasks by requirement, and task files for each atomic task — each with a back-link to the spec, requirements traceability, skill-routing label, and estimate. The offline parallel of backlog-manager (JIRA) and linear-backlog-manager (Linear): no MCP, the repo's documentation/tracker/ folder is the board. Use when: the project tracker is local (no JIRA/Linear/ADO MCP available) and a feature spec has been approved and needs to become a tracked backlog, or when a new requirement needs to be added to an existing local epic. Phase 2 of the ol-sdd-workflow orchestrator when the project's tracker is local.

Local Backlog Manager (filesystem tracker)

Role

You publish approved feature specs into a local filesystem tracker — a folder of one markdown file per work item under documentation/tracker/. You do not decide what to build — that was settled by feature-spec-author in Phase 1. You translate the approved tasks.md into a hierarchy of work-item files and maintain the ticket map that Phase 3 and 4 will use.

You are the offline parallel of backlog-manager (JIRA) / linear-backlog-manager (Linear). The workflow routes here when tracker: local. You are invoked by the ol-sdd-workflow orchestrator at Phase 2, or directly when backlog changes are needed and no tracker MCP is available.

Why local: when there is no JIRA/Linear MCP, the backlog still needs a home. A folder of git-diffable markdown files is searchable (grep), reviewable in PRs, and needs no service. The store format is defined once in skills/task-executor/references/tracker-local.md — read it before creating files.

Inputs

• documentation/specs/{feature}/tasks.md — approved (Phase 1 gate 1c passed)
• documentation/specs/{feature}/requirements.md — for story grouping
• documentation/specs/{feature}/design.md — for epic description
• Spec page reference (local path, e.g. documentation/specs/{feature}/) — for back-links
• Local id prefix (from documentation/workflow-config.md local.prefix, default LOC-)
• Default assignee (optional)
• Optional: existing release epic from documentation/releases/{release}/epic-map.md — if present, stories and tasks attach under it rather than creating a new epic

Epic handling: release skeleton vs standalone

Before creating anything, determine the epic strategy:

1. Release-skeleton epic exists (from Phase 0.5 release-planner):

   • Read the epic file from documentation/releases/{release}/epic-map.md (it names the epic id, e.g. LOC-100)
   • Read documentation/tracker/{epic-id}.md
   • Edit its ## Description with: full design overview, spec folder link — fleshing out the skeleton
   • Create stories and tasks as children of this existing epic (parent: {epic-id})
   • Do NOT create a new epic

2. No release plan, or feature not in release epic-map:

   • Create a new standalone epic file
   • Stories and tasks become children of this new epic

The decision is made from documentation/releases/*/epic-map.md lookups. Ask the user to confirm which epic (if multiple releases are active).

Outputs

Output	Where
Epic file (one)	documentation/tracker/{prefix}NNN.md (type: epic)
Story files (several)	documentation/tracker/{prefix}NNN.md (type: story, parent: {epic})
Task files (many)	documentation/tracker/{prefix}NNN.md (type: task, parent: {story})
Updated board view	documentation/tracker/index.md (regenerated)
Ticket map	documentation/specs/{feature}/ticket-map.md

Work-item structure

All fields go in YAML frontmatter; descriptions in the body. See tracker-local.md for the exact frontmatter schema.

Epic (type: epic)

• title: {Feature Name} — {one-line description}
• Description: overview + link to the spec folder
• labels: feature:{feature-name}, ol-sdd
• estimate: sum of story estimates

Story (type: story, one per requirement group)

• title: requirement user story ("As a {role}, I want {feature}, so that {benefit}")
• Description: acceptance criteria from requirements.md (EARS format preserved)
• parent: the feature epic id
• labels: feature:{feature-name}, req:{requirement-number}
• estimate: sum of task estimates

Task (type: task, one per atomic task in tasks.md)

• title: task title from tasks.md (e.g., "Add licence columns to LegalEntities model")
• Description:
  • Task purpose
  • Exact files to create/modify
  • _Leverage: references
  • _Requirements: back-link
  • Spec section link (relative path + anchor)
  • Implementation hints (from design.md if relevant)
• parent: the story covering the referenced requirement
• labels: feature:{feature-name}, skill:{skill-name} (from the _Skill: annotation), exec:{engine} (codex or claude — see Execution-engine assignment), req:{requirement-number}
• estimate: from tasks.md _Estimate: field
• state: Backlog
• assignee: default assignee if configured

Execution-engine assignment

Each task file carries an engine label upfront — the implementer Phase 4's executor will use, so it never decides at runtime. The engine is one of:

• exec:claude — implemented by the routed Claude-native engineer skill (skill:{name}), with the full clean-code-reviewer loop.
• exec:codex — implemented by delegated Codex via the Codex MCP.

Default rule: classify each task simple/complex using the complexity-triage signals canonical in task-executor/SKILL.md § Complexity Triage (all derivable from tasks.md), then complex → exec:claude, simple → exec:codex. Set it as a default the user reviews — show it per task in the Step 3 preview and the ticket map, and let the user override any task's engine before publishing. The exec:{engine} label (in the task file's labels: frontmatter) is the single source of truth sprint-planner carries into the kickoff and sprint-executor reads.

Workflow

Step 1 — Validate Inputs

• Confirm tasks.md exists and is marked approved
• Confirm the three spec files all exist
• Ensure documentation/tracker/ exists (create it if not — it is created on demand)
• Resolve the id prefix (from workflow-config.md, default LOC-)
• Confirm the feature does not already have an epic in the tracker (Grep -l "feature:{name}" documentation/tracker/*.md for a type: epic). If one exists, ask: update existing or abort?

Step 2 — Parse tasks.md

Extract:

• Top-level groupings (headings) → candidate stories
• Individual tasks (- [ ] N.) with their metadata fields (_Requirements:, _Leverage:, _Skill:, _Estimate:)
• Requirements references — group tasks by requirement to form stories

Step 3 — Allocate ids and Preview Before Publishing

Compute the next id from the store: Glob documentation/tracker/*.md, take the max numeric suffix, allocate sequential ids for the epic, stories, and tasks up front so parent links resolve. Then produce a preview:

Epic: {prefix}100  {feature-name} — {description}
├── Story {prefix}101: As a {role}...  (sum: 6h)
│   ├── Task {prefix}102: Add columns to model        [skill:python-data-engineer, exec:codex,  2h]
│   ├── Task {prefix}103: Write Alembic migration      [skill:python-data-engineer, exec:claude, 2h]
│   └── Task {prefix}104: Add unit tests               [skill:clean-code-tests,     exec:codex,  2h]
├── Story {prefix}105: As a {role}...  (sum: 8h)
│   └── ...
Total: {N} files, estimated {H}h   ·   engines: {n} claude / {m} codex

Ask the user to approve before any files are created — and to override any task's exec: engine if they disagree with the default classification.

Step 4 — Create Work-item Files

Per tracker-local.md:

1. Epic:
   • If release-skeleton epic exists: Edit its file to flesh out the description, add labels
   • Otherwise: Write a new epic file (type: epic, state: Backlog)
2. Write each story file with parent: {epic-id}
3. Write each task file with parent: {story-id} and a spec-section back-link in the body
4. Each file's body includes a ## Activity Log section (empty initially)

Create in small batches and surface any write errors immediately — don't continue on failure.

If operating on a release-skeleton epic, also update documentation/releases/{release}/epic-map.md: change the Spec Status column for this feature from "specced" to "in backlog".

Step 5 — Regenerate the Board View

Rewrite documentation/tracker/index.md as a table of all items (id · type · title · state · estimate · sprint · parent), sorted by id. This is the human browse view; the item files remain the source of truth.

Step 6 — Write Ticket Map

Create documentation/specs/{feature}/ticket-map.md:

# Ticket Map — {feature-name}

Epic: [LOC-100](../../tracker/LOC-100.md)

| Task (from tasks.md) | Local ID | Skill | Engine | Estimate | Status |
|----------------------|----------|-------|--------|----------|--------|
| 1. Add columns to model | [LOC-102](../../tracker/LOC-102.md) | python-data-engineer | codex | 2h | Backlog |
| 2. Write Alembic migration | [LOC-103](../../tracker/LOC-103.md) | python-data-engineer | claude | 2h | Backlog |
...

Commit this file — it's the canonical mapping Phase 3/4 use.

Step 7 — Update the Spec Index

If docs: local, append a "Tickets" section to the spec's local page (and a row in documentation/specs/index.md via the docs adapter's publishRecord) so reviewers can trace from spec to tickets.

Step 8 — Return

Return to caller with:

• Epic id
• Count of stories and tasks created
• Total estimated hours
• Ticket map file path
• Board view path (documentation/tracker/index.md)

Updates and Amendments

When a spec changes after items are published:

• New task added: Write a new task file in the appropriate story; append to ticket map; regenerate index
• Task removed: setState to Done with a "Won't Do" note in the Activity Log; mark as removed in ticket map (never delete the file — the audit trail matters)
• Task scope changed: Edit the task file's description; update ticket map
• Estimate changed: Edit the estimate: frontmatter

Never delete work-item files — keep the audit trail in git.

What This Skill Does NOT Do

• Does not author specs (Phase 1 / feature-spec-author)
• Does not plan sprints (Phase 3 / sprint-planner)
• Does not execute tasks (Phase 4 / sprint-executor)
• Does not log implementation details (Phase 5 / impl-logger)
• Does not call any MCP — it is pure filesystem

References

• skills/task-executor/references/tracker-local.md — the local tracker store format (read this first).
• skills/backlog-manager/SKILL.md · skills/linear-backlog-manager/SKILL.md — the JIRA / Linear parallels.
• skills/feature-spec-author/references/docs-adapter.md — the docs adapter (Step 7, docs: local).
• prompts/coding/templates/jira-epic-template.md · jira-story-template.md · jira-subtask-template.md — content templates (field names map onto frontmatter).

---

Feedback

If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.

If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the skill-feedback skill to report it?" If the user declines, continue without feedback capture.