Upgrade ai coding ok

Upgrade ai-coding-ok

How to upgrade the ai-coding-ok framework in your project to the latest version while preserving all your customizations.

---

Quick upgrade (Claude Code)

In any project with ai-coding-ok installed, in Claude Code:

upgrade ai-coding-ok

Or in Chinese:

升级 ai-coding-ok

Claude will:

1. Detect your installed version
2. Compare against the latest templates
3. Show you what will change
4. Ask for confirmation
5. Apply changes, preserving your project customizations
6. Record the upgrade in task-history.md

---

What happens during an upgrade

Step 1: Version detection

Claude reads the version markers from your installed files:

AGENTS.md:               <!-- ai-coding-ok: v2.2.0 -->
copilot-instructions.md: <!-- ai-coding-ok: v2.2.0 -->
system-prompt.md:        <!-- ai-coding-ok: v2.2.0 -->
...

Reports: "Detected ai-coding-ok v2.2.0. Latest: v3.1.0."

Step 2: Change identification

Claude diffs your installed files against the latest templates, identifying three types of changes:

Type	Example	Action
Added section	New "Five-Layer Defense" section in AGENTS.md	Insert into your file
Removed section	Old section no longer in template	Ask before deleting
Modified section	PDCA mandate updated from 3 to 7 steps	Smart merge

Step 3: Confirmation

Claude shows the change list and asks:

Upgrade v2.2.0 → v3.1.0

Changes:
✅ AGENTS.md — Plan phase expanded 3→7 steps
✅ AGENTS.md — Act phase added document sync step
✅ copilot-instructions.md — mandatory Memory Updates section
✅ system-prompt.md — Act phase annotated ⚠️ must not skip
✅ CLAUDE.md — STOP instruction added
✅ .claude/settings.local.json — hooks template added
✅ All files — version markers bumped to v3.1.0

Continue? (Y/n)

Step 4: Apply changes

For each changed file, Claude:

1. Reads your current file
2. Applies only the framework changes
3. Preserves your project-specific content (name, tech stack, architecture, custom ADRs)
4. Updates the version marker

Step 5: Record

### [TASK-XXX] Upgrade ai-coding-ok v2.2.0 → v3.1.0
- **Date**: 2026-07-14
- **Type**: chore
- **Summary**: Upgraded framework. Sections added: Plan 7-step, Act doc sync, Memory Updates enforcement, CLAUDE.md STOP, hooks template. All project customizations preserved.
- **Files changed**: AGENTS.md, CLAUDE.md, copilot-instructions.md, system-prompt.md, settings.local.json

---

Upgrade paths

If you're on an older version, upgrades are applied in order:

Current	Target	Main changes
v1.0	v2.0	AGENTS.md + copilot-instructions.md gain PDCA mandate; workflows.md Step 5 annotated; version markers added
v2.0	v2.1.0	Cursor support (.cursor/rules/ai-coding-ok.mdc); OpenCode support
v2.1.0	v2.2.0	CLAUDE.md auto-load shim; SKILL.md description rewrite
v2.2.0	v3.0.0	Plugin packaging; bilingual templates (en/zh); README split
v3.0.0	v3.0.1	Act phase enforcement in output format; mandatory Memory Updates section
v3.0.1	v3.1.0	Five-layer defense system; Claude Code hooks; install-time auto-config

Each step is applied sequentially. You can upgrade across multiple versions in one command.

---

What is preserved during upgrade

Claude explicitly preserves:

• Project identity: name, description, type
• Tech stack: language, framework, database, test framework
• Architecture: diagrams, module lists, data flow descriptions
• Custom constraints: your project-specific rules
• Custom ADRs: your decisions in decisions-log.md
• Task history: all entries in task-history.md
• Known issues: your entries in project-memory.md
• Custom workflows: any scenarios you added to workflows.md
• Coding standards: your language-specific conventions

---

Manual upgrade (Copilot / Cursor)

For non-Claude Code users:

1. Pull the latest ai-coding-ok:

   cd ~/tools/ai-coding-ok && git pull

2. Open scripts/upgrade-prompt.md

3. Copy the entire content and paste into Copilot Chat / Cursor Agent

4. The AI will detect your version, show changes, and apply them

---

After upgrade

Verify

bash scripts/verify.sh

Check version markers

head -1 AGENTS.md
# Should show: <!-- ai-coding-ok: v3.1.0 -->

Review changes

git diff

Focus on files that had sections added or modified. Confirm your project customizations are intact.

Test PDCA

Make a small change and confirm the AI still:

1. Reads memory files before coding
2. Includes a ## Memory Updates section in the response

---

Rollback

If the upgrade causes issues:

# Revert to before the upgrade commit
git checkout HEAD~1 -- AGENTS.md CLAUDE.md .github/

# Re-run the upgrade with more caution
upgrade ai-coding-ok
# Review each change carefully before confirming

Or restore from git:

git diff HEAD~1 -- AGENTS.md .github/
# Review what changed
git checkout HEAD~1 -- AGENTS.md .github/

---

Common upgrade issues

"Upgrade says 'no changes needed' but I know I'm on an old version"

Your version markers might be missing or corrupted. Check:

head -1 AGENTS.md
head -1 .github/copilot-instructions.md

If markers are missing, manually add them (e.g., <!-- ai-coding-ok: v2.0 -->) and retry.

"Upgrade wants to delete a section I customized"

Choose "skip" for that section during confirmation. The upgrade is interactive — you can accept/reject individual changes.

"After upgrade, the AI's behavior changed unexpectedly"

The upgrade may have updated system-prompt.md or workflows.md in ways that affect behavior. Review the diff:

git diff HEAD~1 -- .github/agent/system-prompt.md .github/agent/workflows.md

Adjust the new content to match your preferences.

---

Next steps

• Changelog — full version history
• Version Management — how versioning works
• Customization Guide — what's safe to customize after upgrade