codebase-integration

After EVERY integration, you MUST:

1. Update CLAUDE.md Section 3 - Add new agents to routing table
2. Update CLAUDE.md Section 8.5 - Add new skills to workflow enhancement section
3. Update CLAUDE.md Section 3 Workflows - Add new workflows
4. Update learnings.md - Document integration summary

Verification (RUN THIS):

```bash

# Check all new items are in CLAUDE.md

grep "" .claude/CLAUDE.md || echo "ERROR: NOT IN CLAUDE.md!"

```

WHY: Items not in CLAUDE.md are invisible to the Router and will never be used.

---

• Integrating skills/agents from archived codebases
• Porting functionality from external tools (MCP servers, CLI tools)
• Consolidating duplicate functionality
• Importing templates or code style guides

Phase 1: Source Analysis

Analyze the source codebase to understand what can be integrated.

```javascript

Task({

subagent_type: 'Explore',

description: 'Analyze source codebase',

prompt: `Analyze the codebase at for integration.

1. Skills (SKILL.md files, command definitions)
2. Agents (agent definitions, personas)
3. Templates (code styles, boilerplate)
4. Workflows (multi-step processes)
5. Hooks (pre/post execution)
6. Tools (CLI scripts, utilities)

• What exists in source
• What already exists in agent-studio (duplicates)
• What is new and should be imported

`,

});

```

Phase 2: Gap Analysis

Compare source with existing agent-studio content.

Check for duplicates:

```bash

# For each skill in source

grep -l "" .claude/skills/*/SKILL.md

# For each agent in source

grep -l "" .claude/agents/*/.md

```

Create integration plan:

• NEW: Items that don't exist
• ENHANCE: Existing items that can be improved
• SKIP: Duplicates or incompatible items

Phase 3: Create Tasks

Create trackable tasks for each integration item.

```javascript

TaskCreate({

subject: 'Import from ',

description: 'Import, transform, validate, test',

activeForm: 'Importing ',

});

```

Phase 4: Transform and Import

For each item, apply necessary transformations:

Skills:

1. Add proper YAML frontmatter (name, description, version, model, tools)
2. Add Memory Protocol section at end
3. Update paths to use .claude/ structure
4. Validate against skill-definition.schema.json

Agents:

1. Add proper YAML frontmatter (name, description, tools, model, temperature, skills)
2. Add Memory Protocol section
3. Ensure Step 0: Load Skills is present
4. Validate against agent-definition.schema.json

Templates:

1. Place in .claude/templates//
2. Ensure proper markdown formatting

Workflows:

1. Place in .claude/workflows/ or .claude/workflows/enterprise/
2. Update Task() examples to use proper spawn patterns
3. Reference correct agent paths

Phase 5: Validation

Run validation on all imported items.

```bash

# Validate agents

node .claude/tools/validate-agents.mjs

# Check skill frontmatter

for skill in .claude/skills/*/SKILL.md; do

grep -q "^name:" "$skill" || echo "MISSING name: $skill"

grep -q "Memory Protocol" "$skill" || echo "MISSING Memory Protocol: $skill"

done

# Run tests

npm test

```

Phase 6: Router Update (MANDATORY)

This step is NOT OPTIONAL. Integration is incomplete without it.

For new agents - Add to CLAUDE.md Section 3:

```markdown

| Request Type | agent-name | .claude/agents//.md |

```

For new skills - Add to CLAUDE.md Section 8.5:

```markdown

<Skill Name>

Use when :

\\\`javascript

Skill({ skill: '' });

\\\`

```

For new workflows - Add to CLAUDE.md Section 3 Workflows:

```markdown

• .claude/workflows/.md -

```

Phase 7: Documentation

Create integration report and update memory.

Integration Report (.claude/context/reports/-integration-report.md):

```markdown

# Integration Report

Date: YYYY-MM-DD

Status: COMPLETE

• Skills:
• Agents:
• Templates:
• Workflows:

• Section 3: Added
• Section 8.5: Added
• Section 3 Workflows: Added

```

Update learnings.md:

```markdown

Status: COMPLETE

Items Integrated

Key Patterns

CLAUDE.md Updated

• Section 3:
• Section 8.5:

```

Phase 8: Verification

Final verification that integration is complete.

```bash

# Verify all items in CLAUDE.md

for item in ; do

grep -q "$item" .claude/CLAUDE.md || echo "MISSING: $item"

done

# Verify tests pass

npm test

# Verify no broken references

node .claude/tools/validate-agents.mjs

```

Use this checklist for every integration:

```

[ ] Phase 1: Source analyzed

[ ] Phase 2: Gap analysis complete

[ ] Phase 3: Tasks created

[ ] Phase 4: Items transformed and imported

[ ] Phase 5: Validation passed

[ ] Phase 6: CLAUDE.md updated (CRITICAL)

[ ] Section 3 routing table (agents)

[ ] Section 8.5 skills (skills)

[ ] Section 3 workflows (workflows)

[ ] Phase 7: Documentation created

[ ] Integration report

[ ] learnings.md updated

[ ] Phase 8: Final verification passed

```

Path Updates

| Source Pattern | Target Pattern |

| ------------------- | ---------------------- |

| conductor/ | .claude/context/ |

| plugins/ | .claude/ |

| ~/.config/claude/ | .claude/ |

| superpowers: | Direct skill reference |

Frontmatter Requirements

Skills:

```yaml

---

name: skill-name

description: One-line description

version: 1.0.0

model: sonnet

invoked_by: both

user_invocable: true

tools: [Read, Write, Edit, Bash, Glob, Grep]

---

```

Agents:

```yaml

---

name: agent-name

description: One-line description

tools: [Read, Write, Edit, Bash, Glob, Grep]

model: sonnet

temperature: 0.3

priority: medium

skills:

- skill-1

- skill-2

context_files:

- .claude/context/memory/learnings.md

---

```

DO NOT:

• Import without updating CLAUDE.md (Router won't know about new items)
• Skip Memory Protocol section (Agents will forget learnings)
• Copy files without transforming paths (Broken references)
• Skip validation (Silent failures)
• Create duplicate skills/agents (Confusion, wasted context)

DO:

• Check for existing equivalents first
• Transform all paths to .claude/ structure
• Add proper frontmatter
• Add Memory Protocol
• Update CLAUDE.md routing table
• Create integration report
• Update learnings.md

This skill implements the external integration workflow. For the complete multi-agent orchestration pattern, see:

Workflow: .claude/workflows/core/external-integration.md

Phases covered by this skill:

• Phase 1: Clone & Isolate (Step 1.1 - isolation to .claude/context/tmp/)
• Phase 6: Execute integration (file copying, registry updates, CLAUDE.md updates)
• Phase 7: Cleanup (temp directory removal, documentation)

Phases handled by other agents:

• Phase 0: Pre-Check (architect - checks if artifact already exists)
• Phase 2-3: Explore & Plan (architect explores source/target, planner creates integration plan)
• Phase 4-5: Review & Consolidate (architect + security-architect parallel review, planner merges feedback)
• Phase 8: Verify (qa - validates integration works correctly)

Alignment Notes:

• Temp Directory: Use .claude/context/tmp// for isolation (matches workflow)
• Rollback: If integration fails, use git restore for CLAUDE.md and registries (see workflow rollback procedure)
• Gate Decisions: Respect workflow gate decisions (BLOCKING issues stop integration)

When to use this skill vs the workflow:

• This skill: Direct integration when you are the executing agent and have already completed planning/review
• Full workflow: Multi-agent orchestration requiring parallel exploration, security review, and QA verification

• skill-creator - Creating new skills from scratch
• agent-creator - Creating new agents from scratch
• project-onboarding - Understanding existing codebases

Before starting:

Read .claude/context/memory/learnings.md

After completing:

• Integration complete -> .claude/context/memory/learnings.md
• Issue encountered -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

> ASSUME INTERRUPTION: If it's not in memory, it didn't happen.