Evolith Tracker — SMART CLI Gap Analysis & Capability Proposal

Bilingual Navigation: English (this document) · Versión en Español

Document Status: Superseded on contract matters — ratified upstream

Contract ratification (2026-06-10): the output envelope, global flags, error codes, naming, and the command-as-a-service execution model proposed here were ratified upstream by Evolith Core ADR 0073 (Board-approved). On conflict, the ADR prevails. Open implementation work is tracked in the Core Gap Tracking Board (GT-02, GT-03, GT-06).
Type: CLI Design & Gap Analysis
Satellite: Evolith Tracker
Upstream: Evolith Core
Date: 2026-06-07
Author: Architect Agent (BMAD) Note: CLI gaps have been consolidated into docs/audit/tracker-gaps-opportunities-tracking.md

1. Analysis Methodology

1.1 Known Unknowns

The current evolith CLI commands have not been analyzed (listed as a gap in the target architecture). This analysis is based on:

UX Concept CLI interaction design
PRD Use Case UC-007 (CLI as first-class interface)
Expected command coverage for all 5 Phase Gates

1.2 Required CLI Capabilities

The Tracker CLI must support all human and BMAD agent interactions defined in the UX Concept.

2. Command Coverage Matrix

2.1 Discovery Commands

User Journey	Required Command	Description	Status
Create initiative	`evolith initiative create --name --description`	Submit new initiative	Missing
Submit canvas	`evolith discovery submit --initiative=X --file=Y`	Submit Discovery Canvas	Missing
Approve initiative	`evolith initiative approve --id=X --InitiativeId=Y`	Approve at Gate 1	Missing
Generate backlog	`evolith initiative backlog generate --id=X`	Generate backlog	Missing
List initiatives	`evolith initiative list [--status=X]`	Pipeline view	Missing

2.2 Design Commands

User Journey	Required Command	Description	Status
Get constraints	`evolith design get-constraints --initiative=X`	Pull upstream ADRs	Missing
Submit contract	`evolith design submit-contract --initiative=X --spec=Y`	Submit OpenAPI contract	Missing
Submit ADR	`evolith design submit-adr --initiative=X --file=Y`	Submit ADR	Missing
Approve blueprint	`evolith blueprint approve --id=X`	Approve at Gate 2	Missing

2.3 Construction Commands

User Journey	Required Command	Description	Status
Start cycle	`evolith cycle start --blueprint=X --name=Y`	Start implementation cycle	Missing
List stories	`evolith story list --cycle=X`	List technical stories	Missing
Complete story	`evolith story complete --id=X [--hours=Y]`	Mark story done	Missing
Submit peer review	`evolith review submit --story=X --pr-url=Y`	Submit PR for review	Missing
Get drift index	`evolith drift get --initiative=X`	Architecture drift status	Missing

2.4 QA Commands

User Journey	Required Command	Description	Status
Start test cycle	`evolith qa cycle start --cycle=X`	Start QA cycle	Missing
Log test result	`evolith qa execution log --cycle=X --story=Y --result=Z`	Log execution	Missing
Raise defect	`evolith defect create --story=X --severity=Y --description=Z`	Log defect	Missing
Get gate status	`evolith gate status --phase=qa --initiative=X`	QA gate verdict	Missing

2.5 Release Commands

User Journey	Required Command	Description	Status
Plan release	`evolith release plan --stories=X --version=Y`	Create release package	Missing
Authorize release	`evolith release authorize --id=X`	Gate 5 approval	Missing
Trigger deployment	`evolith release deploy --id=X --env=Y`	Deploy to environment	Missing
Get deployment status	`evolith deployment status --id=X`	Deployment record	Missing

2.6 Agent Commands

User Journey	Required Command	Description	Status
Agent status	`evolith agent status [--role=X] [--format=json]`	Current assignments	Missing
Agent assign	`evolith agent assign --initiative=X --role=Y --agentId=Z`	Assign BMAD agent	Missing
Agent task	`evolith agent task --action=X --target=Y`	Trigger agent action	Missing

2.7 Governance Commands

User Journey	Required Command	Description	Status
Get scorecard	`evolith scorecard get --initiative=X [--format=json]`	DORA/SPACE metrics	Missing
Get gate blockers	`evolith gate blockers --initiative=X --phase=Y`	Blocking criteria	Missing
Request exception	`evolith gate exception request --initiative=X --phase=Y --criterion=Z --justification=W	Request gate exception	Missing
List exceptions	`evolith exception list [--status=X]`	Exception requests	Missing

3. Command Structure Standard

3.1 Naming Convention

All commands follow: evolith <verb> <noun> [options]

evolith initiative create --name="..." --description="..."
evolith design submit-contract --initiative=... --spec=...
evolith gate status --phase=discovery --initiative=...

3.2 Global Options (Required for Agentic Use)

Option	Description	Required for
`--format=json`	Machine-readable output	agents, scripting
`--dry-run`	Preview without execution	All write operations
`--initiative=<id>`	Initiative context	Phase-specific commands
`--tenant=<id>`	Tenant context	All commands
`--verbose`	Detailed output	Debugging
`--output=<path>`	Write output to file	Large data export

3.3 Output Standard

{
  "success": true,
  "data": { ... },
  "meta": {
    "command": "evolith initiative create",
    "executedAt": "2026-06-07T10:30:00Z",
    "durationMs": 234,
    "correlationId": "..."
  }
}

{
  "success": false,
  "error": {
    "code": "GATE_BLOCKED",
    "message": "Gate 1 not passed — 2 mandatory criteria unsatisfied",
    "details": { ... }
  },
  "meta": { ... }
}

4. Gaps Summary

4.1 Critical Gaps (Blocking Tracker Use)

Gap	Impact	Recommendation
No structured output (`--format=json`)	agents cannot parse output	Implement JSON output mode
No initiative context (`--initiative`)	Phase commands require context	Add global initiative flag
No dry-run mode	Agents cannot preview effects	Implement `--dry-run` on all write ops
No gate evaluation commands	Cannot evaluate Phase Gates via CLI	Add `evolith gate evaluate` command
No agent assignment commands	Cannot manage agents	Add `evolith agent assign` command

4.2 Standard Gaps (Improve UX)

Gap	Impact	Recommendation
No `--output` flag	Cannot redirect large outputs	Add `--output` for file redirection
No `--verbose` flag	Debugging difficult	Add verbose logging mode
No `evolith init`	First-time setup manual	Add initialization wizard
No `evolith config`	Cannot manage settings	Add configuration management

5. Proposed CLI Architecture

5.1 Package Structure

packages/
└── evolith/
    ├── src/
    │   ├── commands/
    │   │   ├── initiative/
    │   │   ├── discovery/
    │   │   ├── design/
    │   │   ├── construction/
    │   │   ├── qa/
    │   │   ├── release/
    │   │   ├── agent/
    │   │   ├── gate/
    │   │   ├── scorecard/
    │   │   └── exception/
    │   ├── lib/
    │   │   ├── api-client.ts
    │   │   ├── formatter.ts
    │   │   └── config.ts
    │   └── index.ts
    ├── package.json
    └── README.md

5.2 API Client Library

// packages/evolith/src/lib/api-client.ts
import { Client } from '@hey-api/client';

export class EvolithApiClient {
  constructor(private readonly baseUrl: string, private readonly token: string) {}

  private client = new Client({
    baseUrl: this.baseUrl,
  }).withAuth(({ token }) => ({
    headers: { Authorization: `Bearer ${token}` },
  }));

  readonly initiative = {
    create: (data: CreateInitiativeInput) =>
      this.client.post('/initiatives', data),
    list: (params?: ListInitiativesParams) =>
      this.client.get('/initiatives', { params }),
    get: (id: string) =>
      this.client.get(`/initiatives/${id}`),
    approve: (id: string) =>
      this.client.post(`/initiatives/${id}/approve`),
  };

  readonly gate = {
    status: (initiativeId: string, phase: string) =>
      this.client.get(`/initiatives/${initiativeId}/gate/${phase}`),
    evaluate: (initiativeId: string, phase: string) =>
      this.client.post(`/initiatives/${initiativeId}/gate/${phase}/evaluate`),
    blockers: (initiativeId: string, phase: string) =>
      this.client.get(`/initiatives/${initiativeId}/gate/${phase}/blockers`),
  };
}

6. Recommendations

6.1 Immediate Actions

Adopt structured output standard — Implement --format=json across all commands first (enables BMAD agent integration)
Add --initiative global flag — Single context flag for all phase-specific commands
Implement --dry-run — Preview mode for all state-changing operations

6.2 Proposed ADR (CLI Standard)

An ADR should be proposed to Evolith Core establishing:

CLI command naming convention (evolith <verb> <noun>)
Mandatory output formats (JSON, table)
Global flags standard (--format, --dry-run, --initiative, --tenant)
Machine-readable error format

References

Tracker Target Architecture — Primary TAD
UX Concept CLI Design — CLI interaction philosophy
PRD UC-007: CLI as First-Class Interface — CLI use cases
Core Feedback Analysis — CLI gap ADR proposal

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Evolith Tracker — SMART CLI Gap Analysis & Capability Proposal

1. Analysis Methodology

1.1 Known Unknowns

1.2 Required CLI Capabilities

2. Command Coverage Matrix

2.1 Discovery Commands

2.2 Design Commands

2.3 Construction Commands

2.4 QA Commands

2.5 Release Commands

2.6 Agent Commands

2.7 Governance Commands

3. Command Structure Standard

3.1 Naming Convention

3.2 Global Options (Required for Agentic Use)

3.3 Output Standard

4. Gaps Summary

4.1 Critical Gaps (Blocking Tracker Use)

4.2 Standard Gaps (Improve UX)

5. Proposed CLI Architecture

5.1 Package Structure

5.2 API Client Library

6. Recommendations

6.1 Immediate Actions

6.2 Proposed ADR (CLI Standard)

References

FilesExpand file tree

tracker-smart-cli-gap-analysis.md

Latest commit

History

tracker-smart-cli-gap-analysis.md

File metadata and controls

Evolith Tracker — SMART CLI Gap Analysis & Capability Proposal

1. Analysis Methodology

1.1 Known Unknowns

1.2 Required CLI Capabilities

2. Command Coverage Matrix

2.1 Discovery Commands

2.2 Design Commands

2.3 Construction Commands

2.4 QA Commands

2.5 Release Commands

2.6 Agent Commands

2.7 Governance Commands

3. Command Structure Standard

3.1 Naming Convention

3.2 Global Options (Required for Agentic Use)

3.3 Output Standard

4. Gaps Summary

4.1 Critical Gaps (Blocking Tracker Use)

4.2 Standard Gaps (Improve UX)

5. Proposed CLI Architecture

5.1 Package Structure

5.2 API Client Library

6. Recommendations

6.1 Immediate Actions

6.2 Proposed ADR (CLI Standard)

References