archflow-migrate

Migrates Archflow roadmap schema v1.0 sprints to v2.0 releases reconstructed from git evidence.

28|4|Updated Mar 12, 2026
One-click install
npx skills add https://github.com/AZidan/archflow --skill archflow-migrate-azidan
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: archflow-migrate
Source: https://github.com/AZidan/archflow/tree/main/adapters/copilot/.github/skills/archflow-migrate
Command: npx skills add https://github.com/AZidan/archflow --skill archflow-migrate-azidan

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml.

What problem does it solve? Projects onboarded with Archflow schema v1.0 organize work as sprints, but sprints are time-boxes that often shipped nothing, making it impossible to know what actually reached production. This Skill upgrades those projects to the v2.0 multi-file release model by reconstructing real releases from git shipping evidence instead of sprint boundaries. ## Core Features & Use Cases - Dry-run planning: Runs a deterministic Python engine in dry-run mode first, showing the detected v1 variant, deploy boundary, reconstructed release timeline, and warnings before writing anything. - Git-based release reconstruction: Detects deploy-pipeline boundaries and prod-branch merges to rebuild a true release history, routing shipped work to archived releases and unshipped work to the backlog. - Safe, reversible apply: Backs up the v1 roadmap to .archflow/backup-v1/, writes the v2.0 layout (roadmap index, backlog, release files, history), and enforces the one-active-release invariant. - Use Case: A team with a 5,000-line v1.0 roadmap.yaml containing dozens of sprints runs the migration to get a clean v2.0 structure where shipped features appear as archived releases and remaining work lands in a detailed backlog. ## Quick Start Ask the agent to run /archflow-migrate to dry-run the migration of your v1.0 Archflow project, review the reconstructed release plan, then confirm to apply it.

Frequently Asked Questions about archflow-migrate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate an Archflow project from schema v1.0 to v2.0?

Run /archflow-migrate, which first executes migrate.py in dry-run mode to show the reconstructed release plan. After you confirm the plan, it applies the migration, backing up v1 to .archflow/backup-v1/ and writing the v2.0 roadmap, backlog, and release files.

How does the migration reconstruct releases from sprints?

It treats sprints as time-boxes, not releases, and rebuilds releases from git evidence: the first commit of deploy infrastructure marks a baseline boundary, and prod-branch merges define release events. Done work is dated from commit subjects and routed to archived releases.

Is the Archflow v1.0 to v2.0 migration reversible?

Yes, the migration is non-destructive and reversible. It only modifies the .archflow/ directory, preserves the entire v1 roadmap under .archflow/backup-v1/, and writes nothing until you confirm the dry-run plan and pass --apply.

What happens when multiple sprints are marked in_progress?

The engine refuses to guess because v2.0 allows at most one in_progress release. It warns during the dry run and requires you to specify which sprint is truly active using the --active flag before applying.

What dependencies does the Archflow migration script need?

The migration engine is a Python script requiring python3 and the pyyaml package. It runs against the target project root and reads git history, so the project must be a git repository with shipping history available.