acostanzo/ticket

/avanti:ticket — Draft a new ticket

You are the /avanti:ticket orchestrator. When the user runs /avanti:ticket <slug> --plan <plan-slug>, mint the next plan-scoped ticket ID, copy templates/ticket.md into project/tickets/open/<id>-<slug>.md, fill the frontmatter, and update the plan's tickets: array to include the new ID. Every ticket belongs to a plan — invocation without --plan is an error.

Read ${CLAUDE_PLUGIN_ROOT}/references/sdlc-conventions.md if you are uncertain about any lifecycle, ID-mint, or frontmatter rule.

Phase 0: Parse and validate

Step 1: Parse arguments

$ARGUMENTS takes the form <slug> --plan <plan-slug>. Extract:

• SLUG — the ticket's kebab-case suffix (the part after <id>- in the filename).
• PLAN_SLUG — the value that follows --plan.

If --plan is missing or has no value, abort:

/avanti:ticket requires a --plan <plan-slug> argument.
Every ticket belongs to a plan; there are no standalone tickets.
Usage: /avanti:ticket <slug> --plan <plan-slug>

Validate SLUG and PLAN_SLUG against ^[a-z][a-z0-9]*(-[a-z0-9]+)*$. On failure, use AskUserQuestion to re-prompt for whichever is invalid.

Step 2: Locate the repo root

Run git rev-parse --show-toplevel 2>/dev/null. Abort if this fails. Store as REPO_ROOT.

Step 3: Resolve the plan

Glob for project/plans/*/${PLAN_SLUG}.md under REPO_ROOT. If zero matches, abort:

No plan with slug "${PLAN_SLUG}" found under project/plans/.
Check the slug or draft the plan first with /avanti:plan ${PLAN_SLUG}.

If multiple match (should never happen per collision rules in /avanti:plan), abort and list all matches for the user to resolve.

Store the single matching path as PLAN_PATH.

Step 4: Ensure the tickets directory exists

The destination is deterministic: ${REPO_ROOT}/project/tickets/open/. If it is missing, create it with mkdir -p via Bash and continue. The destination is avanti's to manage and cheap to create on demand.

A repo with no project/ at all will already have failed the plan-resolve step in Step 3 (no plans means no --plan resolution), so this branch is unreachable in practice; if it is somehow reached, still proceed with the mkdir and write the ticket.

Phase 1: Mint the ID

Step 1: Read the plan's frontmatter

Read PLAN_PATH. Extract the tickets: array from the YAML frontmatter block.

• If the frontmatter has no tickets: key → treat as empty array [].
• If tickets: is present but empty ([]) → starting fresh.
• If tickets: holds [t1, t2, …] → use those.

Parse the integer suffix from each entry that matches ^t\d+$ (e.g., t3 → 3). Ignore entries that do not match — plans commonly carry acceptance-bar IDs (a1, a2, …) in the same tickets: array, and those are not minted by this skill. Store the max of the t-prefixed IDs as MAX_ID (default 0 if no matching entries exist).

Step 2: Mint

NEW_ID = t${MAX_ID + 1}.

Step 3: Check for file collision

Glob for project/tickets/*/${NEW_ID}-*.md under REPO_ROOT. For every match, read the file's frontmatter and check whether plan: equals PLAN_SLUG. Only abort if a same-plan match exists — different plans legitimately each have their own t1, t2, … sequence, so a t1-foo.md under another plan is not a collision. If a same-plan match is found, abort: "Ticket id ${NEW_ID} is already in use by <path> under plan ${PLAN_SLUG}." (Cross-plan IDs sharing the same numeric prefix are by design — see references/sdlc-conventions.md#plan-scoped-ticket-ids.)

Also glob for project/tickets/*/*-${SLUG}.md. Slug uniqueness is repo-wide because filenames don't carry the plan slug — two plans both choosing the slug foo would produce filename collisions. If any match, warn the user clearly and abort:

A ticket with slug "${SLUG}" already exists at <path>.
Pick a different slug.

Phase 2: Render and write

Step 1: Read the template and today's date

Read ${CLAUDE_PLUGIN_ROOT}/templates/ticket.md as TEMPLATE. Run date +%Y-%m-%d as TODAY.

Step 2: Gather authoring input

Use AskUserQuestion to collect:

1. Ticket title — short, descriptive. Used as the H1 after frontmatter.
2. Context paragraph — one paragraph explaining what this ticket is for and where it sits in the plan.

Store as TITLE and CONTEXT.

Step 3: Fill placeholders

Produce RENDERED by applying these substitutions to TEMPLATE:

• id: TODO → id: ${NEW_ID}
• plan: TODO → plan: ${PLAN_SLUG}
• updated: TODO → updated: ${TODAY}
• # TODO — <ticket title> → # ${NEW_ID} — ${TITLE}
• The "TODO: one short paragraph..." under ## Context → ${CONTEXT}
• project/plans/active/<plan-slug>.md in the Links block → project/plans/active/${PLAN_SLUG}.md (leave as-is if the plan lives in draft/ or done/ — the convention is to reference the active path; stale links are rare and not worth guarding)

Leave the acceptance-criteria, notes, and other TODO sections intact for the author to fill in.

Step 4: Write

Write RENDERED to ${REPO_ROOT}/project/tickets/open/${NEW_ID}-${SLUG}.md.

Phase 3: Update the plan

Use Edit on PLAN_PATH to add NEW_ID to the tickets: array in the plan's frontmatter.

• If tickets: holds [t1, t2, t3] → rewrite to [t1, t2, t3, ${NEW_ID}].
• If tickets: is empty [] → rewrite to [${NEW_ID}].
• If there is no tickets: key → add one immediately after status:.

Also bump the plan's updated: to TODAY — any new ticket is a meaningful plan-level change.

Phase 4: Report

Tell the user:

Ticket drafted: project/tickets/open/${NEW_ID}-${SLUG}.md
Plan updated:   ${PLAN_PATH} (tickets: […, ${NEW_ID}])

Next:
  - Fill in the acceptance criteria and any notes.
  - Move to in-progress by editing status (folder stays put).
  - Close with /avanti:promote ticket:${NEW_ID}-${SLUG} when done.

Error handling

• --plan missing: abort immediately with the "every ticket belongs to a plan" message. Never fall through to a default plan.
• Plan not found: name the missing slug and point to /avanti:plan.
• ID collision (file exists with NEW_ID): abort — something is out of sync; the user should inspect the tickets directory before continuing.
• Slug collision (any existing ticket matches *-${SLUG}.md): abort with the existing path.
• Write failure after plan edit: revert the plan edit if possible (restore the original tickets: and updated:), then re-raise.