Randall Stillwell 778fe1d321 plans: scaffold daily-driver-finish, saas-hardening, agent-coordination

Three new plan trees that fill in the gaps surfaced during repo review.
Together they map out what remains between the current scaffold-with-stubs
state and a daily-usable, multitenant, agent-coordinated app.

* Plan-daily-driver-finish (P0): turn stubs into real data. Five tasks
  covering the lint/shared-types breakage, hardcoded dashboard mocks,
  AI-page setTimeout placeholder, post-signin landing decision, and a
  cross-browser collab smoke test against the deployed Hocuspocus
  instance.

* Plan-multitenant-saas-hardening (P1): everything multitenant needs
  beyond what Plan-multitenant-cursor-sync already covers. Invites and
  role management, soft-delete + append-only audit log, rate limits on
  the auth + mutation hot paths, and a Vitest + GitHub Actions test
  foundation so PRs can't ship red.

* Plan-agent-coordination (P2): the layer that makes a Task-*.md
  runnable, not just readable. Adds workflow_prompt with task -> epic
  -> plan inheritance, an agent_runs table for auditable sessions, and
  two new MCP tools (claim_task / complete_task) that replace the
  freeform update_object composition agents do today. Includes an
  intentionally-deferred Epic-optional-orchestrator that captures the
  Symphony-shaped runner as a decision point rather than an immediate
  build.

Each task is bead-scale (one focused Cursor session) with explicit
in-scope, out-of-scope, and anti-goal sections so a future agent can
pick up a single Task-*.md and start without scrollback context.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-01 23:52:22 -05:00

3.4 KiB

Raw Blame History

kind	slug	title	plan_slug	epic_slug	status	priority	tenant_id	owner	cursor_todo_id	updated_at
task	mcp-claim-task-tool	MCP claim_task tool — open an agent_runs row and return the prompt	agent-coordination	mcp-claim-complete	ready	P2	global	unassigned	null	2026-06-01

Task summary

A new MCP tool claim_task that an agent calls at session start. It flips the backlog item to in_progress, opens an agent_runs row, and returns the effective workflow prompt + run id.

Description

Contract

Input zod schema:

{
  workspace: string,           // slug or UUID, resolved via resolveWorkspaceHandle
  backlogItemId: string,       // uuid
  actorUserId?: string,        // optional — defaults to null ("system / dev session")
  notes?: string,              // short opener text the agent can attach to the run
}

Behavior:

Resolve the workspace handle (existing helper).
Look up the backlog item; verify it belongs to the resolved workspace. 404 otherwise.
Check for an existing open agent_runs row (finished_at IS NULL) for this backlog_item_id:
- If one exists with the same actor_user_id: return it (idempotent re-claim). Refresh its notes if provided.
- If one exists with a different actor (or actor is null on both sides): return error ALREADY_CLAIMED with the existing actor id (or "anonymous").
Insert a new agent_runs row: workspace_id, backlog_item_id, actor_user_id, started_at=now(), notes.
Update the backlog item: status='in_progress' (only if currently ready or draft; leave alone if already in_progress or done).
Compute and return:
- runId: the new agent_runs.id
- workflowPrompt: result of resolveWorkflowPrompt
- backlogItem: a minimal snapshot (title, body_markdown, status)

Output shape

Use the existing toolOk / toolErr helpers in apps/mcp-server/src/tools/tool-result.ts. Return as structured tool output so the in-session model can pattern-match.

Audit log

Write an audit_log row (action: "task.claimed", target_type: "agent_run", target_id: runId, metadata: { backlog_item_id, prior_status }). Assumes audit_log from Plan-multitenant-saas-hardening has landed; if not, file a follow-up to add audit writes when it does.

Anti-goals

No re-fetching from external systems. The tool only touches Echodo's DB.
No "soft lock" mechanic (timeout-based claims). If a run goes stale, the operator (or complete_task) ends it explicitly.

Subtasks

Create apps/mcp-server/src/tools/claim-task.ts.
Register in apps/mcp-server/src/tools/index.ts.
Implement the 6-step behavior with proper zod validation.
Audit log write (or follow-up task if audit_log isn't in yet).
Verify by running the MCP server locally and calling the tool with a stub agent.

Owner or assignee

Unassigned

Status

ready

Estimation

Acceptance criteria

Successful claim returns runId, workflowPrompt, and backlogItem.
Re-claim by same actor returns the same runId.
Claim by different actor errors with ALREADY_CLAIMED.
Backlog item transitions to in_progress only if previously ready or draft.

Epic: ./Epic-mcp-claim-complete.md
Plan: ../Plan-agent-coordination.md

3.4 KiB Raw Blame History