Artifact Integrator

---
name: artifact-integrator
description: Deep integration analysis for newly created artifacts
version: 1.1.0
category: workflow
agents:
  - architect
  - planner
  - developer
tools:
  - Read
  - Write
  - Edit
  - TaskCreate
  - TaskList
  - TaskUpdate
  - Bash
verified: true
lastVerifiedAt: 2026-02-22T00:00:00.000Z
source: builtin
trust_score: 100
provenance_sha: 6286c3c564ac5576
---

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

```markdown
### 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:**

```markdown
## 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:**

```jsonl
{
  "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

```javascript
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:**

```jsonl
{"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:**

```javascript
// 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.