/issue
Create standalone work items through natural conversation with AI-assisted type detection.
Usage
/issue # Start conversation
/issue "Implement authentication" # AI detects: TASK
/issue "Compare GraphQL vs REST" # AI detects: SPIKE
/issue "Broken link in project-brief" # AI detects: BUG
/issue --project coordinatr # Create for specific projectIssue Types
| Type | Purpose | Detection Keywords |
|---|---|---|
| TASK | Work that needs doing | implement, create, add, build, write, set up |
| SPIKE | Time-boxed exploration | compare, vs, should we, evaluate, explore, research, feasibility |
| BUG | Something broken/wrong | fix, broken, incorrect, outdated, wrong, error |
File Structure
ideas/[project]/issues/
└── 001-implement-auth/
├── TASK.md # or SPIKE.md or BUG.md
├── PLAN.md # Created by /plan
└── WORKLOG.md # Progress trackingExecution Flow
1. Gather Context
If no description: "What needs to be done?" If no project: "Which project?"
2. Detect Type
Analyze description keywords, present detection:
"This sounds like a TASK. Create as issue 002? (yes / spike / bug)"
3. Determine Next Issue Number
ls ideas/[project]/issues/ | grep -E '^[0-9]{3}-' | sort -n | tail -14. Ask About Spec Section
Check if project has a spec:
Glob: spaces/[project]/docs/specs/*.mdIf spec exists:
"Which spec section does this implement?" - docs/specs/required-features.md#authentication - docs/specs/required-features.md#documents - none (standalone task)
5. Create Issue Files
TASK.md:
---
status: open
created: YYYY-MM-DD
implements: docs/specs/required-features.md#authentication # or empty if standalone
depends_on: []
---
# TASK-###: [Title]
## Description
[What needs to be done and why]
## Implements
**Spec Section:** [docs/specs/required-features.md#authentication](../../spaces/[project]/docs/specs/required-features.md#authentication)
**Requirements from spec:**
- [Requirement 1 from spec]
- [Requirement 2 from spec]
## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
## Context
[Background, relevant decisions, technical notes]SPIKE.md:
---
status: open
created: YYYY-MM-DD
timebox: X hours
---
# SPIKE-###: [Title]
## Questions
- Question 1?
- Question 2?
## Approaches to Explore
1. Approach A
2. Approach B
## Findings
(filled after exploration)
## Recommendation
(filled after exploration)BUG.md:
---
status: open
created: YYYY-MM-DD
---
# BUG-###: [Title]
## What's Broken
[Description of the problem]
## Location
[File paths, URLs, etc.]
## Expected Behavior
[What should happen]
## Steps to Reproduce
1. Step 1
2. Step 26. Mark Spec Section In Progress (if implements spec)
If the issue implements a spec section, update the inline status markers in the spec:
# Before
- ⏳ User registration with email/password
# After
- 🚧 User registration with email/passwordThe /complete command will mark these ✅ when done.
7. Next Steps
- For TASK/BUG: Suggest
/plan ###to create implementation phases - For SPIKE: Suggest
/plan ###to create exploration plan
Status Values
| Status | Meaning |
|---|---|
open | Not started |
in_progress | Being worked on |
blocked | Waiting on something |
complete | Done |
Spec Integration
Task Scoping
One TASK = One requirement line item
A TASK should be atomic and shippable:
- Implements exactly one spec requirement
- Can be pushed to main independently
- Updates one
⏳→✅marker when complete
# Spec line items (each becomes a TASK)
- ⏳ User registration with email/password ← TASK-002
- ⏳ User login with JWT token ← TASK-003
- ⏳ Password reset flow ← TASK-004Don't create: "TASK: Implement Authentication" (too broad) Do create: "TASK: User registration endpoint" (one requirement)
implements: Field
# Points to the specific requirement
implements: docs/specs/required-features.md#user-registration-with-email-passwordThis creates a direct link between work items and the exact requirement they fulfill.
Workflow
/spec → /issue → /plan → (work) → /complete
↓
implements: spec section