Update Guide — Safe Workspace Updates

Updating your PARA Workspace is simple. Since v1.5.0, the agent handles the entire process — pre-flight checks, dry-run preview, live update, error recovery, and post-update verification — all in one command.

🚀 How to Update

Just tell your AI Agent:

/update

That’s it. The agent will:

✅ Check network connectivity and Git status
📋 Show a dry-run preview of what will change
❓ Ask for your confirmation before applying
🔄 Execute ./para update with automatic error recovery
✅ Verify the update succeeded (kernel version, migration log, audit log)

[!TIP] You don’t need to run any manual checks. The /update workflow handles everything automatically, including diagnosing and recovering from common errors like network issues, Git conflicts, or permission problems.

After the Update

Once /update completes successfully, open each of your active projects to let the agent detect and apply any needed adjustments:

/para-audit update [project-name]

This checks your project against the new version’s requirements and suggests fixes (e.g., missing fields in project.md, outdated task format).

📋 Example: Upgrading from v1.4.x to v1.5.3

Here’s a real-world example of upgrading a workspace from v1.4.x to v1.5.3 — the biggest jump with the most improvements:

Step 1: Run `/update`

The agent auto-detects you’re on v1.4.x, downloads v1.5.3, runs migrations, and verifies.

Step 2: Check each project

/para-audit update my-project

The agent will detect and suggest fixes:

Finding	Suggestion
`project.md` missing `has_rules` field	Add `has_rules: true` if project has custom rules
`sprint-current.md` uses old table format	Clear old content → agent will use new Hot Lane format
`✅ Done` tasks still in `backlog.md`	Run `/backlog clean` to move to `done.md`

Step 3: Enjoy the improvements

After updating, you’ll experience:

🔥 Hot Lane — Agent writes quick tasks directly to sprint-current.md
📉 78% fewer tokens — /open reads only backlog summary + hot lane
🔄 Two-Tier Rule Gate — Rules loaded on demand, no waste
📦 Governed Libraries — Rules & workflows auto-sync via catalog.yml

/open v1.4.x: ~100-3000 tokens (reads full backlog)
/open v1.5.3: ~260-640 tokens (summary + hot lane)
                        ↑ 78% reduction in worst case

📋 What’s New in v1.6.4 & v1.6.5

v1.6.4 — Para-Kit & Recursive Sync

Feature	Description
Para-Kit Skill	New colocated skill with Quick Reference Card (I1–I11, H1–H9) — agents get instant workspace knowledge
Recursive sync	`sync_directory_recursive()` handles arbitrarily nested skill subdirectories during update
Git hash detection	`update.sh` detects changes via commit hash — accurate even for hotfixes without version bumps
Skills backup	`/backup skills` — new backup target for `.agent/skills/`
Upstream field	`upstream` field added to project.md schema (inverse of `downstream`)

v1.6.5 — Update Flow Fix

Fix	Impact
Version direction	`update.sh` now shows ⏬ for downgrades and skips migration
Migration history	`migrate.sh` only writes to `history.log` when steps actually ran
Decision gates	`/update` workflow warns when Kernel > Repo VERSION (workspace ahead of local repo)
validator.sh	`update.sh` loads `validator.sh` at startup for `semver_gte` access

🔧 Manual CLI (Advanced)

If you prefer not to use the agent, you can update manually:

./para update --dry-run    # Preview changes first
./para update              # Apply update

Common issues:

Error	Solution
Network error	Use `./para install` for offline sync
Git conflict	`git stash` then retry
Permission denied	`chmod +x para` then retry

→ Workflow /update — Full command reference → Workflow /para-audit — Post-update compliance → Learn: Kernel — Understand what’s being updated