- 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