Skip to main content

Agent Layer publishes full release notes and artifacts on GitHub Releases. The canonical history lives in CHANGELOG.md and is embedded below.

Where to read release notes:

note

If you pin versions in a repo, read the release notes before upgrading (see /docs/concepts#version-pinning and /docs/upgrades for the upgrade contract).

If you are looking for a specific change, search the changelog by version tag (for example v0.6.0).

Changelog

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

v0.9.1 - 2026-03-07​

Overhauls the built-in skill library from 10 to 22 structured, workflow-driven skills and introduces a user-managed conventions file so you can tailor project-specific rules without losing them on upgrade. Instructions are reordered, deduplicated, and compressed for better agent compliance.

Added​

  • New user-managed 04_conventions.md instruction template for project-specific conventions (architecture, code quality, data safety, time/data, environment). Seeded on al init, never overwritten on al upgrade; future convention updates delivered via append_to_file migrations with duplicate detection.
  • New append_to_file migration kind for delivering content to user-managed files without overwriting edits. Supports duplicate-detection via match string, automatic file creation, and atomic writes.
  • New delete_file migration operations for removing deprecated skill directories during upgrade.
  • 17 new built-in skills following a normalized workflow-driven structure with explicit phases, global constraints, guardrails, and human checkpoints: address-pr-comments, audit-and-fix-uncommitted-changes, audit-memory, audit-tests, complete-current-phase, debug-issue, fix-ci, implement-plan, improve-codebase, plan-work, repair-checks, resolve-findings, review-scope, schedule-backlog, ship-pr, simplify-code, verify-against-plan.
  • Site documentation page for built-in skills (site/docs/skills.mdx) covering the full 22-skill library organized by category with usage examples and customization guidance.
  • Site documentation page for evidence-based skill design (site/pages/skill-design.mdx) with 5 core design principles and 18 academic/industry citations.
  • Internal skill authoring reference (docs/SKILL-DESIGN.md) and audit workflow specification (docs/SKILL-AUDIT.md).

Changed​

  • Instruction files reordered for primacy effect: 02_rules.md → 00_rules.md, 00_base.md → 01_base.md, 01_memory.md → 02_memory.md. Hard constraints now load first to improve model compliance. al upgrade migrates existing repos via rename_file operations.
  • Cross-file instruction duplicates removed: 6 items that appeared in multiple instruction files consolidated to a single canonical location, reducing ~57 instructions to ~50.
  • Verbose instruction sections compressed (~50% fewer tokens in Critical Protocol, Workflow & Safety, and Tools sections) without removing guidance.
  • UTC-only internals and No system Python rules moved from 02_rules.md to 04_conventions.md as project-specific conventions (delivered to existing users via append_to_file migrations).
  • 5 existing built-in skills restructured to normalized workflow pattern: audit-documentation, boost-coverage, finish-task, fix-issues, review-plan.
  • Decision hygiene guidance updated: superseded decisions should be replaced (not accumulated), and entries that become self-evident from the codebase should be removed.
  • Skill loader error message for directories missing a skill file shortened from "missing SKILL.md or skill.md" to "has no SKILL.md".
  • Site docs sidebar positions updated to accommodate new Skills page; upgrade-checklist shell examples consolidated.

Removed​

  • 5 built-in skills replaced by normalized workflow equivalents: cleanup-code (→ simplify-code), continue-roadmap (→ complete-current-phase), find-issues (→ resolve-findings), fix-tests (→ repair-checks), update-roadmap (→ schedule-backlog). Migration manifest deletes these (plus mechanical-cleanup) from user directories during upgrade.

Improved​

  • Expanded automated test coverage for user-owned instruction files (seed-on-init, no-overwrite-on-upgrade, excluded-from-diffs), append_to_file migration paths (apply, no-op, file creation, rollback), normalized workflow skill structure validation, artifact naming conventions, and skill deletion migration scenarios.

v0.9.0 - 2026-03-01​

Added​

  • Added a reusable internal/skillvalidator package with parse/validate separation and deterministic findings for agentskills.io-aligned skill validation.
  • Added al doctor skills diagnostics for standards checks (unknown frontmatter keys, name/path mismatches, and non-canonical directory filenames such as skill.md).
  • Added release manifests for v0.9.0: internal/templates/migrations/0.9.0.json and internal/templates/manifests/0.9.0.json.
  • Added al doctor check for stale flat-format skill files (.md at skills root) with guidance to run al upgrade.
  • Added CONTEXT.md memory file template for general-purpose project context, domain concepts, naming conventions, and lessons learned.
  • Added data-driven breaking-change display: migration manifests now carry breaking, breaking_notice, and breaking_details fields, and the upgrade report renders them generically instead of hardcoding per-kind display logic.
  • Added yellow highlighting for readiness warnings, file-removal counts, and review-needed items in upgrade plan and upgrade output for improved scanability.
  • Upgrade snapshot rollback now accepts snapshots in created status, enabling recovery from interrupted upgrades that failed before reaching applied status.

Changed​

  • Renamed legacy "slash command" source and output terminology to "skills" across config, sync pipelines, templates, and docs.
  • Canonicalized source layout to .agent-layer/skills/, with migrations that rename legacy .agent-layer/slash-commands/ and embedded skill template paths.
  • Breaking: Flat-format skills (<name>.md) are no longer supported by the skill loader. All skills must use directory format (<name>/SKILL.md). al upgrade migrates both built-in and user-authored skills automatically via a single migrate_skills_format operation with pre-flight conflict detection and user confirmation.
  • Skill frontmatter parsing/generation now uses YAML (go.yaml.in/yaml/v3) with support for name, description, license, compatibility, metadata, and allowed-tools, while keeping unknown fields parse-tolerant for portability.
  • Increased skill parser/validator single-line scanner caps to 8 MiB to reduce token-limit failures on large single-line skill content.
  • Documentation now explicitly states that missing or empty skill description is load-enforced (fail-loud), while missing name remains backward-compatible with doctor warnings.
  • Skills migration user-facing copy updated to "Slash-commands renamed to skills" with data-driven breaking-change notices sourced from the migration manifest.
  • Unknown-file scanning now covers both .agent-layer/ and docs/agent-layer/, with a fresh post-migration re-scan so the unknown-file prompt reflects actual post-migration state instead of stale pre-migration paths.
  • Migration-covered diff suppression now uses ancestor-directory matching, so migrations that own an entire directory (e.g., skills format migration) suppress noisy per-file template diffs in plan output.
  • Git safety instruction now clarifies that commit/push authorization applies only to the specific request and does not carry forward.

Fixed​

  • al doctor lenient-config fallback now best-effort loads skills, preventing false "No skills configured" results when strict config validation fails.
  • Skill name handling is now Unicode NFKC-aware across loading and validation paths, preventing false duplicates/mismatches for normalization-equivalent names.
  • Skill metadata and text limits now use rune counts (not bytes), and validation now rejects empty names and non-ASCII digit forms in slug normalization.
  • Directory-format loading now accepts lowercase skill.md as a compatibility fallback while preserving canonical SKILL.md precedence.

Removed​

  • Removed docs/agent-layer/SKILLS_WORKFLOWS.md; workflow guidance is now provided by individual skill sources.

Improved​

  • Expanded automated coverage across skill loading/validation, upgrade migrations, prompt generation, install ownership/readiness checks, and docs surfaces touched by the skills-standard migration.
  • Updated default embedded skills to canonical agentskills directory format (skills/<name>/SKILL.md) and aligned memory/workflow docs for Phase 15 completion.

v0.8.8 - 2026-02-25​

Added​

  • Added embedded upgrade migration manifest support for v0.8.8 to canonicalize the Claude VS Code agent key from agents.claude-vscode.enabled to agents.claude_vscode.enabled and enforce a default for the canonical key.
  • Expanded branch-coverage suites across upgrade/install, dispatch, wizard PTY interactions, and command paths to harden release confidence.

Changed​

  • Canonical config/docs naming now uses [agents.claude_vscode] (snake_case). Legacy [agents.claude-vscode] remains accepted at load time and is migrated during upgrade.
  • Release and upgrade-doc validation checks are stricter, including stronger release workflow/docs contract assertions and stable-tag publishing guardrails.
  • cmd/publish-site release version-retention and versioned-doc pruning behavior is more robust for deterministic stable release publication.

Fixed​

  • Made dispatch cache sync-error coverage deterministic by injecting sync failures in tests instead of relying on platform-specific /dev/null behavior.
  • Aligned upgrade/readiness messaging and docs references to the canonical claude_vscode key to avoid mixed-key guidance.

Improved​

  • Removed obsolete Claude-specific GitHub workflow files in favor of the current release/verification workflow set.
  • Updated README and site docs for key-name consistency and release guidance clarity.

v0.8.7 - 2026-02-24​

Added​

  • al <client> commands now support --quiet / -q for one-off quiet runs that suppress Agent Layer informational output while preserving client output and error exit behavior.
  • Added end-to-end coverage for quiet Claude runs to ensure al claude --quiet emits no Agent Layer output and still launches correctly.
  • Wizard back-navigation support: pressing Esc now moves to the previous step, with explicit first-step exit confirmation and deterministic state rollback behavior for partial selections.
  • Wizard Ctrl+C now exits immediately without saving, distinct from Esc (back). Both keys are shown as hints in the bottom navigation bar (esc back • ctrl+c exit).
  • Config guardrail test for required fields: automated enforcement now checks that newly required config fields have matching config_set_default migration coverage (with explicit legacy baseline allowlist).
  • Claude reasoning-effort support in wizard/config/sync paths (low|medium|high), including projection into .claude/settings.json as effortLevel.

Changed​

  • warnings.noise_mode now supports quiet in addition to default and reduce.
  • Quiet handling is now applied consistently across dispatch and client launch paths, including argument forwarding and no-sync execution.
  • Wizard-managed config.toml writes now use an explicit preferred section order policy (approvals, enabled agents, mcp, warnings) instead of implicitly coupling ordering to template parse order.
  • Upgrade diff output is now colorized in interactive terminals for better scanability (adds/removes/hunks), with plain-text fallback preserved for non-interactive and no-color environments.
  • Wizard profile apply flow now warns when replacing an existing TOML-corrupt .agent-layer/config.toml.

Fixed​

  • al sync warning-only outcomes in quiet mode now preserve non-zero exit behavior without printing warning text.
  • Quiet-mode behavior now avoids leaking dispatch/update-check banners when quiet is enabled via flag or config.
  • Prevented hidden behavior drift in multiline TOML patching by refactoring duplicated state tracking into a shared iterator with regression coverage across call sites.
  • Gemini reasoning_effort is now rejected explicitly with a clear validation error instead of allowing ambiguous/unsupported behavior.
  • Claude reasoning-effort validation now fails loudly for invalid option values and unsupported model selections.

Improved​

  • Documentation and default config comments now describe quiet-mode behavior and its interaction with al doctor (which always prints warnings).
  • Validation and warning messaging now includes quiet as a first-class supported noise mode.
  • Expanded test coverage for wizard back-navigation state transitions, profile corruption warning paths, reasoning-effort capability validation, Claude sync projection behavior, and upgrade diff color/no-color rendering.
  • Added PTY integration tests for wizard Esc/Ctrl+C keystroke classification, validating the full chain from raw terminal bytes through bubbletea to error classification.
  • Updated project memory/docs (ISSUES.md, BACKLOG.md, ROADMAP.md, DECISIONS.md, README.md) to reflect completed sprint scope and release-facing behavior.

v0.8.6 - 2026-02-23​

Added​

  • al wizard now prompts to enable per-repo Claude settings and caches isolation (local_config_dir) when Claude or Claude VS Code is enabled. Default is false (shared global config); selecting true sets CLAUDE_CONFIG_DIR to a repo-local directory for separate settings and caches per repository.

Fixed​

  • .gitignore template inline comments on /.claude/ and /.claude-config/ patterns were treated by Git as part of the literal pattern, causing both directories to not be gitignored. Comments moved to their own lines. Affected users (v0.8.5 installs): run al upgrade or al sync to pick up the corrected template.

Improved​

  • Per-repo isolation is now documented as a core feature in the README comparison table, key properties, and a dedicated Per-repo credential isolation section in the site concepts page (Codex auth isolation plus Claude settings and caches isolation; Claude auth remains shared due to an upstream limitation).

v0.8.5 - 2026-02-23​

Added​

  • Optional agent-specific passthrough configuration for Claude and Codex via agents.claude.agent_specific and agents.codex.agent_specific.
  • Optional agents.claude.local_config_dir support for repo-local Claude config isolation (.claude-config). al vscode sets CLAUDE_CONFIG_DIR only when both local_config_dir = true and agents.claude-vscode.enabled = true.
  • al upgrade rollback --list support to inspect available snapshot IDs and statuses before executing rollback.
  • al sync now auto-adds the repository root to ~/.gemini/trustedFolders.json when Gemini is enabled so Gemini CLI reliably loads project-level .gemini/settings.json. If this write fails, sync still succeeds and emits a non-fatal warning with manual remediation guidance.

Changed​

  • Agent-specific passthrough keys intentionally override Agent Layer-managed keys when they collide, with sync warnings to keep overrides explicit.
  • al vscode now clears CLAUDE_CONFIG_DIR only when it points at the repo-local .claude-config; user-defined non-repo values are preserved.
  • Codex sync now writes agents.codex.agent_specific keys before managed MCP tables so top-level overrides remain at the TOML root.

Fixed​

  • Config parsing now rejects unrecognized keys during strict decode instead of silently ignoring them, with actionable validation guidance in the returned error.
  • .env parsing now correctly handles quoted values, escaped newline/carriage-return sequences, and invalid trailing characters after quoted values.
  • MCP tool-name collision warnings are deterministic: warning subjects and per-tool server lists are sorted for stable output.
  • Upgrade config_set_default prompts no longer mark one choice as "recommended"; migration manifest values are still pre-selected but users must make an explicit choice.
  • al upgrade now accepts zero-byte snapshot file entries, fixing failures where unknown empty files previously produced requires content_base64 errors.
  • al gemini no longer fails MCP discovery for the internal agent-layer server when PATH al is a non-runnable repo-pin shim. Prompt-server command resolution now prefers local source execution (go run <repo>/cmd/al mcp-prompts) when available, al mcp-prompts bypasses repo-pin dispatch, and prompt-server source roots are validated as the Agent Layer module.

Improved​

  • Expanded automated coverage for root/upgrade command paths, Gemini trust flows, upgrade-readiness helpers, warning policy branches, prompt-server root resolution, dispatch behavior, and codex/claude agent-specific config rendering.
  • Added e2e coverage for upgrade flows that include empty unknown files and for wizard MCP sanitization behavior when profile defaults disable an injected server block.
  • Website documentation now includes al upgrade rollback --list guidance, Gemini trusted-folder remediation notes, and expanded agent-specific and repo-local Claude configuration guidance.

v0.8.4 - 2026-02-20​

Fixed​

  • Version dispatch no longer prints the version-source diagnostic twice when a pinned or environment-overridden version dispatches to a cached binary. The diagnostic now prints only from the binary that actually runs the command.

Changed​

  • Config validation now silently strips transport-incompatible MCP server fields instead of rejecting the config with an error. For example, headers on a stdio server or command/args on an HTTP server are removed during validation rather than causing a load failure. This makes configs more resilient to leftover fields from transport changes or manual editing.

Improved​

  • al wizard config patching now removes dotted sub-key lines (e.g., headers.Authorization = "Bearer ...") when stripping a parent key like headers. Previously, only inline-table syntax (headers = { ... }) was handled.
  • Scenario-based end-to-end test framework with 26 scenarios and 436 assertions replaces the previous monolithic e2e script. Covers fresh install, wizard profiles, upgrade paths, error propagation, agent launch, and rollback workflows with mock agent binaries.

v0.8.3 - 2026-02-19​

Fixed​

  • al doctor lenient config fallback now injects built-in environment variables (e.g., AL_REPO_ROOT), fixing false "missing environment variables" warnings for MCP servers like filesystem that reference ${AL_REPO_ROOT} in their args.
  • al wizard now sanitizes transport-incompatible MCP server fields during config patching. For example, leftover headers on a stdio server or leftover command/args on an HTTP server are automatically removed. Previously, the wizard would complete successfully but al sync would fail with a validation error, creating a circular "run wizard to fix" loop.

v0.8.2 - 2026-02-18​

Added​

  • Migration manifest chaining: al upgrade now loads all intermediate migration manifests between the source and target versions during multi-version jumps. Users upgrading from 0.8.0 to 0.8.2 will receive migrations introduced in intermediate releases.
  • Config resilience: al wizard, al doctor, and al upgrade now use lenient config parsing so they always work even on broken or incomplete configs. Runtime commands remain strict with actionable guidance.

Changed​

  • The agents.claude-vscode.enabled config migration has been moved from the v0.8.1 manifest to v0.8.2. This ensures all users (including those who installed v0.8.1 before the migration was added) receive the prompt during upgrade.

Fixed​

  • Users jumping multiple versions (e.g., 0.8.0 to 0.8.2) no longer miss intermediate migration operations.

Removed​

  • Slash command auto-approve frontmatter. Approval permissions are controlled entirely by approvals.mode.

Improved​

  • Slash command frontmatter now rejects unrecognized keys with a clear error, catching typos and unsupported fields early.

v0.8.1 - 2026-02-18​

Added​

  • [agents.claude-vscode] config section for Claude Code VS Code Extension support. al vscode is the single command for launching VS Code with both Codex and Claude extension settings based on which agents are enabled.
  • approvals.mode = "yolo" for maximum agent autonomy: skips all permission prompts (Claude --dangerously-skip-permissions, Gemini --approval-mode=yolo, Codex approval_policy=never + sandbox_mode=danger-full-access, VS Code chat.tools.global.autoApprove). Intended for sandboxed/ephemeral environments.
  • Slash command auto-approve frontmatter: auto-approve: true auto-approves MCP prompt retrieval for that skill in Claude clients. It does not auto-approve agent actions after reading the prompt; those remain governed by approvals.mode.
  • Upgrade readiness checks now detect stale disabled-agent artifacts for .claude/settings.json.

Changed​

  • al vscode now launches when either [agents.vscode] or [agents.claude-vscode] is enabled in config.toml, unifying both extensions under a single launch command.
  • CODEX_HOME is now cleared from the VS Code process environment when [agents.vscode] is disabled, preventing stale Codex configuration leakage when only Claude VS Code is enabled.
  • Release process now includes a preflight gate (make release-preflight RELEASE_TAG=vX.Y.Z) that validates upgrade-contract documentation before tagging.

Fixed​

  • al vscode no longer appends . when pass-through arguments include a positional path or file argument. (#51)
  • Sync warning exit behavior restored: non-suppressible warnings correctly propagate exit status regardless of noise_mode setting.

v0.8.0 - 2026-02-16​

Added​

  • New upgrade command surface centered on al upgrade: al upgrade plan (dry-run preview), al upgrade rollback <snapshot-id> (manual restore), al upgrade prefetch --version X.Y.Z (cache warm-up), and al upgrade repair-gitignore-block (managed block repair).
  • al upgrade plan now produces plain-language categorized upgrade previews with readiness checks and line-level diff previews (default 40 lines per file, configurable via --diff-lines).
  • Upgrade planning ownership inference is now deterministic and offline using committed release manifests (internal/templates/manifests/*.json) plus repo baseline state (.agent-layer/state/managed-baseline.json).
  • al upgrade now creates managed-file snapshots under .agent-layer/state/upgrade-snapshots/ and automatically rolls back transactional changes when an upgrade step fails.
  • Embedded per-release migration engine: al upgrade executes migration manifests (internal/templates/migrations/<target>.json) before template writes and emits deterministic migration reports.
  • al wizard now supports non-interactive profile mode (--profile, optional --yes) and backup cleanup (--cleanup-backups).
  • Warning noise control added via warnings.noise_mode (default or reduce) to reduce non-critical suppressible warning output when desired.

Changed​

  • Breaking: al init is now one-time scaffolding only. If .agent-layer/ already exists, al init errors and directs users to al upgrade plan + al upgrade.
  • Breaking: al upgrade non-interactive execution now requires --yes plus explicit apply flags (--apply-managed-updates, --apply-memory-updates, --apply-deletions) to make mutation intent explicit.
  • .agent-layer/.env and .agent-layer/config.toml are now strictly user-owned: seeded only when missing and never overwritten by init/upgrade operations.
  • .agent-layer/.gitignore is treated as internal agent-owned state: always rewritten from templates and excluded from upgrade plans/diff prompts.
  • Default MCP server templates now pin concrete tool versions by default, with inline floating/latest opt-in examples for teams that want automatic upstream updates.
  • Update-check handling now degrades gracefully on GitHub API rate limits so init/doctor flows continue with actionable warning output.
  • Release process now requires generating and committing a per-tag template ownership manifest before tagging (./scripts/generate-template-manifest.sh --tag vX.Y.Z).

Fixed​

  • al upgrade rollback <snapshot-id> now rejects path separators in snapshot IDs, preventing path traversal attempts during manual rollback resolution.
  • al vscode launch preflight now fails fast with explicit guidance when the code CLI is missing on PATH or when .vscode/settings.json has a managed-block marker conflict.

Removed​

  • Breaking: al init --overwrite and al init --force have been removed. Use al upgrade plan and al upgrade for upgrades/repairs.
  • Breaking: al upgrade --force has been removed. Use explicit apply flags (plus --yes for non-interactive runs) to select mutation categories.
  • Breaking: al upgrade plan --json has been removed; text output is now the only supported plan interface.

v0.7.0 - 2026-02-07​

Added​

  • Upgrade contract published at site/docs/upgrades.mdx: defines upgrade event categories (safe auto, needs review, breaking/manual), sequential compatibility guarantees (N-1 to N), release-versioned migration rules, and OS/shell capability matrix.
  • Release gate validates upgrade documentation for each release tag (make docs-upgrade-check), ensuring migration table rows exist and placeholder text is replaced when changelog notes breaking changes.
  • al init --version latest resolves the latest GitHub release to a semver pin before writing .agent-layer/al.version.
  • al init --version X.Y.Z validates the release exists on GitHub before writing the pin file, failing with a clear "release not found" message instead of writing a pin that 404s on next use.
  • al init auto-recovers from empty or corrupt .agent-layer/al.version pin files with a warning instead of blocking all commands.
  • Binary download progress indicator: ensureCachedBinary emits "Downloading al vX.Y.Z..." / "Downloaded al vX.Y.Z" to stderr.
  • Actionable error messages for binary download failures (404 not-found and timeout scenarios).

Changed​

  • Breaking: Windows support removed. Deleted al-install.ps1 installer, Windows release target, open-vscode.bat launcher, and all Windows-specific code paths in dispatch, cache, exec, and lock packages. Windows was never tested and best-effort support eroded trust. macOS and Linux remain fully supported.
  • al init now bypasses repo-pin binary dispatch and always executes on the invoking CLI binary, preventing older pinned versions from running upgrade operations.
  • Launcher template writes refactored for reliability with proper macOS path escaping.
  • Codex MCP header projection order corrected.
  • CI workflow caches pinned tools in GitHub Actions for faster builds.
  • Upgrade contract linked from README, site docs, DEVELOPMENT.md, and RELEASE.md.

Removed​

  • al-install.ps1 (Windows PowerShell installer).
  • open-vscode.bat (Windows VS Code launcher).
  • Windows release targets (windows/amd64) from build scripts.
  • Windows-specific dispatch, cache, exec, and lock code paths.

v0.6.1 - 2026-02-06​

Added​

  • CLI argument forwarding: al <client> now forwards extra arguments to the underlying client. Use -- to separate Agent Layer flags from client arguments (e.g., al claude -- --help or al vscode --no-sync -- --reuse-window).
  • VS Code launchers are now created during al init in addition to al sync, so launchers are available immediately after initialization.
  • .gitignore managed block is now updated during both al init and al sync operations for consistency.

Fixed​

  • AL_SHIM_ACTIVE environment variable no longer leaks into VS Code's integrated terminal when launching via al vscode. Previously, this caused subsequent al commands in the terminal to fail with "version dispatch already active" errors. (#46)
  • Wizard now rewrites config.toml sections in the template-defined canonical order, preventing section ordering drift after multiple wizard runs.

Changed​

  • Launcher code moved to internal/launchers package with exported EnsureGitignore for cross-package use.
  • Documentation updated with clearer guidance on gitignore template format, wizard behavior, and troubleshooting MCP server startup on macOS.

v0.6.0 - 2026-02-03​

Added​

  • Documentation website with comprehensive guides covering getting started, concepts (approvals, MCP servers, project memory, version pinning), reference (CLI, configuration, environment variables), and troubleshooting.
  • Website publishing pipeline (cmd/publish-site) with automated deployment in the release workflow.
  • Playwright MCP server template in default config.toml for browser automation workflows.
  • Descriptive comments for all default MCP server templates explaining purpose and required credentials.
  • Claude Code VS Code Extension added to supported clients table in README.

Changed​

  • README rewritten with clearer value proposition, comparison table (manual vs Agent Layer), and improved quick start flow.
  • Default MCP server examples in README now use generic example-api instead of GitHub-specific config for clarity.
  • Documentation structure consolidated from nested pages to flat MDX files for better navigation.

v0.5.8 - 2026-01-30​

Changed​

  • Breaking: Environment variables now require AL_ prefix to avoid conflicts with shell environment (e.g., GITHUB_PERSONAL_ACCESS_TOKEN → AL_GITHUB_PERSONAL_ACCESS_TOKEN). This ensures Agent Layer variables don't override existing environment variables when VS Code terminals inherit the process environment.

Fixed​

  • VS Code open-vscode.app launcher now uses osascript with a login shell (zsh -l) instead of hardcoded VS Code CLI paths, fixing launch failures when VS Code is installed via Homebrew, in ~/Applications, or other non-standard locations. This also fixes MCP server failures where VS Code couldn't find node because Finder-launched apps have a minimal PATH.
  • All VS Code launchers (.app, .command, .bat, .desktop) now delegate to al vscode for loading .agent-layer/.env, ensuring consistent parsing (KEY=VALUE data, not sourced) across platforms. Only AL_* variables with non-empty values are loaded, and existing environment variables take precedence—matching the documented behavior for al commands.
  • VS Code .app launcher now shows a descriptive alert when the code command is not found, instead of silently failing.
  • Linux .desktop launcher simplified to delegate to .command script for consistent behavior and maintainability.

v0.5.7 - 2026-01-29​

Added​

  • Custom HTTP header support for Codex MCP servers: bearer_token_env_var for Authorization: Bearer ${VAR}, env_http_headers for other env-var-sourced headers, and http_headers for static literals.
  • X-MCP-Tools header in default GitHub MCP server template for server-side tool filtering, reducing projected tool count.
  • Detailed per-tool token breakdown in al doctor MCP schema bloat warnings, showing top contributors by token count.
  • Documentation for MCP HTTP header projection across all supported clients (docs/MCP_HEADERS_SUPPORT.md).

Changed​

  • Default MCP schema token thresholds increased to accommodate larger MCP servers (server: 7500→20000 tokens, total: 10000→30000 tokens).
  • Doctor command now shows real-time discovery progress when checking MCP servers.
  • Large internal modules (install, dispatch, config) split into smaller, focused files for maintainability.
  • golangci-lint upgraded to v2.8.0 with additional linting rules enabled.

v0.5.6 - 2026-01-27​

Added​

  • http_transport config option for HTTP MCP servers to specify transport mode (streamable or sse).
  • Three new MCP server templates in default config.toml: fetch (mcp-server-fetch), ripgrep (mcp-ripgrep), and filesystem (server-filesystem with repo-scoped access).
  • ${AL_REPO_ROOT} built-in variable for resolving repository root path in MCP server args.
  • VS Code settings sync now preserves existing user settings and comments using JSONC-aware block insertion instead of overwriting the entire file.
  • Memory file templates (BACKLOG.md, COMMANDS.md, DECISIONS.md, ISSUES.md, ROADMAP.md) now include detailed formatting guidelines and entry templates.

Changed​

  • MCP projection refactored: new internal/projection/resolvers.go module centralizes server resolution logic, used by both sync and warning checks.
  • Update-available warning now includes full upgrade instructions for Homebrew, macOS/Linux shell script, and Windows PowerShell.
  • Instruction templates consolidated and shortened to reduce token count while preserving key guidelines.
  • Terminal detection moved to canonical internal/terminal package with IsInteractive() function.
  • Default MCP server templates no longer specify clients filter (servers are projected to all clients by default).

Fixed​

  • MCP server health checks now properly handle HTTP transport timeout scenarios.

v0.5.5 - 2026-01-25​

Added​

  • New 03_tools.md instruction template with comprehensive tool usage guidelines: time-sensitive information handling, Context7 documentation lookups, MCP tool constraints, approval workflows, and error handling.
  • New fix-tests slash command runs repo-defined checks (lint/format/pre-commit/tests) in a loop, fixing failures until all checks pass or max iterations reached.

Changed​

  • Temporary artifact location moved from tmp/agent-layer/runs/ to .agent-layer/tmp/runs/, keeping all agent artifacts within .agent-layer/.
  • Slash command artifact naming standardized across workflows: .agent-layer/tmp/<workflow>.<run-id>.<type>.md with run-id = YYYYMMDD-HHMMSS-<short-rand>. User path overrides removed for consistency.
  • finish-task workflow now delegates to fix-tests when available before falling back to manual repo-defined commands.
  • README updated with new artifact naming convention and VS Code reauthentication note for new CODEX_HOME environments.

v0.5.4 - 2026-01-24​

Changed​

  • Memory file FEATURES.md renamed to BACKLOG.md to better reflect its purpose (unscheduled user-visible features and tasks vs deferred issues).
  • al init --overwrite now detects and prompts to delete unknown files under .agent-layer that are not tracked by Agent Layer templates.
  • al init --force now deletes unknown files under .agent-layer in addition to overwriting existing files without prompts.
  • Memory instruction templates improved with clearer formatting rules and entry layouts.
  • Slash command templates (continue-roadmap.md, update-roadmap.md) simplified and clarified.
  • VS Code launcher paths centralized in internal/launchers package, consumed by sync and install to prevent drift.
  • Sync package refactored with system abstraction layer for improved test isolation and reliability.

v0.5.3 - 2026-01-24​

Changed​

  • User-facing strings consolidated into internal/messages/ package for consistency and maintainability.
  • Python release tools (extract-checksum.py, update-formula.py) replaced with Go implementations in internal/tools/.
  • Release test script reorganized into modular components (scripts/test-release/release_tests.sh, scripts/test-release/tool_tests.sh).
  • Slash command templates (find-issues.md, finish-task.md) simplified to reduce duplication with base instructions; formatting rules now delegate to individual memory file templates.

v0.5.2 - 2026-01-24​

Added​

  • Automated Homebrew tap updates: release workflow now opens a PR against conn-castle/homebrew-tap to update the formula with the new tarball URL and SHA256.

v0.5.1 - 2026-01-23​

Added​

  • Source tarball (agent-layer-<version>.tar.gz) published with releases for Homebrew formula support.

Changed​

  • Release scripts now generate and verify the source tarball via git archive + gzip -n.
  • Documentation cleanup: simplified release process, corrected make dev description.

v0.5.0 - 2026-01-23​

Major shift from repo-local binary to globally installed CLI with per-repo version pinning.

Added​

  • Global CLI installation via Homebrew (brew install conn-castle/tap/agent-layer), shell script (macOS/Linux), or PowerShell (Windows).
  • al init command initializes .agent-layer/ and docs/agent-layer/ in any repo.
  • Per-repo version pinning via .agent-layer/al.version; global CLI dispatches to the pinned version automatically.
  • Cached binary downloads with SHA-256 verification; cached binaries stored in ~/.cache/agent-layer/versions/.
  • Shell completion for bash, zsh, and fish (al completion <shell> with optional --install flag).
  • Update checking: al init and al doctor warn when a newer release is available.
  • Linux desktop entry launcher (.agent-layer/open-vscode.desktop).
  • E2E test suite (scripts/test-e2e.sh) and release test script (scripts/test-release.sh).
  • Environment variables: AL_CACHE_DIR (override cache location), AL_VERSION (force version), AL_NO_NETWORK (disable downloads).

Changed​

  • Breaking: Repo-local ./al executable replaced with globally installed al CLI.
  • Breaking: al install renamed to al init.
  • Breaking: Repository moved from nicholasjconn/agent-layer to conn-castle/agent-layer.
  • Install script renamed from agent-layer-install.sh to al-install.sh.
  • al init --overwrite now prompts before each overwrite; use --force to skip prompts.
  • al init --version <tag> pins the repo to a specific release version.
  • Commands run from any subdirectory now resolve the repo root automatically.
  • .agent-layer/.gitignore added to ignore launchers, template copies, and backups.

Removed​

  • Repo-local ./al binary; global al dispatches to pinned versions as needed.
  • agent-layer-install.sh (replaced by al-install.sh).

v0.4.0 - 2026-01-21​

Added​

  • al doctor command reports missing secrets, disabled servers, and common misconfigurations.
  • al wizard command provides interactive setup for approval modes, agent enablement, model selection, MCP servers, secrets, and warning thresholds.
  • Configurable warning system with thresholds for instruction token count, MCP server/tool counts, and schema token sizes.
  • Antigravity slash commands now generate skills in .agent/skills/<command>/SKILL.md.
  • VS Code launchers: macOS .app bundle (no Terminal window), macOS .command script, and Windows .bat file, all with CODEX_HOME support.
  • al install --no-wizard flag skips the post-install wizard prompt.
  • Atomic file writes across all sync operations prevent partial file corruption.

Changed​

  • al install now prompts to run the wizard after seeding files (interactive terminals only).
  • Gitignore patterns use root-anchored paths (/AGENTS.md instead of AGENTS.md) for precision.
  • Default Codex reasoning effort changed from xhigh to high.
  • Codex config header now warns about potential secrets in generated files.
  • Environment variable loading: process environment takes precedence; .agent-layer/.env fills missing keys only; empty values in .env are ignored.
  • Improved instruction and slash-command templates.

Fixed​

  • VS Code launcher now works correctly with proper error messages for missing code command.
  • MCP configuration for Codex HTTP servers now handles bearer token environment variables correctly.

v0.3.1 - 2026-01-19​

Added​

  • Installer failure output now includes clear, actionable error messages.

Fixed​

  • Installer checksum verification now handles SHA256SUMS entries with "./" prefixes.

Changed​

  • Quick start documentation no longer suggests manual install fallback when only ./al is present.

v0.3.0 - 2026-01-18​

Complete rewrite in Go for simpler installation and fewer moving parts.

Added​

  • Single repo-local Go binary (./al) replaces the Node.js codebase.
  • al install command for repository initialization with template seeding.
  • al install --overwrite flag to reset templates to defaults.
  • al sync command to regenerate client configs without launching.
  • Support for five clients: Gemini CLI, Claude Code CLI, VS Code/Copilot Chat, Codex CLI, and Antigravity.
  • Unified [[mcp.servers]] configuration in config.toml for both HTTP and stdio transports.
  • Approval modes (all, mcp, commands, none) with per-client projection.
  • ${ENV_VAR} substitution from .agent-layer/.env with client-specific placeholder syntax preservation.
  • Internal MCP prompt server for slash command discovery (auto-wired into client configs).
  • Golden-file tests for deterministic output validation.
  • Managed .gitignore block with customizable template (.agent-layer/gitignore.block).

Changed​

  • Breaking: Complete rewrite from Node.js to Go.
  • Breaking: Configuration moved from config/agents.json to .agent-layer/config.toml (TOML format).
  • Breaking: MCP servers now configured via [[mcp.servers]] arrays in config.toml.
  • CLI simplified: ./al <client> always syncs then launches.
  • Instructions now in .agent-layer/instructions/ (numbered markdown files, lexicographic order).
  • Slash commands now in .agent-layer/slash-commands/ (one markdown file per command).
  • Approved commands now in .agent-layer/commands.allow (one prefix per line).
  • Project memory standardized in docs/agent-layer/ (ISSUES.md, FEATURES.md, ROADMAP.md, DECISIONS.md, COMMANDS.md).

Removed​

  • Node.js codebase (src/lib/*.mjs, test files, package.json).
  • config/agents.json and separate MCP server configuration files.
  • Built-in Tavily MCP server (now configurable as external server in config.toml).

v0.2.0 - 2026-01-17​

Major architectural overhaul moving core logic from shell to Node.js.

Added​

  • Per-agent opt-in configuration via config/agents.json with interactive setup prompt.
  • HTTP transport support for MCP servers.
  • Tavily MCP server for web search capabilities.
  • ./al --version flag with dirty suffix for non-tagged commits.
  • User config preservation and backup during upgrades.

Changed​

  • Breaking: CLI entrypoint is now .agent-layer/agent-layer; ./al remains as the launcher wrapper in the parent root.
  • Root resolution, environment loading, and cleanup moved from shell to Node.js (src/lib/roots.mjs, src/lib/env.mjs, src/lib/cleanup.mjs).
  • Test framework migrated from Bats (shell) to Node.js native test runner.
  • GitHub MCP server switched to hosted HTTP endpoint with PAT authentication.
  • Architecture documentation updated to reflect new layer boundaries.

Removed​

  • Shell scripts: al, run.sh, setup.sh, clean.sh, check-updates.sh, open-vscode.command.
  • Shell-based root resolution: src/lib/parent-root.sh, src/lib/temp-parent-root.sh.

v0.1.0 - 2026-01-12​

Initial release.

Added​

  • Installer for per-project setup that pins .agent-layer/ to tagged releases, with upgrade, version, and dev-branch options.
  • Repo-local ./al launcher with sync and environment modes plus local update checks.
  • Sync pipeline that generates client configs from .agent-layer/config sources.
  • MCP prompt server that exposes workflows as prompts.
  • Project memory templates and setup/bootstrap helpers.