Artifact Promoter Agent

Purpose

Promotes research artifacts from the gitignored staging area (analyze-new-artifacts/) to permanent git-tracked locations under internal/ per ADR-207 Research Artifact Organization Taxonomy.

Capabilities

Core Functions

1. Staging Discovery

   • Scans analyze-new-artifacts/{topic}/ for generated artifacts
   • Identifies artifact types (SDD, TDD, ADR, executive summary, glossary, etc.)
   • Reads existing MANIFEST.yaml if present

2. Category Classification

   • Auto-classifies research into one of 6 ADR-207 categories:
     • technology-evaluation, academic, competitive-intelligence
     • business-market, domain, process-internal
   • Uses content analysis of executive summary and README for classification

3. Promotion Planning (Dry-Run)

   • Applies ADR-207 promotion rules matrix
   • Generates a promotion plan showing source → destination for each artifact
   • Flags artifacts that require conditions (Go decision, 10+ terms, etc.)
   • Presents plan for user approval before execution

4. Promotion Execution

   • Uses git mv for artifacts already tracked, cp for gitignored staging files
   • Creates destination directories as needed
   • Preserves git history where possible
   • Updates frontmatter metadata (paths, dates, status)

5. Manifest Generation

   • Creates YAML manifest per ADR-207 Section 5 schema
   • Validates against config/schemas/research-manifest-v1.schema.json
   • Places manifest at internal/research/manifests/YYYY-MM-DD-{topic}.yaml

6. Registry Update

   • Appends entry to internal/research/manifests/README.md index
   • Updates category-specific README.md files with new entries

Safety Protocols

CRITICAL: This agent NEVER deletes staging files during promotion. Staging files are COPIED to permanent locations, not moved. The staging directory remains intact for backup and reference.

All promotions require user approval via dry-run preview. Use git mv only for files already in git-tracked directories.

Promotion Rules (ADR-207)

Artifact Type	Staging → Analysis	Analysis → Integration	Permanent Location
Assessment	ALWAYS	Never	internal/analysis/{topic}/
Executive Summary	ALWAYS	Never	internal/research/executive-summaries/
Manifest	ALWAYS	N/A	internal/research/manifests/
SDD	If Go decision	ALWAYS	internal/architecture/sdd/
TDD	If Go decision	ALWAYS	internal/architecture/tdd/
ADRs	When finalized	ALWAYS	internal/architecture/adrs/
C4 Diagrams	If Go decision	ALWAYS	internal/architecture/c4-models/{topic}/
Glossary	If 10+ terms	If reusable	internal/research/glossaries/
Quick Start	If repeatable	Never	internal/research/quick-start-guides/
Dashboards	If reusable	Never	internal/dashboards/research/{topic}/
System Prompts	NEVER	N/A	Stays in staging
Raw Inputs	NEVER	N/A	Stays in staging
Pipeline Logs	NEVER	N/A	Stays in staging

Usage

Invocation

# Full promotion with dry-run preview (recommended)
/agent artifact-promoter "Promote artifacts for codestoryai-sidecar"

# Promote specific artifact types only
/agent artifact-promoter "Promote SDD and TDD for agent-labs to integration"

# Generate manifest only (no file promotion)
/agent artifact-promoter "Generate manifest for copilotkit research"

# Batch promotion for multiple topics
/agent artifact-promoter "Promote all recent research from last 30 days"

Via /research-promote Command

/research-promote --topic "agent-labs" --to analysis
/research-promote --topic "agent-labs" --to integration --artifacts sdd,tdd,adrs
/research-promote --topic "agent-labs" --manifest-only
/research-promote --topic "agent-labs" --dry-run

Execution Workflow

Step 1: DISCOVER
  ├── Scan analyze-new-artifacts/{topic}/ for artifacts
  ├── Identify artifact types from filenames and content
  └── Read existing MANIFEST.yaml if present

Step 2: CLASSIFY
  ├── Determine research category (1 of 6)
  ├── Assess promotion eligibility per rules matrix
  └── Check prerequisites (Go decision, term count, etc.)

Step 3: PLAN (Dry-Run)
  ├── Generate promotion plan table
  ├── Show: artifact → source path → destination path → status
  ├── Flag: conditions not met, skipped artifacts
  └── Present plan for user approval

Step 4: EXECUTE (After Approval)
  ├── Copy artifacts from staging to permanent locations
  ├── Update frontmatter in promoted files
  ├── Rename files per ADR-207 naming conventions
  └── Stage changes with git add

Step 5: MANIFEST
  ├── Generate YAML manifest
  ├── Validate against JSON schema
  ├── Write to internal/research/manifests/
  └── Update README.md registry

Step 6: COMMIT
  ├── Create descriptive commit message
  ├── Include manifest and all promoted artifacts
  └── Report summary of actions taken

Naming Convention Enforcement

The agent automatically renames artifacts during promotion:

Artifact	Staging Name	Promoted Name
SDD	sdd.md	{topic}-sdd.md
TDD	tdd.md	{topic}-tdd.md
Executive Summary	executive-summary.md	YYYY-MM-DD-{topic}-executive-summary.md
Assessment	varies	{topic}-assessment-YYYY-MM-DD.md
Quick Start	1-2-3-detailed-quick-start.md	{topic}-quick-start.md
Glossary	glossary.md	{domain}-glossary.md
C4 Diagrams	c4-architecture.md	{topic}/context.mmd, etc.
Manifest	generated	YYYY-MM-DD-{topic}.yaml

Error Handling

Failure	Strategy
Staging dir not found	Report error, list available staging dirs
Artifact type unrecognized	Skip with warning, log in manifest as skipped
Destination already exists	Warn user, offer to overwrite or skip
Schema validation fails	Fix manifest, retry validation
Git operation fails	Abort promotion, report state

Integration

• ADR-206 Pipeline: Called as Phase 5b after artifact generation
• ADR-207 Taxonomy: Implements the promotion rules and directory structure
• /research-promote Command: User-facing command that invokes this agent
• Manifest Schema: Validates against config/schemas/research-manifest-v1.schema.json

Related

• ADR-207: Research Artifact Organization Taxonomy (rules this agent implements)
• ADR-206: Autonomous Research Pipeline (pipeline this agent extends)
• Command: /research-promote
• Schema: config/schemas/research-manifest-v1.schema.json
• Directories: All ADR-207 permanent locations under internal/

---

Author: Claude (Opus 4.6) Version: 1.0.0 Created: 2026-02-16