Create and track issue work

Use issues for work that needs ownership, isolation, dependencies, or a review trail. Keep the human description short and put implementation constraints in the technical brief.

Create an issue

Run the command from the target repository so Podium can infer --repo-path:

podium issue create \
  --title "Cache invalidation tests" \
  --description "Cover stale entries after a repository rename." \
  --brief "Add regression cases without changing the cache contract."

Issue and session titles should use three to five words. An operator-created issue starts in backlog unless you pass --start. A top-level issue filed by an agent through podium issue create starts in proposed.

Podium web inside a decorative macOS-style frame, showing a backlog issue with its description, status, session controls, and activity. — A Podium web issue inside a decorative macOS-style frame.

Start or claim work

Start an issue to create its branch, worktree, and first agent session:

podium issue start your_issue_ref --agent codex

Move the issue to planning while you define the approach, then claim it when implementation starts:

podium issue update --id your_issue_ref --stage planning
podium issue claim your_issue_ref --assignee me

Claiming sets the assignee and moves the issue to in_progress.

Keep the issue readable

State is one current paragraph for the operator. Todos are short, human-facing checkpoints:

podium issue state your_issue_ref \
  --set "Regression reproduced; adding coverage before changing the cache."
podium issue todo your_issue_ref --add "Add the failing rename case"
podium issue todo your_issue_ref --add "Run the cache test suite"

Mark a todo complete by its displayed number:

podium issue todo your_issue_ref --done 1

Record dependencies

Add a blocking edge when one issue cannot finish before another:

podium issue dep-add dependent_issue_ref blocker_issue_ref --type blocks

Use a child issue when the parent cannot ship without that work. Use a separate top-level issue with a discovered-from relationship when the current deliverable can ship without it. If you are moving this session onto the discovered work, create the top-level issue and relationship, then rehome the session in one command:

podium issue attach \
  --spinoff "Cache telemetry cleanup" \
  --confirm-rehome

This command rehomes the current session. To file the work for another agent while staying on the current issue, create it without --start, then add the relationship in this direction:

podium issue create \
  --title "Cache telemetry cleanup" \
  --description "Remove obsolete cache telemetry in a separate change."
podium issue dep-add new_issue_ref current_issue_ref \
  --type discovered-from

Top-level work filed with podium issue create by an agent while staying on the current issue lands in proposed. Do not claim or stage it unless you are assigned to move onto it.

Inspect and close work

Read the final record before closing it:

podium issue show your_issue_ref
podium issue close your_issue_ref --reason done

Close only after the requested outcome is accepted or no longer required. A hibernated session does not close its issue.

Get started

Understand Podium

Work in Podium

Coordinate agents

Operate Podium

Reference

Contribute

Create and track issue work

Create an issue

Start or claim work

Keep the issue readable

Record dependencies

Inspect and close work

​Create an issue

​Start or claim work

​Keep the issue readable

​Record dependencies

​Inspect and close work

Create an issue

Start or claim work

Keep the issue readable

Record dependencies

Inspect and close work