cc-pipeline 0.4.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.
- package/BUILD_SUMMARY.md +104 -0
- package/LICENSE +21 -0
- package/README.md +288 -0
- package/bin/cc-pipeline.js +8 -0
- package/docs/AGENT-TEAMS-RESEARCH.md +84 -0
- package/docs/IDEAS.md +24 -0
- package/docs/SYSTEM-PROMPTS-RESEARCH.md +86 -0
- package/docs/brief-example.png +0 -0
- package/package.json +36 -0
- package/src/agents/base.js +56 -0
- package/src/agents/bash.js +50 -0
- package/src/agents/claude-interactive.js +248 -0
- package/src/agents/claude-piped.js +81 -0
- package/src/cli.js +72 -0
- package/src/commands/init.js +55 -0
- package/src/commands/reset.js +46 -0
- package/src/commands/run.js +5 -0
- package/src/commands/status.js +49 -0
- package/src/commands/update.js +42 -0
- package/src/config.js +101 -0
- package/src/engine.js +326 -0
- package/src/logger.js +57 -0
- package/src/prompts.js +49 -0
- package/src/state.js +154 -0
- package/templates/BRIEF.md.example +28 -0
- package/templates/CLAUDE.md +67 -0
- package/templates/pipeline/CLAUDE.md +102 -0
- package/templates/pipeline/prompts/build.md +78 -0
- package/templates/pipeline/prompts/commit.md +40 -0
- package/templates/pipeline/prompts/fix.md +58 -0
- package/templates/pipeline/prompts/plan.md +105 -0
- package/templates/pipeline/prompts/reflect.md +70 -0
- package/templates/pipeline/prompts/research.md +76 -0
- package/templates/pipeline/prompts/review.md +111 -0
- package/templates/pipeline/prompts/spec.md +114 -0
- package/templates/pipeline/prompts/status.md +74 -0
- package/templates/pipeline/workflow.yaml +81 -0
package/BUILD_SUMMARY.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# CC-Pipeline Build Summary
|
|
2
|
+
|
|
3
|
+
**Project:** cc-pipeline v0.1.0
|
|
4
|
+
**Location:** ~/wrk/cc-pipeline
|
|
5
|
+
**Build Method:** Claude Code Agent Teams (4 Phases)
|
|
6
|
+
**Build Date:** 2025-02-16
|
|
7
|
+
**Build Supervisor:** cc-pipeline-supervisor-2 subagent
|
|
8
|
+
|
|
9
|
+
## Phase Summary
|
|
10
|
+
|
|
11
|
+
### Phase 1: Core Engine ✅
|
|
12
|
+
**Commits:** 7c4ce08
|
|
13
|
+
|
|
14
|
+
Implemented:
|
|
15
|
+
- Engine with phase/step execution
|
|
16
|
+
- State management (JSONL event log)
|
|
17
|
+
- Config parsing (workflow.yaml)
|
|
18
|
+
- Prompt system with template substitution
|
|
19
|
+
- Logger with structured output
|
|
20
|
+
|
|
21
|
+
### Phase 2: Agent Implementations ✅
|
|
22
|
+
**Commits:** 31853e7, 686fd26
|
|
23
|
+
|
|
24
|
+
Implemented:
|
|
25
|
+
- BaseAgent class architecture
|
|
26
|
+
- BashAgent (shell commands)
|
|
27
|
+
- ClaudePipedAgent (document generation)
|
|
28
|
+
- ClaudeInteractiveAgent (tmux sessions)
|
|
29
|
+
- Signal handling (SIGINT/SIGTERM)
|
|
30
|
+
- Staff review fixes
|
|
31
|
+
|
|
32
|
+
### Phase 3: CLI Polish & Integration ✅
|
|
33
|
+
**Commits:** ae77b55, abf990c, e27f5a0
|
|
34
|
+
|
|
35
|
+
Implemented:
|
|
36
|
+
- Enhanced banner with Unicode box art
|
|
37
|
+
- Status command with formatted output
|
|
38
|
+
- Signal/resume end-to-end testing
|
|
39
|
+
- 19 new tests (total: 24 tests)
|
|
40
|
+
- Bug fixes: signal handler, banner ANSI
|
|
41
|
+
|
|
42
|
+
### Phase 4: Tests & Documentation ✅
|
|
43
|
+
**Commits:** 631793f, 483993f, c105f01
|
|
44
|
+
|
|
45
|
+
Implemented:
|
|
46
|
+
- 62 additional tests (total: 86 tests)
|
|
47
|
+
- Comprehensive README.md (308 lines)
|
|
48
|
+
- MIT LICENSE
|
|
49
|
+
- npm publish verification (23.7 kB package)
|
|
50
|
+
- .npmignore configuration
|
|
51
|
+
- Staff review fix (duplicate import)
|
|
52
|
+
|
|
53
|
+
## Final Statistics
|
|
54
|
+
|
|
55
|
+
- **Total Tests:** 86 passing
|
|
56
|
+
- **Total Commits:** 10 across 4 phases
|
|
57
|
+
- **Package Size:** 23.7 kB (27 files)
|
|
58
|
+
- **Documentation:** README.md, LICENSE, REFLECTIONS.md, DECISIONS.md, PLAN.md
|
|
59
|
+
- **Architecture:** Clean ESM modules with full signal handling
|
|
60
|
+
|
|
61
|
+
## Remaining Items (v0.2 scope)
|
|
62
|
+
|
|
63
|
+
Non-blocking items for future releases:
|
|
64
|
+
- {{FILE_TREE}} placeholder implementation
|
|
65
|
+
- Test gate stub completion
|
|
66
|
+
- Unused config helpers cleanup
|
|
67
|
+
- Box width inconsistency (banner: 60, status: 52)
|
|
68
|
+
- execSync timeout for interactive agent
|
|
69
|
+
- Signal handler race documentation
|
|
70
|
+
|
|
71
|
+
## Release Checklist
|
|
72
|
+
|
|
73
|
+
- [x] All phases complete
|
|
74
|
+
- [x] Tests passing (86/86)
|
|
75
|
+
- [x] Documentation complete
|
|
76
|
+
- [x] npm publish verification passed
|
|
77
|
+
- [ ] Push to remote repository
|
|
78
|
+
- [ ] Publish to npm registry
|
|
79
|
+
- [ ] Test global installation
|
|
80
|
+
|
|
81
|
+
## Next Steps
|
|
82
|
+
|
|
83
|
+
1. **Push to remote:** `git push origin master`
|
|
84
|
+
2. **Publish to npm:** `npm publish`
|
|
85
|
+
3. **Test installation:** `npm install -g cc-pipeline`
|
|
86
|
+
4. **Verify functionality:** `cc-pipeline init && cc-pipeline run`
|
|
87
|
+
|
|
88
|
+
## Build Notes
|
|
89
|
+
|
|
90
|
+
The build was supervised by a BUILD SUPERVISOR subagent that continued from where a previous supervisor hit context limits mid-Phase-2-review. The supervisor successfully:
|
|
91
|
+
|
|
92
|
+
1. Monitored Phase 2 Staff Review completion
|
|
93
|
+
2. Executed Phase 2 Reflection
|
|
94
|
+
3. Completed Phase 3 (CLI Polish & Integration)
|
|
95
|
+
4. Completed Phase 4 (Tests & Documentation)
|
|
96
|
+
5. Ran Staff Engineer Reviews after each phase
|
|
97
|
+
6. Ran Reflections after each phase
|
|
98
|
+
7. Committed all changes systematically
|
|
99
|
+
|
|
100
|
+
Build time: Approximately 3 hours using Claude Code with experimental agent teams feature.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
**Status:** ✅ BUILD COMPLETE - READY FOR RELEASE 🚀
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Tim Johnson
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
# cc-pipeline
|
|
2
|
+
|
|
3
|
+
**Autonomous Claude Code pipeline engine.** Install into any repo, write a BRIEF.md describing your project, and let Claude build it phase by phase.
|
|
4
|
+
|
|
5
|
+
## What Is This?
|
|
6
|
+
|
|
7
|
+
cc-pipeline orchestrates autonomous development workflows using Claude Code. You provide a project vision in plain language, and the pipeline:
|
|
8
|
+
|
|
9
|
+
- Breaks down the vision into phases
|
|
10
|
+
- Plans and implements each phase
|
|
11
|
+
- Runs tests, reviews code, and commits automatically
|
|
12
|
+
- Iterates until the project is complete
|
|
13
|
+
|
|
14
|
+
Think of it as a CI/CD system for AI-driven development—but instead of deploying code, it writes it.
|
|
15
|
+
|
|
16
|
+
## Prerequisites
|
|
17
|
+
|
|
18
|
+
- **Node.js** >=18
|
|
19
|
+
- **Claude CLI** (`claude`) installed and configured ([get it here](https://docs.claude.ai/docs/claude-cli))
|
|
20
|
+
- **tmux** — Required for interactive build/fix steps (Claude runs inside tmux sessions)
|
|
21
|
+
- macOS: `brew install tmux`
|
|
22
|
+
- Ubuntu/Debian: `sudo apt install tmux`
|
|
23
|
+
- Fedora: `sudo dnf install tmux`
|
|
24
|
+
- **git** — For the commit step (you probably already have this)
|
|
25
|
+
|
|
26
|
+
## Installation
|
|
27
|
+
|
|
28
|
+
This package is published to [GitHub Packages](https://github.com/timothyjoh/cc-pipeline/packages). First, configure npm to use the GitHub registry for the `@timothyjoh` scope:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
echo "@timothyjoh:registry=https://npm.pkg.github.com" >> ~/.npmrc
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Then initialize the pipeline in your project:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
cd your-project
|
|
38
|
+
npx @timothyjoh/cc-pipeline@latest init
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
This scaffolds the `.pipeline/` directory, prompt templates, `CLAUDE.md`, and a `BRIEF.md.example` into your project.
|
|
42
|
+
|
|
43
|
+
## Quick Start
|
|
44
|
+
|
|
45
|
+
### 1. Initialize the pipeline
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
cd your-project
|
|
49
|
+
npx @timothyjoh/cc-pipeline@latest init
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### 2. Write your project brief
|
|
53
|
+
|
|
54
|
+
Copy the example and edit it:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
cp BRIEF.md.example BRIEF.md
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Or let Claude Code help you write it — fire up `claude` in your project and ask:
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
Using the @BRIEF.md.example as a template, let's discuss this project's goals
|
|
64
|
+
and write a BRIEF.md. Ask me for a quick description first, then ask questions
|
|
65
|
+
one-at-a-time to build a good brief.
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+

|
|
69
|
+
|
|
70
|
+
### 3. Run the pipeline
|
|
71
|
+
|
|
72
|
+
> **⚠️ Run from a regular terminal, not from inside Claude Code.** The pipeline spawns its own Claude Code sessions in tmux, so running it from within Claude Code would nest sessions — which isn't supported.
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
npx cc-pipeline run
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
That's it. The pipeline will spec, build, review, fix, and commit each phase automatically.
|
|
79
|
+
|
|
80
|
+
### 4. Monitor progress
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
npx cc-pipeline status
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The pipeline also generates a `STATUS.md` at the project root after each phase — a running summary of what's been built, review findings, test coverage, and what's next.
|
|
87
|
+
|
|
88
|
+
## Commands
|
|
89
|
+
|
|
90
|
+
| Command | Description |
|
|
91
|
+
|---------|-------------|
|
|
92
|
+
| `npx @timothyjoh/cc-pipeline@latest init` | Scaffold `.pipeline/`, `CLAUDE.md`, and `BRIEF.md.example` |
|
|
93
|
+
| `npx @timothyjoh/cc-pipeline@latest update` | Refresh prompts and docs (preserves your `workflow.yaml`) |
|
|
94
|
+
| `npx cc-pipeline run [--phases N] [--model NAME]` | Run the pipeline |
|
|
95
|
+
| `npx cc-pipeline status` | Show current phase, step, and recent events |
|
|
96
|
+
| `npx cc-pipeline reset` | Clear event log, phase outputs, and STATUS.md |
|
|
97
|
+
|
|
98
|
+
> **Tip:** Use `@latest` with `init` and `update` to get the newest templates. For `run`, `status`, and `reset`, the cached version is fine.
|
|
99
|
+
|
|
100
|
+
### Run Options
|
|
101
|
+
|
|
102
|
+
- `--phases <n>` — Limit to N phases (useful for testing)
|
|
103
|
+
- `--model <name>` — Override model for all steps (e.g., `opus`, `sonnet`, `haiku`)
|
|
104
|
+
|
|
105
|
+
### Examples
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
npx cc-pipeline run # Run until complete
|
|
109
|
+
npx cc-pipeline run --phases 3 # Run just 3 phases
|
|
110
|
+
npx cc-pipeline run --model opus # Use opus for all steps
|
|
111
|
+
npx cc-pipeline reset # Start over from scratch
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The pipeline resumes from interruptions automatically. Press **Ctrl-C** to pause, then `npx cc-pipeline run` again to continue.
|
|
115
|
+
|
|
116
|
+
## How It Works
|
|
117
|
+
|
|
118
|
+
### Phases
|
|
119
|
+
|
|
120
|
+
The pipeline works in **phases**, each representing a unit of progress (e.g., "user authentication", "payment integration"). Each phase follows the same workflow of steps.
|
|
121
|
+
|
|
122
|
+
### Steps
|
|
123
|
+
|
|
124
|
+
Each phase runs through these steps (defined in `.pipeline/workflow.yaml`):
|
|
125
|
+
|
|
126
|
+
1. **spec** — Break the project vision into a phase spec
|
|
127
|
+
2. **research** — Analyze the current codebase state
|
|
128
|
+
3. **plan** — Create an actionable implementation plan
|
|
129
|
+
4. **build** — Implement the plan (interactive Claude in tmux)
|
|
130
|
+
5. **review** — Staff engineer-level code review
|
|
131
|
+
6. **fix** — Address review findings (skipped if none)
|
|
132
|
+
7. **reflect** — Look back at progress, plan the next phase
|
|
133
|
+
8. **status** — Update `STATUS.md` with build summary, test coverage, and what's next
|
|
134
|
+
9. **commit** — Git commit and push
|
|
135
|
+
|
|
136
|
+
### Agents
|
|
137
|
+
|
|
138
|
+
| Agent | How It Runs | Used For |
|
|
139
|
+
|-------|------------|----------|
|
|
140
|
+
| `claude-piped` | `claude -p "<prompt>"` (non-interactive) | Planning, analysis, reviews, docs |
|
|
141
|
+
| `claude-interactive` | Claude in a tmux session with full tool access | Building code, fixing issues |
|
|
142
|
+
| `bash` | Direct shell command | Git commits, scripts |
|
|
143
|
+
|
|
144
|
+
### State & Resume
|
|
145
|
+
|
|
146
|
+
Pipeline state lives in `.pipeline/pipeline.jsonl` — an append-only event log. The current phase and step are derived from the log, so you can interrupt and resume seamlessly.
|
|
147
|
+
|
|
148
|
+
### Project Completion
|
|
149
|
+
|
|
150
|
+
When Claude determines the project is complete, it writes `PROJECT COMPLETE` in `REFLECTIONS.md`. The pipeline stops automatically.
|
|
151
|
+
|
|
152
|
+
## Configuration
|
|
153
|
+
|
|
154
|
+
Pipeline behavior is controlled by `.pipeline/workflow.yaml`. See `.pipeline/CLAUDE.md` for full configuration docs — how to edit steps, change agents/models, customize prompts, and add new steps.
|
|
155
|
+
|
|
156
|
+
### Quick Examples
|
|
157
|
+
|
|
158
|
+
**Override model per step:**
|
|
159
|
+
```yaml
|
|
160
|
+
steps:
|
|
161
|
+
- name: spec
|
|
162
|
+
agent: claude-piped
|
|
163
|
+
model: sonnet
|
|
164
|
+
prompt: prompts/spec.md
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
**Add conditional execution:**
|
|
168
|
+
```yaml
|
|
169
|
+
- name: fix
|
|
170
|
+
agent: claude-interactive
|
|
171
|
+
prompt: prompts/fix.md
|
|
172
|
+
skip_unless: "MUST-FIX.md" # Only runs if review produced MUST-FIX.md
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
**Customize prompts:** Edit the markdown files in `.pipeline/prompts/` to change how each step behaves.
|
|
176
|
+
|
|
177
|
+
## Example BRIEF.md
|
|
178
|
+
|
|
179
|
+
```markdown
|
|
180
|
+
# Project Brief
|
|
181
|
+
|
|
182
|
+
## Overview
|
|
183
|
+
A command-line task manager with persistent storage.
|
|
184
|
+
|
|
185
|
+
## Tech Stack
|
|
186
|
+
- Node.js + SQLite
|
|
187
|
+
- No external dependencies
|
|
188
|
+
|
|
189
|
+
## Features (Priority Order)
|
|
190
|
+
1. **Add/list/complete tasks** — Core CRUD operations
|
|
191
|
+
2. **Due dates & filtering** — Filter by status, due date
|
|
192
|
+
3. **Tags & search** — Organize and find tasks
|
|
193
|
+
|
|
194
|
+
## Constraints
|
|
195
|
+
- Must work offline
|
|
196
|
+
- Single-file database
|
|
197
|
+
|
|
198
|
+
## Testing
|
|
199
|
+
- Node test runner for unit tests
|
|
200
|
+
- Cover core CRUD operations
|
|
201
|
+
|
|
202
|
+
## Definition of Done
|
|
203
|
+
~3 phases for MVP, complete when all features work with tests passing
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
## Project Structure
|
|
207
|
+
|
|
208
|
+
After initialization and a few phases:
|
|
209
|
+
|
|
210
|
+
```
|
|
211
|
+
your-project/
|
|
212
|
+
├── .pipeline/
|
|
213
|
+
│ ├── CLAUDE.md # Pipeline config docs (for Claude Code)
|
|
214
|
+
│ ├── workflow.yaml # Step definitions, agents, models
|
|
215
|
+
│ ├── pipeline.jsonl # Event log (auto-created on first run)
|
|
216
|
+
│ └── prompts/ # Prompt templates (customizable)
|
|
217
|
+
│ ├── spec.md
|
|
218
|
+
│ ├── research.md
|
|
219
|
+
│ ├── plan.md
|
|
220
|
+
│ ├── build.md
|
|
221
|
+
│ ├── review.md
|
|
222
|
+
│ ├── fix.md
|
|
223
|
+
│ ├── reflect.md
|
|
224
|
+
│ └── status.md
|
|
225
|
+
├── docs/
|
|
226
|
+
│ └── phases/
|
|
227
|
+
│ ├── phase-1/ # Phase artifacts
|
|
228
|
+
│ │ ├── SPEC.md
|
|
229
|
+
│ │ ├── RESEARCH.md
|
|
230
|
+
│ │ ├── PLAN.md
|
|
231
|
+
│ │ ├── REVIEW.md
|
|
232
|
+
│ │ └── REFLECTIONS.md
|
|
233
|
+
│ └── phase-2/
|
|
234
|
+
│ └── ...
|
|
235
|
+
├── BRIEF.md # Your project vision
|
|
236
|
+
├── CLAUDE.md # Project conventions (for Claude Code)
|
|
237
|
+
├── AGENTS.md # Dev docs (created by Phase 1)
|
|
238
|
+
├── STATUS.md # Running build summary (auto-updated)
|
|
239
|
+
└── [your code here]
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
## Troubleshooting
|
|
243
|
+
|
|
244
|
+
**"Claude Code cannot be launched inside another Claude Code session":**
|
|
245
|
+
- Run the pipeline from a regular terminal, not from within Claude Code
|
|
246
|
+
- If you still see this after exiting Claude Code, run: `unset CLAUDECODE` then try again
|
|
247
|
+
|
|
248
|
+
**Build step times out (60s+):**
|
|
249
|
+
- Check [Anthropic's status page](https://status.anthropic.com) — API issues cause slow startups
|
|
250
|
+
- The pipeline will retry on resume: just run `npx cc-pipeline run` again
|
|
251
|
+
|
|
252
|
+
**Pipeline won't start:**
|
|
253
|
+
- Ensure `claude` CLI is installed: `claude --version`
|
|
254
|
+
- Ensure `tmux` is installed: `tmux -V`
|
|
255
|
+
- Run `npx @timothyjoh/cc-pipeline@latest init` if `.pipeline/` doesn't exist
|
|
256
|
+
|
|
257
|
+
**Want to start over:**
|
|
258
|
+
```bash
|
|
259
|
+
npx cc-pipeline reset
|
|
260
|
+
npx cc-pipeline run
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
**Want the latest prompts without losing your workflow.yaml:**
|
|
264
|
+
```bash
|
|
265
|
+
npx @timothyjoh/cc-pipeline@latest update
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
## Development
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
git clone https://github.com/timothyjoh/cc-pipeline.git
|
|
272
|
+
cd cc-pipeline
|
|
273
|
+
npm install
|
|
274
|
+
npm test
|
|
275
|
+
npm link # For local development
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
## License
|
|
279
|
+
|
|
280
|
+
MIT License — see [LICENSE](LICENSE) for details.
|
|
281
|
+
|
|
282
|
+
## Contributing
|
|
283
|
+
|
|
284
|
+
Contributions welcome! Please open an issue or PR on GitHub.
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
Built with [Claude Code](https://docs.claude.ai/docs/claude-cli) by Anthropic.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Agent Teams Research
|
|
2
|
+
|
|
3
|
+
## What Are Agent Teams?
|
|
4
|
+
|
|
5
|
+
Claude Code experimental feature (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) that enables multi-agent parallel execution. Fundamentally different from the Task tool / sub-agents.
|
|
6
|
+
|
|
7
|
+
**Key differences from Task tool sub-agents:**
|
|
8
|
+
- Each teammate gets their own context window
|
|
9
|
+
- Shared task list with dependency tracking and file-lock claiming
|
|
10
|
+
- Inter-agent mailbox (teammates can message each other, not just report to lead)
|
|
11
|
+
- tmux split-pane mode (each teammate visible in its own pane)
|
|
12
|
+
|
|
13
|
+
## Enabling
|
|
14
|
+
|
|
15
|
+
### Option 1: Settings file (recommended, persistent)
|
|
16
|
+
Add to `~/.claude/settings.json`:
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"env": {
|
|
20
|
+
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### Option 2: Environment variable (per-session)
|
|
26
|
+
```bash
|
|
27
|
+
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### Option 3: cc-pipeline sets it automatically
|
|
31
|
+
The pipeline sets the env var in the tmux session before launching Claude.
|
|
32
|
+
|
|
33
|
+
## tmux Control Mode
|
|
34
|
+
|
|
35
|
+
One article reports that agents didn't spawn in separate panes without `tmux -CC` (control mode). Control mode maps tmux panes to native iTerm2 tabs/windows.
|
|
36
|
+
|
|
37
|
+
- `tmux -CC` — control mode, needed for iTerm2 native pane mapping
|
|
38
|
+
- Regular `tmux new-session -d` — may work but panes may not split automatically
|
|
39
|
+
- `--teammate-mode tmux` — Claude Code flag to prefer tmux split panes
|
|
40
|
+
|
|
41
|
+
**TODO:** Test whether `tmux -CC` is actually required or just an iTerm2 preference.
|
|
42
|
+
|
|
43
|
+
## Different Models Per Teammate
|
|
44
|
+
|
|
45
|
+
You can assign different models to each teammate:
|
|
46
|
+
```
|
|
47
|
+
Spawn a team of 3 agents:
|
|
48
|
+
- Agent 1 (opus): Backend implementation
|
|
49
|
+
- Agent 2 (sonnet): Frontend implementation
|
|
50
|
+
- Agent 3 (haiku): Test writing
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**Opportunity for cc-pipeline:** Build prompt could specify model per teammate role:
|
|
54
|
+
- Tester → haiku (cheaper, tests are simpler)
|
|
55
|
+
- Builder → opus (smarter, implementation is harder)
|
|
56
|
+
- Or respect the `--model` flag from the CLI
|
|
57
|
+
|
|
58
|
+
## Token/Cost Considerations
|
|
59
|
+
|
|
60
|
+
- Each teammate has its own context window → multiplies token usage
|
|
61
|
+
- A 3-agent team on a codebase analysis ran ~13 minutes
|
|
62
|
+
- Max plan users report heavy weekly limit impact from intense team runs
|
|
63
|
+
- Monitor with `/usage` command in Claude Code
|
|
64
|
+
|
|
65
|
+
## Architecture Details
|
|
66
|
+
|
|
67
|
+
- Config: `~/.claude/teams/{team-name}/config.json`
|
|
68
|
+
- Tasks: `~/.claude/tasks/{team-name}/`
|
|
69
|
+
- Display modes: in-process (default), split-pane (tmux), auto (detects environment)
|
|
70
|
+
- Setting: `"teammateMode": "tmux"` in settings.json
|
|
71
|
+
|
|
72
|
+
## References
|
|
73
|
+
|
|
74
|
+
- [How to Set Up and Use Claude Code Agent Teams](https://darasoba.medium.com/how-to-set-up-and-use-claude-code-agent-teams-and-actually-get-great-results-9a34f8648f6d) — Darasoba, Feb 7 2026
|
|
75
|
+
- [Claude Code Multi-Agent tmux Setup](https://www.dariuszparys.com/claude-code-multi-agent-tmux-setup/) — Dariusz Parys, Feb 2026
|
|
76
|
+
|
|
77
|
+
## Open Questions / TODOs
|
|
78
|
+
|
|
79
|
+
- [ ] Test `tmux -CC` vs regular tmux — is control mode required for pane splitting?
|
|
80
|
+
- [ ] Test settings.json approach vs env var — which is more reliable?
|
|
81
|
+
- [ ] Experiment with model-per-teammate in build prompt (haiku for tests, opus for code)
|
|
82
|
+
- [ ] Investigate `--teammate-mode tmux` flag — can we pass it when launching Claude?
|
|
83
|
+
- [ ] Measure token usage difference: solo build vs agent team build
|
|
84
|
+
- [ ] Check if agent teams work with `--dangerously-skip-permissions`
|
package/docs/IDEAS.md
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# IDEAS.md — Future Enhancements
|
|
2
|
+
|
|
3
|
+
## Contract-First Plan→Build Handoff
|
|
4
|
+
**Source:** Cole Medin's "Agent Teams" video (Feb 2026)
|
|
5
|
+
|
|
6
|
+
Currently the plan step outputs a task list. Instead, have it output **explicit API contracts and schemas** — function signatures, data structures, file boundaries — before the build step spawns parallel agents. This way agents can integrate without reading each other's code.
|
|
7
|
+
|
|
8
|
+
**Implementation:** Add a `contracts` section to PLAN.md template. The plan prompt should require: "Define the API contract between modules — function signatures, expected inputs/outputs, shared data structures. Each build agent receives these contracts as context."
|
|
9
|
+
|
|
10
|
+
**Why it matters:** The #1 failure mode in parallel agent builds is integration conflicts. Contract-first eliminates this by agreement-before-implementation.
|
|
11
|
+
|
|
12
|
+
## Structured Pre-Flight Questions
|
|
13
|
+
**Source:** Cole Medin
|
|
14
|
+
|
|
15
|
+
Before the spec step, force the agent to generate 10-15 clarifying questions about the BRIEF.md, then answer them from context. Catches ambiguity early instead of mid-build.
|
|
16
|
+
|
|
17
|
+
**Where it fits:** Could be a new `clarify` step before `spec`, or baked into the spec prompt itself.
|
|
18
|
+
|
|
19
|
+
## Autonomous Validation Loop
|
|
20
|
+
**Source:** Cole Medin
|
|
21
|
+
|
|
22
|
+
After build/fix, add a validation loop: agent runs tests → finds bugs → fixes → re-runs tests → repeats until clean. Currently we do review→fix as separate steps with a human-like handoff. An autonomous loop would be tighter.
|
|
23
|
+
|
|
24
|
+
**Where it fits:** Could replace or augment the review→fix→reflect sequence with a `validate` step that loops internally.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# System Prompts Research
|
|
2
|
+
|
|
3
|
+
Analysis of leaked system prompts from major AI coding tools.
|
|
4
|
+
Source: https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools (110K+ stars)
|
|
5
|
+
|
|
6
|
+
## Key Patterns Worth Stealing
|
|
7
|
+
|
|
8
|
+
### 1. TodoWrite / Task Tracking (Claude Code, Cursor)
|
|
9
|
+
Both Claude Code and Cursor heavily emphasize TODO tracking during execution:
|
|
10
|
+
- "Use TodoWrite tools VERY frequently to ensure you are tracking tasks"
|
|
11
|
+
- "Mark todos as completed as soon as you are done — do not batch"
|
|
12
|
+
- Cursor uses `todo_write` with `merge=true` to reconcile before every edit
|
|
13
|
+
|
|
14
|
+
**Relevance to cc-pipeline:** Our build prompt could tell the team lead to use TodoWrite to track teammate progress. Currently we just say "orchestrate" — this is more specific.
|
|
15
|
+
|
|
16
|
+
### 2. Think Tool / Reasoning (Devin)
|
|
17
|
+
Devin has an explicit `<think>` scratchpad that's mandatory before:
|
|
18
|
+
- Critical git decisions
|
|
19
|
+
- Transitioning from exploring to editing
|
|
20
|
+
- Reporting completion (must "critically examine" work before claiming done)
|
|
21
|
+
- After test/CI failures (think big picture before diving into fixes)
|
|
22
|
+
|
|
23
|
+
**Relevance:** Our review/reflect prompts could benefit from explicit "think before acting" instructions.
|
|
24
|
+
|
|
25
|
+
### 3. Parallel Tool Calls (Cursor)
|
|
26
|
+
Cursor is aggressive about parallelism:
|
|
27
|
+
- "DEFAULT TO PARALLEL unless output of A required for input of B"
|
|
28
|
+
- "Parallel tool execution can be 3-5x faster"
|
|
29
|
+
- Batch read-only operations, independent edits
|
|
30
|
+
- "Limit to 3-5 tool calls at a time or they might time out"
|
|
31
|
+
|
|
32
|
+
**Relevance:** Our agent teams already parallelize at the teammate level, but the build prompt could encourage parallel tool calls within each teammate too.
|
|
33
|
+
|
|
34
|
+
### 4. Code Conventions First (All)
|
|
35
|
+
Universal pattern across Claude Code, Cursor, Devin, Windsurf:
|
|
36
|
+
- "First understand the file's code conventions"
|
|
37
|
+
- "NEVER assume a library is available — check package.json first"
|
|
38
|
+
- "Look at neighboring files, mimic code style"
|
|
39
|
+
- "When you create a new component, first look at existing components"
|
|
40
|
+
|
|
41
|
+
**Relevance:** Our research step already does this, but the build prompt should reinforce "follow patterns from RESEARCH.md."
|
|
42
|
+
|
|
43
|
+
### 5. No Comments Unless Asked (Claude Code, Devin)
|
|
44
|
+
- Claude Code: "IMPORTANT: DO NOT ADD ANY COMMENTS unless asked"
|
|
45
|
+
- Devin: "Do not add comments to the code you write, unless the user asks"
|
|
46
|
+
|
|
47
|
+
**Relevance:** Could add this to our build prompt — AI-generated comments are usually noise.
|
|
48
|
+
|
|
49
|
+
### 6. Concise Output (Claude Code)
|
|
50
|
+
Claude Code is extremely aggressive about brevity:
|
|
51
|
+
- "Fewer than 4 lines unless user asks for detail"
|
|
52
|
+
- "Minimize output tokens as much as possible"
|
|
53
|
+
- "One word answers are best"
|
|
54
|
+
- "NEVER add unnecessary preamble or postamble"
|
|
55
|
+
|
|
56
|
+
**Relevance:** Our piped steps (spec, plan, review) want detailed output, but the build step should be concise — focus on coding, not explaining.
|
|
57
|
+
|
|
58
|
+
### 7. Verify Before Claiming Done (Claude Code, Devin, Cursor)
|
|
59
|
+
- Claude Code: "Run lint and typecheck commands when completed"
|
|
60
|
+
- Devin: "Critically examine your work before reporting completion"
|
|
61
|
+
- Cursor: "Gate before new edits — reconcile TODO list"
|
|
62
|
+
|
|
63
|
+
**Relevance:** Our build prompt has quality gates but could be more emphatic. The review step catches issues, but catching them in build is cheaper.
|
|
64
|
+
|
|
65
|
+
### 8. Never Commit Unless Asked (Claude Code)
|
|
66
|
+
- "NEVER commit changes unless the user explicitly asks"
|
|
67
|
+
|
|
68
|
+
**Relevance:** Our pipeline has a dedicated commit step, so this is handled architecturally. Good validation of our approach.
|
|
69
|
+
|
|
70
|
+
## Interesting Architectural Differences
|
|
71
|
+
|
|
72
|
+
| Tool | Planning | Execution | Review |
|
|
73
|
+
|------|----------|-----------|--------|
|
|
74
|
+
| Claude Code | TodoWrite | Sequential + Task tool | Lint/typecheck |
|
|
75
|
+
| Cursor | todo_write with merge | Parallel tool calls | Summary spec |
|
|
76
|
+
| Devin | Explicit plan mode | Standard mode with think gates | CI-based |
|
|
77
|
+
| Windsurf | Inline | Sequential | Terminal run |
|
|
78
|
+
| cc-pipeline | Separate spec/plan steps | Agent teams (parallel) | Dedicated review step |
|
|
79
|
+
|
|
80
|
+
Our pipeline's separated planning → building → reviewing is more structured than any of these. They all do it in one session. That's our advantage for larger projects.
|
|
81
|
+
|
|
82
|
+
## TODO
|
|
83
|
+
- [ ] Add "no comments unless asked" to build prompt
|
|
84
|
+
- [ ] Add TodoWrite encouragement to build prompt for team lead task tracking
|
|
85
|
+
- [ ] Consider adding "think before acting" gate to fix prompt (Devin pattern)
|
|
86
|
+
- [ ] Test whether explicit "run lint/typecheck" instruction in build prompt catches more issues before review
|
|
Binary file
|
package/package.json
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "cc-pipeline",
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "Autonomous Claude Code pipeline engine. Install into any repo, write a BRIEF.md, and let Claude build your project phase by phase.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"cc-pipeline": "bin/cc-pipeline.js"
|
|
8
|
+
},
|
|
9
|
+
"scripts": {
|
|
10
|
+
"test": "node --test src/**/*.test.js"
|
|
11
|
+
},
|
|
12
|
+
"repository": {
|
|
13
|
+
"type": "git",
|
|
14
|
+
"url": "git+https://github.com/timothyjoh/cc-pipeline.git"
|
|
15
|
+
},
|
|
16
|
+
"bugs": {
|
|
17
|
+
"url": "https://github.com/timothyjoh/cc-pipeline/issues"
|
|
18
|
+
},
|
|
19
|
+
"homepage": "https://github.com/timothyjoh/cc-pipeline#readme",
|
|
20
|
+
"keywords": [
|
|
21
|
+
"claude",
|
|
22
|
+
"claude-code",
|
|
23
|
+
"pipeline",
|
|
24
|
+
"ai",
|
|
25
|
+
"autonomous",
|
|
26
|
+
"code-generation"
|
|
27
|
+
],
|
|
28
|
+
"author": "Tim Johnson",
|
|
29
|
+
"license": "MIT",
|
|
30
|
+
"engines": {
|
|
31
|
+
"node": ">=18"
|
|
32
|
+
},
|
|
33
|
+
"dependencies": {
|
|
34
|
+
"yaml": "^2.7.0"
|
|
35
|
+
}
|
|
36
|
+
}
|