[Epic] Gira-based agent work map roadmap

[StatPan]

Goal

Reposition Agentree from an opencode-only approval UI into a Gira-based AI work map: opencode remains the rich/control-capable harness, while Gira tickets, branches, PRs, and checks become the shared work identity across agent systems.

Product Direction

Agentree should stay opencode-native for v1 control because opencode exposes server/session APIs. The broader product should not try to control every harness immediately. Instead, it should use Gira/GitHub evidence to visualize work across harnesses.

Positioning:

Agentree is an opencode-native AI worker control room, with Gira-backed read-only observability for other worker systems.

Core Model

Use Git work identity as the common layer:

Gira ticket -> branch -> agent run/session -> file changes -> PR -> checks -> finish

A canvas node should evolve from a raw session node into a work node:

Work node:
- repo
- Gira ticket number
- branch
- harness session/run id when available
- linked PR
- status: running / blocked / review / merged / failed

Recommended identity key:

repo + branch + ticket

Harness Strategy

• opencode: rich adapter with control support (prompt, pause/abort, approval, subtask, live messages).
• Codex: read-only adapter later; import branch/repo/run result/final report where available.
• Claude Code: read-only adapter later; import branch/transcript/path/PR where available.
• GitHub Actions: read-only check/run nodes.
• Human/manual work: branch/PR/ticket-only nodes.

Do not block v1 on universal multi-harness control.

Gira Integration Requirements

• Use Gira branch naming and ticket lifecycle conventions where possible.
• Resolve ticket/branch/PR/check state from GitHub evidence through Gira or compatible commands.
• Display Gira ticket metadata on canvas nodes.
• Group canvas by repo, milestone/sprint, running/blocked/review/done, or dependency shape.
• Make opencode branch-aware behavior the first-class v1 path.

Roadmap Slices

1. Design note: define Agentree work-node schema and Gira identity mapping.
2. Add Gira/GitHub read model for repo + branch + ticket + PR status.
3. Bind opencode session nodes to Gira work identity when branch metadata is available.
4. Add canvas grouping/filtering by Gira ticket status and PR/check state.
5. Add read-only import format for non-opencode harnesses.
6. Revisit multi-user/auth only after internal dogfood proves value.

Acceptance Criteria

• A roadmap/design note exists in the repo.
• Follow-up implementation issues are created for the first two slices.
• v1 remains opencode-native and control-capable.
• Non-opencode systems are explicitly read-only until an adapter proves a safe control API.
• Agentree's product language shifts from approval UI to AI worker control room / work observability map.

Out of Scope

• SaaS multi-user backend implementation.
• Full Codex/Claude control APIs.
• Replacing Gira as the ticket/branch/PR source of truth.