Upgrade Guide

You have Atomic Spec installed in one or more projects and want to refresh them with the latest framework files (knowledge stations, subagents, templates, slash commands, scripts).

Quick Reference

What Changed in v0.5.0? (unreleased — ships after v0.4.1)

v0.5 closes the “testing is always Later” gap in AI-driven development. Every /atomicspec.clarify session for a web / mobile / desktop feature now asks one yes/no question — “Do you want automated tests for this feature?” — with app-specific rationale explaining why tests would save time. If yes, a new /plan sub-phase (Phase 0.85) derives per-layer Test Strategy autonomously from the pinned tech stack, presents a 7-column table for row-by-row HITL approval, and hands the resulting per-task slice to /tasks for Directive 8 embedding. Zero derivation tokens spent without recorded consent. Consumers who answer No are never re-asked. Fully backwards compatible. Feature closes G-002 in docs/internal/known-gaps.md.

• Registry testing.enabled field — new primary field in the existing testing: block. Values: null | true | false | "later". Controls whether Phase 0.85 runs. Value coercion enforced (only boolean/null/"later" accepted; string "yes"/"1" triggers a hard warning). Provenance tracked at _provenance.testing.enabled (human | accepted_recommendation | migrated_v0.5). The 6 existing testing.* fields (unit_framework etc.) become derivation outputs, no longer asked at /clarify.
• Registry lifecycle.intent field — new field extending the existing lifecycle: block. Values: production | prototype | throwaway | null. When production, suppress_when anti-keywords are bypassed unconditionally — a “spike” in a production feature’s spec cannot silently suppress the testing question.
• suppress_when trigger-schema field — new optional predicate on triggers in .specify/knowledge/triggers.yaml. Soft-warning + AskUserQuestion (never silent skip) when the spec matches anti-keywords AND lifecycle.intent != production. Closes the “payment-spike” footgun.
• testing.enabled architectural lurker — .specify/knowledge/architectural-lurkers.yaml gains a must_decide entry in the web_with_api, mobile, and desktop packs. library pack unchanged (already requires testing.unit_framework since v0.2).
• New testing keyword trigger — fires on test / TDD / coverage / regression / QA / CI / flake / quality gate / reliability SLO / P0 bug.
• Phase 0 Testing-Consent Migration hook — runs alongside the interview_completed genesis check, before Phase 0.5 begins. Fires exactly once when testing.enabled key is absent (v0.4-shaped registry). Non-interactive session skips silently.
• Phase 0.85 — Test Strategy Derivation (HITL #3.5) — new sub-phase in /atomicspec.plan between Phase 0.8 and Phase 0.9. Six-branch consent gate, per-row HITL edit variant (copies Phase 0.7’s per-warning pattern), 7-column Test Strategy table (Layer | Test Type | Tool | Coverage | Task-Range Slot | Subagent / Source | Rationale) with visible MANUAL-CONFIGURE fallback when no subagent matches.
• ## Test Strategy section in plan-template.md — placed between Tech Stack Validation and Frontend/UI Specifications.
• Test Strategy Slice embedding in /atomicspec.tasks — new task-generation step slices plan.md’s Test Strategy per test-writing T-XXX file and embeds the row (framework, coverage, layer, rationale) into the task’s Embedded Context. Implementer respects D3 Context Pinning without ever reading plan.md.
• 12 testing subagents imported into .specify/subagents/testing/: pytest, django-tdd, kotlin (kotest-mockk), cargo, go, googletest, springboot-tdd, laravel-tdd, playwright-webapp, playwright-e2e, android ADB verification, k6 load. Registered in .specify/subagents/_index.md under a new ## Testing category.
• Directive 8 companion row — new “Test Strategy Slice (v0.5+)” row in the Embedded Context table, immediately below “Efficiency Tier Hint (v0.4+)”.
• Directive 6 rationale clarification — one-sentence extended-scope note (“Derivation checkpoints for tech-stack subdomains inherit this directive’s HITL contract”). Not an amendment — the 4-checkpoint floor stays.
• Full details: see the testing derivation guide.

Deliberately scope-out for v0.5.x

Twelve testing subagents ship in v0.5 — mostly backend + mobile + language-native. Stacks without derived support fall back to MANUAL-CONFIGURE (visible marker in the Test Strategy table, never silent): native iOS (XCTest), Electron/Tauri desktop, web frontend JS/TS unit (Vitest/Jest/RTL), web accessibility (axe / screen-reader), API security, Ruby/Rails, Node/TS backend unit, .NET/C#, Vue/Svelte/Angular frontend unit. Contract testing, visual regression, mutation testing all deferred to v0.6+. Users on those stacks see the fallback marker and configure manually; iterated in later releases.

Migration note

Fully backwards compatible. Consumer projects on v0.4.x upgrade to v0.5.0 with no behavior change unless the user opts in at the migration prompt:

1. Existing registry.yaml files without testing.enabled key continue to work. First /atomicspec.plan under v0.5 fires the Phase 0 migration hook exactly once, with Recommended: Yes and app-specific rationale.
2. On Yes: writes testing.enabled: true with _provenance: migrated_v0.5. Phase 0.85 fires an inline confirm-migration prompt before deriving.
3. On No: writes testing.enabled: false with _provenance: human. Phase 0.85 skips silently on every subsequent run. Never re-asks.
4. Non-interactive session (--no-review or no TTY): skips migration silently. Phase 0.85 later skips too. No infinite loop.
5. Contract test: v0.5-migrated consumer that answered No produces byte-identical v0.4.1 output on subsequent runs.

To opt in immediately without waiting for the migration prompt:

1. Edit specs/_defaults/registry.yaml: set testing.enabled: true and _provenance.testing.enabled: human.
2. Run /atomicspec.plan — Phase 0.85 fires derivation directly.

What Changed in v0.4.0?

v0.4 introduces advisory model-tier routing: consumer projects can split coordinator-role turns (Phase 0 orientation, task selection, gate checks, stamp writes) from implementer-role turns (code generation, verification loop) and HITL turns (Directive 6 checkpoints) onto different model tiers. Fully backwards compatible. Shipped advisor-off by default; consumer projects on v0.3 see byte-for-byte identical behavior after upgrade until they explicitly flip it.

• Registry efficiency: block (schema 5 → 6) — new top-level with model_tiers.{coordinator,implementer,hitl}, advisor_enabled: false, snapshot_recorded: null. Governed by Directive 7 — every field is amended via the standard /atomicspec.registry HITL flow.
• Three new CLI subcommands:
  • atomicspec select-model --phase <coordinator|implementer|hitl> — machine-readable model lookup. Prints the configured tier or empty on advisor-off; exit code always 0 so bash/PowerShell callers can MODEL=$(atomicspec select-model ...) cleanly.
  • atomicspec cost snapshot --amount <USD> --provider <name> — record a single-number cost snapshot. Any provider. Writes .specify/efficiency-snapshots/<YYYY-MM-DD-HHMMSSuuuuuu>-<scope>.md with YAML frontmatter.
  • atomicspec efficiency report --advisory — print the tier resolution table + recent snapshots. Header labeled “advisory only, measurement in v0.4.1” verbatim.
• Phase 1 Prelude — Efficiency Hint added to /atomicspec.specify, /plan, /tasks, /implement command templates at their Phase 0 anchors. Advisory prose only — does not affect Directive 3 pinning, gate criteria, or downstream steps.
• Directive 7 clause amendment — efficiency.model_tiers mapping added to the scope list. Nine directives stays nine — clause amendment, not new directive.
• Directive 8 companion row — added “Efficiency Tier Hint” row to the Embedded Context table.
• Orientation-run files gain ## Efficiency H2 section — /atomicspec.implement §0.6 emits advisor_enabled state + tier map source + resolved models per phase.
• pyyaml>=6.0,<7 added to the Python CLI. First YAML lib in the CLI; safe_load-only by design (ruff S506 enforced). Matches upstream github/spec-kit and every peer template-distributor CLI.
• Full details: see the efficiency guide.

Deliberately deferred to v0.4.1

• atomicspec baseline record --feature NNN on Claude Code’s stable hook API (Stop / PostToolUse / SessionEnd) + Anthropic Console CSV import for API-key users + Codex CLI JSONL adapter (behind separate flag). This is the per-feature measurement primitive that gates the advisor default flip.
• Flip advisor_enabled: true default — behind the promotion evidence bar (≥60% of tracked consumer projects show non-empty baselines across ≥2 providers; measured cost reduction ≥15% median; zero P0 governance regressions for 4 weeks).

Deliberately scope-out for v0.4.x

Cursor / Windsurf / Copilot / Gemini CLI have no equivalent hook API and no path to token-level measurement in v0.4.x. The tier config still applies to them advisorily; they just don’t measure. This is honest about a real constraint.

Migration note

Fully backwards compatible. Consumer projects on v0.3 upgrade to v0.4 with no behavior change unless they explicitly flip advisor_enabled: true in the new efficiency: block. Existing registry.yaml files with version: 5 continue to work — the check-prerequisites awk classifier ignores the new top-level. Fresh atomicspec init writes version: 6 with the advisor off. Command templates gain the “Phase 1 Prelude” block; when advisor_enabled: false, atomicspec select-model returns empty and templates proceed with byte-for-byte v0.3 behavior.

To try the advisor:

1. Edit specs/_defaults/registry.yaml, set efficiency.advisor_enabled: true.
2. (Optional) Replace model_tiers.* with provider-native model IDs for OpenAI / Google / etc.
3. Run any /atomicspec.* command — resolved tier appears in orientation evidence.

What Changed in v0.3.0?

v0.3 closes the cross-provider AI handoff gap. When Claude crashes mid-feature and you switch to Codex (or hit a quota cliff and fall over to Gemini), the receiving AI now self-orients from files alone — detects which artifacts are half-done, prompts you on conflict, and resumes cleanly without silently overwriting work. A new sibling directive (9) governs this read surface narrowly so Directive 3’s Context Pinning stays verbatim.

• Lifecycle Markers — every artifact (spec.md, clarify-log.md, plan.md, index.md, traceability.md, tasks/T-*.md) now carries a ## Lifecycle Markers block recording start/end timestamps and provider names for authoring + implementation lifecycles. Script-managed; AIs MUST NEVER hand-write stamps.
• scripts/{bash,powershell}/stamp-lifecycle.{sh,ps1} — deterministic gate for all Lifecycle Markers writes. Subcommands: init / start / end / status. 18-provider allowlist, ISO 8601 UTC timestamps, atomic writes.
• Article IX, Directive 9: Orientation Read Surface — a NEW sibling to Directive 3 (Context Pinning). Defines a narrow, single-shot carve-out for the Phase 0 Orientation procedure in /atomicspec.implement: read Lifecycle Markers blocks via the status script (NOT direct file reads of plan.md / spec.md / clarify-log.md), classify outcome as Clean / Stale / Conflict, write evidence to orientation-runs/<ts>-<provider>.md, present resume menu on conflict via AskUserQuestion. Directive 3 stays verbatim — no governance creep.
• Registry schema bump (4 → 5) — adds lifecycle.stale_threshold_days (default 7). Framework-level setting, no HITL gate required.
• clarify-log.md (new artifact) + scripts/{bash,powershell}/clarify-session-bootstrap.{sh,ps1} — clarify is an EDIT to spec.md, not a re-author, so spec.md is NEVER re-stamped per session. Each clarify run gets its own H2 ## Session <ts> block in clarify-log.md.
• Atomic Spec Orientation block auto-injected into every agent file (CLAUDE.md / GEMINI.md / AGENTS.md / .cursorrules / 12 others) by scripts/{bash,powershell}/inject-orientation.{sh,ps1}. Sentinel-versioned; auto-upgrades older blocks; never downgrades newer ones.
• init-project.{sh,ps1} substitutes the {{AGENT_NAME}} placeholder in command templates with the --ai value at copy time.

Honest disclosure

Orientation Evidence enforcement — the current release defines orientation-runs/<ts>-<provider>.md as REQUIRED by policy. The runtime gate (check-prerequisites --check-orientation) blocking Phase 1 on missing evidence was originally scoped for v0.3.1, which was not released; it now targets v0.4.1 alongside per-feature baseline record.

Migration note

Fully backwards compatible. v0.2.x projects work without changes. New Lifecycle Markers blocks are added incrementally by command runs; pre-v0.3 artifacts without stamps are treated as legacy_closed by the Phase 0 Orientation procedure.

What Changed in v0.2.0?

v0.2 closes the “AI silently picks structural defaults” gap. Fully backwards compatible — v0.1.x registries merge cleanly without any migration script.

• Hardened /atomicspec.clarify — extends the v0.1 ambiguity scan with three new phases: architectural lurkers (scoped by app type), trigger-driven probes (declarative keyword table at .specify/knowledge/triggers.yaml), and compliance probes (GDPR / PCI / HIPAA / COPPA / SOC 2 with two-step Y/N/Unsure gates). Lite mode (~5 min, 7 questions, default) or Detailed (~15 min, ~22 questions).
• Pre-plan interview gate — /atomicspec.plan Phase 0 now checks interview_completed in the registry. If null, surfaces a three-option AskUserQuestion (run clarify / proceed with assumed defaults / cancel) instead of an abort wall.
• Reverse-traceability exit gate — new Phase 10 in /atomicspec.implement. Compares every changed file against traceability.md; flags orphans (files no task referenced). Catches the “Docker without asking” failure mode after the fact. Warn-only by default in v0.2.0; promoted to enforce-by-default in v0.2.1.
• Registry schema bumped 3 → 4 — 12 new fields covering payment, email, domain primitives (money / id / time), integrations (webhook ingress, outbound HTTP), compliance, deployment target, search, scheduling, i18n, file storage, job durability. Plus a _provenance block tracking how each decision was made (human / accepted_recommendation / manifest_scan / unknown_legacy).
• Directive 7 (Project Defaults Registry) clause amendment — now explicitly covers any structural choice that pervades the codebase (containerization, deployment target, monorepo layout, framework choice, cross-cutting infrastructure, domain primitives, auth model, observability stack, CI/CD platform). The “Docker-without-asking” failure mode is now a Directive 7 violation, not an unspecified blind spot. Eight directives stays eight — clause amendment, not a new directive.
• Two new subagents: backend/metering-engineer (entitlement schemas, two-phase enforcement, AI token controls) and ux/interaction-patterns (state-machine templates, hide-vs-disable RBAC, limit-threshold UI surfacing).
• Governance / pattern split — 7 Knowledge Stations (05, 06, 07, 08, 09, 10, 15) gained cross-reference headers pointing at the matching subagent for code-level patterns. Full content migration deferred to v0.2.1 (cross-refs work today).

Migration note

No action required for v0.1.x projects. New interview_completed field defaults to null; /atomicspec.clarify is advertised (soft nudge from specify) but does NOT block — only blocks at /atomicspec.plan Phase 0 if the registry is genuinely uninterviewed. New registry fields default to null and fill in as features hit them.

What Changed in v0.1.1?

• PyPI release: atomicspec is now installable via uv tool install atomic-spec
• Auto-publish pipeline: pushing a v* tag builds 34 per-agent template zips and uploads to PyPI via Trusted Publishing
• cursor-agent accepted alongside cursor as an agent key
• Tech-stack gate tightened: check-prerequisites now rejects unfilled [placeholder] values instead of silently passing
• Registry template de-duplicated: target_platform: and mobile: sections no longer appear twice
• Registry-absent gate added: check-prerequisites --check-gates now fails if specs/_defaults/registry.yaml is missing (escape hatch: ATOMIC_SPEC_NO_REGISTRY=1). Direct users to the new /atomicspec.registry command to create it from project manifests.
• New /atomicspec.registry command: discovers defaults from package.json, pyproject.toml, Cargo.toml, go.mod, Docker/CI configs, etc., batches HITL confirmation, and writes registry.yaml + changelog.md atomically.
• /atomicspec.implement Phase 9 (Registry Sync on Exit): every completed implementation now scans for new project-wide patterns (tenancy filtering, error envelope format, structured logging, etc.) and prompts the user to add them to the registry. Satisfies Directive 7 “Protocol — On Exit” at feature level. Only exception to Context Pinning — scoped to Phase 9 only.

Migration note for projects without a registry

If you upgrade a project that was initialized before v0.1.1 and doesn’t have specs/_defaults/registry.yaml, the first /atomicspec.tasks or /atomicspec.implement run will now fail the gate with a clear instruction. Two options:

• Recommended: run /atomicspec.registry once to discover your existing defaults from manifests and confirm them.
• Quick escape: export ATOMIC_SPEC_NO_REGISTRY=1 (bash) or $env:ATOMIC_SPEC_NO_REGISTRY='1' (PowerShell) to proceed with graceful degradation for this session. Decisions will be feature-specific until you run /atomicspec.registry or /atomicspec.plan Phase 0.9 populates the registry.

Part 1: Refresh the source

If you installed via PyPI, upgrade the CLI:

uv tool install atomic-spec --force

If you cloned the repo instead, pull the latest version:

cd /path/to/Atomic-Spec
git pull origin main

Part 2: Re-initialize the project

Option A — PyPI CLI (recommended)

Run inside your project directory:

atomicspec init --here --force --ai claude

Replace claude with your AI assistant. See Supported AI Agents for the full list.

Option B — Clone path

Run the initializer from your local clone against the existing project:

# macOS / Linux / WSL
./init-project.sh /path/to/existing/project --ai claude

# Windows PowerShell
.\init-project.ps1 -TargetPath "D:\path\to\existing\project" -AIAgent "claude"

[!WARNING] Re-initialization replaces .specify/, templates/, memory/, and scripts/ inside the target project. If you customized any of those files, commit them to git first, then reconcile after the upgrade.

What gets updated vs. what stays safe

Updated by re-init

• ✅ Slash command files (.claude/commands/, .github/prompts/, etc.)
• ✅ Scripts (.specify/scripts/)
• ✅ Templates (.specify/templates/)
• ✅ Memory files (.specify/memory/) — ⚠️ see warnings below

Never touched by re-init

• ✅ Your specifications (specs/001-my-feature/spec.md, etc.)
• ✅ Your implementation plans and tasks (specs/001-my-feature/plan.md, specs/001-my-feature/tasks/, specs/001-my-feature/index.md, specs/001-my-feature/traceability.md, etc.)
• ✅ Your source code
• ✅ Your git history

The specs/ directory is excluded from template packages and is never overwritten.

Understanding the --force flag

Without --force, the CLI warns you and asks for confirmation:

Warning: Current directory is not empty (25 items)
Template files will be merged with existing content and may overwrite existing files
Proceed? [y/N]

With --force, it skips the confirmation and proceeds immediately. Your specs/ directory is always safe — --force only affects template files (commands, scripts, templates, memory).

⚠️ Important Warnings

1. Constitution file will be overwritten

Known issue: atomicspec init --here --force currently overwrites .specify/memory/constitution.md with the default template, erasing any customizations you made.

Workaround:

# 1. Back up your constitution before upgrading
cp .specify/memory/constitution.md .specify/memory/constitution-backup.md

# 2. Run the upgrade
atomicspec init --here --force --ai claude

# 3. Restore your customized constitution
mv .specify/memory/constitution-backup.md .specify/memory/constitution.md

Or use git to restore it:

# After upgrade, restore from git history
git restore .specify/memory/constitution.md

2. Custom template modifications

If you customized any templates in .specify/templates/, the upgrade will overwrite them. Back them up first:

# Back up custom templates
cp -r .specify/templates .specify/templates-backup

# After upgrade, merge your changes back manually

3. Duplicate slash commands (IDE-based agents)

Some IDE-based agents (like Kilo Code, Windsurf) may show duplicate slash commands after upgrading — both old and new versions appear.

Solution: Manually delete the old command files from your agent’s folder.

Example for Kilo Code:

cd .kilocode/rules/
ls -la
rm atomicspec.specify-old.md
rm atomicspec.plan-v1.md

Restart your IDE to refresh the command list.

Common Scenarios

Scenario 1: “I just want new slash commands”

# Refresh the CLI
uv tool install atomic-spec --force

# Update project files
atomicspec init --here --force --ai claude

# Restore your constitution if customized
git restore .specify/memory/constitution.md

Scenario 2: “I customized templates and constitution”

# 1. Back up customizations
cp .specify/memory/constitution.md /tmp/constitution-backup.md
cp -r .specify/templates /tmp/templates-backup

# 2. Refresh the CLI
uv tool install atomic-spec --force

# 3. Update the project
atomicspec init --here --force --ai claude

# 4. Restore customizations
mv /tmp/constitution-backup.md .specify/memory/constitution.md
# Manually merge template changes if needed

Scenario 3: “I see duplicate slash commands in my IDE”

This happens with IDE-based agents (Kilo Code, Windsurf, Roo Code, etc.).

cd .kilocode/rules/
ls -la
rm atomicspec.old-command-name.md

Then restart your IDE.

Scenario 4: “I’m working on a project without Git”

If you initialized your project with --no-git, you can still upgrade:

cp .specify/memory/constitution.md /tmp/constitution-backup.md
atomicspec init --here --force --ai claude --no-git
mv /tmp/constitution-backup.md .specify/memory/constitution.md

The --no-git flag skips git initialization but doesn’t affect file updates.

Using --no-git

The --no-git flag tells Atomic Spec to skip git repository initialization. Use when:

• You manage version control differently (Mercurial, SVN, etc.)
• Your project is part of a larger monorepo with existing git setup
• You’re experimenting and don’t want version control yet

During initial setup:

atomicspec init my-project --ai claude --no-git

During upgrade:

atomicspec init --here --force --ai claude --no-git

What --no-git does NOT do

• Does NOT prevent file updates
• Does NOT skip slash command installation
• Does NOT affect template merging

It only skips running git init and creating the initial commit.

Working without Git

If you use --no-git, you’ll need to manage feature directories manually by setting SPECIFY_FEATURE before using planning commands:

# Bash/Zsh
export SPECIFY_FEATURE="001-my-feature"

# PowerShell
$env:SPECIFY_FEATURE = "001-my-feature"

Without git, Atomic Spec can’t detect your current branch name to determine the active feature. The environment variable provides that context manually.

Troubleshooting

”Slash commands not showing up after upgrade”

Cause: Agent didn’t reload command files.

Fix:

1. Restart your IDE/editor completely (not just reload window)

2. For CLI-based agents, verify files exist:

   ls -la .claude/commands/      # Claude Code
   ls -la .gemini/commands/      # Gemini
   ls -la .cursor/commands/      # Cursor

3. Check agent-specific setup:

   • Codex requires CODEX_HOME environment variable
   • Some agents need workspace restart or cache clearing

”I lost my constitution customizations”

# If you committed before upgrading
git restore .specify/memory/constitution.md

# If you backed up manually
cp /tmp/constitution-backup.md .specify/memory/constitution.md

Prevention: Always commit or back up constitution.md before upgrading.

”CLI upgrade doesn’t seem to work"

# List installed uv tools
uv tool list

# Reinstall if missing
uv tool uninstall atomic-spec
uv tool install atomic-spec

# Verify executable path
which atomicspec         # macOS/Linux
where.exe atomicspec     # Windows

"Do I need to run atomicspec every time I open my project?”

No. You only run atomicspec init once per project (or when upgrading).

Once you’ve run atomicspec init, slash commands (/atomicspec.specify, /atomicspec.plan, etc.) are permanently installed in your project’s agent folder (.claude/, .github/prompts/, etc.). Your AI assistant reads these files directly — no need to run atomicspec again.

If your agent isn’t recognizing slash commands:

1. Verify command files exist (see above)
2. Restart your IDE/editor completely
3. Check you’re in the correct directory where you ran atomicspec init

Version Compatibility

Atomic Spec follows semantic versioning. The CLI and project files are designed to be compatible within the same major version.

Best practice: Keep the CLI and project files in sync by upgrading both together during major version changes.

Next Steps

After upgrading:

• Test new slash commands: Run /atomicspec.constitution or another command to verify everything works
• Review release notes: Check Atomic Spec Releases for new features and breaking changes
• Update workflows: If new commands were added, update your team’s development workflows
• Check documentation: Visit the Atomic Spec repository for updated guides