New Tool Kickoff
A structured workflow for turning a tool idea into a working MVP. Covers the full cycle: research existing solutions, brainstorm approach, write a plan, scaffold the project, build core features, and write documentation.
When to Use
- User says "I have an idea for a tool/CLI/library"
- User wants to start a new project from scratch
- User wants to research feasibility before building
- Greenfield development of a focused tool or CLI
Workflow
Phase 1: Research (Stop point: get user approval before Phase 2)
Goal: Understand the landscape before building.
- Clarify the idea: Ask what problem the tool solves, who uses it, and what the core workflow looks like
- Search for existing tools: Web search for similar tools, libraries, or CLIs
- Evaluate alternatives: For each existing tool found:
- What does it do well? - What gaps or limitations does it have? - Is it actively maintained?
- API/Integration research: If the tool integrates with external services, research their APIs:
- Authentication methods - Rate limits and pagination - Data models and available endpoints
- Present findings: Summarize as a brief landscape overview:
- Existing tools and their limitations - API capabilities (if applicable) - Recommended approach based on findings
Ask the user: "Based on this research, should we proceed with building? Any adjustments to the concept?"
Phase 2: Brainstorm & Design (Stop point: get user approval before Phase 3)
Goal: Nail down the approach before writing code.
- Core features: Identify the minimum set of features for a useful v1
- Technology choices: Recommend language, frameworks, and key dependencies based on:
- User's preferences and existing projects - Tool requirements (CLI, TUI, web, library) - Available ecosystem (Go for CLI tools, TypeScript for Node ecosystem, etc.)
- Interface design: Define the user-facing interface:
- CLI: command structure, flags, arguments - Library: public API surface - TUI: key bindings, views
- Architecture sketch: High-level component breakdown (keep it simple — avoid over-engineering)
- Name the project: Suggest a name if the user hasn't chosen one (or invoke the
project-namerskill)
Ask the user: "Here's the proposed design. What adjustments?"
Phase 3: Plan
Goal: Create an executable implementation plan.
- Write a plan file to the repo (
.claude/plans/[project-name].mdor a location the user specifies) - The plan should include:
- Goal: One-sentence summary - Scope: What's in v1, what's deferred - Steps: Numbered implementation steps with clear deliverables - File structure: Expected project layout - Dependencies: Key libraries to use - Test strategy: What to test and how
- Keep the plan concise — under 100 lines. The plan is a contract, not a design doc.
Ask the user: "Plan is ready. Proceed with implementation?"
Phase 4: Scaffold & Build
Goal: Get to a working MVP.
- Initialize project:
- Create directory structure - Initialize module/package (go mod init, npm init, etc.) - Set up linting and formatting config - Create.gitignore
- Implement core features: Work through plan steps in order
- Write tests alongside implementation (not after) - Commit at logical checkpoints - If a step gets complex, break it down further
- Verify: Run the full test suite, lint, and build before moving on
Phase 5: Polish & Document
Goal: Make the tool usable by others.
- README: Write a README with:
- Clear description and tagline - Installation instructions - Quick start / usage examples - Configuration reference (if applicable)
- CLI help: Ensure all commands have proper help text and examples
- License: Add an appropriate license file (default: MIT unless user specifies)
- Final review: Run a quick scan:
- go vet / eslint / equivalent for the language - Check for hardcoded paths or secrets - Verify README matches actual CLI interface
Adapting the Workflow
- If the user already researched: Skip Phase 1, start at Phase 2
- If the user has a plan: Skip to Phase 4
- If the user wants just research: Stop after Phase 1
- If adding to existing project: Skip scaffolding in Phase 4, focus on the new feature
Tips
- Prefer simplicity in v1. The user can always add features later.
- For CLI tools, the user prefers Go with cobra/viper patterns.
- Always verify with web search before recommending libraries — check for maintenance status and compatibility.
- Use conventional commits during implementation.
- Don't over-engineer: no feature flags, no plugin systems, no config file formats beyond what's needed for v1.
Examples
Example 1: CLI tool from idea
User: "I want to build a CLI tool for Slack using Go"
Action:
1. Research existing Slack CLI tools (slackcli, etc.)
2. Research Slack API capabilities
3. Brainstorm: core commands (messages, channels, search)
4. Plan: write implementation plan
5. Build: scaffold Go project, implement core commands
6. Document: write README with install + usageExample 2: Research only
User: "I'm thinking of creating some linter. Research if there's anything similar."
Action:
1. Search for existing linters in the relevant space
2. Compare features, limitations, maintenance status
3. Present findings and recommendation
4. Stop — wait for user to decide next stepsExample 3: Tool with external API
User: "I want to create a Fireflies CLI"
Action:
1. Research Fireflies API docs, authentication, endpoints
2. Research existing Fireflies integrations
3. Design: core features (list meetings, get transcript, action items)
4. Plan and build with API client as foundation