name: issue description: Automate GitHub Issues lifecycle workflows with deterministic scripts. Use when creating, triaging, assigning, updating, linking, or closing issues in this repository, especially when converting planning documents in docs/tasks or docs/rfcs into trackable GitHub issues with required type labels and default priority handling.

GitHub Issue Automation

Use these scripts for all issue operations. Avoid interactive gh prompts. Scripts are executable; invoke them directly (no cargo +nightly -Zscript prefix).

Enforce Document-First Creation

Before creating an issue, validate the planning document path:

tools/issue.rs validate-doc-path --path docs/tasks/000001-example.md

Accepted paths:

• docs/tasks/<6 digits>-<slug>.md
• docs/rfcs/<4 digits>-<slug>.md

Create operations must fail if no valid planning document is provided.

If user input is id-only shorthand (for example $issue create task 000047), resolve id to exactly one document first:

tools/doc-id.rs search-by-id --kind task --id 000047 --scope open

Create Issue From Planning Doc

tools/issue.rs create-issue-from-doc \
  --doc docs/tasks/000001-example.md \
  --labels "type:task,priority:high" \
  --assignee "@me"

create-issue-from-doc must use assignee @me. After successful issue creation, the tool also syncs github_issue: <issue-id> back into the source planning doc immediately (task or RFC) so later workflows can read issue linkage directly from doc content.

--labels is optional. If omitted, labels can be derived from planning-doc metadata:

Issue Labels:
- type:task
- priority:high
- codex

When both metadata and --labels are present:

• CLI type:* and priority:* override metadata values.
• codex is unioned from both sources.

Defaults when no source provides a value:

• task doc -> type:task
• RFC doc -> type:epic
• priority -> priority:medium

For child issues linked to an epic:

tools/issue.rs create-issue-from-doc \
  --doc docs/tasks/000002-subtask.md \
  --labels "type:task" \
  --assignee "@me" \
  --parent 42

This script always uses --body-file to avoid body-length command issues. Allowed labels are strictly validated:

• type: type:doc, type:perf, type:feature, type:question, type:bug, type:chore, type:epic, type:task
• priority: priority:low, priority:medium, priority:high, priority:critical
• special: codex

List Issues

tools/issue.rs list-issues --state open --assignee "@me" --limit 50

Use --label repeatedly for multiple labels:

tools/issue.rs list-issues --label type:task --label priority:high

Update Issue

tools/issue.rs update-issue \
  --issue 123 \
  --add-label "priority:high" \
  --comment "Refined acceptance criteria."

Supported update operations:

• Add/remove labels
• Add/remove assignees
• Replace body (--body or --body-file)
• Add comment

For multiline comments, markdown, Rust code, or text containing backticks, prefer --comment-file over inline --comment. Default safe pattern: write the text to a temp file with a quoted heredoc such as <<'EOF', then pass that file path.

Close Issue

tools/issue.rs close-issue \
  --issue 123 \
  --comment "Completed in PR #456."

Use --comment-file when the close comment is longer than a short phrase or contains markdown/backticks.

Resolve RFC Issue (Precheck + Explicit Close)

Use RFC-specific resolve flow instead of direct close when closing RFC issues:

tools/issue.rs resolve-rfc \
  --doc docs/rfcs/0006-example.md

This runs RFC resolve precheck only (no closure).

To close explicitly after precheck passes:

tools/issue.rs resolve-rfc \
  --doc docs/rfcs/0006-example.md \
  --issue 456 \
  --close \
  --comment "RFC implemented and synchronized."

Use --comment-file for longer resolve comments or any text that includes markdown/backticks.

Rules:

• resolve-rfc must validate all sub-task/docs/backlog prechecks before closure.
• No automatic issue closure from rfc resolve; closure requires explicit --close.
• For legacy RFC docs without parseable phase tracking, use --allow-legacy.

Optional PR Bridge

Generate a canonical close-link snippet:

tools/issue.rs link-pr-guidance --issue 123

Use the snippet in PR body (for example: Fixes #123).

Or create PR directly from current branch with default close-link body:

tools/issue.rs create-pr-from-branch --issue 123 --push --assignee "@me"

Default body includes Closes #123. Assignee must be @me. If --title is omitted, title is auto-derived from changed planning docs in base...head:

• if both task and RFC docs are present, RFC is preferred.
• if only RFC docs are present, use RFC title with a suitable type prefix (default feat:).
• if only task docs are present, use task title with a suitable type prefix (default chore:).
• explicit --title always overrides auto title. Before creating PR, workflow must check for uncommitted changes. If dirty changes exist, developer must explicitly decide to:

1. manually commit selected changes, or
2. ignore and proceed with explicit override:

tools/issue.rs create-pr-from-branch --issue 123 --push --assignee "@me" --allow-dirty

Reference

If workflow details are needed, read:

• references/workflow.md