@codedrifters/configulator 0.0.188 → 0.0.190

package/lib/index.js

@@ -745,6 +745,129 @@ var baseBundle = {
       ].join("\n"),
       tags: ["workflow"]
     },
+    {
+      name: "issue-label-conventions",
+      description: "Priority and status label taxonomy, defaults, inference rules, and blocking rules for agent-created or updated issues",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# Issue Label Conventions",
+        "",
+        "Every issue created or updated by an agent in **{{repository.owner}}/{{repository.name}}**",
+        "must carry exactly one `priority:*` label and exactly one `status:*` label.",
+        "These conventions apply to **all** agent bundles \u2014 do not redefine them",
+        "locally. The orchestrator and issue worker depend on this taxonomy.",
+        "",
+        "## Priority Labels",
+        "",
+        "Pick exactly one of the following:",
+        "",
+        "| Label | Criteria |",
+        "|-------|----------|",
+        "| `priority:critical` | Production is broken, blocked, or data at risk. Must start immediately. Use for outages, security incidents, regressions that block a release. |",
+        "| `priority:high` | Important work that should be next in the queue. Blocks other planned work, an epic's children, or a near-term deliverable. |",
+        "| `priority:medium` | Default for normal planned work. No immediate blocker but belongs in the current roadmap. |",
+        "| `priority:low` | Nice-to-have. Can be deferred without impact. Cleanups, minor polish, non-urgent refactors. |",
+        "| `priority:trivial` | Cosmetic or optional. Typos, formatting, stray comments. Safe to never pick up. |",
+        "",
+        "### Default Priority",
+        "",
+        "When the user has not indicated a priority and context provides no signal,",
+        "assign `priority:medium`.",
+        "",
+        "### Inference Heuristics",
+        "",
+        "Before defaulting to medium, scan the user's request and the issue context",
+        "for these signals:",
+        "",
+        "- **Urgency language** \u2014 words like *urgent*, *ASAP*, *immediately*, *now*,",
+        "  *blocker*, *on fire* \u2192 `priority:critical`",
+        "- **Importance language** \u2014 words like *important*, *soon*, *need this*,",
+        "  *next up*, *before launch* \u2192 `priority:high`",
+        "- **Deadlines** \u2014 an explicit due date within 7 days \u2192 `priority:high`;",
+        "  within 24 hours or labeled as a release blocker \u2192 `priority:critical`",
+        "- **Blocker status** \u2014 the issue blocks another open issue, an epic child,",
+        "  or a release \u2192 `priority:high` (or `priority:critical` if the blocked",
+        "  work is itself critical)",
+        "- **Business impact** \u2014 revenue loss, customer-facing outage, security",
+        "  exposure \u2192 `priority:critical`",
+        "- **Polish language** \u2014 *nice to have*, *minor*, *cleanup*, *whenever*,",
+        "  *low priority* \u2192 `priority:low`",
+        "- **Cosmetic scope** \u2014 typo fixes, comment tweaks, formatting-only \u2192 `priority:trivial`",
+        "- **Meeting-note origin** \u2014 any issue created from reviewing meeting notes or",
+        "  a meeting transcript \u2192 `priority:high` (meeting follow-ups are time-sensitive",
+        "  and presumed important unless the note explicitly says otherwise)",
+        "",
+        "### Ask vs. Infer",
+        "",
+        "- **Infer** when the user's request contains at least one clear signal from",
+        "  the heuristics above, or when the default (`priority:medium`) is clearly",
+        "  appropriate (routine feature, refactor, or chore with no urgency cues).",
+        "- **Ask** before creating the issue when:",
+        '  - The request mixes signals (e.g., "minor but blocks the release")',
+        "  - The work would reasonably map to `priority:critical` \u2014 always confirm",
+        "    before using the top tier",
+        "  - The scope is ambiguous enough that medium vs. high is unclear **and**",
+        "    the outcome would change how the orchestrator sequences work",
+        "- When asking, pose a single question with the candidate levels, e.g.",
+        '  "Is this `priority:high` (next in queue) or `priority:medium` (normal)?"',
+        "",
+        "## Status Labels",
+        "",
+        "Pick exactly one of the following. Status reflects where the issue sits in",
+        "the workflow, not the nature of the work.",
+        "",
+        "| Label | Criteria |",
+        "|-------|----------|",
+        "| `status:ready` | The issue is fully specified, has no open blockers, and is available for a worker to pick up. |",
+        "| `status:blocked` | The issue cannot be started yet \u2014 either it declares `Depends on: #N` on an open issue, or it is an epic with one or more open children. |",
+        "| `status:in-progress` | A worker has claimed the issue and a branch exists. Set when the worker starts; cleared only on completion or failure. |",
+        "| `status:needs-attention` | Automated triage has flagged the issue for human review (stale, failed worker, or ambiguous state). Humans reset this label manually. |",
+        "| `status:done` | The change has shipped. Usually set when the PR merges and the issue closes. |",
+        "",
+        "### Blocking Rules",
+        "",
+        "Two rules force `status:blocked` \u2014 both are non-negotiable:",
+        "",
+        "1. **Epic-blocking rule.** Any issue of GitHub type *Epic* that has one or",
+        "   more open child issues must carry `status:blocked`. Only flip it to",
+        "   `status:ready` (or close it) once every child is resolved.",
+        "2. **Dependency-blocking rule.** Any issue whose body contains a",
+        "   `Depends on: #N` line referencing an open issue must carry",
+        "   `status:blocked` for as long as that dependency remains open.",
+        "   When all referenced dependencies close, transition to `status:ready`.",
+        "",
+        "### Status Transitions",
+        "",
+        "Agents transition status labels at these well-defined points:",
+        "",
+        "- **Issue creation** \u2192 `status:ready` by default, or `status:blocked` if",
+        "  either blocking rule applies.",
+        "- **Worker claims the issue** \u2192 remove `status:ready`, add",
+        "  `status:in-progress`. A branch must exist before this transition.",
+        "- **Worker opens a PR** \u2192 leave `status:in-progress` in place until the",
+        "  PR merges. Do not pre-flip to `status:done`.",
+        "- **PR merges / issue closes** \u2192 remove `status:in-progress`, add",
+        "  `status:done`.",
+        "- **Dependency resolves** \u2192 if the issue was `status:blocked` solely because",
+        "  of the dependency-blocking rule, remove `status:blocked` and add",
+        "  `status:ready`.",
+        "- **Automated flag** \u2192 add `status:needs-attention` (do not remove existing",
+        "  status). Never auto-reset a `status:needs-attention` issue back to ready;",
+        "  a human must decide.",
+        "- **PR CI failure** \u2192 add `status:needs-attention` to the associated PR (and",
+        "  its linked issue) when CI fails in a **permanent** state \u2014 i.e. the failure",
+        "  persists after a rerun, or the failure is clearly not a flake (compile",
+        "  errors, failing assertions, type errors, broken builds). Do **not** flag",
+        "  when CI self-mutates the PR and the follow-up run passes \u2014 for example,",
+        "  lint auto-fixes, formatter commits, or snapshot/lockfile updates pushed",
+        "  by CI. Those are expected self-healing behaviors, not failures.",
+        "",
+        "An issue must always carry exactly one of `status:ready`, `status:blocked`,",
+        "`status:in-progress`, or `status:done`. The `status:needs-attention` label",
+        "is additive \u2014 it coexists with whichever of those four applies."
+      ].join("\n"),
+      tags: ["workflow"]
+    },
     {
       name: "issue-conventions",
       description: "Issue title prefixes, GitHub issue type mapping, prerequisite issues",
@@ -876,8 +999,20 @@ var githubWorkflowBundle = {
         "6. **Create the issue** using `gh issue create`:",
         "   - `--title '<type>: <description>'`",
         "   - `--body '<issue body>'`",
-        "   - `--type '<GitHub issue type>'` (Epic, Feature, Bug, or Task)",
         "   - `--label '<type-label>' --label '<priority-label>' --label '<status-label>'`",
+        "7. **Set the GitHub issue type** via the GraphQL `updateIssueIssueType` mutation:",
+        "   - Look up the issue's node ID: `gh issue view <issue-number> --json id -q .id`",
+        "   - Look up the repo's issue type node IDs (one-time, can be cached):",
+        "",
+        "     ```sh",
+        "     gh api graphql -f query='query($owner:String!,$repo:String!){repository(owner:$owner,name:$repo){issueTypes(first:20){nodes{id name}}}}' -f owner=<owner> -f repo=<repo>",
+        "     ```",
+        "",
+        "   - Apply the chosen type to the issue:",
+        "",
+        "     ```sh",
+        "     gh api graphql -f query='mutation($issueId:ID!,$typeId:ID!){updateIssueIssueType(input:{issueId:$issueId,issueTypeId:$typeId}){issue{number issueType{name}}}}' -f issueId=<issue-node-id> -f typeId=<issue-type-node-id>",
+        "     ```",
         "",
         "### Issue Body Template",
         "",
@@ -898,7 +1033,7 @@ var githubWorkflowBundle = {
         "### Important",
         "",
         "- Always use the conventional prefix in the issue title",
-        "- Always assign the correct GitHub issue type",
+        "- Always assign the correct GitHub issue type via the `updateIssueIssueType` GraphQL mutation (step 7) \u2014 never via `gh issue create --type`",
         "- Always include `type:*`, `priority:*`, and `status:*` labels",
         "- If the user does not specify a type, ask before creating the issue",
         "- If the priority cannot be inferred from the description, ask the user before creating the issue",