| name | crosslink-guide |
| description | Use when working in any repo that has `.crosslink/` and the workflow involves issue tracking, sessions, locks, swarms, kickoff, or knowledge pages. Reference for the full crosslink CLI surface plus the harness footguns (auto-CHANGELOG entries on issue close, --no-changelog flag, label-based skip rules, session lifecycle). Trigger when the user mentions crosslink commands, when the crosslink-behavioral-guard hook fires asking for issue creation, or when a session needs to be started/ended/handed off. |
Crosslink Guide
Crosslink is a local-first issue tracker designed for AI-assisted development. Data lives in .crosslink/issues.db (SQLite); state syncs via the crosslink/hub git branch. Read this skill when the workflow involves any crosslink command, when the crosslink-behavioral-guard hook fires, or when starting/ending a session.
Hook awareness — the things that bite
These are not in the CLI --help output but matter constantly:
crosslink issue close auto-appends to CHANGELOG.md
Closing an issue triggers a hook that adds a one-line entry to the workspace's CHANGELOG.md under ### Changed (or ### Fixed for bug-labeled issues). For meta-work that shouldn't be in the release notes (skill edits, settings tweaks, CHANGELOG cleanup itself), this is pollution.
Fix: pass --no-changelog to skip:
crosslink issue close 643 --no-changelog
The recursive trap: if you close an issue without --no-changelog, then close a follow-up issue to clean up the entry, that close also auto-appends. Either use --no-changelog from the start, or remove the line directly via Edit rather than another crosslink close.
crosslink quick doesn't take --no-changelog
Only close triggers the auto-CHANGELOG hook. quick and create do not, so no --no-changelog flag exists on them.
Session must be started before session work <id> succeeds
crosslink session work 642
# Error: No active session. Use 'crosslink session start' first.
Always pair them:
crosslink session start && crosslink session work <id>
--work flag on quick is silently a no-op without an active session
crosslink quick "..." -p high -l bug
# WARN: --work specified but no active session
The issue gets created but isn't marked as the current focus. Same fix: session start first.
Labels matter for hook routing
Bug-labeled issues land under ### Fixed in CHANGELOG; everything else under ### Changed. The chore, docs, refactor labels currently do not exempt the entry from CHANGELOG (use --no-changelog).
Core workflow
crosslink session start
crosslink quick "Title" -p high -l bug
crosslink issue list -s open
crosslink session work <id>
crosslink issue comment <id> "Approach: ..." --kind plan
crosslink issue comment <id> "Chose X over Y because ..." --kind decision
crosslink session end --notes "What's done, what's next, blockers"
Issue management
Creating
crosslink issue create "Title" -p medium
crosslink quick "Title" -p high -l bug
crosslink subissue <parent-id> "Child title"
Querying
crosslink issue list
crosslink issue list -s all
crosslink issue list -l bug -p high
crosslink issue search "keyword"
crosslink issue show <id>
crosslink issue tree
crosslink issue next
Lifecycle
crosslink issue update <id> -t "new title" -p high
crosslink issue close <id>
crosslink issue close <id> --no-changelog
crosslink issue close-all
crosslink issue reopen <id>
crosslink issue delete <id> --force
crosslink issue tested <id>
Comments — typed for audit trails
crosslink issue comment <id> "text" --kind plan
crosslink issue comment <id> "text" --kind decision
crosslink issue comment <id> "text" --kind observation
crosslink issue comment <id> "text" --kind blocker
crosslink issue comment <id> "text" --kind resolution
crosslink issue comment <id> "text" --kind result
Labels and relations
crosslink issue label <id> bug
crosslink issue unlabel <id> bug
crosslink issue block <id> <blocker-id>
crosslink issue unblock <id> <blocker-id>
crosslink issue blocked
crosslink issue ready
crosslink issue relate <id1> <id2>
crosslink issue related <id>
Interventions
For recording when you had to deviate from the planned approach:
crosslink issue intervene <id> "description" --trigger <type> --context "what you were doing"
Sessions
crosslink session start
crosslink session work <id>
crosslink session status
crosslink session last-handoff
crosslink session action "did X"
crosslink session end --notes "context for next session"
Always end with --notes. The next session reads them via session start — terse notes there save real reorientation time.
Locks
Crosslink uses optimistic locking on issues so multiple agents don't collide.
crosslink locks list
crosslink locks check <id>
crosslink locks claim <id>
crosslink locks release <id>
crosslink locks steal <id>
crosslink quick and crosslink session work auto-claim. crosslink issue close releases.
Time tracking
crosslink timer start <id>
crosslink timer stop
crosslink timer show
Knowledge base
Shared markdown pages on the crosslink/knowledge branch:
crosslink knowledge add "page-slug" --body "content"
crosslink knowledge show <slug>
crosslink knowledge list
crosslink knowledge edit <slug> --body "new content"
crosslink knowledge remove <slug>
crosslink knowledge search "query"
crosslink knowledge sync
crosslink knowledge import <path>
Kickoff (agent launcher)
crosslink kickoff run <issue-id>
crosslink kickoff launch
crosslink kickoff status
crosslink kickoff logs <id>
crosslink kickoff stop <id>
crosslink kickoff list
crosslink kickoff cleanup
crosslink kickoff graph
Design-driven workflow:
crosslink kickoff plan <design-doc>
crosslink kickoff show-plan <slug>
crosslink kickoff report <id>
Swarm (multi-agent coordination)
crosslink swarm init <design-doc>
crosslink swarm status
crosslink swarm resume
crosslink swarm list
crosslink swarm archive
crosslink swarm reset
crosslink swarm launch
crosslink swarm gate
crosslink swarm checkpoint
crosslink swarm merge
crosslink swarm plan
crosslink swarm plan-show
crosslink swarm config
crosslink swarm estimate
crosslink swarm harvest
crosslink swarm review
crosslink swarm fix
crosslink swarm pipeline
crosslink swarm review-status
crosslink swarm review-continue
Container execution
crosslink container build
crosslink container start <worktree>
crosslink container ps
crosslink container logs <id>
crosslink container stop <id>
crosslink container rm <id>
crosslink container kill <id>
crosslink container shell <id>
crosslink container snapshot <id>
Agent identity and trust
crosslink agent init
crosslink agent status
crosslink agent prompt <session> "message"
crosslink agent bootstrap
crosslink trust approve <fingerprint>
crosslink trust revoke <fingerprint>
crosslink trust list
crosslink trust pending
crosslink trust check <agent>
Design documents
crosslink design "feature description"
crosslink design --issue <id>
crosslink design --gh-issue <num>
crosslink design --continue <slug>
Milestones
crosslink milestone create "v1.0"
crosslink milestone list
crosslink milestone show <id>
crosslink milestone add <milestone-id> <issue-id>
crosslink milestone remove <milestone-id> <issue-id>
crosslink milestone close <id>
crosslink milestone delete <id>
Archive
crosslink archive add <id>
crosslink archive remove <id>
crosslink archive list
crosslink archive older <days>
Configuration
crosslink config
crosslink config --preset team
crosslink config --preset solo
crosslink config show
crosslink config get <key>
crosslink config set <key> <value>
crosslink config list
crosslink config reset
crosslink config diff
Workflow and diagnostics
crosslink workflow diff
crosslink workflow trail <id>
crosslink context measure
crosslink context check
crosslink cpitd scan
crosslink cpitd status
crosslink cpitd clear
Style syncing
crosslink style set <repo-url>
crosslink style sync
crosslink style diff
crosslink style show
crosslink style unset
Infrastructure
crosslink init
crosslink sync
crosslink compact
crosslink prune
crosslink export
crosslink import <file>
crosslink daemon start|stop|status
crosslink migrate to-shared|from-shared|rename-branch
Integrity / troubleshooting
crosslink integrity counters --repair
crosslink integrity hydration --repair
crosslink integrity locks
crosslink integrity schema
crosslink integrity layout
crosslink integrity sign-backfill
UI
crosslink tui
crosslink mc
crosslink serve
Issue ID formats
#42 — hub-synced, positive display IDL3 — local-only (not yet pushed to hub)- Both formats work everywhere:
crosslink show 42, crosslink show L3
Priorities
critical > high > medium > low
Global flags (work on most subcommands)
--quiet / -q — minimal output (for scripting)--json — machine-readable output--log-level <error|warn|info|debug|trace> — diagnostic output level--log-format <text|json> — log format
When meta-work shouldn't go in CHANGELOG
Tag the close with --no-changelog for any of these:
- Skill edits in
~/.claude/
- Settings.json changes
- CHANGELOG cleanup itself
- Documentation-only PRs that don't ship to users
- Issue tracker hygiene (closing audit/tracking issues whose deliverables already shipped)
- Any
chore-labeled work (the auto-routing currently doesn't exempt these)
If the auto-entry already landed, remove it via Edit on CHANGELOG.md directly. Don't open another issue to "fix the CHANGELOG entry" — that just adds another entry. The recursion is real.
