v0.4.0 — multi-agent orchestration + currency cycle

Multi-agent orchestration, and a currency cycle that found real defects. This release adds the all-hands orchestration pattern across every runtime, and corrects a set of claims that had drifted from - or never matched - what the vendors actually do. Several were functional, not cosmetic: the sanitization gate this framework advertises was not firing, and one shipped template carried a model value no runtime accepts.

Vendor facts in this release were verified against official documentation and, where docs were inconsistent, against installed vendor binaries. That method is now written down as a repeatable cycle.

Added

• all-hands multi-agent orchestration. A coordinator skill that triages a work item, fans it out across the relevant agents in parallel waves, synthesizes their output, runs the validation gates, and reports. Shipped in all six runtime layouts (runtimes/.<vendor>/skills/all-hands/), each with its own vendor-correct frontmatter and a shared body kept in sync by tools/sync-skills.py. Consumer template at skills/examples/all-hands/.
• agentic-docs/multi-agent-orchestration.md and wiki/Multi-Agent-Orchestration.md - the six mechanisms a working orchestrator needs, and what breaks when each is missing. Framed as a composition of the existing four primitives, not a fifth primitive.
• docs-currency-auditor agent - owns vendor facts, version anchors, transition dates, and cross-mirror consistency. Produces evidence-backed findings; does not write the prose.
• doc-currency-check skill - the currency cycle in executable form, encoding the specific rot classes that have bitten this repo.
• tools/sync-hooks-to-settings.sh - merges the annotated hooks.json source of truth into settings.json, with JSON validation, refusal to overwrite an invalid destination, and idempotency.
• Tracked .claude/settings.json, which CLAUDE.md had documented but which did not exist.
• runtimes/mcp/render/render_devin.py and runtimes/.devin/config.template.json - six renderers now emit from runtimes/mcp/servers.yaml.
• Hook layouts in every runtime. runtimes/.codex/, .gemini/, .cursor/, and .devin/ now ship hooks in their vendor's native shape, plus a new top-level hooks/devin/ reference. All six layouts now deliver the hook support they advertise. Gemini is the shape exception: its hooks live inside the generated .gemini/settings.json, so the layout ships a documented merge-in snippet rather than a standalone config.

Fixed

• Hooks never fired. Claude Code executes hooks from settings.json; a project-level .claude/hooks/hooks.json is read only for plugins. This repo's own sanitization gate, the consumer template, and the worked example all shipped inert hooks while CLAUDE.md described a hook block as "a hard stop". All three are now wired through settings.json and the fix was verified by observing the hook actually run.
• model: flagship was written into live agent files. flagship/balanced/fast are SpecRoute's vendor-neutral tier abstractions; no runtime accepts them. Nine shipped agent files carried one. Real files now carry real values; tiers are confined to roster tables, with a per-vendor mapping in wiki/Agents.md. The frontmatter hook now flags a tier name used as a model value.
• Kiro's hook format was retired. Kiro IDE 1.0 (2026-06-25) replaced *.kiro.hook with .kiro/hooks/<name>.json v1; 0.x hooks do not execute until migrated. Examples migrated, trigger vocabulary updated, migration guidance added.
• Agent and skill frontmatter contracts were wrong in both directions. Only name and description are required; model and color are optional. internet: Yes|No was documented as a contract field but is not one - removed, with web access now expressed through tools. Roughly eleven real optional fields were undocumented.
• allowed-tools was described as a restriction. It pre-approves tools for the invoking turn; disallowed-tools is what removes them. The previous framing gave a false sense of confinement.
• A fabricated standard was cited. A claimed "150-line instruction budget" from the Agentic AI Foundation does not exist - the AGENTS.md standard specifies no schema and no length limit. The Linux Foundation stewardship is real and is now stated accurately; the length target is labelled as SpecRoute's own convention.
• The capability table over-claimed. It conflated "the vendor supports this" with "SpecRoute ships a runtime layout for this". Those are now distinct claims.
• agentic-docs/agentic-coding-model.md's vendor section predated the v0.3.0 convergence and contradicted the matrix in four places.
• Codex hook facts. v0.3.0 recorded 10 events; there are 11 (SessionEnd was missing), confirmed against both codex-cli 0.145.0 and the official docs. Codex reuses Claude Code's event names verbatim, but the overlap is close rather than total: no PostToolUseFailure, and only type: "command" handlers execute. Hooks are enabled by default, and the canonical [features] key is hooks with codex_hooks as a deprecated alias - an intermediate draft of this release wrongly retracted that as unverifiable, on the strength of a grep that could not prove the negative. Corrected against the vendor documentation.
• Kiro hook templates would not have loaded. The root version field is the string "v1", not the integer 1 - all four shipped example hooks carried the integer, and two migration tables instructed readers to convert toward it. Kiro IDE 1.0 also has 10 triggers, not 11: Manual was retired in favour of manual steering files, and one shipped example used it. Both fixed and verified against kiro.dev/docs/hooks/.
• MCP renderers declared a pyyaml dependency they never used, and the Gemini and Codex renderers silently dropped requires_env, omitting required environment wiring from the generated configs. All six now round-trip byte-identically against their committed templates.
• /audit checked the wrong files for matrix consistency and used a glob that matched nothing for Codex agents; /sanitize could not detect flattened project paths, which was the one path leak actually present.
• Maintainer home-directory paths removed from tracked files; .claude/agent-memory/ notes regenerated against disk after marking 21 existing files as "TODO".
• The SessionStart banner and /status reported a phantom missing docs/ directory, renamed to agentic-docs/ long ago.
• The sanitization gate could not see the files most likely to leak. /sanitize and pre-bash-sanitize.sh both scanned via git grep, which reads tracked content only - so a commit that adds a leaking file passed cleanly, and new content is exactly what leaks. 49 of this release's own files were invisible to it. Both now scan tracked plus untracked-but-not-ignored paths, verified by planting a canary in a new file and confirming the gate blocks. (The first attempt at this fix was itself broken: xargs returns 123 when any grep batch finds nothing, so an exit-status guard swallowed real hits.)
• Three inconsistencies caught by a post-implementation audit pass: hooks/cursor/hooks.template.json claimed 19 lifecycle events while wiring 18 against a documented 21 (now states the count and why the Tab/workspace hooks are omitted); wiki/Frontmatter-Contracts.md's intro still asserted the pre-correction "missing fields = won't register" rule that its own corrected body contradicts; and .claude/agent-memory/runtime-architect/vendor-matrix-progress.md still carried an in-flight banner and a pre-hooks capability snapshot.
• all-hands did not register as a skill at all. Its frontmatter carried disable-model-invocation: true, which removes a skill from the model-facing registry that Claude Code's @ mention picker completes against - so @all-hands returned only directories and no Skill row, and the skill looked broken while being structurally valid. Its tool list also named Task, which was superseded by Agent. The Claude copy now uses the documented space-separated allowed-tools scalar, while every runtime keeps only its native frontmatter. The portable body documents each runtime's dispatch mechanism without claiming Claude's subagent_type is universal.
• Cursor hook path resolution was documented two contradictory ways. hooks/cursor/scripts/README.md said paths resolve relative to hooks.json's parent; the runtime README said project root. Cursor's docs settle it: project hooks resolve from the project root (.cursor/hooks/scripts/x.sh), user hooks from ~/.cursor/ (./hooks/scripts/x.sh). The shipped configs were already correct - only the reference doc was wrong. This mattered because the beforeShellExecution gate sets failClosed: true, so an unresolvable path exits 127 and blocks every shell command rather than failing quietly.
• $ARGUMENTS now degrades gracefully. All six all-hands bodies are byte-identical by design, so a per-vendor substitution token cannot be expressed - but only Claude Code and Codex expand $ARGUMENTS. The body now tells the coordinator what to do when it reads the literal token instead of a work item.
• Kiro shipped one hook where every sibling ships three, with no stated reason, and its hooks README was the only one without a Setup section. It now ships the same session-start / sanitization-gate / frontmatter-check trio, plus setup steps that assert the scripts exist rather than only that the config parses.
• The wiki-parity CI gate was inert. It captured $? after a pipeline, which is tee's status, not the script's - so exit_code was pinned to 0 and both the staleness-annotation and hard-break-failure steps were unreachable. Now uses PIPESTATUS[0].
• /audit's vendor-matrix check could not detect cell-level drift - it compared only row count and the set of runtime-dir tokens, so ...

v0.3.0 — vendor capability convergence + doc currency cycle

Vendor capability convergence. All six supported tools now back the full capability set (skills, agents, commands, hooks, MCP) with real runtime templates - previously several vendors were rules/steering-only. The vendor docs and tooling were re-verified current against each vendor's mid-2026 releases (the vendor-doc currency cycle from the Phase 4 roadmap).

Added

• runtimes/.devin/ runtime layout for Devin Desktop (the relaunched Windsurf): rules, skills, per-profile agents/<name>/AGENT.md subagents, and workflows. .devin/ takes precedence over the legacy .windsurf/ layout.
• Skills, subagents, and command templates for Gemini CLI, Kiro, Cursor, and Windsurf - each in the vendor's native shape (previously these vendors shipped only rules/steering).
• Codex hooks wiring and a standalone .codex/agents/<name>.toml subagent example.
• MCP renderers render_kiro.py, render_cursor.py, and render_windsurf.py - six renderers now emit from the single source runtimes/mcp/servers.yaml.
• Per-vendor rule files rules/kiro-rules.md and rules/devin-rules.md.
• A review-spec worked-example command, mirrored across vendors in each native shape.

Changed

• tools/sync-skills.py rewritten to be body-aware: it syncs the SKILL.md body across all six vendors while preserving each vendor's distinct frontmatter contract. Agents are no longer synced - their formats diverge (Codex TOML, Devin AGENT.md directories).
• Codex agents are standalone TOML (name / description / developer_instructions), not Claude's flat Markdown - the matrix and sync-skills.py reflect this.
• Gemini commands migrated from the obsolete gemini_cli_config.json shell-command map to .gemini/commands/*.toml prompt templates.
• Claude MCP template renamed claude_desktop_config.template.json → mcp.template.json; it renders to the Claude Code CLI's .mcp.json (project) / ~/.claude.json (user), which is distinct from the Claude Desktop app's claude_desktop_config.json. Earlier docs conflated the two.
• Vendor matrix and supporting docs reconciled to the convergence model: capability tiers (Full / Near-full / Partial / Rules-only) retired; "three vendors consume MCP" corrected to all six (two emit shapes - JSON for everyone except Codex's TOML).

Fixed

• Hook event counts re-verified against official vendor docs and corrected repo-wide: Claude Code ~30 (was ~27/~31), Codex 10 and enabled by default (hooks feature; codex_hooks is a deprecated alias), Cursor ~21 (was ~19).
• Gemini SKILL.md frontmatter corrected to the Agent Skills open-standard name / description only (Claude-specific user-invocable / argument-hint / allowed-tools removed).
• Removed a hardcoded local filesystem path from wiki/README.md (sanitization).
• Fixed a broken cross-reference link in runtimes/.cursor/agents/README.md.

v0.2.4 — Version-string synchronization

[0.2.4] - 2026-05-19

Fixed

• CITATION.cff version and date-released fields advanced from 0.2.1 / 2026-05-14 to the current release. The field had been left stale during the v0.2.3 cut and was caught in the post-flip pre-publication review.
• ROADMAP.md and wiki/Home.md / wiki/Roadmap.md "Current version" lines synchronized to the current release. Phase 4 release-history bullets in both ROADMAP.md and wiki/Roadmap.md updated to reflect the v0.2.0 / v0.2.1 retraction and the v0.2.3 → v0.2.4 path.

v0.2.3 — Post-sanitization public release

[0.2.3] - 2026-05-19

First publicly available release. Supersedes the withdrawn v0.2.0 (2026-05-11) and v0.2.1 (2026-05-14) entries below; the shipping content is unchanged from v0.2.1.

Security

• Repository history sanitized end-to-end prior to public flip. A second-pass commit-message rewrite scrubbed a residual reference to the upstream private codebase that was reintroduced (while describing the prior sanitization) in the release-promotion commits behind v0.2.0 and v0.2.1. File content, authorship, and authorship timestamps are unchanged; only message bodies in the rewritten chain differ.
• The repository was additionally recreated from the clean local state to drop GitHub-preserved refs/pull/*/head refs that retained the tainted commits out-of-band of the rewrite. The pre-recreate repository is retained privately as Enovatr-Labs/SpecRoute-archive.
• The v0.2.0, v0.2.1, and v0.2.2 tag names were consumed during this process and are permanently reserved org-wide by the immutable-releases feature; v0.2.3 is therefore the equivalent shipping artifact for what would have been v0.2.1.

SpecForge v0.1.0 — Initial public release

Initial public release. Phases 1-3 of the roadmap complete; Phase 4 (maturity) in progress.

For the canonical, machine-readable changelog entry see CHANGELOG.md. For the citation-stable record see CITATION.cff.

What is SpecForge?

An open-source framework for spec-driven agentic software engineering — vendor-neutral across Claude Code, Codex, Gemini CLI, Kiro, Cursor, and Windsurf. SpecForge ships markdown content (templates, runtime layouts, worked examples) rather than application code; consumers drop the per-vendor runtime layouts into their own repositories and adapt the templates to their stack.

What's in v0.1.0

Framework foundation

• Repo skeleton, root files, vendor matrix, two-tier docs pattern.
• Implementation team in .claude/: 11 author agents, 4 contributor skills, 4 slash commands, 3 hooks, agent-memory directories.
• Sanitization infrastructure: gitignored wordlist + PreToolUse hook gate + /sanitize command + sanitization-auditor agent.

Artifact templates

• PRDs: full 23-section enterprise + lightweight + platform SRS.
• Specs: triplet (requirements-template.md + design-template.md + tasks-template.md) with stable IDs and back-reference contract; lightweight feature-spec; technical-spec; ADR.
• Agents: template + 7 archetypes + cross-vendor roster.
• Skills: folder-per-skill SKILL.md with full frontmatter contract.
• Commands: per-vendor templates (Claude markdown + Gemini JSON).
• Hooks: comprehensive coverage across all six vendors (~27 Claude / 6 Codex / 11 Gemini / 10 Kiro / ~19 Cursor / 12 Windsurf events).
• Prompts: master/phase/task production-grade trio + per-vendor sets + shared utility prompts.

Runtime layouts

• Per-vendor layouts under runtimes/.<vendor>/ for all six supported vendors.
• MCP single-source-of-truth (runtimes/mcp/servers.yaml) + working Python renderers.
• tools/sync-skills.py — cross-runtime skill / agent diff and copy.

Workflows and rules

• 5 workflow playbooks (prd-to-production, spec-to-implementation, agent-review-loop, testing-and-validation, release-readiness).
• Vendor-neutral engineering / code-review / security / documentation rules + per-vendor surfacing files.

Drop-in worked example: examples/sample-project/

• Self-contained, Claude-Code-only.
• Full PRD (23-section, prds/active/user-search.md), spec triplet (specs/user-search/), 5 ADRs (adrs/), 7 project-specific deep references (agentic-docs/).
• 28 prompt files: 1 global master + 4 phase masters + 22 numbered task prompts + 2 runtime operational prompts.
• 8 implementation-team agents, 4 slash commands, 3 hooks, agent-memory.
• Drop-in flow: copy folder → rename .template files → open Claude Code → run prompts/runtime/pickup-next-task.md.

Documentation and attribution

• 10-file agentic-docs/ framework reference library.
• MAINTAINERS.md (governance, decision-making, becoming-a-maintainer).
• CITATION.cff (CFF v1.2.0) — GitHub renders a "Cite this repository" button.
• NOTICE file (Apache 2.0 attribution).
• README sections: Maintainers, Citation, Mermaid spec-driven flow diagram with text fallback.

Get started

git clone https://github.com/Enovatr-Labs/SpecForge.git
cd SpecForge

# Read the canonical context
cat AGENTS.md

# Walk the worked example
ls examples/sample-project/

# Or copy the example into a new repo for drop-in use
cp -R examples/sample-project/. /path/to/your-new-repo/
cd /path/to/your-new-repo/
mv .claude/settings.local.template.json     .claude/settings.local.json
mv .claude/claude_desktop_config.template.json .claude/claude_desktop_config.json
mv .claude/.forbidden-strings.template.txt  .claude/.forbidden-strings.txt
# Open with Claude Code; run prompts/runtime/pickup-next-task.md

Citation

@software{Ihejimba_SpecForge_2026,
  author       = {Ihejimba, Chika},
  title        = {{SpecForge: An open-source framework for spec-driven agentic software engineering}},
  organization = {Enovatr Labs},
  year         = {2026},
  version      = {0.1.0},
  url          = {https://github.com/Enovatr-Labs/SpecForge},
  license      = {Apache-2.0}
}

A persistent DOI via Zenodo will be added at v1.0.

Roadmap

See ROADMAP.md. Phase 4 (Maturity) target items include additional worked examples, broader vendor support based on community demand, and the Zenodo DOI.

Maintainers

• Lead maintainer: Chika Ihejimba (chika@enovatr.com)
• Sponsoring organization: Enovatr Labs
• Security reports: security@enovatr.com (see SECURITY.md)
• Full governance: MAINTAINERS.md