ADR-009: CODI Command Interface (v4) - Part 1: Human Narrative
Document Specification Block
Document: ADR-009-v4-codi-command-interface-part1-human
Version: 1.0.0
Purpose: Introduce CODI as a friendly assistant interface that makes CODITECT approachable and powerful
Audience: Business stakeholders, product managers, developers, UX designers
Date Created: 2025-08-27
Date Modified: 2025-08-31
Status: DRAFT
Table of Contents
- 1. Document Information
- 2. Purpose of this ADR
- 3. User Story Context
- 4. Executive Summary
- 5. Visual Overview
- 6. Background & Problem
- 7. Decision
- 8. Consequences
- 9. References & Standards
1. Document Information 🔴 REQUIRED
| Field | Value |
|---|---|
| ADR Number | ADR-009 |
| Title | CODI Command Interface - Your Friendly CODITECT Assistant |
| Status | Draft |
| Date Created | 2025-08-27 |
| Last Modified | 2025-08-27 |
| Version | 1.0 |
| Decision Makers | Platform Architect, Lead Developer, UX Designer |
| Stakeholders | All CODITECT users, Development teams, AI agents |
2. Purpose of this ADR 🔴 REQUIRED
This ADR serves dual purposes:
- For Humans 👥: Introduces CODI, your friendly assistant who makes CODITECT feel approachable and powerful, like having a helpful colleague who knows everything about your project
- For AI Agents 🤖: Defines the standardized command interface, Rust binary architecture, and MCP integration protocols for autonomous tool orchestration
3. User Story Context 🔴 REQUIRED
As a developer using CODITECT,
I want a simple, memorable command interface that feels like talking to a helpful assistant,
So that I can focus on building instead of remembering complex commands.
📋 Acceptance Criteria:
- Commands feel natural: "codi help me with..."
- Everything works with simple commands like
codi deploy - Complex operations happen behind simple interfaces
- Team coordination is effortless
- Works identically whether human or AI agent is using it
4. Executive Summary 🔴 REQUIRED
🏢 For Business Stakeholders
Imagine having a personal assistant named CODI who knows everything about your software project. Instead of remembering dozens of complex commands, you just say things like "CODI, deploy the frontend" or "CODI, help me review this code."
CODI is like having a friendly expert sitting next to you who:
- Never forgets anything about your project
- Can coordinate with your entire team instantly
- Speaks both human and AI languages fluently
- Makes complex tasks feel simple
Business Value: Reduces onboarding time from weeks to hours, increases developer productivity by 40%, and enables seamless human-AI collaboration.
Key Decision: We're creating CODI as the universal interface to CODITECT, making it as easy to use as talking to a helpful colleague.
💻 For Technical Readers
Technical Summary: CODI is a Rust-based CLI that provides a git-like command interface to CODITECT, with built-in MCP server/client capabilities for tool ecosystem integration and a standardized .codi/ directory structure for persistent state management.
5. Visual Overview 🔴 REQUIRED (Minimum 2)
5.1 CODI in Daily Development
5.2 CODI Architecture Overview
6. Background & Problem 🔴 REQUIRED
6.1 Business Context
- Why this matters: Developers spend 30% of their time looking up commands and documentation
- User impact: Current tools feel robotic and impersonal, creating friction
- Cost of inaction: Each developer loses 2 hours daily to tool complexity
6.2 Technical Context
- Current state: Scattered scripts in various directories, no unified interface
- Limitations: No persistent state, no team coordination, no AI integration
- Technical debt: Multiple command styles, inconsistent naming, poor discoverability
6.3 Constraints
| Type | Constraint | Impact |
|---|---|---|
| ⏰ Time | 4 weeks to MVP | Must use existing backend services |
| 💰 Budget | $0 additional infrastructure | Leverage current cloud resources |
| 👥 Resources | 2 developers | Focus on essential commands first |
| 🔧 Technical | Must work in containers | Persistent state in .codi/ |
| 📜 Compliance | Audit all commands | Built-in logging required |
7. Decision 🔴 REQUIRED
7.1 Y-Statement Format
In the context of making CODITECT accessible to both humans and AI agents,
facing complexity overwhelming users and lack of standardization,
we decided for CODI as a friendly, persona-based command interface
and neglected traditional CLI tools, REST-only APIs, GUI-first approach,
to achieve human-friendly interaction with powerful backend orchestration,
accepting initial development time and Rust learning curve,
because simplicity at the surface with power underneath drives adoption.
7.2 What We're Doing
Creating CODI - a friendly assistant persona that provides a unified command interface to CODITECT. Every CODITECT project will have a .codi/ directory with a Rust-based CLI that makes complex operations feel like chatting with a helpful colleague.
7.3 Why This Approach
- Human-Centric: Commands feel natural, like talking to a person
- Power Hidden: Complex orchestration behind simple commands
- Universal Language: Same commands work for humans and AI agents
- Ecosystem Ready: MCP integration enables network effects
7.4 Alternatives Considered 🟡 OPTIONAL (but recommended)
Option A: Traditional CLI Tools
| Aspect | Details |
|---|---|
| Description | Separate command tools like coditect-deploy, coditect-build |
| ✅ Pros | • Unix philosophy • Simple implementation |
| ❌ Cons | • Hard to discover • No unified experience |
| Rejection Reason | Lacks personality and cohesion |
Option B: REST API Only
| Aspect | Details |
|---|---|
| Description | Pure HTTP API with curl commands |
| ✅ Pros | • Maximum flexibility • Language agnostic |
| ❌ Cons | • Unfriendly to humans • Complex for simple tasks |
| Rejection Reason | Too low-level for daily use |
8. Consequences 🔴 REQUIRED
8.1 Positive Outcomes
- ✅ Delightful Experience: Developers enjoy using CODITECT
- ✅ Rapid Adoption: Teams onboard in hours, not weeks
- ✅ Network Effects: MCP integration attracts ecosystem
- ✅ Future-Proof: Same interface for human and AI users
8.2 Negative Impacts
- ⚠️ Initial Investment: 4 weeks to build CODI properly
- ⚠️ Rust Expertise: Team needs Rust knowledge
- ⚠️ Migration Effort: Existing users must adapt
8.3 Risk Register 🟡 OPTIONAL
| Risk | Probability | Impact | Mitigation | Owner |
|---|---|---|---|---|
| Users reject persona concept | Low | High | User testing early | UX Team |
| Rust binary too complex | Medium | Medium | Start with bash prototype | Dev Team |
| MCP standard changes | Low | Medium | Abstract integration layer | Architect |
8.4 Test Coverage Requirements
To ensure CODI meets our quality standards:
- Unit Tests: ≥ 90% coverage for all CODI components
- Integration Tests: ≥ 80% coverage for API interactions
- Critical Paths: 100% coverage for authentication and command routing
- User Acceptance: All acceptance criteria from Section 3 must have automated tests
- Performance Tests: Response time benchmarks for all commands
9. References & Standards 🔴 REQUIRED
9.1 Related ADRs
- ADR-001: Foundation Architecture
- ADR-004: API Architecture
- ADR-075-v3: Session Recovery
9.2 External Documentation
- MCP Specification: Model Context Protocol
- Rust CLI Book: Building CLIs in Rust
- Command Language Design: CLI Guidelines
9.3 Standards & Compliance 🟡 OPTIONAL
- POSIX.1-2017: Command line standards
- XDG Base Directory: Directory standards
Next: See Part 2: Technical Implementation for Rust implementation, command specifications, and MCP integration details.