Codebase Integration

Codebase Integration

Structured workflow for integrating external codebases (skills, agents, templates, workflows) into the agent-studio framework.

ROUTER UPDATE REQUIRED (CRITICAL - FINAL STEP)

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):

# Check all new items are in CLAUDE.md
grep "<item-name>" .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.

When to Use

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

8-Phase Integration Workflow

Phase 1: Source Analysis

Analyze the source codebase to understand what can be integrated.

Task({
  subagent_type: 'Explore',
  description: 'Analyze source codebase',
  prompt: `Analyze the codebase at <source-path> for integration.

## Find
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)

## Report
- 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:

# For each skill in source
grep -l "<skill-name>" .claude/skills/*/SKILL.md

# For each agent in source
grep -l "<agent-name>" .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.

TaskCreate({
  subject: 'Import <item-name> from <source>',
  description: 'Import, transform, validate, test',
  activeForm: 'Importing <item-name>',
});

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/<category>/
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.

# 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:

| Request Type | agent-name | `.claude/agents/<category>/<name>.md` |

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

### <Skill Name>

Use when <trigger condition>:

\`\`\`javascript
Skill({ skill: '<skill-name>' });
\`\`\`

<One-line description of what it does.>

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

- `.claude/workflows/<name>.md` - <Description>

Phase 7: Documentation

Create integration report and update memory.

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

# <Source> Integration Report

**Date**: YYYY-MM-DD
**Status**: COMPLETE

## Items Integrated

- Skills: <count>
- Agents: <count>
- Templates: <count>
- Workflows: <count>

## Files Created

<list>

## Files Modified

<list>

## CLAUDE.md Updates

- Section 3: Added <agents>
- Section 8.5: Added <skills>
- Section 3 Workflows: Added <workflows>

Update learnings.md:

## [YYYY-MM-DD] <Source> Integration Complete

**Status**: COMPLETE

### Items Integrated

- <list>

### Key Patterns

- <patterns adopted>

### CLAUDE.md Updated

- Section 3: <agents>
- Section 8.5: <skills>

Phase 8: Verification

Final verification that integration is complete.

# Verify all items in CLAUDE.md
for item in <item1> <item2> <item3>; 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

Integration Checklist

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

Common Transformations

Path Updates

Frontmatter Requirements

Skills:

---
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:

---
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
---

Anti-Patterns

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

Workflow Integration

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/<repo-name>/ 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

Related Skills

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

Memory Protocol (MANDATORY)

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.