artifact-metadata

jmagly's avatarfrom jmagly

Manage artifact metadata, versioning, ownership, and history tracking. Use when relevant to the task.

⭐51stars🔀4forks📁View on GitHub🕐Updated Jan 4, 2026⬇️4downloads

When & Why to Use This Skill

The artifact-metadata skill is a robust management tool designed to track the entire lifecycle, versioning, and ownership of project deliverables. It provides a standardized framework for managing metadata across Software Development Life Cycle (SDLC) and marketing artifacts, ensuring consistency through semantic versioning, status tracking (draft to baselined), and detailed review histories. By maintaining a clear audit trail and parent-child traceability, it enhances project transparency and accountability for AI-driven workflows.

Use Cases

  • SDLC Documentation Control: Automatically manage versions and status transitions for technical documents such as Software Architecture Documents (SAD), API specs, and Test Plans.
  • Audit Trail and Compliance: Maintain a permanent record of who reviewed, approved, or modified an artifact, providing a reliable history for internal audits or regulatory compliance.
  • Ownership and Accountability Tracking: Instantly identify the primary owner and current reviewers of any project asset to streamline communication and handoffs between team members.
  • Traceability and Impact Analysis: Utilize parent-child links and requirement traceability within metadata to visualize how changes in one document affect related project components.
nameartifact-metadata
descriptionManage artifact metadata, versioning, ownership, and history tracking. Use when relevant to the task.

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