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

• Load the artifact graph: require('.claude/lib/workflow/artifact-graph.cjs')

• Load impact analyzer: require('.claude/lib/workflow/integration-impact.cjs')

• Call analyzeImpact({ artifactId, changeType, graphPath })

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

• Use companion-check.cjs from .claude/lib/creators/companion-check.cjs

• Call checkCompanions(artifactType, artifactName) to get companion matrix

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

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)

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?

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)

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

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

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

• ALWAYS validate backward-propagation claims against actual code — require >= 3 confirmed duplicate instances AND >= 30 LOC reduction before queuing; never queue unverified claims.

• ALWAYS mark queue entries as processed: true before reporting complete — unprocessed entries persist indefinitely and will be retried on every subsequent invocation.

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