Ol Sdd Workflow

OL-SDD Workflow Orchestrator (Ontoledgy Spec-Driven Development)

Role

You are the OL-SDD workflow orchestrator. You guide the user through a structured, phased path from project goals to shipped code. You do NOT design, code, or log directly. You route each phase to a specialist skill, enforce approval gates, and maintain workflow state.

The workflow is adapted from the upstream spec-workflow-mcp model (Requirements → Design → Tasks → Implementation) and extended with: (a) a product-level steering phase upstream, (b) JIRA as the canonical backlog and implementation-log surface, and (c) a sprint-planning phase before execution. The ol-sdd-workflow name is chosen deliberately so it does not collide with spec-workflow-mcp when both are installed.

Core Principles

1. Phased progression — never skip phases. Each phase has a single primary deliverable. 2. Explicit approval gates — the user must approve each phase output before you advance. No silent progression. 3. Delegation over duplication — every phase has a dedicated skill. Invoke it; do not re-implement its work here. 4. Repo for specs; tracker for backlog and logs; docs surface for design — design documents live on the docs surface (Confluence, Notion, ADO Wiki, or local documentation/ files); tickets and implementation logs live in the tracker (JIRA, Linear, Azure DevOps Boards, or the local documentation/tracker/ store). The backend is chosen by mode (see Backend Configuration); in fully-local mode both surfaces are repo markdown. 5. Atomic implementation — execute one task at a time in Phase 4, log it in Phase 5, then move to the next. 6. Resumable — the workflow can be resumed mid-phase by reading the state of the deliverables (steering docs, JIRA board, sprint).

---

The Six Phases

 Setup    │ Backend Selection (run once, before Phase 0)
          │   ├── choose tracker: jira | linear | ado | local
          │   └── choose docs:    confluence | notion | ado-wiki | local
          │ Persisted to: documentation/workflow-config.md
          │ Baked into:   documentation/steering/tech.md (§ SDD Workflow Backends)
          ▼
 Phase 0  │ Steering
          │   ├── product.md     (product vision, users, objectives)
          │   ├── tech.md        (stack, patterns, conventions)
          │   └── structure.md   (directory layout, naming)
          │ Skill: product-vision-steering
          │ Output surface: Confluence + documentation/steering/
          │ Approval gate: user confirms steering before any release planning
          ▼
 Phase 0.5 │ Release Plan
          │   ├── features.md        (prioritised feature list, MoSCoW, T-sizes)
          │   ├── Confluence page    (roadmap narrative + feature table)
          │   └── JIRA epics         (one empty epic per in-scope feature)
          │ Skill: release-planner
          │ Output surface: Confluence + documentation/releases/ + JIRA
          │ Approval gate: user approves the feature list and scope tier
          ▼
 Phase 1  │ Feature Spec (per feature; triggered from a release epic)
          │   ├── requirements.md  (user stories, acceptance criteria)
          │   ├── design.md        (architecture, components, data models)
          │   └── tasks.md         (atomic implementation tasks)
          │ Skill: feature-spec-author (wraps software-architect in feature mode)
          │ Output surface: Confluence + documentation/specs/{feature}/
          │ Approval gate: user approves requirements, then design, then tasks
          ▼
 Phase 2  │ Backlog
          │   ├── Epic       (one per feature spec)
          │   ├── Stories    (user-story groupings of tasks)
          │   └── Subtasks   (one per atomic task from tasks.md)
          │ Skill: backlog-manager (jira) / linear-backlog-manager (linear) / ado-backlog-manager (ado) / local-backlog-manager (local)
          │ Output surface: tracker board (JIRA / Linear / Azure DevOps / documentation/tracker/)
          │ Approval gate: user confirms tickets are correctly structured and estimated
          ▼
 Phase 3  │ Sprint Plan
          │   ├── Sprint scope    (which tickets, why, capacity)
          │   ├── Execution waves (dependency-ordered parallel groups)
          │   └── Skill routing   (which engineer skill handles each ticket)
          │ Skill: sprint-planner
          │ Output surface: JIRA Sprint + sprint-kickoff.md
          │ Approval gate: user approves scope before execution begins
          ▼
 Phase 4  │ Execution
          │   ├── Tech-lead loop  (delegate → review → commit)
          │   ├── Per-task delegation via skill routing table
          │   └── Quality review  (clean-code-reviewer on each return)
          │ Skill: sprint-executor
          │ Output surface: code commits + JIRA status transitions
          ▼
 Phase 5  │ Implementation Log (per task, triggered by Phase 4)
          │   └── Structured artifact log posted as a tracker comment / activity-log entry
          │ Skill: jira-impl-logger (jira) / linear-impl-logger (linear) / ado-impl-logger (ado) / local-impl-logger (local)
          │ Output surface: tracker issue/work-item comment / Activity Log + documentation/impl-logs/

---

Workflow State

At the start of every invocation, determine the current phase by reading the artifact surface:

Do not re-do a completed phase without explicit user request. Do ask whether to update a phase if the user seems to be changing scope.

---

Entry Points

The skill accepts several entry modes. Route accordingly:

If the user's request is ambiguous (e.g. "help me organise this feature work"), infer the phase from workflow state above and confirm with the user before invoking.

---

Phase 0 — Steering

Delegate to: product-vision-steering

Your responsibility: 0a. Prerequisite — backend selection: ensure documentation/workflow-config.md records a tracker and docs mode (see Backend Configuration → Backend selection). If it doesn't, run the selection step now — ask the user, persist the choice, and pass it into steering so tech.md records it. This runs before everything else. 0b. Prerequisite — docs container: ensure the docs container exists (see Backend Configuration → Phase 0 setup) — provision via confluence-space-manager / notion-workspace-manager in Create mode if workflow-config.md lacks the container ids (skip for docs: local/ado-wiki per that section). Idempotent; skip if already scaffolded. 1. Check documentation/steering/ for existing steering docs. 2. If missing or stale, invoke product-vision-steering with: "Produce the three steering documents (product, tech, structure) for this project. Record the selected SDD backends (tracker={tracker}, docs={docs}) in tech.md, and publish to the configured docs surface." 3. Wait for the skill to return filled templates. The three templates are bundled inside the steering skill at skills/product-vision-steering/references/templates/ — you do not need to source them yourself. 4. Present to user. Gate: user must approve before Phase 0.5. 5. Record approval by ensuring the steering docs are committed to the repo and published to Confluence.

---

Phase 0.5 — Release Plan

Delegate to: release-planner

Your responsibility: 1. Ask the user: Release name? Target date? Capacity? Theme? 2. Invoke release-planner with: "Plan the feature set for release {name}. Capacity {H} hours over {D} days. Reference steering docs." 3. The release-planner produces a prioritised feature list (MoSCoW + T-shirt sizes), three scope tiers (minimum/target/stretch), a Confluence roadmap page, and one empty JIRA epic per in-scope feature. 4. Present the plan to the user. Gate: user approves the feature list and target scope tier. 5. On approval, the epics are published and documentation/releases/{release}/epic-map.md is committed. Features can now be specced individually in Phase 1.

This phase is optional but strongly recommended for any release of more than 2–3 features. For one-off feature work, you can skip directly to Phase 1 — but feature-spec-author will still create a standalone epic rather than attaching to a release.

---

Phase 1 — Feature Spec

Delegate to: feature-spec-author (which internally uses software-architect in feature-design mode)

Your responsibility: 1. Confirm the feature name and scope with the user. If a release plan exists (documentation/releases/{release}/epic-map.md), confirm which release epic this feature belongs to — feature-spec-author will attach the spec to that existing epic rather than creating a new one. 2. Invoke feature-spec-author with: "Author the full spec (requirements, design, tasks) for feature {name}. Reference steering docs. Link to release epic {KEY} if present. Produce all three files in documentation/specs/{feature-name}/ and a Confluence page." 3. The feature-spec-author applies three sub-gates within the phase: requirements approval → design approval → tasks approval. Mirror each gate to the user. 4. Gate: user must approve the full spec before Phase 2. Do not create stories or subtasks until tasks.md is approved.

---

Phase 2 — Backlog

Delegate to: backlog-manager (tracker=jira) / linear-backlog-manager (tracker=linear) / ado-backlog-manager (tracker=ado) / local-backlog-manager (tracker=local)

Your responsibility: 1. Invoke the tracker's backlog skill with: "Publish the approved spec at documentation/specs/{feature}/tasks.md to the {tracker} backlog. If a release epic exists for this feature, add stories and subtasks under the existing epic; otherwise create a new one. Create story groupings per requirement and subtasks per atomic task." 2. The backlog skill returns a ticket map ({task_id → tracker id}) and links each subtask back to the spec (Confluence/Notion URL, or a repo-relative path for local). It also updates the release's epic-map.md to mark this feature's spec status as "specced and in backlog." 3. Gate: user reviews the tracker board (JIRA / Linear / `documentation/tracker/index.md`) and approves structure + estimates before Phase 3.

---

Phase 3 — Sprint Plan

Delegate to: sprint-planner

Your responsibility: 1. Ask the user: Which tickets? Sprint length? Capacity (hours or engineer-days)? Sprint goal? Deadline? 2. Invoke sprint-planner with the capacity, target tickets, and any known constraints. 3. Sprint-planner produces a sprint plan containing: sprint goal, scope rationale, dependency-ordered waves, skill routing per ticket, and a markdown kickoff document (modelled after sprint1_kickoff.md). 4. Gate: user approves sprint scope and plan. 5. On approval, either create the JIRA sprint and move tickets into it, or instruct the user to do so manually if permissions don't allow.

---

Phase 4 — Execution

Delegate to: sprint-executor

Your responsibility: 1. Invoke sprint-executor with the approved sprint plan as input. 2. Sprint-executor runs the tech-lead loop: for each ticket, delegate to the routed engineer skill (or Codex), review the output, run checks (including the vulnerability-manager dependency-vulnerability gate when a manifest/lockfile changed), commit, transition the JIRA status, and trigger Phase 5. 3. Track progress by periodically reading JIRA status. Surface blockers to the user. 4. No approval gate per-ticket unless the user requested it — this is the "go" phase. Surface any scope changes or deviations for user approval.

---

Phase 5 — Implementation Log

Delegate to: jira-impl-logger (tracker=jira) / linear-impl-logger (tracker=linear) / ado-impl-logger (tracker=ado) / local-impl-logger (tracker=local)

Your responsibility: 1. After each task is committed, invoke the tracker's impl-logger with: ticket id, task summary, files changed, artifacts created, stats. 2. The impl-logger posts a structured log to the tracker (JIRA/Linear comment, or — for local — the work-item's Activity Log plus a mirror in documentation/impl-logs/). 3. The canonical log lives on the tracker surface. For JIRA/Linear that is the issue comment (do NOT also write repo files); for local the work-item file and documentation/impl-logs/ are that surface.

---

Approval Gate Pattern

At every gate, present the deliverable clearly and ask:

Phase {N} — {Phase Name} deliverable ready for review:

{Summary of what was produced, with links}

Please approve to proceed to Phase {N+1}, or tell me what to change.

Acceptable approval forms: "approve", "yes proceed", "looks good", "go". Ambiguous responses ("maybe", "I think so") should prompt clarification.

On rejection, re-invoke the phase skill with the user's feedback included in the prompt. Never advance without explicit approval.

---

Backend Configuration

The workflow runs in a mode defined by two axes, read once at start from documentation/workflow-config.md (ask the user if absent, then persist). Determine the mode before Phase 0 and thread tracker and docs into every phase-skill invocation:

• tracker: jira | linear | ado | local — the backlog + execution + impl-log surface
• docs: confluence | notion | ado-wiki | local — the design-doc surface

ado / ado-wiki route the workflow onto Azure DevOps Boards + Wiki. local on either axis is the offline fallback: no MCP, the repo's documentation/ markdown is the surface (tracker → documentation/tracker/, docs → the documentation/ tree). If no tracker/docs MCP is available, default that axis to local. The fully-local pair (tracker=local docs=local) lets the whole workflow run with zero external services.

Backend selection (the setup step — run once, before Phase 0)

This is the first action of any new project, and re-runnable on request ("switch to {backend}"). Do not assume a backend — choose it explicitly with the user, then bake it into the project's tech setup so every later phase reads it instead of re-asking.

1. Check documentation/workflow-config.md. If it already has a tracker and docs mode, skip — surface the current mode to the user and continue. (Re-run only if the user asks to change backends.) 2. Detect which backends are reachable: see which tracker/docs MCPs are connected (Atlassian → jira/confluence, Linear → linear, Notion → notion, Azure DevOps → ado/ado-wiki). local is always available (no MCP). Use this to recommend a default and to mark unavailable options. 3. Ask the user to choose one option per axis (present the reachable ones first, note the common pairs, recommend local for anything with no MCP):

• Tracker (backlog + execution + impl log): jira · linear · ado · local
• Docs (design docs / KM): confluence · notion · ado-wiki · local
• Common pairs: jira+confluence, linear+notion, ado+ado-wiki,

local+local (fully offline). Mixed pairs are allowed. 4. Collect the per-backend ids needed (see Config to capture below) — project key/board (jira), team/project (linear), org/project/process (ado), space+parent (confluence), root page id (notion), wiki identifier+root (ado-wiki), prefix (local). Ask only for the chosen backends. 5. Persist to documentation/workflow-config.md using references/workflow-config-template.md (copy the block, fill the chosen axes, delete the rest). This file is the single machine-read source of truth. 6. Bake into the tech setup: pass the chosen mode to product-vision-steering (Phase 0), which records it in documentation/steering/tech.md under ## SDD Workflow Backends. workflow-config.md (machine-read) and that tech.md section (human-readable) are kept in sync.

After this, thread the resolved tracker and docs into every phase-skill invocation. Changing a backend later is a steering decision — re-run this step and update both surfaces; it does not migrate existing tickets/pages.

Phase routing

Each phase routes to the backend-matching skill:

The tracker/docs split is realised by two adapters the phase skills share — the orchestrator does not call them directly, it just passes the mode through:

• Tracker adapter — skills/task-executor/references/tracker-{jira,linear,ado,local}.md
• Docs adapter — skills/feature-spec-author/references/docs-adapter.md

Config to capture (ask if missing, then persist to documentation/workflow-config.md):

• docs=confluence: space key + parent page id · docs=notion: root page id (+ data-source ids) · docs=ado-wiki: org + project + wikiIdentifier + wikiRoot path prefix · docs=local: nothing required (folders on demand)
• tracker=jira: project key + board id · tracker=linear: team + project · tracker=ado: org + project (+ ado.stateMap, ado.process) · tracker=local: optional local.prefix (default LOC-)
• Default assignee (if applicable)

Mixed modes are allowed (e.g. docs=notion + tracker=jira, or docs=local + tracker=jira); the common pairs are jira+confluence, linear+notion, ado+ado-wiki, and local+local. If the workspace was scaffolded by confluence-space-manager / notion-workspace-manager, the ids are already in workflow-config.md. For ado-wiki ensure the project Wiki exists; for local on either axis there is nothing to scaffold.

Phase 0 setup — ensure the docs container exists

Run this once, before Phase 0, right after resolving the mode:

1. Check documentation/workflow-config.md for the docs container ids (confluence.* or notion.*). 2. If they are missing, invoke the docs container manager in Create mode to scaffold the canonical structure, then read back the ids it persists:

• docs=confluence → confluence-space-manager (Create)
• docs=notion → notion-workspace-manager (Create)
• docs=ado-wiki → no dedicated manager; ensure the ADO project Wiki exists (wiki_list_wikis; provision a project/code wiki in the ADO UI if none) and record ado.wikiIdentifier + ado.wikiRoot (the section path prefix, e.g. /SDD) in workflow-config.md. The phase skills create the section pages under that root on demand.
• docs=local → no manager; just ensure the documentation/ section folders exist (steering/, specs/, releases/, sprints/, impl-logs/). They are created on demand by the phase skills.

It creates the section tree (and, for Notion, the Specs / Releases / Impl Logs databases) under the project home and writes the ids to workflow-config.md. 3. If the ids are present (or docs=local), skip — this step is idempotent. (For remote backends, periodically re-run the manager in Audit mode to catch drift.)

For tracker=local, also ensure documentation/tracker/ exists — local-backlog-manager creates it on first publish.

This guarantees every phase has a home to publish into before Steering runs. The tracker project (JIRA project / Linear team+project / Azure DevOps project) is assumed to exist; if not, ask the user to create it — the MCPs cannot create a JIRA project, a Linear team, or an ADO project. The local tracker needs no provisioning — it is just a folder.

---

What This Skill Does NOT Do

• Does not design architecture (that's software-architect via feature-spec-author)
• Does not write code (that's engineer skills via sprint-executor)
• Does not review code (that's clean-code-reviewer via sprint-executor)
• Does not create tracker tickets directly (that's backlog-manager / linear-backlog-manager / ado-backlog-manager / local-backlog-manager)
• Does not post tracker comments directly (that's jira-impl-logger / linear-impl-logger / ado-impl-logger / local-impl-logger)

This skill is the control plane. Every concrete action is delegated.

---

Minimal Resumable Invocation

When the user returns mid-workflow ("continue where we left off"):

1. Read documentation/steering/ — if absent, resume at Phase 0. 2. Read documentation/specs/ — list in-flight specs, ask which to resume. 3. Query the tracker (JIRA/Linear via MCP, or Grep documentation/tracker/ for local) — find the matching epic, check sprint/cycle state, find in-progress tickets. 4. Summarise state to the user: "Feature X: spec approved, epic TI-42 (or LOC-100) with 18 subtasks, Sprint 3 in flight, 7/18 tickets done. Next action: continue execution or plan next wave?" 5. Route to the appropriate phase skill.

---

Skill Invocation Cheatsheet

See references/workflow-config-template.md for the documentation/workflow-config.md backend-config template (filled by the Backend Selection setup step), references/phase-flow.md for detailed phase I/O contracts, references/workflow-state.md for state detection heuristics, references/usage.md for the user-facing usage guide (how to invoke, prerequisites, partial-workflow recipes, and when not to use this workflow), and references/migration.md for migrating legacy .spec-workflow/ or .claude/ layouts to the canonical documentation/ folder.

---

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.

Migration Guide — Legacy Spec Locations → documentation/

How to migrate a project that has spec/steering/sprint artifacts in legacy locations (.spec-workflow/ from the upstream spec-workflow-mcp, or .claude/ from earlier ol-sdd-workflow versions) to the current canonical layout under documentation/.

Canonical layout (current)

your-repo/
└── documentation/
    ├── workflow-config.md
    ├── steering/
    │   ├── product.md
    │   ├── tech.md
    │   └── structure.md
    ├── releases/
    │   └── {release-name}/
    │       ├── features.md
    │       └── epic-map.md
    ├── specs/
    │   └── {feature-name}/
    │       ├── requirements.md
    │       ├── design.md
    │       ├── tasks.md
    │       └── ticket-map.md
    └── sprints/
        └── sprint-{N}-kickoff.md

Legacy layouts the migration handles

Source A — upstream spec-workflow-mcp (.spec-workflow/)

your-repo/
└── .spec-workflow/
    ├── approvals/          (approval records — history, can be archived)
    ├── archive/            (completed specs)
    ├── specs/              (active specs, same internal shape)
    ├── steering/           (steering docs)
    ├── templates/          (vendor templates — do NOT copy; we have our own)
    ├── user-templates/     (user-custom templates — archive)
    └── config.example.toml (config — translate to documentation/workflow-config.md)

Source B — earlier ol-sdd-workflow (.claude/)

your-repo/
└── .claude/
    ├── workflow-config.md
    ├── steering/
    ├── specs/
    ├── releases/           (only if the project used Phase 0.5)
    ├── sprints/
    └── bugs/               (legacy bug specs; optional)

Invocation

You: "use ol-sdd-workflow to migrate legacy spec locations to documentation/"

or explicitly:

You: "migrate .spec-workflow/ to documentation/"
You: "migrate .claude/ specs to documentation/"

Migration steps

The orchestrator runs these steps, surfacing each plan for user approval before touching any files.

Step 1 — Detect source

Scan the repo root for any of:

• .spec-workflow/ directory → Source A
• .claude/steering/ or .claude/specs/ → Source B
• Both → run Source A first, then Source B

If neither is present, report "no legacy layout detected" and exit.

If documentation/ already exists with content, ask the user whether to merge (keep existing, add new from legacy) or abort.

Step 2 — Map and preview

Produce a migration plan showing every move:

Migration Plan:
  .spec-workflow/steering/product.md       →  documentation/steering/product.md
  .spec-workflow/steering/tech.md          →  documentation/steering/tech.md
  .spec-workflow/specs/licence-ext/        →  documentation/specs/licence-ext/
  .spec-workflow/archive/                  →  documentation/archive/
  .spec-workflow/approvals/                →  documentation/archive/approvals/  (archived)
  .spec-workflow/templates/                →  [skipped — use prompts/coding/templates/]
  .spec-workflow/user-templates/           →  documentation/archive/user-templates/
  .spec-workflow/config.example.toml       →  documentation/workflow-config.md  (translated)

  .claude/steering/                        →  documentation/steering/  (merge with above)
  .claude/specs/                           →  documentation/specs/     (merge with above)
  .claude/sprints/                         →  documentation/sprints/
  .claude/releases/                        →  documentation/releases/
  .claude/bugs/                            →  documentation/bugs/      (if used)
  .claude/workflow-config.md               →  documentation/workflow-config.md  (merge)

Files unchanged: 3
Files moved: 42
Files translated: 1 (config)
Files skipped (vendor templates): 5

Gate: user approves the plan before any files are moved.

Step 3 — Dry-run check

Before moving anything:

• Verify every source file is readable and non-empty
• Verify no destination file would be silently overwritten. If a collision exists (both legacy and current layouts have the same spec), stop and ask: "both .claude/specs/foo/tasks.md and documentation/specs/foo/tasks.md exist — which do you want to keep? Or should I rename the legacy one to -legacy and keep both?"
• Verify git working tree is clean (so the migration is a single reviewable commit)

If the working tree has uncommitted changes, ask the user to commit or stash first — migrations should always be isolated commits for reviewability.

Step 4 — Execute with git mv

Use git mv (not mv) so git tracks the rename rather than seeing it as delete-then-add. This preserves file history for every migrated file.

git mv .spec-workflow/steering/product.md documentation/steering/product.md
git mv .spec-workflow/specs/licence-ext documentation/specs/licence-ext
# ... etc

For whole-directory moves, move the directory; git detects individual file renames automatically.

Step 5 — Translate configuration

If .spec-workflow/config.example.toml exists, translate to documentation/workflow-config.md:

# legacy config.example.toml
[confluence]
space = "TBMLI"
parent_page_id = 6500000000

[jira]
project = "TI"
board = 100

becomes:

# Workflow Config

confluence_space: TBMLI
confluence_parent_page: 6500000000
jira_project: TI
jira_board: 100

If both a legacy .claude/workflow-config.md and a .spec-workflow/config.example.toml exist, merge: prefer .claude/ values (more recent format), fill gaps from the TOML.

Step 6 — Archive history

Legacy approval records, user-templates, and any other history should not be deleted — move them under documentation/archive/{source-name}/ so they remain in git history and are discoverable if someone needs to trace a decision.

Step 7 — Update references

Some files may contain hardcoded .claude/ or .spec-workflow/ path references in their text (not just their location). After moving files, grep for these paths inside the moved files and update:

grep -l '.claude/\|.spec-workflow/' documentation/ --recursive

Common cases:

• tasks.md files referencing .claude/specs/{feature}/ in _Leverage: paths
• sprint kickoff docs referencing .claude/steering/ or .claude/specs/
• steering docs referencing .claude/ paths in examples

Update each to the documentation/ equivalent. Present diffs for approval before committing.

Step 8 — Remove empty legacy directories

After everything is moved, the legacy directories should be empty. Remove them:

rmdir .spec-workflow/templates .spec-workflow/steering .spec-workflow/specs .spec-workflow  2>/dev/null || true
rmdir .claude/steering .claude/specs .claude/releases .claude/sprints .claude  2>/dev/null || true

rmdir fails on non-empty dirs — this is intentional, surfacing anything overlooked.

Do NOT remove .claude/ at the user's home directory level — only at repo root.

Step 9 — Commit

Single commit per migration source:

refactor(docs): migrate .spec-workflow/ to documentation/

- steering, specs, archive moved under documentation/
- approvals archived to documentation/archive/approvals/
- config.example.toml translated to documentation/workflow-config.md
- internal path references updated

Legacy .spec-workflow/ directory removed.

Use git mv in the commit so rename history is preserved. Do not squash file moves into a feat commit — keep the migration reviewable as its own refactor.

Step 10 — Update downstream systems

Post-migration tasks (not automated by the skill — prompt the user):

• [ ] Update any CI scripts that reference .claude/ or .spec-workflow/ paths
• [ ] Update any editor/IDE config that excluded .claude/ from search
• [ ] Update .gitignore if it referenced legacy paths
• [ ] Re-publish affected Confluence pages if URLs have changed
• [ ] Notify team in Slack / standup that spec locations have moved

Collision handling policy

Reversibility

Because every move uses git mv and is in a single commit, reverting the migration is:

git revert {migration-commit-sha}

or, if the user wants to undo during the migration itself:

git restore --staged --worktree .

(before committing)

This is why Step 3 requires a clean tree — so revert is surgical.

What this migration does NOT do

• Does not change JIRA tickets (those are already in JIRA by key; the spec's new path is updated in ticket descriptions when backlog-manager is next invoked)
• Does not change Confluence pages (their URLs are content-based, not path-based)
• Does not re-publish the impl logs
• Does not upgrade legacy specs to add new fields (_Skill:, _Estimate:) — it preserves content verbatim. If a legacy spec is missing these, feature-spec-author in refine mode can add them, but that's a separate action.
• Does not migrate implementation logs that lived in the repo (those should have been JIRA comments from the start; if a legacy .claude/logs/ directory exists, archive it and flag for manual review)

After migration

Run the workflow's normal state detection (references/workflow-state.md probes). All probes should succeed against the new documentation/ layout. The orchestrator should report:

"Steering present, {N} features specced, {M} in backlog, sprint {K} active — ready to continue."

If any probe fails after migration, surface the gap to the user — don't silently re-migrate.

Phase Flow — I/O Contracts

Each phase has a defined input contract (what must exist before it starts) and output contract (what it produces). This file is the reference for orchestration.

Setup — Backend Selection (before Phase 0)

Input:

• The repo (existing or empty)
• Which tracker/docs MCPs are reachable (detected), or none

Output:

• documentation/workflow-config.md recording the chosen tracker

(jira | linear | ado | local) and docs (confluence | notion | ado-wiki | local) mode plus per-backend ids — filled from skills/ol-sdd-workflow/references/workflow-config-template.md

• The same selection baked into documentation/steering/tech.md →

## SDD Workflow Backends (written in Phase 0; the two surfaces stay in sync)

Gate: user has chosen both axes. Runs once per project; re-run only to switch backends. Every later phase reads the mode from workflow-config.md instead of asking.

Phase 0 — Steering

Input:

• A codebase directory (existing or empty)
• Optionally: user-provided product goals, known tech stack, known directory preferences

Output:

• documentation/steering/product.md (from prompts/coding/templates/product-template.md)
• documentation/steering/tech.md (from prompts/coding/templates/tech-template.md) — includes the ## SDD Workflow Backends record (tracker + docs), kept in sync with workflow-config.md
• documentation/steering/structure.md (from prompts/coding/templates/structure-template.md)
• Docs pages (per the configured docs backend — Confluence/Notion/ADO Wiki, or the local files themselves): "Project Steering — {project name}" with three child pages

Approval gate output: Three documents committed to repo and published to the configured docs surface.

Phase 0.5 — Release Plan

Input:

• Approved steering docs (Phase 0 output)
• Release target (name + date)
• Capacity (engineer-days or hours across the release window)
• Optional: stakeholder feature requests, carry-over from prior releases

Output:

• documentation/releases/{release-name}/features.md (from release-plan-template.md): prioritised feature list with MoSCoW, T-shirt sizes, dependencies, three scope tiers
• documentation/releases/{release-name}/epic-map.md: feature → JIRA epic key mapping, with a Spec Status column that downstream skills update
• Confluence page: "Release Plan — {release-name}" under the project parent
• JIRA epic per in-scope feature (skeleton: summary, description, release:{name} label, priority label — no stories or subtasks yet)

Approval gate output: feature list approved; skeleton epics created. Features with empty epics are ready for Phase 1 specification.

This phase is optional. If skipped, Phase 1 creates standalone epics per feature (no release grouping). Recommended for any release larger than 2–3 features.

Phase 1 — Feature Spec

Input:

• Approved steering docs (Phase 0 output)
• Feature name and brief scope from user
• Optional but preferred: release epic from Phase 0.5 — if documentation/releases/{release}/epic-map.md has an epic for this feature, the spec attaches to that existing epic rather than creating a new one
• Upstream feature dependencies (optional)

Output:

• documentation/specs/{feature-name}/requirements.md (from requirements-template.md)
• documentation/specs/{feature-name}/design.md (from design-template.md)
• documentation/specs/{feature-name}/tasks.md (from tasks-template.md)
• Confluence page: feature spec under project parent (linked from the release page if applicable)
• If a release epic exists: its description is updated with a link to the spec, and epic-map.md Spec Status column is updated to "specced"

Sub-gates within Phase 1: 1. Requirements approval (before design starts) 2. Design approval (before tasks breakdown) 3. Tasks approval (before Phase 2)

Phase 2 — Backlog

Input:

• Approved documentation/specs/{feature}/tasks.md
• JIRA project key
• Confluence URL for the spec (for back-link)
• Optional: existing release epic from Phase 0.5 (documentation/releases/{release}/epic-map.md)

Output:

• One JIRA epic — either the existing release-skeleton epic (fleshed out with full description + story/subtask children) or a new standalone epic if no release plan exists
• N JIRA stories (one per top-level requirement or task group), children of the epic
• M JIRA subtasks (one per atomic task in tasks.md), children of stories
• Ticket map file: documentation/specs/{feature}/ticket-map.md (task_id → JIRA key)
• If a release is active: documentation/releases/{release}/epic-map.md Spec Status column updated to "in backlog"
• Each ticket has:
• Description with spec back-link
• Estimate (from tasks.md or user input)
• Labels (feature name, skill routing tag, release name if applicable)

Phase 3 — Sprint Plan

Input:

• JIRA epic(s) to pull tickets from
• Sprint capacity (engineer-days or hours)
• Sprint length (days)
• Sprint goal (one sentence)

Output:

• JIRA sprint created (or ticket list if permissions don't allow)
• documentation/sprints/sprint-{N}-kickoff.md — markdown sprint plan document modelled on sprint1_kickoff.md, containing:
• Sprint goal
• Architecture spec links (Confluence)
• Skill routing table
• Execution waves (dependency order)
• Review checklist
• Task execution order

Phase 4 — Execution

Input:

• Approved sprint plan (documentation/sprints/sprint-{N}-kickoff.md)
• JIRA sprint in "active" state

Output (per ticket):

• Code changes in the repo (delegated via engineer skill)
• A commit with conventional-commits message
• JIRA ticket transitioned to "Done"
• Implementation log comment on JIRA ticket (via Phase 5)

Output (per sprint):

• All scoped tickets Done or explicitly deferred
• Sprint retrospective notes appended to documentation/sprints/sprint-{N}-kickoff.md

Phase 5 — Implementation Log

Input:

• JIRA ticket key
• Task summary
• List of files created
• List of files modified
• Code stats (lines added/removed)
• Artifacts (apiEndpoints, components, functions, classes, integrations — schema from spec-workflow-mcp)

Output:

• JIRA issue comment on the ticket with the structured log
• Ticket labelled impl-logged (or similar) for traceability

The JIRA comment format is defined in prompts/coding/templates/jira-impl-log-template.md.

Usage Guide — ol-sdd-workflow

How to invoke the workflow and the skills it orchestrates, from first-time project setup through sprint execution.

Quick start (end-to-end, new project)

You: "use ol-sdd-workflow to take this project end to end — we want to ship Feature X in the next sprint"

The orchestrator will walk through: 1. Phase 0 — steering docs (product, tech, structure) 2. Phase 0.5 — release plan (feature list, Confluence roadmap, empty JIRA epics) 3. Phase 1 — feature spec for each in-scope feature (requirements → design → tasks) 4. Phase 2 — JIRA backlog (stories + subtasks added under the release epic) 5. Phase 3 — sprint plan 6. Phase 4 — sprint execution (with Phase 5 impl logs per task)

At each phase gate it will pause and ask for approval.

Invoking by phase

You don't have to start at Phase 0. Jump in wherever you are.

Resuming mid-workflow

You: "use ol-sdd-workflow — where are we?"

The orchestrator reads documentation/steering/, documentation/specs/, active JIRA sprints, and in-flight tickets, then summarises state and proposes the next action. You can approve or redirect.

Prerequisites

Before you can run the workflow end-to-end you need:

• Atlassian MCP configured — the skill creates/reads JIRA issues and Confluence pages via mcp__claude_ai_Atlassian__* tools. Without it, backlog-manager and jira-impl-logger cannot publish.
• A JIRA project with epic → story → subtask hierarchy enabled, and a board with sprints
• A Confluence space with a project parent page (for steering and spec documents)
• Optional: a documentation/workflow-config.md at repo root with:

  confluence_space: TBMLI
  confluence_parent_page: 6500000000
  jira_project: TI
  jira_board: 100
  default_assignee: khanm@ontoledgy.io
  sprint_length_days: 10

If absent, the skills will ask for these values on first run.

Repo layout the workflow creates

your-repo/
├── documentation/
│   ├── workflow-config.md              (JIRA/Confluence config; Phase 0)
│   ├── steering/
│   │   ├── product.md                  (Phase 0)
│   │   ├── tech.md                     (Phase 0)
│   │   └── structure.md                (Phase 0)
│   ├── releases/
│   │   └── {release-name}/
│   │       ├── features.md             (Phase 0.5; prioritised feature list)
│   │       └── epic-map.md             (Phase 0.5; feature → JIRA epic mapping)
│   ├── specs/
│   │   └── {feature-name}/
│   │       ├── requirements.md         (Phase 1, gate 1a)
│   │       ├── design.md               (Phase 1, gate 1b)
│   │       ├── tasks.md                (Phase 1, gate 1c)
│   │       └── ticket-map.md           (Phase 2; task_id → JIRA key)
│   └── sprints/
│       └── sprint-{N}-kickoff.md       (Phase 3)
└── (your code)

Implementation logs (Phase 5) do not go in the repo — they are comments on JIRA issues.

Approval gates — what to expect

At every gate the orchestrator will: 1. Show you the deliverable (file contents, JIRA preview, sprint plan) 2. Ask explicitly: "approve to proceed to Phase {N+1}, or tell me what to change" 3. Wait. It does not advance on silence or ambiguous replies.

Acceptable approvals: approve, yes proceed, looks good, go.

On rejection with feedback, the orchestrator re-invokes the current phase's skill with your feedback, then re-presents.

Delegation: who actually writes the code

In Phase 4, sprint-executor is the tech lead. For each JIRA subtask it reads the skill:{name} label and delegates to that engineer skill (or to Codex via the mcp__codex__codex MCP, if your environment uses Codex as the implementation engine).

Routing table: see skills/feature-spec-author/references/skill-routing.md.

After the engineer skill returns, sprint-executor reviews via clean-code-reviewer, commits with conventional-commits format (via clean-code-commit), transitions the JIRA ticket, and invokes jira-impl-logger to post the impl log — all before moving to the next ticket.

Implementation logs — format and why JIRA

Each completed task gets a structured comment on its JIRA subtask containing:

• Files created / modified and line stats
• Structured artifacts: apiEndpoints, components, functions, classes, integrations, dataModels, pipelineStages
• Searchable keywords (for future AI agents grepping JIRA before writing new code)
• Back-links to spec, commit, related tickets

Template: prompts/coding/templates/jira-impl-log-template.md.

We chose JIRA comments over repo files because:

• JIRA is already the work-done system of record; repo logs duplicate git log
• JIRA is searchable via mcp__claude_ai_Atlassian__searchJiraIssuesUsingJql
• Comments naturally link to the ticket's full context (description, review, sprint)
• Repo log files tend to decay and rot

Replanning mid-sprint

You: "we have a blocker on TI-102, replan the rest of the sprint"

This re-invokes sprint-planner in replan mode. It reads current sprint state (done, in-flight, remaining), you describe the trigger (blocker, new priority, capacity change), and it proposes changes. On approval it updates JIRA and appends a "Replan {date}" addendum to the kickoff doc — history is preserved, never rewritten.

Adding tasks to an in-flight feature

If a new task surfaces during execution:

1. Add it to documentation/specs/{feature}/tasks.md with full metadata (_Requirements:, _Leverage:, _Skill:, _Estimate:) 2. Re-invoke backlog-manager with "add new task to existing epic {KEY}" 3. It creates a new subtask and appends to ticket-map.md — existing tickets are unchanged 4. Decide whether the new task goes in this sprint (re-invoke sprint-planner replan) or the backlog

Never delete JIRA tickets — use "Won't Do" status with a reason.

Not using all phases?

Every phase skill is independently callable. Common partial uses:

• Steering-only: product-vision-steering alone to document an existing codebase
• Release-planning-only: release-planner alone to enumerate and prioritise features for stakeholder review (produces Confluence roadmap + skeleton epics without forcing spec work)
• Spec-only: feature-spec-author to produce spec docs without JIRA publishing (useful for exploratory specs)
• JIRA-only: backlog-manager to publish an externally-authored tasks.md to JIRA
• Exec-only: sprint-executor against an existing JIRA sprint, without going through planning (useful when someone else planned the sprint)
• Log-only: jira-impl-logger to backfill impl logs on already-done tickets

The master ol-sdd-workflow skill is only needed when you want gated end-to-end orchestration.

When NOT to use this workflow

• One-liner bug fixes — too much overhead. Use a direct engineer skill and clean-code-commit.
• Exploratory spikes / R&D — specs constrain; spikes need freedom. Do the spike first, then write a feature spec if you keep any of it.
• Already-agreed work without external stakeholders — if the team knows the scope and trusts each other, you may not need Confluence/JIRA overhead. Use just the engineer skills.

Migrating from legacy spec locations

If your project has specs under .spec-workflow/ (upstream spec-workflow-mcp layout) or .claude/ (earlier ol-sdd-workflow versions), migrate them to the canonical documentation/ folder:

You: "use ol-sdd-workflow to migrate .claude/ to documentation/"
You: "migrate .spec-workflow/ to the new folder layout"

The migration uses git mv to preserve file history, single-commits the move for reviewability, translates legacy config files, archives approval/template history, and updates internal path references in moved files. Full procedure and collision-handling policy: migration.md.

Further reading

• SKILL.md — the orchestrator behaviour spec
• phase-flow.md — I/O contracts for each phase
• workflow-state.md — how state is detected for resumption
• migration.md — migrating legacy .spec-workflow/ or .claude/ layouts
• skills/feature-spec-author/references/skill-routing.md — engineer-skill routing table
• Upstream inspiration: https://github.com/Pimzino/spec-workflow-mcp

Workflow Config Template

Template for documentation/workflow-config.md — the machine-read configuration the SDD workflow and every phase skill consult to know which tracker and docs backend to use, plus the per-backend ids. Created by the ol-sdd-workflow Backend Selection setup step (before Phase 0) and kept in sync with the ## SDD Workflow Backends section of documentation/steering/tech.md.

Copy the block below into documentation/workflow-config.md, fill the chosen backends, and delete the config blocks for the backends you are not using.

# SDD workflow backend selection — the single source of truth for tracker/docs mode.
# Phase skills read this; the tracker/docs adapters resolve ids from it.
tracker: jira | linear | ado | local       # backlog + execution + impl-log surface
docs:    confluence | notion | ado-wiki | local   # design-doc surface
selected: { date: YYYY-MM-DD, by: "name" }  # when/who chose (audit trail)
defaultAssignee: null                        # optional

# ── Tracker config (keep only the chosen tracker's block) ──
jira:
  projectKey: ""        # e.g. TI
  boardId: ""
linear:
  team: ""              # shared team prefix, e.g. ONT
  project: ""           # the app project
ado:
  organization: ""      # https://dev.azure.com/{organization}
  project: ""
  process: agile | scrum | basic | cmmi   # drives the state names
  stateMap: {}          # optional override, e.g. {InReview: "Resolved", Blocked: "Blocked(tag)"}
local:
  prefix: LOC-          # work-item id prefix; files live in documentation/tracker/

# ── Docs config (keep only the chosen docs block) ──
confluence:
  spaceKey: ""
  parentPageId: ""      # section page ids are discovered/created under this
notion:
  rootPageId: ""
  dataSources: {}       # Specs / Releases / "Impl Logs" data-source ids
ado:
  wikiIdentifier: ""    # from wiki_list_wikis
  wikiRoot: "/SDD"      # section path prefix; pages land under {wikiRoot}/{Steering,Specs,...}
local: {}               # nothing required — documentation/ folders are created on demand

Notes

• One axis can be `local` while the other is remote (e.g. docs: ado-wiki +

tracker: ado, or docs: local + tracker: jira). The two axes are independent.

• The common pairs are jira+confluence, linear+notion, ado+ado-wiki, and

local+local (the fully-offline default when no MCP is available).

• Adapters resolve every concrete id from this file:

skills/task-executor/references/tracker-{jira,linear,ado,local}.md (tracker) and skills/feature-spec-author/references/docs-adapter.md (docs).

• This file is the machine-read copy; the human-readable mirror is the

## SDD Workflow Backends section of documentation/steering/tech.md. When one changes, update the other (the product-vision-steering skill keeps them aligned).

• Changing a backend mid-project is a steering decision — record it (don't silently

flip). Migrating existing tickets/pages between backends is out of scope for a flip; it is a deliberate migration.

Workflow State Detection

When invoked without explicit phase direction, infer the current phase by probing these surfaces in order.

State probes

probe 0: documentation/steering/product.md + tech.md + structure.md
  present & non-empty  → steering complete
  missing/empty        → Phase 0 required

probe 0.5: documentation/releases/{release}/epic-map.md
  present                    → release plan in place; read epic-map to identify
                               candidate features and their spec status
  absent and user is scoping → Phase 0.5 required (MVP, v1, roadmap language)
  absent and single-feature  → Phase 0.5 skippable; proceed to Phase 1 directly
    work                     

probe 1: documentation/specs/{feature}/ directory
  with requirements.md only              → Phase 1 mid, gate 1
  with requirements.md + design.md       → Phase 1 mid, gate 2
  with all three (incl. tasks.md)        → Phase 1 complete, ready for Phase 2
  absent                                  → Phase 1 not started

probe 2: JIRA epic state for target feature
  release-skeleton epic (no children)       → Phase 0.5 done, Phase 2 not yet
  epic with stories and subtasks            → Phase 2 complete
  no epic at all                             → neither Phase 0.5 nor Phase 2 done

probe 3: JIRA sprint containing epic's subtasks
  absent                 → Phase 3 required
  present, state=future  → Phase 3 complete, awaiting start
  present, state=active  → Phase 4 in progress

probe 4: tickets in sprint with status transitions
  all To-Do              → Phase 4 not started
  mixed                  → Phase 4 in progress
  all Done (or deferred) → Sprint complete

Multi-feature state

A project can have several features in flight simultaneously. When multiple documentation/specs/*/ exist:

1. List all feature folders 2. For each, report phase (use probe sequence above) 3. Ask the user which feature to operate on

Configuration file

If documentation/workflow-config.md exists, read it for project-level config:

# Workflow Config

confluence_space: TBMLI
confluence_parent_page: 6500000000
jira_project: TI
jira_board: 100
default_assignee: khanm@ontoledgy.io
sprint_length_days: 10

These values flow into the downstream skill invocations so the user isn't asked repeatedly.

Unknown state

If probes return inconsistent results (e.g., JIRA epic exists but no documentation/specs/), flag to the user:

"I see a JIRA epic {KEY} for {feature} but no spec folder in the repo. Did the spec live elsewhere, or should we reverse-engineer one from the epic description?"

Do not assume; ask.