Upgrading ArcKit

This guide covers how to upgrade ArcKit CLI to the latest version while preserving your project data and custom templates.

Upgrade Process Overview

ArcKit uses a safe upgrade pattern:

Upgrade the CLI tool (pip or uv)
Re-run arckit init in your existing project
Templates and scripts are refreshed in .arckit/templates/
Your customizations in .arckit/templates-custom/ are preserved
Your project data in projects/ is untouched

Upgrading the CLI Tool

Using pip

# Step 1: Upgrade ArcKit CLI
pip install --upgrade git+https://github.com/tractorjuice/arc-kit.git

# Verify new version
arckit --version

Using uv (Recommended)

# Step 1: Upgrade ArcKit CLI
uv tool upgrade arckit-cli --from git+https://github.com/tractorjuice/arc-kit.git

# Verify new version
arckit --version

Check Latest Version

See the latest release on GitHub. Current stable version: v3.0.9

Upgrading an Existing Project

After upgrading the CLI, update your project:

# Step 2: Navigate to your project
cd /path/to/your-existing-project

# Step 3: Re-run init in place
arckit init --here --ai codex

# Or for OpenCode:
arckit init --here --ai opencode

Always use --here flag when upgrading. Without it, arckit init will try to create a new directory.

What Gets Updated

When you re-run arckit init --here:

Directory/File	Action
`.arckit/templates/`	✅ Refreshed with latest defaults
`.arckit/templates-custom/`	✅ Preserved (your customizations untouched)
`.arckit/scripts/`	✅ Refreshed with latest automation scripts
`.codex/prompts/`	✅ Refreshed with latest commands
`.opencode/commands/`	✅ Refreshed with latest commands
`projects/`	✅ Preserved (all project data untouched)
`docs/`	✅ Refreshed (unless `--minimal` used originally)
`VERSION`	✅ Updated to new version
`CHANGELOG.md`	✅ Updated with release notes

Minimal Install Projects

If you originally ran arckit init --minimal, re-run with --minimal:

arckit init --here --ai codex --minimal

This skips updating docs/ directory.

Preserving Custom Templates

Your custom templates are automatically preserved:

# Before upgrade
.arckit/
  templates/              # Default templates (OLD)
  templates-custom/       # Your customizations (PRESERVED)
    requirements-template.md
    risk-register-template.md

# After upgrade
.arckit/
  templates/              # Default templates (NEW)
  templates-custom/       # Your customizations (PRESERVED)
    requirements-template.md
    risk-register-template.md

Commands continue using your customizations from templates-custom/.

Adopting New Template Features

After upgrading, you may want to adopt new features in default templates:

1. Check What Changed

Compare your custom template with the new default:

# Show differences
diff .arckit/templates/requirements-template.md \
     .arckit/templates-custom/requirements-template.md

2. Selectively Merge Changes

You can:

Copy entire new section (e.g., new compliance framework)
Add new fields (e.g., new document control field)
Update existing sections (e.g., improved acceptance criteria format)
Leave customizations intact (e.g., your organization’s branding)

3. Example: Adopting New DPIA Section

If the new default requirements-template.md adds a DPIA section:

## Data Protection Impact Assessment (DPIA)

**DPIA Required**: [YES/NO]
- Large-scale processing: [YES/NO]
- Automated decision-making: [YES/NO]
- Special category data: [YES/NO]

Copy this section into your custom template:

# Edit your custom template
code .arckit/templates-custom/requirements-template.md

# Add the new DPIA section
# Adjust field labels if needed for your organization

Upgrading from v0.x to v3.x

If upgrading from v0.x (pre-January 2025), there are breaking changes:

1. Filename Convention Changed

Old convention (v0.x):

projects/001-project-name/
  requirements-v1.md
  risk-register-v1.md
  sow-v1.md

New convention (v3.x):

projects/001-project-name/
  ARC-001-REQ-v1.0.md
  ARC-001-RISK-v1.0.md
  ARC-001-SOW-v1.0.md

Document ID format: ARC-{PROJECT_ID}-{DOC_TYPE}-v{VERSION}

2. Migration Script

If you have v0.x files, rename them manually:

# Example migration for project 001
cd projects/001-project-name/

mv requirements-v1.md ARC-001-REQ-v1.0.md
mv risk-register-v1.md ARC-001-RISK-v1.0.md
mv sow-v1.md ARC-001-SOW-v1.0.md
mv stakeholder-analysis-v1.md ARC-001-STKE-v1.0.md
mv business-case-v1.md ARC-001-SOBC-v1.0.md

3. Document Control Fields

v3.x templates include more structured Document Control:

## Document Control

| Field | Value |
|-------|-------|
| **Document ID** | ARC-001-REQ-v1.0 |
| **Document Type** | Requirements Specification |
| **Project** | Payment Gateway (Project 001) |
| **Classification** | OFFICIAL-SENSITIVE |
| **Status** | DRAFT |
| **Version** | 1.0 |
| **Created Date** | 2025-03-04 |
| **Last Modified** | 2025-03-04 |
| **Review Date** | 2025-04-04 |
| **Owner** | [OWNER_NAME_AND_ROLE] |
| **Reviewed By** | [PENDING] |
| **Approved By** | [PENDING] |
| **Distribution** | Project Team, Architecture Team |

Update your existing documents to include this section.

Upgrading Claude Code Plugin

For Claude Code users: Updates are automatic via the marketplace — no manual action needed. To force an update:

/plugin marketplace update tractorjuice/arc-kit

Upgrading Gemini CLI Extension

For Gemini CLI users:

gemini extensions update arckit

Checking Your Version

CLI Version

arckit --version

Project Version

Check the VERSION file in your project:

cat VERSION

Template Version

Check the template header:

> **Template Origin**: Official | **ArcKit Version**: 3.0.9 | **Command**: `/arckit.requirements`

Release Notes

See the CHANGELOG.md for detailed release notes. Recent major releases:

v3.0.9 (Current)

Added /arckit.datascout for external data source discovery
Added /arckit.presentation for MARP slide decks
Enhanced /arckit.traceability with pre-processor hook
Improved /arckit.backlog with multi-factor prioritization

v3.0.0 (Major)

New document ID convention (ARC-{PROJECT_ID}-{DOC_TYPE}-v{VERSION})
Structured Document Control section
Template customization system (.arckit/templates-custom/)
54 commands (up from 32 in v0.x)

Rollback Strategy

If you need to rollback:

CLI Rollback

# Pin to specific version
pip install git+https://github.com/tractorjuice/[email protected]

# Or with uv
uv tool install arckit-cli --from git+https://github.com/tractorjuice/[email protected]

Project Rollback

If re-running arckit init --here caused issues:

Restore from git:

git checkout HEAD -- .arckit/ .codex/

Or restore from backup:

cp -r .arckit.backup/ .arckit/

Always commit your project to git before upgrading. This provides a safety net.

Best Practices

1. Test in Development First

Before upgrading production projects:

# Clone project to test
cp -r my-production-project my-production-project-test
cd my-production-project-test

# Upgrade test copy
arckit init --here --ai codex

# Verify commands work
# Then upgrade production

2. Commit Before Upgrading

git add .
git commit -m "Before ArcKit upgrade to v3.0.9"

3. Review CHANGELOG First

Check for breaking changes:

# View latest changes
curl https://raw.githubusercontent.com/tractorjuice/arc-kit/main/CHANGELOG.md

4. Update Dependencies

After upgrading, update related tools:

# If using Codex CLI
pip install --upgrade codex

# If using OpenCode CLI
pip install --upgrade opencode

5. Re-run Key Commands

After upgrading, re-run a command to verify:

# Test command execution
/arckit.requirements Update requirements for project 001

Troubleshooting

Command Not Found After Upgrade

Symptom: arckit: command not found Fix:

# Ensure installation path is in PATH
export PATH="$HOME/.local/bin:$PATH"

# Or reinstall
pip install --force-reinstall git+https://github.com/tractorjuice/arc-kit.git

Templates Not Updating

Symptom: Commands use old templates after upgrade Fix:

# Re-run init with --here
arckit init --here --ai codex

# Verify templates updated
ls -la .arckit/templates/

Custom Templates Overwritten

Symptom: Custom templates lost after upgrade This should never happen if using --here flag correctly. Recovery:

Check git history: git log -- .arckit/templates-custom/
Restore from git: git checkout HEAD~1 -- .arckit/templates-custom/

Commands Fail After Upgrade

Symptom: /arckit.requirements fails with error Fix:

Check error message for missing fields
Update custom template to include new required fields
Compare custom template with default template

Upgrading Multiple Projects

If you manage multiple ArcKit projects:

#!/bin/bash
# upgrade-all-arckit-projects.sh

PROJECTS=(
  "/path/to/project-1"
  "/path/to/project-2"
  "/path/to/project-3"
)

for project in "${PROJECTS[@]}"; do
  echo "Upgrading $project..."
  cd "$project"
  arckit init --here --ai codex
  echo "✅ $project upgraded"
done

Getting Help

If you encounter issues during upgrade:

Check documentation: https://github.com/tractorjuice/arc-kit
File an issue: https://github.com/tractorjuice/arc-kit/issues
Ask on discussions: https://github.com/tractorjuice/arc-kit/discussions

Get Started

Core Concepts

Governance Workflow

Vendor Procurement

Design & Review

UK Government Compliance

Guides

​Upgrade Process Overview

​Upgrading the CLI Tool

​Using pip

​Using uv (Recommended)

​Check Latest Version

​Upgrading an Existing Project

​What Gets Updated

​Minimal Install Projects

​Preserving Custom Templates

​Adopting New Template Features

​1. Check What Changed

​2. Selectively Merge Changes

​3. Example: Adopting New DPIA Section

​Upgrading from v0.x to v3.x

​1. Filename Convention Changed

​2. Migration Script

​3. Document Control Fields

​Upgrading Claude Code Plugin

​Upgrading Gemini CLI Extension

​Checking Your Version

​CLI Version

​Project Version

​Template Version

​Release Notes

​v3.0.9 (Current)

​v3.0.0 (Major)

​Rollback Strategy

​CLI Rollback

​Project Rollback

​Best Practices

​1. Test in Development First

​2. Commit Before Upgrading

​3. Review CHANGELOG First

​4. Update Dependencies

​5. Re-run Key Commands

​Troubleshooting

​Command Not Found After Upgrade

​Templates Not Updating

​Custom Templates Overwritten

​Commands Fail After Upgrade

​Upgrading Multiple Projects

​Getting Help

​Further Reading

Build docs developers (and LLMs) love

Upgrade Process Overview

Upgrading the CLI Tool

Using pip

Using uv (Recommended)

Check Latest Version

Upgrading an Existing Project

What Gets Updated

Minimal Install Projects

Preserving Custom Templates

Adopting New Template Features

1. Check What Changed

2. Selectively Merge Changes

3. Example: Adopting New DPIA Section

Upgrading from v0.x to v3.x

1. Filename Convention Changed

2. Migration Script

3. Document Control Fields

Upgrading Claude Code Plugin

Upgrading Gemini CLI Extension

Checking Your Version

CLI Version

Project Version

Template Version

Release Notes

v3.0.9 (Current)

v3.0.0 (Major)

Rollback Strategy

CLI Rollback

Project Rollback

Best Practices

1. Test in Development First

2. Commit Before Upgrading

3. Review CHANGELOG First

4. Update Dependencies

5. Re-run Key Commands

Troubleshooting

Command Not Found After Upgrade

Templates Not Updating

Custom Templates Overwritten

Commands Fail After Upgrade

Upgrading Multiple Projects

Getting Help

Further Reading