The board (the "course")
The board, which Castforge calls the course, is where your project's work lives as a set of columns and cards. Each column is a phase (a chunk of work), and each card in a column is a task. You read it left to right: earlier phases on the left, later phases on the right.
The board is one of the two ways you follow the team. Chat shows you what each role is saying right now; the board shows you the shape of the whole job and where every task stands.
Phases (columns) and cards (tasks)
A phase is a column with a name, an optional description, and a state (it is "done", "active", or "upcoming", derived automatically from the cards inside it). Phases are the milestones-of-work that the Lead lays out, or that you add by hand.
A card is a single task. A card can carry:
- a title (what to do),
- a role tint (which kind of work it is),
- optional files it touches,
- a rough estimate,
- dependencies on other cards (so the board knows what must come first),
- a longer detail (the full task write-up behind the short title),
- and an author label when a teammate added it.
You can add a phase with the + Add phase column on the right, and add a card with the + affordance inside a phase.
Click a card to open its detail. A short click opens a dialog with the card's full task detail, where you can read and edit it and then Save (a card that has no detail yet still opens, so you can write one). When the Lead plans a phase it now writes each card's detail for you: the card face stays a short title and the dialog is pre-filled with the full task write-up the Lead authored, which you can still edit and Save. Clicking does not grab the card: to move a card you either hold it in place for about a second, or start dragging it a short distance, and then it lifts for drag-to-reorder. This keeps a quick click free to inspect the task without accidentally picking the card up. When you drag a card to reorder it or move it between phases, if a move would break a dependency (putting a task ahead of something it depends on), the board warns you and asks you to confirm before moving anyway.
Removing cards you do not want
If a plan puts cards on the board you do not want to run, you can remove them:
- Delete one card: right-click the card and choose Delete card, then confirm. You cannot delete a card that is actively running (stop its turn first), and you cannot delete a card that another unfinished card depends on (the board tells you which one, so you never orphan a task). When you delete the last card in a phase, that now-empty phase leaves the board too. An empty phase you added yourself with + Add phase stays put, so you can add cards to it.
- Delete a whole phase: right-click the phase header and choose Delete phase, then confirm. This removes the phase and every card in it in one step. It is blocked while a card in that phase is running (stop the turn first), and blocked if a card in another phase still depends on one of the cards you are removing (the board names it), so you never orphan a task.
- Discard the plan: the board has a Discard plan action that removes every card that has not run yet, in one step. Completed cards and any card currently in progress are kept, so you only clear the work that has not started. It asks you to confirm first, and tells you how many cards it removed.
- Clear the whole board: next to Discard plan, a Clear board action resets the board to a fresh state. It removes all phases and cards, keeping only cards that are currently running (and the phase that holds them), so an in-flight turn is never cut off. It asks you to confirm first. Clearing the board does not affect your project memory: it only empties the board, so what the project has learned and decided is kept.
Deleting cards, phases, or the whole board only affects the board, never your project memory. To also reset the chat conversation, use the /clear command, which archives the current conversation and starts a fresh one.
How cards move through states
Every card has a status. As work progresses, a card moves through these:
- Up next: queued, ready to be picked up.
- Doing (in progress): currently being worked on by an agent.
- Review: the work is done and waiting for a look (for example, after a Coder finishes and hands to a Reviewer).
- Done: complete.
- Awaiting: paused on a question for you (the card surfaces the prompt).
- Blocked: cannot proceed yet.
When you run the board, the dispatcher flips a card from up next to doing, and when the agent finishes that task it lands in review (for a single task) or rolls straight to done when you are running the whole queue. You can also mark a card done yourself from the card.
For an Unreal Engine project, Castforge also captures a viewport keyframe each time a card reaches done, so you can scrub back through that history in the Unreal panel's UE Time Machine. See "Preview and iterate" for the Unreal panel.
Filtering and a "collapse done" toggle let you hide finished work so the board stays focused on what is left.
The dispatcher: Run, Pause, Resume
The dispatcher is the control in the board header that actually runs tasks. It works on a queue of up-next cards, one task at a time, respecting dependencies (a card whose prerequisites are not done will not jump the line).
The dispatcher has three states:
- Run (idle): a Run button. Click it to send the top task in the queue to the active agent. The Run button is disabled when there are no phases.
- Running: an amber pill reading "Running, task N of M" with a live dot, plus a Pause button. N of M tells you how far through the queue you are. When you run the whole queue, each completed task advances to the next automatically.
- Paused: a dim pill plus a Resume button. Pausing takes effect after the current task finishes (so a task in flight is never cut off). Resume picks up the next task in the queue. If the queue has emptied while paused, Resume just returns the dispatcher to its idle Run state.
You can also run a single card directly from the card itself (its play affordance) without running the whole queue. If a dispatch fails (for example, the agent stream rejects it), the card rolls back to up next and you get a clear error, so the board never lies about what ran.
The Health tab: stuck cards, interrupted work, and recent activity
Next to Chat, Course, Preview, and Memory there is a Health tab. It is a focused, read-only view of anything that needs your attention on the current project, so a stalled or stranded run is never invisible. It has three sections:
- Stuck cards: cards the board currently reads as stalled (an in-progress card with no agent actually working it). Each stuck card has a Nudge button that re-dispatches it. The Health tab does not invent its own idea of "stuck": it shows exactly the cards the board's own Stalled marker shows, so the two can never disagree.
- Interrupted after a restart: cards that were mid-task when the app closed or crashed (the same Interrupted cards you see on the board). Each has a Resume button that rebuilds and continues the run. See "Recovery and troubleshooting" for how resume works.
- Recent activity: a running log of stalls, wedges, surfaced idle prompts, and automatic resumes that happened on this project, newest first. This is a history you can scan to understand what the run has been doing, not a set of actions.
When nothing needs you, the Health tab shows a clean "Nothing needs you" state rather than an empty or broken panel. Nudge and Resume are the only actions in the tab, and both only run when you click them; opening the Health tab never starts an agent on its own.
Milestones and the milestone strip
For larger, multi-release projects, phases can be grouped into milestones. A milestone is a named group of phases (for example, "v1 launch", "v2 polish"), and it rolls up its phases' states into a single state of its own.
When at least one named milestone exists, a milestone strip appears as a band above the columns. Each entry shows the milestone's name and a state chip (the same chip style the phases use). The strip is display-only: there are no buttons on it; it is there to give multi-release projects a sense of the bigger arc above the detailed columns.
If your project has no named milestones (the common case for a simple project), the strip does not appear at all and the board looks exactly as it always has. Milestones are an optional annotation on phases, not a separate structure you have to manage.
How a Lead plan materializes onto the board
When a Lead drafts a plan, that plan does not just live in chat: its phases and tasks are written onto the board so you can see the proposed work as columns and cards.
- If plan approval is off, the plan populates the board and is ready to run.
- If User approves Lead plans before execution is on, the plan still populates the board, but the affected phases show an Awaiting approval pill and are dimmed until you act. Approving in chat releases them; editing the plan updates the board in place (it merges, it does not duplicate); rejecting rolls the still-pending plan cards off the board. Work already in progress, anything you added by hand, and anything from an existing planning folder are never touched by this.
A handy shortcut: dispatching (running) a card from a pending plan counts as approving it, so you can start straight from the board.
Adopting a project that already has a .planning folder
If you open an existing folder that already has a .planning/ roadmap (a .planning/ directory), Castforge can read it instead of starting the board from scratch.
When you open such a folder, Castforge scans it and shows a Research review: a short summary, the signals it detected (including a roadmap-planning signal when a .planning setup is present), and a proposed team. From there you continue to Adopt team, which maps the proposed roles onto your connected agents and saves the team for the project.
For the board itself, set the project's plan source to Roadmap auto-detect (in settings). With that source, the board follows your .planning/ROADMAP.md: it reads the existing phases from that file so your already-planned work shows up as columns and cards. The board stays in sync with that file as the source of truth.
A note on other sources: Manual (you control every card by hand) and Roadmap auto-detect are the live plan sources today. Markdown, Linear, GitHub Issues, and Notion appear as sources but are stubs for now; picking one shows a "coming soon" state rather than importing tasks.
Common questions
What is the difference between a phase and a milestone? A phase is a single column of tasks. A milestone is a named group of phases, shown in the strip above the board. Milestones are optional and only appear when you have named at least one.
Does "Run" run everything at once? No. The dispatcher runs one task at a time and advances through the queue. While it runs you see "task N of M". Running several tasks in parallel is not available in this build.
What does "task N of M" mean? N is the position of the task currently running within the queue, and M is how many tasks are queued. It is your progress indicator while the dispatcher is running.
If I pause, does the current task stop immediately? No. Pause takes effect after the current task finishes, so a task in flight is never cut off. Resume then continues with the next task.
Why are some columns dimmed with an "Awaiting approval" pill? Those phases came from a Lead plan and the "approve Lead plans" rule is on, so they are waiting for you. Approve in chat, or dispatch one of their cards, to release them.
I opened an existing project with a .planning folder. How do I get its phases on the board?
Adopt the proposed team in the Research review, then set the plan source to Roadmap auto-detect in settings. The board then reads .planning/ROADMAP.md and shows your existing phases.
Can I still add and move cards by hand when using Roadmap auto-detect?
Cards you add by hand and other manual or in-progress work are preserved and never overwritten by plan merges. With that source, the board follows .planning/ROADMAP.md for the planned phases.
My card is stuck in "review". How do I finish it? Mark it done from the card, or let a Reviewer close it. A card lands in review after a single-task run; running the whole queue advances completed work to done automatically.
A run went quiet and I cannot tell what is stuck. Where do I look? Open the Health tab. It lists stuck cards (with a Nudge to re-dispatch), cards left Interrupted by a restart (with a Resume), and a recent history of stalls, wedges, and automatic resumes. If nothing needs you, it says so. It mirrors the board's own Stalled and Interrupted markers, so it never disagrees with what the cards show.