Feature Request: Support for Custom Metadata in spec.json

[louspringer]

Summary

We're using the cc-sdd/Kiro workflow to manage specs across multiple repos. We need to attach additional metadata to each spec (unique ID, owner contact, integrity hash) so we can track dependencies, support dormant "tardigrade" specs, and wire it into CI/CD checks.

Today, the tooling doesn't give us a way to persist custom fields. We've observed that extra keys in spec.json survive, but that behavior isn't documented or guaranteed. We'd like explicit support for custom metadata (or at least a guarantee that the CLI won't clobber unknown fields).

What we'd like to do

1. Add a native command to generate a spec identifier (UUID/ULID) and store it in spec.json.
2. Include optional fields like owner, hash, and other domain-specific metadata.
3. Ensure that Kiro commands round-trip arbitrary keys instead of overwriting them.

Why this matters

• Every published spec needs stable identification so downstream repos can reference it.
• We're building a "tardigrade" preservation mode that depends on metadata surviving across repos and repos.
• CI/CD pipelines can validate that only identified specs ship.
• Future enhancements (classification, dependency DAGs) rely on attached metadata.

Use Case Example

Currently, we manage 19 active specifications in our beast-mailbox-core repository:

.kiro/specs/
├── redis-mailbox/
├── filesystem-mailbox/
├── rpg2k-platform-definition/
├── prometheus-pushgateway/
└── ... (15 more specs)

We need to:

• Uniquely identify each spec across repos and over time (even if renamed/moved)
• Track ownership for multi-agent AI development workflows
• Verify integrity with cryptographic hashes to detect drift
• Cross-reference dependencies between specs (e.g., filesystem-mailbox depends on redis-mailbox patterns)
• Support "tardigrade mode" - dormant specs that can be rehydrated across repository boundaries

Current Workaround

We've manually added fields to spec.json:

{
  "feature_name": "filesystem-mailbox",
  "id": "a1b2c3d4-e5f6-...",
  "owner": "platform-core@beast",
  "hash": {
    "algorithm": "sha256",
    "value": "3b8c272d189cad858562880ff0a2ee5648561530..."
  },
  "phase": "tasks-generated",
  "created_at": "2025-11-08T20:14:36.227171+00:00",
  "updated_at": "2025-11-08T20:42:12.379963+00:00",
  ...
}

These fields appear to survive Kiro command invocations, but we can't rely on undocumented behavior for production workflows.

Questions

1. Is there an existing mechanism for attaching custom metadata to specs?
2. Could the CLI expose a hook or option to declare additional fields that should be preserved?
3. Would you accept a PR that adds:
   • An identification command (e.g. /kiro/spec-identify {feature-name} or --id flag during spec-init)
   • Explicit preservation of unknown fields when writing spec.json
   • Optional metadata schema validation
   • Tests/documentation around custom metadata lifecycle

Proposed API

Option 1: Dedicated Identification Command

# Generate unique ID and add to spec.json
/kiro/spec-identify filesystem-mailbox

# With optional metadata
/kiro/spec-identify filesystem-mailbox --owner "platform-core@beast"

Option 2: Extend Existing Commands

# Add metadata during initialization
/kiro/spec-init "Filesystem mailbox backend" --id --owner "platform-core@beast"

# Update metadata anytime
/kiro/spec-metadata filesystem-mailbox --set owner="platform-core@beast"

Option 3: Configuration-Based Preservation

# .kiro/settings/metadata-schema.yml
custom_fields:
  - id           # UUID/ULID - auto-generated if missing
  - owner        # String - contact/team identifier
  - hash         # Object - integrity verification
  - tags         # Array - classification tags
  - dependencies # Array - spec dependency references

Benefits for the Ecosystem

This capability would enable:

• Multi-repo spec management - specs referenced across related repositories
• Spec marketplaces - shareable, identifiable spec templates
• Automated governance - CI/CD validation of spec metadata
• Dependency tracking - build DAGs of spec relationships
• AI agent coordination - multiple AI agents working on identified specs with clear ownership
• Archival & restoration - "tardigrade" specs that can hibernate and rehydrate

Related Context

Our project (beast-mailbox-core) is:

• 100% AI-agent developed and maintained
• Uses cc-sdd for all feature development (19 active specs)
• Requires stable spec identification for cross-repository agent coordination
• Building infrastructure for distributed AI development workflows

We're willing to contribute the implementation if this aligns with cc-sdd's roadmap. Any guidance on the preferred direction would help us align our work with your vision.

Thank you for this excellent tool! 🙏

Visual Example: Spec Metadata Flow

graph TB
    subgraph "Repository A: beast-mailbox-core"
        SpecA1[redis-mailbox<br/>id: a1b2c3d4<br/>owner: platform-core]
        SpecA2[filesystem-mailbox<br/>id: e5f6g7h8<br/>owner: platform-core<br/>depends: a1b2c3d4]
        SpecA3[rpg2k-platform<br/>id: i9j0k1l2<br/>owner: platform-core]
    end

    subgraph "Repository B: beast-agent"
        SpecB1[agent-discovery<br/>id: m3n4o5p6<br/>owner: agent-team<br/>depends: a1b2c3d4, i9j0k1l2]
    end

    subgraph "Tardigrade Archive"
        Archive[(Dormant Specs<br/>with metadata)]
    end

    subgraph "CI/CD Pipeline"
        Validate[Validate Metadata]
        CheckHash[Verify Integrity]
        CheckDeps[Check Dependencies]
    end

    SpecA1 -.->|references| SpecB1
    SpecA3 -.->|references| SpecB1
    SpecA2 -.->|depends on| SpecA1

    SpecA1 --> Archive
    SpecA2 --> Archive

    SpecA1 --> Validate
    SpecB1 --> Validate
    Validate --> CheckHash
    CheckHash --> CheckDeps

    style Archive fill:#f9f,stroke:#333,stroke-width:2px
    style Validate fill:#bbf,stroke:#333,stroke-width:2px

Loading

Current spec.json (Limited)

{
  "feature_name": "filesystem-mailbox",
  "phase": "tasks-generated",
  "language": "en",
  "approvals": { ... }
}

Proposed spec.json (With Metadata)

{
  "feature_name": "filesystem-mailbox",
  "id": "e5f6g7h8-i9j0-k1l2-m3n4-o5p6q7r8s9t0",
  "owner": "platform-core@beast",
  "hash": {
    "algorithm": "sha256",
    "value": "3b8c272d189cad85856..."
  },
  "dependencies": ["a1b2c3d4-..."],
  "tags": ["transport", "async", "filesystem"],
  "phase": "tasks-generated",
  "language": "en",
  "approvals": { ... }
}