| name | create-issue |
| description | Create a GitHub issue and add it to the Typhon org project |
| argument-hint | [title] or leave empty for interactive mode |
Create GitHub Issue for Typhon
Create a GitHub issue in log2n-io/Typhon and add it to the Typhon org project (org Log2n-io, project number 1).
Migration note (2026-06-29): the repo moved to log2n-io/Typhon and the board to the org project orgs/Log2n-io/projects/1. Native Issue Types (Task / Bug / Feature / Epic) are live, and Area / Product are issue-level fields (the ones Epics carry), not project single-selects. Release maturity is expressed as a Milestone on Features. Use owner log2n-io for repo/API ops and Log2n-io for gh project ops (both resolve to the same org; GitHub owner matching is case-insensitive).
🔴 Hierarchy rule — Epic → Feature → Task, no skipping. The development cycle revolves around Features, so an Epic's direct children must be typed Feature, never Task. A Task may only be a child of a Feature (further breakdown of one feature's implementation), never a direct child of an Epic. Concretely: parent_issue_url = an Epic ⟹ child type = Feature; parent_issue_url = a Feature ⟹ child type = Task. Verified pattern: #146 (Epic) → #147 (Feature) is a direct child; #435 (Feature, child of #146) → #427 (Task, child of #435). If a piece of epic-level work doesn't need further breakdown, it's still typed Feature as the Epic's direct child — don't downgrade it to Task just because it has no children of its own yet.
Input provided by user
$ARGUMENTS
Help
If $ARGUMENTS contains --help or -h, display the following and stop — do not execute the workflow.
/create-issue [title]
Create a GitHub issue and add it to the Typhon org project.
Arguments:
title Issue title text — if provided, skips the title prompt
--help, -h Show this help
What it does:
1. Gathers info (title, description, labels, issue type, area, product, milestone)
2. Creates the issue (MCP) and sets its Issue Type (gh --type)
3. Adds it to the Typhon org project board and sets Status
4. Optionally links it under a parent Epic as a native sub-issue
Examples:
/create-issue
/create-issue "Add spatial indexing support"
Required information
Gather the following. If NOT provided in the arguments, use AskUserQuestion:
- Title (required): a clear, concise issue title
- Description (required): what needs to be done and why
- Issue Type (recommended — native):
Task, Bug, Feature, Question, or Epic
- Type labels (optional): one or more of
bug, enhancement, documentation, performance, refactoring, testing, technical-debt
(Questions use the Question Issue Type, not a label.)
- Area (optional — issue-level field): the subsystem outcome area (e.g. Execution, Storage, Concurrency, Observability, …). Match the parent Epic's Area when there is one.
- Product (optional — issue-level field): e.g.
Engine, Workbench.
- Milestone (optional — release maturity on Features): e.g.
alpha-1.
- Parent Epic (optional): issue number to link under as a native sub-issue.
Priority / Estimate were project single-selects on the old board and are currently unconfigured on the new one. If needed, convey priority with labels (important, P0-Critical, P1-High, …) rather than a project field.
Gathering information
- If the user gave a clear title + description, proceed directly.
- Otherwise ask via
AskUserQuestion; multi-select for labels.
- Confirm the Issue Type — it's the primary classifier now (labels are secondary).
Creating the issue
IMPORTANT — absolute URLs in the body. GitHub renders issue bodies outside the repo context (project board, etc.), so relative links 404. Use https://github.com/Log2n-io/Typhon/blob/main/<path> for files and https://github.com/Log2n-io/Typhon/tree/main/<path> for directories. See .claude/skills/_helpers.md rule #9.
Step 1: Create the issue (MCP)
Use mcp__GitHub__create_issue with:
- owner:
"log2n-io"
- repo:
"Typhon"
- title:
"<title>"
- body:
"<description>"
- labels:
["<label1>", "<label2>"]
- assignees:
["nockawa"] ← the maintainer; do NOT change to the org
Capture the returned number, html_url, and id (the big integer — needed for sub-issue linking).
Step 2: Set the Issue Type (gh — MCP has no field for it)
gh issue edit <number> --repo log2n-io/Typhon --type "Feature"
Step 3: Add to the project board
gh project item-add 1 --owner Log2n-io --url <issue_url>
Step 4: Get the project item ID
Robust patterns: see .claude/skills/_helpers.md Section 2.
gh project item-list 1 --owner Log2n-io --limit 500 --format json 2>&1 | python3 -c "
import json, sys
items = json.load(sys.stdin)['items']
for item in items:
if item.get('content', {}).get('number') == int(sys.argv[1]):
print(item['id'])
sys.exit(0)
print('NOT_FOUND')
" <issue_number>
Step 5: Set the project Status
Status is the working project single-select (Todo / In Progress / Done). New work = Todo.
gh project item-edit --project-id PVT_kwDOEcGj5M4Bb-8P --id <ITEM_ID> \
--field-id PVTSSF_lADOEcGj5M4Bb-8PzhWrH1A --single-select-option-id f75ad846
Step 6 (optional): Set Area / Product / Milestone
- Milestone (release maturity):
gh issue edit <number> --repo log2n-io/Typhon --milestone "alpha-1"
- Area / Product are issue-level fields (the same ones Epics carry — e.g. #146 = Area:Execution, Product:Engine), not the now-empty project single-selects.
gh has no dedicated flag yet; set them via the GitHub web UI, or via GraphQL if scripting. Match the parent Epic's values when linking under one.
Step 7 (optional): Link under a parent Epic or Feature (native sub-issue)
Before linking, check the parent's Issue Type and set the child's type to match the Epic → Feature → Task rule above: linking under an Epic ⟹ child type Feature; linking under a Feature ⟹ child type Task. Never link a Task directly under an Epic.
Use the issue's database id (big integer from Step 1), and -F so it serializes as a JSON integer. On Git Bash, prefix MSYS_NO_PATHCONV=1 because the API path starts with /.
MSYS_NO_PATHCONV=1 gh api repos/log2n-io/Typhon/issues/<epic_number>/sub_issues \
-X POST -F sub_issue_id=<issue_database_id>
Verify: gh issue view <epic_number> --repo log2n-io/Typhon --json subIssuesSummary.
Umbrella issues (parent-of-many)
If the issue is a multi-phase umbrella with separate tracking issues per phase, do both:
- Include a
[tasklist] block in the body with one #N per sub-issue — the human-readable checklist.
- Link each sub-issue natively via the Sub-issues API (Step 7 pattern) — this drives GitHub's Sub-issues panel / roll-up, which reflects only native links, not the
[tasklist] text.
SUB_ID=$(gh api repos/log2n-io/Typhon/issues/<sub_number> --jq '.id')
MSYS_NO_PATHCONV=1 gh api repos/log2n-io/Typhon/issues/<umbrella_number>/sub_issues -X POST -F sub_issue_id=$SUB_ID
Verify:
MSYS_NO_PATHCONV=1 gh api repos/log2n-io/Typhon/issues/<umbrella_number>/sub_issues | python3 -c "
import json, sys
for s in json.load(sys.stdin):
print(f'#{s[\"number\"]} - {s[\"title\"]} [{s[\"state\"]}]')
"
Do both — the [tasklist] gives a body-embedded checklist (used by /complete-subtask), the native linkage gives GitHub's first-class Sub-issues UI. If retroactively converting an existing [tasklist] umbrella (its subIssuesSummary.total is 0), just run the linking loop — no body edit needed.
Field Reference (org project Log2n-io / #1)
Project
- Project ID:
PVT_kwDOEcGj5M4Bb-8P (number 1, owner Log2n-io)
Status Field (the working project single-select)
- Field ID:
PVTSSF_lADOEcGj5M4Bb-8PzhWrH1A
- Options:
Todo = f75ad846 · In Progress = 47fc9ee4 · Done = 98236657
Other project single-selects (currently empty — no options configured)
- Priority:
PVTSSF_lADOEcGj5M4Bb-8PzhWsLu0 · Estimate: PVTSSF_lADOEcGj5M4Bb-8PzhWsLu4 · Area: PVTSSF_lADOEcGj5M4Bb-8PzhWsLu8 · Product: PVTSSF_lADOEcGj5M4Bb-8PzhW2BfY
- Re-verify anytime:
gh project field-list 1 --owner Log2n-io --format json
Issue-level classifiers (not project fields)
- Issue Type:
gh issue edit <n> --repo log2n-io/Typhon --type "<Type>" (Task/Bug/Feature/Question/Epic)
- Area / Product: issue custom fields (web UI / GraphQL); mirror the parent Epic
- Milestone: release maturity —
gh issue edit <n> --repo log2n-io/Typhon --milestone "<name>"
Output
After creating, report back with:
- Issue number, title, and link
- Issue Type set
- Confirmation it was added to the Typhon org project (+ Status)
- Parent Epic link, if any
- Any Area / Product / Milestone / labels set
Example interaction
User: /create-issue Add support for spatial indexing
Claude: asks for description, issue type, area, and (optionally) parent Epic
User: provides answers
Claude: creates issue, sets type, adds to project + Status, links parent, reports success
Feature #123 created: "Add support for spatial indexing"
Link: https://github.com/Log2n-io/Typhon/issues/123
Issue Type: Feature
Added to Typhon org project · Status: Todo
Parent: sub-issue of Epic #NN
Area: Indexes · Product: Engine · Labels: enhancement, performance