AIF Handoff

AIF Handoff is a task management automation system built as a Turborepo monorepo. It uses a React Kanban UI for task creation, a Hono-based API server, and an agent coordinator that orchestrates tasks via a provider-neutral runtime layer. All data is managed through a centralized layer backed by SQLite using drizzle-orm.

┌─────────────┐     HTTP/WS      ┌─────────────┐
│   Web (UI)  │ ◄──────────────► │  API Server  │
│  React+Vite │                  │    Hono      │
└─────────────┘                  └──────┬───────┘
                                        │
┌───────────────┐   Runtime API   ┌──────┴───────┐
│ Runtime/Provider│ ◄────────────► │    Agent     │
│ adapters        │                │ Coordinator  │
└───────────────┘                └──────┬───────┘
                                          │
                                   ┌──────┴───────┐
                                   │ @aif/runtime
                                   │ (registry + 
                                   │ workflow spec)
                                   └──────┬───────┘
                                        │
                                 ┌──────┴───────┐
                                 │ @aif/data     
                                 │ (DB access)   
                                 └──────┬───────┘
                                        │
                                 ┌──────┴───────┐
                                 │   Database    
                                 │ (drizzle-orm) 
                                 └──────────────┘

AIF Handoff uses two execution modes to manage task state synchronization between agents and the Handoff database. The mode is determined by the presence of specific environment variables injected into the Claude Code subprocess.

Mode 1: Managed by Handoff (HANDOFF_MODE=1)

In this mode, the Handoff Coordinator (TypeScript) is the source of truth. It manages all status transitions and database writes directly.

• Behavior: Skills and agents (like aif-plan or aif-implement) do not call MCP tools. Instead, they operate in a non-interactive mode, skipping prompts and relying on the coordinator to handle status updates.
• Use Case: Automated pipelines where the coordinator drives the workflow (coordinator → planner → implementer → reviewer).

Mode 2: Manual Claude Code session (HANDOFF_TASK_ID set, HANDOFF_MODE not set)

In this mode, a developer runs skills directly in a Claude Code session but wants to sync progress with the Handoff system.

• Behavior: Because there is no coordinator managing the run, skills call MCP tools themselves to update the task status and push plan content.
• Use Case: Manual development where you want your local Claude Code actions to reflect in the Handoff Kanban UI.
• Requirement: The Handoff MCP server must be registered in your .mcp.json configuration.

# Skills read these at load time via dynamic shell substitution
Handoff mode: !`echo ${HANDOFF_MODE:-}`
Handoff task ID: !`echo ${HANDOFF_TASK_ID:-}`
Handoff skip review: !`echo ${HANDOFF_SKIP_REVIEW:-}`

The system uses a provider-neutral discovery mechanism to determine the available 'effort' levels (e.g., low, high, max, ultra) for a selected model.

Mental Model:

1. Discovery: The RuntimeModel.metadata object serves as the shared Data Transfer Object (DTO) for model capabilities.
2. Normalization: Instead of using a fixed allowlist of effort strings, the system normalizes provider-specific strings (like Codex's max or ultra) into a standard format.
3. Authority & Fallback: The UI (specifically RuntimeProfileForm) treats the selected model's metadata as the authoritative source for effort levels. If a model does not provide metadata, the system falls back to the runtime's default effort list. If a model explicitly sets supportsEffort: false, the effort control is hidden.
4. Mapping: Each runtime adapter (Claude, Codex, OpenCode, OpenRouter) is responsible for mapping its native payload into the RuntimeModel.metadata structure.

The system uses a specific fallback order to determine which runtime profile to use based on the current mode (Task, Planning, Review, or Chat).

Task Mode Fallback Order

1. tasks.runtime_profile_id
2. projects.default_task_runtime_profile_id
3. app_settings.default_task_runtime_profile_id
4. Environment fallback

Planning, Review, and Chat

• Planning and Review: Use the same chain as Task mode. If default_plan_runtime_profile_id or default_review_runtime_profile_id are unset, they fall back to the task default at the same scope.
• Chat: Uses default_chat_runtime_profile_id for project or app-level steps.

Scope and Security Rules

• App Defaults: May only point to enabled global profiles (runtime_profiles.project_id = null).
• Project/Task Overrides: Project defaults and task/chat overrides may point to either a same-project profile or a global profile.
• Isolation: The API rejects project-owned profiles that belong to a different project when accessed via a project scope.