Changelog

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

[0.3.3] - 2025-12-14

Documentation

  • Organization: Refactored Man Pages to have a single top-level Title (# H1) and shifted all other sections down (# H2) to fix the flatten Table of Contents on ReadTheDocs/Sphinx.

  • Versioning: Updated docs/conf.py to read the version dynamically from the VERSION file.

Build System

  • Cleanup: Updated .gitignore to exclude generated man pages and removed them from the root directory.

  • Magefile: Updated Docs target to support the new header structure (--shift-heading-level-by=-1) and output to docs/_build/man/.

  • Nix: Updated flake.nix to use pandoc --shift-heading-level-by=-1 during installation.

[0.3.2] - 2025-12-14

Documentation

  • Validation: Document reconciliation.

[0.3.1] - 2025-12-14

Windows Support

  • Paths: Updated path resolution to respect %APPDATA% and %LOCALAPPDATA% on Windows.

  • Symlinks: Added detection for Windows runtime to provide helpful error messages about Developer Mode/Admin privileges.

[0.3.0] - 2025-12-14

Refactoring & Architecture

  • Canonical Target as Source of Truth: The main symlink (default $XDG_CONFIG_HOME/agents/AGENTS.md) is now the single source of truth for the active persona.

  • Reconcile: Now respects manual changes to the main symlink (drift) and propagates them to secondary targets.

  • Use: Optimized to calculate targets once and fail fast.

  • Unuse: Now explicitly clears internal state to prevent “resurrection” of old targets.

  • Robustness:

    • Fixed potential resource leaks (defer in loop).

    • Added chmod 0644 to copied files.

    • Downgraded go.mod to stable 1.23.0.

    • State Management: SaveState now replaces targets for a persona instead of merging/accumulating, preventing stale targets from persisting.

    • Drop Safety: Added guard to prevent drop from removing directories.

  • Modularization: Restructured codebase to Domain-Driven Design layout. Moved CLI logic to internal/cli, state management to internal/state, configuration to internal/config, and operations to internal/ops.

  • ApplyPersona: Improved reliability and error reporting in internal/ops/apply.go.

  • Environment Handling: robust mapping of environment variables to configuration (e.g., AGENTS_TARGET_FILE).

Features

  • Multi-Persona Status: status command now lists all tracked personas in the state file, indicating active status for each ([internal/cli/status.go](file:///home/sysop/Projects/agent-smith/internal/cli/status.go)).

  • Multi-Target Accumulation: use command now merges targets for the same persona instead of overwriting, enabling complex setups with multiple links/copies per persona.

  • Enhanced Error Reporting: CLI now consistently returns non-zero exit codes on failure and provides clearer error messages for permissions and missing files.

Testing

  • End-to-End Suite: Implemented comprehensive E2E tests in tests/e2e/ covering:

    • Flows: Happy path for list, use, status, reconcile.

    • Configuration Precedence: Verified Flag > Env > Config File priority.

    • Error Recovery: Automated verification of recovery from missing files, drift, and permission errors.

  • Unit Tests: Added dedicated unit tests for config, ops, and state packages.

CI/CD

  • GitHub Actions: Added .github/workflows/ci.yml to run nix flake check, unit tests, and E2E tests on detailed PRs and main branch pushes.

  • Contribution Guide: Added CONTRIBUTING.md with development instructions.

Documentation

  • Refactoring: Separated README.md to focus on high-level overview. Technical reference moved to docs/man/.

  • Man Pages: Added comprehensive man page suite:

    • agents(1): Main CLI reference.

    • agents-config(5): Configuration file format.

    • agents-status(5): Internal status file format.

    • agents-format(7): AGENTS.md concepts and specifications.

[0.2.0] - 2025-12-13

Core Features & Logic

  • XDG Compliance: implemented XDG Base Directory support (cmd/xdg.go).

    • Config is now looked for in $XDG_CONFIG_HOME/agent-smith (default ~/.config/agent-smith).

    • Personas are now stored in $XDG_DATA_HOME/agent-smith/personas (default ~/.local/share/agent-smith/personas).

    • State is stored in $XDG_STATE_HOME/agent-smith (default ~/.local/state/agent-smith).

  • Directory Structure: Renamed the default definition storage folder from agents to personas.

  • New Command: Added version command (cmd/version.go) reading from a new VERSION file.

  • Build System: Updated flake.nix and magefile.go to inject the version string during build.

  • Man Pages: Added Docs target to magefile.go and configured flake.nix to generate and install man pages using pandoc.

CLI Enhancements

  • Output Refinement:

    • use: Swapped output messages and changed terminology (“Persona switched”).

    • status: Removed verbose path output, keeping the user-friendly “Active Persona” message.

  • Terminology: Unified terminology to use “Persona” instead of “Agent” across help text and output (cmd/list.go, etc).

Documentation

  • Updated all paths to reflect XDG standards in README.md.

  • Added documentation for the version command.

  • Standardized terminology to “Persona”.

  • Fixed typos.

  • Man Page: Added automatic generation of agents.1 man page from README.md.

Testing

  • Integration Fix: Updated cmd/cli_test.go to match the actual output of the use command.

  • Test Updates: Updated cmd/root_test.go and cmd/state_test.go to verify XDG path resolution and the new personas directory default.