Add METHODOLOGY.md: GitHub Issues + Project backlog guide#3
Merged
Conversation
Captures a methodology for running a project's backlog as GitHub Issues in a single per-repo public Project, with maintainer-driven status transitions (Triage -> In Design -> Ready -> Doing -> Done) that dispatch Claude Code agents for spec drafting and implementation. Coexists with the current BACKLOG.md / navigator approach during the transition.
|
🚀 Backlog Navigator preview deployed
This preview runs in dry-run mode — "Push Changes" is a no-op. |
Adds the GitHub spec-kit toolkit so this repo can host the canonical workflow our METHODOLOGY.md references. Installed via: uv tool run --from git+https://github.com/github/spec-kit.git \ specify init . --integration claude --force Skills land in .claude/skills/ (speckit-{constitution,specify,clarify, plan,tasks,implement,analyze,checklist,taskstoissues}, plus the speckit-git-* extension). Workflow templates and scripts go to .specify/.
Now that spec-kit is installed in this repo, rewrites the abstract "agent triggers" section into concrete speckit skill invocations (specify/clarify/plan/tasks/taskstoissues/implement). Adds a Toolchain section listing the skills the orchestrator drives. Introduces two named implementation paths: - Path A (recommended): polling from a long-lived Claude Code session via /loop 15m /backlog-poll, with .claude/in-flight/ lock files for human-in-the-loop safety. - Path B: GitHub App + repository_dispatch + Claude Code Action, for teams that want hands-off automation without a live session. Adoption checklist gains a spec-kit install step and a path choice; the testbed role of this repo is called out in the intro.
Drops Path B as a co-equal alternative. The methodology now prescribes the polling orchestration (long-lived Claude Code session running /loop 15m /backlog-poll) as the canonical path. A short note acknowledges that a webhook-driven variant is possible and references the same trigger contracts, but no longer ships detailed sketches. Knock-on simplifications: Maintaining Total folds into the poll (no standalone recomputer workflow), the adoption checklist's "pick a path" step collapses to "adopt the orchestrator", and the open-questions list is rewritten without the path comparison.
The canonical orchestrator described in METHODOLOGY.md. Designed to be driven by /loop, it reconciles the GitHub Project board against on-disk speckit artefacts and invokes the appropriate speckit skill when work is outstanding. Key properties: - One action per tick (predictable, bounded). - Lock files at .claude/in-flight/<issue>.md are committed on the feature branch so cloud-CC container restarts can resume. - Questions for the maintainer go to chat; lock files record them so a new session sees them on resume. - Recomputes Total = V + M + A each tick (subsumes the standalone recomputer workflow). - Walks items by Total descending, ties broken by oldest issue. - Configuration read from .claude/backlog-poll.config.json (project_owner, project_number, repo, default_branch).
Step-by-step runbook a maintainer (or adopter) follows locally to: 1. Create a public GitHub Project with the methodology's field schema (Status, Category, Complexity single-selects; V/M/A/Total numbers). 2. Configure the built-in workflows (item_added -> Triage, item_closed -> Done) — UI-only step. 3. Add the issue template and auto-add workflow. 4. Migrate existing BACKLOG.md rows: file the Epic parents first, then each item, then link sub-issues via the GraphQL addSubIssue mutation. 5. Reconcile spec directory names against new issue numbers. 6. Create .claude/backlog-poll.config.json. 7. Archive the old BACKLOG.md. 8. Start /loop 15m /backlog-poll. Includes a status mapping table (BACKLOG.md statuses -> new Project statuses), a rollback section, and a bulk-migration script sketch for adopters with >50 items.
15-slide self-contained HTML deck recapping the objectives, strategy, state machine, schema, trigger contracts, orchestration loop, lock-file safety, and current vs remaining work. Uses reveal.js + Mermaid from CDN — no build step, opens directly in a browser at docs/presentation/methodology-review.html.
Two Mermaid syntax bugs caused the "Strategy in one picture" diagram to silently fail to render: 1. Subgraph labels used quotes (subgraph foo["Bar"]) instead of the brackets-only form (subgraph foo [Bar]). Mermaid's parser rejects quoted subgraph titles in v11. 2. Dotted arrows missed required spaces around the label (BP -.reads state.-> PJ instead of BP -. reads state .-> PJ). Switched dotted arrows to solid arrows with |label| edge labels — simpler syntax and renders identically for the diagram's purpose.
The trigger contracts had plan and tasks listed as Epic-only steps. That was wrong — those phases run for every item moving to In Design. Only /speckit-taskstoissues is Epic-specific (it's the step that decomposes an Epic's tasks into child sub-issues). Fixed in three places: - METHODOLOGY.md: Overview paragraph, In Design state machine entry (now lists all four design phases explicitly with one-phase-per-tick pacing), Epic decomposition section, and trigger contracts table. - .claude/skills/backlog-poll/SKILL.md: decision table now has a row per artefact (no spec.md, no plan.md, no tasks.md, Epic with no sub-issues), and the Epic-decomposition section now describes taskstoissues as the single Epic-specific addition. - docs/presentation/methodology-review.html: slide 7 (Trigger contracts) table updated; slide 9 (One item's journey) clarifies the design phase and the Epic-only taskstoissues step in the footnote.
Points the orchestrator at the freshly created Project at https://github.com/orgs/DeepBlueCLtd/projects/4. This repo's testbed Project; other repos adopting the methodology create their own config equivalent.
Two design refinements to remove orchestrator re-trigger risk and
settle the branching model:
1. New Phase Project field (single-select; values: empty, Spec
drafting, Plan drafting, Tasks drafting, Decomposing, Designed,
Implementing). API state, not git state — the orchestrator can
tell a phase is in flight even when its output sits in an open PR
that hasn't merged yet. Maintained by /backlog-poll; never edited
by maintainers. Inconsistencies with Status get flagged in chat.
2. Branch strategy: one feature, two PRs per issue.
- Design branch <NNN>-<slug> carries spec.md, plan.md, tasks.md
(and the side effect of sub-issue creation for Epics) as
successive commits in one design PR.
- Implementation branch <NNN>-<slug>-impl carries the implement
work in a separate PR with Closes #N.
- Optional worktree via workspace_dir config field for local CC
sessions where the maintainer is also editing.
Updated:
- METHODOLOGY.md: schema table gains Phase row; new "Phase field"
subsection with lifecycle diagram; "In Design" and "Doing" state
machine entries rewritten to be Phase-driven; new top-level "Branch
strategy" section.
- .claude/skills/backlog-poll/SKILL.md: config schema gains
workspace_dir; decision table now keyed off (Status, Phase) instead
of artefact existence on main; new "Branches" sub-section in
speckit invocation; the sequence now writes Phase via GraphQL
alongside opening the PR.
- docs/migration/from-backlog-md.md: step 2b adds the Phase field;
step 7d's mapping table now includes initial Phase per legacy
status (so partially-progressed migrated items don't get specify
re-run on them).
- docs/presentation/methodology-review.html: schema slide shows
Phase as the orchestrator-maintained authoritative state; strategy
diagram labels reflect Phase + Total writes; "what's still ahead"
slide marks Project + config as done, adds "add Phase field to
Project #4" as a new pending step.
The orchestration-loop sequence diagram (slide 8) and other wide diagrams were rendering at their natural width and getting clipped on the right. Two changes fix it: - Mermaid init: add useMaxWidth: true for both flowchart and sequence diagrams, reduce sequence actorMargin from 40 to 30, enable text wrapping. useMaxWidth tells Mermaid to set viewBox-only sizing on the SVG so it scales down to fit. - CSS: !important on max-width/width/height for pre.mermaid svg to beat Mermaid's inline width/height attributes, and explicit width: 100% on the pre wrapper.
useMaxWidth alone wasn't enough — Mermaid v11 sets width/height as SVG attributes (not just inline styles), which CSS !important doesn't override on Safari/iPad. Post-process every rendered SVG to strip those attributes and rely on viewBox + preserveAspectRatio for scaling. Also shorten the actor names on slide 8 (Loop / Poll / Project / Phase / User) so the diagram has more horizontal slack to begin with.
The previous fix forced width: 100% which stretched naturally tall sequence diagrams to the full slide width, making them overflow vertically. Switch to max-width: 100% + max-height: 68vh with width/height: auto — SVGs scale down to fit within both dimensions, preserving aspect ratio, and don't stretch beyond their natural size.
Lets multiple Claude Code sessions cooperate on the same Project without colliding. Each session is a "worker" with an auto-generated identity; the Project's new Owner field is the claim mechanism. New skill /backlog-worker-start: - Reads repo from .claude/backlog-poll.config.json and derives a short tag (initials of hyphenated parts; e.g. backlog-navigator -> bn). - Generates a petname like bn-swift-mango-7234 (adj + noun + PID). - Writes it to /tmp/backlog-poll-worker-id (per-container, not committed, not in the project tree). - Invokes /loop 15m /backlog-poll to start polling. /backlog-poll updates: - Pre-flight reads /tmp/backlog-poll-worker-id; aborts with a friendly message if /backlog-worker-start hasn't been run. - Fetches Owner alongside Status/Phase/etc. - Ownership filter applied first: continue work on items owned by me, skip items owned by others, claim unowned candidates. - Claim is write-then-read-back; the read-back resolves races between simultaneous workers. - Release at human-review gates: clear Owner after advancing Phase to Designed (design PR awaiting review) or Implementing (impl PR awaiting review). Keep Owner while actively working or blocked on a chat question. Methodology + runbook: - Owner row added to the Project schema (text field). - New "Workers" section in METHODOLOGY.md covering joining the pool, claim/release, and stale-worker recovery (manual reset for now; heartbeats are a future refinement). - Runbook step 2b adds the gh project field-create for Owner. - Presentation slide 6 schema shows Owner; slide 12 marks Phase field done, adds Owner field as new pending step.
A bash script that handles the API-doable portion of adopting the backlog methodology in any repo: - gh project create + capture project number/ID/URL - Adds all custom fields: Owner (text), Phase / Category / Complexity (single-selects with options), V / M / A / Total (numbers). - GraphQL updateProjectV2 to flip visibility public. - Writes .claude/backlog-poll.config.json with the new Project details (auto-detects owner type org vs user). - Writes .github/ISSUE_TEMPLATE/backlog-item.yml and .github/workflows/add-to-project.yml. - Prints clear "remaining manual UI steps" at the end: Status field options (GraphQL coverage is patchy on existing fields' options), the two built-in Project workflows, and adding PROJECT_TOKEN. Refuses to run if .claude/backlog-poll.config.json already exists, so re-runs can't accidentally create duplicate Projects. Linked from METHODOLOGY.md adoption checklist and the migration runbook as the "fast path" alternative to the manual walkthrough.
One-off helper that adds the 12 migrated issues (#4-#15) to Project #4 and sets their Project field values per the migration mapping table. Looks up project + field + option IDs dynamically, so it doesn't need hard-coded IDs. Issues are already filed via the GitHub MCP tools from the session; this script just handles the Project field side, which the MCP doesn't expose. Run once locally with gh auth: scripts/migrate-testbed-items.sh
The script blew up with "field-id must be provided" when a field defined in the script wasn't present in the Project (only Status, Phase, Owner had been added; Category/Complexity/V/M/A/Total were not). Fix: - Pre-flight prints a warning listing any missing expected fields so the failure mode is obvious upfront. - set_select / set_number now also early-return when field_id is empty (in addition to the existing empty-value check), so a missing field downgrades from "crash" to "silently skipped" with the pre-flight warning explaining why.
The methodology is stable enough to invite real adopters. This commit
bundles everything an adopter needs into a clear, self-contained
adoption story:
- docs/adopt-methodology.md (476 lines) — the canonical walkthrough.
Five-phase plan with literal commands, expected outputs, and
per-phase verification. Troubleshooting section seeded from the
failure modes we hit setting up the testbed (jq missing,
field-create incomplete, gh auth scopes, "field-id must be
provided", auto-add not firing, worker-id churn, claim races).
Covers both greenfield repos and ones migrating from a BACKLOG.md.
- scripts/setup-project.sh enhanced from 6 to 7 steps:
- Adds step 7: fetches backlog-worker-start and backlog-poll
SKILL.md files from the methodology repo's main branch into the
adopter's .claude/skills/ via curl. Configurable via
SOURCE_REPO / SOURCE_BRANCH env vars; SKIP_SKILL_FETCH=1 opt-out.
- Summary points adopters at docs/adopt-methodology.md and the
new check-setup.sh diagnostic.
- curl moved into prereq check.
- scripts/check-setup.sh (new, 247 lines) — diagnostic any adopter
can run anytime to verify state. PASS/WARN/FAIL per check across
local tools, gh auth + scopes, repo files, config sanity, live
Project schema (every expected field), and runtime artefacts (lock
files, worker identity). Curl-runnable. Exits non-zero on FAIL so
it can drop into CI.
- README.md reframed: top of file makes clear the methodology is the
primary thing this repo hosts, with the navigator app as a sibling.
Adoption guide is the first link.
- METHODOLOGY.md adoption checklist now points at the walkthrough as
the recommended path; includes a one-line curl|bash shortcut.
The project's live backlog now lives on the GitHub Project (https://github.com/orgs/DeepBlueCLtd/projects/4). The 12-row dummy dataset that previously lived at BACKLOG.md is moved to docs/history/BACKLOG.md.archived with a clear "ARCHIVED" header explaining where work happens now. README updated to call out that the navigator app's default bundled-demo path now points at a missing file and needs a follow-up (either repoint its default fixture or use ?repo= to target an external repo's BACKLOG.md). Local pnpm dev / e2e tests that load the root BACKLOG.md will fail until that follow-up; the methodology side of the repo is unaffected.
Now that the methodology has taken over, the navigator app stops being a co-equal sibling. Marking it deprecated explicitly: - README.md: deprecation banner above the navigator-app section. - ADOPTING.md, CONFIGURATION.md, KIT-FOLLOWUPS.md: deprecation banners at top, redirecting readers to METHODOLOGY.md and the adoption walkthrough. Workflow triggers reduced to workflow_dispatch only across all five navigator workflows (ci, deploy, lighthouse, pr-preview, pr-preview-cleanup). Reason: the bundled BACKLOG.md fixture has moved, so any automatic run would fail; reducing to manual-only keeps the files around for future revival without polluting PR check-runs. Source code (src/, e2e/, public/, vite.config.ts, etc.) untouched — it still builds locally if someone wants to revive the navigator, but nothing fires automatically anymore.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces
METHODOLOGY.md, a comprehensive adoption guide for managing project backlogs using GitHub Issues and Projects as an alternative to the existing markdown-based approach inADOPTING.md.Key Changes
New methodology document that describes a complete workflow for backlog management using:
Detailed specifications including:
Implementation guidance with:
Notable Details
ADOPTING.mdapproach, addressing merge conflict and review overhead issues with version-controlled backlogshttps://claude.ai/code/session_01PynbLJMDyAhAbGCvtpNKgB