Initial commit

skills/artifact.scaffold/README.md

@@ -0,0 +1,166 @@
+# artifact.scaffold
+
+Generate new artifact templates automatically from metadata inputs.
+
+## Overview
+
+The `artifact.scaffold` skill creates fully compliant artifact descriptors in one call. It generates valid `.artifact.yaml` files, assigns auto-incremented versions starting at 0.1.0, and registers artifacts in the artifacts registry.
+
+## Features
+
+- **Automatic Generation**: Creates artifact YAML files from metadata inputs
+- **Schema Definition**: Supports field definitions with types, descriptions, and required flags
+- **Inheritance**: Supports extending from base artifacts
+- **Registry Management**: Automatically registers artifacts in `registry/artifacts.json`
+- **Validation**: Optional `--validate` flag to validate generated artifacts
+- **Version Management**: Auto-assigns version 0.1.0 to new artifacts
+
+## Usage
+
+### Basic Example
+
+```bash
+python3 skills/artifact.scaffold/artifact_scaffold.py \
+  --id "new.artifact" \
+  --category "report"
+```
+
+### With Field Definitions
+
+```bash
+python3 skills/artifact.scaffold/artifact_scaffold.py \
+  --id "new.artifact" \
+  --category "report" \
+  --fields '[{"name":"summary","type":"string","description":"Summary field","required":true}]'
+```
+
+### With Inheritance and Validation
+
+```bash
+python3 skills/artifact.scaffold/artifact_scaffold.py \
+  --id "new.artifact" \
+  --category "report" \
+  --extends "base.artifact" \
+  --fields '[{"name":"summary","type":"string"}]' \
+  --validate
+```
+
+### Custom Output Path
+
+```bash
+python3 skills/artifact.scaffold/artifact_scaffold.py \
+  --id "new.artifact" \
+  --category "report" \
+  --output "custom/path/artifact.yaml"
+```
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `--id` | string | Yes | Unique identifier for the artifact (e.g., "new.artifact") |
+| `--category` | string | Yes | Category/type of artifact (e.g., "report", "specification") |
+| `--extends` | string | No | Base artifact to extend from |
+| `--fields` | JSON array | No | Field definitions with name, type, description, and required properties |
+| `--output` | string | No | Custom output path for the artifact file |
+| `--validate` | flag | No | Validate the artifact after generation |
+
+## Field Definition Format
+
+Fields are provided as a JSON array with the following structure:
+
+```json
+[
+  {
+    "name": "field_name",
+    "type": "string|number|boolean|object|array",
+    "description": "Field description",
+    "required": true|false
+  }
+]
+```
+
+## Output
+
+The skill outputs a JSON response with the following structure:
+
+```json
+{
+  "ok": true,
+  "status": "success",
+  "artifact_id": "new.artifact",
+  "file_path": "/path/to/artifact.yaml",
+  "version": "0.1.0",
+  "category": "report",
+  "registry_path": "/path/to/registry/artifacts.json",
+  "artifacts_registered": 1,
+  "validation": {
+    "valid": true,
+    "errors": [],
+    "warnings": []
+  }
+}
+```
+
+## Generated Artifact Structure
+
+The skill generates artifact YAML files with the following structure:
+
+```yaml
+id: new.artifact
+version: 0.1.0
+category: report
+created_at: '2025-10-26T00:00:00.000000Z'
+metadata:
+  description: new.artifact artifact
+  tags:
+  - report
+extends: base.artifact  # Optional
+schema:
+  type: object
+  properties:
+    summary:
+      type: string
+      description: Summary field
+  required:
+  - summary
+```
+
+## Registry Management
+
+Artifacts are automatically registered in `registry/artifacts.json`:
+
+```json
+{
+  "registry_version": "1.0.0",
+  "generated_at": "2025-10-26T00:00:00.000000Z",
+  "artifacts": [
+    {
+      "id": "new.artifact",
+      "version": "0.1.0",
+      "category": "report",
+      "created_at": "2025-10-26T00:00:00.000000Z",
+      "description": "new.artifact artifact",
+      "tags": ["report"],
+      "extends": "base.artifact",
+      "schema": { ... }
+    }
+  ]
+}
+```
+
+## Dependencies
+
+- `artifact.define`: For artifact type definitions and validation
+
+## Status
+
+**Active** - Ready for production use
+
+## Tags
+
+- artifacts
+- scaffolding
+- generation
+- templates
+- metadata