Claramap Builder

Agent Skills to Orchestrate Code Development.

Claramap Builder is an open-source agent skill that orchestrates software development with Claude Code and Codex. Install it in your coding harness and invoke /implement with a goal. It breaks the goal into manageable tasks, gives each worker the context it needs, and selects models based on task complexity. It validates what comes back, integrates the changes, and iterates until the requested behavior is implemented and the required checks pass.

The skill bundles instructions, references, spec templates, and executable helpers. The current implementation runs on Claude Code, Codex, and SpecStory, with SpecFlow guiding the workflow and Kiro-style specs using EARS structuring the feature documents. See attribution. The AgentSkill format can be adapted to other coding harnesses; the shipped setup uses Claude Code as its host. See harness support.

Install the skill · How it works · Architecture

Why I built this

I built Claramap Builder to make agent-driven development easier to coordinate, inspect, and improve. Three goals shaped it:

1. Orchestrate development across coding harnesses. Package the workflow as an AgentSkill so its instructions, context, and development practices can travel with the tools I use. The current implementation connects Claude Code and Codex; adapting another harness means wiring its execution and review capabilities.

2. Use a powerful orchestrator and delegate to specific subagents. Keep the full goal and project context with a capable coordinator. Give each subagent a scoped task, the context it needs, and a model matched to the work's complexity. The orchestrator validates what comes back, integrates it, and drives the next iteration.

3. Capture the work so I can improve the workflow. Preserve conversations, worker attempts, check results, and review findings. Use those records to understand repeated work, slow handoffs, and verification gaps, then make targeted improvements and evaluate them on later runs.

Where it fits

I wanted spec-driven development with a coordinator that owns the complete goal: assigning contextual work, validating the integrated result, and preserving evidence for the next run. Claramap Builder packages that workflow as an MIT-licensed agent skill with inspectable helpers.

These approaches operate at different layers and can be combined. A project's SPEC.md and use of RFC 2119 words such as MUST or SHOULD are authoring choices; this comparison does not treat them as a universal Codex or Claude Code spec format.

Claramap Builder's review helper checks that approval names the reviewed Git tree and that the captured content remains unchanged. The coordinator still judges reviewer independence, finding dispositions, and check results. Token reports show observed usage, not verified billing. See Architecture for the boundaries of those guarantees.

Architecture

See the Architecture guide for the full workflow, component responsibilities, installation requirements, and where specs and run records live.

These are separate projects used by the skill. Set up the tools before your first build; scripts/install.py only copies Claramap Builder's skill files.

Python 3.11+, Git, and macOS/Linux or WSL are also required for the helpers. The installation guide gives the setup order and checks. The architecture guide explains capture records and how the components connect.

Developer workflow

One-time setup

Install and authenticate the tools listed above, then install the skill:

git clone https://github.com/mathaix/claramap-builder.git ~/claramap-builder
cd ~/claramap-builder
python3 scripts/install.py implement

This copies the primary skill into ~/.claude/skills/implement, making /implement available across your projects. You do not repeat this installation for each build. See installation and updates for model access, project-specific installation, and upgrading the skill.

For each development goal

1. Start in your project. Open Claude with session capture from the product repository:

   cd /path/to/your/project
   specstory run claude --no-cloud-sync
   

   When using Codex workers, keep specstory watch --no-cloud-sync running in another terminal in the relevant worktree. See capture setup. An existing captured session can handle subsequent goals.

2. Describe the outcome. Give the skill a goal, constraints, and acceptance criteria:

   /implement Add a display-name setting. Save it using the existing profile API,
   preserve account permissions, and verify that it survives a page reload.
   

3. Build and iterate. Claude inspects the code, creates specs where needed, and breaks the goal into scoped work. It gives workers relevant context, selects models for task complexity, validates returned work, and integrates the changes. Failed checks and blocking review findings return for repair; missing access or unresolved requirements remain explicit blockers.

4. Inspect the result. Review the changed code, check results, independent review findings, and remaining gaps. Larger changes include requirements, design, and task progress in your product repository at specs/<slug>/. Run evidence stays in ~/.claude/implement/, and conversations in the worktree's .specstory/history/. See Where files live.

5. Commit and publish through your project workflow. Have the coordinator perform authorized Git and PR actions, or handle them yourself. Commit product specs with the code, keep raw run records local, and satisfy your repository's review and CI requirements. Specify deployment separately when you want it.

6. Resume or improve when needed. If interrupted, ask /implement to resume the existing run, reconcile Git and worker state, and continue remaining work. After a build, use /improve-workflow to investigate bottlenecks and recommend improvements.

The first-build guide provides more detail. The illustrative walkthrough shows the records and review process using a synthetic example.

Claramap Builder is MIT licensed. Model usage runs through your existing accounts and is subject to their billing.

Improve how the next build runs

The companion /improve-workflow skill examines completed runs to find repeated work, slow handoffs, and verification gaps. Ask why a small fix took an hour, where checks were duplicated, or what should change before the next build.

Install it from this repository:

python3 scripts/install.py improve-workflow

Then ask in your project:

/improve-workflow Review the last three runs. Find repeated work and bottlenecks,
and recommend improvements without editing yet.

It connects findings to recorded evidence and can apply targeted improvements when requested. Compare later runs to see whether those changes helped. See the workflow improvement guide.

Documentation

The installed agent instructions live in implement and improve-workflow. See the spec format and provenance.

Attribution

Claramap Builder combines existing ideas with its own orchestration and verification helpers. Credit for the foundations belongs to:

• Kiro: the three-file feature-spec layout (requirements.md, design.md, tasks.md), EARS-based requirements, tasks that cite requirement IDs, and keeping specs versioned with the code. See its requirements-first workflow and version-control guidance.
• EARS — Easy Approach to Requirements Syntax: the event-driven WHEN … THE SYSTEM SHALL … sentence form. Developed by Alistair Mavin and colleagues and first published in 2009, EARS predates both Kiro and SpecFlow.
• SpecFlow: the five-phase framing of intent, roadmap, tasks, execute, and refine, including assigning tasks to humans or AI. Its prompt-context concept carries into our worker briefs. /improve-workflow applies the Refine phase to the development workflow itself.
• SpecStory: the conversation-capture tooling used by the current implementation, and the publisher of SpecFlow. Its CLI is an installed dependency; its captured history supports recovery and workflow analysis.

The templates are our adaptations. Worker model routing, execution records, review snapshots, and recovery helpers are Claramap Builder's implementation. Kiro, EARS, and SpecFlow supply structure and methodology and require no separate installation for this skill; SpecStory supplies a tool that must be installed for capture.

Built by mathaix.