CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

[Unreleased]

Changed

• docs: README rewritten as a slim front door (379 → ~104 lines, EN + pt-BR). Leads with the live catalog site, three-option quick start, one linked component table with real counts (111 skills / 27 hooks / 22 agents / 22 servers / 21 collections / 14 tools), and a curated guide index into docs/guides/. Maintainer-only content moved out verbatim: quality checks / mutation testing / release pre-flight / parity audit → docs/guides/maintenance.md; troubleshooting → docs/guides/troubleshooting.md.

Fixed

• ci: deploy-web.yml now fires automatically after a release. Releases created by release.yml with GITHUB_TOKEN never emit a release: published event to other workflows (GitHub anti-recursion rule), so the webapp deploy silently required a manual workflow_dispatch since June. release.yml now triggers deploy-web.yml explicitly via gh workflow run (exempt from the rule) after creating the tag.

[0.31.0] - 2026-08-21

Added

• feat(kit): Zed and VSCode adapters (#321). Both follow the project-local editor pattern (cursor/windsurf): rules file, skills dir, providers config, MCP merge. Zed writes .rules and merges MCP servers into .zed/settings.json under context_servers; VSCode writes .github/copilot-instructions.md and merges MCP servers for Copilot.
• feat(kit): Kimi Code CLI adapter (#328). Kimi has real event-driven hooks (PreToolUse, PostToolUse, UserPromptSubmit, SubagentStart/Stop) via [[hooks]] TOML entries in config.toml, with a stdin-JSON contract compatible with forge-kit's existing PostToolUse hook scripts unchanged.
• feat: Harness quality + cost instrumentation — 3 tools + 1 hook. Catalog entries for the "optimize what you measure" toolchain: harness-skill-scorecard (structural skill-quality score: HARD invalid-YAML/unclosed-fence vs SOFT missing-stop-conditions, regression-gateable) and memory-quality-scorecard (memory-corpus quality: HARD no-frontmatter/invalid-YAML vs SOFT thin/orphan/stale/duplicate) — both category: benchmarking; harness-metrics (category: observability) aggregates both scorecards + self-test + rolling 7-day token cost into a dated JSONL time-series with a visible improvement/regression trend; and the session-cost-telemetry SessionEnd hook, which appends per-session tokens + estimated USD by model (Opus/Sonnet/Haiku pricing table) to ~/.claude/metrics/sessions.jsonl so down-tiering shows up as dollars saved. Scripts identity-sanitized; catalog:validate + schema + leak checks pass. Catalog: tools 11→14, hooks 26→27.

Changed

• feat(web): Real SVG icons replace Unicode glyphs. Catalog kind icons (KIND_ICONS in apps/web/src/lib/ui.ts) are now inline feather-style SVGs (stroke currentColor) instead of Unicode characters, and the copy-button feedback uses an SVG check instead of a checkmark glyph. Consistent rendering across OS/font stacks.
• fix(web): getTools() no longer breaks the build when a tool dir contains subdirectories (e.g. local __pycache__): script file selection now filters to regular files via withFileTypes, fixing a local-only EISDIR during astro build.
• test: Scoped mutation testing + 28 negative tests from survivor analysis (#329). stryker.conf.json scoped to 3 jest-covered leaf modules; mutation score 25.89 → 35.09 total / 44.99 → 59.83 covered; baseline in reports/mutation/baseline.json.
• docs: README improved for discoverability and user journey (#309); Ecosystem Heritage section added (EN + pt-BR) (#336, #337).

Deprecated

• chore(kit/rag): kit/rag deprecated in favor of the standalone shelfmark repo (#335).

[0.30.0] - 2026-06-24

Removed

• 28 external link-out catalog entries removed per quality gates ADR (docs/decisions/2026-06-24-catalog-curation-quality-gates.md): 8 firecrawl-* (dead private repo), 10 eng-* (404 paths), 1 brainstorming (404), 9 anthropics/skills entries (doc-coauthoring, docx, pdf, xlsx, slack-gif-creator, web-artifacts-builder, internal-comms, claude-api, frontend-design) that fail depth/trigger gates. Also removed empty web-scraping collection. Retained: skill-creator, webapp-testing, mcp-builder (all pass gates); forgekit-owned entries exempt.

Added

• skill-leak-check CI lint — fail the build on maintainer-environment leaks in authored skills. New scripts/skill-leak-check.js (wired into npm run validate) scans packages/** and locales/** SKILL.md for a denylist of literal maintainer tokens (/Users/lucassantana, -Users-lucassantana, /Volumes/External HD, oac-workstation). Deliberately literal, not pattern-class: generic /Users///Volumes/ would false-positive on the catalog's own placeholder examples (/Users/jdoe, /Users/yourname) and on the public GitHub org github.com/LucasSantana-Dev/.... ~/.claude/ and $HOME are allowed. Rationale in docs/decisions/2026-06-22-skill-leak-lint.md.

Fixed

• Scrubbed 22 maintainer-environment leaks across 13 authored skills (caught by the new lint): canonical_source home-dir paths → ~/; recall project-slug → <project> (EN + pt-BR); worktree-root examples (branch-hygiene, repo-bootstrap) → $HOME/.worktrees; mac-optimize external-disk refs → /Volumes/<external-drive>. Reactive scrubbing had previously missed the recall leak across multiple commits; the lint makes this proactive. See also docs/decisions/2026-06-22-recall-skill-portability.md.

Changed

• OpenCode harness templates: repoint default + agent models to OpenRouter for robust multi-provider failover. Primary default model: openai/gpt-5.3-codex → openrouter/z-ai/glm-4.6; codex-primary: openai/gpt-5.3-codex → openrouter/qwen/qwen-2.5-coder-32b-instruct; architect: anthropic/claude-opus-4-1 → openrouter/moonshotai/kimi-k2-thinking; fast: anthropic/claude-sonnet-4-5 → openrouter/qwen/qwen-2.5-coder-7b; reviewer & planner: anthropic/claude-sonnet-4-5 → openrouter/z-ai/glm-4.6. Added a free escape-hatch agent: opencode/deepseek-v4-flash-free (free-tier OpenCode Go model) to handle rate-limit or no-credits fallback scenarios. Disabled unauthenticated context7 MCP by default (enabled: false) with authentication comment. Prevents subagent stalling on unconfigured/unroutable providers. Applied to all three templates: primary setup, core reference, and pt-BR locale mirror.

• Curated index — link to external skills, don't re-host them. forgekit no longer vendors SKILL.md body copies for skills it didn't author. The externally-sourced catalog skills (from anthropics/skills, obra/superpowers, alirezarezvani/claude-skills) now keep only their manifests as curated link-out entries (source + homepage); forgekit-authored skills keep their bodies. forge install <external-skill> fetches the body from the upstream source on demand instead of serving a copy; skill detail pages render "maintained upstream — view at source" for body-less entries. Rationale in docs/decisions/2026-06-06-curated-index-link-dont-rehost.md.

[0.29.1] - 2026-06-18

Added

• Workflow alignment with local standards: Added 7 Claude Code hooks (bash-prefilter, protect-files, turn-counter, session-budget-guard, sessionend-memory-writer, pre-compact-summary, post-compact-reset) for safety, session management, and context hygiene. Added 2 composite skill templates (session-bootstrap, scope-and-execute).

• 6 new catalog agents: homelab-ops (Docker/k3s/Pi-hole/Caddy), lucky-bot-dev (TypeScript monorepo), infra-reviewer (read-only config reviewer), linkedin-automation (Chrome extension), rag-engineer (hybrid retrieval), discord-bot-factory (Discord.js patterns). Catalog now has 28 agents total.

Changed

• CLAUDE.md rewrite: Replaced generic behavioral guidelines (lines 73-137) with battle-tested rules from local workflow — Hard Rules, Code Standards, Workflow, Testing, Documentation Governance, Security, Gotchas.

[0.29.0] - 2026-06-10

Added

• Claude Code platform docs: Three new catalog guides covering recent platform features — claude-code-workflows (dynamic multi-agent orchestration), claude-code-cloud-review-plan (ultrareview + ultraplan, research preview), and claude-code-routines-monitor (scheduled/event-driven agents + background event streaming). Wired into multi-agent-orchestration, spec-and-planning, and infrastructure-and-devops collections.

• Three new catalog entries (v0.29.0 slice 3): Claude Managed Agents doc (Anthropic's hosted agent runtime, beta since April 2026), Braintrust doc (eval-first LLM + agent scoring platform, with AutoEvals open-source library), Brave Search MCP server (privacy-first web search, image, news, video). All wired into existing collections: Managed Agents → multi-agent-orchestration, Braintrust → verification-review-gate, Brave Search → research-and-writing.

Fixed

• Wired 6 orphan skills into collections: adt-specs-aggregate-roadmap → spec-and-planning, adt-sync-pt-parity + claude-automation-recommender → skill-authoring, gemini-context-cache → token-and-context-optimization, gemini-grounding-config → api-and-mcp-development, vertex-ai-setup → local-models-starter.

[0.28.0] - 2026-05-27

Added

• Initial slash commands in catalog: compact, review, plan — installable via forge-kit install <id> (#248).

Fixed

• Homepage entry count now includes tutorials and docs (#247).

[0.27.0] - 2026-05-27

Added

• Agent detail pages with ## IDE and ## CLI headings now render as clickable tab panels with URL hash deep-linking (#240).

Changed

• Deps: astro 6.3.5 → 6.3.8, @astrojs/sitemap 3.7.2 → 3.7.3, tsx 4.19.2 → 4.22.3.

[0.26.2] - 2026-05-27

Fixed

• adt-* skill display names no longer leak the adt- ID prefix — 69 manifest name fields updated (e.g. "Adt CI Watch" → "CI Watch", "Adt RAG" → "RAG"); pt-BR translations updated to match (#238).

Changed

• Catalog culled from 154 → 135 skills: removed deprecated Codex platform skills (#232), incomplete stub skills (#233), personal/niche-scope skills (#234), and editor-specific Cursor cluster skills (#235).
• 26 previously orphaned skills (zero collection memberships) wired into existing collections (#237).

[0.26.1] - 2026-05-27

Fixed

• CI deploy workflow now triggers only on release published or manual dispatch, preventing unintended deploys on push to main (#215).
• Added pnpm cache to workspace validation job; pinned all GitHub Actions action SHAs for supply-chain integrity (#216).

Changed

• Catalog collections trimmed to 6–10 skill items each; aws-kiro-ide-workflow, document-generation, and platform-environments collections removed; adt-dep-lifecycle, adt-perf-audit, and adt-test-pipeline composites wired into relevant collections.
• token-and-context-optimization and spec-and-planning collections trimmed to 8 skill items each.
• 4 skills rewritten to compact SKILL.md + separate REFERENCE.md pattern.
• env-kiro agent comprehensively rewritten with verified Kiro IDE/CLI docs: all 9 hook events, correct MCP config path (.kiro/settings/mcp.json), 4 steering inclusion modes, 4 spec-driven workflow variants, EARS notation, Kiro Powers, current pricing and model tables, auth options (v0.3.0).

[0.26.0] - 2026-05-21

Added

• Optional provider field in manifest schemas (skill, agent, hook, command, tool, server); validator emits advisory warnings for entries missing it, pointing to #155 backfill (closes #154).
• docs/PROVIDERS.md — provider taxonomy: all 6 provider IDs, install-path conventions, field rules, and backfill promotion logic; pt-BR mirror at locales/pt-BR/docs/PROVIDERS.md (closes #162).

[0.25.0] - 2026-05-21

Added

• 8 Firecrawl skills to the catalog (firecrawl-* namespace):
  • firecrawl — web scraping, search, crawling, and page interaction via the Firecrawl CLI
  • firecrawl-search — search the web and return Markdown results with Firecrawl
  • firecrawl-scrape — scrape a single URL into clean Markdown or structured JSON
  • firecrawl-crawl — crawl an entire site and return all pages as Markdown
  • firecrawl-map — map all URLs on a site before deciding what to scrape
  • firecrawl-download — download files (PDF, CSV, binary) discovered during crawls
  • firecrawl-instruct — drive a real browser with natural-language instructions via Firecrawl
  • firecrawl-agent — autonomous AI agent that navigates complex sites and returns structured JSON
• web-scraping collection — surfaces all 8 Firecrawl skills in a dedicated collection.
• pt-BR translations on all 8 new manifest entries.

Changed

• Catalog skill count: 155 → 163.

[0.24.0] - 2026-05-14

Added

• 7 ops/recipe skills to the catalog (adt- namespace):
  • adt-ci-watch — PR state machine + Monitor pattern + already-merged race handling
  • adt-next-priority — decision order + blocker escape hatches (self-PR enforce_admins toggle, webhook desync)
  • adt-sync-memories — durable memory writes across systems
  • adt-rag-curate — gap-filling patterns for the RAG corpus (also moved from kit; was unprefixed before)
  • adt-force-merge-self-pr — wraps the 4-step enforce_admins toggle for self-PR merges through protected branches
  • adt-unstick-pr — recreate a PR whose head SHA disagrees with its branch ref (webhook desync); skips futile force-push loops
  • adt-parallel-investigate — fan out N agents in one tool-use block when answering the same question across multiple targets
• pt-BR translations on all 6 new manifest entries.

Changed

• adt-plan — added extend-vs-new plan rule, skip rule, and a worked example.
• adt-loop — added context-budget stop condition (>75%) and parallel-mode guidance while a Monitor is running.
• adt-knowledge-loop — added worked example with skipped-phase rationale.
• adt-rag-curate content trimmed and restructured into 3 named patterns + a cheatsheet (183 → 98 lines).
• adt-sync-memories trimmed; removed forge-space-specific bloat (176 → 88 lines).
• Catalog skill count: 149 → 155.

[0.23.0] - 2026-05-13

Added

• 4 tool-builder skills for authoring Claude Code primitives: agent-development (subagent frontmatter + design), command-development (slash command authoring with frontmatter, args, AskUserQuestion patterns), hook-development (PreToolUse/PostToolUse/Stop/etc. hook events + prompt-based API), create-subagent (reusable specialized-agent design).
• Collection cross-reference — all 4 surfaced under skill-authoring.

Changed

• Catalog skill count: 145 → 149.

[0.22.0] - 2026-05-13

Added

• 4 Claude-Code ops skills for managing the Claude Code setup itself: hook-effectiveness (audit hook fire rate, latency, exit codes), mcp-audit (read-only MCP-usage diagnostic), claude-md-improver (audit + improve CLAUDE.md files), claude-automation-recommender (analyze a codebase and recommend hooks/skills/agents/MCP servers).
• Collection cross-references — new skills surfaced under claude-code-power-user (hook-effectiveness, claude-md-improver, claude-automation-recommender) and mcp-ops-and-recovery (mcp-audit).

Changed

• Catalog skill count: 141 → 145.

[0.21.0] - 2026-05-13

Added

• 7 release-flow composite skills promoted from Codex/Claude-private into the shared catalog: release-cut (batch release branch into one tagged version), branch-hygiene (one-pass cleanup of stale branches + worktrees), dep-sweep (batch-process bot PR queues), incident-followup (postmortem chain), hotfix (emergency main-branch bypass), repo-bootstrap (one-pass release-branch workflow setup), first-pr (safe-first-PR onboarding chain). These close the doc→installable loop opened by the codex-parity doc in v0.20.0, which referenced them as the composite-first principle anchors.
• Collection cross-references — new composites surfaced under release-and-deploy, git-and-version-control, production-debugging, and codebase-onboarding.

Changed

• Catalog skill count: 134 → 141.

[0.20.0] - 2026-05-13

Added

• 4 new portable skills promoted from Codex-only into the shared catalog: debug (systematic root-cause analysis), dev-assets-sync (workspace backup), handoff-diet (no-wakeup-polling pattern), mac-optimize (macOS resource-pressure triage with boost.sh + diagnose.sh companions).
• codex-parity doc — full setup guide for bringing OpenAI Codex CLI into parity with Claude Code on the same machine: symlinked skill catalog, .agents/memory/ mirror, composite-first AGENTS.md section, shared RAG MCP wiring.
• review-tools tool — cross-repo PR review installer (Danger + CodeRabbit + Sonar templates per stack) — promoted from packages/core/review-tools/ after PR #173 merged.
• 11 MCP server catalog entries — fetch, filesystem, firecrawl, git, google-drive, notion, rag-index, sonarqube, ssh, tavily, context-mode. Each entry includes the canonical command/args/env block needed by Codex/Claude MCP hosts.
• Collection cross-references — new entries surfaced under api-and-mcp-development, mcp-ops-and-recovery, token-and-context-optimization, context-rag-launchpad, solo-developer-starter, production-debugging, and verification-review-gate.

Changed

• Catalog server count: 10 → 21.
• Catalog skill count: 130 → 134.
• Catalog tool count: 10 → 11.
• Catalog doc count: 21 → 22.

[0.19.0] - 2026-05-09

Added

• 27 new catalog skills + composite workflow ecosystem (#166) — 17 composite skills that chain related skills with reconciliation rules and explicit stop conditions, plus 10 individual skills + 4 merged-cluster skills. See PR #166 for the full list.
• Web — SEO + accessibility + UX overhaul (#165) — provider and trust pages, improved typography and contrast, dropped pt-BR locale duplication, accessibility audit fixes across detail pages.

Removed

• apps/web/src/pages/pt-br/ locale routes (#165) — duplicated content moved to canonical English pages with lang attribute switching.

[0.18.0] - 2026-05-07

Added

• 10 new catalog collections — multi-agent-orchestration, rag-maintenance, spec-and-planning, token-and-context-optimization, git-and-version-control, document-generation, infrastructure-and-devops, api-and-mcp-development, codebase-onboarding, skill-authoring. Catalog grows from 13 → 22 collections, covering ~85% of the 103 available skills. (#132)
• 6 RAG maintenance skills — adt-rag-coverage, adt-rag-curate, adt-rag-drift, adt-rag-index-rebuild, adt-rag-inspect, adt-rag-quality — full lifecycle for auditing, curating, and rebuilding the local RAG index. (#132)
• 3 missing skill manifests — adt-token-audit, adt-smart-commands, adt-smart-model-route added to catalog so they are installable via CLI. (#132)
• feat(skills): add sync-ai-tools and warp-ai-setup for cross-editor parity

Changed

• Collections i18n schema — all 22 collection YAML files migrated to translations.pt-BR block (from legacy root-level name_pt/description_pt fields). (#132)
• Web UI — EntryHeader component — shared component replaces emoji + inline-style headers across all 16 detail pages (8 en + 8 pt-BR). Kind-aware accent colors, typographic glyphs, accessible aria-hidden decoration, prefers-reduced-motion guard on scroll-reveal. (#133)

Removed

• discord-bot-dev collection — too platform-specific; all constituent skills are available in broader collections (security-first-dev, verification-review-gate, production-debugging). (#132)

Fixed

• apps/web/src/lib/catalog.ts path resolution — findCatalogDir() replaces the hardcoded ../../../../ traversal that broke under Astro 6 / Vite 6 compiled module depth changes.
• Web UI a11y — skill and server detail pages now show license-only footer correctly; empty <p> tag guard added when both homepage and license are absent. (#133)

[0.17.0] - 2026-04-18

Added

• resume skill (kit/core/skills/resume.md) — first-class session recovery that detects state from handoff files, .agents/plans/*.json, git, and open PRs, then re-enters the loop at the last-incomplete phase without repeating work. Closes the README gap where resume was listed but had no dedicated file.
• SKILL.md adoption pattern (#80) — vendor-neutral skill discovery pattern that lets multiple AI tools find the same skill file without duplicating content.
• dev-assets-sync workspace backup skill (#81) — on-demand rsync of Claude/Codex configs, memories, standards, hooks, skills-index, and per-project dev files to a private dev-assets repo.
• Tier-based tool governance test — new CI invariant that haiku agents cannot hold write-access tools and only opus agents can hold delegate-access tools (Agent spawn).

Changed

• loop skill Resume section now delegates to the new resume skill instead of carrying inline recovery steps.
• BACKLOG.md + docs/roadmap.md reconciled — 7 AI-guides specs (PR #61) promoted from proposed to archived/shipped; backlog.json entries for hooks-manifest, dispatch-skill, schedule-skill, memory-skill, parity-audit-script, mcp-tool-registry, agent-tool-access, and cost-tracking marked done to match shipped artifacts in-repo.
• BACKLOG.md snapshot header refreshed from stale v0.11.0 (2026-04-03) to v0.16.0 + current remaining gaps.

[0.16.0] - 2026-04-16

Added

• 3 New Patterns — mcp-tool-lazy-loading (dynamic MCP tool registration), agent-evals-ci (autonomous evaluation pipeline in GitHub Actions), benchmark-reality-gap (empirical vs. theoretical performance analysis)
• 5 New Autonomous-Dev Skills — route.md (request routing), orchestrate.md (multi-step task coordination), fallback.md (graceful degradation), add.md (code generation), secure.md (security analysis)

Fixed

• NIST AI 100-2 reference link in patterns documentation

Changed

• Roadmap refresh for Q2 2026

[0.15.0] - 2026-04-16

Added

• Agent Sandboxing Patterns — Isolation strategies for untrusted agent code: process boundaries, capability revocation, audit logging, recovery mechanisms, and sandboxing layer selection guide
• OpenTelemetry GenAI Instrumentation — Production observability for multi-agent systems: span creation for agent/tool/LLM steps, metric collection (latency, token count, cost), trace context propagation, and dashboard templates
• Prompt Injection Defense — Attack surface analysis and mitigation strategies: input sanitization patterns, structured parsing, output validation, and detection rules
• Cost-Aware Routing — Token/cost prediction before model selection: embedding vector similarity search over model capability profiles, cost-latency Pareto frontiers, budgeted sampling, and telemetry-driven model assignment
• Local-First Agents — Edge deployment patterns: embedding cache strategies, on-device inference routing, network failure recovery, and sync protocols with cloud fallback
• Reasoning Model Prompting — Structured thought patterns for o1/Claude-with-thinking: chain-of-thought scaffolding, hypothesis validation, error injection during reasoning, and token-budget planning
• AI Skill Stewardship & Prompting Discipline best practices — Governance patterns for maintaining a curated skill library: skill lifecycle (conception → triage → graduation → archival), version-pinned imports, skill auto-invocation conditions, and prompting discipline standards (explicit grounding, isolation, testing)
• Plugin Audit Skill (kit/core/skills/plugin-audit.md) — Marketplace governance: version compatibility checks, security scanning, feature gap analysis, upgrade path validation, and certification readiness checklist
• Bilingual README Sync Skill (kit/core/skills/bilingual-readme-sync.md) — Multi-language documentation automation: PT ↔ EN synchronization, diff detection, translator sourcing, and Markdown structure preservation
• Environment variable generalization across multi-repo setups: CURATED_REPOS now accepts comma-separated paths (both file and remote URLs); email placeholder moved to env config; kit/core/rules.md and agents.json now reference env-substituted values for broader deployment flexibility
• GitHub Actions Marketplace discovery pattern — automated audit of installed GitHub Apps and Actions for deprecation + cost tracking

Fixed

• None (clean release)

[0.14.0] - 2026-04-15

Features

• AI Guides wave 1 — docs/guides + hooks + agents + skills (#61)
• add 8 automation skills from 2026-04-15 session (#60)
• portable env-var configuration (#55)
• add rag + specs modules (#54)
• handoff system, session-budget rules, resume anti-false-completion (#51)
• MCP patterns, multi-agent orchestration, model serving, AI observability (#49)
• skill auto-invocation — agents apply skills autonomously based on situation (#48)
• add RAG, eval, and self-heal skills + pattern guides from AI engineering curriculum (#47)
• add release helper preflight
• enforce canonical agent tool registry (rebased) (#39)
• consolidate setup-repo content — 10 portable skills, templates, and helper scripts (#37)
• install portable hooks manifests for supported adapters (#35)
• add company templates for solopreneur, startup MVP, agency, and open-source maintainers (#31)
• add heartbeat routine system with schedule config and validation (#30)
• add formal JSON schemas for all core configs (#29)
• adapter parity, MCP expansion, c7score README, language reviewers, harness audit (#27)

Fixes

• Backfill [0.12.0] changelog and wire ESLint into validate workflow
• catch release preflight parity blockers (#41)
• add oh-my compat support to remaining adapters (#28)

Documentation

• for-teams intro — adoption, governance, concrete wins (#59)
• add AI-assisted summary and Portuguese onboarding
• refresh claude and codex guidance
• add backlog map and README link (#32)

CI

• add OpenCode plugin typecheck lane (#34)

Chores

• bump trufflesecurity/trufflehog from 3.94.2 to 3.94.3 (#52)
• release v0.13.0 (#57)
• remove handoff-specific skills (#58)
• bump prettier from 3.8.1 to 3.8.3 (#56)
• bump trufflesecurity/trufflehog from 3.94.1 to 3.94.2 (#42)
• bump eslint from 10.1.0 to 10.2.0 (#43)
• release v0.12.0 — consolidated setup content, 29 skills (#38)
• reconcile backlog state and add triage automation (#33)

[0.13.0] - 2026-04-15

Features

• portable env-var configuration (#55)
• add rag + specs modules (#54)
• handoff system, session-budget rules, resume anti-false-completion (#51)
• MCP patterns, multi-agent orchestration, model serving, AI observability (#49)
• skill auto-invocation — agents apply skills autonomously based on situation (#48)
• add RAG, eval, and self-heal skills + pattern guides from AI engineering curriculum (#47)
• add release helper preflight
• enforce canonical agent tool registry (rebased) (#39)
• consolidate setup-repo content — 10 portable skills, templates, and helper scripts (#37)
• install portable hooks manifests for supported adapters (#35)
• add company templates for solopreneur, startup MVP, agency, and open-source maintainers (#31)
• add heartbeat routine system with schedule config and validation (#30)
• add formal JSON schemas for all core configs (#29)
• adapter parity, MCP expansion, c7score README, language reviewers, harness audit (#27)

Fixes

• Backfill [0.12.0] changelog and wire ESLint into validate workflow
• catch release preflight parity blockers (#41)
• add oh-my compat support to remaining adapters (#28)

Documentation

• add AI-assisted summary and Portuguese onboarding
• refresh claude and codex guidance
• add backlog map and README link (#32)

CI

• add OpenCode plugin typecheck lane (#34)

Chores

• bump prettier from 3.8.1 to 3.8.3 (#56)
• bump trufflesecurity/trufflehog from 3.94.1 to 3.94.2 (#42)
• bump eslint from 10.1.0 to 10.2.0 (#43)
• release v0.12.0 — consolidated setup content, 29 skills (#38)
• reconcile backlog state and add triage automation (#33)

[0.12.0] — 2026-04-04

Added

• Consolidated setup-repo content (#37): 10 portable skills, governance templates, and helper scripts merged into kit/ so a single clone is enough to bootstrap an AI-assisted workflow. Complements the companion ai-dev-toolkit-setup bootstrapper.
• 29 portable skills total in kit/core/skills/ (was 18) covering routing, resume, ship, sync-memories, plan, focus, optimize, and the full forge-kit lifecycle.
• Formal JSON schemas for all core configs (#29): 10 schemas under kit/schema/ validate agents, dispatch, hooks, routines, rules, and skills at install time.
• Canonical agent tool registry (#39): enforces which tools each specialty agent may invoke, with governance tests for title validation, reportsTo reference integrity, and org-chart consistency.
• Release helper preflight (tools/release.py --verify): blocks a release when the git working tree is dirty, git identity is missing, the target tag already exists, or the changelog / release notes are malformed. CI smoke-tests every blocker path in validate.yml.
• Portable hooks manifests (#35) installed for every supported adapter (claude-code, codex, opencode, windsurf, cursor).
• Company templates (#31): solopreneur, startup MVP, agency, and open-source maintainer presets ready for forge-kit consumption.
• Heartbeat routine system (#30): schedule config + validation so recurring maintenance tasks can be declared once and executed by any adapter.
• Backlog triage automation (#33) + backlog map + README link (#32).
• OpenCode plugin typecheck lane (#34) in CI.
• Adapter parity expansion (#27): MCP coverage, c7score README, language reviewers, and harness audit across all adapters.
• oh-my compatibility support (#28) for the remaining adapters (previously only opencode and claude-code).

Fixed

• Release preflight now catches adapter parity blockers before tagging (#41) so a release with missing adapter files is refused at --verify time instead of at publish time.

[0.11.0] — 2026-04-03

Added

• kit/core/agents.json v4 — Paperclip-inspired specialty agents with org chart:

  • 12 agents (was 6): orchestrator, architect, frontend, backend, devops, tester, security, reviewer, writer, researcher, explorer
  • Each agent has title, role, skills, tools, reportsTo, fallback chain
  • orgChart section defining hierarchy: orchestrator → architect → engineering specialists
  • specialtyRouting in dispatch config: UI work → frontend, API work → backend, CI/CD → devops, etc.
  • Escalation: if specialist unavailable, fall back to generic worker
  • Governance tests: agent title validation, reportsTo reference integrity, org chart consistency

• Optional forge-kit oh-my compatibility mode via --oh-my-compat:

  • kit/install.sh supports --oh-my-compat and surfaces compatibility status during installs
  • profiles now include FORGE_OHMY_COMPAT (default false) to keep default installs tool-agnostic
  • kit/adapters/opencode.sh can bootstrap ~/.config/opencode/oh-my-opencode.jsonc from the toolkit reference when absent
  • kit/adapters/claude-code.sh can install ~/.claude/oh-my-claudecode.md ownership guidance
  • kit/adapters/codex.sh can install ~/.codex/oh-my-codex.md ownership guidance

• New compatibility references:

  • implementations/claude-code/oh-my-claudecode.md
  • implementations/codex/oh-my-codex.md

• 6 new portable skills in kit/core/skills/:

  • route.md — multi-model routing and task complexity classification
  • resume.md — session recovery from git state, plans, and open PRs
  • orchestrate.md — multi-phase task breakdown with dependency tracking and verification checkpoints
  • tdd.md — test-driven development red/green/refactor workflow
  • secure.md — security scan checklist (secrets, deps, inputs, permissions, injection)
  • context.md — context window optimization and session compaction

• Skill installation now works across ALL 6 tool adapters (was claude-code only):

  • codex, opencode, cursor, windsurf, antigravity adapters now install/uninstall skills
  • Shared install_skills and uninstall_skills helpers extracted to kit/lib/merge.sh

• kit/setup.sh — interactive CLI setup wizard:

  • Prompts for primary provider, fallback provider, local model usage, token optimization strategy
  • Prompts for profile, oh-my compatibility, orchestration, worktrees, and backlog preferences
  • Generates .forge-setup.json with resolved model maps, routing, agent assignments, token presets, and autopilot config

• 2 additional portable skills:

  • loop.md — autonomous dev cycle (plan → implement → test → review → fix → commit → PR) without stopping
  • fallback.md — provider/model fallback chain behavior with escalation rules

• kit/core/loop.json — autonomous loop engine definition:

  • 5 loop phases (plan, implement, review, secure, commit) + 3 post-loop steps (quality gates, push, PR)
  • Per-phase fallback (retry → switch model → switch provider → escalate tier, max 5 attempts)
  • Loop-level guardrails: max 3 consecutive phase failures → stop and save state
  • Governance gates: required checks before commit, push, PR, and merge; block/never-block rules
  • Resume from last incomplete phase with .agents/plans/.loop-state.json

• kit/core/autopilot.json v2 — autonomy levels and guardrails:

  • supervised / assisted / autonomous levels (default: autonomous)
  • neverPauseFor list: lint fixes, type fixes, test fixes, commits, pushes, file edits
  • hardBlock list: only genuinely destructive actions (rm -rf /, drop database, force push main)
  • Durable execution: continue until complete, persist on interrupt, resume from checkpoint
  • Fallback config: model/provider/tier switching with exponential backoff

• kit/core/agents.json v3 — agents with fallback chains and autonomy flags:

  • Every agent has a fallback.chain (list of tiers to try) and fallback.onFailure policy
  • autonomous: true on orchestrator and worker — they never pause for trivial confirmations
  • async: true on researcher and explorer — they run in background, never block the main loop
  • readOnly: true on architect, reviewer, researcher, explorer — they advise, never block progress
  • Orchestration dispatch: dependency-first, parallelize independent phases, neverPauseFor list
  • Escalation rules: worker fails 2x → consult architect, model unavailable → fallback chain

• kit/core/routing.json v2 — complexity classifier with signals and escalation:

  • Per-category signal lists for automatic classification
  • Per-tier token budgets and context budget levels
  • Escalation rule: 2 consecutive failures → promote to next tier
  • Target distribution: 40% haiku / 45% sonnet / 15% opus

• kit/core/token-optimization.json — 3 presets (standard, aggressive, minimal):

  • Compaction thresholds, tool output truncation, session message limits
  • Rules for what is always safe to remove vs always preserve

• Governance enforcement via expanded test suite:

  • validateKit() validates all core JSON configs, agent tiers, routing categories, skill frontmatter, and loop governance
  • 5 new tests (11 total): kit config parsing, agent tier validity, skill completeness, loop governance

• README rewritten with conversion-focused structure, scannable pattern table, and forge-kit flag reference

Fixed

• forge-kit adapter hardening from PR review feedback:
  • kit/adapters/claude-code.sh avoids duplicate durable header append, creates .forge-kit marker on skills install, fixes uninstall marker detection, and normalizes skill count parsing
  • kit/adapters/windsurf.sh uses cross-platform hashing for content comparison and shared json_merge for MCP merge
  • kit/adapters/cursor.sh only uninstalls forge.mdc when file is marked as forge-managed
  • kit/adapters/codex.sh preserves local providers.json by skipping no-op copies and only updating when content changes
• kit/install.sh now validates --tools and --profile argument values before parsing
• kit/lib/log.sh, kit/lib/merge.sh, kit/lib/os.sh, and kit/lib/detect.sh improved portability and safer fallback behaviors
• kit/core/rules.md and core skill docs updated to satisfy markdown lint expectations; tools/README.md plugin references now include source links for opencode-mem and opencode-codegraph

[0.10.0] - 2026-04-02

Added

• kit/ — forge-kit: universal AI dev toolkit installer with cross-tool adapter architecture
  • kit/install.sh — main entry point with --tools, --profile, --dry-run, --status, --uninstall flags
  • kit/core/rules.md — single source of truth for agent behavior rules (all adapters read from here)
  • kit/core/providers.json — unified provider + model registry (Anthropic, OpenAI, Google, Groq, Ollama)
  • kit/core/mcp.json — curated MCP server definitions with required env vars and profiles
  • kit/core/agents.json — multi-model agent routing config (Sisyphus/Hephaestus/Artemis/Hermes pattern)
  • kit/core/routing.json — task complexity classifier for automatic model selection
  • kit/core/skills/ — 6 portable skill definitions: plan, verify, ship, review, debug, research
  • Adapters for 6 tools: claude-code (CLAUDE.md + skills + MCP), codex (AGENTS.md + providers), opencode (system.md + MCP), cursor (.cursor/rules/forge.mdc + MCP), windsurf (.windsurfrules + MCP), antigravity (rules.md + MCP)
  • 4 install profiles: standard (rules+skills+MCP), minimal (rules only), research (rules+MCP), durable (full+durable execution)
  • kit/lib/ — shared shell libraries: log.sh (colored output), os.sh (platform helpers), merge.sh (JSON merge via python3), detect.sh (auto-detect installed tools)
• implementations/opencode/oh-my-openagent.jsonc — reference config for oh-my-openagent plugin
• implementations/opencode/README.md — updated setup instructions for oh-my-openagent workflow
• rules/AGENTS.md — expanded agent routing table with oh-my-openagent Sisyphus delegation model

[0.9.0] - 2026-04-02

Added

• patterns/spec-driven-development.md — spec-first workflow for AI development covering:
  • Three roles a spec plays: agent instruction, inter-agent contract, regression anchor
  • Minimal spec template with purpose, scope, inputs, outputs, behavior statements, and constraints
  • Workflow: write spec → implement → test → change control
  • Grounding agents to specs via prompt injection and directory-level CLAUDE.md auto-load
  • Multi-agent coordination pattern using spec as shared contract
  • Spec granularity guide (when to apply SDD vs skip it)
• README: added Spec Driven Development entry to Repository Map and Day 6 to the adoption week table

[0.8.0] - 2026-04-01

Added

• tools/README.md — OpenCode Plugins section with curated catalog across five categories: Auth, Orchestration & Workflow, Memory, Code Quality, Notifications
  • Auth: opencode-claude-auth (reuses Claude Code credentials), opencode-gemini-auth and opencode-antigravity-auth (Gemini OAuth, with ToS risk notes)
  • Orchestration: oh-my-openagent (multi-model harness, ulw command), @kompassdev/opencode (repo-grounded workflows), @plannotator/opencode (interactive plan review), opencode-scheduler (launchd/systemd recurring agent tasks)
  • Memory: opencode-graphiti (Graphiti knowledge graph), opencode-mem (local vector DB)
  • Code Quality: opencode-codegraph (CPG analysis), opencode-plugin-openspec (architecture spec agent)
  • Notifications: opencode-plugin-apprise (Apprise CLI integration)
• Recommended adoption order for OpenCode plugins (7-step progression)
• Install snippet showing opencode.jsonc plugin array configuration

[0.7.0] - 2026-03-31

Added

• patterns/streaming-orchestration.md — event-driven turn loops, turn budgeting, transcript compaction, session persistence, stop reason handling
• patterns/tool-registry-patterns.md — separating tool metadata from implementation, JSON snapshots, permission contexts, trust-gated init, parity checking
• patterns/permission-boundaries.md — three-layer permission model (filter/block/confirm), named profiles, CLAUDE.md permission sections, PreToolUse hook patterns

[0.6.0] - 2026-03-31

Added

• patterns/task-orchestration.md — OMC-Inspired Orchestration Patterns section covering:
  • 3-layer composition (ultrawork → ralph → autopilot)
  • Model tier routing table (Haiku/Sonnet/Opus with routing heuristics)
  • Ralph PRD-driven persistence pattern with prd.json schema
  • Preemptive compaction pattern (O(1) cumulative token tracking)
  • Verify-deliverables hook checklist

[0.5.0] - 2026-03-31

Added

• package.json — npm scripts for validation, testing, and formatting
• scripts/validate-schemas.js — JS schema validator (enables jest coverage)
• test/validate-schemas.test.js — jest test suite (75% coverage target)
• jest.config.js — jest ESM configuration
• SECURITY.md — security policy and reporting guide
• CODEOWNERS — code ownership definitions
• .github/workflows/secret-scan.yml — TruffleHog secret scanning
• .github/workflows/semgrep.yml — SAST scanning for scripts/
• .github/workflows/stale.yml — stale issue/PR management
• .github/dependabot.yml — automated dependency updates

[0.4.0] - 2026-03-31

Added

• companies/ — pre-built agent organizations with specialized roles, skills, and routing protocols
• fullstack-forge company (49 agents, 66 skills, 10 teams) imported from paperclipai/companies (MIT)
• tools/validate-companies.sh — validates agent frontmatter, required sections, reportsTo references, and skill existence
• CI validation for company schemas in .github/workflows/validate.yml

[0.3.3] - 2026-03-31

Fixed

• tools/setup-ai-workflow-macos.sh: lmnr now auto-installed via pipx install lmnr (macOS Python 3.14 uses uv and is externally managed — pip3 install fails with PEP 668 error). ai-lmnr alias updated to point to ~/.local/bin/lmnr.
• tools/install-ubuntu.sh: Added lmnr install section using pip3 install lmnr --break-system-packages. Added promptfoo user-local install via npm install --prefix ~/.npm-global — avoids better-sqlite3 native module version mismatch on Ubuntu + Node 22 (NODE_MODULE_VERSION 115 vs 127).
• patterns/agent-observability.md: install instructions now split by platform — pipx install lmnr for macOS, pip3 install lmnr --break-system-packages for Linux, and user-local promptfoo pattern for Ubuntu + Node 22.

[0.3.2] - 2026-03-31

Fixed

• .github/workflows/release.yml — release notes now written to a temp file and passed via --notes-file to avoid backtick shell expansion corrupting markdown code spans in notes.

[0.3.1] - 2026-03-31

Added

• .github/workflows/release.yml — automatic tag and GitHub release on every push to main; parses version from CHANGELOG.md, skips if tag already exists, extracts matching section as release notes.

[0.3.0] - 2026-03-31

Added

• patterns/agent-observability.md — new pattern covering the three-layer observability stack: lmnr tracing, promptfoo regression testing, TDD Guard enforcement, and claude-code-security-review CI integration. Explains when and how to combine them.
• tools/README.md: six new entries in Curated AI Productivity Additions: markdownify-mcp (PDF/image/audio→Markdown), MCPHub (multi-server HTTP proxy), lmnr (agent tracing and eval), TDD Guard (test-first enforcement hook), container-use (Dagger-based agent sandboxing), and claude-code-security-review (official Anthropic PR security action).
• tools/README.md: new Claude Code Skills subsection documenting Superpowers, Context Optimization, claude-deep-research-skill, and the Anthropic official skills collection (PDF, DOCX, XLSX, PPTX, Canvas Design, Frontend Design).
• setup-claude-code.sh: markdownify-mcp added to the MCP server merge list — auto-installed alongside tavily, context7, and playwright on fresh setups.
• setup-ai-workflow-macos.sh: new aliases ai-markdownify, ai-mcphub, ai-lmnr, ai-tdd-guard added to the workflow block.
• README pattern table updated with Agent Observability entry.
• Recommended Adoption Order in tools/README.md expanded to include skills, markdownify-mcp, lmnr, TDD Guard, and container-use with positioning rationale.
• Dead link skillsmp.com removed from Claude Code Skills section.

[0.2.3] - 2026-03-30

Added

• Codex CLI reference implementation: implementations/codex/ with setup guide, approval policy guidance, sandbox modes, multi-model routing table, and task orchestration patterns
• implementations/codex/config.toml — annotated reference config for ~/.codex/config.toml
• rules/AGENTS.md now covers both Codex CLI and OpenCode; model routing table split by tool
• "How Codex Differs" section explaining sandbox-first design vs trust-first tools (Claude Code, OpenCode, Cursor)
• Approval policy autonomy dial: untrusted → on-request → on-failure → never with rationale for on-request as dev default
• Trust model mismatch gotcha in patterns/agent-gotchas.md — comparison table and cross-tool guidance
• @openai/codex install in tools/setup-ai-workflow-macos.sh via install_codex()
• ai-codex alias in zsh workflow block
• Codex CLI entry in tools/README.md curated additions and adoption order

[0.2.2] - 2026-03-30

Added

• tools/capture-training.py — extract Claude Code sessions as alpaca-format instruction pairs for fine-tuning. Parses ~/.claude/projects/**/*.jsonl, deduplicates by session hash. Flags: --export, --min-turns, --dry-run, --output.
• tools/setup-claude-code.sh now installs capture-training to ~/.local/bin/ so it's available as a CLI command after running the setup script.
• Claude Code Router (CCR) pattern added to patterns/multi-model-routing.md — slot-based routing (default/background/think/longContext) with minimal preset example.
• Sub-agent routing section added to patterns/multi-model-routing.md — explains why CLAUDE_CODE_SUBAGENT_MODEL matters and expected savings.
• Sub-agent routing + CCR sections added to implementations/claude-code/README.md.
• training/README.md — session capture workflow with capture-training.py, optional LoRA fine-tuning section (axolotl + Ollama export).

[0.2.1] - 2026-03-30

Added

• tools/setup-claude-code.sh: new script that configures Claude Code from scratch — creates ~/.claude/.mcp.json with recommended MCP servers (tavily, context7, playwright), sets default model to Sonnet 4.6 and subagent model to Haiku 4.5, removes CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS if present, creates memory directory structure with MEMORY.md and gotchas.md templates, and runs a plugin audit

Fixed

• tools/install-macos.sh: corrected RTK init command (rtk init -g, not --hook-only)
• tools/install-ubuntu.sh: same RTK init fix
• tools/setup-ai-workflow-macos.sh: removed Ollama (local model — not universally applicable); removed ai-ollama alias from the zsh workflow block

[0.2.0] - 2026-03-30

Added

• rtk (Rust Token Killer) added to macOS and Ubuntu install scripts — 60-90% token reduction on Bash outputs via a transparent Claude Code PreToolUse hook. macOS: installed via brew install rtk + rtk init -g. Linux: installed via official install.sh. Run rtk gain after a few sessions to track savings.
• TurboQuant added to Curated AI Productivity Additions — Google's near-optimal KV cache quantization algorithm (6x memory reduction, 8x inference speed). Works with vLLM today via 0xSero/turboquant; llama.cpp/Ollama integration expected Q3 2026. Paired with Ollama in Recommended Adoption Order.
• New patterns: Prompt Engineering, Code Review, Testing with AI, Git Worktrees, Agent Gotchas, Multi-Repo Workflows
• Rule templates for all major tools: .cursorrules, .windsurfrules, COPILOT.md
• Claude Code reference implementation with hooks, skills, and memory structure
• Example files: backlog.json, .claude/memory/ structure
• CONTRIBUTING.md with contribution guidelines
• LICENSE (MIT)
• GitHub issue and PR templates
• CI workflow for markdown link validation
• CHANGELOG.md
• Curated "AI Productivity Additions" in tools/README.md covering Context7, Tavily, Firecrawl, promptfoo, Portkey AI Gateway, LangGraph, n8n, Dify, Open WebUI, fastmcp, and Playwright MCP
• tools/setup-ai-workflow-macos.sh for local AI workflow setup (promptfoo, n8n, and shell workflow aliases)
• Community workflow integrations for planning-with-files, antigravity-awesome-skills, and OpenViking in setup/docs
• Added community-picked browser-use and letta into setup/docs/aliases
• Added a dedicated memory stack (mem0ai + graphiti-core) with ai-memory-check and ai-memory-python helpers
• Claude Code MCP plugin dual-registration documentation and audit guidance
• Claude Code CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS warning and fix
• MEMORY.md 200-line discipline section with topic-file extraction strategy

Improved

• README rewritten with problem-first framing and before/after examples
• Install scripts: added missing tools (fd, ripgrep, chezmoi), idempotency checks
• rules/CLAUDE.md now includes Quick Reference and Gotchas sections
• best-practices/context-management.md made tool-agnostic with separate tool-specific sections
• README now links to the curated AI productivity tools section
• tools/README.md now documents local workflow commands (ai-eval, ai-flow, ai-webui, ai-portkey, ai-browser-mcp)
• tools/setup-ai-workflow-macos.sh now installs pipx, supports openviking, and adds aliases for skills discovery and installation workflows
• tools/setup-ai-workflow-macos.sh now also installs browser-use and letta via pipx with matching aliases
• tools/setup-ai-workflow-macos.sh now provisions a Python 3.13 memory venv for mem0ai + graphiti-core and exposes health-check aliases
• tools/install-windows.ps1 now checks Scoop buckets by exact name before adding them, preventing duplicate-add failures on reruns
• README structure improved with clearer quick start, adoption roadmap, table of contents, and a more descriptive repository map
• tools/README.md: added rtk to core stack table and platform notes
• tools/README.md: added TurboQuant to curated additions; updated Recommended Adoption Order to pair TurboQuant
• best-practices/context-management.md: /compact threshold corrected to 60-70%; added MEMORY.md discipline section; added plugin dual-registration and agent teams warnings to MCP strategy
• implementations/claude-code/README.md: fixed MCP config path to ~/.claude/.mcp.json; added plugin management section; added agent teams env var warning; updated model table to Sonnet/Opus/Haiku 4.x IDs; corrected /compact threshold to 60-70%

[0.1.0] - 2026-03-15

Added

• Initial release
• 5 tool-agnostic patterns: Context Building, Task Orchestration, Multi-Model Routing, Session Management, Memory Systems
• 3 best practices guides: Context Management, Workflow, Security
• Rule templates: CLAUDE.md, AGENTS.md
• CLI tool install scripts for macOS, Ubuntu, Windows
• OpenCode reference implementation with orchestrator, session manager, and metrics plugins