Kerf: A Specification-First Workflow Management Tool for AI Agents

Kerf is a specification-first workflow management tool designed for AI Agents. Its core philosophy is derived from the woodworking wisdom of 'Measure twice, cut once' (think twice before acting), aiming to address issues like unstable code quality, requirement deviations, and rework caused by the 'code first, plan later' approach in AI-assisted development. Through a structured planning process (problem understanding → task decomposition → option research → specification writing → task breakdown), it enables recoverable and parallel development management. It offers two working modes: Plan-First (for existing projects) and Spec-First (for new projects), helping AI Agents and human developers fully plan before coding.

Against the backdrop of widespread AI-assisted software development, AI Agents often rush into the coding phase without sufficient planning and design. This approach easily leads to unstable code quality, misinterpretation of requirements, and extensive rework. Kerf's core philosophy was born to address this issue: by drawing on the woodworking principle of 'Measure twice, cut once', it forces AI Agents to complete a structured planning process before coding, fundamentally reducing the aforementioned problems.

Kerf offers two working modes:

1. Plan-First Mode: Suitable for projects with existing codebases. Before modifying code, the Agent writes a change plan, keeping the codebase as the source of truth. Ideal for adding features, fixing bugs, or refactoring.
2. Spec-First Mode: Suitable for new projects or teams requiring strict requirement management. Specifications define system goals; code that does not comply with specifications is considered erroneous. Ideal for greenfield projects or complex systems.

Its workflow is managed via a series of CLI commands (e.g., kerf new to create a task, kerf resume to restore progress, etc.), supporting state tracking, snapshot saving and recovery, parallel work, and more. Additionally, the Jigs process template system defines the stages an Agent must go through (Problem Space → Decomposition → Research → Spec Writing → Task Breakdown), with each stage producing corresponding artifacts to ensure a structured process.

Storage Architecture: Kerf stores tasks in the ~/.kerf/bench directory (outside the git repository). Each task includes a spec.yaml (for state tracking) and artifact files (products of each stage). Only when kerf finalize is executed does it enter the git repository to create a branch. Directory Structure: The project creates specs (specifications) and plans (change proposals) directories. The plans directory contains _plan.md (intentions, design) and beads.md (task breakdown), clearly separating 'what to do' from 'how to do it.' AI Integration: Supports bootstrapped installation (Agents can complete configuration automatically). Each stage provides structured prompts, clarifying goals, outputs, progress methods, and timing for human confirmation, and is compatible with AI coding Agents like Claude Code and Cursor.

Kerf brings multiple values to AI-driven development:

• Quality Improvement: Sufficient planning reduces rework and defects;
• Traceability: Decision-making processes are documented;
• Recoverability: Continuous work across sessions;
• Parallelism: Multiple independent tasks can be performed simultaneously;
• Team Collaboration: Specifications become a common language for communication.

Technically, Kerf is written in Go and distributed as a single binary, offering advantages such as cross-platform compatibility, fast startup, no runtime dependencies, and easy integration with existing toolchains.

Kerf represents an important direction for AI-assisted development tools: enabling AI to plan and design more intelligently, rather than just producing code faster. In software engineering, understanding problems and designing solutions are core challenges. Kerf helps AI Agents and human developers practice the engineering wisdom of 'Measure twice, cut once' through a mandatory structured planning process.

For teams looking to improve the quality of AI Agent development, Kerf provides a lightweight yet powerful workflow management solution that is worth trying and applying.