Skip to content

docs(delivery): GitHub Issues as spec and queue — kind:state labels, issue forms, spec templates - #136

Merged
V3RON merged 1 commit into
mainfrom
delivery/model
Sep 10, 2026
Merged

V3RON merged 1 commit into
mainfrom
delivery/model

Conversation

@V3RON

@V3RON V3RON commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Summary

Makes GitHub Issues the spec and the queue for agentic delivery. First of three stacked PRs; this one is usable entirely by hand.

  • docs/internal/agent-rules/delivery.md — the binding rule. Every issue carries exactly one <kind>:<state> label; agents act only on bug:triage, bug:ready, feature:ready, task:ready; the assignee is the claim; the body is the spec and comments are discussion; every spec session reconciles comments posted since the body's lastEditedAt; reporters' issues are never rewritten; feature specs describe outcomes, tasks carry business scope plus technical spec; triage produces a report, not a fix; done is defined per kind; ADR status follows the feature.
  • Issue forms — a bug report (bug:new) and a feature request (request:new). Both reporter-facing and short. Blank issues stay enabled because feature and task specs are authored from templates, not forms.
  • docs/internal/templates/feature.md, docs/internal/templates/task.md — the bodies a spec session writes. The task template carries the approval checkbox the automation in the third PR reads.
  • .github/labels.json + labels.yml — the ten state labels declared in the repo and synced with gh label create --force on push to main. Create and update only; deletions are manual.
  • docs/internal/DELIVERY.md — the maintainer's manual: the model in five sentences, the three walkthroughs (bug, single-PR feature, split feature), handoffs, what is automated, where ADRs fit.
  • Rule 11, branches — work on issue <n> happens on <kind>/<n>, nothing appended; bug/<n>-repro for reproductions. Issue names branch, branch names issue.
  • Rule 2, handoffs — an agent that stops before merge leaves one ## Handoff comment (Done, Not done, Findings, Blocked on) and unassigns. State, never spec; no progress logs.
  • AGENTS.md, docs/internal/adr/README.md — link the rule; tie ADR status to feature state.

After merge (manual, once)

Relabel the open issues and retire the default labels. Proposed mapping, please correct before running:

Issue Now Becomes
#70 enhancement feature:planned
#72 #74 #75 #76 #77 #78 enhancement task:draft
#88 enhancement feature:spec
#79 bug bug:new
#52 none bug:new

Then delete enhancement, bug, duplicate, invalid, question, wontfix, good first issue, help wanted. documentation, dependencies, github_actions stay because Dependabot uses them.

Stack

  1. this PR — model, forms, templates, labels
  2. skills: spec-session, triage-bug, deliver
  3. issue-state.yml automation

@V3RON
V3RON added this pull request to stack #139 September 9, 2026 23:31
@V3RON
V3RON marked this pull request as ready for review September 10, 2026 01:36
…issue forms, spec templates, DELIVERY.md, handoffs
@V3RON
V3RON merged commit 25293b8 into main Sep 10, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant