182 lines
7.2 KiB
YAML
182 lines
7.2 KiB
YAML
name: fast-drive
|
|
version: 1
|
|
description: Fast OpenSpec workflow - design -> tasks -> apply
|
|
artifacts:
|
|
- id: design
|
|
generates: design.md
|
|
description: Self-contained solution brief and execution plan
|
|
template: design.md
|
|
instruction: |
|
|
Create design.md as the self-contained source of truth for what will
|
|
change, why it is changing, and how the work will be executed.
|
|
|
|
This workflow does not use proposal or specs artifacts. design.md MUST
|
|
preserve the important outcomes from prior exploration and user
|
|
discussion so a later apply phase can proceed correctly even after
|
|
context compression or in a new session.
|
|
|
|
Write for someone who cannot see the earlier conversation. Keep simple
|
|
changes concise, but include enough detail to make execution
|
|
unambiguous. Add more detail when any apply:
|
|
|
|
- Cross-cutting change across multiple systems, teams, workstreams, or
|
|
artifacts
|
|
|
|
- New dependency, integration, vendor, tool, policy, or external input
|
|
|
|
- Significant information model, process model, data model, or ownership
|
|
changes
|
|
|
|
- Security, privacy, compliance, performance, operational, or migration
|
|
complexity
|
|
|
|
- Ambiguity that benefits from decisions before execution
|
|
|
|
- Prior discussion settled non-obvious requirements, constraints, or
|
|
rejected alternatives
|
|
|
|
Required sections:
|
|
|
|
- **Context**: Problem, current state, relevant references, and the user
|
|
request that triggered this change
|
|
|
|
- **Discussion Notes**: Key points from exploration or prior discussion
|
|
that must not be lost. Include agreed conclusions, user preferences,
|
|
constraints, and important rejected ideas.
|
|
|
|
- **Requirements**: Expected outcomes, behavior/process/interface/content
|
|
changes, continuity expectations, and acceptance criteria.
|
|
|
|
- **Goals / Non-Goals**: What this change will achieve and what is
|
|
explicitly out of scope.
|
|
|
|
- **Execution Guardrails**: Must-follow constraints, forbidden approaches,
|
|
preserved behavior/processes, dependency limits, and project- or
|
|
workflow-specific boundaries.
|
|
|
|
- **Affected Areas**: Concrete artifacts, references, stakeholders,
|
|
systems, workstreams, documents, configurations, assets, or handoffs that
|
|
are relevant to the change.
|
|
|
|
- **Decisions**: Key choices with rationale (why X over Y?). For each
|
|
important decision, include alternatives considered and why they were not
|
|
chosen.
|
|
|
|
- **Execution Plan**: Main workstreams or artifacts to change, integration
|
|
or handoff points, sequencing, and any rollout notes.
|
|
|
|
- **Verification Plan**: Validation checks, reviews, approvals,
|
|
acceptance checks, documentation checks, communication checks, and manual
|
|
checks needed to prove the change is complete.
|
|
|
|
- **Risks / Trade-offs**: Known limitations and things that could go
|
|
wrong.
|
|
Format: [Risk] -> Mitigation
|
|
|
|
- **Open Questions**: Outstanding decisions, assumptions, or unknowns to
|
|
resolve before execution. Separate blocking questions that must pause
|
|
apply from non-blocking follow-ups. Use "None" if there are no open
|
|
questions.
|
|
|
|
Optional sections when relevant:
|
|
|
|
- **Migration / Rollout Plan**: Rollout steps, communication, ownership,
|
|
rollback, or continuity strategy.
|
|
|
|
Focus on preserving requirements, rationale, constraints, and approach.
|
|
Avoid line-by-line or step-by-step details unless a detail is a deliberate
|
|
decision from the discussion.
|
|
|
|
Prefer durable summaries over chat transcripts. Use concrete artifact
|
|
names, data/information shapes, examples, stakeholders, ownership, and
|
|
edge cases when they affect execution.
|
|
|
|
Do not use task checkboxes in design.md; checkboxes belong only in
|
|
tasks.md.
|
|
|
|
Final design.md must not contain unresolved template comments, empty
|
|
table rows, or placeholder text.
|
|
|
|
If information is missing, state assumptions and open questions instead
|
|
of inventing hidden requirements. Do not rely on unstated chat context.
|
|
requires: []
|
|
- id: tasks
|
|
generates: tasks.md
|
|
description: Trackable execution checklist derived from design.md
|
|
template: tasks.md
|
|
instruction: |
|
|
Create tasks.md by breaking design.md into executable work.
|
|
|
|
**IMPORTANT: Follow the template below exactly.** The apply phase parses
|
|
checkbox format to track progress. Tasks not using `- [ ]` will not be
|
|
tracked.
|
|
|
|
Guidelines:
|
|
|
|
- Derive tasks from design.md. Do not depend on proposal.md or specs
|
|
artifacts; any relevant prior discussion must already be captured in
|
|
design.md.
|
|
|
|
- Group related tasks under `##` numbered headings
|
|
|
|
- Each task MUST be a single-line checkbox: `- [ ] X.Y Task description`
|
|
|
|
- Tasks should be small enough to complete in one session
|
|
|
|
- Order tasks by dependency (what must be done first?)
|
|
|
|
- Start with context review tasks when execution depends on guardrails,
|
|
affected areas, or open questions
|
|
|
|
- Include validation tasks for checks, reviews, approvals, acceptance,
|
|
documentation, communication, and manual checks when required
|
|
|
|
- Do not include repository, version-control, or release operation tasks
|
|
unless they are explicitly part of the change scope
|
|
|
|
- Final tasks.md must not contain unresolved template comments, empty
|
|
table rows, or placeholder task text
|
|
|
|
Example:
|
|
|
|
```
|
|
## 1. Context Review
|
|
|
|
- [ ] 1.1 Read design.md and identify scope, requirements, decisions, guardrails, and open questions
|
|
- [ ] 1.2 Review relevant artifacts and references listed in Affected Areas
|
|
|
|
## 2. Execution
|
|
|
|
- [ ] 2.1 Execute first concrete work item from design.md
|
|
- [ ] 2.2 Execute next concrete work item from design.md
|
|
|
|
## 3. Validation
|
|
|
|
- [ ] 3.1 Run required validation from Verification Plan
|
|
- [ ] 3.2 Perform quality checks required by the project or workflow
|
|
- [ ] 3.3 Perform required manual review or acceptance checks from Verification Plan
|
|
|
|
## 4. Documentation / Communication
|
|
|
|
- [ ] 4.1 Update relevant documentation, runbooks, communication materials, or project references if behavior, process, interface, configuration, or usage changed
|
|
```
|
|
|
|
Reference design.md for scope, requirements, decisions, execution
|
|
direction, and verification expectations.
|
|
|
|
Each task should be verifiable: it must be clear when the task is done.
|
|
requires:
|
|
- design
|
|
apply:
|
|
requires:
|
|
- design
|
|
- tasks
|
|
tracks: tasks.md
|
|
instruction: |
|
|
Read design.md first, then tasks.md.
|
|
Also follow workflow context/configuration, such as openspec/config.yaml when available, and any relevant project or workflow documentation referenced by design.md.
|
|
Treat design.md as the source of truth for scope, requirements, decisions, guardrails, execution direction, and verification expectations.
|
|
Work through pending tasks in dependency order and mark complete as you go.
|
|
Mark a task complete only after its execution and required verification are done.
|
|
Pause if tasks conflict with design.md, if design.md has blocking open questions, or if clarification is needed.
|