issue

GitHub Issue Automation

Use these scripts for issue creation and listing. 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 a task whose explicit Parent RFC: block names one RFC document, validate that RFC document and read its github_issue value. Fail if the block is ambiguous or the RFC has no issue. Pass the resolved issue number to the task creation command:

tools/issue.rs validate-doc-path \
  --path docs/rfcs/0001-example.md

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

The tool forwards --parent to the same gh issue create command so GitHub creates a native sub-issue. Do not add Part of #<parent> to the body and do not run a follow-up linking command. Omit --parent for standalone tasks and RFC documents.

This script always uses --body-file to avoid body-length command issues. Issue bodies include planning metadata plus selected document context:

• task docs: Summary, Context, Goals, and Non-Goals
• RFC docs: Summary, Context, and Decision

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

Reference

If workflow details are needed, read:

• references/workflow.md