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.

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:

1. Generates gitBranchName as kanban/{PRJ}-{N}-{slug} (example: kanban/KAN-14-add-google-oauth)
2. Creates a git worktree at .worktrees/kanban/{PRJ}-{N}-{slug} inside the project directory
3. Sets gitWorktreeStatus = active and gitBranchStatus = active

The project stays on its main branch in the original working directory; the worktree is an isolated checkout for this specific card.

Branch enforcement

Once a card is in In Progress, a PreToolUse hook blocks Claude from editing files while the working tree is on the wrong branch. This closes the loophole where a Claude session started outside the Ideafy-managed flow (e.g. via bind_session_to_card from an existing shell) could still edit main despite having a feature branch provisioned.

The deny message tells Claude to call the ensure_branch MCP tool, which creates or switches to the correct branch, after which the edit succeeds on retry. The user-visible behaviour is "the edit pauses, switches branches, then completes" — no manual intervention needed for the common case.

Enforcement only applies in In Progress. Terminal columns (Test / Completed / Withdrawn) don't enforce, so you can freely edit during human testing or post-merge review. See PreToolUse hook details.

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.

Testing on the isolated dev server

Because the worktree is a full checkout on its own branch and runs its dev server on its own port, it's the safest place to exercise a card's work. You can break things freely — the blast radius stops at the worktree boundary.

The isolation is layered, not total:

The shared database is deliberate: when the worktree's dev server boots, Ideafy points data/kanban.db at the main project's database before npm run dev launches. You end up testing the new UI against your actual board — real cards to drag, real projects to open, production-shaped data — while source changes stay sandboxed to the branch. Rollback takes the branch and the dev server with it; nothing leaks into main.

Test Together (manual walkthrough)

The Test Together button appears on cards in Human Test that have testScenarios filled in. It opens an interactive Claude session whose working directory is gitWorktreePath (falling back to the project folder only if no worktree is attached). The agent reads the scenario checklist, walks you through each item one at a time, and lets you debug failing scenarios in-place against the branch — edit a file, restart the server, re-run the test, tick the box. The route is /api/cards/[id]/test-together. See Card modal — Tests for how the chat panel drives this.

Generate Tests (manual → automated)

The Generate Tests button converts human-readable testScenarios into real unit tests. The route (/api/cards/[id]/generate-tests) prefers the worktree as the working directory when one exists, so the CLI session:

1. Detects the project's test runner from package.json (Jest, Vitest, and similar)
2. Writes test files on the card's branch
3. Runs the suite and only marks a scenario - [x] once the matching test passes

Because this happens inside the worktree, the new tests ride the branch into the merge — or disappear with it on rollback.

Parallel testing

Nothing in the isolation model is single-tenant. Three cards in In Progress or Human Test can each have a dev server running (3031, 3032, 3033) against the same shared database. You can flip between browser tabs testing three unrelated features at once, without port conflicts, without rebuilding node_modules, and without cross-contamination of source changes. The end-to-end pattern is in Three features in parallel worktrees.

Branch lifecycle

gitBranchStatus walks through three terminal states:

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:

1. Sets rebaseConflict = true
2. Parses the unmerged files from git status --porcelain into conflictFiles
3. 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

The rule of thumb: you take the decision, Ideafy does the bookkeeping.

Prev: Card chat & mentions Up: User guide index