Back to all guides

The board: course, dispatcher, and milestones

Track your project's work on the board (the "course"): phases as columns, task cards that move from up next to done, the dispatcher that runs independent tasks in parallel (or one at a time when you turn parallel off), milestones that group a run of phases under one workload, how you or the team move a queued phase earlier or later and what the MOVED marker tells you, and how a Lead plan, an edit to the project's plan file, and an existing .planning folder populate the board. Also how to open a milestone and read what is inside it: a finished one shows each phase's verdict, the seat that checked it, and each card's role and commit, naming exactly why a commit is absent rather than leaving a blank; an upcoming one shows its phases in order with the dependencies Castforge inferred from the cards. Opening either changes nothing.

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:

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:

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:

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.

If a card's turn ends with the agent reporting it cannot proceed (for example, a design task whose target screens are not built yet), Castforge parks that card as Blocked with the reason shown right on the card, instead of retrying the same task over and over. The Lead is asked to resequence the plan around it. The card comes back on its own: it returns to up next automatically once the work it depends on is done, or when the Lead re-plans it, and you can always run it yourself from the card at any time.

There is one exception, and it is deliberate. A card parked because its finished work never reached your project (the step that brings a card's work in could not bring it) does not come back on its own. It keeps reading Done, because the task itself did finish, and carries the reason next to that, so it reads "Done: " followed by what Castforge found. It stays put until you run it from the card, because sending it round again with nothing changed is the loop Castforge is now avoiding. See "Recovery and troubleshooting" for the reasons you may see there and what each one asks of you.

Design reviews now wait up front rather than running and then blocking. A visual review will not start while the card it reviews depends on work that is not built yet, whether it was triggered automatically or you pressed the design review action yourself. If you trigger it early, Castforge tells you the review will run once that prerequisite card is done, so no agent turn is spent reviewing a screen that does not exist.

A card also cannot mark itself finished past its own reviewer. If a role writes a completion for its own card and, in the same turn, reports that it cannot do that work, the completion is dropped and the card stays open. The card shows its real state, and the conflict is recorded in the project's history rather than quietly clearing the card. The same rule applies to the tidy-up Castforge runs at the end of a visual review: it used to close the reviewing role's own card whatever the review said, and it now leaves that card open when the review blocked, with the hold recorded in the project's history. A later passing round closes it normally.

A card that is already done can say a seat is working on it again. Whether a card is finished and whether anything is running on it are two different questions, and the board answers both rather than letting them look like a contradiction. The common way this happens is a review sending work back: a Reviewer asks for changes, the Coder picks that card up again, and the card is complete the whole time.

While a seat is working it, the card's status pill stops reading Done and reads Revising instead, and the title loses its strikethrough, because a card someone is actively working is not finished text. A second pill beside it names the seat, reading "Coder is revising this". If you re-run a finished card yourself instead, the status pill reads In progress and the second pill reads "Coder is working on this again", because an ordinary re-run is not a revision and is not described as one. Both pills go back to Done when the seat finishes.

This is a display change only. Underneath, the card is still counted as done, so anything waiting on it keeps moving and is never sent back to waiting because someone opened the card again.

Nothing else about the card changes: the status stays Done, the progress figures still count it as finished, and there is no colour change and no pulse. The second pill appears only while that seat's turn is live and goes away by itself when the turn ends. Only the card the seat is actually working shows it, so a second finished card of the same role stays as it was. This is what a board reading 100% complete looks like while work is still running: the percentage counts cards that are finished, and the pill tells you a seat is on one of them.

While a card is doing, its role can spin up its own short-lived background agents to gather context in parallel (for example, a Researcher researching several questions at once). In the relay above the board, that role keeps showing what it is doing rather than Done, with a small child dot per live helper beside its name and an N agents badge on its lane (1 agent when there is only one); click a dot to watch that helper's own stream. The card stays doing and the next task does not start until the helpers finish reporting, so a plan or a downstream task is never built from half-finished research. If a helper stops responding, the wait ends on its own after a short bound so the board never gets stuck. See "Your AI dev team" for more on background agents.

A card only reads in progress while something is actually on it. If the app closes or crashes mid-run, the card the saved snapshot says was running comes back marked Interrupted with a Resume control, as long as that card is genuinely still in progress. If it had already finished before the app closed, the stale note is dropped instead, so nothing is marked Interrupted and you are not offered a Resume for work that is done. Any other card left sitting in progress was stranded when its turn died, so on reopen it goes back to Up next. That keeps the board's count of working roles honest, and it matters for scheduling too: an in-progress card is unfinished work that nothing may run past, so a stranded one would otherwise hold back everything that depends on it and keep its phase from ever completing. See "Recovery and troubleshooting" for the details.

An in-progress card also tells you when a tool has gone quiet on it. While a card is doing, if the tool its role is using has been running for a while without producing any output, the card replaces its live status with a badge naming that tool and how long it has been running, for example Bash running 7m 30s. The badge says only that, and nothing is stopped: some tools legitimately run that long, a full build or a complete test run among them, and only you know whether the named tool plausibly takes that long here. Right-click the card and choose Stop this turn if it should not. The badge clears by itself as soon as the tool produces output again. See "Recovery and troubleshooting" for the two cases it covers and how to tell them apart.

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:

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.

Run a one-off now

Sometimes you need something done in the middle of a run without derailing the plan. The board header has a Run now quick-input for exactly that: type a short one-off ask, press Enter or click Run now, and Castforge runs it immediately as a one-off, outside the current milestone sequence.

While the one-off runs, the card the team was working is paused at exactly where it was (you see it as an in-progress card marked paused, not lost). When the one-off finishes, that card resumes on its own at the same point, so your milestone work picks up right where it left off. The one-off never opens a second milestone or runs alongside your milestone work: the active milestone is paused, then resumed, so only one milestone is ever in progress at a time.

Run now is available while a run is in progress (there has to be active work to pause over). On an idle board there is nothing to pause, so the input is disabled and a normal ask just runs as usual. Only one run-now can be in flight at a time: if you send a second while the first is still running, Castforge tells you one is already running rather than stacking them.

Sending a message while the team is working

When you type a new message in chat while a run is in progress, Castforge does not guess what you meant with it, and it never silently re-plans or wipes the board. It holds the message in a visible queue above the composer and, on a project with several roles and a board that is already planned, asks one quick multiple-choice question about what should happen with it. The queue itself and all five options are described in "Working in a project"; this section covers the two answers that touch the board, and what Castforge does when your message looks like an architecture change.

The recommended option, Queue it for after this run, is first and preselected, so a bare Enter can never kick off a new milestone or pause your run by accident. Only picking one of the others deliberately does that. In Autonomous mode Castforge takes that same recommended option on its own, so an unattended run is never re-planned or paused behind your back. A plain "continue" or "resume" is not treated as a new message: it re-engages the work already on the board as before.

Folding a message into the card in flight

Choosing Fix it in the card in flight folds your message into the task that is already running. No new card is created and the board does not change shape. Castforge says which card it folded into, right in the chat, for example: Folded into "Add the settings toggle". No new card was created. That line is how you know the fold landed and where, instead of having to infer it from the board not moving.

If nothing is actually in flight when you pick it, Castforge does not hand your message to the Lead instead. It queues the message and says so: No card was in flight, so this is queued for the next settle point instead. Either way the message is kept.

There is no undo on a fold in this build. Because the announcement names the card, a fold you did not want is recoverable by asking again explicitly.

"Plan a new milestone" is not offered while a run is active

Earlier builds offered Plan a new milestone as one of the mid-run answers. It is deliberately no longer in the list. A mid-run "make this a whole new milestone" ask is an architecture-shaped change, and Castforge parks that kind of ask for you to decide rather than quietly re-planning the board around work that is still running.

You are not losing the destination. Queue it for after this run reaches the same place through the normal routing: the message goes out at the next settle point, Castforge announces the lane it chose, and you can override that announcement in one click (including straight to a milestone change) if it read your request differently than you meant it.

When Castforge parks an architecture question

If Castforge reads a queued message as an architecture change, it does not start it. It posts a Waiting for you notice in the chat: Waiting for you. This looks like an architecture change, so nothing was started. Choose what happens to it on the queued list.

While the hold is on, the whole queue is held, and the queued stack says so: Held for your decision. This looks like an architecture change. Nothing goes out until you decide.

The queued stack gives you two buttons, and each one does what its label says:

The X on the held row does the same thing as Drop it: it removes that message and releases the hold, so you can never be left holding a queue behind a message that is no longer there.

Once you have chosen, that message is not parked a second time. A Stop cancels the hold along with the run, so a message like that can be parked again on a later run.

Running tasks in parallel

By default, when two or more cards are genuinely independent (their dependencies are all met and they do not depend on each other), Castforge runs them at the same time instead of one after another. A common case is a design card and a coding card that touch different parts of the project: both start together, up to a small limit, so the run does not idle work behind a queue.

To stay safe, each concurrent task runs in its own isolated workspace (a separate copy of your project), so two tasks writing files at the same time can never step on each other. Review and merge stay in order: the results come back and are reviewed and landed one at a time, in a deterministic order, exactly as before. Parallel execution changes only when independent build work starts, never whether your work is reviewed before it lands.

Each time a task finishes, the board re-checks the dependency graph and starts any card that just became unblocked. A card whose prerequisites are not yet done stays parked as blocked and never jumps the line. Concurrency is bounded (a small per-project limit, currently two lanes), so a single project cannot saturate your machine.

How parallel results land. A card that ran in its own workspace does not touch your main project until it has passed review. Once a parallel card is reviewed and done, Castforge merges its branch back onto your main branch, one card at a time, in a deterministic order (a card that depends on another always lands after it, then board order). Because the merges are ordered and serialized, your main branch is always in a consistent state, and nothing is landed before it is reviewed.

When two results conflict. If two parallel cards changed the same lines and their results cannot be merged cleanly, Castforge detects the conflict before it touches your main branch, so your main branch is never overwritten or left half-merged. The affected card is marked with a conflict on the board (with the conflicting files noted). Independent cards that do not conflict keep landing normally.

What happens next depends on the project's permission level. On Careful and Balanced, the conflicted card is left for you or the Reviewer to resolve, and Castforge never resolves it mechanically. On Autonomous, Castforge sends the card's own agent back into that card's isolated workspace to resolve the merge by hand: the agent merges your main branch into the card's branch, resolves each conflicted file keeping both sides' intent, and commits the merge. Your main branch is still only touched by the ordinary landing step once the merge is clean. This is bounded: a card gets at most two resolution turns, and if the conflict survives both, it stays parked on the board for you, exactly as on Careful.

Turning it off. If you prefer the classic one-at-a-time behavior, open the project's Settings, Behavior and set Parallel execution to Off. The project then runs the serial pipeline: a single task at a time, advancing through the queue. You can turn it back On at any time; the change takes effect on the next task the dispatcher starts.

Keeping parallel runs safe

Parallel execution is designed to be safe to leave on. A few guarantees back that up:

You choose how wide it fans out. The Maximum lanes control in Settings, Behavior caps how many independent cards run at once (1, 2, or 3; the default is 2). Castforge never runs more than 3 agents at the same time no matter what you pick, so one project can never take over your machine or your provider limit. Set it to 1 if you want the parallel review order but only one card building at a time.

Running cards in parallel never removes a confirmation. Actions that spend money or are public or irreversible (a production deploy, a schema migration, publishing a design, buying a domain) are the ones Castforge treats as high risk. On a Careful or Balanced project they ask for your confirmation first, and fanning the board out across several lanes does not change that: the same prompts appear, and each one reaches the exact lane that asked for it. Widening a run does not widen what an agent may do unattended.

Autonomous is the exception, and it is the whole point of the setting. A project set to Autonomous shows you no permission prompts at all, high-risk ones included. An agent on an Autonomous project can deploy to production, migrate a schema, publish, and spend, without stopping to ask. That is deliberate, and it is what you are choosing when you set the level. If you want the high-risk confirmations, use Careful or Balanced; parallel execution works the same way on both.

A dependent card waits for its prerequisite's work to actually land. When a card depends on another card, it waits until that card's finished work has landed on your main branch before it starts, so an agent never works from a checkout that is missing its prerequisites.

One card failing does not stall the others. If a card in one lane errors out, the other lanes keep running and finishing normally. The failed card is surfaced on the board (marked blocked or needing resolution) and on the Health tab, so you can see and address it without the rest of the run grinding to a halt. If a card's changes conflict with your main branch, that card is parked with the conflicting files shown on its board card while the other lanes keep landing, and Castforge retries the parked card automatically as the branch moves. On an Autonomous project, a parked conflict also gets an agent sent in to resolve it (see "When two results conflict" above), so a conflict does not quietly stall the rest of the run when nothing else can land past it.

A rate limit pauses only the affected lane. If your provider (for example Claude) hits a usage limit while one card is running, only that card is parked, with the time it resets shown. The other lanes keep working, and the parked card can resume on its own lane once the limit clears, without waiting on or blocking the others.

A crash or restart never leaves stray workspaces behind. Each parallel card runs in its own isolated workspace on disk. If Castforge closes or crashes mid-run, the in-flight workspaces are recorded, and on the next launch Castforge cleans up any leftover ones safely (it never touches your main project copy) while keeping each card's committed work on its branch, so nothing is orphaned and your reviewed-and-merged history stays consistent.

Watching parallel work

When more than one agent is building at once, the orchestration panel shows every working agent at the same time, not just the first one. Each active agent gets its own live row in the Roles section, and the board strip and the in-chat activity line both say how many agents are working (for example "2 agents working"). With parallel execution off, you see a single working agent, exactly as before.

Drill into one agent. Under each working agent's row is its live lane. Click it to open that agent's isolated transcript in a side panel: only that agent's output, streaming live, separate from the shared conversation. Close it (the X, clicking outside, or Escape) to go back. Opening a lane never disturbs the board or the main chat, and the panel stays responsive even when several agents stream at once.

On the board. A card that ran in its own workspace shows its merge outcome once it lands: Merged when its branch went onto your main branch cleanly, Needs resolution when it conflicts (with the conflicting files in the tooltip; on Careful and Balanced it waits for you or the Reviewer, on Autonomous an agent is sent to resolve it), or Merge blocked when the merge could not be safely attempted. Cards being actively worked keep their live pulse, so you can see which lanes are busy at a glance.

In the FILES panel. While isolated lanes are running, the FILES panel adds a read-only "In flight" section that lists each active lane's files, badged with the role working in it, so you can browse in-flight work without touching it. If the file tree looks empty during a parallel run, nothing is lost: the work lives in the agent lanes and lands on your branch after each card passes review.

Why parallel, why waiting. In the Roles section, select Why parallel to open the dependency graph. It lays your cards out by dependency depth and labels each one: Running now, Ready to start, Waiting (with the exact upstream cards it is waiting on), In review, Needs you, Blocked, or Done. This is how you see, at a glance, which cards are safe to run together and which are parked behind a dependency and why.

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:

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 (grouping a run of phases)

A milestone is a container that groups a run of board phases under one workload or intent, for example "v1 launch" or "billing rework". Where a phase is a single column of tasks, a milestone is the band that a run of phases lives inside. The board shows milestones as a vertical stack of sections: each section is one milestone, and the phases inside it are that milestone's columns.

The active milestone is expanded. The milestone you are working in shows its phases as the usual horizontal row of columns, so day to day the board looks and behaves exactly as it always has. A milestone that is finished collapses to a one-line summary: its title, how many phases it holds, and when it completed. You can leave your history stacked below without it crowding the work in front of you.

Every project shows its milestone section. Even a project you have never grouped shows one milestone section: its default milestone, expanded and named, wrapping the phases you already have. So there is always a milestone header on the board to see and a create affordance to reach, on any project, from the very first phase.

The Lead triages where every request belongs. Before it writes a plan, the Lead weighs your request against the milestones already on the board and routes the work to one of four places: it keeps a small, self-contained one-off in the default section (a "now" task), it folds work that extends an existing milestone into that milestone, it starts a new milestone for a distinct multi-phase workload, or, when the request genuinely sits on a boundary, it asks you first with a quick multiple-choice question and then plans with your answer. Work that belongs to an existing milestone goes into it regardless of size; a single task becomes a card, one coherent step becomes a phase, and a run of dependent phases or a distinct named epic becomes its own milestone.

New, distinct work starts a new milestone, and the Lead proposes the structure. When you kick off a fresh, milestone-shaped piece of work (for example "build X": a multi-phase job with a dependency chain across distinct workloads), the Lead proposes the milestone structure as part of its plan, grouping the phases under one or more named milestones, instead of you pre-creating empty milestones first. Before Castforge creates any new milestone, it shows you the proposed structure and asks you to confirm. That confirm appears on Careful and Balanced. On Autonomous it does not: since 2026-08-05 an autonomous run creates the proposed milestones with no dialog and carries straight on into them, so leave a planning run unattended only if you are willing to come back to a board organised into milestones you did not approve. If you are looking for this dialog and not seeing it, the permission level is why. A small, self-contained ask is different: it stays a one-shot in the default section, with no milestone proposed and no confirm. Once your milestones exist, later work that extends one routes into the correct existing milestone on its own (continuation), with no confirm. Continuing or refining the work already in flight stays in the current milestone.

Nothing you already have is lost. Existing projects were folded into a single default milestone when this shipped, a safe backfill: every phase and card you already had is still there, now grouped under one milestone rather than floating loose. That default milestone shows up on the board as a named, expanded section right away, so you can see it and start creating more milestones without any setup.

A run works inside one milestone, and it always knows which one. A run advances through the phases of a single milestone at a time. If a run is interrupted, when it picks back up (after a crash, or after a provider usage limit lifts) it re-enters the same milestone it was in, and the team's re-orientation names it, for example "Milestone 2 of 4 ('Auth revamp'), phase 3 of 5". Stepping back in time to an earlier point (Time Machine) also names the milestone you land in, so you always know where you are.

Queue a backlog and reorder it

You do not have to start a milestone the moment you think of it. At the bottom of the milestone stack, on any board (including a project that still has only its default milestone), there is a Queue milestone affordance: give it a title and it adds a pending milestone to your backlog without starting any work. It is a placeholder for "next workload, but not yet", so you can capture what is coming without cluttering the run in progress. This is also how you create your first named milestone: the button is always there, so you are never stuck with no way to add one.

Drag to reorder your backlog. Pending milestones carry a drag handle. Grab it and drag a pending milestone up or down to change the order the project will pick them up in. Only pending milestones move: the active milestone and finished ones are frozen and have no handle, so you can never reorder work that is already running or done. The new order is saved as you drop.

Move a phase earlier or later

Phases move too, not just milestones. Right-click a phase header on the board and the menu offers Move to front of queue, Move earlier, and Move later. The new order takes effect on the next task the dispatcher starts: no restart, no re-plan, and nothing that is already running is disturbed.

Only a phase where no task has begun can move. As soon as one task in a phase is running or finished, the whole phase keeps its place, even if the rest of its tasks are still queued. A phase that cannot move shows its menu item greyed out, and hovering it tells you why, so an item is never offered to you just so it can be turned down.

A phase moves inside its own milestone. To change which milestone runs first, reorder the milestones instead (the drag handle described above), and the phases inside each one travel with it.

A move that would break something is refused rather than applied, and the refusal always states its reason. See "My move was refused, why" in "Recovery and troubleshooting" for the full list of reasons and what each one asks of you.

The Moved marker

An item that was moved carries a small MOVED marker for as long as it is still queued, on the phase header or on the pending milestone row. Hover it to read who moved it, when, and what it now runs after, for example: Moved by you, 2 hours ago. Now runs after "Interface". The marker clears on its own once the item starts, and it survives closing and reopening the app, so someone who was not the one who moved it still finds it there later.

Every accepted move is also written to the project's decision log, which you can read under Decisions in the Memory tab. So a move is never a silent reshuffle: it is visible on the board while the item is queued, and it stays in the record after that.

Moving work to the front from the conversation

You do not have to come to the board to reprioritize. If you ask in chat for something that is already planned, Castforge answers you there and offers to move that work to the front. See "Asking again for something that is already on the board" in "Working in a project" for what that answer looks like.

Accepting the offer is not a separate mechanism. It performs the same guarded move you can already make by hand from the phase menu, so it obeys the same rules described above: a phase where a task has already begun does not move, a move that would break a dependency is refused, and an accepted move gets the same MOVED marker and the same line in the decision log. Declining the offer does nothing at all to the board.

Two cases are worth knowing:

Where a new ask landed on the board

You do not have to be looking at the board to find out what an ask became. When a turn finishes having planned your ask into one new phase, the conversation gets one quiet line naming that phase, its card count and what it is queued behind, so the board and the chat agree without you switching tabs.

That landing is also written to the project's decision record, which is what makes it survive a restart: the line in the conversation belongs to the session, but the entry in the Memory tab and in the project's decisions file does not.

The line states a position, not a time. If the new phase is in a milestone that is not the one running now, it also says that the run pauses at each milestone boundary for your review, which is the default behaviour described under milestones above.

A bug report about work that is already built

When you report a defect in something the board shows as finished, that fix does not queue up behind every feature you have planned since. Castforge places it at the front of the current milestone and says so with one short line in the conversation.

Three things about that placement:

This only applies when the board says the thing you are describing is already built. The same words about a feature that does not exist yet are planned as an ordinary feature ask.

Pausing at a milestone boundary

Moving from one phase to the next inside a milestone is automatic, exactly as it always was. Crossing from one milestone into the next is different: by default the run pauses when it finishes a milestone and the next one is ready, so you get a natural checkpoint to review the finished work before the team rolls on. The board simply returns to its idle Run state at that point; press Run, or start a card in the next milestone, to continue.

If you would rather the team roll straight into the next milestone without stopping, open the project's Settings, Behavior and turn on Continue past milestone boundaries. With it on, auto-advance crosses the boundary on its own. This setting only affects the jump between milestones; phase-to-phase advancement inside a milestone is unchanged either way.

Agents can manage milestones for you

Milestones are agent-callable, so the team can organize the board on your behalf:

Dependencies between milestones

You can say that one milestone must finish before another can start. When a pending milestone depends on another milestone, the board treats the one it depends on as a prerequisite:

Dependencies are declared by the team on your behalf (see below); a milestone with no dependency behaves exactly as before.

Opening a milestone to see what is inside

A milestone is not a dead end once it is finished. Expand any milestone section and it lists its phases; open a phase and you get a detail panel with the cards inside it. This works on a milestone that is already done and on one that has not started yet, and the two tenses answer different questions.

Opening a milestone changes nothing. Nothing re-runs, nothing re-plans, nothing reorders, and a run in progress is not touched. There is no control on this panel that can change your project. It is a place to read.

A finished milestone: what was done

Each phase inside a finished milestone shows its name, how many cards it holds, and the verdict of the check that ran on it. Open the phase and you get the seat that reported that check, then one row per card with the card's title, the role that did it, and the commit.

When there is a commit, you get the short commit id and the date, plus a copy control beside it. Copy puts the full forty character id on your clipboard, not the seven characters on screen.

Often there is no commit to show, and that is normal rather than a fault. Castforge names which case applies instead of leaving the space blank:

None of these means work was lost. Every one of them is a statement about the record, not about the code. Castforge says what it can prove from the record and stops there.

Finished at, and why it is worded more weakly. Sometimes a commit id appears after the words Finished at rather than as the card's own commit. That is the difference between a card that PRODUCED a commit and a card that only FINISHED at one, and the difference is deliberate. Castforge reads the commit's own record of which cards it carried. When that record names the card, the commit is that card's work and is shown as such. When the record cannot settle the question either way, the row says only where the card finished, which is true, rather than claiming authorship it cannot prove. The weaker wording is a narrower claim, not an error.

A record Castforge could not read is different from a record that says nothing. If the read fails the row says Commit record could not be read, and if only part of it came back it says Commit record could not be read in full. Neither is the same as No commit recorded, and one is never substituted for the other. While the read is still in flight the row says Reading commit record.

What the verdict on a phase means

Each phase row carries the result of the check that ran on it, in one of these forms:

If the check record itself could not be read you get Check record could not be read., or Check record could not be read in full. when only part of it came back. Neither is ever collapsed into No check on record.

Occasionally a recorded check cannot be matched to any phase on the board. Rather than dropping it, Castforge states it at the foot of the open panel, so the evidence is not silently lost.

An upcoming milestone: what is planned

A milestone that has not run yet opens the same way and shows its phases in the order they will run. There is no verdict and no commit on those rows, because neither could exist yet.

What each future phase row does carry is its dependencies:

A milestone with no phases yet says No phases planned yet., and a phase with no cards says No cards on record for this phase.

A long dependency list wraps onto another line rather than being cut short, because a truncated list reads as a complete one.

Partial history still opens

Older projects, and projects that ran before parts of this were recorded, will have gaps. The panel opens anyway and names each gap where it sits, next to everything it does know. Failing to open is the one outcome this panel does not have.

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.

A handy shortcut: dispatching (running) a card from a pending plan counts as approving it, so you can start straight from the board.

Re-planning a phase updates it, it does not add a copy

Plans get revised. You ask for a change, the team picks work back up after a pause, or a plan comes back malformed and Castforge asks for it again. Each of those can hand the planning seat a fresh session that has no memory of the board it is re-planning.

So Castforge tells the planning seat, every time, what phases the board already has and what each one's durable identity is. When the new plan describes one of those phases again, it lands on the phase that is already there: the column is updated in place, with your finished and in-progress cards left alone, rather than a near-identical second column appearing beside it.

When Castforge cannot match an incoming phase to one already on the board, it adds it as a new phase rather than guessing which existing one it meant. That is deliberate, and the tradeoff is worth knowing: you may occasionally see a phase that looks like a duplicate of one you already had. Castforge would rather show you that than quietly merge two phases that only looked alike, because a duplicate column is obvious and takes seconds to clean up, while a wrong merge silently replaces planned work with different planned work. If you do see one, ask the team to fold it into the phase you meant, or remove the cards you do not want.

When a plan is not applied, Castforge tells you why

Some plans are deliberately not written to the board. Castforge protects work that is already underway, so a fresh full plan does not quietly clobber a run in progress. When that protection fires, your board is left exactly as it was and you get a short note saying which one fired:

Nothing is lost in any of these cases. Your board and everything on it are untouched, and your original request is still in the conversation.

New milestones are only created when a plan actually lands. If a plan is turned away for any of the reasons above, no empty milestones are left behind on your board.

When the plan file is what changes

Work reaches the board two ways, and both are supported.

The first is the one described above: the agent in the Lead seat returns a plan, and Castforge writes its phases and tasks onto the board as columns and cards.

The second is the plan file. Castforge keeps a readable copy of the whole board at .castforge/plan.md in your project, and a Lead can answer a plan-shaped ask by editing that file on disk instead of writing a plan into chat. When that turn ends, Castforge reads the file, works out what the board does not have yet, and adds it. Both routes end in the same place: live cards you can dispatch and run. This holds with whichever agent is in the Lead seat, so a Lead that edits the plan file and a Lead that returns a plan land equivalent work on the board, down to which task the board runs next and which role it goes to. The two write different things to disk; the board you end up with is the same.

Describing the same phase twice does not duplicate it. Castforge matches what the file lists against what the board already has by title, ignoring capitalization. A section or a task the board already carries is left exactly as it is, and only what is missing gets added, so a Lead that rewrites the whole plan file adds only the new part of it. There is an honest consequence to matching by title: two tasks with the same name are treated as the same task. If the file lists a task under a name the board already has, nothing new is added for it, even when you meant a second, different task.

The plan file is Castforge's file, not a document you own. Castforge rewrites it from the board on the next board change, so free-form prose written into it is replaced by the standard layout. What survives that round trip is the phase structure: section names, section descriptions, and task titles with their roles and their status. What does not survive is the rest. A task's own goal line does not come back as a task description, and the run order between tasks does not come back either: the file records which task depended on which, but those links are not read back in. If you keep notes in that file, they will not persist. Keep them somewhere else in the project.

That rewrite is an attempt rather than a promise. It is best effort: if Castforge cannot write the file, for example because the file is read only, your board is still correct and the file catches up on a later change.

A task's status in the file is honoured. Each task line ends with its state in square brackets, for example [up-next] or [done]. A task the file adds to the board lands in the state the line names, so writing [done] against work that is already finished keeps it out of the run instead of queueing it up again. Anything that is not one of the board's own states is read as part of the title, and a line with no state at all lands as up next.

A task added through the plan file is not ordered behind anything. Because those dependency links are not carried across, a task that arrives that way lands ready to run rather than gated behind another task. If the order matters, say so in chat and the Lead can sequence it.

If you want to know what Castforge does when the plan file and the board have drifted apart, see "Recovery and troubleshooting".

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 the container one level up: it groups a run of phases under one workload (for example "v1 launch"). The board stacks milestones vertically, expands the one you are working in as the usual row of columns, and collapses finished ones to a one-line summary. Starting distinct new work while the project is idle creates a new milestone; continuing the current work stays in the current one.

Does "Run" run everything at once? Not everything, but independent tasks do run together. By default the board runs independent ready cards in parallel (each in its own isolated workspace), up to a small per-project limit, and re-checks for newly unblocked cards as each one finishes. Review and merge stay in order, so nothing lands unreviewed. If you want the classic one-at-a-time behavior, set Parallel execution to Off in the project's Settings, Behavior, and the dispatcher runs a single task at a time through the queue.

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. Is it still alive? Check the working badge at the top of the workspace pane. A long tool call (a big install, a slow test suite, a long shell command) can produce no visible output for many minutes, which used to look exactly like a crashed run. The badge now answers it directly: while Castforge can confirm the agent's process is still alive, it reads Working: Bash, running 4m 12s, where the tool name is whatever is currently running and the timer keeps counting. That wording is a statement, not a guess, so you can leave a long step alone instead of reaching for Stop.

If Castforge stops being able to confirm the process, the badge changes its wording to Working: Bash, last activity 4m 12s ago. That version only reports what was last seen, so a run that has genuinely gone away never keeps claiming it is running. This works the same on every agent, so a Codex or Gemini seat gets the same signal a Claude seat does. On agents that report their own progress, the badge can also name the exact tool that is taking the time.

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.