oimiragieo/artifact-integrator

Artifact Integrator

Purpose

Analyze newly created or modified artifacts for integration gaps and propose follow-up tasks to ensure full ecosystem integration.

When to Use

• After any artifact creator skill completes
• When Router Step 0.5 detects unprocessed integration queue entries
• When manually checking integration health
• When reviewing artifacts for completeness

Protocol

Step 1: Read Integration Queue

Read .claude/context/runtime/integration-queue.jsonl Filter for entries with "processed": false If no unprocessed entries, check if artifactId argument was provided for direct analysis.

Step 2: Analyze Each Artifact

For each unprocessed entry (or the directly specified artifact):

1. Load the artifact graph: require('.claude/lib/workflow/artifact-graph.cjs')
2. Load impact analyzer: require('.claude/lib/workflow/integration-impact.cjs')
3. Call analyzeImpact({ artifactId, changeType, graphPath })
4. Review the missingIntegrations and proposedTasks

Step 3: Generate Integration Plan

For each artifact with missing integrations:

Must-Have (P1) — Create tasks immediately:

• Missing catalog entry → TaskCreate: "Add {name} to {catalog}"
• Missing agent assignment → TaskCreate: "Assign {name} to relevant agent"
• Missing routing entry → TaskCreate: "Update routing for {name}"
• Missing hook registration → TaskCreate: "Register {name} in settings.json"

Should-Have (P2) — Create tasks with lower priority:

• Missing documentation → TaskCreate: "Document {name} in {doc}"
• Missing enforcement hook → TaskCreate: "Create enforcement for {name}"
• Missing tests → TaskCreate: "Write tests for {name}"

Nice-to-Have — Note but don't create tasks:

• Missing templates, optional docs

Step 3.1: Companion Matrix Analysis (Interwoven Creator Ecosystem)

For each artifact analyzed, run companion matrix validation to identify missing ecosystem companions:

Analysis:

1. Use companion-check.cjs from .claude/lib/creators/companion-check.cjs
2. Call checkCompanions(artifactType, artifactName) to get companion matrix
3. Parse the companion checklist into categories:
   • Required companions (must-have for artifact completeness)
   • Recommended companions (should-have for best practices)
   • Optional companions (nice-to-have for full integration)

Task Generation:

• For each missing required companion → Create P1 task: "Create {companion-type}:{companion-name} for {artifact-name}"
• For each missing recommended companion → Create P2 task: "Consider creating {companion-type}:{companion-name} for {artifact-name}"
• For missing optional companions → Note in report but don't create tasks

Safety Limits (SEC-ICE-002):

• Max auto-spawned tasks per artifact: 3 (prevent cascade creation)
• Max total companion tasks per integration run: 10 (prevent batch explosion)
• If limits exceeded, queue remaining companions for manual review with warning in report

Example:

### Companion Matrix Analysis: skill:rate-limiter

**Required Companions (MISSING):**

- [ ] hook:rate-limit-validator (validates rate limit headers) — **TASK CREATED** (P1)
- [ ] schema:rate-limit-config (validates configuration) — **TASK CREATED** (P1)

**Recommended Companions (MISSING):**

- [ ] template:rate-limit-pattern (template for rate limiting implementations) — **TASK CREATED** (P2)

**Optional Companions (MISSING):**

- [ ] workflow:rate-limit-setup (onboarding workflow) — noted for future consideration

**Safety Check:**

- Auto-spawned tasks: 3 (within limit of 3 per artifact)
- Total companion tasks this run: 8 (within limit of 10)

Integration with Companion Check:

• Companion matrix data sourced from ecosystem-impact-graph.json
• Uses same companion-check.cjs library invoked by creator skills at Step 0.5
• Ensures bidirectional consistency: creators check companions at creation, integrator validates companions post-creation

Step 3.5: Backward Propagation Processing (ADR-100 Phase 3.1-3.3)

When processing backward propagation signals from code-reviewer or architect:

Detection:

• Queue entries with changeType: "backward-propagation"
• Review findings containing BACKWARD_PROPAGATION section
• Pattern reports indicating systemic duplication

Validation:

1. Verify the pattern exists (check mentioned files/components)

   • Read each affected file to confirm pattern duplication
   • Count actual instances (not just claimed instances)
   • Validate pattern similarity (not just superficially similar)

2. Assess if a new artifact is warranted

   • Threshold: >= 3 instances of identical or near-identical pattern
   • Impact: Would artifact reduce duplication by 50%+ LOC?
   • Maintenance: Would centralization improve maintainability?

3. If warranted, queue for creation:

   • Write entry to integration-queue.jsonl with changeType: "backward-propagation"
   • Set proposedArtifact field with type and suggested name
   • Set priority based on impact:
     • P1 (3-5 instances, security/critical patterns)
     • P2 (6+ instances, quality/consistency patterns)
   • Include validation evidence (file paths, LOC counts, pattern excerpts)

4. Report back in integration analysis report:

## Backward Propagation Analysis

**Pattern**: <validated pattern description>
**Instances Found**: <actual count> (claimed: <original count>)
**Proposed Artifact**: <type>:<name>
**Justification**: <why centralization is beneficial>
**Priority**: P1 | P2
**Next Steps**: Queued for creator skill invocation

Example Queue Entry:

{
  "artifactId": "hook:jwt-validation",
  "changeType": "backward-propagation",
  "timestamp": "2026-02-08T10:30:00Z",
  "processed": false,
  "source": "code-reviewer",
  "pattern": "Manual JWT validation logic duplicated in 4 route handlers",
  "affectedFiles": [
    "routes/auth.ts",
    "routes/api.ts",
    "routes/admin.ts",
    "routes/user.ts"
  ],
  "validatedInstances": 4,
  "estimatedLOCReduction": 120,
  "priority": "P1",
  "proposedArtifact": {
    "type": "hook",
    "name": "jwt-validation",
    "rationale": "Centralize JWT validation for consistent security enforcement"
  }
}

Rejection Criteria:

• Pattern found in < 3 files (insufficient duplication)
• Pattern variations are too different (not truly duplicated)
• Existing artifact already handles this pattern (orphaned/underutilized)
• LOC reduction < 30 lines (insufficient benefit)

Integration with Creator Skills:

• Validated backward propagation entries trigger creator skill invocation
• Creator skills (skill-creator, hook-creator, template-creator, schema-creator) consume queue entries
• After creation, artifact-integrator processes the newly created artifact for standard integrations

Step 4: Update Graph

After creating integration tasks:

• Add edges for newly discovered relationships
• Update node integrationStatus based on current state
• Save the graph

Step 5: Mark Queue Entries Processed

For each processed entry, update the JSONL to mark processed: true

Step 6: Report

Output a summary:

## Integration Analysis Report

Processed: {count} artifacts
Tasks created: {count}
Must-have gaps: {count}
Should-have gaps: {count}

### Details
[artifact-by-artifact breakdown]

Arguments

• artifactId (optional) — Analyze a specific artifact instead of queue
• mode (optional) — 'queue' (default) | 'single' | 'health-check'

Integration Rules by Artifact Type

| Type | Must-Have | Should-Have | | -------- | --------------------------- | -------------------- | | Skill | Catalog + agent assignment | Hook, workflow ref | | Agent | Registry + routing keywords | Skills, model config | | Hook | settings.json registration | Docs entry | | Workflow | Registry + agent mapping | Docs entry | | Template | Catalog entry | Consumer ref | | Schema | Catalog entry | Consumer wiring |

Example Usage

Skill({ skill: 'artifact-integrator' });
// Processes queue, creates tasks, updates graph

Skill({ skill: 'artifact-integrator', args: 'skill:rate-limiter' });
// Analyzes specific artifact

Implementation Reference

Core Libraries:

• .claude/lib/workflow/integration-impact.cjs - Impact analysis and task generation
• .claude/lib/workflow/artifact-graph.cjs - Graph CRUD operations

Data Sources:

• .claude/context/runtime/integration-queue.jsonl - Queue of artifacts needing integration
• .claude/context/data/artifact-graph.json - Artifact relationship graph

Integration Queue Format:

{"artifactId":"skill:rate-limiter","changeType":"created","timestamp":"2026-02-07T10:30:00Z","processed":false}
{"artifactId":"agent:security-architect","changeType":"updated","timestamp":"2026-02-07T10:35:00Z","processed":false}

Workflow Integration

This skill is invoked by:

• Router Step 0.5 (automatic when queue entries exist)
• Creator skills (after artifact creation)
• Manual health checks

Auto-invoke pattern:

// Router Step 0.5 pseudocode
if (integrationQueueHasUnprocessedEntries()) {
  Task({
    task_id: 'task-1',
    subagent_type: 'developer',
    prompt: 'Invoke Skill({ skill: "artifact-integrator" })',
  });
}

Iron Laws

1. ALWAYS check the integration queue before starting any new artifact creation — Step 0.5 is mandatory; unprocessed entries compound into orphan debt that accumulates silently.
2. NEVER create more than 3 auto-spawned companion tasks per artifact — SEC-ICE-002 hard limit; exceeding it overwhelms the agent pipeline; queue remaining companions for manual review.
3. ALWAYS validate backward-propagation claims against actual code — require >= 3 confirmed duplicate instances AND >= 30 LOC reduction before queuing; never queue unverified claims.
4. ALWAYS mark queue entries as processed: true before reporting complete — unprocessed entries persist indefinitely and will be retried on every subsequent invocation.
5. NEVER report integration gaps without updating the artifact graph — the graph is the system of record for artifact relationships; gap reports without graph updates are invisible to future runs.

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | ---------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------- | | Skipping integration queue check | Unprocessed entries accumulate silently | Always read integration-queue.jsonl at Step 1 | | Creating >3 companion tasks per artifact | Task explosion overwhelms the agent pipeline | Enforce SEC-ICE-002: max 3 per artifact, 10 total | | Queuing backward-propagation without code validation | False positives create unnecessary artifacts | Verify >= 3 instances AND >= 30 LOC reduction | | Not marking queue entries processed | Entries retry indefinitely on next invocation | Set processed: true before reporting completion | | Reporting gaps without updating artifact graph | Graph becomes stale; future analysis uses wrong data | Always update graph edges after gap analysis | | Running integration on unverified artifact IDs | Invalid IDs cause silent failures | Verify artifact file exists before analysis |

Related Skills

• research-synthesis - Research phase before artifact creation
• agent-creator - Creates agents (triggers integration analysis)
• skill-creator - Creates skills (triggers integration analysis)
• hook-creator - Creates hooks (triggers integration analysis)
• workflow-creator - Creates workflows (triggers integration analysis)

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New integration pattern → .claude/context/memory/learnings.md
• Issue found → .claude/context/memory/issues.md
• Decision made → .claude/context/memory/decisions.md

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