Skip to content

DR-006: EAC Commands System - Convention-Based Command Structure

Home › Reference › Decision Records › Dr006

Status

  • [x] Accepted
  • [ ] Proposed
  • [ ] Rejected
  • [ ] Deprecated
  • [ ] Superseded

Date: 2024-12-01

Context

Repository operations (build, test, validate, release) need consistent interface, automatic documentation, MCP server exposure for AI integration, and dual execution modes (CLI + programmatic).

Problem: How to provide unified interface for 100+ repository operations across CLI and AI workflows?

Decision

Convention-based command structure with verb-first organization, automatic documentation mapping, and MCP server exposure.

Command Categories (.r2r/eac/commands.yml):

  • build - Build modules and dependencies
  • create - Generate artifacts using AI or templates
  • get - Retrieve structured data (YAML/JSON)
  • show - Display human-readable output (tables, summaries)
  • validate - Check correctness against contracts
  • work - Git worktree and workspace management
  • release - Release management operations
  • pipeline - CI/CD orchestration

MCP Server Integration: - Commands exposed as MCP tools via go/eac/mcp/commands - Tool naming: mcp__commands__<command-name> - Stdio-based protocol - Dual execution: CLI (human-readable) vs. MCP (structured data)

Documentation Mapping (automatic): - validate-specs → docs/reference/commands/validate/specs.md - create pr → docs/reference/commands/create/pr.md - work create → docs/reference/commands/work/create.md

Consequences

Positive: Predictable UX, AI-accessible, auto-documentation, dual execution, extensible, consistent patterns

Negative: Convention discipline required, MCP server maintenance, dual output format complexity

Alternatives Considered

  1. Flat Command Namespace: Rejected - poor discoverability, no organization, name collision risk
  2. REST API: Rejected - overkill for local tools, server overhead, authentication complexity
  3. Separate CLI and API: Rejected - duplication, drift risk, maintenance burden

Tutorials | How-to Guides | Explanation | Reference

You are here: Reference — information-oriented technical descriptions of the system.