codingthefuturewithai/teamcraft:create-issue

Goal

Create a well-structured work item in .teamcraft/work/ that captures what needs to be done and how to know it's done. The work item should contain enough information for a developer (or AI agent) to pick it up later and understand the requirements — but stay light on technical implementation details, which are generated fresh at implementation time.

Create the item to the work-item standard — ../references/work-item-standard.md is the single source of truth for the format, ID rules, relationships, INDEX update, and commit, shared by every skill that creates work items. Read it first, plus references/example-work-item.md for worked examples of the shape and what "light on technical guidance" looks like in practice.

What to Capture

1. Understand what the developer wants to capture. $ARGUMENTS is a brief description or empty. If it's a description, use it as a starting point. If empty, ask what work they want to track.

2. Ask about external context. "Do you have requirements, mockups, user research, or any other context for this work documented somewhere I can access?" Read whatever they point to. Present what you found and let the developer decide what's relevant — never auto-apply external content.

3. Interview for the essentials. After reviewing any external context, fill in what's still missing:

• What is this work? (clear title and description)
• Why does it matter? (business context, user need, bug impact)
• What does "done" look like? (acceptance criteria — specific, testable)
• Priority? (critical, high, medium, low)
• Effort estimate? (small, medium, large, xl — optional, developer can skip)
• Is this a feature, bug, or chore? (determines the ID prefix)

4. Ask about relationships to other work items. After the essentials, ask whether this item has any structured relationships to existing work items. Phrase it briefly so simple items don't slow down. For example: "Is this blocked by, related to, or a duplicate of any existing work item? (skip if none)". If yes, capture:

• blocked_by — work items that must complete before this one can start. Most important to capture; gates pickability.
• relates_to — soft links to items that share context or touch the same area without a hard sequence.
• duplicates — historical pointer when this item is the same as an earlier one; the duplicate is closed (status done) and points to the original.

Validate IDs lightly: glob .teamcraft/work/*.md and warn if a referenced ID isn't found ("feat-xyz isn't in the backlog — was it spelled differently, or is it not created yet?"). Don't block on this — the developer may be creating items out of order. Don't write blocks as the inverse of blocked_by — the work-board and the other consumers compute that direction on read; storing both sides invites drift.

See "Relationships vs Bundling" below for when to use relationships at all vs. just making it one work item.

5. Present the work item for review. Show the complete work item before writing it, including any relationships. The developer confirms or adjusts.

Write the Work Item

Write the item to the work-item standard (../references/work-item-standard.md): generate the ID, write .teamcraft/work/<id>.md, add the INDEX row, and commit with the work-item ID in the message. The standard owns all the format and mechanics — ID rules, frontmatter, body shape, INDEX update, one-way relationships, and the relationships-vs-bundling test — so they live in one place rather than being restated here.

Relationships vs Bundling

When the developer mentions a connection to other work, decide whether it's a real relationship or just part of this one item — the work-item standard's Relationships vs bundling section is the test. The trap to watch for in the interview: treating implementation steps as separate work items. They aren't — steps are acceptance criteria. Relationships are only for things that genuinely ship as separate PRs.

Constraints

• The developer can create multiple work items in one session. After creating one, ask if they have more to capture. Don't end the skill after a single item unless they're done.
• Everything about the item's shape and robustness — light-on-technical-guidance, status: backlog at creation, one-way relationships, the commit — is defined once in ../references/work-item-standard.md. Follow it; don't improvise a lighter version.

When You're Done

Confirm what was created, including the file path and the INDEX.md update. If the developer wants to start working on the item immediately, point them to /plan-and-implement-issue <id>.