Card git workflow
Ideafy doesn't ask you to manage branches, worktrees, or dev server ports by hand. When a card moves into implementation, the app provisions the git scaffolding; when the card ships (or is rolled back), it cleans up. This page describes what's happening under the hood so you can trust the automation — and intervene when you need to.
Screenshot gap. The git/worktree/dev-server UI isn't in the current screenshot set. See the gap list at the end of this page.
When does a branch get created?
A card doesn't have a branch while it's in Ideation, Backlog, or Bugs. The branch is provisioned when you start work on the card — autonomous, quick-fix, or an interactive terminal session.
At that moment, Ideafy:
- Generates
gitBranchNameaskanban/{PRJ}-{N}-{slug}(example:kanban/KAN-14-add-google-oauth) - Creates a git worktree at
.worktrees/kanban/{PRJ}-{N}-{slug}inside the project directory - Sets
gitWorktreeStatus = activeandgitBranchStatus = active
The project stays on its main branch in the original working directory; the worktree is an isolated checkout for this specific card.
Dev server allocation
If the card needs a running dev server (most UI work does), Ideafy starts one inside the worktree and allocates a port:
- Main Ideafy app:
3030 - Worktree dev servers:
3031,3032,3033, …
The port is recorded in devServerPort and shown on the card. The PID in devServerPid lets Ideafy stop the server cleanly later. Multiple worktrees can run in parallel, each on its own port — see Three features in parallel worktrees.
Start/stop is a button in the card modal header; the underlying route is /api/cards/[id]/dev-server.
Branch lifecycle
gitBranchStatus walks through three terminal states:
| State | Meaning | How it gets there |
|---|---|---|
active | Work is in progress on this branch | Card moves into In Progress |
merged | Branch was merged back to main, worktree removed | /api/cards/[id]/git/merge succeeded without conflicts |
rolled_back | Work was abandoned, branch deleted, worktree removed | /api/cards/[id]/git/rollback |
null means no branch has been provisioned yet.
Merging & rebase conflicts
When you merge a card back to main, Ideafy rebases onto origin/main first. If the rebase clean-runs, the worktree is removed and the card flips to merged. If it hits conflicts, Ideafy:
- Sets
rebaseConflict = true - Parses the unmerged files from
git status --porcelainintoconflictFiles - Surfaces a "Resolve Conflict" panel in the card modal header with the file list
Clicking Resolve Conflict spawns a Claude CLI session against the worktree (/api/cards/[id]/resolve-conflict) — the agent reads the conflicting files, resolves them, and hands control back. You can also open an interactive terminal into the worktree and resolve conflicts manually.
Rollback
Rollback is the "I changed my mind" button. /api/cards/[id]/git/rollback deletes the branch, removes the worktree, and clears the dev server. The card itself stays on the board — only the git scaffolding goes away. gitBranchStatus becomes rolled_back so you can still see that work was attempted.
What you manage vs. what the system manages
| Managed by you | Managed by Ideafy |
|---|---|
| Deciding to start work, merge, or roll back | Branch naming, worktree creation, port allocation |
| Resolving conflicts (or delegating to Claude) | Status enum transitions, dev-server PID tracking |
| Writing the plan and the tests | Cleanup after merge / rollback |
The rule of thumb: you take the decision, Ideafy does the bookkeeping.
Screenshot gap
None of the following are in the current screenshot set and should be captured before this page is promoted out of draft:
- Card modal header showing the active branch chip + dev server port + start/stop button
- Branch status chip in the three states (
active,merged,rolled_back) - Rebase conflict panel with a populated
conflictFileslist - "Resolve Conflict" Claude session in progress
Prev: Card chat & mentions Up: User guide index