Getting Started
Formic is an AI-powered task manager that autonomously executes coding tasks using AI agents. Each task is processed through a defined workflow — from brief, to plan, to execution — with full concurrency support and self-healing QA.
Board Layout
The kanban board shows tasks across all workflow stages as columns. Use the header buttons to manage settings, switch themes, and access this guide. The floating AI Assistant button (bottom-right) opens a chat panel for brainstorming and task creation.
Adding Your First Task
- Click the + New Task button in any column header (or the board header).
- Enter a short action-oriented title and a description with requirements and context.
- Choose a task type: Standard, Quick, or Goal.
- Set priority: High, Medium, or Low.
Running a Task
- Tasks in Todo must be queued manually — open the task and click Queue.
- Once queued, the system picks it up automatically based on priority and concurrency limits.
- Monitor progress as the task moves through: Queued → Briefing → Planning → Running → Review.
- When a task reaches Review, inspect the changes and move it to Done to approve.
Learn More
Explore the other sections in this guide: Task Types for choosing the right type, Workflow Stages for understanding each column, and Concurrency for how parallel execution works.
Task Types
Formic supports three task types, each with a different workflow suited to the complexity of the work.
Standard
Full workflow: Brief → Plan → Declare → Run. The AI generates a feature spec (README.md), creates an implementation plan (PLAN.md + subtasks.json), declares file leases for concurrency, then executes the implementation.
Best for: new features, refactors, complex bug fixes — any work that benefits from up-front planning.
Quick
Single-step execution — skips briefing and planning, goes directly from Queued to Running. Faster but with no spec or plan document generated.
Best for: typo fixes, small one-liner changes, documentation updates, or tasks where the description is already complete.
Goal
High-level objective — the Architect skill decomposes it into 3–8 child tasks with a dependency graph (DAG). Each child task then runs independently through its own standard or quick workflow.
Best for: large epics, multi-file features, or any goal that is too broad for a single task to implement safely.
Workflow Comparison
Standard
Queued → Briefing → Planning → Declaring → Running → Review
Quick
Queued → Running → Review
Goal
Queued → Architecting → Done (children run separately)
Workflow Stages
Each kanban column represents a workflow stage. Tasks progress left-to-right as they are processed.
| Stage | Description |
|---|
Todo | Task created, not yet queued. Awaits manual queuing. |
Queued | In the priority queue. Will be picked up when a worker slot is available. |
Briefing | AI is generating the feature specification document (README.md). |
Planning | AI is creating PLAN.md and a structured subtasks.json file. |
Declaring | Task declares which files it will modify (exclusive leases) or read (shared leases) for concurrency control. |
Running | AI agent is actively executing the implementation. |
Architecting | Goal task is being decomposed into child tasks by the Architect skill. |
Verifying | Self-healing QA loop is running checks on the completed implementation. |
Review | Implementation complete. Awaiting human inspection and approval. |
Done | Approved and complete. |
Blocked | Task is waiting on one or more dependency tasks to complete first. |
Progressing Tasks
- Tasks in Todo must be queued manually via the task card menu or the task detail view.
- Tasks in Review must be approved by a human — move them to Done after inspecting the changes.
- All other transitions are handled automatically by the Formic server and AI agents.
AI Assistant
The AI Assistant is a chat panel in the bottom-right corner of the board. It is context-aware — it knows your current codebase and board state — and can help with brainstorming, task creation, and answering questions.
Opening and Closing
- Click the floating chat icon (💬) in the bottom-right to open the assistant panel.
- Click it again, or press Escape, to close the panel.
- The panel can be expanded to a larger view for longer conversations.
What the Assistant Can Help With
- Brainstorm features: Describe a problem; the assistant will suggest approaches and trade-offs.
- Create tasks: Ask it to create a task — it will output a structured
task-create block that the server automatically processes into a new task.
- Explore the codebase: Ask questions about architecture, find files, understand patterns.
- Refine requirements: Describe a rough idea and let the assistant turn it into a detailed task description.
Creating Tasks via Chat
The assistant creates tasks by outputting a task-create code block in the chat:
```task-create
{
"title": "Add login page",
"context": "...",
"priority": "medium",
"type": "standard"
}
```
The Formic server detects this block and automatically calls POST /api/tasks to create the task on the board.
Lease-Based Concurrency
Formic can run multiple tasks in parallel. To prevent conflicting writes, it uses a file lease system managed by leaseManager.ts.
File Declaration
During the Declaring stage, a task explicitly declares which files it will touch:
- Exclusive leases — files the task will write to. Only one task can hold an exclusive lease on a file at a time.
- Shared leases — files the task will only read. Multiple tasks can hold shared leases on the same file simultaneously.
Task Yielding
When a task requests an exclusive lease on a file that is already held exclusively by another running task, it yields — it pauses and re-queues itself to wait. Once the conflicting lease is released, the yielded task is picked up again automatically.
Optimistic Concurrency for Shared Files
Shared-lease files use optimistic concurrency: conflicts are detected at merge time via git hash-object collision detection. If two tasks read the same file and both modify it, the second to merge will detect the collision and trigger a resolution step.
Lease Expiration & Watchdog
Leases expire after a configurable duration (default: 5 minutes). A background watchdog process periodically cleans up expired leases to prevent deadlocks if a task crashes without releasing its leases.
Self-Healing QA Loop
After a task finishes execution, Formic optionally runs a Verifier step that checks the implementation before it reaches Review. If verification fails, a Critic automatically creates a fix task.
Verifier Step
- Runs automatically after the Running stage when self-healing is enabled.
- Checks that the implementation meets the acceptance criteria defined in the task's brief.
- The task enters the Verifying stage during this check.
Critic & Auto-Fix
- If verification fails, the Critic skill generates a detailed fix task describing exactly what went wrong and what needs to be corrected.
- The fix task is automatically created with a high priority override and is queued immediately.
- The fix task runs through its own workflow (usually Quick type) and is linked back to the original task.
Result
Tasks that pass verification move to Review as normal. Tasks that fail have their fix tasks run first; once the fix is complete and verified, the original task proceeds to Review.
Goal Tasks & DAG Decomposition
A Goal task represents a high-level objective. Instead of running code directly, a Goal task triggers the Architect skill, which breaks it into 3–8 concrete child tasks with a dependency graph (DAG).
End-to-End Flow
- Create a Goal task with a high-level objective (e.g., "Add user authentication").
- Queue it — it enters the Architecting stage.
- The Architect analyzes the codebase and decomposes the goal into child tasks, each with a
depends_on list.
- Child tasks appear on the board linked via
parentGoalId. Tasks with no dependencies are queued immediately; dependent tasks are Blocked.
- As child tasks complete, their dependents are automatically unblocked and queued.
- The Goal task itself moves to Done once created — its progress is tracked through its children.
DAG Relationships
- Each child task may declare
depends_on: ["sibling-task-id", ...] in the architect output.
- Blocked tasks display a dependency indicator on their card showing which tasks they are waiting for.
- Automatic unblocking runs whenever a task completes — Formic checks all blocked tasks and unblocks those whose dependencies are now all done.
Viewing Child Tasks
Child tasks appear as regular task cards on the board. Open any child task to see its parentGoalId link, which takes you back to the original Goal task.
Keyboard Shortcuts
| Shortcut | Action |
|---|
| Escape | Close the active panel (Help, Settings, AI Assistant, modals) |
| Enter | Send message in the AI Assistant chat input |
| Shift+Enter | Insert newline in the AI Assistant chat input |
Tips
- Only one panel (Help or Settings or AI Assistant) is active at a time — Escape always closes the topmost one.
- Dragging a task card to a different column manually overrides the automated workflow for manual triage.
Settings
Open Settings via the ⚙ button in the header. Changes take effect immediately and are persisted in the browser's local storage.
General
- Theme — Choose Dark, Light, or Auto (follows the OS preference). The active theme is highlighted in the selector.
- Notifications — Toggle browser notifications for task state changes (e.g., a task entering Review). Requires browser permission on first enable.
Execution
- Max Concurrent Sessions — How many AI agent sessions can run in parallel. Increase this to process more tasks simultaneously. The default is 1 (sequential). Higher values require more system resources.
Workspaces
- Formic can manage tasks across multiple code repositories. Add a workspace by pasting an absolute path to a local repository and clicking + Add.
- Each workspace has a color-coded label for quick identification on task cards.
- Remove a workspace with the trash icon. This does not delete any files — it only removes the workspace from Formic's list.
- The active workspace (shown in the board header) determines which repository tasks are executed against.