artifact-metadata

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

Triggers

• "update artifact metadata"
• "track artifact version"
• "artifact history"
• "who owns [artifact]"
• "artifact status"
• "version [artifact]"

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