| name | stack-decomposition-format |
| description | Structured format contract for "## Stack Decomposition" sections in plan documents, shared by gt-stack-plan (producer) and flow:work (consumer). Use when writing or parsing a Stack Decomposition section. |
| user-invocable | false |
What It Does
Defines the machine-readable format for ## Stack Decomposition sections
that gt-stack-plan writes into plan documents, and that flow:work
(yellow-core) parses to execute a stack bottom-up. Both sides must agree on
this format exactly — it is a contract, not free-form prose.
When to Use
- Writing a
## Stack Decomposition section (the gt-stack-plan skill,
Phase 3).
- Parsing a
## Stack Decomposition section (the flow:work skill's
Phase 1a stack detection).
- Reading or writing the companion
## Stack Progress section that tracks
execution.
Usage
Machine-readable contract between gt-stack-plan (producer) and
flow:work (consumer). Both commands must agree on this format.
Section Structure
The ## Stack Decomposition section is appended to a plan document by
gt-stack-plan. It uses structured markdown with numbered ### subsections
per stack item.
## Stack Decomposition
<!-- stack-topology: linear -->
<!-- stack-trunk: main -->
### 1. feat/branch-slug-one
- **Type:** feat
- **Description:** Short description of what this PR does
- **Scope:** path/to/file1.ts, path/to/file2.ts
- **Tasks:** 1.1, 1.2, 1.3
- **Depends on:** (none)
- **Linear:** ENG-123
### 2. fix/branch-slug-two
- **Type:** fix
- **Description:** Short description of what this PR does
- **Scope:** path/to/file3.ts
- **Tasks:** 2.1, 2.2
- **Depends on:** #1
- **Linear:** ENG-124
Fields
Each stack item heading uses the format ### N. type/branch-name where N is
the stack position (1-indexed) and type/branch-name is the Graphite branch
name.
| Field | Required | Format | Description |
|---|
| Type | Yes | Conventional commit prefix | feat, fix, refactor, docs, test, chore, etc. |
| Description | Yes | Single line | One-line summary used as PR title |
| Scope | Yes | Comma-separated paths | Files or directories this item touches |
| Tasks | Yes | Comma-separated IDs | Plan task IDs from ## Implementation Plan (e.g., 1.1, 1.2) |
| Depends on | Yes | (none) or #N refs | Prerequisite items by number |
| Linear | No | Issue ID | Linear issue identifier (e.g., ENG-123) |
HTML Comment Metadata
Placed immediately after the ## Stack Decomposition heading, before the
first item.
| Comment | Required | Values | Description |
|---|
stack-topology | Yes | linear, parallel, mixed | How items relate to each other |
stack-trunk | Yes | Branch name | Base branch for the stack (usually main) |
Topologies
Examples below show dependency relationships in shorthand for readability.
Actual output uses the full field format from Section Structure above.
Linear
Each item depends on the previous. flow:work creates each branch on
top of the last with gt create.
<!-- stack-topology: linear -->
<!-- stack-trunk: main -->
### 1. feat/auth-types → Depends on: (none)
### 2. feat/auth-middleware → Depends on: #1
### 3. feat/auth-routes → Depends on: #2
Parallel
Items are independent, all branching off trunk. flow:work checks out
trunk before creating each branch.
<!-- stack-topology: parallel -->
<!-- stack-trunk: main -->
### 1. docs/update-readme → Depends on: (none)
### 2. fix/lint-warnings → Depends on: (none)
### 3. test/add-coverage → Depends on: (none)
Mixed
Some items are stacked, others are parallel. The Depends on field determines
the dependency graph. Note that while mixed topology is defined for forward-compatibility,
the flow:work consumer currently only supports linear and parallel topologies.
<!-- stack-topology: mixed -->
<!-- stack-trunk: main -->
### 1. feat/core-types → Depends on: (none)
### 2. feat/core-logic → Depends on: #1
### 3. feat/api-routes → Depends on: #2
### 4. docs/migration-guide → Depends on: (none)
Standalone Invocation
When gt-stack-plan is invoked without a plan file path, it writes the full
## Stack Decomposition section to .gt-stack-plan.md in the repo root.
This file uses the identical format and can be consumed by flow:work.
Idempotency
If ## Stack Decomposition already exists in the target plan file,
gt-stack-plan replaces it entirely (does not append a duplicate). The
replacement preserves all content before and after the section.
Progress Tracking
When flow:work executes a stack, it writes a ## Stack Progress
section after ## Stack Decomposition:
## Stack Progress
<!-- Updated by flow:work. Do not edit manually. -->
- [x] 1. feat/branch-slug-one (completed 2026-03-10)
- [ ] 2. feat/branch-slug-two
- [ ] 3. fix/branch-slug-three
On resume, flow:work reads this section and skips completed items,
cross-referencing with gt log short to verify branches exist.
