> ## Documentation Index
> Fetch the complete documentation index at: https://podium.do/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and track issue work

> Describe work, claim it, record progress, add dependencies, and close it.

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`:

```bash theme={"system"}
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.

<Frame caption="A Podium web issue inside a decorative macOS-style frame.">
  <img src="https://mintcdn.com/podium-420ab911/2s5JLbtgPIHQF79c/images/issue-detail.png?fit=max&auto=format&n=2s5JLbtgPIHQF79c&q=85&s=f109044e4b29f7906ea93d6ada678e47" alt="Podium web inside a decorative macOS-style frame, showing a backlog issue with its description, status, session controls, and activity." width="1230" height="715" data-path="images/issue-detail.png" />
</Frame>

## Start or claim work

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

```bash theme={"system"}
podium issue start your_issue_ref --agent codex
```

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

```bash theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
podium issue todo your_issue_ref --done 1
```

## Record dependencies

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

```bash theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
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.