Skip to content

Declarative Agent Command Registry

Intent

Externalize agent command contracts, task specifications, and continuous architecture skills into declarative manifests to standardize capability definition, invocation, and verification across workspaces.

Context

Applied across agent execution runtimes, planning commands, and continuous architecture skills where autonomous agents and developer tooling require consistent, schema-validated command definitions without coupling callers to bespoke command-line interfaces or implementation scripts.

Agentic Profile

Governs autonomous reasoning agents, planning workflows, and developer assistants by externalizing execution parameters, prerequisites, and expected deliverables into repository-resident declarative contracts.

Forces

Balances the necessity for flexible, repository-defined skill configurations against the requirements of deterministic command invocation and cross-workspace interoperability.

Drivers

  • Unification of agent task invocation interfaces across human developers and autonomous runtimes
  • Decoupling capability specifications from concrete execution scripts and host environments
  • Enablement of deterministic validation and discovery of agent skills at runtime

Constraints

  • Manifest schema definitions must remain platform-agnostic and repository-native
  • Command registries must not depend on centralized external services for resolution

Tradeoffs

  • Maintenance overhead of declarative manifest schemas alongside operational implementation code
  • Requirement for schema validation tooling to prevent specification divergence

Solution

Define agent capabilities, task arguments, prerequisites, and execution hooks within declarative TOML manifests residing under repository configuration paths (such as .agents/commands/). Execution engines and orchestration runners parse these manifests to construct validated command trees, ensuring identical execution semantics across CLI commands, automated pipelines, and autonomous agent loops.

Operationalisation

Maintain declarative command manifests within source-controlled directory structures, enforcing automated schema compliance during integration workflows and exposing registered commands to agent tooling.

Workflow Implications

  • Agent executors dynamically load task definitions from repository manifests rather than invoking hardcoded scripts
  • Command additions and parameter changes are reviewed through standard source control pull requests

Automation Opportunities

  • Automated linting and validation of command manifest schemas during CI execution
  • Dynamic synthesis of agent prompt tool definitions and shell auto-completion from declarative manifests

Implementation Signals

Declarative command manifests located under .agents/commands/ (such as speckit.plan.toml and speckit.analyze.toml) defining task contracts, parameters, and runtime bindings.

Evidence

Supported by ratified Reference Architecture in ArchGov and active production implementation of command manifests in repository workspaces.

Signals

  • Declarative command manifest implementation under .agents/commands/
  • Standardized execution mapping within continuous architecture runner workflows

Confidence Basis

Ratified Reference Architecture in ArchGov with verified production manifest usage in agent runtimes.

Consequences

Standardizes agent capability contracts across repositories while requiring disciplined manifest schema maintenance and version governance.

Benefits

  • Deterministic invocation and validation of capabilities for both autonomous agents and human developers
  • Elimination of divergent, brittle CLI command structures across workspaces
  • Repository-native auditing and version control of available agent capabilities

Risks

  • Runtime failures if executor environments lag behind manifest schema evolutions
  • Redundant manifest authoring overhead if task scope is narrow or ephemeral

Governance Implications

  • Declarative manifests become the authoritative contract for agent skills, requiring validation gating in continuous integration

Reuse Notes

Universally applicable across all agent-driven repositories, continuous architecture planning tasks, and CLI automation platforms requiring predictable capability abstraction.

Confidence

High confidence based on ratified Reference Architecture status and demonstrated stability across agent runtime flows.

Level: high

Rationale

Backed by ratified ArchGov Reference Architecture status, high evidence strength, and mature command manifest specifications in active use.