ROADMAP.md

WritBase Roadmap

Implementation status organized by technical domain. See docs/concepts.md for architecture details.

Database

M1: Core schema

• Enum types: priority, status, actor_type, source, event_category, target_type, agent_role
• projects table
• departments table
• tasks table with version integer DEFAULT 1 (optimistic concurrency)
• event_log table — unified, append-only
• agent_keys table with role, key_prefix, SHA-256 key_hash
• agent_permissions table
• app_settings table with require_human_approval_for_agent_keys
• rate_limits table for Postgres-based per-key rate limiting

M2: Constraints, indexes, grants

• Foreign keys, NOT NULL, CHECK, UNIQUE constraints across all tables
• Check constraints: role in ('worker','manager'), enums match allowed values
• Index: tasks(project_id, department_id, status)
• Index: tasks(project_id, created_at, id) — compound cursor pagination
• Index: event_log(target_id, event_category)
• Index: agent_permissions(agent_key_id)
• REVOKE UPDATE, DELETE ON event_log FROM anon, authenticated
• GRANT INSERT ON event_log to service_role only

M3: RLS policies

• Workspace-scoped RLS on all data tables (M23)
• event_log: RLS read-only for authenticated users, INSERT via service_role only
• No RLS on agent path — Edge Functions use service_role and handle auth in code

Auth

M4: Human auth

• Supabase Auth configuration
• Signup with auto-provisioned workspace (Postgres trigger on auth.users INSERT)
• Session management with Supabase client SDK

M5: Agent key system

• Key generation: compound format wb_<key_id>_<secret>
• SHA-256 hashing of secret portion on creation
• Store key_prefix (first 8 chars of secret) for display
• Key lookup: parse compound key, extract key_id, single DB lookup
• Timing-safe hash verification
• Role resolution (worker/manager)
• Permission loading: join agent_keys + agent_permissions
• Update last_used_at on successful auth
• Reject inactive keys

MCP Server

M6: Transport layer

• Streamable HTTP endpoint with @modelcontextprotocol/sdk + Hono
• Authentication middleware
• Auth on all MCP lifecycle methods: initialize, tools/list, tools/call
• Rate limit middleware
• CORS: allow missing Origin (CLI agents), validate browser Origin
• Request logging: key ID, tool name, auth result, latency

M7: Worker tools — info + get_tasks

• info: agent name, role, scopes, special prompt, valid projects/depts
• get_tasks: project required, department/status/priority filters
• Cursor-based pagination with compound cursor
• Max limit 50 enforced server-side
• updated_after filter for change polling
• Scope enforcement
• Tool annotations

M8: Worker tools — add_task + update_task

• add_task: scope validation, reject archived project/dept, event_log
• update_task: atomic optimistic concurrency (WHERE version = $2)
• update_task: version_conflict error with current_version
• Cross-scope department move authorization
• Field-level provenance in event_log

M9: Dynamic schema per role

• Tool visibility: workers see 4 tools, managers see 11 in tools/list
• Description-based hints: valid projects/depts in tool description
• Dynamic enum injection for project/department params
• Default value injection for single-project agents
• Per-request schema generation

M10: Manager tools

• manage_agent_keys: list/create/update/deactivate/rotate
• manage_agent_permissions: grant/revoke with per-row subset constraint
• get_provenance: filtered event_log, cursor pagination
• manage_projects: create/rename/archive
• manage_departments: create/rename/archive
• All manager actions logged in event_log

M11: Human API endpoints

• Project CRUD: GET/POST/PATCH /api/projects
• Department CRUD: GET/POST/PATCH /api/departments
• Task CRUD: GET/POST/PATCH /api/tasks
• Task history: GET /api/tasks/:id/history
• Agent keys: GET/POST/PATCH /api/agent-keys, POST /api/agent-keys/:id/rotate
• Event log: GET /api/event-log

Business Logic

M12: Validation and error handling

• Task validation: required fields, enum checks, min lengths
• Permission validation: active key, matching scope, archived entity checks
• Department move validation
• Version conflict detection
• Structured error responses with recovery guidance
• Per-field validation error details
• Postgres-based rate limiting per agent key

M13: Manager permission enforcement

• Per-row subset constraint
• No self-modification check
• Workers-only check (cannot create manager keys)
• Optional human approval queue for agent-created keys

Frontend

M14: App shell

• Next.js 16 with Supabase Auth
• Left sidebar: project selector, department selector
• Project management (create, rename, archive)
• Department management (create, rename, archive)

M15: Tasks table

• Task list with all columns
• Filter by project and department
• Sort by created date, due date, priority, status
• Create/edit task modal
• Version conflict error display

M16: Agent keys admin

• Key list: prefix, role badge, active status, last used
• Create key flow with one-time secret display
• Special prompt editor
• Activate/deactivate toggle
• Permission rows editor

M17: Provenance UI

• Task detail side panel
• History timeline from event_log
• Actor, timestamp, field, old → new values

M18: Hardening

• Request ID generation and propagation
• Error and loading states in UI
• Archived entity behavior
• Edge-case validation

Inter-Agent Task Exchange

M19: Cross-department task assignment

• can_assign permission
• assign_task MCP tool (creates task in department where caller has can_assign)
• Provenance tracking via event_log actor fields

M20: Webhook notifications

• webhook_subscriptions table
• subscribe MCP tool (manager only)
• Webhook delivery: pg_net trigger → fan out with HMAC-SHA256

M21: Agent discovery

• agent_capabilities table (skills[], description)
• discover_agents MCP tool (manager only, filterable by skill)

M22: A2A protocol endpoints (deferred)

• A2A-compliant task lifecycle endpoints (pending A2A spec v1.0)
• Agent Cards at .well-known/agent.json

Workspace Architecture

M23: Multi-tenant workspace model

• workspaces + workspace_members tables
• workspace_id NOT NULL on all data tables
• get_user_workspace_ids() RLS helper
• Workspace-scoped RLS policies
• Auto-provisioning on signup (handle_new_user() trigger)
• ensure_user_workspace() idempotent fallback
• Cross-workspace integrity triggers
• WorkspaceProvider React context
• All MCP tools filter by ctx.workspaceId

M24: Multi-member workspaces (future)

• Invite flow
• Role-based workspace permissions (owner, admin, member)
• Workspace member management UI