Techcle Wiki

SCHEMA

6 min read

Project Metadata Schema

This document defines the metadata.json schema used for all projects in .ai/projects/.

Schema Version 1.0

Complete Schema

{
  "name": "string (required)",
  "displayName": "string (optional)",
  "created": "ISO 8601 datetime (required)",
  "updated": "ISO 8601 datetime (required)",
  "format": "kiro | codev (required)",
  "artifacts": ["array of strings (required)"],
  "status": "new | in_progress | complete | archived (required)",
  "codevNumber": "string (optional, required if format=codev)",
  "tags": ["array of strings (optional)"],
  "category": "string (optional)",
  "description": "string (optional)"
}

Field Descriptions

name (required)

  • Type: string
  • Description: Unique project identifier in kebab-case
  • Example: "simple-xml-response", "n8n-platform"
  • Rules:
    • Must be unique across all projects
    • Use kebab-case (lowercase with hyphens)
    • No spaces or special characters except hyphens

displayName (optional)

  • Type: string
  • Description: Human-readable project name
  • Example: "Simple XML Response Adapter", "N8N Platform Integration"

created (required)

  • Type: ISO 8601 datetime string
  • Description: When the project was created
  • Example: "2026-01-26T10:30:00Z"
  • Format: UTC timezone recommended

updated (required)

  • Type: ISO 8601 datetime string
  • Description: When the project was last modified
  • Example: "2026-01-26T15:45:00Z"
  • Format: UTC timezone recommended
  • Rules: Should be updated whenever any artifact changes

format (required)

  • Type: enum string
  • Values: "kiro", "codev", "bmad", or "hybrid"
  • Description: Which tool format the project uses
  • Rules:
    • A project uses exactly one format (or hybrid for mixed artifacts)
    • Determines which artifacts are present
    • Determines integration method (symlink, pointer, or direct access)

artifacts (required)

  • Type: array of strings
  • Description: List of artifact files present in the project
  • Example (Kiro): ["requirements.md", "design.md", "tasks.md"]
  • Example (Codev): ["spec.md", "plan.md", "review.md"]
  • Example (BMAD): ["brief.md", "prd.md", "architecture.md", "epics-stories.md", "stories/story-001.md"]
  • Example (Hybrid): ["requirements.md", "design.md", "architecture.md", "stories/story-001.md"]
  • Rules:
    • Must match actual files in project directory
    • Updated automatically by sync scripts
    • For hybrid projects, include artifacts from all tools used

status (required)

  • Type: enum string
  • Values: "new", "in_progress", "complete", "archived"
  • Description: Current project status
  • Definitions:
    • new: Project created but not started
    • in_progress: Actively being worked on
    • complete: All artifacts complete
    • archived: No longer active

codevNumber (conditional)

  • Type: string (4-digit zero-padded)
  • Description: Codev sequential number
  • Example: "0001", "0042"
  • Rules:
    • Required if format="codev"
    • Not used if format="kiro"
    • Must be unique across all Codev projects
    • Used in pointer file names

tags (optional)

  • Type: array of strings
  • Description: Categorization tags
  • Example: ["gateway", "adapter", "xml"]
  • Rules:
    • Use lowercase
    • Use hyphens for multi-word tags
    • Keep tags concise

category (optional)

  • Type: string
  • Description: Project category mapping to distinct systems/domains
  • Values: "infrastructure", "domain-apis", "eda", "market-making", "ai-dev"
  • Examples:
    • "infrastructure" - Platform foundation (secrets, ingress, networking, build tools, n8n, clickhouse)
    • "domain-apis" - Domain API system projects
    • "eda" - Event-driven architecture system
    • "market-making" - Market making system
    • "ai-dev" - AI development system
  • Rules:
    • Use one of the standard category values
    • A project belongs to one category but may span multiple repositories
    • Categories represent distinct systems in your platform

description (optional)

  • Type: string
  • Description: Brief project description
  • Example: "Adapter to transform XML backend responses to JSON"
  • Rules:
    • Keep concise (1-2 sentences)
    • Describe the project’s purpose

bmadPhase (conditional)

  • Type: enum string
  • Values: "1-analysis", "2-planning", "3-solutioning", "4-implementation", "complete"
  • Description: Current phase in BMAD workflow
  • Example: "3-solutioning"
  • Rules:
    • Required if format="bmad" or format="hybrid" with BMAD artifacts
    • Not used if format="kiro" or format="codev" only
    • Updated as project progresses through BMAD phases
    • Helps agents understand where to pick up work

tools (conditional)

  • Type: array of strings
  • Values: Any combination of ["kiro", "codev", "bmad"]
  • Description: List of tools that have been used on this project
  • Example: ["kiro", "bmad"]
  • Rules:
    • Required if format="hybrid"
    • Not used for single-format projects
    • Tracks project evolution across tools
    • Helps with migration and handoff scenarios

Format-Specific Examples

Kiro Project Example

{
  "name": "n8n-platform",
  "displayName": "N8N Platform Integration",
  "created": "2026-01-26T10:00:00Z",
  "updated": "2026-01-26T16:30:00Z",
  "format": "kiro",
  "artifacts": ["requirements.md", "design.md", "tasks.md"],
  "status": "in_progress",
  "tags": ["platform", "automation", "n8n"],
  "category": "infrastructure",
  "description": "Integration of N8N workflow automation platform"
}

Codev Project Example

{
  "name": "simple-xml-response",
  "displayName": "Simple XML Response Adapter",
  "created": "2026-01-26T10:30:00Z",
  "updated": "2026-01-26T15:45:00Z",
  "format": "codev",
  "artifacts": ["spec.md", "plan.md", "review.md"],
  "status": "complete",
  "codevNumber": "0001",
  "tags": ["gateway", "adapter", "xml"],
  "category": "domain-apis",
  "description": "Adapter to transform XML backend responses to JSON"
}

BMAD Project Example

{
  "name": "clickhouse-operator",
  "displayName": "ClickHouse Kubernetes Operator",
  "created": "2026-01-30T14:00:00Z",
  "updated": "2026-01-30T16:45:00Z",
  "format": "bmad",
  "artifacts": [
    "brief.md",
    "prd.md",
    "architecture.md",
    "epics-stories.md",
    "stories/story-e1-s1.md",
    "stories/story-e1-s2.md",
    "sprint-status.yaml"
  ],
  "status": "in_progress",
  "bmadPhase": "4-implementation",
  "tags": ["operator", "kubernetes", "clickhouse"],
  "category": "infrastructure",
  "description": "Kubernetes operator for managing ClickHouse clusters"
}

Hybrid Project Example

{
  "name": "api-gateway-refactor",
  "displayName": "API Gateway Refactor",
  "created": "2026-01-26T10:00:00Z",
  "updated": "2026-01-30T17:00:00Z",
  "format": "hybrid",
  "artifacts": [
    "requirements.md",
    "design.md",
    "architecture.md",
    "epics-stories.md",
    "stories/story-e1-s1.md",
    "stories/story-e2-s1.md"
  ],
  "status": "in_progress",
  "bmadPhase": "4-implementation",
  "tools": ["kiro", "bmad"],
  "tags": ["gateway", "refactor", "architecture"],
  "category": "domain-apis",
  "description": "Refactor API gateway with new architecture, started with Kiro, continued with BMAD for implementation"
}

Validation Rules

Required Fields

All projects must have:

  • name
  • created
  • updated
  • format
  • artifacts
  • status

Conditional Requirements

  • If format="codev", then codevNumber is required
  • If format="kiro", then codevNumber should not be present
  • If format="bmad" or format="hybrid" with BMAD artifacts, then bmadPhase is required
  • If format="hybrid", then tools array is required

Artifact Validation

  • Kiro projects should have: requirements.md, design.md, tasks.md
  • Codev projects should have: spec.md, plan.md, review.md
  • BMAD projects may have (based on phase):
    • Phase 1: brief.md, research/*.md
    • Phase 2: prd.md, ux-design.md
    • Phase 3: architecture.md, epics-stories.md
    • Phase 4: stories/*.md, sprint-status.yaml
  • Hybrid projects can mix artifacts from multiple tools
  • Artifacts array must match actual files in project directory

Uniqueness Constraints

  • name must be unique across all projects
  • codevNumber must be unique across all Codev projects

Schema Evolution

Version History

  • 1.0 (2026-01-26): Initial schema with Kiro and Codev support
  • 1.1 (2026-01-30): Added BMAD and hybrid format support
    • Added bmadPhase field for BMAD workflow tracking
    • Added tools array for hybrid projects
    • Updated format to include “bmad” and “hybrid”
    • Added BMAD artifact patterns

Future Considerations

  • Add version field to track schema version
  • Add dependencies array for project relationships
  • Add contributors array for multi-person projects
  • Add estimatedHours for project sizing
  • Add llmModel to track which model was used for generation

Maintenance

Automatic Updates

The sync-metadata.sh script automatically:

  • Updates updated timestamp when artifacts change
  • Updates artifacts array to match actual files
  • Validates schema compliance

Manual Updates

Developers should manually update:

  • status when project phase changes
  • tags when categorization changes
  • description when project scope changes
  • displayName for better readability

Tools Integration

Kiro

  • Reads metadata to understand project format
  • Updates updated timestamp on artifact changes
  • Does not modify other metadata fields

Codev

  • Reads metadata to get codevNumber for pointer files
  • Updates updated timestamp on artifact changes
  • Updates artifacts array when files are added/removed

Helper Scripts

  • create-project.sh: Creates initial metadata
  • list-projects.sh: Reads metadata for display
  • migrate-project.sh: Updates format and artifacts
  • sync-metadata.sh: Validates and updates metadata

Graph View