workflow-guide

---
name: workflow-guide
description: >-
  Routes a piece of work to the right pipeline in this collection. First decides
  TaskTracker vs file-based (the tt-* skills when a TaskTracker MCP is available and the
  project is tracked there; /create-plan and /implement-plan otherwise; /brainstorm serves
  both), then
  picks the lane by work shape: sequential phase-by-phase implementation, an autonomous
  gated run (/tt-workflow-run), an unattended /loop build prompt (/tt-create-build-loop),
  a parallel build (/tt-workflow-build), a read-only audit at scale (/tt-workflow-audit),
  or one GitHub issue to a merged PR (/ship-issue). Use when the user asks which workflow,
  pipeline or mode to use, whether to run work in parallel, or is about to start building
  without having picked a lane. It recommends a lane and the next command; it does not
  run the work itself.
---

# Workflow Guide

<!-- contents: generated by tests/skill_structure.py --write; edit headings, not this block -->
## Contents

- [How to decide](#how-to-decide)
- [Decision table](#decision-table)
- [Parallel lanes](#parallel-lanes)
- [Output](#output)
- [Examples](#examples)
<!-- /contents -->

Pick one lane for the user's work and name the command to run next. Commands are written unprefixed; with the `devflow` plugin installed they are `/devflow:<name>`.

## How to decide

1. **TaskTracker or file-based.** Use the TaskTracker column when TaskTracker MCP tools (`mcp__tasktracker__*`) are available and the project is tracked there: the user names a TaskTracker project, an active task is set, or `tasktracker_listProjects` has a project for this repo (load the tool with ToolSearch if it is deferred). Otherwise use the file-based column. The tt-* skills keep plans, phases and insights in TaskTracker, so a file-based skill in a tracked project only produces orphan markdown.
2. **Work shape.** Find the row that matches what the user wants done.
3. **Ask only what is missing.** If the request already answers both, recommend straight away. Otherwise ask at most two short questions — whether the project is tracked in TaskTracker, and what shape the work has (explore, plan, build, audit, one issue). Don't ask about anything the table doesn't use.

## Decision table

| The user wants to… | TaskTracker | File-based |
|---|---|---|
| Refine a rough idea before planning | `/brainstorm` (writes `docs/brainstorms/`; `/tt-create-plan` reads it) | `/brainstorm` |
| Turn an idea or clear requirement into a phased plan | `/tt-create-plan` | `/create-plan` |
| Implement a plan phase by phase, confirming between phases | `/tt-implement-plan` | `/implement-plan` |
| Drive the ready backlog to done autonomously, with per-slice gates and measured time | `/tt-workflow-run` | `/implement-plan` (no autonomous lane) |
| Leave the project building itself unattended across many `/loop` iterations | `/tt-create-build-loop` (writes the loop prompt; it then runs under `/loop`) | none — use `/implement-plan` |
| Build many independent pieces at once | `/tt-workflow-build` | `/tt-workflow-build` if the user agrees to track the project in TaskTracker (it creates one); otherwise `/implement-plan` |
| Audit or analyze a whole repo, backlog or component set, read-only | `/tt-workflow-audit` | `/codebase-audit` |
| Take one GitHub issue to a merged PR | `/ship-issue <issue>` | `/ship-issue <issue>` |

A full pipeline runs the first three rows in order; skip brainstorming when the requirement is already clear.

`/ship-issue` is manual-only (`disable-model-invocation`), so tell the user to type it rather than invoking it.

## Parallel lanes

`/tt-workflow-build` and `/tt-workflow-audit` fan work out to many agents. They use the Claude Code `Workflow` tool when it is in your tool list — it is opt-in, enabled with `/config` → "Dynamic workflows" — and otherwise fall back to parallel `Agent` subagents. Check your own tool list to see which applies, and mention it in the recommendation, since the `Workflow` path costs noticeably more tokens and shows a confirmation prompt on first use.

They pay off when the units are independent and their results can be merged afterwards. Work where each step depends on the previous result belongs in a sequential lane (`/tt-implement-plan`, `/tt-workflow-run`, `/implement-plan`). In both parallel skills the parent session makes every TaskTracker write and the fanned-out agents stay read-only — see [the workflow–TaskTracker contract](../tt-workflow-audit/references/workflow-tasktracker-contract.md).

## Output

```
## Recommendation: <lane>

Why: <one or two sentences tying the request to the table row and the TaskTracker/file-based choice>

Next: `/<command> <args>`  (then `/<command>` … if it is a multi-step pipeline)

Alternative: <only if borderline — the adjacent row and when to switch>
```

## Examples

> **User:** "Fix the date formatting bug in the dashboard." No TaskTracker tools available.
>
> **Recommendation:** file-based pipeline without the brainstorm, since the problem is already clear. Next: `/create-plan`, then `/implement-plan <plan>`.

> **User:** "Add OAuth2 with Google and GitHub to the billing app." An active TaskTracker task belongs to the billing project.
>
> **Recommendation:** TaskTracker pipeline. Next: `/brainstorm` to settle the provider design, `/tt-create-plan` with the brainstorm file it wrote, then `/tt-implement-plan`. Alternative: once the plan has independent provider phases, `/tt-workflow-build` can build them in parallel.

> **User:** "Find all architecture drift and duplicate tasks across this project." The project is tracked in TaskTracker.
>
> **Recommendation:** read-only audit at scale. Next: `/tt-workflow-audit`. Say whether it will run on the `Workflow` tool or on parallel subagents, based on your tool list.

> **User:** "I want this repo to keep building overnight without me."
>
> **Recommendation:** TaskTracker, unattended row (ask whether it is tracked if you can't tell). Next: `/tt-create-build-loop`, then `/loop` with the prompt it writes. Alternative: `/tt-workflow-run` for a measured, gated run that pauses at human gates.