Optional declarative layer for agents

[hernancapucci]

This is a very compelling approach to multi-agent orchestration.

Each agent clearly defines its role, workflow, and style — which makes the system highly usable.

One thought: what if each agent also had a minimal declarative layer?

Not for execution, but for clarity.

Something that makes explicit:
– purpose
– capabilities
– limits
– stopping conditions

For example:

{
  "agent_name": "Evidence Collector",
  "purpose": "Validate claims based on verifiable evidence",
  "capabilities": ["request evidence", "analyze inputs"],
  "limits": ["no claims without evidence"],
  "stopping_conditions": ["insufficient data"]
}

It wouldn’t change how agents run.
It would just make their boundaries explicit.

Curious if something like this could fit into the project.

[kienbui1995]

Interesting idea. A few thoughts on practical implementation:

A separate metadata.json per agent would create a maintenance burden — 162 files that need to stay in sync with the .md content.

A more practical approach: a scripts/catalog.sh that auto-generates a single catalog.json from existing agent frontmatter and content structure. No manual maintenance, always in sync:

[
  {
    "name": "Code Reviewer",
    "description": "Constructive code review, security, maintainability",
    "division": "engineering",
    "file": "engineering/engineering-code-reviewer.md",
    "sections": ["Identity", "Core Mission", "Critical Rules", "Deliverables"]
  }
]

That said, the standalone value of a catalog file is limited — users don't interact with JSON directly. The real value comes when it enables tooling like a search CLI (./scripts/search.sh "database") that lets users find the right agent from 162+ options.

See Discussion #225 for that proposal. Would make sense to combine both if there's interest.

[hernancapucci]

That makes sense — avoiding manual sync across 162 files is definitely the right constraint.

I wasn’t tied to a separate file per agent, more to making certain aspects explicit in a structured way without adding maintenance overhead.

Auto-generating a catalog from frontmatter/content seems like a solid approach.

If that layer could expose fields like purpose, capabilities, limits, or stopping conditions, it might add clarity without changing how agents are authored.

Since it’s all derived, it would stay fully in sync.

I’ll check out #225 — combining this with search/discoverability sounds like a strong direction.