jmagly/artifact-metadata

artifact-metadata

Manage artifact metadata, versioning, ownership, and history tracking.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "tag this artifact" → metadata tagging
• "classify [artifact]" → artifact metadata assignment

Purpose

This skill provides consistent metadata management for all SDLC and marketing artifacts. It tracks ownership, versioning, review history, and status across the artifact lifecycle.

Behavior

When triggered, this skill:

1. Locates or creates metadata:

   • Check for existing metadata.json alongside artifact
   • Create new metadata if none exists
   • Validate against metadata schema

2. Updates metadata fields:

   • Version (semantic versioning)
   • Status (draft, review, baselined, deprecated)
   • Owner (agent or user)
   • Reviewers (list of reviewing agents)
   • Timestamps (created, modified, baselined)

3. Tracks history:

   • Version history with change summaries
   • Review records with reviewer and outcome
   • Approval records

4. Validates relationships:

   • Parent/child artifact links
   • Requirement traceability links
   • Cross-references to related artifacts

Metadata Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["artifact_id", "name", "type", "version", "status", "owner"],
  "properties": {
    "artifact_id": {
      "type": "string",
      "description": "Unique identifier (e.g., SAD-001, UC-003)"
    },
    "name": {
      "type": "string",
      "description": "Human-readable artifact name"
    },
    "type": {
      "type": "string",
      "enum": ["requirements", "architecture", "test", "security", "deployment", "marketing", "report"]
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Semantic version"
    },
    "status": {
      "type": "string",
      "enum": ["draft", "review", "approved", "baselined", "deprecated"]
    },
    "owner": {
      "type": "string",
      "description": "Primary owner (agent name or user)"
    },
    "created": {
      "type": "string",
      "format": "date-time"
    },
    "modified": {
      "type": "string",
      "format": "date-time"
    },
    "baselined": {
      "type": "string",
      "format": "date-time"
    },
    "reviewers": {
      "type": "array",
      "items": {"type": "string"}
    },
    "history": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "version": {"type": "string"},
          "date": {"type": "string", "format": "date-time"},
          "author": {"type": "string"},
          "summary": {"type": "string"}
        }
      }
    },
    "reviews": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "reviewer": {"type": "string"},
          "date": {"type": "string", "format": "date-time"},
          "outcome": {"type": "string", "enum": ["approved", "conditional", "rejected"]},
          "comments": {"type": "string"}
        }
      }
    },
    "traceability": {
      "type": "object",
      "properties": {
        "requirements": {"type": "array", "items": {"type": "string"}},
        "parent": {"type": "string"},
        "children": {"type": "array", "items": {"type": "string"}}
      }
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"}
    }
  }
}

Usage Examples

Create New Metadata

User: "Create metadata for the SAD"

Skill creates:
.aiwg/architecture/sad/metadata.json
{
  "artifact_id": "SAD-001",
  "name": "Software Architecture Document",
  "type": "architecture",
  "version": "0.1.0",
  "status": "draft",
  "owner": "architecture-designer",
  "created": "2025-12-08T14:30:00Z",
  "modified": "2025-12-08T14:30:00Z",
  "reviewers": [],
  "history": [],
  "reviews": []
}

Update Version After Changes

User: "Version the SAD to 1.0.0 with summary 'Initial baseline'"

Skill updates:
- version: "1.0.0"
- status: "baselined"
- baselined: "2025-12-08T16:45:00Z"
- history: [adds entry with version, date, summary]

Record Review

User: "Record security-architect review as approved"

Skill updates:
- reviews: [adds review record]
- reviewers: [adds "security-architect" if not present]
- modified: [updates timestamp]

Query Ownership

User: "Who owns the test plan?"

Skill responds:
"Test Plan (TP-001) is owned by test-architect.
Status: review
Version: 0.3.0
Last modified: 2025-12-07
Reviewers: security-auditor, requirements-analyst"

Status Lifecycle

draft → review → approved → baselined
  ↑        ↓
  └── rejected (returns to draft)

baselined → deprecated (end of life)

Status Transitions

| From | To | Triggered By | |------|-----|-------------| | draft | review | Submit for review | | review | approved | All reviewers approve | | review | draft | Any reviewer rejects | | approved | baselined | Formal baseline action | | baselined | deprecated | Superseded or retired |

Version Conventions

• 0.x.x: Draft versions (not baselined)
• 1.0.0: First baseline
• x.y.0: Minor changes (compatible)
• x.0.0: Major changes (may break traceability)

Auto-Version Rules

| Change Type | Version Bump | |-------------|-------------| | Typo fix | patch (0.0.x) | | Section update | minor (0.x.0) | | Structure change | major (x.0.0) | | Initial baseline | 1.0.0 |

Artifact Type Conventions

| Type | ID Prefix | Location | |------|-----------|----------| | requirements | UC-, REQ-, NFR- | .aiwg/requirements/ | | architecture | SAD-, ADR-, API- | .aiwg/architecture/ | | test | TP-, TC-, TS- | .aiwg/testing/ | | security | TM-, SEC- | .aiwg/security/ | | deployment | DP-, RN- | .aiwg/deployment/ | | marketing | CB-, CA- | .aiwg/marketing/ | | report | RPT- | .aiwg/reports/ |

CLI Usage

# Create metadata for artifact
python artifact_metadata.py --create --artifact ".aiwg/architecture/sad.md" --type architecture

# Update version
python artifact_metadata.py --version "1.0.0" --artifact ".aiwg/architecture/sad.md" --summary "Initial baseline"

# Record review
python artifact_metadata.py --review --artifact ".aiwg/architecture/sad.md" \
  --reviewer "security-architect" --outcome "approved" --comments "LGTM"

# Query metadata
python artifact_metadata.py --query --artifact ".aiwg/architecture/sad.md"

# List all artifacts by status
python artifact_metadata.py --list --status "review"

# Validate all metadata
python artifact_metadata.py --validate-all

Integration

This skill integrates with:

• artifact-orchestration: Sets initial metadata when creating artifacts
• gate-evaluation: Checks artifact status for gate criteria
• traceability-check: Uses traceability links in metadata
• template-engine: Copies metadata template on instantiation

Output Locations

• Metadata file: {artifact-dir}/metadata.json
• Alternatively: {artifact-dir}/{artifact-name}.metadata.json
• Index file: .aiwg/reports/artifact-index.json

References

• Schema: schemas/artifact-metadata.schema.json
• Conventions: AIWG Artifact Naming Guide