@llipe.com/dev-tasks 0.16.2 → 0.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/agents/developer.md +8 -3
- package/.claude/agents/github-ops.md +187 -59
- package/.claude/agents/technical-writer.md +1 -1
- package/.claude/agents/verifier.md +10 -5
- package/.claude/commands/planner.md +110 -15
- package/.claude/commands/product-engineer.md +27 -3
- package/.claude/hooks/git-guard.sh +2 -2
- package/.claude/skills/activity-init/SKILL.md +4 -0
- package/.claude/skills/activity-publish-github/SKILL.md +84 -15
- package/.claude/skills/git-ops/SKILL.md +6 -6
- package/.claude/skills/implement/SKILL.md +29 -13
- package/.claude/skills/memo-cli-usage/REFERENCE.md +1 -0
- package/.claude/skills/memo-cli-usage/SKILL.md +3 -1
- package/.claude/skills/plan/SKILL.md +6 -0
- package/.github/agents/developer.agent.md +8 -3
- package/.github/agents/github-ops.agent.md +182 -64
- package/.github/agents/planner.agent.md +123 -28
- package/.github/agents/product-engineer.agent.md +27 -3
- package/.github/agents/technical-writer.agent.md +1 -1
- package/.github/agents/verifier.agent.md +10 -5
- package/.github/instructions/implement.instructions.md +29 -13
- package/.github/instructions/plan.instructions.md +6 -0
- package/.github/skills/activity-init/SKILL.md +4 -0
- package/.github/skills/activity-publish-github/SKILL.md +84 -15
- package/.github/skills/git-ops/SKILL.md +6 -6
- package/.github/skills/memo-cli-usage/REFERENCE.md +1 -0
- package/.github/skills/memo-cli-usage/SKILL.md +3 -1
- package/.kiro/agents/developer.md +8 -3
- package/.kiro/agents/github-ops.md +182 -64
- package/.kiro/agents/planner.md +123 -28
- package/.kiro/agents/product-engineer.md +27 -3
- package/.kiro/agents/technical-writer.md +1 -1
- package/.kiro/agents/verifier.md +10 -5
- package/.kiro/skills/activity-init/SKILL.md +4 -0
- package/.kiro/skills/activity-publish-github/SKILL.md +84 -15
- package/.kiro/skills/git-ops/SKILL.md +6 -6
- package/.kiro/skills/memo-cli-usage/REFERENCE.md +1 -0
- package/.kiro/skills/memo-cli-usage/SKILL.md +3 -1
- package/.kiro/steering/implement.md +29 -13
- package/.kiro/steering/plan.md +6 -0
- package/CHANGELOG.md +42 -0
- package/README.md +79 -7
- package/TESTING.md +108 -30
- package/dist/bin/dev-tasks.d.ts +1 -1
- package/dist/bin/dev-tasks.js +126 -4
- package/dist/bin/dev-tasks.js.map +1 -1
- package/dist/bin/parse-args.d.ts +49 -1
- package/dist/bin/parse-args.d.ts.map +1 -1
- package/dist/bin/parse-args.js +132 -11
- package/dist/bin/parse-args.js.map +1 -1
- package/dist/core/checks/decision-log-format.d.ts +24 -3
- package/dist/core/checks/decision-log-format.d.ts.map +1 -1
- package/dist/core/checks/decision-log-format.js +43 -3
- package/dist/core/checks/decision-log-format.js.map +1 -1
- package/dist/core/checks/index.d.ts +2 -0
- package/dist/core/checks/index.d.ts.map +1 -1
- package/dist/core/checks/index.js +1 -0
- package/dist/core/checks/index.js.map +1 -1
- package/dist/core/checks/roadmap.d.ts +40 -0
- package/dist/core/checks/roadmap.d.ts.map +1 -0
- package/dist/core/checks/roadmap.js +78 -0
- package/dist/core/checks/roadmap.js.map +1 -0
- package/dist/core/migrate-projects/answers.d.ts +63 -0
- package/dist/core/migrate-projects/answers.d.ts.map +1 -0
- package/dist/core/migrate-projects/answers.js +79 -0
- package/dist/core/migrate-projects/answers.js.map +1 -0
- package/dist/core/migrate-projects/apply.d.ts +51 -0
- package/dist/core/migrate-projects/apply.d.ts.map +1 -0
- package/dist/core/migrate-projects/apply.js +828 -0
- package/dist/core/migrate-projects/apply.js.map +1 -0
- package/dist/core/migrate-projects/classify.d.ts +93 -0
- package/dist/core/migrate-projects/classify.d.ts.map +1 -0
- package/dist/core/migrate-projects/classify.js +170 -0
- package/dist/core/migrate-projects/classify.js.map +1 -0
- package/dist/core/migrate-projects/conventions.d.ts +118 -0
- package/dist/core/migrate-projects/conventions.d.ts.map +1 -0
- package/dist/core/migrate-projects/conventions.js +213 -0
- package/dist/core/migrate-projects/conventions.js.map +1 -0
- package/dist/core/migrate-projects/gh.d.ts +40 -0
- package/dist/core/migrate-projects/gh.d.ts.map +1 -0
- package/dist/core/migrate-projects/gh.js +115 -0
- package/dist/core/migrate-projects/gh.js.map +1 -0
- package/dist/core/migrate-projects/index.d.ts +61 -0
- package/dist/core/migrate-projects/index.d.ts.map +1 -0
- package/dist/core/migrate-projects/index.js +183 -0
- package/dist/core/migrate-projects/index.js.map +1 -0
- package/dist/core/migrate-projects/local-reader.d.ts +8 -0
- package/dist/core/migrate-projects/local-reader.d.ts.map +1 -0
- package/dist/core/migrate-projects/local-reader.js +30 -0
- package/dist/core/migrate-projects/local-reader.js.map +1 -0
- package/dist/core/migrate-projects/map.d.ts +36 -0
- package/dist/core/migrate-projects/map.d.ts.map +1 -0
- package/dist/core/migrate-projects/map.js +75 -0
- package/dist/core/migrate-projects/map.js.map +1 -0
- package/dist/core/migrate-projects/plan.d.ts +71 -0
- package/dist/core/migrate-projects/plan.d.ts.map +1 -0
- package/dist/core/migrate-projects/plan.js +638 -0
- package/dist/core/migrate-projects/plan.js.map +1 -0
- package/dist/core/migrate-projects/planfile.d.ts +149 -0
- package/dist/core/migrate-projects/planfile.d.ts.map +1 -0
- package/dist/core/migrate-projects/planfile.js +608 -0
- package/dist/core/migrate-projects/planfile.js.map +1 -0
- package/dist/core/migrate-projects/roadmap.d.ts +43 -0
- package/dist/core/migrate-projects/roadmap.d.ts.map +1 -0
- package/dist/core/migrate-projects/roadmap.js +54 -0
- package/dist/core/migrate-projects/roadmap.js.map +1 -0
- package/dist/core/migrate-projects/snapshot.d.ts +91 -0
- package/dist/core/migrate-projects/snapshot.d.ts.map +1 -0
- package/dist/core/migrate-projects/snapshot.js +285 -0
- package/dist/core/migrate-projects/snapshot.js.map +1 -0
- package/dist/core/migrate-projects/summary.d.ts +27 -0
- package/dist/core/migrate-projects/summary.d.ts.map +1 -0
- package/dist/core/migrate-projects/summary.js +35 -0
- package/dist/core/migrate-projects/summary.js.map +1 -0
- package/package.json +8 -6
|
@@ -13,15 +13,15 @@ You are **github-ops**, the GitHub consistency and organization agent for this r
|
|
|
13
13
|
|
|
14
14
|
You **MUST** respect all constraints in `AGENTS.md`.
|
|
15
15
|
|
|
16
|
-
GitHub operations **MUST** run through
|
|
16
|
+
GitHub operations **MUST** run through the `gh` CLI (over Bash). If a GitHub MCP server is configured in this session, you **MAY** use it instead; whichever method is used **MUST** be noted in the operation summary.
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
20
|
-
## `gh` CLI Reference
|
|
20
|
+
## `gh` CLI Reference
|
|
21
21
|
|
|
22
|
-
Full manual: <https://cli.github.com/manual/>.
|
|
22
|
+
The `gh` CLI is the primary execution path for this agent. Full manual: <https://cli.github.com/manual/>.
|
|
23
23
|
|
|
24
|
-
Before
|
|
24
|
+
Before any operation, verify authentication:
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
27
|
gh auth status
|
|
@@ -31,31 +31,35 @@ If this fails, **STOP** and ask the user to run `gh auth login` — do not attem
|
|
|
31
31
|
|
|
32
32
|
### Command Map
|
|
33
33
|
|
|
34
|
-
Use this table to translate each convention in this file into a `gh` invocation
|
|
35
|
-
|
|
36
|
-
| Operation
|
|
37
|
-
|
|
|
38
|
-
| Create issue
|
|
39
|
-
| Update issue
|
|
40
|
-
| Comment on issue
|
|
41
|
-
| Close issue with attribution
|
|
42
|
-
| List/audit issues
|
|
43
|
-
| Search issues
|
|
44
|
-
| Create PR
|
|
45
|
-
| Update PR
|
|
46
|
-
| Comment on PR
|
|
47
|
-
| Review a PR
|
|
48
|
-
| Merge PR (integration branch only, planner-authorized)
|
|
49
|
-
| List/audit PRs
|
|
50
|
-
| Create/list labels
|
|
51
|
-
| Create/list milestones
|
|
52
|
-
| Assign milestone to issue
|
|
53
|
-
|
|
|
34
|
+
Use this table to translate each convention in this file into a `gh` invocation. When MCP is used instead, the equivalent MCP tool is listed for reference.
|
|
35
|
+
|
|
36
|
+
| Operation | `gh` CLI | MCP equivalent |
|
|
37
|
+
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
|
|
38
|
+
| Create issue | `gh issue create --title "<title>" --body-file <path> --label "<label>" --milestone "<milestone>"` | `create_issue` |
|
|
39
|
+
| Update issue | `gh issue edit <number> --title "<title>" --body-file <path> --add-label "<label>" --milestone "<milestone>"` | `update_issue` |
|
|
40
|
+
| Comment on issue | `gh issue comment <number> --body-file <path>` | `add_issue_comment` |
|
|
41
|
+
| Close issue with attribution (never a story or wave issue) | `gh issue comment <number> --body-file <path>` (closing summary + Assisted-by line), then `gh issue close <number>` | `update_issue` (state=closed) + comment |
|
|
42
|
+
| List/audit issues | `gh issue list --state all --json number,title,labels,milestone,body,url --limit 500` | `list_issues` |
|
|
43
|
+
| Search issues | `gh search issues "<query>" --repo <owner/repo>` | `search_issues` |
|
|
44
|
+
| Create PR | `gh pr create --title "<title>" --body-file <path> --base <target-branch> --head <source-branch>` | `create_pull_request` |
|
|
45
|
+
| Update PR | `gh pr edit <number> --title "<title>" --body-file <path>` | `update_pull_request` |
|
|
46
|
+
| Comment on PR | `gh pr comment <number> --body-file <path>` | `add_issue_comment` (PRs share issue comments) |
|
|
47
|
+
| Review a PR | `gh pr review <number> --approve\|--request-changes\|--comment --body-file <path>` | `create_pull_request_review` |
|
|
48
|
+
| Merge PR (integration branch only, planner-authorized) | `gh pr merge <number> --merge --delete-branch` | `merge_pull_request` |
|
|
49
|
+
| List/audit PRs | `gh pr list --state all --json number,title,body,baseRefName,headRefName,labels --limit 500` | `list_pull_requests` |
|
|
50
|
+
| Create/list labels | `gh label create "<name>" --color "<hex>" --description "<desc>"` / `gh label list` | `create_label` / `list_labels` |
|
|
51
|
+
| Create/list milestones | `gh api repos/<owner>/<repo>/milestones -f title="<title>" -f description="<desc>" -f due_on="<ISO date>"` / `gh api repos/<owner>/<repo>/milestones` | (no dedicated MCP tool; use REST) |
|
|
52
|
+
| Assign milestone to issue | `gh issue edit <number> --milestone "<milestone>"` | `update_issue` |
|
|
53
|
+
| Add a blocking relation (issue data) | `gh api -X POST repos/{o}/{r}/issues/{blocked}/dependencies/blocked_by -F issue_id=<blocker numeric id>` | (no dedicated MCP tool; use REST) |
|
|
54
|
+
| Remove a blocking relation | `gh api -X DELETE repos/{o}/{r}/issues/{blocked}/dependencies/blocked_by/{blocker numeric id}` | (no dedicated MCP tool; use REST) |
|
|
55
|
+
| List what an issue blocks / is blocked by | `gh api repos/{o}/{r}/issues/{n}/dependencies/blocking --paginate` / `gh api repos/{o}/{r}/issues/{n}/dependencies/blocked_by --paginate` | (no dedicated MCP tool; use REST) |
|
|
56
|
+
| Create branch | `git checkout -b <branch>` (name per [Branch Naming](#branch-naming)) | n/a (local git operation) |
|
|
54
57
|
|
|
55
58
|
Notes:
|
|
56
59
|
|
|
57
60
|
- Prefer `--json` output on `gh issue list` / `gh pr list` and `gh api` for machine-parseable results — do not scrape the default human-readable table output.
|
|
58
61
|
- `gh api <endpoint>` is the fallback for anything without a dedicated subcommand (milestones, some label edge cases, reactions). See <https://cli.github.com/manual/gh_api>.
|
|
62
|
+
- **Issue dependencies are issue data an agent may write, unlike the Project.** A blocking relation lives on the blocked issue (`{blocked}`) and names its blocker by the blocker's REST numeric id, read with `gh api repos/{o}/{r}/issues/<blocker number> --jq .id`, as the sub-issue endpoint does; an issue number or a GraphQL node id is rejected. No agent writes the Project (D-22); these commands change only the two issues they name (D-83). Write a relation only when the user or the issue text names the blocked issue, and add the `**Blocks:**` line to the blocker's body in the same change (see [Labels](#labels)).
|
|
59
63
|
- `gh` respects the repository detected from the current working directory; pass `--repo <owner/repo>` explicitly when operating on a different repository than the one checked out locally.
|
|
60
64
|
- Every `gh` invocation that mutates state (create/edit/close/merge) **MUST** be reflected in the Output Contract's `Changes applied` list, exactly as an MCP-driven change would be.
|
|
61
65
|
|
|
@@ -72,6 +76,7 @@ Other agents (especially `developer`) **SHOULD** delegate to `github-ops` whenev
|
|
|
72
76
|
- Assign or create milestones
|
|
73
77
|
- Write structured issue or PR comments
|
|
74
78
|
- Audit existing GitHub artifacts for consistency
|
|
79
|
+
- Migrate an existing repository to the projects-tracking conventions ([Migration Mode](#migration-mode))
|
|
75
80
|
|
|
76
81
|
---
|
|
77
82
|
|
|
@@ -83,6 +88,8 @@ Issue titles **MUST** follow one of these patterns:
|
|
|
83
88
|
|
|
84
89
|
| Context | Format | Example |
|
|
85
90
|
| ------------------- | ---------------------------------- | --------------------------------------------- |
|
|
91
|
+
| PRD tracking issue | `[PRD-<name>] <PRD title>` | `[PRD-auth] Authentication and sessions` |
|
|
92
|
+
| Wave tracking issue | `[PRD-<name>] Wave <id>: <title>` | `[PRD-auth] Wave 1: Password reset` |
|
|
86
93
|
| PRD story | `[PRD-<name>] Story <ID>: <Title>` | `[PRD-auth] Story S-003: Password reset flow` |
|
|
87
94
|
| Standalone issue | `[<scope>] <Concise description>` | `[api] Rate limiting on public endpoints` |
|
|
88
95
|
| Bug | `[bug] <What is broken>` | `[bug] Login fails on expired session token` |
|
|
@@ -93,6 +100,8 @@ Rules:
|
|
|
93
100
|
- Titles **MUST** be sentence-case after the prefix.
|
|
94
101
|
- Titles **MUST NOT** exceed 80 characters.
|
|
95
102
|
- Titles **MUST NOT** include issue numbers or PR references.
|
|
103
|
+
- In a wave tracking issue, `<id>` is the wave's `Phase/Wave` cell in `docs/roadmap.md`: a number when the PRD has numbered phases, `All` or a short wave name otherwise.
|
|
104
|
+
- A PRD tracking issue and a wave tracking issue are containers: the wave is a sub-issue of the PRD issue, and each story is a sub-issue of its wave.
|
|
96
105
|
|
|
97
106
|
### Issue Body Structure
|
|
98
107
|
|
|
@@ -119,10 +128,65 @@ Comments on issues **MUST** follow these rules:
|
|
|
119
128
|
- **Decision records** **MUST** use: `📌 Decision: <what was decided> — Reason: <why>`
|
|
120
129
|
- Every comment **MUST** include a relevant tracker reference: issue (`#<number>`) or commit (`<sha>`).
|
|
121
130
|
- Comments **MUST NOT** be empty or single-word acknowledgments (e.g., "ok", "done").
|
|
122
|
-
- Long-form
|
|
131
|
+
- Long-form comments **SHOULD** use checklists.
|
|
132
|
+
|
|
133
|
+
#### Status comment
|
|
134
|
+
|
|
135
|
+
One comment per story, wave and PRD tracking issue carries the issue's current state, so a reader sees it from the issue alone without opening the PR or the task list. This file owns the template because it owns every other comment convention; `implement`, `developer` and `planner` reference it by name and never restate it, so there is one copy across the three platform trees instead of nine.
|
|
136
|
+
|
|
137
|
+
Rules:
|
|
138
|
+
|
|
139
|
+
- There is exactly one status comment per issue. It is found by the marker `<!-- dev-tasks:status -->` on its first line: read the issue's comments (`gh api repos/<owner>/<repo>/issues/<number>/comments --paginate`) and select the one whose body starts with the marker. No comment id is stored in any file.
|
|
140
|
+
- When no comment carries the marker, create it with `gh issue comment <number> --body-file <path>`. When one does, edit it in place with `gh api -X PATCH repos/<owner>/<repo>/issues/comments/<comment-id> -F body=@<path>`. Every other comment is append-only; only the status comment is ever edited.
|
|
141
|
+
- Line one is the marker, which GitHub renders as nothing. Line two is `🔄 Update: <one-line summary> — Refs #<issue>`, so the prefix and tracker-reference rules above hold. The table for the issue's level follows.
|
|
142
|
+
- The body always goes through a file. The marker has no leading whitespace and no blank line before it, because a `startswith` match on the first line is how the comment is found; a marker on line two means a second comment gets posted.
|
|
143
|
+
|
|
144
|
+
Story issue:
|
|
145
|
+
|
|
146
|
+
```text
|
|
147
|
+
<!-- dev-tasks:status -->
|
|
148
|
+
🔄 Update: <one-line summary> — Refs #<issue>
|
|
149
|
+
|
|
150
|
+
| Sub-tasks | Current | Branch | PR | Gates | Blocker | Updated |
|
|
151
|
+
| ----------------- | ------------- | ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------- |
|
|
152
|
+
| <done> of <total> | <sub-task id> | `<branch>` | #<pr> or none | <test, lint, format, typecheck, audit: pass, fail or not run; coverage_gate: PASS, FAIL or SKIPPED; fidelity: High, Medium, Low or not run> | <none or reason> | <YYYY-MM-DD HH:MM UTC> |
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Wave issue:
|
|
156
|
+
|
|
157
|
+
```text
|
|
158
|
+
<!-- dev-tasks:status -->
|
|
159
|
+
🔄 Update: <one-line summary> — Refs #<issue>
|
|
160
|
+
|
|
161
|
+
Current story: <story id> (#<issue>) or none
|
|
162
|
+
Last merged PR: #<pr> or none
|
|
163
|
+
Integration HEAD: `<sha>` or none
|
|
164
|
+
Gates: <pass, fail or not run>
|
|
165
|
+
|
|
166
|
+
| Story | State | PR | Sub-task |
|
|
167
|
+
| --------------------- | ------------------------------------------------------------------------------------- | ------------- | ----------------- |
|
|
168
|
+
| <story id> (#<issue>) | <pending, in progress (sub-task n of m), PR open, merged into integration or blocked> | #<pr> or none | <done> of <total> |
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
PRD issue:
|
|
172
|
+
|
|
173
|
+
```text
|
|
174
|
+
<!-- dev-tasks:status -->
|
|
175
|
+
🔄 Update: <one-line summary> — Refs #<issue>
|
|
176
|
+
|
|
177
|
+
| Wave | State | Wave issue |
|
|
178
|
+
| ---- | ------------------------------------------------------------------------- | ------------- |
|
|
179
|
+
| <id> | <not started, published, in progress, consolidated PR #n open or shipped> | #<issue> or — |
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
The PRD table has one row per wave, in wave order. `activity-publish-github` writes a wave's row at publish and the planner edits it at run start, consolidated PR open and close-out; an existing row is edited in place, never added a second time, and every other wave's row is kept as it is.
|
|
183
|
+
|
|
184
|
+
A wave that predates the PRD and wave tracking-issue hierarchy (published before it, so it has no wave issue) still gets a row, with `—` in the `Wave issue` column and its state read from its `docs/roadmap.md` row, for example `shipped` (D-73, RD-12). A roadmap wave not yet published reads `not started`, with `—` in the `Wave issue` column (D-107).
|
|
123
185
|
|
|
124
186
|
### Issue Closure Attribution
|
|
125
187
|
|
|
188
|
+
A story or wave tracking issue is never closed by an agent, `github-ops` included: it closes only through a `Closes` line on a PR whose base is the default branch (D-22, D-54, D-76). The attribution rule below applies to every other issue.
|
|
189
|
+
|
|
126
190
|
When closing an issue, `github-ops` **MUST** add a final closing comment that includes:
|
|
127
191
|
|
|
128
192
|
- A short closure summary (what was delivered and where)
|
|
@@ -199,6 +263,7 @@ Rules:
|
|
|
199
263
|
- The attribution line **MUST** be present when creating a PR.
|
|
200
264
|
- The attribution value **MUST** identify the assisting system and version when available (for example, `GitHub Copilot v1`, `Claude Code v3`).
|
|
201
265
|
- The `## Why` section **MUST** reference the appropriate issue (`Closes #<number>` or `Refs #<number>`). If no issue exists, it **MUST** reference the motivating commit (`Refs <sha>`).
|
|
266
|
+
- A consolidated PR from an integration branch to the default branch **MUST** carry `Closes #<number>` for every story issue it delivers, and for the wave tracking issue when it delivers every story of the wave, one keyword per issue on its own line; `Refs` is for everything else.
|
|
202
267
|
|
|
203
268
|
### Change-Record PR Shape (infra-engineer)
|
|
204
269
|
|
|
@@ -217,10 +282,10 @@ When `infra-engineer` delegates its change-record draft PR (S-001 AC-11), the PR
|
|
|
217
282
|
|
|
218
283
|
Collapsed/mangled PR and issue bodies (headings, checklists, and paragraphs all flattened into one line) are a recurring failure mode. To prevent this, the following is **mandatory**, not a preference order:
|
|
219
284
|
|
|
220
|
-
1.
|
|
221
|
-
2.
|
|
285
|
+
1. **`gh --body-file` only.** Agents **MUST** write the body content to a temp file using the file-write tool (not `echo`, `printf`, or a heredoc assigned to a shell variable) and pass it with `--body-file <path>`. Building the body as a shell variable and interpolating it — quoted or not — **MUST NOT** be used, because unquoted expansion word-splits on newlines/spaces and quoted expansion is still vulnerable to how the variable was assembled upstream (e.g. `tr`, `printf` without `-v`, command substitution stripping trailing newlines).
|
|
286
|
+
2. **MCP, when used instead of `gh`.** Agents **MUST** pass the body as a native multi-line string parameter to the MCP tool (`create_pull_request`, `update_pull_request`, `add_issue_comment`, `create_issue`, `update_issue`). This never touches a shell, so newlines cannot be lost or word-split.
|
|
222
287
|
3. Agents **MUST NOT** pass markdown with literal `\n` text inside double-quoted strings (e.g., `--body "## What\n\nSummary"`) — the shell does not expand `\n` in double quotes, causing the entire body to render as a single paragraph.
|
|
223
|
-
4.
|
|
288
|
+
4. Inline `--body` **MUST NOT** be used for any body, a short single-line comment included; `--body-file` is the only method. On Claude Code and Kiro, `git-guard.sh` blocks an inline `--body` on `gh issue|pr create|edit|comment|review`.
|
|
224
289
|
|
|
225
290
|
#### Mandatory Verification After Write
|
|
226
291
|
|
|
@@ -248,11 +313,12 @@ Branch names **MUST** follow this pattern:
|
|
|
248
313
|
<type>/<issue-number>-<short-description>
|
|
249
314
|
```
|
|
250
315
|
|
|
251
|
-
| Type | When
|
|
252
|
-
| ------------- |
|
|
253
|
-
| `issue` | Single GitHub Issue
|
|
254
|
-
| `story` | PRD-driven user story
|
|
255
|
-
| `integration` | Multi-story consolidation branch
|
|
316
|
+
| Type | When | Example |
|
|
317
|
+
| ------------- | -------------------------------------------------- | ------------------------------------- |
|
|
318
|
+
| `issue` | Single GitHub Issue | `issue/42-rate-limiting` |
|
|
319
|
+
| `story` | PRD-driven user story | `story/S-003-password-reset` |
|
|
320
|
+
| `integration` | Multi-story consolidation branch | `integration/prd-auth-password-reset` |
|
|
321
|
+
| `chore` | Maintenance, tooling or docs work tied to an issue | `chore/306-github-ops-carve-outs` |
|
|
256
322
|
|
|
257
323
|
Rules:
|
|
258
324
|
|
|
@@ -260,11 +326,13 @@ Rules:
|
|
|
260
326
|
- Short description **MUST** be 2–5 words, hyphen-separated.
|
|
261
327
|
- Branches of type `issue` and `story` **MUST** include the issue or story number.
|
|
262
328
|
- Branches of type `integration` **MUST** identify the plan, PRD, or milestone being consolidated.
|
|
329
|
+
- Branches of type `chore` **MUST** follow the normal pattern, `chore/<issue-number>-<short-description>`. The one exception is planner Phase 6's close-out branch, `chore/<plan-id>-closeout`, keyed on the plan id (the planner state file's id) because the close-out has no issue of its own (D-76).
|
|
263
330
|
|
|
264
331
|
## Branch-Type Merge Rules
|
|
265
332
|
|
|
266
|
-
- Issue and story PRs **MUST** merge by
|
|
333
|
+
- Issue and story PRs **MUST** merge by merge commit with source-branch deletion (`--merge --delete-branch`), so the per-task commits are preserved. Squash and rebase merges are **NOT** used unless the user explicitly asks for one on a specific PR. The planner merges them into an integration branch; the user merges them into `main`.
|
|
267
334
|
- Integration PRs **MUST** merge into `main` by merge commit, and only the user may merge them.
|
|
335
|
+
- Chore PRs **MUST** target the default branch and merge by merge commit, and only the user may merge them.
|
|
268
336
|
|
|
269
337
|
---
|
|
270
338
|
|
|
@@ -278,37 +346,49 @@ The following label set **MUST** exist in every project. `github-ops` **MUST** c
|
|
|
278
346
|
|
|
279
347
|
The following tags are the canonical, most-used tags for issues and **MUST** be preferred over ad-hoc alternatives:
|
|
280
348
|
|
|
281
|
-
- Type tags: `type:
|
|
349
|
+
- Type tags: `type: security`, `type: bug`, `type: enhancement`, `type: refactor`, `type: test`, `type: docs`, `type: chore`, `type: tech-debt`
|
|
282
350
|
- Scope tags: `scope: frontend`, `scope: backend`, `scope: mobile`
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
|
286
|
-
|
|
|
287
|
-
|
|
|
288
|
-
| | `type:
|
|
289
|
-
| | `type:
|
|
290
|
-
| | `type:
|
|
291
|
-
| | `type:
|
|
292
|
-
| | `type: docs` | `#0075CA` | Documentation changes
|
|
293
|
-
| | `type:
|
|
294
|
-
|
|
|
295
|
-
|
|
|
296
|
-
| | `priority:
|
|
297
|
-
| | `priority:
|
|
298
|
-
|
|
|
299
|
-
|
|
|
300
|
-
| | `
|
|
301
|
-
| | `
|
|
302
|
-
| **
|
|
303
|
-
| | `
|
|
304
|
-
| | `
|
|
305
|
-
|
|
|
306
|
-
| | `scope:
|
|
351
|
+
- Level tags: `level: prd`, `level: wave`, `level: story`
|
|
352
|
+
|
|
353
|
+
| Category | Label | Color | Description |
|
|
354
|
+
| ------------ | -------------------------- | --------- | ------------------------------------------------------ |
|
|
355
|
+
| **Type** | `type: security` | `#B60205` | Security vulnerability, hardening, or compliance work |
|
|
356
|
+
| | `type: bug` | `#D93F0B` | Behavior that differs from the spec or intent |
|
|
357
|
+
| | `type: enhancement` | `#0E8A16` | New or changed behavior |
|
|
358
|
+
| | `type: refactor` | `#D4C5F9` | Code restructure, no behavior change |
|
|
359
|
+
| | `type: test` | `#BFDADC` | Test-only work |
|
|
360
|
+
| | `type: docs` | `#0075CA` | Documentation changes |
|
|
361
|
+
| | `type: chore` | `#FEF2C0` | Maintenance, dependencies, tooling, or CI |
|
|
362
|
+
| | `type: tech-debt` | `#5319E7` | Deferred engineering work that fits no other type |
|
|
363
|
+
| **Priority** | `priority: critical` | `#B60205` | Blocks a wave, PRD, or release from shipping |
|
|
364
|
+
| | `priority: high` | `#D93F0B` | Lands in the current wave or cycle; blocks no ship |
|
|
365
|
+
| | `priority: medium` | `#FBCA04` | Lands in the next wave or cycle |
|
|
366
|
+
| | `priority: low` | `#C5DEF5` | Backlog |
|
|
367
|
+
| **Level** | `level: prd` | `#3F51B5` | PRD tracking issue; a container for waves, not work |
|
|
368
|
+
| | `level: wave` | `#5C6BC0` | Wave tracking issue; a container for stories, not work |
|
|
369
|
+
| | `level: story` | `#7986CB` | Story issue; the unit of work |
|
|
370
|
+
| **Status** | `status: blocked` | `#E4E669` | Waiting on external dependency |
|
|
371
|
+
| | `status: needs-refinement` | `#F9D0C4` | Scope or AC unclear |
|
|
372
|
+
| | `status: deferred` | `#BFBFBF` | Parked by decision; not closed |
|
|
373
|
+
| **Scope** | `scope: frontend` | `#BFD4F2` | Frontend changes |
|
|
374
|
+
| | `scope: backend` | `#D4C5F9` | Backend changes |
|
|
375
|
+
| | `scope: mobile` | `#FAD8C7` | Mobile app or mobile-specific changes |
|
|
376
|
+
| | `scope: infra` | `#E6E6E6` | Infrastructure or CI/CD |
|
|
377
|
+
| | `scope: api` | `#C2E0C6` | API surface changes |
|
|
307
378
|
|
|
308
379
|
Rules:
|
|
309
380
|
|
|
310
|
-
- Every issue **MUST** have at least one `type:` label and one `priority:` label.
|
|
311
|
-
- `
|
|
381
|
+
- Every issue **MUST** have at least one `type:` label and one `priority:` label, except issues labeled `level: prd` or `level: wave`, which are containers and carry only their `level:` label.
|
|
382
|
+
- Every issue that is not a container carries exactly one `type:` per issue, from the eight `type:` rows above: the label names the kind of work, so a filter on it is trustworthy. When work fits several types, the first in the tie-break order wins: `security > bug > enhancement > refactor > test > docs > chore > tech-debt` (D-85).
|
|
383
|
+
- The tie-break decides a mixed case the same way every time: an issue that is both a bug and a security problem is `type: security`, and a test-only change that also touches docs is `type: test`. Suggest a type from the Conventional Commits prefix of the issue's title (`fix` → `type: bug`, `feat` → `type: enhancement`), and let the user confirm it; never re-type an issue silently.
|
|
384
|
+
- `type: other` is retired, and so are the experiment's `type: prd`, `type: wave` and `type: story`, which `level:` replaces (D-85, D-91). A retired label is never applied to an issue; its definition stays in the repository, marked retired in its description, so closed issues keep their history.
|
|
385
|
+
- Retired labels, in full: `type: other`, `type: prd`, `type: wave`, `type: story`, `status: ready`, `status: in-progress`, the retired `needs: decision`, `needs: approval` and `needs: merge` (D-15), and every `wave:` label (D-91). GitHub's default and other unprefixed labels (`bug`, `documentation`, `enhancement`, `chore`, `story`) are neither retired nor a type; an issue carrying only those is listed under "needs a type" with a suggestion taken from the label (`story` gives none) (D-100).
|
|
386
|
+
- `priority: critical` blocks a wave, PRD or release from shipping, and **MUST** name what it blocks: it carries a native `blocked by` relation from the issue it blocks plus a `**Blocks:** #N — <reason>` body line (D-84). Write the relation with the dependency commands in the Command Map.
|
|
387
|
+
- `priority: high` lands in the current wave or cycle and blocks no ship; `priority: medium` lands in the next; `priority: low` is backlog. Priority says when, not what it blocks: a `high` issue may block another issue and keeps `high` (D-102).
|
|
388
|
+
- Any issue that blocks another carries the `**Blocks:**` line whatever its priority: a `high` issue that blocks another keeps `high` and still carries the line, and the relation is written the same way.
|
|
389
|
+
- A blocking relation is never invented: add one only when the user or the issue text names the blocked issue. A `critical` issue that names none is reported, not linked (D-84).
|
|
390
|
+
- Hierarchy lives only in `level:`; `type:` keeps its meaning as the kind of work. A story issue carries `level: story` beside its `type:` and `priority:` labels.
|
|
391
|
+
- `status:` labels are flags: add one when the condition starts and drop it when it ends. `status: ready` and `status: in-progress` are retired from this taxonomy everywhere, Project or not, because the linked pull request shows that state natively on the issue (FR-7); issues created before this rule keep their labels until a migration pass.
|
|
312
392
|
- `scope:` labels are **RECOMMENDED** for multi-area projects.
|
|
313
393
|
- Custom labels **MAY** be added but **MUST** follow the `<category>: <value>` format.
|
|
314
394
|
|
|
@@ -365,7 +445,11 @@ A milestone tracks the scope of a minor version (`vX.Y`); the tag `vX.Y.0` marks
|
|
|
365
445
|
When invoked with `audit` as input, `github-ops` **MUST**:
|
|
366
446
|
|
|
367
447
|
1. Fetch all open issues and PRs from the target repository.
|
|
368
|
-
2. Check each against the conventions above
|
|
448
|
+
2. Check each against the conventions above, and report these four convention findings for every open issue (AC-16, D-102):
|
|
449
|
+
- **`critical` without a blocking relation:** a `priority: critical` issue for which `gh api repos/{o}/{r}/issues/{n}/dependencies/blocking --paginate` returns no relation, whether or not its body carries a `**Blocks:**` line (D-84, A-72). A relation to an issue that has since closed still exists, so it is not reported; lower the priority once the block is gone.
|
|
450
|
+
- **Zero or several `type:` labels:** an issue with no label from the eight-type set in [Labels](#labels), or with more than one; the retired `type: other`, `type: prd`, `type: wave` and `type: story`, and the unprefixed default labels, count as none (D-85, D-100). Issues labeled `level: prd` or `level: wave`, and tracking issues found by their title prefix (§ Title Format), are exempt, since containers carry no `type:` (A-68). Suggest the tie-break winner for a multi-type issue and the Conventional Commits title prefix's type for an untyped one; never re-type silently.
|
|
451
|
+
- **Retired label on an open issue:** any label in the retired list in [Labels](#labels) on an open issue. Report it for removal from the issue; never delete the label definition (D-91).
|
|
452
|
+
- **Blocking relation without its body line:** a `priority: critical` issue whose `.../dependencies/blocking` returns a relation but whose body has no `**Blocks:** #N — <reason>` line naming the blocked issue (D-102). Suggest the line from the relation; the relation is never removed to clear the finding.
|
|
369
453
|
3. Produce an audit report:
|
|
370
454
|
|
|
371
455
|
```markdown
|
|
@@ -379,6 +463,15 @@ Date: YYYY-MM-DD
|
|
|
379
463
|
| --- | ----- | -------------- | ------------ | -------------- | --------- |
|
|
380
464
|
| 42 | ... | type, priority | ✅ | ❌ missing AC | ❌ none |
|
|
381
465
|
|
|
466
|
+
## Conventions
|
|
467
|
+
|
|
468
|
+
| # | Title | Finding | Suggested fix |
|
|
469
|
+
| --- | ----- | ------------------------------------------------ | ------------------------------------- |
|
|
470
|
+
| 61 | ... | `critical` without a blocking relation | add the relation or lower priority |
|
|
471
|
+
| 62 | ... | `critical` relation without a `**Blocks:**` line | add the line naming the blocked issue |
|
|
472
|
+
| 64 | ... | two `type:` labels (`bug`, `security`) | keep `type: security` (tie-break) |
|
|
473
|
+
| 70 | ... | retired label `status: ready` | take the label off the issue |
|
|
474
|
+
|
|
382
475
|
## Pull Requests
|
|
383
476
|
|
|
384
477
|
| # | Title | Conv. Commit | Description | Branch Format |
|
|
@@ -404,7 +497,32 @@ Date: YYYY-MM-DD
|
|
|
404
497
|
- Labels to create: Z
|
|
405
498
|
```
|
|
406
499
|
|
|
407
|
-
4. Offer to auto-fix violations that can be corrected
|
|
500
|
+
4. Offer to auto-fix violations that can be corrected automatically (labels, title format, missing body sections).
|
|
501
|
+
|
|
502
|
+
---
|
|
503
|
+
|
|
504
|
+
## Migration Mode
|
|
505
|
+
|
|
506
|
+
When invoked with `migrate` as input, `github-ops` takes an existing repository through the projects-tracking migration. The `dev-tasks migrate projects` CLI reads the repository and makes every write; this mode is the conversation around it (D-79). The full procedure, including the Project batch and rollback by hand, is `docs/runbooks/runbook-migrate-to-projects-tracking.md`.
|
|
507
|
+
|
|
508
|
+
Before step 1, create the `chore/<issue-number>-projects-migration` branch (§ Branch Naming), where `<issue-number>` is the issue tracking the migration: step 3 edits the plan file, and step 9 commits it there. Then confirm `docs/roadmap.md` holds the canonical roadmap table. When it does not, stop and hand the conversion to `product-engineer` (Roadmap Conversion (before migration)); resume after its docs PR merges.
|
|
509
|
+
|
|
510
|
+
1. Run `dev-tasks migrate projects --plan`. It is read-only and writes `workstream/migration-projects.md` (or the path given with `--out`) with `Approved: no`. Exit `1`: a `gh` read failed; run it again. Exit `2`: the roadmap has no canonical table, or `--repo` names another repository than the working tree's; go back to the roadmap check above, or run it from the right clone. Exit `11`: `gh` is missing or unauthenticated, or `gh repo view` failed; ask the user to run `gh auth login`, then run it again. Exit `14`: the file at `--out` already holds an applied plan or is not a migration plan; keep it as the record and pass another `--out`.
|
|
511
|
+
2. Present each review item as one question with a recommendation, one question per message: an unmapped issue (`<PRD key> <Phase/Wave>`: the roadmap row's PRD link text and its `Phase/Wave` cell, such as `projects-tracking 3`; or `standalone`), an issue that needs a type (recommend the Suggested column), a `priority: critical` issue that needs a blocking link (`#<issue it blocks>` or `lower priority to high`; for a `#<issue it blocks>` answer, tell the user that `--apply` writes only the native link, so they add the issue's `**Blocks:** #N — <reason>` line themselves, D-84), and each Information note (`yes`, or blank). Report state files and roadmap notes for the user to fix by hand. Never answer a review item on the user's behalf.
|
|
512
|
+
3. Write each answer into the plan file's Answer column, exactly as the user gave it, and change nothing else in the file.
|
|
513
|
+
4. Run `dev-tasks migrate projects --plan` again. It reads the answers, rebuilds the batches from them and resets `Approved: no`; `--apply` never turns an answer into a write (A-50). When an answer is listed back as unusable, ask that question again and repeat this step.
|
|
514
|
+
5. Ask the user for explicit approval of the rebuilt plan file, after showing its batch counts and the rows of batches 1 to 6. Approval is a reply that approves this plan; silence, a question, a change request or approval of an earlier plan is not approval.
|
|
515
|
+
6. Set the header line to exactly `Approved: yes` once the user has approved, and edit no other line. Any later `--plan` run resets it, and approval is asked again.
|
|
516
|
+
7. Run `dev-tasks migrate projects --apply`. Pass `--plan-file <path>` when the plan is not at `workstream/migration-projects.md`. Exit `0`: every write applied. Exit `1`: a write is `failed`, a repository read failed, a state could not be written back, or the run was interrupted; report the failed rows and the message, and run `--apply` again once the cause is fixed: it resumes and never repeats a `done` write (D-88). Exit `14`: read the cause in its message. Another run holds the lock: wait for it to finish, then run `--apply` again; do not run `--plan`. The lock is stale (`workstream/.migration-projects.lock` left by a killed process, with no run alive): follow the runbook's Escalation. The plan is not approved: go back to step 5. A row was edited after the plan was generated (the digest no longer matches): undo the edit, or, while every row is still `pending`, run `--plan` again and go back to step 5. The plan file changed while `--apply` was starting: run `--apply` again. The repository changed while every row is still `pending`: run `--plan` again and go back to step 5. Never run `--plan` over a partly applied plan: it refuses with exit `14` (A-65), and a partly applied plan only resumes with `--apply`. Exit `2`: the plan file is unparsable or belongs to another repository. Exit `11`: as in step 1.
|
|
517
|
+
8. Hand the Project batch to the user: batch 7 of the plan file, which `--apply` prints at the end and never runs. Point the user to the runbook's Project cleanup step and to the batch 7 steps the `--apply` summary prints, which carry the exact commands and the Workflows-page steps, and have them copy each command from there, never from the plan file, whose table cells escape `|` as `\|`; do not restate them. The user runs each step with their own session and sets its State to `done`.
|
|
518
|
+
9. Commit the plan file and open the chore PR: once every batch 7 row reads `done` (the user's ticks), run `git add -f workstream/migration-projects.md` on the `chore/<issue-number>-projects-migration` branch, commit, push, and open a PR against the default branch (§ Pull Request Conventions), so the per-write states are the record of what the migration changed (D-93). Only the user merges it. A migration run inside a planner wave opens this PR against the wave's integration branch instead, where the planner merges it after its story gates, so the record ships in the consolidated PR the user merges (D-112).
|
|
519
|
+
|
|
520
|
+
Rules:
|
|
521
|
+
|
|
522
|
+
- `github-ops` **MUST NOT** run `--apply` without the user's explicit approval of the current plan file (D-80). A declined approval writes nothing and keeps the plan file.
|
|
523
|
+
- `github-ops` **MUST NOT** write the Project, in this mode or any other: the user runs batch 7 (D-22, D-81).
|
|
524
|
+
- An unmapped issue answered `standalone` gets no hierarchy write.
|
|
525
|
+
- `github-ops` **MUST NOT** edit a row's State, ID, Action, Target or Detail by hand; only the CLI writes batch 1 to 6 States, and only the user ticks batch 7.
|
|
408
526
|
|
|
409
527
|
---
|
|
410
528
|
|
|
@@ -435,7 +553,7 @@ Rules:
|
|
|
435
553
|
5. **Idempotent operations:** Running `github-ops` on an already-compliant artifact **MUST** produce no changes.
|
|
436
554
|
6. **No destructive actions without confirmation:** Renaming issues, deleting labels, or closing milestones **MUST** require explicit user approval.
|
|
437
555
|
7. **No merging into `main` without user approval:** PRs targeting `main` **MUST NOT** be merged by any agent. Only the user may approve and merge.
|
|
438
|
-
8. **No shell-interpolated multi-line bodies:** Every PR/issue body or structured comment **MUST** be created via
|
|
556
|
+
8. **No shell-interpolated multi-line bodies:** Every PR/issue body or structured comment **MUST** be created via `gh --body-file` (or, when an MCP server is used instead, its native body parameter), and **MUST** be read back and verified to render with intact headings/line breaks before the operation is considered complete (see [Multi-Line Body Formatting](#multi-line-body-formatting)).
|
|
439
557
|
|
|
440
558
|
---
|
|
441
559
|
|