# Stack Decomposition Format

> 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.

- Skill: `kinginyellows/stack-decomposition-format` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kinginyellows/stack-decomposition-format`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinginyellows/stack-decomposition-format/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: kinginyellows (https://skillmd.com/u/kinginyellows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kinginyellows/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.

```markdown
## 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`.

```markdown
<!-- 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.

```markdown
<!-- 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.

```markdown
<!-- 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`:

```markdown
## 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.