Options for integrating apex-workflows with Nebula when Nebula needs its own .claude directory

apex-workflows-integration-options.md

Integrating apex-workflows with Nebula

Problem Statement

Nebula currently uses a symlink approach to share Claude Code configuration from apex-workflows:

~/dev/Nebula/.claude → ~/dev/apex-workflows/.claude

This breaks when Nebula needs its own .claude/ directory tracked in source control. A path cannot be both a symlink and a real directory.

Requirements

• Nebula gets its own .claude/ directory (tracked in git)
• apex-workflows tools (commands, skills, agents) remain available in Nebula
• Nebula repo remains unaware of apex-workflows (no direct references in tracked files)
• apex-workflows stays a separate, reusable repository

What apex-workflows Provides

Type	Items
Commands	task-review, task-eval-analyze, subtask-scope, subtask-create, subtask-review, fetch-discord, task-idea-research, transcript-analyze
Agents	eval-analyzer, overlap-detector, task-reviewer, task-idea-researcher, strategy-extractor
Skills	nebula, discord-fetcher, tmux-apex, task-tools, transcript-patterns

---

Option 1: Symlink Subdirectories

Keep apex-workflows structure unchanged. Create a real .claude/ directory in Nebula and symlink individual items from apex-workflows into it.

Structure

Nebula/.claude/                        # Real directory (tracked)
├── commands/
│   ├── task-review.md        → ~/dev/apex-workflows/.claude/commands/task-review.md
│   ├── subtask-scope.md      → ~/dev/apex-workflows/.claude/commands/subtask-scope.md
│   └── ...
├── skills/
│   ├── nebula/               → ~/dev/apex-workflows/.claude/skills/nebula/
│   ├── discord-fetcher/      → ~/dev/apex-workflows/.claude/skills/discord-fetcher/
│   └── ...
├── agents/
│   ├── eval-analyzer.md      → ~/dev/apex-workflows/.claude/agents/eval-analyzer.md
│   └── ...
├── settings.json                      # Nebula-specific (tracked)
└── settings.local.json                # Local overrides (gitignored)

Setup

A setup script (living in apex-workflows or user's dotfiles) creates the symlinks:

#!/bin/bash
APEX="$HOME/dev/apex-workflows/.claude"
NEBULA="$HOME/dev/Nebula/.claude"

# Ensure target directories exist
mkdir -p "$NEBULA"/{commands,skills,agents}

# Symlink commands
for cmd in "$APEX"/commands/*.md; do
  ln -sf "$cmd" "$NEBULA/commands/$(basename "$cmd")"
done

# Symlink skills (directories)
for skill in "$APEX"/skills/*/; do
  ln -sf "$skill" "$NEBULA/skills/$(basename "$skill")"
done

# Symlink agents
for agent in "$APEX"/agents/*.md; do
  ln -sf "$agent" "$NEBULA/agents/$(basename "$agent")"
done

Nebula .gitignore Additions

# apex-workflows symlinks (not tracked)
.claude/commands/task-review.md
.claude/commands/task-eval-analyze.md
.claude/commands/subtask-*.md
.claude/commands/fetch-discord.md
.claude/commands/task-idea-research.md
.claude/commands/transcript-analyze.md
.claude/skills/nebula
.claude/skills/discord-fetcher
.claude/skills/tmux-apex
.claude/skills/task-tools
.claude/skills/transcript-patterns
.claude/agents/eval-analyzer.md
.claude/agents/overlap-detector.md
.claude/agents/task-reviewer.md
.claude/agents/task-idea-researcher.md
.claude/agents/strategy-extractor.md

Pros & Cons

Pros	Cons
No changes to apex-workflows	Breaks if apex-workflows path changes
Works immediately	Many symlinks to manage
Nebula repo stays clean	Verbose .gitignore
Simple mental model	Setup script required per-machine

---

Option 2: Plugin + Symlinked Commands

Restructure apex-workflows as a Claude Code plugin. Skills and agents are distributed via the plugin system. Commands (which plugins cannot distribute) are symlinked separately.

apex-workflows Structure (Updated)

apex-workflows/
├── .claude-plugin/
│   └── plugin.json
├── skills/                    # Plugin provides these
│   ├── nebula/
│   │   └── SKILL.md
│   ├── discord-fetcher/
│   │   └── SKILL.md
│   └── ...
├── agents/                    # Plugin provides these
│   ├── eval-analyzer.md
│   ├── overlap-detector.md
│   └── ...
├── commands/                  # NOT part of plugin (symlinked separately)
│   ├── task-review.md
│   └── ...
├── docs/
└── scripts/

plugin.json

{
  "name": "apex-workflows",
  "version": "1.0.0",
  "description": "Workflow tools for apex-arena task development and evaluation"
}

Nebula Structure

Nebula/.claude/
├── commands/                 → ~/dev/apex-workflows/commands/  # Single symlink
├── skills/                   # Empty or Nebula-specific only
├── agents/                   # Empty or Nebula-specific only
└── settings.json

Installation

# Install plugin (one-time per project)
cd ~/dev/Nebula
claude plugins add ~/dev/apex-workflows

# Symlink commands directory
ln -sf ~/dev/apex-workflows/commands ~/dev/Nebula/.claude/commands

Nebula .gitignore

# apex-workflows commands (symlinked)
.claude/commands

Pros & Cons

Pros	Cons
Official plugin mechanism	Requires apex-workflows restructure
Skills/agents managed cleanly	Commands still need symlink
Single symlink for commands	Plugin install step per-project
Portable to other projects	Two concepts to understand

---

Comparison

flowchart TB
    subgraph AW[apex-workflows repo]
        AWC[commands/]
        AWS[skills/]
        AWA[agents/]
    end

    subgraph NEB[Nebula repo]
        subgraph CLAUDE[.claude/]
            NC[commands/]
            NS[skills/]
            NA[agents/]
        end
    end

    subgraph OPT1[Option 1: Symlinks]
        direction LR
        O1["Individual symlinks<br/>for each file/dir"]
    end

    subgraph OPT2[Option 2: Plugin + Symlink]
        direction LR
        O2P["Plugin provides<br/>skills + agents"]
        O2S["Single symlink<br/>for commands/"]
    end

    AWC -.->|symlink| NC
    AWS -.->|symlink or plugin| NS
    AWA -.->|symlink or plugin| NA

Loading

Aspect	Option 1 (Symlinks)	Option 2 (Plugin + Symlink)
Upfront effort	Low	Medium
apex-workflows changes	None	Restructure + plugin.json
Nebula .gitignore	Verbose (many entries)	Minimal (one entry)
Maintenance	Higher (symlink per item)	Lower (plugin handles most)
Portability	Script per project	claude plugins add
Commands handling	Symlinks	Symlinks (same)

---

Recommendation

Option 1 if:

• You want the quickest path forward
• apex-workflows structure shouldn't change
• Only used with Nebula (or few projects)

Option 2 if:

• You want cleaner long-term maintenance
• apex-workflows will be used across multiple projects
• You prefer official plugin semantics for skills/agents

Both options keep Nebula's tracked files unaware of apex-workflows. The symlinks and plugin installation happen outside of version control.