Issues and the timeline

fp2’s issue workflow is durable capture, server-authoritative status transitions, a typed timeline, and handoff. It does not yet claim work or compute readiness.

Create an issue

Choose a stable retry ID before the first request:

$
fp2 issue create \
>
  --title "<short-title>" \
>
  --body "<markdown-context-and-acceptance-notes>" \
>
  --priority <urgent|high|medium|low> \
>
  --client-id "<stable-retry-id>" \
>
  --json

The server creates the canonical 32-letter issue ID and derives its short FP-xxxxxxxx display reference.

Retrying the same client_id and identical payload returns the original issue. Reusing that ID with a changed payload is a conflict.

To create a child under an existing issue, add --parent <issue-reference>. One relation carries epics, tasks, and subtasks; see Issue hierarchy for the rules and the close gate.

Inspect work

$
fp2 issue list --json
$
fp2 issue list --parent <issue-reference|none> --json
$
fp2 issue show --id <issue-reference> --json

Short references are project-scoped. If one is ambiguous, list issues and retry with more ID characters. issue show returns the issue, its parent and children, the full timeline, and the server-authored actions that are legal right now.

Record typed timeline events

Every comment is an immutable, attributed timeline event. Type yours:

$
fp2 issue comment \
>
  --id <issue-reference> \
>
  --body "<what-happened-and-why>" \
>
  --kind <progress|decision|blocker|question> \
>
  --client-id "<stable-retry-id>" \
>
  --json

Omitting --kind records an untyped legacy note. The server rejects kinds that do not belong to your principal; post only the options the issue representation advertises. There is no edit and no delete — correct a wrong event with another event.

Questions gate closure

Posting a question withholds the issue’s done transition until the sponsoring human resolves it:

$
fp2 issue comment \
>
  --id <issue-reference> \
>
  --kind answer \
>
  --resolves <question-comment-id> \
>
  --body "<the-answer>" \
>
  --client-id "<stable-retry-id>" \
>
  --json

The human’s representation advertises one answer action per unresolved question with resolves pre-filled; the console renders the same composer inline. Agents cannot answer. Each question accepts exactly one resolving answer. While waiting, keep working other issues and re-read this one to see whether the answer arrived — non-done transitions stay legal.

Transition issue status

Move status with an explicit retry-safe command:

$
fp2 issue transition \
>
  --id <issue-reference> \
>
  --status <todo|in_progress|review|done|cancelled> \
>
  --client-id "<stable-retry-id>" \
>
  --json

The server enforces:

• todo → in_progress | cancelled
• in_progress → todo | review | cancelled
• review → in_progress | done | cancelled
• done and cancelled are terminal
• done additionally requires no open children and no unresolved questions

The CLI reads the current issue status and the server uses it as an atomic compare-and-set precondition. A concurrent update returns issue_transition_conflict; an illegal edge returns invalid_issue_transition; a gated close returns issue_children_open or issue_questions_open with the count and the currently legal actions. Retrying the exact command returns the original attributed transition.

Recover context

At the start of each work session:

$
fp2 context --json

The response includes the resolved project, compact open-issue summaries, an optional active issue with its timeline and actions, and executable suggested operations. It is orientation, not an ownership or readiness signal.