KanSpec: project management for parallel coding agents

Most coding-agent tools start with one conversation and one checkout. That is fine for a contained change. It becomes awkward when I want to split a project into several pieces, run them at the same time, keep their branches apart and retain the reasoning behind each piece of work.

Conventional project-management tools handle the plan but know very little about the repository, the agent's terminal or the state of its worktree. I wanted the task and the place where it was being implemented to be connected, so I could see what was running, inspect the change and bring it back into the project without reconstructing the context by hand.

KanSpec manages specifications, tasks, notes, documentation and supporting resources. The application gives me a Kanban board, document and tree views, search and links between related material. Underneath that interface, the project records are ordinary YAML and Markdown files in or alongside the repository.

The files matter more than the interface. They can be reviewed and changed with the same tools as the code, and their history is still available when I switch to another agent or model. Through the KanSpec command line, an agent can read the current schema, create or update a task, specification or note, and validate the file afterwards. I can also dictate a task through any voice interface instead of having to fill in a form myself.

The application is therefore a convenient way to view the project, not the only way to operate it. I use the board for an overview, the file views when I want to read or edit something directly, and terminal commands when an agent is already working on the project.

When I assign a task, KanSpec creates or reuses a Git worktree. A worktree is a separate checkout of the same repository, so the agent gets its own branch and files without needing another full clone. The terminal and application preview are attached to that worktree, which makes it clear where the process is running and what I am looking at.

Separate checkouts stop two agents from editing the same files, but a full-stack project also has runtime state to think about. KanSpec can allocate a different port, provision a separate database and run the project's setup steps for each worktree. Without that separation, two apparently independent tasks can still interfere with each other through a shared server or database.

Each task keeps its preview, diff and terminal conversation together. If the approach is wrong, I can revise or reset that task without disturbing the other work in progress.

The embedded terminals are backed by a separate broker process rather than the development server that serves the KanSpec interface. Restarting that development server or refreshing the browser does not interrupt an agent. The page reconnects to the terminal session and restores its scrollback.

Because the broker is separate, I can use KanSpec to develop KanSpec itself. Restarting or rebuilding the interface leaves the agents working on it running in their existing terminals.

After a machine restart or broker failure, the underlying process really is gone. KanSpec then uses the provider's own resume command to reopen the conversation. That is a different path from reconnecting the browser to a terminal that never stopped, which avoids trying to recover sessions unnecessarily during ordinary frontend development.

KanSpec launches the provider CLIs I already use rather than requiring its own model API. The same task can be opened with Claude Code, Codex or Cursor. I tend to use different providers and model sizes for different kinds of work instead of spending one provider's allowance on everything.

Narrower tasks also need less context. An agent receives the task, the relevant specification and the linked resources instead of having to rediscover the whole project. For routine implementation I can use a smaller or cheaper model and reserve the stronger models for work that needs more reasoning.

Switching providers helps with cost and token limits, but it also keeps the project independent of one company's harness. Whichever agent I use, the KanSpec command line provides the same commands for searching records, reading schemas, updating tasks and specifications, validating files and operating the workspace. The web interface is there for me; an agent does not have to click through it.

I use a developer branch as the place where completed task branches are integrated. Agents can make frequent checkpoint commits on their task branches, and I can bring finished tasks onto the developer branch without pretending that the resulting history is ready for everybody else to read.

I treat the shared branch as the version I am prepared to publish to a team or client. On the private developer branch I can keep small checkpoint commits while the work is moving. Before publication I review the code and the commit history separately, so useful development checkpoints do not automatically become the permanent public history.

On my own projects I normally keep the code and KanSpec records in one repository. A code commit can be accompanied by the task or specification changes that explain it. I find that history useful because it records not only what changed, but the piece of work and decision-making around it.

I do not yet assume that this is the best arrangement for every project. KanSpec also supports a split setup where the application repository ignores the `kanspec` directory and that directory is a private Git repository of its own. Specifications, tasks and notes remain versioned, but their commits do not appear in the application repository's history.

KanSpec pairs the code and metadata worktrees for each task and coordinates their status, commits and integration. The paths shown in the interface and supplied to agents stay the same. This lets me use the split setup on a shared or client repository without introducing my experimental project-management workflow into it.

There is a separate option for projects where the developer and task branches should not appear on the shared remote at all. KanSpec can synchronize those branches through a private developer repository and publish only the reviewed developer branch to the shared repository's main branch.

The metadata repository and the private developer repository are independent choices. The first keeps tasks and notes out of the code history. The second keeps unfinished code branches off the shared remote. Either one can be used alone, or they can be combined for a client repository.

Agent sessions often leave useful checkpoint commits, small follow-up fixes and messages that only made sense while the task was in progress. I want to keep those commits during development without asking the next person who reads the history to make sense of them.

Before publishing, KanSpec lists the commits that are on the developer branch but not the shared branch. From that view I can fold a follow-up into the change it belongs to, rename or reorder commits, or ask KanSpec to propose a split when one commit contains unrelated work. I review the proposed split before anything is rewritten.

KanSpec creates recovery references before changing the history and checks that the final file tree is unchanged. Once the commits are in a useful order, it fast-forwards the shared branch. The working history remains available while I need it, but the published repository receives the reviewed version.

Some resources are useful to an agent but are only temporary working material. Figma exports are a good example. The generated JSX and screenshots help with an implementation, but putting every export and refresh under version control would add a lot of noise. KanSpec keeps this material in `_unversioned` directories while retaining stable project-relative paths that a task or note can refer to.

When a task starts, KanSpec reads its resource references and copies only the required local files into that worktree. It does not duplicate the whole asset library for every agent, and Git never sees files that were only needed as temporary evidence.

The Figma integration can import selected frames as screenshots and fetch JSX with mappings back to the original Figma nodes. An agent can inspect the Tailwind classes and JavaScript behaviour behind the design, then translate the relevant parts into the React application. The screenshot and JSX appear in the task worktree without becoming part of the repository history.

KanSpec is still personal software rather than a released product, but I use it for all of my project work. Its parallel workflow is how I managed the frontend, API, database, AWS infrastructure and release work needed to take Mappd to private beta in roughly two months.

The only time I usually work directly in a standalone provider harness is when I am making a breaking change to KanSpec's own settings structure or file format. Even then, I use KanSpec to create a separate task worktree for the update and fold that branch back into the project when it is ready.

Most KanSpec features start with a problem I have met while using it: a terminal that should survive a development-server restart, two tools trying to use the primary checkout at once, or a Figma export that needs to reach one worktree without being committed. I usually build the smallest change that removes that problem, then see how it holds up on the next project.