102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
## Crosslink Task Management
|
|
|
|
Create issues before starting work to keep things organized and enable context handoff between sessions.
|
|
|
|
### Creating Issues
|
|
- Use `crosslink quick "title" -p <priority> -l <label>` for one-step create+label+work.
|
|
- Issue titles should be changelog-ready: start with a verb ("Add", "Fix", "Update"), describe the user-visible change.
|
|
- Add labels for changelog categories: `bug`/`fix` → Fixed, `feature`/`enhancement` → Added, `breaking` → Changed, `security` → Security.
|
|
- For multi-part features: create parent issue + subissues. Work one at a time.
|
|
- Add context as you discover things: `crosslink issue comment <id> "..."`
|
|
|
|
### Labels for Changelog Categories
|
|
- `bug`, `fix` → **Fixed**
|
|
- `feature`, `enhancement` → **Added**
|
|
- `breaking`, `breaking-change` → **Changed**
|
|
- `security` → **Security**
|
|
- `deprecated` → **Deprecated**
|
|
- `removed` → **Removed**
|
|
- (no label) → **Changed** (default)
|
|
|
|
### Quick Reference
|
|
```bash
|
|
# One-step create + label + start working
|
|
crosslink quick "Fix auth timeout" -p high -l bug
|
|
|
|
# Or use create with flags
|
|
crosslink issue create "Add dark mode" -p medium --label feature --work
|
|
|
|
# Multi-part feature
|
|
crosslink issue create "Add user auth" -p high --label feature
|
|
crosslink issue subissue 1 "Add registration endpoint"
|
|
crosslink issue subissue 1 "Add login endpoint"
|
|
|
|
# Track progress
|
|
crosslink session work <id>
|
|
crosslink issue comment <id> "Found existing helper in utils/" --kind observation
|
|
|
|
# Close (auto-updates CHANGELOG.md)
|
|
crosslink issue close <id>
|
|
crosslink issue close <id> --no-changelog # Skip changelog for internal work
|
|
crosslink issue close-all --no-changelog # Batch close
|
|
|
|
# Quiet mode for scripting
|
|
crosslink -q create "Fix bug" -p high # Outputs just the ID number
|
|
```
|
|
|
|
### Session Management
|
|
Sessions auto-start. End them properly when you can:
|
|
```bash
|
|
crosslink session work <id> # Mark current focus
|
|
crosslink session end --notes "..." # Save handoff context
|
|
```
|
|
|
|
End sessions when: context is getting long, user indicates stopping, or you've completed significant work.
|
|
|
|
Handoff notes should include: what was accomplished, what's in progress, what's next.
|
|
|
|
### Typed Comments (REQUIRED)
|
|
|
|
Every `crosslink comment` MUST include `--kind` to categorize the comment for audit trails. This is not optional.
|
|
|
|
**Kinds**: `plan`, `decision`, `observation`, `blocker`, `resolution`, `result`, `handoff`
|
|
|
|
**Minimum required comments per issue:**
|
|
1. `--kind plan` — before writing code (what you intend to do)
|
|
2. `--kind result` — before closing (what you delivered)
|
|
|
|
**Also required when applicable:**
|
|
- `--kind decision` — when choosing between approaches
|
|
- `--kind blocker` / `--kind resolution` — when blocked and unblocked
|
|
- `--kind observation` — when you discover something noteworthy
|
|
|
|
```bash
|
|
crosslink issue comment <id> "Will refactor auth module to use middleware pattern" --kind plan
|
|
crosslink issue comment <id> "Chose middleware over decorator — matches existing patterns" --kind decision
|
|
crosslink issue comment <id> "Auth module refactored, 12 tests pass" --kind result
|
|
```
|
|
|
|
**You cannot omit `--kind`.** Even for brief comments, categorize them. The audit trail depends on it.
|
|
|
|
### Priority Guide
|
|
- `critical`: Blocking other work, security issue, production down
|
|
- `high`: User explicitly requested, core functionality
|
|
- `medium`: Standard features, improvements
|
|
- `low`: Nice-to-have, cleanup, optimization
|
|
|
|
### Dependencies
|
|
```bash
|
|
crosslink issue block 2 1 # Issue 2 blocked by issue 1
|
|
crosslink issue ready # Show unblocked work
|
|
```
|
|
|
|
### Large Implementations (500+ lines)
|
|
1. Create parent issue: `crosslink issue create "<feature>" -p high`
|
|
2. Break into subissues: `crosslink issue subissue <id> "<component>"`
|
|
3. Work one subissue at a time, close each when done
|
|
|
|
### Context Window Management
|
|
When conversation is long or task needs many steps:
|
|
1. Create tracking issue: `crosslink issue create "Continue: <summary>" -p high`
|
|
2. Add notes: `crosslink issue comment <id> "<what's done, what's next>"`
|