learning_ai_common_plat/dashboards/tracker-web/ROADMAP.md

Tracker Dashboard — Product Roadmap

Living document. Coding agents, developers, PMs, and public contributors can submit items via the public roadmap or the Agent API. Deployed at https://tracker.bytelyst.com · Last updated: 2026-05-25.

---

Legend

Symbol	Meaning
✅	Shipped / complete
🔄	In progress
🔲	Planned — not started
🤖	Agent-targeted feature
🌐	Public-facing feature
🏢	Internal / team feature
⚠️	Known bug / gap
🔗	Depends on another phase item

---

Permissions Matrix

Action	Public (no login)	Auth User	PM / Admin	Agent (API key)
View public roadmap	✅	✅	✅	✅
Submit public idea	✅	✅	✅	✅
Vote on public item	✅	✅	✅	✅
View internal items	❌	✅	✅	✅ (scoped)
Create internal item	❌	✅	✅	✅ (write key)
Edit any item	❌	own only	✅	✅ (write key)
Delete item	❌	❌	✅	❌
Change status	❌	✅	✅	✅ (write key)
Claim item	❌	❌	❌	✅ (write key)
Link PR to item	❌	✅	✅	✅ (write key)
Manage API keys	❌	❌	✅	❌
Configure webhooks	❌	❌	✅	❌
Access analytics	❌	❌	✅	🔲 (read key)

---

Phase 0 — Foundation (Current State) ✅

Everything checked here is already shipped and running at https://tracker.bytelyst.com.

Core Item Management ✅

• Create / read / update / delete tracker items
• Item types: bug · feature · task
• Statuses: open → in_progress → done → closed · wont_fix
• Priority levels: critical · high · medium · low
• Visibility toggle: internal vs public
• Labels (free-text array)
• Assignee field
• Reporter / reportedBy tracking
• Target release field
• Source tracking: internal · user_submitted · auto_detected
• Vote count per item
• Comment count per item

Views ✅

• Dashboard overview with stats (by type / status / priority)
• Items list with search, filter, paginate
• Kanban board (4-column status board)
• Item detail page with inline edits

Public Roadmap ✅

• Public /roadmap page — no auth required
• Board / list view toggle
• Submit idea form (name + email + type + description)
• Email-based voting (stored in localStorage)
• Stats bar (total · votes · in-progress · completed)
• Search and filter by type

Authentication ✅

• Email + password login via platform-service
• MFA (multi-factor authentication)
• Google OAuth
• JWT token refresh
• Product switcher (multi-product support via x-product-id header)

Infrastructure ✅

• Dockerised (standalone Next.js build)
• Caddy reverse proxy with HTTPS (tracker.bytelyst.com)
• PostHog analytics integration
• Vitest unit tests
• Playwright E2E scaffolding
• ESLint + Prettier + Husky git hooks

---

Phase 1 — Production Hardening 🔄

Goal: Make everything that's built actually reliable in production. Target: Sprint ending 2026-06-14

1.1 — Infrastructure Health ⚠️

• Fix valkey (Redis) container health — currently unhealthy; root cause of most downstream container failures; all session/queue-dependent services degrade
• Fix platform-service health check — reports unhealthy due to valkey connectivity; fix after valkey is stable
• Fix tracker-web /health route — must actively probe DB + platform-service reachability, not just return HTTP 200
• Add 8 GB swap space on VM — currently 0 B swap; build spikes cause OOM-kills of running services
• Limit concurrent Gitea CI runner jobs — cap to 1–2 simultaneous next build + tsc jobs; 4-core VM cannot survive 4+ parallel builds
• Ensure restart: unless-stopped on all docker-compose services — several containers don't auto-recover after VM reboot

1.2 — Rate Limiting & Spam Protection 🌐

• Rate-limit POST /public/submit — no throttling today; minimum 10 req/min per IP
• Add Cloudflare Turnstile (or hCaptcha) to public submission form — bot-proof without user friction
• Server-side vote deduplication per email — current dedup is localStorage-only and trivially bypassed
• Validate and sanitise all public inputs server-side — XSS / injection guard on title, description, name, email

1.3 — Test Coverage

• Vitest unit tests ≥ 80 % on src/lib/ — tracker-client.ts, auth-context.tsx, utils.ts
• Playwright E2E: login → create item → transition to done happy path
• Playwright E2E: public roadmap submit + vote flow
• Playwright E2E: Kanban status transitions (update after drag-and-drop ships in Phase 2)
• API contract tests — verify proxy routes match platform-service OpenAPI schema

1.4 — Error Handling & Observability

• Global React error boundary with friendly fallback — no raw stack traces leaked to users
• Structured server-side logging via @bytelyst/logger on all Next.js API routes
• Loki log aggregation — forward Next.js server logs into the already-deployed Loki instance
• Prometheus metrics — expose /metrics; scrape request count, latency p50/p95, error rate
• Grafana alert on health-check failure and error rate > 1 %
• Sentry (or @bytelyst/diagnostics-client) for client-side unhandled React errors

1.5 — Security

• Security headers audit — CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy
• CSRF tokens on all mutating API routes
• API key rotation mechanism — prerequisite for Phase 3 agent keys
• Audit log on every item mutation — { actor, action, field, before, after, timestamp } written to append-only log
• PII scrubbing in logs — emails and names must not appear in plaintext log lines

---

Phase 2 — Rich Item Details (Linear / Jira parity) 🔲

Goal: Items rich enough for developers, PMs, and agents to fully spec, reproduce, and track work without leaving the tool. Target: Sprint ending 2026-07-12

2.1 — Expanded Item Types & Statuses

• New item types: improvement (enhances existing feature) · chore (infra / maintenance / dependency bumps)
• Custom status workflows — products can define extra statuses beyond the default five (e.g., needs_review, blocked, in_qa)
• wont_fix reason field — free-text explanation required when closing as wont_fix
• Reopen flow — explicit "Reopen" action with mandatory comment; audit-logged

2.2 — Rich Text & Markdown

• Markdown description editor — live side-by-side preview, toolbar, keyboard shortcuts (bold, italic, code, link)
• Acceptance criteria checklist — structured - [ ] items inside description; individually checkable by any team member or agent

  ## Acceptance Criteria
  
  - [ ] User can submit form without login
  - [ ] Email confirmation sent within 60 s
  - [ ] Duplicate-email server-side check prevents double vote
  - [ ] Rate limit returns 429 with `Retry-After` header
  

• Steps to reproduce (bug type only) — numbered list; "Copy as markdown" button
• Expected vs Actual behaviour fields (bug type only) — separate text areas shown side-by-side
• Code blocks in descriptions and comments — syntax-highlighted fenced blocks (Shiki)
• @username mention in comments → in-app + email notification to mentioned user
• source: auto_detected UI badge — distinct chip on items filed by CI/agents (fixes B-014)

2.3 — Attachments & Media

• File uploads — screenshots, logs, designs up to 25 MB; stored via @bytelyst/blob service
• Clipboard paste into description — paste screenshot → auto-upload → embed as ![image](url)
• Video embed — paste Loom / YouTube URL → inline player in description
• Attachment list on item detail — filename, size, uploader, uploaded-at, download, delete

2.4 — Relationships & Linking

• Linked items — blocks / is blocked by / relates to / duplicate of with bidirectional display on both items
• Sub-tasks — child items nested under parent; parent shows 3/5 done progress chip
• Milestones — named groupings with a target date; items can be assigned to one milestone
• PR / commit links — attach GitHub or Gitea PR URL; show live PR title + open/merged/closed badge (prerequisite for Phase 3 webhook auto-linking)
• Branch name chip — auto-suggest feat/tracker-{id}-{slug} with one-click copy
• External links — arbitrary URL + label pairs (Notion doc, Figma frame, Confluence page, CI run)

2.5 — Metadata & Custom Fields

• Effort estimate — Fibonacci story points (1 2 3 5 8 13 21) or T-shirt sizes (XS S M L XL); picker on item detail
• Time tracking — log hours per session; show logged vs estimate; per-sprint burndown
• Due date — date picker; overdue items highlighted red in list and Kanban
• Environment — production · staging · dev · all
• Affected version — free-text; displayed as chip; links to changelog
• Fixed in version — auto-populated when item closes within a milestone
• Watchers / stakeholders — subscribe to all item updates without being the assignee
• Custom fields — per-product admin defines field name + type (text, number, date, single-select); stored in metadata map
• Colour-coded labels — each label gets a hex colour; rendered as chips in list, Kanban card, and detail views
• metadata map for agent data — agents write arbitrary KV pairs ({ testRunId, commitSha, ciJobUrl }) without polluting core fields

2.6 — Activity, History & Notifications

• Full activity log per item — every field change, status transition, comment, attachment, PR link recorded with actor + timestamp

  09:14  saravana       status: open → in_progress
  09:22  codex-agent    linked PR #142 (open)
  09:45  codex-agent    checklist: "Email confirmation sent within 60 s" ✅
  10:05  saravana       priority: medium → high
  10:31  codex-agent    PR #142 status: open → merged
  10:31  codex-agent    status: in_progress → done  (reason: PR #142 merged)
  

• Comment reactions — emoji reactions (👍 ✅ 🔥 💡 ❓) on any comment
• Comment edit + delete — authors can edit within 15 min; admins can delete any comment
• Item history diff view — expandable before/after diff for description edits
• Notification preferences — per user, per item: all activity · mentions only · status changes · none
• In-app notification centre — bell icon with unread count; mark-all-read action

2.7 — Real-Time Updates

• Server-Sent Events (SSE) on item detail — status, comments, and activity log refresh live without polling
• Kanban board live updates — card moves and new cards appear in real-time for all active viewers
• Optimistic UI — status/priority changes apply instantly client-side; roll back on server error with toast

2.8 — Views, Filters & Search

• Kanban drag-and-drop — drag cards between status columns; persist to server immediately (fixes B-003)
• Saved filter views — name, save, and pin a filter combination to the sidebar
• Bulk actions — checkbox-select multiple items → bulk status change / assign / label / milestone / delete
• Group by — group list view by assignee · label · milestone · priority · type
• Timeline / Gantt view — items with due dates on a horizontal calendar; milestones as vertical markers
• My items view — quick filter tabs: assigned to me · reported by me · watching · mentioned in
• Global search — Ctrl+K full-text search across title + description for all products (admin); per-product search for members
• Export — CSV and JSON download of any filtered view; includes all metadata and custom fields

---

Phase 3 — Agent & Automation API 🤖

Goal: First-class REST API for coding agents (Claude Code, Codex, Copilot Workspace, custom agents) to consume, update, and create tracker items — closing the loop between AI-assisted development and project management. Target: Sprint ending 2026-07-26 Dependency: Phase 2 acceptance-criteria checklist and PR link fields must ship first.

3.1 — Agent Authentication

• API key management UI (admin) — generate, revoke, rotate keys; set name + role + product scope + optional IP allowlist
• Agent roles: agent-read · agent-write · ci · webhook — minimum necessary permissions per role (see Permissions Matrix)
• Key usage log — last-used timestamp, request count, error count per key
• Rate limits per key — configurable RPM; 429 Too Many Requests with Retry-After header on breach
• Key expiry — optional expiry date; keys auto-revoked on expiry
• API versioning — all agent routes under /api/agent/v1/; breaking changes bump version; old versions supported 6 months with Deprecation + Sunset headers

3.2 — Agent Item Operations

All routes require Authorization: Bearer <agent-key> and X-Product-Id: {productId}.

Pull & Claim

• GET /api/agent/v1/items — list items with filters; cursor-based pagination; since for incremental sync

  GET /api/agent/v1/items?status=open&label=agent-ready&limit=20&cursor=<opaque>&since=2026-05-20T00:00:00Z
  Authorization: Bearer <TRACKER_AGENT_KEY>
  X-Product-Id: chronomind
  
  # 200 Response
  {
    "items": [...],
    "next_cursor": "eyJpZCI6IjEyMyJ9",
    "has_more": true,
    "total": 47
  }
  

• PATCH /api/agent/v1/items/:id/claim — atomically assign to calling agent + transition to in_progress; returns 409 Conflict if already claimed (prevents parallel agent races)

Create & Update

• POST /api/agent/v1/items — create item; source auto-set to auto_detected

  {
    "type": "bug",
    "title": "TypeError: Cannot read properties of null (reading 'avatar')",
    "description": "Reproduced in E2E run #4821 on `main` at commit `abc123`.\n\n```\nTypeError at UserCard.tsx:42\n```",
    "source": "auto_detected",
    "priority": "high",
    "labels": ["ci-failure", "agent-reported", "frontend"],
    "metadata": {
      "testRun": "4821",
      "commitSha": "abc123def456",
      "ciJobUrl": "https://gitea.bytelyst.com/org/repo/actions/runs/4821"
    }
  }
  

• PATCH /api/agent/v1/items/:id/status — update status with mandatory reason and optional evidenceUrl

  {
    "status": "done",
    "reason": "PR #142 merged",
    "evidenceUrl": "https://github.com/org/repo/pull/142"
  }
  

• PATCH /api/agent/v1/items/:id/checklist — check/uncheck acceptance-criteria items by text match 🔗 (requires Phase 2)

  { "item": "Email confirmation sent within 60 s", "checked": true }
  

• POST /api/agent/v1/items/:id/comments — post implementation notes, test results, diffs, error logs

PR Integration

• PATCH /api/agent/v1/items/:id/pr — link or update a PR; callable multiple times as PR status evolves

  {
    "prUrl": "https://github.com/org/repo/pull/142",
    "prNumber": 142,
    "prTitle": "fix: null-check avatar in UserCard",
    "prStatus": "open",
    "branch": "fix/tracker-789-null-avatar",
    "commitSha": "abc123def456",
    "ciStatus": "pending"
  }
  

  prStatus: open · merged · closed · draft
ciStatus: pending · success · failure · cancelled

Context

• GET /api/agent/v1/items/:id/context — full item as LLM-ready markdown: title, description, acceptance criteria, comments, linked PRs, activity log; ideal for agent system-prompt injection

  # Tracker #789: TypeError in UserCard on null avatar
  
  **Status:** open **Priority:** high **Assignee:** unassigned
  
  ## Description
  
  ...
  
  ## Acceptance Criteria
  
  - [ ] Null-check avatar before rendering
  - [ ] Unit test covers null case
  - [ ] No snapshot regression
  
  ## Recent Activity
  
  2026-05-25 09:14 saravana: opened
  

3.3 — Inbound Webhooks

• GitHub webhook receiver — POST /api/webhooks/github
  • PR opened → auto-link to item if branch matches tracker-{id} or feat/tracker-{id}-*; status → in_progress
  • PR merged → status → done; post commit SHA + PR URL as comment
  • PR closed without merge → post closure comment; status unchanged
  • CI check failed → post failure summary + job URL as comment on linked item
  • CI check passed → update ciStatus on linked PR
• Gitea webhook receiver — POST /api/webhooks/gitea (identical event handling, targeting localhost:3300)
• HMAC-SHA256 signature verification — reject unsigned inbound webhooks
• Webhook event log — last 100 inbound events per product; each replayable via UI

3.4 — Outbound Webhooks

• Outbound webhook configuration UI — register target URLs per product; choose subscribed event types
• Events emitted: item.created · item.updated · item.status_changed · comment.added · pr.linked · pr.status_changed · checklist.checked · item.closed
• Retry with exponential backoff — up to 5 retries over 24 h on non-2xx; final failure fires webhook.delivery_failed alert
• Delivery log UI — timestamp · target URL · event type · HTTP status · duration · response body snippet
• Built-in Slack integration — send formatted item cards to a Slack channel; configurable per product + per event type

3.5 — Agent SDK & Tooling

• @bytelyst/tracker-client npm package — typed Node.js client; auto-handles pagination cursor, retry, rate-limit backoff

  import { TrackerClient } from '@bytelyst/tracker-client';
  
  const tracker = new TrackerClient({
    apiKey: process.env.TRACKER_AGENT_KEY,
    productId: 'chronomind',
  });
  
  for await (const item of tracker.items.stream({ status: 'open', label: 'agent-ready' })) {
    await tracker.items.claim(item.id);
    // ... implement fix ...
    await tracker.items.linkPr(item.id, { prUrl, prNumber, prTitle, prStatus: 'open' });
  }
  

• Claude Code hook template — ready-made PostToolUse hook that auto-files a tracker bug when tests fail; add to .claude/settings.json

• CI integration guide — GitHub Actions + Gitea Actions example steps to file bugs and update PR status

• OpenAPI spec — auto-generated; browsable at /api-docs

3.6 — AI-Assisted Triage

• Auto-classify new submissions — LLM call on every new item suggests type, priority, labels; shown as "AI suggestions" (human confirms or dismisses; never auto-applied)
• Duplicate detection — embedding similarity vs open items; surface "Possible duplicate of #42" if cosine similarity > 0.85
• Auto-assign rules — configurable routing table: label frontend → frontend-agent; label ci-failure → ci-agent; editable by PM in settings
• Sentiment analysis on public submissions — flag angry/urgent submissions for fast-lane triage queue
• Auto-generate acceptance criteria 🔗 (requires Phase 2 checklist) — LLM suggests starter - [ ] checklist for feature and improvement items; editable before saving

---

Phase 4 — Multi-Source Intake 🌐🏢

Goal: Every stakeholder — public users, internal team, developers, and agents — has a frictionless native path to submit and track items. Target: Sprint ending 2026-08-09

4.1 — Public Submission Enhancements 🌐

• Optional public account — lightweight sign-up (email only) to track your own submissions; no access to internal items
• Submission status page — /submissions/{token} shows item status without login; token emailed on submit
• Email notifications to submitters — "Your idea moved to In Progress" / "Shipped in v2.3! Thanks for the report."
• Public changelog — /changelog auto-generated from done + visibility: public items grouped by milestone
• Vote cap — max 5 votes per email per product; server-enforced (proper fix for B-004)

4.2 — Internal Team Intake 🏢

• Quick-capture widget — floating "Report issue" button embeddable in any internal dashboard via <script> tag; pre-fills productId and reportedBy
• Browser extension — one-click bug capture from any web page; auto-fills URL, captures screenshot, lets user annotate before submitting
• Email-to-tracker — send to tracker+{productId}@bytelyst.com → creates item; reply threading = item comments
• Slack /tracker slash command — /tracker bug This crashes → creates item and replies with link; /tracker list shows your open items
• Microsoft Teams bot — equivalent to Slack bot for Teams-based teams

4.3 — Developer Intake 🏢

• GitHub Issues bidirectional sync — link a GitHub repo; new issues → tracker items; tracker status changes → GitHub labels and vice versa
• Gitea Issues bidirectional sync — same as GitHub, targeting localhost:3300
• npx @bytelyst/tracker CLI — tracker create --type bug --title "...", tracker list --status open, tracker show 789
• VS Code extension — sidebar panel: view assigned items, change status, file bugs without leaving the editor
• CI test-failure auto-item — Vitest/Jest/Playwright reporter plugin that auto-files bug items on failure with full test output attached
• Import wizard — CSV import from Jira, Linear, or GitHub Issues with field-mapping UI; avoids cold-start problem when migrating

4.4 — PM / Stakeholder Features 🏢

• Roadmap presentation mode — clean full-screen view grouped by milestone; shareable read-only link (no login required)
• Sprint planning board — drag items into sprint buckets; velocity chart (items closed per sprint)
• Release notes generator — from done + public items in a milestone → draft release notes markdown; one-click copy
• Weekly digest email — per-product: N opened, N closed, N blocked, top-voted ideas; sent to all watchers every Monday

---

Phase 5 — Analytics & Intelligence 🔲

Target: Sprint ending 2026-08-30

5.1 — Item Analytics

• Cycle time tracking — time in each status per item; p50/p95/p99 across all items and per-label
• Throughput chart — items closed per week/sprint over a rolling 12-week window
• Bug burn-down — open bug count over time; configurable target line for zero-bug releases
• Feature request leaderboard — ranked by vote count; trending (vote velocity this week vs all-time)
• Agent productivity dashboard — items claimed/closed/abandoned per agent; PR merge rate; average cycle time vs human baseline

5.2 — SLA & Alerting

• SLA rules — configurable per priority: critical > 4 h, high > 24 h, medium > 7 days before auto-alert
• SLA breach alert — notify assignee + PM via in-app, email, and outbound webhook
• Stale item detector — no activity for N days → auto-ping assignee; N configurable per product
• Blocked item escalation — item in blocked status > 3 days → escalate to team lead

5.3 — Reporting

• CSV / PDF export of any filtered view, including all metadata and custom fields
• Scheduled email reports — configurable frequency (daily/weekly/monthly) and recipients per product
• Embeddable public status widget — <script> snippet; shows open bug count + last-updated on any external page
• Data retention policy UI — archive items older than N months; archived items searchable but excluded from live views

---

Phase 6 — Mobile & Accessibility 🔲

Target: Sprint ending 2026-09-13

6.1 — Responsive & Mobile

• Fully responsive layout — all views fully usable on < 768 px (phone); no horizontal scroll, no hidden controls
• Touch-friendly Kanban — drag-and-drop via touch events 🔗 (requires Phase 2 Kanban)
• PWA — installable from browser; offline read-only access to cached item list
• Web push notifications — opt-in browser push for item updates / mentions / SLA breaches

6.2 — Accessibility

• WCAG 2.1 AA compliance audit — full keyboard navigation, correct ARIA roles, colour contrast ≥ 4.5 : 1
• Screen reader tested — VoiceOver (Safari/macOS) + NVDA (Chrome/Windows) on all main flows
• Focus management — modal / sheet close returns focus to trigger; no focus traps
• Reduced motion — all animations respect prefers-reduced-motion
• Dark mode — system-preference aware; manual toggle in user settings

6.3 — Native Apps (Stretch)

• React Native wrapper — iOS + Android with push notifications and offline queue

---

Known Bugs & Gaps ⚠️

Confirmed issues ordered by severity. File new bugs via the public roadmap.

ID	Severity	Description	Affects	Phase
B-001	🔴 Critical	valkey (Redis) container unhealthy — root cause of most downstream failures	All services	1.1
B-002	🔴 Critical	platform-service container unhealthy — caused by B-001	All apps	1.1
B-003	🟠 High	Kanban has no drag-and-drop — status changes via buttons only	Board view	2.8
B-004	🟠 High	Vote deduplication is localStorage-only — server has no per-email enforcement	Roadmap	4.1
B-005	🟠 High	No rate limiting on POST /public/submit — open to bot spam	Roadmap	1.2
B-006	🟡 Medium	Description is plain text — no markdown rendering in detail view	Item detail	2.2
B-007	🟡 Medium	Comment edit/delete not implemented — all comments are permanent	Comments	2.6
B-008	🟡 Medium	No @mention support in comments — no notifications triggered	Comments	2.6
B-009	🟡 Medium	/health route returns 200 without checking dependencies	Infra	1.1
B-010	🟡 Medium	No audit log — no record of field changes with actor + timestamp	Item detail	1.5
B-011	🟡 Medium	No real-time updates — item detail requires manual refresh for new activity	Item detail	2.7
B-012	🟢 Low	Kanban scroll position lost on page refresh	Board view	2.8
B-013	🟢 Low	Product switcher selection lost on hard refresh	Nav	2.8
B-014	🟢 Low	source: auto_detected items have no UI badge to distinguish them	Items list	2.2
B-015	🟢 Low	Item detail has no loading skeleton — blank flash before data loads	Item detail	2.2
B-016	🟢 Low	Public roadmap stats don't refresh after submitting a new idea	Roadmap	4.1
B-017	🟢 Low	No improvement or chore item types — everything shoehorned into bug/feature/task	Item create	2.1
B-018	🟢 Low	No global search across items — only per-page search bar	Items list	2.8

---

Submission Guide — For All Audiences

🌐 Public Users

Visit https://tracker.bytelyst.com/roadmap → click "Submit an idea". No account required — just name + email. You can also upvote items you care about. After submitting you receive a link to track your item's status without logging in.

🏢 Company Team / PMs / Developers

Log in at https://tracker.bytelyst.com/login with your ByteLyst credentials. Go to Dashboard → Items → Create. Set visibility: internal to keep an item off the public roadmap. Use labels to route to the right agent or team.

🤖 Coding Agents (REST API)

Agent API keys are managed by an admin at /dashboard/settings/api-keys (ships Phase 3). Until then, agents use a standard JWT token.

### 1. Pull items labelled for agent work (cursor-paginated, incremental via `since`)
GET /api/agent/v1/items?status=open&label=agent-ready&limit=10&since=2026-05-20T00:00:00Z
Authorization: Bearer <TRACKER_AGENT_KEY>
X-Product-Id: chronomind

### 2. Claim one atomically (prevents another agent racing on the same item)
PATCH /api/agent/v1/items/{id}/claim
Authorization: Bearer <TRACKER_AGENT_KEY>

### 3. Open a PR → link it
PATCH /api/agent/v1/items/{id}/pr
Content-Type: application/json
Authorization: Bearer <TRACKER_AGENT_KEY>

{
  "prUrl": "https://github.com/org/repo/pull/42",
  "prNumber": 42,
  "prTitle": "fix: null-check avatar in UserCard",
  "prStatus": "open",
  "branch": "fix/tracker-{id}-null-avatar",
  "commitSha": "abc123def456",
  "ciStatus": "pending"
}

### 4. Check off an acceptance criterion
PATCH /api/agent/v1/items/{id}/checklist
Content-Type: application/json
Authorization: Bearer <TRACKER_AGENT_KEY>

{ "item": "Null-check avatar before rendering", "checked": true }

### 5. Post implementation notes as a comment
POST /api/agent/v1/items/{id}/comments
Content-Type: application/json
Authorization: Bearer <TRACKER_AGENT_KEY>

{ "body": "Fixed in `UserCard.tsx:42` by adding `avatar ?? defaultAvatar`. Unit test added in `UserCard.null-avatar.test.tsx`." }

### 6. Mark done when PR merges
PATCH /api/agent/v1/items/{id}/status
Content-Type: application/json
Authorization: Bearer <TRACKER_AGENT_KEY>

{ "status": "done", "reason": "PR #42 merged to main" }

Full OpenAPI spec → https://tracker.bytelyst.com/api-docs (ships Phase 3)

---

Release Schedule

Phase	Target Date	Theme
Phase 0	✅ Shipped	Foundation
Phase 1	2026-06-14	Production hardening
Phase 2	2026-07-12	Rich item details (Linear/Jira parity)
Phase 3	2026-07-26	Agent & automation API
Phase 4	2026-08-09	Multi-source intake
Phase 5	2026-08-30	Analytics & intelligence
Phase 6	2026-09-13	Mobile & accessibility

---

Contributing

1. File an item via the public roadmap or the dashboard
2. Upvote items you care about — priority is vote-weighted
3. Comment with context, edge cases, or design notes
4. Open a PR — branch as feat/tracker-{id}-{slug} so the inbound webhook auto-links it (Phase 3)

---

Maintained by the ByteLyst platform team · Questions → platform@bytelyst.com