Track issues with the issy CLI

Authoring Issues

Issues describe what needs to be done and why. Keep them high-level unless the user provides specific details.

What to Include

Problem/Overview: What's wrong or what's needed (1-2 paragraphs)
Proposed Solution: High-level approach
Acceptance Criteria: Optional - what "done" looks like from user perspective
Verification: Optional but encouraged - how to prove the issue is resolved (see below)
Future Considerations: Optional - related ideas for later
References: Optional - links to related docs, issues, or resources

Verification Guidance

When possible, include verification steps or hints that tell the implementing agent how to prove the issue is resolved. This helps ensure work is actually verified before being marked complete.

Why include verification? Agents should never claim work is done without evidence. If the issue itself describes how to verify, the implementing agent can follow those steps and provide concrete proof (command output, test results, screenshots, etc.).

Verification examples:

Commands to run and expected output (curl, CLI commands, bun test)
UI flows to test (can use agent-browser skill if available for automation)
Database queries to confirm state changes
Specific behavior to observe or confirm
Edge cases to check

Examples:

## Verification
Run `bun test src/auth.test.ts` — all tests should pass, including the new "handles expired tokens" case.

## Verification
Perform the following using the agent-browser skill:

1. Navigate to /settings and toggle dark mode
2. Refresh the page — preference should persist
3. Check localStorage contains `theme: "dark"`

## Verification
After deployment, `curl https://api.example.com/health` should return `{"status": "ok"}` with a 200 response.

Implementation Details

Only include implementation details if the user explicitly provides them. Don't invent:

Task lists or phases
Specific code changes or file paths
Step-by-step instructions
Technical breakdowns

Why? The engineer working on the issue will plan their own implementation. Issues capture the user's intent, not execution plans generated by the agent.

The rule: Capture what the user says. If they provide implementation details, include them. If they don't, keep it high-level.

Issue Sizing

An issue should be completable and verifiable in a single focused session — pick it up, implement it, prove it works, close it. If that's not realistic, split along verification boundaries so each child issue is independently closeable. Don't split when it adds overhead without adding clarity.

Roadmap Ordering

issy maintains a roadmap — a strict, intentional ordering of all open issues. Every open issue has a position in the roadmap, and the ordering is designed to be dependency-aware and chronological. No issue should be blocked by one that follows it.

Rules

When creating an issue: if there are already open issues, you must provide a position flag: --before <id>, --after <id>, --first, or --last.
When reopening an issue: same rule — provide a position flag if there are other open issues.
When updating an issue: optionally provide a position flag to reposition it in the roadmap.
issy next returns the first open issue in roadmap order — the next unit of work.
issy list sorts by roadmap order by default.

Choosing placement

Think about logical dependency when choosing position:

If issue B requires work from issue A to be done first, A must come before B.
Place foundational/infrastructure work early, user-facing features later.
Use --first for urgent work that should be tackled immediately.
Use --last when in doubt — appends to the end of the roadmap.
Use --before <id> or --after <id> for precise placement between existing issues.

CLI Commands

Use the issy CLI. If not installed, install it globally using the project's package manager (e.g., bun install issy --global, pnpm add issy --global, npm install issy --global).

# List issues (roadmap order by default)
issy list                    # Open issues only
issy list --all              # Include closed
issy list --priority high    # Filter: high, medium, low
issy list --scope small      # Filter: small, medium, large
issy list --type bug         # Filter: bug, improvement
issy list --search "keyword" # Fuzzy search
issy list --sort priority    # Sort: roadmap (default), priority, created, updated, id

# Search issues (fuzzy search with typo tolerance)
issy search "dashboard"      # Search open issues
issy search "k8s" --all      # Include closed issues

# Read issue
issy read <id>               # e.g., issy read 0001

# Next issue (first open issue in roadmap order)
issy next

# Create issue (position flag required when open issues exist)
issy create --title "Fix login bug" --type bug --priority high --after 0002
issy create --title "Add dark mode" --type improvement --last --labels "ui, frontend"
issy create --title "Urgent fix" --first
issy create --title "Fix crash" --body "## Problem\n\nApp crashes on startup." --last

# Update issue (position flags to reposition in roadmap)
issy update <id> --priority low
issy update <id> --after 0003
issy update <id> --first
issy update <id> --labels "api, backend"
issy update <id> --body "## Problem\n\nUpdated description of the issue."

# Close issue
issy close <id>

# Reopen issue (position flag required when other open issues exist)
issy reopen <id> --last
issy reopen <id> --after 0004

Hooks

issy supports optional hook files in .issy/ that print context to stdout after successful operations. This is useful for injecting reminders into the agent's context — for example, prompting the agent to update documentation or run post-action checks.

Hook file	Triggered after
`on_create.md`	Creating an issue
`on_update.md`	Updating an issue
`on_close.md`	Closing an issue

Project Structure

Issues are stored in .issy/issues/ as markdown files with YAML frontmatter. The directory structure:

.issy/
  issues/
    0001-fix-login-redirect.md
    0002-add-dark-mode.md
  on_create.md   # Optional: printed after successful create
  on_update.md   # Optional: printed after successful update
  on_close.md    # Optional: printed after successful close

Closing Issues with Learnings

When closing an issue, append a ## Resolution Notes section if anything useful was discovered during implementation:

Alternative approaches considered or rejected
Unexpected gotchas or edge cases found
Decisions made that differ from the original plan
Useful context for future reference

Keep it brief—just capture what someone revisiting this issue would want to know.

Issue Properties

Property	Required	Values
title	Yes	string
body	No	markdown content (the issue body after frontmatter)
priority	Yes	`high`, `medium`, `low`
scope	No	`small`, `medium`, `large`
type	Yes	`bug`, `improvement`
labels	No	comma-separated strings
status	Yes	`open`, `closed`
order	Auto	fractional index key (managed by issy)

After Mutations

If your workflow tracks issues in git, consider committing updates so the tracker stays in sync.

issue-tracking