/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 project
Issue 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 tracking
Execution Flow
- Gather Context
If no description: "What needs to be done?" If no project: "Which project?"
- Detect Type
Analyze description keywords, present detection:
"This sounds like a TASK. Create as issue 002? (yes / spike / bug)"
- Determine Next Issue Number
ls ideas/[project]/issues/ | grep -E '^[0-9]{3}-' | sort -n | tail -1
- Ask About Spec Section
Check if project has a spec:
Glob: spaces/[project]/docs/specs/*.md
If spec exists:
"Which spec section does this implement?"
-
docs/specs/required-features.md#authentication
-
docs/specs/required-features.md#documents
-
none (standalone task)
- 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
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
- Approach A
- 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
-
Step 1
-
Step 2
-
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/password
The /complete command will mark these ✅ when done.
- 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-004
Don'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-password
This creates a direct link between work items and the exact requirement they fulfill.
Workflow
/spec → /issue → /plan → (work) → /complete ↓ implements: spec section