How to manage issues day to day

This guide assumes that you initialized tisket. See Getting Started if you have not.

Projects

A project is a subdirectory under the tisket directory. Each project holds a project.yml file with at least a name field. Every repo starts with a default project.

To create a new project:

tisket project create backend

To list every project:

tisket project list

Creating issues

To create a simple issue in the default project:

tisket issue create "Fix the widget"

To place it in a specific project:

tisket issue create "Fix the widget" -p backend

Every issue gets a 4-character short ID prefix before the slug of the title. The prefix is random lowercase alphanumeric text, such as ab12. The full ID for the example above is something like ab12-fix-the-widget. Tisket writes the file to .tisket/backend/ab12-fix-the-widget.md.

Metadata flags

You can set every metadata field when you create the issue:

tisket issue create "Fix the widget" \
  --priority 2 \
  -a cjohnhanson \
  -l "bug,urgent" \
  --due 2026-04-01 \
  -d "x9f2-other-issue" \
  -s discovery \
  -b "Detailed description of the problem"

Flag reference:

Use --body or --body-file, but not both.

The short ID system

Every issue ID has the form {prefix}-{slug}, such as ab12-fix-the-widget. The 4-character prefix is unique across every project and every closed issue.

Tisket accepts three forms when you reference an issue:

1. Full ID — ab12-fix-the-widget (an exact match)
2. Short prefix — ab12 (4 lowercase alphanumeric characters; tisket scans every project)
3. Slug — fix-the-widget (tisket matches the slug part of each prefixed filename)

Short prefix resolution returns an error if more than one issue has the same prefix. This is unlikely, because tisket generates a unique prefix. Slug resolution returns an error if more than one issue has the same slug.

Every command that accepts an issue ID uses this resolution: show, edit, close, reopen, move, path, and scratch.

Statuses and lifecycle

Tisket has a fixed set of statuses:

done and cancelled are terminal. Closing an issue moves it to one of them. discovery, todo, in_progress, blocked, and paused are active statuses.

Changing status

To update an issue’s status:

tisket issue edit ab12 -s in_progress

Closing an issue

Closing moves the file from the project directory into a .closed/ subdirectory. It sets the status to done, or to the terminal status you give. It also updates the timestamp.

tisket issue close ab12

To close as cancelled instead:

tisket issue close ab12 -s cancelled

Reopening an issue

Reopening moves the file back out of .closed/. It sets the status to todo, or to the status you give. It also removes the .closed/ directory if the directory is now empty.

tisket issue reopen ab12
tisket issue reopen ab12 -s discovery

Viewing issues

To show one issue with all of its metadata:

tisket issue show ab12

The command prints the ID, the project, the title, and the status. It then prints each optional field that has a value: the priority, the assignee, the due date, the labels, and the dependencies. It prints the body last. If other branches hold divergent versions of the issue, the command lists those branches and the fields that differ.

To extract one field value, which is useful in a script:

tisket issue show ab12 --field status
tisket issue show ab12 --field assignee

Valid field names: title, status, priority, assignee, due_date, labels, depends_on, children, body, scratch, id, project.

To get the file path of an issue:

tisket issue path ab12

JSON output

Both show and list support --format json:

tisket issue show ab12 --format json
tisket issue list --format json

Listing and filtering issues

To list every open issue in every project:

tisket issue list

To filter by project, status, or label:

tisket issue list -p backend
tisket issue list -s todo
tisket issue list --label bug

To list the closed issues instead of the open ones:

tisket issue list --closed

Selector filtering

For more precise filtering, use --where with namespace:value syntax. You can repeat the flag. An issue must match every selector.

tisket issue list --where label:bug --where status:todo
tisket issue list --where project:backend

label, status, and project read the fields of those names. Any other namespace names a tag, and the value is compared against that tag’s value.

Editing issues

To change the metadata on an existing issue:

tisket issue edit ab12 --title "New title"
tisket issue edit ab12 --priority 1
tisket issue edit ab12 -a someone
tisket issue edit ab12 --due 2026-05-01

Labels

You can replace every label, add one label, or remove one label:

tisket issue edit ab12 -l "bug,p1"          # replace every label
tisket issue edit ab12 --add-label urgent    # add one label
tisket issue edit ab12 --remove-label p1     # remove one label

Dependencies

To replace the dependency list:

tisket issue edit ab12 -d "x9f2,b3k1"

Body

To replace the body entirely:

tisket issue edit ab12 --body "New body content"

To append to the existing body:

tisket issue edit ab12 --append "Additional notes from investigation"

Tisket does not edit a closed issue. Reopen the issue first.

Moving issues between projects

To move an issue from its current project to another:

tisket issue move ab12 --project backend

This works for an open issue and for a closed issue. Tisket moves the file to the target project directory. For a closed issue, it moves the file to the .closed/ subdirectory of that project. A move to the same project changes nothing.

Scratch notes

Each issue file can hold a ## Scratch Notes section below the body. The scratch notes are working memory. Use them for context, partial findings, links, and anything else an agent or a person needs across sessions.

To read the scratch notes:

tisket scratch ab12
tisket scratch ab12 read

To replace the scratch notes:

tisket scratch ab12 write "Current findings: the bug is in the parser"

To append to the scratch notes:

tisket scratch ab12 append "Also checked the lexer — not the issue"

To clear the scratch notes:

tisket scratch ab12 clear

Searching issues

Search reads the frontmatter fields and never the body. The pattern is a regular expression, matched against the title, the status, the priority, the assignee, the due date, the labels, and the dependencies.

tisket search "parser"
tisket search "fix.*widget"

To search one project only:

tisket search "parser" -p backend

The search results show the issue ID, the status, the project, the title, and the fields that matched.

Git-aware divergence detection

When tisket lists or shows an issue, it reads the issue file from every other branch in the repository. It compares each version to the version on the current branch. Tisket marks the issue as divergent if any compared field differs. The compared fields are title, status, priority, assignee, due date, labels, and dependencies, plus whether a body and scratch notes are present.

In the list output, a divergent issue shows an asterisk after the status:

ab12  in_progress*  Fix the widget

In the show output, tisket lists each divergent branch with the fields that differ:

  Other branches:
    feature/xyz   status, priority
    origin/main

A branch with no listed fields differs in none of the compared fields. Its body text can still differ, because the comparison reads only whether a body is present.

Issue files are committed to git, so two worktrees or two branches can change the same issue. Divergence tells you that the view on the current branch differs from the view on another branch.

Epics

An epic is an issue that lists its children in the children: field. Tisket has no separate epic type, and a child can live in another tracker.

tisket issue create "epic: context lifecycle management" \
  -l epic,architecture \
  -s discovery \
  --children "8skh,irx9"

Add a child later with the same field:

tisket issue edit nbuj --children "8skh,irx9,f4k2"

tisket issue show prints the children with the status of each one and the count that is done, so you maintain no list by hand:

  Children:
    done      8skh-context-lifecycle-design   Context lifecycle design
    todo      irx9-skills-go-unused           Skills go unused
    1/2 done

A child in another tracker carries its alias: children: [a:x9k2, b:m4p1]. The alias must be declared in stores.yml. An entry whose text before the first colon is not a declared alias stays local. An entry such as x: y keeps the meaning it always had.

tisket check reports a child in another tracker that names no issue there, and a cycle in the children of an epic. It does not report a missing child in the same tracker.

Containment is not blocking. children says what an epic contains; depends_on says what an issue waits for. Use depends_on when work cannot start until another issue is closed.

Preparing an issue for agent pickup

An agent harness picks up a tisket issue to start work on it. Tisket supplies the vocabulary the gate reads; the harness applies the gate and runs the session steps. A typical pickup runs these steps:

1. Verify that the current branch is the main branch.
2. Find the issue and check that its status is pickable (todo, blocked, or paused).
3. Check that every depends_on issue is closed.
4. Set the issue status to in_progress.
5. Add a ## Scratch Notes section to the issue file if it has none.
6. Commit the status change on the main branch.
7. Create a git worktree for the issue.

A pickup accepts only an issue with a pickable status. It rejects an issue in discovery or in_progress, and an issue with an open dependency. The harness enforces those rules. Tisket accepts any valid status on issue edit, and it refuses only an edit to a closed issue.

To make an issue ready for pickup, set its status to todo:

tisket issue edit ab12 -s todo

To block pickup until another issue is closed, add a dependency:

tisket issue edit ab12 -d "x9f2"