Workflow Update

Updates the agentic-workflows instruction set and applies changes that go beyond simple file replacement.

The update-check script handles file downloads by SHA-256 comparison, but some updates require additional work:

• New entries in .claude/settings.json (env vars, permissions)
• New symlinks or directory structures
• Workflow state schema migrations (new fields in .workflow-state.json)
• New MCP configs or skill registrations

This skill handles the full update lifecycle.

/workflow-update

Run a full update cycle.

Steps:

Step 1: Run the update check script

bash .agentic-workflows/scripts/update-check.sh

Capture the full output. Parse it for:

• Version change: v{old} → v{new} or "Already up-to-date"
• Updated files: lines starting with + (e.g., + .agentic-workflows/fragments/workflow-rules.md)
• Failed files: lines starting with !
• Whether AGENTS.md was regenerated

If the script reports "Already up-to-date" and nothing failed, inform the user and stop.

Step 2: Summarize changes

For each updated file, read it and summarize what changed compared to what was there before. Group by category:

Category	Files	Impact
Fragments	fragments/*.md	Shared rules — affects AGENTS.md (already regenerated by script)
Workflow	workflow/*.json	Phase/gate/schema changes — may need state migration
Templates	templates/**/*.md	PRD/PR/track templates — affects new artifacts only
Skills	skills/*/SKILL.md	Skill behavior changes — new commands, updated steps
Scripts	scripts/*.sh	Update/generation scripts — already applied
Config	scaffolds, templates	Dev environment scaffolding

Present a concise summary to the user:

Updated from v2.0.38 → v2.0.39 (5 files changed)

Fragments:
  - workflow-rules: Rewritten Subagent Orchestration section (intercom, model/effort per task)
  - brainstorm-conventions: When the orchestrator should re-ask after a context-changing answer

Config:
  - run-all-template.sh: Added new service entry

Step 3: Detect and apply non-trivial changes

After file replacement, check if any updated files require additional work that the script couldn't do:

3a. Settings changes (.claude/settings.json)

Check if any updated agent or fragment references new env vars or experimental features.

# Check for env var references in updated files
grep -r "CLAUDE_CODE_EXPERIMENTAL" .agentic-workflows/ --include="*.md" | grep -v ".git"

Compare against current .claude/settings.json. If there are env vars referenced in agents that aren't in settings:

1. Read current .claude/settings.json (create if missing)
2. Show the user what needs to be added (env vars referenced by updated fragments/skills)
3. Ask for confirmation before modifying settings.json
4. Merge new env vars into the existing env object (preserve existing entries)

3b. Workflow state schema migration

If workflow/state-schema.json was updated:

1. Read the new schema
2. Read .workflow-state.json (if it exists)
3. Check for new required fields that are missing from existing state
4. If migration is needed:
   • Show user what fields are new and their defaults
   • Ask for confirmation
   • Add missing fields with sensible defaults (null for nullable, empty object/array for collections)
5. If no .workflow-state.json exists, skip — it will be created correctly when needed

3c. Symlinks

If skill paths changed in the manifest:

1. Check the skills symlinks exist (.claude/skills, .cursor/skills, .opencode/skills → .agents/skills)
2. If any are missing or point to wrong targets, fix them
3. Report what was fixed

3e. Legacy installs without a snapshot (one-time)

Workspaces that last updated from a pre-4.0.0 install have no manifest.json snapshot in .agentic-workflows/, so update-check can't prune removed files. Run this cleanup once after the update lands (local .version or .agentic-workflows/.version < 4.0.0, or old roster files still present):

1. Agent files + symlinks. If .agentic-workflows/agents/<tool>/ contains frndos-files or exists at all, delete that directory tree. Then remove theagents symlinks it fed (.claude/agents, .cursor/agents, .opencode/agents, .amp/agents) if they are symlinks. Keep the skills` symlinks — those are still real.
2. Removed skills. Delete .agents/skills/jj-workflow/ and .agents/skills/workflow/references/agent-teams.md if present.
3. .claude/settings.json (show the diff to the user, confirm first): remove the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env entry (Team Session mode is gone), and drop these permission entries: mcp__lark__*, mcp__claude_ai_Lark__*, mcp__code-review-graph__*, Bash(jj workspace:*), Bash(jj git init:*), Bash(jj log:*), Bash(jj status:*). Lark is read-only via the Lark CLI now; code-reviews no longer use the MCP.
4. .workflow-state.json (preserve everything else): delete workspaces and workspace_meta at the top level; delete agent_teams inside any feature entry. Leave branch values alone — the new gates accept the legacy <worker>/vc- branch form.
5. .onboard-state.json: remove jj_available and claude_session_mode; write optional_services from the directories actually present (data-pipeline, desktop → "included" when the dir exists, "skipped" otherwise) and lark_cli: "skipped" (user can connect the Lark CLI anytime).

From v4.0.0 on, every self-update carries a manifest snapshot and prunes removed files automatically — this step exists only for installs predating the snapshot.

3f. New skills or skill changes

If any skill files were updated:

1. Inform user: "Skills were updated. Restart your agent session for changes to take effect."
2. List which skills changed and briefly what's different

Step 4: Final verification

After applying all changes:

1. Verify AGENTS.md is current:

   bash .agentic-workflows/scripts/generate-agents.sh
   

2. Verify symlinks:

   [ -L .claude/agents ] && echo "✓ .claude/agents" || echo "✗ .claude/agents missing"
   [ -L .claude/skills ] && echo "✓ .claude/skills" || echo "✗ .claude/skills missing"
   [ -f .claude/settings.json ] && echo "✓ .claude/settings.json" || echo "✗ .claude/settings.json missing"
   [ -f AGENTS.md ] && echo "✓ AGENTS.md" || echo "✗ AGENTS.md missing"
   [ -f CLAUDE.md ] || [ -L CLAUDE.md ] && echo "✓ CLAUDE.md" || echo "✗ CLAUDE.md missing"
   

3. Check version:

   cat .agentic-workflows/.version
   

4. Report:

   Update complete! v2.0.38 → v2.0.39
   
   Applied automatically:
     - 5 files replaced by update script
     - AGENTS.md regenerated
   
   Action needed:
     - Restart session to pick up skill changes
   

/workflow-update check

Dry-run — check for updates without applying them.

Steps:

1. Fetch remote manifest only:

   curl -fsSL "https://raw.githubusercontent.com/alva-intelligence/agentic-workflows/main/manifest.json" 2>/dev/null
   

2. Compare remote version with local .agentic-workflows/.version
3. If different, list which files would be updated (SHA comparison)
4. Do NOT download or apply anything

/workflow-update verify

Verify the current installation is healthy.

Steps:

1. Check all symlinks are correct
2. Check .claude/settings.json has required env vars
3. Check AGENTS.md matches what generate-agents.sh would produce
4. Check .agentic-workflows/.version matches manifest version
5. Report any issues found