Skip to content

AgentForge v0.2.3 — Upgrade-flow fix (bug-007)

Choose a tag to compare

View all tags
@kjoshi07 kjoshi07 released this 21 May 13:42
· 64 commits to main since this release
v0.2.3
0437e57

AgentForge v0.2.3 — Upgrade-flow fix

v0.2.2 fixed the scaffold path so fresh agentforge new agents
work end-to-end. But existing v0.2.x agents had no way to pull
those fixes — agentforge upgrade was non-functional. v0.2.3
fixes the upgrade path itself.

No new features. No breaking changes. Same 34 workspace
packages, same shipped surface as v0.2.2.

Highlights

  • agentforge upgrade actually works now. Existing agents
    scaffolded under v0.2.1 / v0.2.2 can pull the latest template
    fixes into their managed files via a single command:

    cd my-agent
agentforge upgrade --to 0.2.3

    Managed files refresh; forked files are preserved; any new
    managed files the upgraded template introduced get added.

  • agentforge new now persists .agentforge-state/answers.yml.
    Previously empty / missing on every fresh scaffold — which is
    why upgrade was unreachable in the first place.

  • End-to-end validated against agents/code-reviewer/. An
    agent scaffolded under buggy v0.2.1 templates was upgraded to
    v0.2.3 cleanly. All six v0.2.2 scaffold fixes propagated:
    agentforge-anthropic[anthropic] + python-dotenv in
    pyproject.toml, strategy: "react" in agentforge.yaml,
    load_dotenv() in main.py, the [project.scripts] entry,
    and the updated README invocation.

What's new

Fixed — bug-007 (both halves)

  • Part A — agentforge new doesn't persist scaffold answers.
    Copier's _answers_file directive is supposed to write
    .agentforge-state/answers.yml after rendering, but doesn't
    reliably for in-package templates. agentforge new now writes
    the file itself with _template_name + the four resolved
    template variables (project_name, project_slug,
    llm_provider, description).
  • Part B — agentforge upgrade failed with "Template not
    found".     The previous implementation called Copier's
    run_update, which expects the template source to be a
    VCS-versioned git repo. AgentForge's templates live inside the
    framework package (v0.2 compromise; the spec-aligned
    agentforge-templates separate repo is a v0.4 target). v0.2.3
    replaces run_update with a custom in-package upgrade that
    renders to a temp directory via run_copy and copies each
    non-forked managed file in place. Forked entries (set via
    agentforge fork) are preserved; new template files are
    added; the shared scaffold (_shared/ — runbooks +
    AGENTS.md / CLAUDE.md / .cursorrules / Copilot
    instructions) is re-injected so it tracks the new framework
    version.

Changed

  • 34 workspace packages bumped to 0.2.3. Cross-package
    pins refreshed from ~= 0.2.2 to ~= 0.2.3.

Added

  • docs/bugs/bug-007-upgrade-non-functional.md — full
    reproduction + root cause analysis + fix description.
  • Three regression tests in
    packages/agentforge/tests/unit/test_scaffold_state.py:
    • test_new_writes_answers_yml
    • test_upgrade_refreshes_managed_files
    • test_upgrade_preserves_forked_files

Breaking changes

None.

Upgrade guide

From v0.2.2 — fresh install

pip install "agentforge-py[anthropic]==0.2.3"

From v0.2.2 — existing scaffolded agent

cd my-agent
agentforge upgrade --to 0.2.3
uv sync

For agents scaffolded under v0.2.1 or earlier that pre-date
the bug-007 fix: .agentforge-state/answers.yml is missing.
Hand-write it before upgrade:

# .agentforge-state/answers.yml
_template_name: minimal   # or whichever template the agent was scaffolded from
_template_version: 0.2.1
project_name: My Agent
project_slug: my-agent
llm_provider: anthropic   # or bedrock / openai
description: An AgentForge agent.

Then agentforge upgrade --to 0.2.3 works as documented.

Coordinated release train

Per ADR-0015, every release bumps every in-scope workspace
package to the same version. v0.2.3 ships the same 34 packages
as v0.2.2 at 0.2.3 with cross-package pins refreshed.

Acknowledgements

Thanks to kjoshi — designer, implementer, reviewer.
Generated with Claude Code
(Anthropic) as the primary AI co-author per the
Co-Authored-By: commit trailers.

Full changelog

What's next

v0.3 backlog unchanged — see
docs/roadmap.md. v0.4 candidate: the
spec-aligned agentforge-templates separate-repo migration that
restores Copier's three-way merge for managed files (today's
v0.2.3 upgrade overwrites managed files wholesale instead of
merging — relies on the agentforge fork flag to preserve
user-edited files).

Assets 2
Loading