red64-cli 0.3.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/README.md +194 -338
  2. package/dist/cli/parseArgs.d.ts.map +1 -1
  3. package/dist/cli/parseArgs.js +5 -13
  4. package/dist/cli/parseArgs.js.map +1 -1
  5. package/dist/components/init/types.d.ts +0 -2
  6. package/dist/components/init/types.d.ts.map +1 -1
  7. package/dist/components/screens/HelpScreen.d.ts.map +1 -1
  8. package/dist/components/screens/HelpScreen.js +0 -2
  9. package/dist/components/screens/HelpScreen.js.map +1 -1
  10. package/dist/components/screens/InitScreen.d.ts.map +1 -1
  11. package/dist/components/screens/InitScreen.js +5 -8
  12. package/dist/components/screens/InitScreen.js.map +1 -1
  13. package/dist/components/screens/StartScreen.d.ts.map +1 -1
  14. package/dist/components/screens/StartScreen.js +29 -8
  15. package/dist/components/screens/StartScreen.js.map +1 -1
  16. package/dist/components/screens/StatusScreen.d.ts.map +1 -1
  17. package/dist/components/screens/StatusScreen.js +16 -1
  18. package/dist/components/screens/StatusScreen.js.map +1 -1
  19. package/dist/services/AgentInvoker.d.ts.map +1 -1
  20. package/dist/services/AgentInvoker.js +76 -37
  21. package/dist/services/AgentInvoker.js.map +1 -1
  22. package/dist/services/ClaudeErrorDetector.d.ts +1 -1
  23. package/dist/services/ClaudeErrorDetector.d.ts.map +1 -1
  24. package/dist/services/ClaudeErrorDetector.js +1 -0
  25. package/dist/services/ClaudeErrorDetector.js.map +1 -1
  26. package/dist/services/ClaudeHealthCheck.d.ts +7 -0
  27. package/dist/services/ClaudeHealthCheck.d.ts.map +1 -1
  28. package/dist/services/ClaudeHealthCheck.js +76 -12
  29. package/dist/services/ClaudeHealthCheck.js.map +1 -1
  30. package/dist/services/ConfigService.d.ts +1 -0
  31. package/dist/services/ConfigService.d.ts.map +1 -1
  32. package/dist/services/ConfigService.js.map +1 -1
  33. package/dist/services/DockerRunner.js +1 -1
  34. package/dist/services/DockerRunner.js.map +1 -1
  35. package/dist/services/PhaseExecutor.d.ts.map +1 -1
  36. package/dist/services/PhaseExecutor.js +2 -1
  37. package/dist/services/PhaseExecutor.js.map +1 -1
  38. package/dist/services/TaskRunner.d.ts.map +1 -1
  39. package/dist/services/TaskRunner.js +2 -1
  40. package/dist/services/TaskRunner.js.map +1 -1
  41. package/dist/services/index.d.ts +1 -1
  42. package/dist/services/index.d.ts.map +1 -1
  43. package/dist/services/index.js +1 -1
  44. package/dist/services/index.js.map +1 -1
  45. package/dist/types/index.d.ts +4 -3
  46. package/dist/types/index.d.ts.map +1 -1
  47. package/dist/types/index.js.map +1 -1
  48. package/framework/stacks/c/code-quality.md +326 -0
  49. package/framework/stacks/c/coding-style.md +347 -0
  50. package/framework/stacks/c/conventions.md +513 -0
  51. package/framework/stacks/c/error-handling.md +350 -0
  52. package/framework/stacks/c/feedback.md +158 -0
  53. package/framework/stacks/c/memory-safety.md +408 -0
  54. package/framework/stacks/c/tech.md +122 -0
  55. package/framework/stacks/c/testing.md +472 -0
  56. package/framework/stacks/cpp/code-quality.md +282 -0
  57. package/framework/stacks/cpp/coding-style.md +363 -0
  58. package/framework/stacks/cpp/conventions.md +420 -0
  59. package/framework/stacks/cpp/error-handling.md +264 -0
  60. package/framework/stacks/cpp/feedback.md +104 -0
  61. package/framework/stacks/cpp/memory-safety.md +351 -0
  62. package/framework/stacks/cpp/tech.md +160 -0
  63. package/framework/stacks/cpp/testing.md +323 -0
  64. package/framework/stacks/java/code-quality.md +357 -0
  65. package/framework/stacks/java/coding-style.md +400 -0
  66. package/framework/stacks/java/conventions.md +437 -0
  67. package/framework/stacks/java/error-handling.md +408 -0
  68. package/framework/stacks/java/feedback.md +180 -0
  69. package/framework/stacks/java/tech.md +126 -0
  70. package/framework/stacks/java/testing.md +485 -0
  71. package/framework/stacks/javascript/async-patterns.md +216 -0
  72. package/framework/stacks/javascript/code-quality.md +182 -0
  73. package/framework/stacks/javascript/coding-style.md +293 -0
  74. package/framework/stacks/javascript/conventions.md +268 -0
  75. package/framework/stacks/javascript/error-handling.md +216 -0
  76. package/framework/stacks/javascript/feedback.md +80 -0
  77. package/framework/stacks/javascript/tech.md +114 -0
  78. package/framework/stacks/javascript/testing.md +209 -0
  79. package/framework/stacks/loco/code-quality.md +156 -0
  80. package/framework/stacks/loco/coding-style.md +247 -0
  81. package/framework/stacks/loco/error-handling.md +225 -0
  82. package/framework/stacks/loco/feedback.md +35 -0
  83. package/framework/stacks/loco/loco.md +342 -0
  84. package/framework/stacks/loco/structure.md +193 -0
  85. package/framework/stacks/loco/tech.md +129 -0
  86. package/framework/stacks/loco/testing.md +211 -0
  87. package/framework/stacks/rust/code-quality.md +370 -0
  88. package/framework/stacks/rust/coding-style.md +475 -0
  89. package/framework/stacks/rust/conventions.md +430 -0
  90. package/framework/stacks/rust/error-handling.md +399 -0
  91. package/framework/stacks/rust/feedback.md +152 -0
  92. package/framework/stacks/rust/memory-safety.md +398 -0
  93. package/framework/stacks/rust/tech.md +121 -0
  94. package/framework/stacks/rust/testing.md +528 -0
  95. package/package.json +14 -2
package/README.md CHANGED
@@ -1,436 +1,285 @@
1
1
  # Red64 CLI
2
2
 
3
- **Deterministic spec-driven development orchestrator for AI-assisted coding.**
3
+ <div align="center">
4
4
 
5
- Red64 automates the entire feature development lifecycle—from requirements to implementation—using a structured, phase-gated workflow that ensures quality and traceability.
5
+ ### 30,000 hours of experience building software.<br/>The SDLC that makes AI-generated code maintainable.
6
6
 
7
- ![Red64 Flow Demo](docs/assets/demo.gif)
8
- <!-- TODO: Add screencast -->
7
+ **20 years of building products. 1+ year of AI-first development. Captured in a CLI.**
9
8
 
10
- ---
11
-
12
- ## Quick Start
13
-
14
- ### 1. Install
15
-
16
- ```bash
17
- # Clone and install
18
- git clone https://github.com/your-org/red64-cli.git
19
- cd red64-cli
20
- npm install
21
- npm link
22
- ```
9
+ TDD built in. Code smells to avoid. Documentation required. Quality gates enforced.<br/>
10
+ The process that turns AI code into production-ready software.
11
+ The result? Code that lives and evolves—not legacy the day it ships.
23
12
 
24
- ### 2. Initialize your project
13
+ [![npm version](https://img.shields.io/npm/v/red64-cli.svg)](https://www.npmjs.com/package/red64-cli)
14
+ [![Build](https://github.com/Red64llc/red64-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Red64llc/red64-cli/actions/workflows/ci.yml)
15
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
16
+ [![Built with Red64](https://img.shields.io/badge/Built%20with-Red64-red)](https://red64.io/ventures)
25
17
 
26
- ```bash
27
- cd /path/to/your/project
28
- red64 init
29
- ```
18
+ [Quick Start](#-quick-start) · [Why Red64](#-why-red64) · [Features](#-features) · [Documentation](#-documentation)
30
19
 
31
- ### 3. Start a feature
32
-
33
- ```bash
34
- red64 start "user-authentication" "Add login and registration with JWT tokens"
35
- ```
20
+ </div>
36
21
 
37
- Red64 will:
38
- 1. Create an isolated git worktree
39
- 2. Generate requirements (EARS format)
40
- 3. Create technical design
41
- 4. Break down into implementation tasks
42
- 5. Execute each task with commits
43
- 6. Complete with a ready-to-review branch
22
+ <img width="1283" height="378" alt="Red64 CLI screenshot (claude)" src="https://github.com/user-attachments/assets/cc309998-340b-4764-af83-902efc26b58f" />
44
23
 
45
24
  ---
46
25
 
47
- ## What is Red64?
26
+ ## 🎯 The Problem
48
27
 
49
- Red64 is a **spec-driven development orchestrator** that brings structure and determinism to AI-assisted coding. Instead of ad-hoc prompting, Red64 enforces a rigorous workflow:
28
+ I've spent 20 years building products and writing software. 30,000 hours of experience. Then I went all-in on AI coding tools:
50
29
 
51
- ```
52
- Requirements → Design → Tasks → Implementation
53
- ↓ ↓ ↓ ↓
54
- (review) (review) (review) (commits)
55
- ```
56
-
57
- ### Key Features
30
+ **They're incredible for building a feature.** But then you start iterating—and you hit a wall:
58
31
 
59
- | Feature | Description |
60
- |---------|-------------|
61
- | **Spec-Driven** | Every feature starts with formal requirements and design |
62
- | **Phase Gates** | Human review required between phases (or auto-approve with `-y`) |
63
- | **Git Isolation** | Each feature runs in its own worktree and branch (sibling directory) |
64
- | **Atomic Commits** | One commit per task for clean history |
65
- | **Sandboxed Execution** | Optional Docker isolation for safe agent execution |
66
- | **Resumable Flows** | `start` auto-detects in-progress flows and offers resume |
67
- | **API Health Checks** | Validates Claude API before starting (credits, auth, network) |
32
+ - Code quality goes down the drain
33
+ - ❌ No testing (or tests written after the fact)
34
+ - No documentation/specs (good luck iterating on anything)
35
+ - No careful design review, no code review
36
+ - No quality gates—code smells everywhere
37
+ - Large commits that can't be easily rolled back
38
+ - No non-regression tests, so things start breaking
68
39
 
69
- ### Goals
40
+ **This is the same problem that arises in any team with no processes, no gates, no constraints.**
70
41
 
71
- 1. **Predictability**: Same inputs produce consistent outputs through structured phases
72
- 2. **Traceability**: Every code change links back to requirements and design decisions
73
- 3. **Quality**: Mandatory review gates prevent AI hallucinations from reaching production
74
- 4. **Isolation**: Git worktrees prevent work-in-progress from polluting main branch
75
- 5. **Efficiency**: Automate the tedious parts while keeping humans in control
42
+ ## The Solution
76
43
 
77
- ---
44
+ The solution is what I've been doing for 20 years: **Software Development Life Cycle and Processes.** The stuff tech leaders and experience software professional implement in their teams. The stuff that separates "it works" from "it's maintainable."
78
45
 
79
- ## Installation
46
+ **Red64 CLI captures both:**
80
47
 
81
- ### Requirements
48
+ 1. **My 30,000 hours of experience** — code smells to avoid, patterns that scale, production wisdom
49
+ 2. **My process for working with AI** — the SDLC that makes AI-generated code maintainable
82
50
 
83
- - Node.js >= 20.0.0
84
- - Git
85
- - Claude CLI (`npm install -g @anthropic-ai/claude-cli`)
86
- - Docker (optional, for sandboxed execution)
51
+ **The process (HOW the software professional works):**
52
+ - Isolate every feature in a branch (git worktree)
53
+ - Write tests FIRST (TDD built in)
54
+ - Small atomic commits (one thing per commit)
55
+ - Document everything (REQUIREMENTS.md, DESIGN.md)
56
+ - High test coverage enforced
57
+ - Quality gates at every phase
87
58
 
88
- ### From Source
59
+ **The expertise (WHAT the software professional builds):**
60
+ - Code smells to avoid (the stuff that breaks at 3 AM)
61
+ - Patterns and anti-patterns for Python, Next, Ruby, Rails etc...
62
+ - Stack-specific conventions (Next.js, Rails, FastAPI, etc.)
89
63
 
90
- ```bash
91
- git clone https://github.com/your-org/red64-cli.git
92
- cd red64-cli
93
- npm install
94
- npm run build
95
- npm link
96
- ```
97
-
98
- ### Verify Installation
99
-
100
- ```bash
101
- red64 --version
102
- red64 help
103
- ```
64
+ **The result:** Code that lives and evolves. We've rewritten features in another language in **days** because the documentation is so complete.
104
65
 
105
66
  ---
106
67
 
107
- ## Commands
108
-
109
- ### `red64 init`
110
-
111
- Initialize Red64 in your project. Creates `.red64/` directory with steering documents.
68
+ ## 🚀 Quick Start
112
69
 
113
70
  ```bash
114
- red64 init
115
- red64 init --repo owner/repo --stack nextjs
116
- red64 init --agent gemini # Use Gemini as coding agent
117
- ```
118
-
119
- **Flags:**
120
- - `-a, --agent <name>` — Coding agent: `claude`, `gemini`, `codex` (default: `claude`)
121
-
122
- ![red64 init](docs/assets/init.png)
123
- <!-- TODO: Add screenshot -->
124
-
125
- ### `red64 start <feature> <description>`
126
-
127
- Start a new feature development flow, or resume an existing one.
128
-
129
- ```bash
130
- red64 start "shopping-cart" "Add shopping cart with add/remove items and checkout"
131
- ```
132
-
133
- **Smart Resume Detection:**
134
-
135
- When you run `start` for a feature that's already in progress (at any phase: requirements, design, tasks, or implementation), Red64 will:
71
+ # Install
72
+ npm install -g red64-cli
136
73
 
137
- 1. **Detect uncommitted changes** — If the worktree has uncommitted changes, prompts:
138
- - Commit changes (WIP commit)
139
- - Discard changes
140
- - Cancel
141
-
142
- 2. **Offer resume or restart** — If an in-progress flow is found, prompts:
143
- - Resume from current phase
144
- - Start fresh (discard previous progress)
145
- - Cancel
146
-
147
- This means you can always use `red64 start <feature>` to continue working—no separate resume command needed.
148
-
149
- **Flags:**
150
- - `-m, --model <name>` — Model to use (e.g., `claude-3-5-haiku-latest` for dev, `claude-sonnet-4-20250514` for prod)
151
- - `-y, --yes` — Auto-approve all phases (skip review gates)
152
- - `-b, --brownfield` — Enable gap analysis for existing codebases
153
- - `-g, --greenfield` — New feature mode (default)
154
- - `-s, --skip-permissions` — Pass to Claude CLI
155
- - `-t, --tier <name>` — Use specific Claude config tier
156
- - `--sandbox` — Run in Docker isolation
157
- - `--verbose` — Show detailed execution logs
158
-
159
- <img width="1134" height="567" alt="Screenshot 2026-01-29 at 6 35 01 PM" src="https://github.com/user-attachments/assets/91ea478f-53de-4964-a0b2-b0f05d2bfb2b" />
160
-
161
- ### `red64 status [feature]`
74
+ # Initialize in your project
75
+ cd /path/to/your/project
76
+ red64 init --stack nextjs
162
77
 
163
- Show the status of a flow.
78
+ # Start a feature (interactive mode)
79
+ red64 start "user-auth" "Add login and registration with JWT"
164
80
 
165
- ```bash
166
- red64 status shopping-cart
167
- red64 status # Show all flows
81
+ # Or YOLO mode — no babysitting required
82
+ red64 start "shopping-cart" "Full cart with checkout" --sandbox -y
168
83
  ```
169
84
 
170
- ![red64 status](docs/assets/status.png)
171
- <!-- TODO: Add screenshot -->
172
-
173
- ### `red64 list`
85
+ That's it. Red64 generates requirements → design → tests → implementation → documentation.
174
86
 
175
- List all active flows in the repository.
87
+ Each phase has review checkpoints. Each task = one clean commit. Tests first. Docs included.
176
88
 
177
- ```bash
178
- red64 list
179
- ```
89
+ ---
180
90
 
181
- ### `red64 abort <feature>`
91
+ ## 🔥 YOLO Mode (No Babysitting)
182
92
 
183
- Abort a flow and clean up resources (worktree, branch).
93
+ Tired of approving every line?
184
94
 
185
95
  ```bash
186
- red64 abort shopping-cart
96
+ red64 start "feature-name" "description" --sandbox -y
187
97
  ```
188
98
 
189
- ---
190
-
191
- ## Workflow Phases
192
-
193
- ### 1. Initialization
194
-
195
- Creates spec directory at `.red64/specs/<feature>/` with `spec.json`.
196
-
197
- ### 2. Requirements Generation
198
-
199
- Generates `requirements.md` using EARS (Easy Approach to Requirements Syntax) format:
200
- - Ubiquitous requirements
201
- - Event-driven requirements
202
- - State-driven requirements
203
- - Optional features
204
- - Unwanted behaviors
205
-
206
- ### 3. Gap Analysis (Brownfield only)
207
-
208
- For existing codebases, analyzes what already exists and what needs to be built.
209
-
210
- ### 4. Design Generation
211
-
212
- Creates `design.md` with:
213
- - Architecture decisions
214
- - Component design
215
- - Data models
216
- - API contracts
217
- - File structure
218
-
219
- ### 5. Task Generation
220
-
221
- Breaks down the design into atomic `tasks.md`:
222
- - Each task is independently implementable
223
- - Tasks are ordered by dependency
224
- - Each task produces a commit
99
+ - `--sandbox` = Docker isolation (AI can't break your system, pulls image from `ghcr.io/red64llc/red64-sandbox`)
100
+ - `-y` = Auto-approve all phases (total autonomy)
225
101
 
226
- ### 6. Implementation
102
+ **Start a feature. Go to lunch. Come back to a completed branch—with tests, docs, and clean commits.**
227
103
 
228
- Executes tasks sequentially:
229
- - Runs `/red64:spec-impl <feature> <task-id>`
230
- - Commits after each task
231
- - Checkpoints every 3 tasks (optional pause)
104
+ With other tools, YOLO mode means "write code fast with no oversight."<br/>
105
+ With Red64, autonomous mode means "follow the SDLC with no babysitting."
232
106
 
233
- ### 7. Completion
107
+ The AI still:
108
+ 1. Writes tests FIRST (TDD enforced)
109
+ 2. Documents everything (REQUIREMENTS.md, DESIGN.md)
110
+ 3. Makes atomic commits (easy to review, easy to rollback)
111
+ 4. Passes quality gates (no code smells ship)
234
112
 
235
- Flow completes with:
236
- - All tasks implemented
237
- - Clean commit history
238
- - Feature branch ready for PR
113
+ **Review the PR when it's done. Like a senior engineer delegating to a junior who's been properly onboarded.**
239
114
 
240
115
  ---
241
116
 
242
- ## Comparison with Other Tools
117
+ ## 🏆 Battle-Tested
243
118
 
244
- | Feature | Red64 | Cursor/Copilot | Aider | Claude Code |
245
- |---------|-------|----------------|-------|-------------|
246
- | **Spec-driven workflow** | Yes | No | No | No |
247
- | **Phase gates** | Yes | No | No | No |
248
- | **Git worktree isolation** | Yes | No | No | No |
249
- | **Atomic commits per task** | Yes | No | Yes | No |
250
- | **Requirements generation** | Yes | No | No | No |
251
- | **Design documents** | Yes | No | No | No |
252
- | **Resumable flows** | Yes | No | Partial | No |
253
- | **Docker sandboxing** | Yes | No | No | Yes |
254
- | **IDE integration** | No | Yes | Partial | Yes |
255
- | **Real-time editing** | No | Yes | Yes | Yes |
119
+ We built **6 production products** with Red64 at [red64.io/ventures](https://red64.io/ventures):
256
120
 
257
- ### When to use Red64
121
+ | Company | Industry | Status |
122
+ |---------|----------|--------|
123
+ | [Saife](https://red64.io/ventures) | InsurTech | Production |
124
+ | [EngineValue](https://red64.io/ventures) | Engineering Scorecards | Production |
125
+ | [MediaPulse](https://red64.io/ventures) | Digital Presence | Production |
126
+ | [TheScriptMarketplace](https://red64.io/ventures) | Entertainment | Production |
127
+ | [QueryVault](https://red64.io/ventures) | Data Platform | Production |
128
+ | [Kafi](Internal product) | Virtual Executive Assistant | Production |
258
129
 
259
- **Use Red64 when:**
260
- - Building complete features (not quick fixes)
261
- - You need traceable requirements and design
262
- - Working on complex, multi-file changes
263
- - You want clean git history with atomic commits
264
- - You need to pause and resume work across sessions
265
-
266
- **Use other tools when:**
267
- - Making quick, single-file edits
268
- - Exploring or prototyping ideas
269
- - You need real-time IDE integration
270
- - Working on bug fixes without spec requirements
130
+ Same tool. Same encoded experience. Now open source.
271
131
 
272
132
  ---
273
133
 
274
- ## Limitations
134
+ ## 💡 Why Red64?
275
135
 
276
- ### Current Limitations
136
+ ### Two Decades of Experience, Encoded
277
137
 
278
- 1. **No IDE integration**Red64 is CLI-only; no VS Code or JetBrains plugins yet
279
- 2. **Sequential execution** — Tasks run one at a time, no parallelization
280
- 3. **No incremental changes** — Regenerating a phase replaces previous output entirely
281
- 4. **English-centric** — Prompts and templates are English-only (configurable per spec)
138
+ I've spent 20 years building products30,000 hours of learning what works and what breaks. Then I spent a year going all-in on AI coding tools.
282
139
 
283
- ### Known Issues
140
+ **The pattern is always the same:**
284
141
 
285
- - Large codebases may hit context limits during design phase
286
- - Docker sandbox requires pre-built image (`docker build -f Dockerfile.sandbox -t red64-sandbox:latest .`)
287
- - Some UI frameworks may not render correctly in all terminals
142
+ 1. **Week 1:** "This is amazing! I shipped a feature in a day!"
143
+ 2. **Week 4:** "Why is everything breaking? Why is the code so messy?"
144
+ 3. **Week 8:** "I'm afraid to touch anything. Time to rewrite."
288
145
 
289
- ### Roadmap
146
+ **The missing ingredient?** SDLC. The stuff that takes 20 years to learn. The stuff I've been teaching engineers my entire career.
290
147
 
291
- - [ ] VS Code extension
292
- - [ ] Parallel task execution
293
- - [ ] Incremental phase editing
294
- - [ ] Web dashboard for flow monitoring
148
+ Red64 gives you both:
295
149
 
296
- ---
150
+ | What Goes Wrong Without SDLC | Red64 Solution |
151
+ |------------------------------|----------------|
152
+ | No tests → things break when you iterate | TDD built in (tests FIRST) |
153
+ | No docs → can't remember why anything works | REQUIREMENTS.md + DESIGN.md per feature |
154
+ | Huge commits → can't rollback, can't review | Atomic commits (one task = one commit) |
155
+ | No quality gates → code smells everywhere | Guardrails from 30K hours of experience |
156
+ | Babysitting every line → slow, exhausting | Autonomous mode with SDLC guardrails |
297
157
 
298
- ## Project Structure
158
+ ### What You Get Per Feature
299
159
 
300
160
  ```
301
- .red64/
302
- ├── specs/ # Feature specifications
303
- │ └── <feature>/
304
- ├── spec.json # Spec metadata
305
- ├── requirements.md # EARS requirements
306
- ├── design.md # Technical design
307
- └── tasks.md # Implementation tasks
308
- ├── flows/ # Flow state and logs
309
- └── <feature>/
310
- │ ├── state.json # Current flow state
311
- │ └── flow.log # Execution log
312
- └── steering/ # Project-wide guidance
313
- ├── product.md # Product context
314
- ├── tech.md # Technical standards
315
- └── structure.md # Codebase structure
161
+ feature-branch/
162
+ ├── REQUIREMENTS.md # What we're building and why
163
+ ├── DESIGN.md # How it works, architecture decisions
164
+ ├── TASKS.md # Atomic breakdown with acceptance criteria
165
+ ├── src/
166
+ ├── feature.ts # Implementation
167
+ └── feature.test.ts # Tests (written first)
168
+ └── docs/
169
+ └── feature.md # User-facing documentation
316
170
  ```
317
171
 
318
- ### Git Worktree Layout
319
-
320
- Red64 creates git worktrees in a **sibling directory** following the [GitLens/VSCode convention](https://gist.github.com/ChristopherA/4643b2f5e024578606b9cd5d2e6815cc). This keeps the main repository clean and avoids nested git structures.
321
-
322
- ```
323
- ~/projects/
324
- ├── my-project/ # Main repository (unchanged)
325
- │ ├── .git/
326
- │ ├── .red64/
327
- │ ├── src/
328
- │ └── package.json
329
- └── my-project.worktrees/ # Worktrees directory (sibling)
330
- ├── user-authentication/ # feature/user-authentication branch
331
- │ ├── .red64/
332
- │ ├── src/
333
- │ └── package.json
334
- └── shopping-cart/ # feature/shopping-cart branch
335
- ├── .red64/
336
- ├── src/
337
- └── package.json
338
- ```
339
-
340
- **Benefits of sibling worktrees:**
341
- - Main repository stays clean (no `.gitignore` needed for worktrees)
342
- - No nested `.git` references inside the working tree
343
- - Better IDE and tool compatibility
344
- - Clear separation between main work and feature isolation
345
- - Easy to see all active features at a glance
172
+ Every decision traceable. Every line has a reason. **Code that survives iteration.**
346
173
 
347
174
  ---
348
175
 
349
- ## Configuration
176
+ ## 📊 Comparison
177
+
178
+ | Feature | Red64 | Cursor | Copilot | Claude Code | Gemini CLI | Aider |
179
+ |---------|:-----:|:------:|:-------:|:-----------:|:----------:|:-----:|
180
+ | **30K hours expertise encoded** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
181
+ | **SDLC/Process enforced** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
182
+ | **Autonomous mode** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
183
+ | **Sandboxed execution** | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
184
+ | **MCP support** | ✅ | ⚠️ | ✅ | ✅ | ✅ | ❌ |
185
+ | **TDD enforced (tests first)** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
186
+ | **High coverage enforced** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
187
+ | **Auto-generates docs** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
188
+ | **Git worktree isolation** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
189
+ | **Atomic commits enforced** | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
190
+ | **Phase gates with review** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
191
+ | **Code smell guardrails** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
192
+ | **Resumable multi-step flows** | ✅ | ❌ | ❌ | ✅ | ❌ | ⚠️ |
193
+ | **Multi-model support** | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
194
+ | **Battle-tested (production)** | ✅ 6 cos | N/A | N/A | N/A | N/A | N/A |
195
+
196
+ **Key:** ✅ = Built-in & enforced | ⚠️ = Partial/Optional | ❌ = Not available
197
+
198
+ > **The difference:** Other tools have autonomous modes. Red64 has autonomous mode **plus** the encoded expertise and enforced process that produces production-quality code.
199
+
200
+ ### When to Use Red64
201
+
202
+ ✅ **Use Red64 when:**
203
+ - Building complete features (not quick fixes)
204
+ - You want code with tests, docs, and clean history
205
+ - You need to walk away and let AI work autonomously
206
+ - You're tired of babysitting every line
207
+ - You want code that's safe to refactor
350
208
 
351
- ### Steering Documents
209
+ **Use other tools when:**
210
+ - Making quick, single-file edits
211
+ - You want real-time IDE autocomplete
212
+ - Exploring or prototyping ideas
352
213
 
353
- Customize AI behavior by editing `.red64/steering/`:
214
+ ---
354
215
 
355
- - **product.md** — Product vision, user personas, business rules
356
- - **tech.md** — Tech stack, coding standards, patterns to use/avoid
357
- - **structure.md** — Codebase organization, file naming conventions
216
+ ## Features
358
217
 
359
- ### Coding Agents
218
+ ### Multi-Agent Support
360
219
 
361
- Red64 supports multiple coding agents. Set the agent at init time:
220
+ Use your preferred AI:
362
221
 
363
222
  ```bash
364
- red64 init --agent claude # Default - Anthropic Claude
223
+ red64 init --agent claude # Default
365
224
  red64 init --agent gemini # Google Gemini
366
225
  red64 init --agent codex # OpenAI Codex
367
226
  ```
368
227
 
369
- The agent is stored in `.red64/config.json` and used for all subsequent commands.
370
-
371
- ### Model Selection
228
+ ### Smart Resume
372
229
 
373
- Override the model per command for cost optimization:
230
+ Interrupted? Just run `start` again:
374
231
 
375
232
  ```bash
376
- # Development (cheap, fast models)
377
- red64 start "feature" "desc" --model claude-3-5-haiku-latest
378
- red64 start "feature" "desc" --model gemini-2.0-flash
379
- red64 start "feature" "desc" --model gpt-4o-mini
380
-
381
- # Production (best quality models)
382
- red64 start "feature" "desc" --model claude-sonnet-4-20250514
383
- red64 start "feature" "desc" --model gemini-2.5-pro
384
- red64 start "feature" "desc" --model o1
233
+ red64 start "shopping-cart" "..."
234
+ # Detects in-progress flow, offers to resume
385
235
  ```
386
236
 
387
- | Agent | Cheap (Dev) | Best (Prod) |
388
- |-------|-------------|-------------|
389
- | Claude | `claude-3-5-haiku-latest` | `claude-sonnet-4-20250514` |
390
- | Gemini | `gemini-2.0-flash` | `gemini-2.5-pro` |
391
- | Codex | `gpt-4o-mini` | `o1` |
392
-
393
- ### Claude Tiers
237
+ ### Steering Documents
394
238
 
395
- Use different Claude configurations with `--tier`:
239
+ Customize AI behavior in `.red64/steering/`:
396
240
 
397
- ```bash
398
- red64 start "feature" "desc" --tier pro
399
- # Uses ~/.claude-pro/ for configuration
400
- ```
241
+ - **product.md** — Product vision, user personas
242
+ - **tech.md** Stack standards, code smells to avoid
243
+ - **structure.md** Codebase organization
401
244
 
402
245
  ---
403
246
 
404
- ## Development
405
-
406
- ### Run in development mode
407
-
408
- ```bash
409
- npm run dev -- start my-feature "Feature description"
410
- ```
247
+ ## 📖 Documentation
411
248
 
412
- ### Run tests
249
+ - [Full Documentation](./docs/README.md)
250
+ - [Steering Document Guide](./docs/steering.md)
251
+ - [Configuration Reference](./docs/configuration.md)
252
+ - [Troubleshooting](./docs/troubleshooting.md)
413
253
 
414
- ```bash
415
- npm test
416
- npm run test:ui
417
- ```
254
+ ---
418
255
 
419
- ### Build
256
+ ## 🛠 Commands
420
257
 
421
258
  ```bash
422
- npm run build
259
+ red64 init --agent gemini # Initialize Red64 in your project
260
+ red64 start <feature> <desc> # Start a new feature
261
+ red64 start ... --sandbox -y # YOLO mode (autonomous)
262
+ red64 status [feature] # Check flow status
263
+ red64 list # List all active flows
264
+ red64 abort <feature> # Abort and clean up
423
265
  ```
424
266
 
425
- ### Type checking
267
+ ### Flags
426
268
 
427
- ```bash
428
- npm run type-check
429
- ```
269
+ | Flag | Description |
270
+ |------|-------------|
271
+ | `-y, --yes` | Auto-approve all phases (YOLO mode) |
272
+ | `--sandbox` | Run in Docker isolation (uses GHCR image by default) |
273
+ | `--local-image` | Build and use local sandbox image instead of GHCR (init only) |
274
+ | `-m, --model` | Override AI model |
275
+ | `-a, --agent` | Set coding agent (claude/gemini/codex) |
276
+ | `--verbose` | Show detailed logs |
430
277
 
431
278
  ---
432
279
 
433
- ## Contributing
280
+ ## 🤝 Contributing
281
+
282
+ We'd love your help encoding more production wisdom:
434
283
 
435
284
  1. Fork the repository
436
285
  2. Create a feature branch
@@ -438,16 +287,23 @@ npm run type-check
438
287
  4. Run tests: `npm test`
439
288
  5. Submit a pull request
440
289
 
290
+ **What we're looking for:**
291
+ - More code smells to catch
292
+ - Stack-specific best practices
293
+ - Bug fixes and improvements
294
+
441
295
  ---
442
296
 
443
- ## License
297
+ ## 📜 License
444
298
 
445
- MIT
299
+ MIT — Built by [Yacin Bahi](mailto:yacin@red64.io) at [Red64.io](https://red64.io)
446
300
 
447
301
  ---
448
302
 
449
- ## Acknowledgments
303
+ <div align="center">
304
+
305
+ ### The code isn't the asset.<br/>The documentation + tests + history is the asset.<br/>The code is just the current implementation.
306
+
307
+ **[⭐ Star this repo](https://github.com/Red64llc/red64-cli)** if you believe AI should write code like a senior engineer.
450
308
 
451
- - Built by Yacin Bahi, yacin@Red64.io
452
- - Inspired by spec-driven development and EARS requirements methodology
453
- - Uses [Ink](https://github.com/vadimdemedes/ink) for terminal UI
309
+ </div>
@@ -1 +1 @@
1
- {"version":3,"file":"parseArgs.d.ts","sourceRoot":"","sources":["../../src/cli/parseArgs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAqC,MAAM,mBAAmB,CAAC;AAatF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAiH5D;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,QAwBd,CAAC"}
1
+ {"version":3,"file":"parseArgs.d.ts","sourceRoot":"","sources":["../../src/cli/parseArgs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAqC,MAAM,mBAAmB,CAAC;AAatF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CA0G5D;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,QAyBd,CAAC"}