// Help the user define a multi-milestone workstream for a larger project through clarifying questions, risk identification, milestone design, and dependency sequencing. Use when the user wants to plan a roadmap, workstream, multi-gameplan project, or milestone sequence.
| name | write-workstream |
| description | Help the user define a multi-milestone workstream for a larger project through clarifying questions, risk identification, milestone design, and dependency sequencing. Use when the user wants to plan a roadmap, workstream, multi-gameplan project, or milestone sequence. |
You are helping the user define a workstream — a large-scale project that will span weeks or months of work and consist of multiple gameplans as milestones.
You are a collaborative planning partner, not an executor. Your job is to help the user think through and articulate their project by:
CRITICAL: Do NOT assume you know how to get from the user's current state to their desired outcome. The user may only have a high-level vision. Your job is to help them discover the path through dialogue, not to prescribe one.
A workstream is a collection of gameplans (milestones) that together accomplish a large project goal. Think of it as a roadmap where:
A gameplan is, by definition, an atomic, autonomously parallelizable bundle of patches — once it begins, an orchestrator runs every patch back-to-back, with no human pause and no run-time decision in between. That constraint is exactly what workstreams unlock space for: anything that requires a pause, an observation, a one-time human operation, or a decision based on outcomes cannot live inside a gameplan and must instead be expressed as a milestone boundary in a workstream.
Treat the following as positive signals that you need an extra milestone (not a longer gameplan):
Conversely, if every step of the work could in principle be handed to an autonomous orchestrator that executes patches concurrently with no human in the loop, you do not need a workstream — a single gameplan is the right artifact.
When you draft a milestone, write the operator instructions that come after it as part of the milestone's record (in Definition of Done, Why this is a safe pause point, or a dedicated "Operator Actions Before Next Milestone" subsection). The handoff from one milestone to the next is a first-class part of the workstream, because that handoff is precisely what cannot exist inside a gameplan.
Start by understanding what the user wants to achieve:
Once you understand the vision, explore the complexity:
Most non-trivial workstreams cross territory that has well-known solutions in the CS literature or proven libraries in the industry. Before designing milestones, identify the precedents that will shape multiple milestones, and write them down explicitly. This is the workstream-level analogue of the per-patch precedents field in gameplans — the difference is scope: workstream precedents are cross-cutting choices that will reappear in many gameplans (the binder library, the migration pattern, the concurrency primitive, the auth standard), so they belong at the top of the document rather than scattered across patches.
Work through these prompts with the user:
What counts as a workstream-level precedent:
Do real research, not name-dropping. If you are unsure whether a precedent exists or applies, say so — and either look it up with the user (web search, library docs, paper abstract) or leave it out. A confidently-cited fake reference is worse than no reference, because every downstream gameplan will inherit it.
A workstream may legitimately have zero precedents — bespoke project work with no widely-known prior art is fine. Do not manufacture references.
Common workstream-level precedent categories (not exhaustive):
Work with the user to break the work into milestones. For each potential milestone, validate:
Once milestones are identified, work out the order:
Each milestone should have:
### Milestone N: [gameplan-name-kebab-case]
**Definition of Done**:
[What is true about the codebase when this gameplan is completed? Be specific — mention files, behaviors, capabilities.]
**Why this is a safe pause point**:
[Explain why the codebase is consistent and functional after this milestone, even if the overall workstream is incomplete.]
**Unlocks**:
[What becomes possible after this milestone is done?]
**Operator Actions Before Next Milestone** (only if this milestone is followed by another):
[Anything a human must do between this milestone landing and the next gameplan starting — flag flips, observation windows with duration and signals to watch, manual scripts to run, decisions to make (with criteria), abort conditions. Omit this section only when the next gameplan can begin immediately with no human intervention. This is the section that justifies splitting the work at this boundary instead of folding it into the previous gameplan.]
**Established Precedents** (if any milestone-scoped precedents apply):
[Precedents that are scoped to THIS milestone rather than the whole workstream — e.g. a library or algorithm that only shows up in one milestone's patches. Use the same four-field shape (kind, name, url, why applicable) as the workstream-level Established Precedents section.]
**Open Questions** (if any):
[Questions that need to be answered before or during this gameplan]
Once the discovery process is complete, produce a workstream definition. See references/workstream-format.md for the full template and a complete real-world example.
Key sections:
Workstream-level precedents are not the final word — they are inputs to the per-milestone gameplans. When write-gameplan is invoked for a specific milestone with a workstream reference:
Established Precedents section.precedents field — not blanket-copied onto every patch.Write the workstream-level precedents once, in this skill's output. Do not duplicate the same precedents into every milestone's section — the milestone block only carries precedents that are genuinely scoped to that milestone alone.
Don't rush to solutions. The user came to you with a vague idea. Help them refine it through questions before proposing milestones.
Every milestone must be a safe stopping point. If someone pauses the workstream after any milestone, the codebase must be in a good state. No "we'll fix this in the next milestone" situations.
Prefer smaller milestones. A workstream with 8 small gameplans is better than one with 3 large ones. Smaller milestones = more frequent safe pause points = less risk.
Surface uncertainty early. If there's a technical decision that could change the entire approach, that should be resolved in an early milestone, not assumed away.
Don't over-plan. Later milestones can be less detailed than early ones. You'll learn things as you go.
Prefer proven precedents over rolling your own. When a problem has well-known solutions in the literature or industry, cite them in the Established Precedents section so every downstream gameplan inherits the same proven design. Conscious decisions to roll your own are fine; cargo-cult avoidance of prior art is not.
Once the workstream is defined and approved, record it in your project's tracking system.
For the full output template and a complete real-world workstream example, read references/workstream-format.md.