Feat(ship): add configurable PR body sections (#3391)
* feat: add configurable ship PR body sections * chore: add changeset for ship PR sections * docs: avoid prompt scanner trigger in PR body guide * docs: escape pr body source separator
This commit is contained in:
Tom Boucher
@@ -291,6 +291,9 @@ Create PR from completed phase work with auto-generated body.
|
||||
- Requirements addressed (REQ-IDs)
|
||||
- Verification status
|
||||
- Key decisions
|
||||
- Optional configured PRD-style sections from `ship.pr_body_sections`
|
||||
|
||||
See [Custom PR Body Sections](ship-pr-body-sections.md) for onboarding, examples, and validation rules.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -59,6 +59,9 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
|
||||
"build_command": null,
|
||||
"test_command": null
|
||||
},
|
||||
"ship": {
|
||||
"pr_body_sections": []
|
||||
},
|
||||
"hooks": {
|
||||
"context_warnings": true,
|
||||
"workflow_guard": false
|
||||
@@ -225,6 +228,56 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
|
||||
| `workflow.build_command` | string | (none) | Shell command to build the project in the post-merge build gate (Step A of step 5.6 in execute-phase). When unset, the gate auto-detects: Xcode (`.xcodeproj` present) → `xcodebuild build`, `Makefile` with `build:` target → `make build`, Justfile → `just build`, `Cargo.toml` → `cargo build`, `go.mod` → `go build ./...`, Python → `python -m py_compile`, `package.json` with `build` script → `npm run build`. Runs with a 5-minute timeout; failure increments `WAVE_FAILURE_COUNT`. Added in v1.39 |
|
||||
| `workflow.test_command` | string | (none) | Shell command to run the project's test suite in the post-merge test gate (Step B of step 5.6 in execute-phase) and the regression gate. When unset, the gate auto-detects: Xcode (`.xcodeproj` present) → `xcodebuild test`, `Makefile` with `test:` target → `make test`, Justfile → `just test`, `package.json` → `npm test`, `Cargo.toml` → `cargo test`, `go.mod` → `go test ./...`, Python → `python -m pytest`. Runs with a 5-minute timeout; failure increments `WAVE_FAILURE_COUNT`. Added in v1.39 |
|
||||
|
||||
## Ship Settings
|
||||
|
||||
`ship.pr_body_sections` adds additional PR body sections for project-specific PRD/PR body content in `/gsd-ship` without editing `get-shit-done/workflows/ship.md`.
|
||||
|
||||
For a user guide with onboarding examples and troubleshooting, see [Custom PR Body Sections](ship-pr-body-sections.md).
|
||||
|
||||
This list is append-only: configured entries are added after the core `Summary`, `Changes`, `Requirements Addressed`, `Verification`, and `Key Decisions` sections. They cannot replace, remove, or reorder required sections.
|
||||
|
||||
Recommended lean/agile PRD uses include user stories, acceptance criteria, Definition of Done or release criteria, risks and dependencies, success metrics, and stakeholder review notes. Keep these sections short and evidence-oriented so the PR body remains a living release artifact rather than a static requirements dump.
|
||||
|
||||
Each entry supports:
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `heading` | string | required | Markdown section heading rendered as `## {heading}`. Must be a single line. |
|
||||
| `enabled` | boolean | `true` | When `false`, onboarding can keep a candidate section in config without rendering it in generated PR bodies. |
|
||||
| `source` | string | (none) | Optional fallback chain of planning artifact headings, such as `PLAN.md ## Risks \|\| VERIFICATION.md ## Manual Checks`. Allowed artifacts are `ROADMAP.md`, `PLAN.md`, `SUMMARY.md`, `VERIFICATION.md`, `STATE.md`, `REQUIREMENTS.md`, and `CONTEXT.md`. |
|
||||
| `template` | string | (none) | Literal Markdown with closed tokens: `{phase_number}`, `{phase_name}`, `{phase_dir}`, `{base_branch}`, `{padded_phase}`. |
|
||||
| `fallback` | string | (none) | Literal Markdown used when `source` yields no content and no `template` is provided. |
|
||||
|
||||
At least one of `source`, `template`, or `fallback` is required for each section. The default is `[]`, so existing projects keep their current `/gsd-ship` output until onboarding adds enabled entries.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"ship": {
|
||||
"pr_body_sections": [
|
||||
{
|
||||
"heading": "User Stories & Acceptance Criteria",
|
||||
"enabled": true,
|
||||
"source": "REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria",
|
||||
"fallback": "- Acceptance criteria are covered by the linked requirements and verification evidence."
|
||||
},
|
||||
{
|
||||
"heading": "Risks & Rollback",
|
||||
"enabled": true,
|
||||
"source": "PLAN.md ## Risks || PLAN.md ## Rollback",
|
||||
"fallback": "- Rollback: revert this PR."
|
||||
},
|
||||
{
|
||||
"heading": "Stakeholder Sign-off",
|
||||
"enabled": false,
|
||||
"template": "- Product owner: pending for {phase_name}"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Recommended Presets
|
||||
|
||||
| Scenario | mode | granularity | profile | research | plan_check | verifier |
|
||||
|
||||
@@ -412,10 +412,13 @@
|
||||
- REQ-SHIP-03: System MUST auto-generate PR body from SUMMARY.md, VERIFICATION.md, and REQUIREMENTS.md
|
||||
- REQ-SHIP-04: System MUST update STATE.md with shipping status and PR number
|
||||
- REQ-SHIP-05: System MUST support `--draft` flag for draft PRs
|
||||
- REQ-SHIP-06: System MUST support append-only project PR body sections configured with `ship.pr_body_sections`
|
||||
|
||||
**Prerequisites:** Phase verified, `gh` CLI installed and authenticated, work on feature branch
|
||||
|
||||
**Produces:** GitHub PR with rich body, STATE.md updated
|
||||
**Produces:** GitHub PR with rich body, optional configured PRD-style sections, STATE.md updated
|
||||
|
||||
**User documentation:** [Custom PR Body Sections](ship-pr-body-sections.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -13,6 +13,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
|
||||
| [Feature Reference](FEATURES.md) | All users | Feature narratives and requirements for released features (see [CHANGELOG](../CHANGELOG.md) for latest additions) |
|
||||
| [Command Reference](COMMANDS.md) | All users | Stable commands with syntax, flags, options, and examples |
|
||||
| [Configuration Reference](CONFIGURATION.md) | All users | Full config schema, workflow toggles, model profiles, git branching |
|
||||
| [Custom PR Body Sections](ship-pr-body-sections.md) | All users | How to append project-specific PRD sections to `/gsd-ship` PR bodies |
|
||||
| [CLI Tools Reference](CLI-TOOLS.md) | Contributors, agent authors | `gsd-tools.cjs` programmatic API for workflows and agents |
|
||||
| [Agent Reference](AGENTS.md) | Contributors, advanced users | Role cards for primary agents — roles, tools, spawn patterns (the `agents/` filesystem is authoritative) |
|
||||
| [User Guide](USER-GUIDE.md) | All users | Workflow walkthroughs, troubleshooting, and recovery |
|
||||
@@ -29,5 +30,6 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
|
||||
- **Full workflow walkthrough:** [User Guide](USER-GUIDE.md)
|
||||
- **All commands at a glance:** [Command Reference](COMMANDS.md)
|
||||
- **Configuring GSD:** [Configuration Reference](CONFIGURATION.md)
|
||||
- **Customizing ship PR bodies:** [Custom PR Body Sections](ship-pr-body-sections.md)
|
||||
- **How the system works internally:** [Architecture](ARCHITECTURE.md)
|
||||
- **Contributing or extending:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md)
|
||||
|
||||
@@ -249,6 +249,10 @@ Once a phase is verified, ship it:
|
||||
/gsd-ship 1 # Creates a PR with auto-generated body
|
||||
```
|
||||
|
||||
The PR body always includes the required GSD sections: `Summary`, `Changes`, `Requirements Addressed`, `Verification`, and `Key Decisions`. During `/gsd-new-project`, you can also enable optional PRD-style sections such as user stories, acceptance criteria, risks, release criteria, and stakeholder approval. These are appended through `ship.pr_body_sections` and do not change the required core sections.
|
||||
|
||||
For setup examples, field definitions, and troubleshooting, see [Custom PR Body Sections](ship-pr-body-sections.md).
|
||||
|
||||
For multi-phase projects, repeat the loop:
|
||||
|
||||
```
|
||||
|
||||
170
docs/ship-pr-body-sections.md
Normal file
170
docs/ship-pr-body-sections.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Custom PR Body Sections
|
||||
|
||||
`/gsd-ship` creates a pull request body from the planning artifacts for a verified phase. Projects can append extra PRD-style sections to that body with `ship.pr_body_sections` in `.planning/config.json`.
|
||||
|
||||
Use this when your project needs the PR to carry more release context than the default GSD sections, such as user stories, acceptance criteria, risks, release criteria, or stakeholder approval notes.
|
||||
|
||||
## What GSD Always Includes
|
||||
|
||||
Every generated `/gsd-ship` PR body keeps the required core sections:
|
||||
|
||||
- `Summary`
|
||||
- `Changes`
|
||||
- `Requirements Addressed`
|
||||
- `Verification`
|
||||
- `Key Decisions`
|
||||
|
||||
Custom sections are append-only. They render after `Key Decisions`; they cannot replace, remove, or reorder the core sections.
|
||||
|
||||
## Configure Sections During Onboarding
|
||||
|
||||
During `/gsd-new-project`, GSD can seed optional PRD-style sections into `.planning/config.json`.
|
||||
|
||||
Recommended onboarding choices:
|
||||
|
||||
- `User Stories & Acceptance Criteria` for user-facing stories and acceptance checks.
|
||||
- `Risks & Dependencies` for rollout risks, dependencies, and rollback notes.
|
||||
- `Success Metrics & Release Criteria` for Definition of Done, measurable outcomes, and release checks.
|
||||
- `Stakeholder Review & Approval` for sign-off traceability.
|
||||
|
||||
Selected sections are written with `"enabled": true`. Seeded but unselected sections are written with `"enabled": false`, so you can enable them later without editing the shipped `/gsd-ship` workflow.
|
||||
|
||||
## Configure Sections Manually
|
||||
|
||||
Set `ship.pr_body_sections` with `gsd-sdk query config-set`:
|
||||
|
||||
```bash
|
||||
gsd-sdk query config-set ship.pr_body_sections '[{"heading":"Risks & Dependencies","enabled":true,"source":"PLAN.md ## Risks || PLAN.md ## Dependencies","fallback":"- No known high-risk rollout dependencies."}]'
|
||||
```
|
||||
|
||||
You can also edit `.planning/config.json` directly:
|
||||
|
||||
```json
|
||||
{
|
||||
"ship": {
|
||||
"pr_body_sections": [
|
||||
{
|
||||
"heading": "User Stories & Acceptance Criteria",
|
||||
"enabled": true,
|
||||
"source": "REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria",
|
||||
"fallback": "- Acceptance criteria are covered by the linked requirements and verification evidence."
|
||||
},
|
||||
{
|
||||
"heading": "Risks & Dependencies",
|
||||
"enabled": true,
|
||||
"source": "PLAN.md ## Risks || PLAN.md ## Dependencies",
|
||||
"fallback": "- No known high-risk rollout dependencies."
|
||||
},
|
||||
{
|
||||
"heading": "Stakeholder Review & Approval",
|
||||
"enabled": false,
|
||||
"template": "- Product owner approval pending for {phase_name}."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Section Fields
|
||||
|
||||
Each section is an object with these fields:
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `heading` | Yes | Markdown heading text rendered as `## {heading}`. Must be one line. |
|
||||
| `enabled` | No | Defaults to `true`. Set `false` to keep a section in config without rendering it. |
|
||||
| `source` | No | Fallback chain of planning artifact headings to copy into the PR body. |
|
||||
| `template` | No | Literal Markdown with a small set of supported tokens. |
|
||||
| `fallback` | No | Literal Markdown used when `source` finds no content and no `template` is present. |
|
||||
|
||||
Each section must include at least one of `source`, `template`, or `fallback`.
|
||||
|
||||
## Source Selectors
|
||||
|
||||
`source` points at headings in planning artifacts. Use `||` to provide fallbacks:
|
||||
|
||||
```text
|
||||
REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria
|
||||
```
|
||||
|
||||
Allowed source files:
|
||||
|
||||
- `ROADMAP.md`
|
||||
- `PLAN.md`
|
||||
- `SUMMARY.md`
|
||||
- `VERIFICATION.md`
|
||||
- `STATE.md`
|
||||
- `REQUIREMENTS.md`
|
||||
- `CONTEXT.md`
|
||||
|
||||
If the first selector has no content, GSD tries the next selector. If no selector produces content, GSD uses `fallback` when present. Empty final bodies are omitted.
|
||||
|
||||
## Template Tokens
|
||||
|
||||
`template` supports only these tokens:
|
||||
|
||||
- `{phase_number}`
|
||||
- `{phase_name}`
|
||||
- `{phase_dir}`
|
||||
- `{base_branch}`
|
||||
- `{padded_phase}`
|
||||
|
||||
Unknown tokens are rejected by config validation. This keeps PR body generation predictable and avoids accidental prompt or shell expansion.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"heading": "Stakeholder Review & Approval",
|
||||
"enabled": true,
|
||||
"template": "- Product owner approval pending for {phase_name}."
|
||||
}
|
||||
```
|
||||
|
||||
## Agile PRD Examples
|
||||
|
||||
For a lightweight agile PRD trail, use sections that map to the increment being shipped:
|
||||
|
||||
```json
|
||||
{
|
||||
"heading": "User Stories & Acceptance Criteria",
|
||||
"enabled": true,
|
||||
"source": "REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria",
|
||||
"fallback": "- Acceptance criteria are covered by the linked requirements and verification evidence."
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"heading": "Success Metrics & Release Criteria",
|
||||
"enabled": true,
|
||||
"source": "REQUIREMENTS.md ## Definition of Done || VERIFICATION.md ## Release Criteria",
|
||||
"fallback": "- Release when automated verification and required manual checks pass."
|
||||
}
|
||||
```
|
||||
|
||||
These sections make the PR body useful as a release artifact: concise enough for review, but traceable back to requirements and verification.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `ship.pr_body_sections` is rejected
|
||||
|
||||
Check that the value is a JSON array and each entry has:
|
||||
|
||||
- a one-line `heading`
|
||||
- `enabled` as `true` or `false`, not a string
|
||||
- at least one of `source`, `template`, or `fallback`
|
||||
- only supported fields
|
||||
|
||||
### A section does not appear in the PR body
|
||||
|
||||
Check these conditions:
|
||||
|
||||
- `enabled` is not `false`
|
||||
- the selected source heading exists in the allowed artifact
|
||||
- `fallback` or `template` is present if source content may be missing
|
||||
- the rendered body is not empty after trimming
|
||||
|
||||
### A template token is rejected
|
||||
|
||||
Use only the supported token list above. Arbitrary environment variables, shell substitutions, and project-specific tokens are intentionally unsupported.
|
||||
Reference in New Issue
Block a user