{"slug": "show-hn-self-improving-agentorchestrator-skill", "title": "Show HN: Self Improving AgentOrchestrator Skill", "summary": "Claramap Builder, an MIT-licensed open-source agent skill that orchestrates software development with Claude Code and Codex, was released by developer mathaix. The skill accepts a goal via the `/implement` command, breaks it into tasks, assigns each worker context and a model matched to task complexity, validates returned work, integrates changes, and iterates until required checks pass. The current implementation runs on Claude Code, Codex, and SpecStory, with SpecFlow guiding the workflow and Kiro-style specs using EARS structuring feature documents.", "body_md": "**Agent Skills to Orchestrate Code Development.**\n\n**Claramap Builder is an open-source agent skill that orchestrates software development with Claude Code and Codex.**\nInstall it in your coding harness and invoke `/implement` with a goal. It breaks the\ngoal into manageable tasks, gives each worker the context it needs, and selects\nmodels based on task complexity. It validates what comes back, integrates the\nchanges, and iterates until the requested behavior is implemented and the required\nchecks pass.\n\nThe skill bundles instructions, references, spec templates, and executable helpers.\nThe current implementation runs on **Claude Code, Codex, and SpecStory**, with\n**SpecFlow** guiding the workflow and **Kiro-style specs using EARS** structuring the\nfeature documents. See [attribution](#attribution).\nThe AgentSkill format can be adapted to other coding harnesses; the shipped setup\nuses Claude Code as its host. See [harness support](https://github.com/mathaix/claramap-builder/blob/main/docs/architecture.md#agent-skill-packaging-and-harness-support).\n\n[Install the skill](https://github.com/mathaix/claramap-builder/blob/main/docs/usage.md) · [How it works](https://github.com/mathaix/claramap-builder/blob/main/docs/implement.md) · [Architecture](https://github.com/mathaix/claramap-builder/blob/main/docs/architecture.md)\n\nI built Claramap Builder to make agent-driven development easier to coordinate, inspect, and improve. Three goals shaped it:\n\n1. \n**Orchestrate development across coding harnesses.** Package the workflow as an\nAgentSkill so its instructions, context, and development practices can travel with\nthe tools I use. The current implementation connects Claude Code and Codex;\nadapting another harness means wiring its execution and review capabilities.\n2. \n**Use a powerful orchestrator and delegate to specific subagents.** Keep the full\ngoal and project context with a capable coordinator. Give each subagent a scoped\ntask, the context it needs, and a model matched to the work's complexity. The\norchestrator validates what comes back, integrates it, and drives the next iteration.\n3. \n**Capture the work so I can improve the workflow.** Preserve conversations,\nworker attempts, check results, and review findings. Use those records to understand\nrepeated work, slow handoffs, and verification gaps, then make targeted improvements\nand evaluate them on later runs.\n\nI 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.\n\n| Approach | Documents and structure | Workflow support | \n|---|---|---|\n| [Kiro feature specs](https://kiro.dev/docs/specs/feature-specs/) | Requirements, design, and tasks; EARS acceptance criteria | Spec workflow integrated into Kiro | \n| [GitHub Spec Kit](https://github.com/github/spec-kit) | Specification, technical plan, and tasks | CLI setup, templates, and agent skills/commands for implementation and convergence | \n| [Codex project instructions](https://learn.chatgpt.com/docs/agent-configuration/agents-md) | `AGENTS.md` carries project instructions; teams supply their own spec conventions | Codex loads instructions into agent context; project tools and checks implement additional gates | \n| [Claude Code project instructions](https://code.claude.com/docs/en/memory) | `CLAUDE.md` carries project instructions; teams supply their own spec conventions | Claude loads instructions into agent context; project tools and checks implement additional gates | \n| **Claramap Builder** | Kiro-style specs, EARS, scoped worker briefs, exact-tree review records, and token reports | Agent skill plus worker, review, usage, and recovery helpers; currently coordinates Claude Code and Codex | \n\nThese approaches operate at different layers and can be combined. A project's\n`SPEC.md` and use of RFC 2119 words such as MUST or SHOULD are authoring choices;\nthis comparison does not treat them as a universal Codex or Claude Code spec format.\n\nClaramap Builder's review helper checks that approval names the reviewed Git tree\nand that the captured content remains unchanged. The coordinator still judges\nreviewer independence, finding dispositions, and check results. Token reports show\nobserved usage, not verified billing. See [Architecture](https://github.com/mathaix/claramap-builder/blob/main/docs/architecture.md) for\nthe boundaries of those guarantees.\n\nSee the [Architecture guide](https://github.com/mathaix/claramap-builder/blob/main/docs/architecture.md) for the full workflow, component\nresponsibilities, installation requirements, and where specs and run records live.\n\nThese are separate projects used by the skill. **Set up the tools before your first\nbuild; `scripts/install.py` only copies Claramap Builder's skill files.**\n\n| Project | What it is and how we use it | Install beforehand? | \n|---|---|---|\n| [Claude Code](https://github.com/anthropics/claude-code) | Anthropic's terminal coding agent. Hosts the skill, coordinates tasks and repairs, and runs a separate agent for independent review. | **Yes.** Install and authenticate; ensure access to the configured reviewer.[Setup](https://code.claude.com/docs/en/overview) . | \n| [Codex CLI](https://github.com/openai/codex) | OpenAI's terminal coding agent. Runs scoped workers with relevant context and a model selected for task complexity. | **Yes for delegated builds.** Install and authenticate before launching workers. Direct Claude tasks do not launch Codex.[Setup](https://github.com/openai/codex#quickstart) . | \n| [SpecStory CLI](https://github.com/specstoryai/getspecstory) | A tool that saves AI coding conversations as local Markdown. Captures coordinator and worker history for recovery and workflow analysis. | **Yes.** Install its CLI and enable capture before starting the documented workflow.[Setup](https://docs.specstory.com/integrations/terminal-coding-agents) . | \n| [SpecFlow](https://github.com/specstoryai/specflow) | SpecStory's methodology for building with software agents: intent, roadmap, tasks, execution, and refinement. Structures our specs and worker briefs. | **No.** Its planning approach is incorporated in the bundled templates and instructions.[Method guide](https://www.specflow.com/getting-started.html) . | \n\nPython 3.11+, Git, and macOS/Linux or WSL are also required for the helpers.\nThe [installation guide](https://github.com/mathaix/claramap-builder/blob/main/docs/installation.md#requirements) gives the setup order and\nchecks. The [architecture guide](https://github.com/mathaix/claramap-builder/blob/main/docs/architecture.md) explains capture records and\nhow the components connect.\n\nInstall and authenticate the tools listed above, then install the skill:\n\n```\ngit clone https://github.com/mathaix/claramap-builder.git ~/claramap-builder\ncd ~/claramap-builder\npython3 scripts/install.py implement\n```\n\nThis copies the primary skill into `~/.claude/skills/implement`, making `/implement`\navailable across your projects. You do not repeat this installation for each build.\nSee [installation and updates](https://github.com/mathaix/claramap-builder/blob/main/docs/installation.md) for model access, project-specific\ninstallation, and upgrading the skill.\n\n1. \n**Start in your project.** Open Claude with session capture from the product repository:\n\n```\ncd /path/to/your/project\nspecstory run claude --no-cloud-sync\n```\n\n When using Codex workers, keep `specstory watch --no-cloud-sync` running in another\nterminal in the relevant worktree. See[capture setup](https://github.com/mathaix/claramap-builder/blob/main/docs/installation.md#run-claude-and-codex-through-specstory) .\nAn existing captured session can handle subsequent goals.\n2. \n**Describe the outcome.** Give the skill a goal, constraints, and acceptance criteria:\n\n```\n/implement Add a display-name setting. Save it using the existing profile API,\npreserve account permissions, and verify that it survives a page reload.\n```\n\n3. \n**Build and iterate.** Claude inspects the code, creates specs where needed, and\nbreaks the goal into scoped work. It gives workers relevant context, selects models\nfor task complexity, validates returned work, and integrates the changes. Failed\nchecks and blocking review findings return for repair; missing access or unresolved\nrequirements remain explicit blockers.\n4. \n**Inspect the result.** Review the changed code, check results, independent review\nfindings, and remaining gaps. Larger changes include requirements, design, and task\nprogress in**your product repository at `specs/<slug>/`** . Run evidence stays in`~/.claude/implement/` , and conversations in the worktree's`.specstory/history/` .\nSee[Where files live](https://github.com/mathaix/claramap-builder/blob/main/docs/architecture.md#where-files-live) .\n5. \n**Commit and publish through your project workflow.** Have the coordinator perform\nauthorized Git and PR actions, or handle them yourself. Commit product specs with\nthe code, keep raw run records local, and satisfy your repository's review and CI\nrequirements. Specify deployment separately when you want it.\n6. \n**Resume or improve when needed.** If interrupted, ask`/implement` to resume the\nexisting run, reconcile Git and worker state, and continue remaining work. After a\nbuild, use`/improve-workflow` to investigate bottlenecks and recommend improvements.\n\nThe [first-build guide](https://github.com/mathaix/claramap-builder/blob/main/docs/usage.md) provides more detail. The\n[illustrative walkthrough](https://github.com/mathaix/claramap-builder/blob/main/skills/implement/references/example-run.md) shows the\nrecords and review process using a synthetic example.\n\nClaramap Builder is [MIT licensed](https://github.com/mathaix/claramap-builder/blob/main/LICENSE). Model usage runs through your existing\naccounts and is subject to their billing.\n\nThe companion `/improve-workflow` skill examines completed runs to find repeated work,\nslow handoffs, and verification gaps. Ask why a small fix took an hour, where checks\nwere duplicated, or what should change before the next build.\n\nInstall it from this repository:\n\n```\npython3 scripts/install.py improve-workflow\n```\n\nThen ask in your project:\n\n```\n/improve-workflow Review the last three runs. Find repeated work and bottlenecks,\nand recommend improvements without editing yet.\n```\n\nIt connects findings to recorded evidence and can apply targeted improvements when\nrequested. Compare later runs to see whether those changes helped. See the\n[workflow improvement guide](https://github.com/mathaix/claramap-builder/blob/main/docs/improve-workflow.md).\n\n| Guide | Purpose | \n|---|---|\n| [Your first build](https://github.com/mathaix/claramap-builder/blob/main/docs/usage.md) | Install, give a goal, inspect the result, and resume | \n| [How orchestration works](https://github.com/mathaix/claramap-builder/blob/main/docs/implement.md) | Task scoping, worker selection, validation, and completion | \n| [Architecture](https://github.com/mathaix/claramap-builder/blob/main/docs/architecture.md) | Claude, Codex, SpecStory, SpecFlow, capture records, and harness support | \n| [Installation and configuration](https://github.com/mathaix/claramap-builder/blob/main/docs/installation.md) | Prerequisites, model policy, project setup, updates, and removal | \n| [Improve the next build](https://github.com/mathaix/claramap-builder/blob/main/docs/improve-workflow.md) | Investigate runs and apply evidence-based improvements | \n| [Illustrative walkthrough](https://github.com/mathaix/claramap-builder/blob/main/skills/implement/references/example-run.md) | Follow a request through specs, checks, and review | \n| [Contributing](https://github.com/mathaix/claramap-builder/blob/main/CONTRIBUTING.md) | Repository structure, tests, and contribution guidance | \n\nThe installed agent instructions live in [implement](https://github.com/mathaix/claramap-builder/blob/main/skills/implement/SKILL.md) and\n[improve-workflow](https://github.com/mathaix/claramap-builder/blob/main/skills/improve-workflow/SKILL.md). See the\n[spec format and provenance](https://github.com/mathaix/claramap-builder/blob/main/skills/implement/references/spec-format.md).\n\nClaramap Builder combines existing ideas with its own orchestration and verification helpers. Credit for the foundations belongs to:\n\n- **[Kiro](https://kiro.dev/docs/specs/feature-specs/):** the three-file feature-spec\nlayout (`requirements.md` ,`design.md` ,`tasks.md` ), EARS-based requirements,\ntasks that cite requirement IDs, and keeping specs versioned with the code.\nSee its[requirements-first workflow](https://kiro.dev/docs/specs/feature-specs/requirements-first/) and[version-control guidance](https://kiro.dev/docs/specs/best-practices/) .\n- **[EARS — Easy Approach to Requirements Syntax](https://alistairmavin.com/ears/):** the event-driven`WHEN … THE SYSTEM SHALL …` sentence form. Developed by Alistair\nMavin and colleagues and first published in 2009, EARS predates both Kiro and SpecFlow.\n- **[SpecFlow](https://github.com/specstoryai/specflow):** the five-phase framing of\nintent, roadmap, tasks, execute, and refine, including assigning tasks to humans or\nAI. Its[prompt-context concept](https://www.specflow.com/getting-started.html#step-41-prepare-your-ai-assistant) carries into our[worker briefs](https://github.com/mathaix/claramap-builder/blob/main/skills/implement/assets/templates/brief.md) .`/improve-workflow` applies the Refine phase to the development workflow itself.\n- **[SpecStory](https://github.com/specstoryai/getspecstory):** the conversation-capture\ntooling used by the current implementation, and the publisher of SpecFlow. Its CLI\nis an installed dependency; its captured history supports recovery and workflow analysis.\n\nThe 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.\n\nBuilt by [mathaix](https://github.com/mathaix).", "url": "https://wpnews.pro/news/show-hn-self-improving-agentorchestrator-skill", "canonical_source": "https://github.com/mathaix/claramap-builder", "published_at": "2026-09-21 14:30:23+00:00", "updated_at": "2026-09-21 14:54:24.183268+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Claramap Builder", "Claude Code", "Codex", "SpecStory", "SpecFlow", "Kiro", "GitHub Spec Kit", "mathaix"], "alternates": {"html": "https://wpnews.pro/news/show-hn-self-improving-agentorchestrator-skill", "markdown": "https://wpnews.pro/news/show-hn-self-improving-agentorchestrator-skill.md", "text": "https://wpnews.pro/news/show-hn-self-improving-agentorchestrator-skill.txt", "jsonld": "https://wpnews.pro/news/show-hn-self-improving-agentorchestrator-skill.jsonld"}}