Skip to content
gdlc

Plan and track work with the planning and PR plugins

Run a plan-to-merge cycle: decompose a goal into issues, board them, open and classify the PR, and let linkage close the loop. Assumes Claude Code with this marketplace added (root README) and github-pull-requests installed (which brings github-sdlc-planning).

Steps 1–5 below can be driven by hand, tool by tool, or run end to end by asking for the epic-pipeline skill (github-sdlc-planning) with a goal, seed issue, or plan/design doc — it composes the exact same tools this page describes (plus file-bug/pr-review-route and a get_branch_protection pre-flight) into one decompose-then-execute pipeline, gated on explicit confirmation before executing and before merging. The skill itself is the interactive trigger; the orchestration runs as a bundled background Workflow script launched twice — plan mode, then (only after your explicit confirmation) execute mode — and merging always stays with you.

When the starting point is a search query rather than a single goal (“everything labeled tech-debt”, “all open Dependabot PRs”), ask for the query-pipeline skill instead — the fan-out counterpart: every query result is driven to its own reviewed, settled PR independently, with merging gated behind an explicit --automerge flag.

1. Decompose a goal into issues

Section titled “1. Decompose a goal into issues”

Ask for the epic-decomposition skill with your goal. It files an Epic and its Story/Task children as real GitHub sub-issues (native hierarchy, not task-list checkboxes), each body carrying the MIF comment block (mif-id/mif-type/mif-ns) so downstream tooling can read what each issue is. Under the hood: create_issue + add_sub_issue; use those tools directly for one-off issues. Progress on a parent is visible via list_sub_issues (total/completed/percent). create_issue’s owner/repo are optional if destination.repo is set in .config/gdlc/config.yml; when either a targeting allowlist is configured there, every create_issue call – explicit or defaulted – is checked against it.

2. Put work on the board

Section titled “2. Put work on the board”
  • New issues are auto-added with Status Todo when the org project has GitHub’s built-in workflows enabled, as this org’s board does (ADR-0003).
  • For a board without auto-add, add_item_to_project places an issue explicitly; it is idempotent and returns the existing item rather than creating a duplicate when the issue is already there.
  • Set any single-select/text/number/date/iteration field with set_field_value; read the board with get_project_items.
  • Milestones: create_milestone, assign_milestone, list_milestones; the milestone-triage skill flags overdue/empty/stale ones, and sprint-plan fills an iteration from the backlog.
  • Board bootstrap from nothing: the project-setup skill (or template-gallery for the curated Sprint/OKR/Bug-Triage/Feature layouts).

3. Mark work In Progress automatically

Section titled “3. Mark work In Progress automatically”

Configure the board mapping once per consuming project in .config/gdlc/config.yml (committed, team-shared – see the layered config schema for the full shape and how a project value overrides a global default). The recommended way to set it is the configure-gdlc agent, which reads the current state, elicits the values, and writes a schema-validated file; hand-editing the shape below directly still works too:

board:
  projectOwnerLogin: <org-or-user>
  projectNumber: <n>

With that in place, starting work through the tools (adding a sub-issue, updating an open issue) moves the affected item to In Progress when its Status is unset or Todo. Done needs nothing: the native workflows set it on close/merge. The same mapping also fills in projectOwnerLogin/ projectNumber on add_item_to_project/set_field_value/ get_project_items/get_session_context when a call omits them.

The legacy board: key in .claude/github-sdlc-planning.local.md frontmatter no longer works at all (ADR-0006 removed the one-release fallback ADR-0004 introduced); migrate that key into .config/gdlc/config.yml’s board: section if you haven’t already.

4. Open, classify, and route the PR

Section titled “4. Open, classify, and route the PR”

From github-pull-requests:

  • create_pull_request opens the PR via GraphQL.
  • classify_pull_request applies type:/size:/risk: labels; size is computed from the diff.
  • The pr-review-route skill suggests reviewers and requests them on your confirmation.
  • add_pull_request_to_project puts the PR itself on a board.

Write Fixes #N/Closes #N in the PR body so the merge closes the issue natively.

5. Close the loop after merge

Section titled “5. Close the loop after merge”
  • get_linked_issues reads which issues a PR closes (with retry, since GitHub populates the linkage asynchronously).
  • sync_linked_issues_project_field stamps a board field (a “Shipped in” iteration, a release column) across every issue the merged PR closed, matching items by repo and number so multi-repo boards stay correct.
  • The board’s Done transition happens natively on close; nothing to call.

Working outside Claude Code

Section titled “Working outside Claude Code”

Every write above goes through the portable MCP servers, so any MCP host drives the same flow; get_session_context replaces the SessionStart hook for context, and get_agent_capabilities is the feature-detection entry point. See Verify cross-agent portability.