CLI Tool Builder — CLI Tool Development Pipeline
An agent team collaborates to develop CLI tools through command design > parser implementation > handlers > testing > documentation > deployment.
Execution Mode
Agent Team — Five agents communicate directly via SendMessage and perform cross-validation.
Agent Composition
| Agent |
File |
Role |
Type |
| command-designer |
.claude/agents/command-designer.md |
Command structure design |
general-purpose |
| core-developer |
.claude/agents/core-developer.md |
Core implementation |
general-purpose |
| test-engineer |
.claude/agents/test-engineer.md |
Test writing |
general-purpose |
| docs-writer |
.claude/agents/docs-writer.md |
Documentation writing |
general-purpose |
| release-engineer |
.claude/agents/release-engineer.md |
Build, deployment |
general-purpose |
Workflow
Phase 1: Preparation (performed directly by the orchestrator)
- Extract the following from user input:
- Tool purpose: What the CLI does
- Language/Runtime: Python/Node.js/Go/Rust (default: Python)
- Key features: List of core subcommands
- Distribution channel: PyPI/npm/Homebrew/binary
- Constraints (optional): Dependency limitations, compatible OS, performance requirements
- Create the
_workspace/ directory at the project root
- Organize the input and save it to
_workspace/00_input.md
- Create the
_workspace/src/ directory
- If pre-existing files are available, copy them to
_workspace/ and skip the corresponding phase
- Determine the execution mode based on the scope of the request
Phase 2: Team Assembly and Execution
| Order |
Task |
Owner |
Dependencies |
Deliverable |
| 1 |
Command structure design |
designer |
None |
_workspace/01_command_design.md |
| 2 |
Core implementation |
developer |
Task 1 |
_workspace/02_core_implementation.md + src/ |
| 3a |
Test writing |
tester |
Task 2 |
_workspace/03_test_suite.md + src/tests/ |
| 3b |
Documentation |
docs |
Tasks 1, 2 |
_workspace/04_documentation.md |
| 4 |
Release configuration |
release |
Tasks 2, 3a |
_workspace/05_release_config.md + CI files |
Tasks 3a (testing) and 3b (documentation) run in parallel.
Inter-agent communication flow:
- designer completes > passes command schema to developer, passes --help drafts to docs
- developer completes > passes mock points to tester, passes API to docs, passes build info to release
- tester completes > passes bug reports to developer (if any), passes CI test config to release
- docs completes > passes README path to release
- release integrates all deliverables to complete the deployment pipeline
Phase 3: Integration and Final Deliverables
- Verify that the code in
_workspace/src/ is executable
- Verify that tests pass
- Validate consistency between documentation and code
- Report the final summary to the user
Execution Modes by Request Scope
| User Request Pattern |
Execution Mode |
Agents Deployed |
| "Build me a CLI tool", "full development" |
Full pipeline |
All 5 agents |
| "Just design the command structure" |
Design mode |
designer only |
| "Add a subcommand to this CLI" |
Extension mode |
designer + developer + tester |
| "Write tests for this CLI" |
Test mode |
tester only |
| "Just set up deployment" |
Deploy mode |
release only |
Data Transfer Protocol
| Strategy |
Method |
Purpose |
| File-based |
_workspace/ directory |
Design documents and configuration sharing |
| Message-based |
SendMessage |
Real-time key information transfer, bug reports |
| Code-based |
_workspace/src/ |
Executable source code |
Error Handling
| Error Type |
Strategy |
| Tool purpose unclear |
Research similar CLI tools via WebSearch, propose 3 candidates |
| Language not specified |
Default to Python (typer), state reasoning and alternatives |
| Test failure |
Send bug report to developer, retest after fix (up to 2 rounds) |
| Cross-platform build failure |
Switch affected OS build to CI-only, present local build alternatives |
| Agent failure |
Retry once > if still failing, proceed without that deliverable |
Test Scenarios
Normal Flow
Prompt: "Build a file conversion CLI tool in Python. Support JSON/YAML/TOML conversion"
Expected result:
- Command design:
convert [input] --from json --to yaml --output out.yaml
- Core: typer-based, parser + conversion logic + output formatter
- Testing: Each conversion combination, invalid format input, pipe input
- Documentation: README + installation + quick start + full command reference
- Release: pyproject.toml + GitHub Actions CI + PyPI deployment
Existing File Reuse Flow
Prompt: "Just add tests and docs to this CLI code" + CLI source code attached
Expected result:
- Copy existing source code to
_workspace/src/
- Skip designer and developer; deploy tester + docs + release
- Analyze existing code's command structure to generate tests and documentation
Error Flow
Prompt: "Build me a CLI" (purpose unclear)
Expected result:
- designer requests tool purpose clarification from user
- Present 3 examples of similar popular CLI tools
- Proceed with remaining pipeline after purpose is confirmed
Agent Extension Skills
Extension skills that enhance agent domain expertise:
| Skill |
File |
Target Agent |
Role |
| arg-parser-generator |
.claude/skills/arg-parser-generator/skill.md |
command-designer, core-developer |
Argument type classification, subcommand patterns, per-language parser boilerplate, help text standard |
| ux-linter |
.claude/skills/ux-linter/skill.md |
test-engineer, docs-writer |
CLI UX 12 principles, error message standards, output format guide, color/interaction patterns |
1---2name: cli-tool-builder3description: Full pipeline where an agent team collaborates to develop a CLI tool. Use this skill for requests like 'build me a CLI tool', 'command-line tool development', 'CLI utility', 'terminal tool', 'command-line program', 'CLI app build', 'shell tool development', and other CLI tool development tasks. Also supports design-only mode when only command design is needed. Note: GUI app development, web dashboard construction, and IDE plugin development are outside the scope of this skill.4---56# CLI Tool Builder — CLI Tool Development Pipeline78An agent team collaborates to develop CLI tools through command design > parser implementation > handlers > testing > documentation > deployment.910## Execution Mode1112**Agent Team** — Five agents communicate directly via SendMessage and perform cross-validation.1314## Agent Composition1516| Agent | File | Role | Type |17|-------|------|------|------|18| command-designer | `.claude/agents/command-designer.md` | Command structure design | general-purpose |19| core-developer | `.claude/agents/core-developer.md` | Core implementation | general-purpose |20| test-engineer | `.claude/agents/test-engineer.md` | Test writing | general-purpose |21| docs-writer | `.claude/agents/docs-writer.md` | Documentation writing | general-purpose |22| release-engineer | `.claude/agents/release-engineer.md` | Build, deployment | general-purpose |2324## Workflow2526### Phase 1: Preparation (performed directly by the orchestrator)27281. Extract the following from user input:29 - **Tool purpose**: What the CLI does30 - **Language/Runtime**: Python/Node.js/Go/Rust (default: Python)31 - **Key features**: List of core subcommands32 - **Distribution channel**: PyPI/npm/Homebrew/binary33 - **Constraints** (optional): Dependency limitations, compatible OS, performance requirements342. Create the `_workspace/` directory at the project root353. Organize the input and save it to `_workspace/00_input.md`364. Create the `_workspace/src/` directory375. If pre-existing files are available, copy them to `_workspace/` and skip the corresponding phase386. **Determine the execution mode** based on the scope of the request3940### Phase 2: Team Assembly and Execution4142| Order | Task | Owner | Dependencies | Deliverable |43|-------|------|-------|-------------|-------------|44| 1 | Command structure design | designer | None | `_workspace/01_command_design.md` |45| 2 | Core implementation | developer | Task 1 | `_workspace/02_core_implementation.md` + `src/` |46| 3a | Test writing | tester | Task 2 | `_workspace/03_test_suite.md` + `src/tests/` |47| 3b | Documentation | docs | Tasks 1, 2 | `_workspace/04_documentation.md` |48| 4 | Release configuration | release | Tasks 2, 3a | `_workspace/05_release_config.md` + CI files |4950Tasks 3a (testing) and 3b (documentation) run **in parallel**.5152**Inter-agent communication flow:**53- designer completes > passes command schema to developer, passes --help drafts to docs54- developer completes > passes mock points to tester, passes API to docs, passes build info to release55- tester completes > passes bug reports to developer (if any), passes CI test config to release56- docs completes > passes README path to release57- release integrates all deliverables to complete the deployment pipeline5859### Phase 3: Integration and Final Deliverables60611. Verify that the code in `_workspace/src/` is executable622. Verify that tests pass633. Validate consistency between documentation and code644. Report the final summary to the user6566## Execution Modes by Request Scope6768| User Request Pattern | Execution Mode | Agents Deployed |69|---------------------|---------------|----------------|70| "Build me a CLI tool", "full development" | **Full pipeline** | All 5 agents |71| "Just design the command structure" | **Design mode** | designer only |72| "Add a subcommand to this CLI" | **Extension mode** | designer + developer + tester |73| "Write tests for this CLI" | **Test mode** | tester only |74| "Just set up deployment" | **Deploy mode** | release only |7576## Data Transfer Protocol7778| Strategy | Method | Purpose |79|----------|--------|---------|80| File-based | `_workspace/` directory | Design documents and configuration sharing |81| Message-based | SendMessage | Real-time key information transfer, bug reports |82| Code-based | `_workspace/src/` | Executable source code |8384## Error Handling8586| Error Type | Strategy |87|-----------|----------|88| Tool purpose unclear | Research similar CLI tools via WebSearch, propose 3 candidates |89| Language not specified | Default to Python (typer), state reasoning and alternatives |90| Test failure | Send bug report to developer, retest after fix (up to 2 rounds) |91| Cross-platform build failure | Switch affected OS build to CI-only, present local build alternatives |92| Agent failure | Retry once > if still failing, proceed without that deliverable |9394## Test Scenarios9596### Normal Flow97**Prompt**: "Build a file conversion CLI tool in Python. Support JSON/YAML/TOML conversion"98**Expected result**:99- Command design: `convert [input] --from json --to yaml --output out.yaml`100- Core: typer-based, parser + conversion logic + output formatter101- Testing: Each conversion combination, invalid format input, pipe input102- Documentation: README + installation + quick start + full command reference103- Release: pyproject.toml + GitHub Actions CI + PyPI deployment104105### Existing File Reuse Flow106**Prompt**: "Just add tests and docs to this CLI code" + CLI source code attached107**Expected result**:108- Copy existing source code to `_workspace/src/`109- Skip designer and developer; deploy tester + docs + release110- Analyze existing code's command structure to generate tests and documentation111112### Error Flow113**Prompt**: "Build me a CLI" (purpose unclear)114**Expected result**:115- designer requests tool purpose clarification from user116- Present 3 examples of similar popular CLI tools117- Proceed with remaining pipeline after purpose is confirmed118119## Agent Extension Skills120121Extension skills that enhance agent domain expertise:122123| Skill | File | Target Agent | Role |124|-------|------|-------------|------|125| arg-parser-generator | `.claude/skills/arg-parser-generator/skill.md` | command-designer, core-developer | Argument type classification, subcommand patterns, per-language parser boilerplate, help text standard |126| ux-linter | `.claude/skills/ux-linter/skill.md` | test-engineer, docs-writer | CLI UX 12 principles, error message standards, output format guide, color/interaction patterns |
revfactory