issue-create

Files (5)

• SKILL.md
• eval-confirm-gate.sh · scripts/
• make-empty-verdict.sh · scripts/
• run-bulk-dispatch.sh · scripts/
• run-phase5-record.sh · scripts/

SKILL.md (first lines)

The sanctioned path for creating **task issues** (`type:task`) from a Claude Code
session. Surveys existing issues first, classifies the relationship semantically,
then dispatches to a wrapper that handles reopen / sub-issue attach / new-parent
reclassification / sibling cross-reference / plain creation. The dispatcher
delegates new-issue creation to `bin/github-issues/issue-create.sh`.

## Scope

- **In scope**: task issues (`type:task`) for the current repository.
- **Out of scope**: incident issues (use the web UI incident template or a
  `--label "type:incident"` invocation of your own); issues for other repos or
  projects, which take the cross-repo path below.
- Cross-repo work: confirm the ownership of the target repository before filing the issue — an issue lands publicly in whichever repo `gh` resolves, and that resolution follows the working directory when no target is named.

Required reading: Read `rules/github-issues.md` before Pre-flight — it is on-demand-only and never auto-injected.
Read `rules/coding.md` before writing any issue title or body — on-demand-only, never auto-injected; its Public GitHub Rules govern this outbound write.
Apply the TERMS line of hooks/lib/lang-directives.txt and the Writer directives in skills/_shared/combined-glossary.md to issue titles and bodies; both govern terminology only, not the body language.

## Phase 0b — Project preflight

Runs before Pre-flight. Detects a missing Projects v2 board and offers to run `/issue-setup`. Independent of Phase 0a (label auto-repair in `issue-create.sh`) — one's result never affects the other.

- Skip Phase 0b and proceed to Pre-flight when `bin/is-github-dotcom-remote` returns non-zero (non-GitHub remote).
- Run `bash "$AGENTS_MAIN_ROOT/bin/github-issues/issue-create-preflight.sh" --check-project` (add `--repo OWNER/REPO` when targeting another repo).
- On rc=1 (no board), AskUserQuestion:
  - `run-issue-setup`: run `/issue-setup` against the target repo, then re-check Phase 0b.
  - `skip-this-time`: proceed to Pre-flight; the attach step remains warn-only.
- `skip-this-time` is NOT persisted — Phase 0b re-checks on every `issue-create` run (no suppression state file).

## Pre-flight

- `AGENTS_MAIN_ROOT` must be set.
- `gh` must be authenticated against the current repository.
- `gh` must have the `project` scope for Projects v2 attach. Add with
  `gh auth refresh -s project`.
- The `type:task` label must exist. `issue-create.sh` Phase 0a auto-syncs it when missing (run `/issue-setup` to initialize a fresh repo).

## Mid-workflow gate

Runs after Pre-flight, before Phase 1. Detects mid-workflow context to surface
adjacent-issue awareness to the user. Informational-only — never aborts the skill.
Phase 1 runs regardless of gate outcome.

IC-1. Resolve session intent:
   Resolve `<PLANS_DIR>` with one standalone Bash call —
   `bash "$AGENTS_MAIN_ROOT/bin/workflow-plans-dir"` — and read `<SESSION_ID>`
   from `$CLAUDE_CODE_SESSION_ID`. `<INTENT_MD>` is the output of `node "$AGENTS_MAIN_ROOT/bin/plan-artifact-path" --stage intent --session <SESSION_ID>` (a failed call counts as no intent).
   Skip the gate silently when `<SESSION_ID>` is empty or `<INTENT_MD>` does not exist.

IC-1a. Read `rules/mid-workflow-findings.md` — on-demand-only, never auto-injected; it owns the capture paths the IC-3 notice points the user at.

IC-2. Parse `closes_issues` with one standalone call (pass the path as a script
   argument — never use `node -e`):
   `node "$AGENTS_MAIN_ROOT/bin/parse-closes-issues" "<INTENT_MD>"`.
   If its stdout is `[]`, empty, or the call fails: skip the gate silently and
   proceed to Phase 1.

IC-3. When `CLOSES` is non-empty, emit a notice:
   - **Interactive:** "This issue is created now and is NOT added to the current session's
     `closes_issues` (#N, ...); only its implementation belongs to a separate session.
     Fallback: write to `<worktree>/WORKTREE_NOTES.md` — see
     `rules/mid-workflow-findings.md`." Then proceed to Phase 1.
   - **Non-interactive:** print the same notice to stderr. Proceed to Phase 1.

## Procedure

Must be invoked from a linked worktree when `ENFORCE_WORKTREE=on`.
Exception — the notes-promotion pass reaches this skill from the main worktree via `/session-close` SC-8 and via `/issue-close-finalize`; both are sanctioned callers with no linked worktree of their own.

Four phases: **Gather → Survey → Confirm → Dispatch**.

### Phase 1 — Gather

Collect title and canonical-schema body from the user.

Required body schema for `type:task` (enforced by `bin/github-issues/issue-create.sh` exit 3):

| Field | Shape variants accepted |
|---|---|
| `Background` | `Background: <text>` / `## Background` / `### Background` |
| `Changes`    | `Changes: <text>` / `## Changes` / `### Changes` |

When the user-provided body is missing one or both required fields, use `AskUserQuestion` with these branches:
- `fix-now`: re-author the body inline with the missing field(s) added.
- `template`: prefill the 2-section template `## Background\n<TBD>\n\n## Changes\n<TBD>` and ask the user to fill it.
- `bypass`: set `ISSUE_CREATE_SKIP_SCHEMA=1` for this invocation — emergency escape hatch; sanctioned path is always to add the missing fields.

### Phase 2 — Survey

The survey follows an ordered cascade that considers `reopen` first; the criteria are defined in `skills/_shared/issue-verdict-cascade.md` (SSOT — never restated here or in the worker).

Every route below produces the same schema-v2 artifact. The worker-bypassing routes write it with `bash "$AGENTS_MAIN_ROOT/skills/issue-create/scripts/make-empty-verdict.sh" <out-path> <verdict> --title T --background B --changes C [--parent N]`.

Of that artifact the main conversation reads only `verdict` / `target` / `children` / `related` / `reason` / `review_result` / `review.worth_filing`. Never read `proposal` or `candidates[].body` into the main context.

If invoked with `--skip-survey` (caller already ran a bulk dedupe pass and supplies an explicit `--verdict bulk-sub-of --parent N --manifest FILE`): skip Phase 2 entirely, write the artifact with `make-empty-verdict.sh <out> bulk-sub-of --parent N`, and proceed to Phase 3 with the caller-supplied verdict.

Skip this phase when `bin/is-github-dotcom-remote` returns non-zero (non-GitHub remote) — write the artifact with `make-empty-verdict.sh <out> none` and proceed to Phase 3 with `verdict: none`.

2a. Pre-resolve in main: `session_id` (from `$CLAUDE_CODE_SESSION_ID`), `agents_main_root` (absolute), `artifact_dir` (`PLANS_DIR` resolved by calling `bash "$AGENTS_MAIN_ROOT/bin/workflow-plans-dir"` directly at this callsite — do NOT reuse any variable from IC-1).
2b. Invoke the `issue-create-survey-worker` subagent via the Agent tool (`subagent_type`) with `title`, `background`, `changes` from Phase 1 input.
    Set the JSON prompt's `dispatch_directive` key to the canonical line of the `rules/shell-commands.md` Subagent Dispatch Prompts section.
2c. `status: failed` → stop and report error.
2d. `status: no_candidates` → write the artifact with `make-empty-verdict.sh <out> none` and proceed to Phase 3 with `verdict: none`.
2e. `status: complete` → read verdict JSON from `artifact_path`.

### Phase 3 — Review and confirm

3a. Review the survey verdict: `bash "$AGENTS_MAIN_ROOT/bin/github-issues/review-survey-verdict-codex.sh" --artifact <survey-artifact> --out <final-artifact>`.
3b. Of `<final-artifact>` read only `verdict` / `target` / `children` / `related` / `reason` / `review.status` / `review.worth_filing`. Phase 4 dispatches on these, not on the Phase 2 values.
3c. Delete the Phase 2 survey artifact (`rm -f <survey-artifact>`) — it is the only file holding full candidate bodies, and the final artifact has superseded it. Skip silently if absent.
3d. Classify the gate: `bash "$AGENTS_MAIN_ROOT/skills/issue-create/scripts/eval-confirm-gate.sh" <final-artifact> <severity-label>` — stdout is `confirm: yes|no` then `reasons: <G-list>`.
3e. `confirm: yes` → AskUserQuestion before Phase 4, naming the fired conditions. `confirm: no` → proceed to Phase 4 without asking.

The gate is the logical OR of five conditions; the script owns the decision, this list only supplies the question text:
- G1 — final verdict is `reopen`, `make-parent`, `sub-of` or `bulk-sub-of` (mutates existing state)
- G2 — the review stage replaced the survey verdict
- G3 — the review did not confirm filing is worthwhile (`review.worth_filing` is not `true`)
- G4 — review status is anything other than `upheld` or `replaced` (verdict unverified)

From nirecom/agents, MIT.

More from nirecom/agents