Stack Decomposition Format

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.

HTML Comment Metadata

Placed immediately after the ## Stack Decomposition heading, before the first item.

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.