Pool mechanics

The pool is Ideafy's team collaboration primitive. Instead of assigning cards at creation time, you push them to a shared pool; teammates pull cards they want to work on. Assignment is a side effect of who claims the work, not a gate at the start.

Four operations

All four are exposed as MCP tools and as buttons in the UI. An agent can drive the workflow (push the card it just finished, pull the next one from the queue) and a human can drive it just as well.

Push — sending a card to the pool

When you push:

1. The backend creates (or updates) a row in pool_cards with title, description, solution, tests, opinion, verdict, status, complexity, priority, project name, project color
2. Your local card's poolCardId is set, poolOrigin stays null (only pulled cards get poolOrigin = "pulled")
3. If you specified an assignee, a pool_assigned notification fires to that user
4. The card is now visible to everyone on the team in the pool view

The card doesn't leave your local board. It's duplicated into the pool — your copy stays where it is, so you can keep working on it or keep it as a reference. The pool copy is the authoritative shared state.

By default, pool view on your own board hides pushed cards (they're "elsewhere"), but you can toggle that filter. See Board views.

Pull — taking a card out of the pool

Someone (maybe you) pushes a card to the pool. You see it, decide you want to work on it, and pull it. When you pull:

1. The backend atomically updates the pool row: pulled_by = you, assigned_to = you
2. A new local card is created on your machine with poolOrigin = "pulled" and poolCardId linking back to the pool row
3. The card carries over all content (description, solution, tests, opinion, conversation is NOT synced — see below) plus priority and complexity
4. Your local project matches the pool card by name; task number is assigned fresh from your project

The atomic update means only one person can win a pull. If two team members try to pull the same card simultaneously, the loser gets a 409 and retries, or picks a different card.

Claim / unclaim — lightweight ownership

Sometimes you want to signal intent without pulling (for example, you want to think about a card before starting work). Claim sets assigned_to to yourself. Unclaim clears it. Neither pulls the card into your local board — they only change the pool row's assignment.

Members can claim unassigned cards or their own; they can't take a card already assigned to someone else. Admins can reassign.

The fire-and-forget sync

Every local card mutation on a pool-linked project (title edit, status move, save_plan, save_tests) fires a POST /api/internal/sync-card call to the local Ideafy API, which in turn updates the corresponding pool_cards row in Supabase. This is how the pool view on a teammate's machine — or the web board — stays current.

What syncs:

• title, description, solution_summary, test_scenarios, ai_opinion, ai_verdict
• status, complexity, priority
• project_name, project_color
• task_number, git_branch_name, git_branch_status, processing_type, completed_at

What doesn't sync:

• assigned_to (only claim/reassign changes it)
• Conversations (per-card chat history)
• Local-only fields (dev server PID, worktree path)

Fire-and-forget means: if the call fails (network, Supabase down), the local mutation still succeeds. The next mutation retries. You never see an error for a sync failure.

Pool view

The pool view is a separate board view showing only pool cards. Filters:

• By team: pick one team or "all teams I'm in"
• By status: default active; switch to all to include completed and withdrawn
• Unassigned / assigned to me / everyone: three quick filters for who's on what

The pool view uses the same card modal the main board does, so opening a pool card gives you the full Detail / Opinion / Solution / Tests experience — read-only unless you pull it first.

Paywall

The pool is gated by subscription status:

• Read (pool_list, pool view, my-queue visibility): always allowed
• Write (pool_push, pool_pull, pool_claim): allowed when subscription is active or trial; blocked when expired, past_due, canceled, or grace

So a team whose subscription lapses can still see their pool but can't move cards. This is deliberate — you never lose access to your data, you just can't collaborate until you renew.

See Subscription states.

Prev: Team setup Next: My Queue Up: User guide index