trellis-fusion

Fusion overlay for Trellis — adds plan-first workflow, TDD methodology, context recovery, and enhanced AI skills.

What is Fusion?

Fusion extends Trellis with:

• 7 AI Skills — brainstorm-plus, write-task-plan, execute-plan-tdd, harvest-learnings, systematic-debugging, review-with-agents, context-continuity
• 8 Slash Commands — /fusion:brainstorm-plus, /fusion:checkpoint, /fusion:resume-context, etc.
• 2 Hooks — automatic context checkpointing before compaction, session-start recovery
• Python Scripts — checkpoint/resume tools for context persistence
• Workflow Docs — fusion-workflow.md, quickref, maintenance guide

Quick Start

# Install into an existing Trellis project
cd your-project
npx trellis-fusion init

# Or auto-initialize Trellis + Fusion in one step
npx trellis-fusion init --with-trellis -u your-name --claude

Commands

trellis-fusion init [target-dir]

Install Fusion overlay into a project.

| Option | Description | |--------|-------------| | --with-trellis | Auto-run trellis init if not initialized | | -u, --user <name> | Developer name (passed to trellis init) | | --claude | Include Claude Code platform | | --codex | Include Codex platform | | --cursor | Include Cursor platform | | --gemini | Include Gemini CLI platform | | -f, --force | Overwrite existing files |

trellis-fusion update [target-dir]

Update Fusion files to the latest version. Uses SHA256 hash comparison to detect user modifications.

| Option | Description | |--------|-------------| | -a, --all | Also update base Trellis before updating Fusion | | --dry-run | Preview changes without applying | | -f, --force | Overwrite user-modified files | | -n, --create-new | Create .new files instead of overwriting |

trellis-fusion status [target-dir]

Show installation status and file integrity report.

Upgrade Flow

When a new version of trellis-fusion is published:

# Update Fusion only
npx trellis-fusion@latest update

# Update Trellis + Fusion together (one command)
npx trellis-fusion@latest update --all

# Preview changes first
npx trellis-fusion@latest update --all --dry-run

Files you haven't modified are updated automatically. Files you've customized are preserved (skipped by default, or use --force / --create-new).

Avoid Hook Loss

If you use trellis-fusion as an overlay on top of official Trellis, the recommended upgrade command is:

npx trellis-fusion@latest update --all

Why this is recommended:

• Phase A updates base Trellis first
• Phase B reapplies the Fusion overlay
• Phase B also re-checks and re-registers:
  • .claude/settings.json Fusion hooks
  • .codex/hooks.json Fusion SessionStart hook
  • .trellis/config.yaml update.skip entries

Avoid running only:

trellis update --force

That command may rewrite .claude/settings.json or .codex/hooks.json and remove Fusion-added hooks.

If that already happened, run:

npx trellis-fusion@latest update --force

If you want to upgrade base Trellis and reapply Fusion in one pass, use:

npx trellis-fusion@latest update --all --force

Quick checks:

• .claude/settings.json contains fusion-session-start.py
• .claude/settings.json contains fusion-pre-compact.py
• .codex/hooks.json contains fusion-session-start.py
• .trellis/config.yaml has Fusion paths under update.skip

How It Works

1. Install: Copies template files into your project under .agents/skills/, .claude/commands/fusion/, .claude/hooks/, .trellis/scripts/fusion/
2. Track: Records SHA256 hashes of all installed files in .fusion/hashes.json
3. Update: Compares current file hashes against recorded hashes to detect user modifications, then intelligently merges upstream changes

License

Apache-2.0