dev-new-tool

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.

1. Clarify the idea: Ask what problem the tool solves, who uses it, and what the core workflow looks like
2. Search for existing tools: Web search for similar tools, libraries, or CLIs
3. Evaluate alternatives: For each existing tool found:
   • What does it do well?
   • What gaps or limitations does it have?
   • Is it actively maintained?
4. API/Integration research: If the tool integrates with external services, research their APIs:
   • Authentication methods
   • Rate limits and pagination
   • Data models and available endpoints
5. 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.

1. Core features: Identify the minimum set of features for a useful v1
2. 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.)
3. Interface design: Define the user-facing interface:
   • CLI: command structure, flags, arguments
   • Library: public API surface
   • TUI: key bindings, views
4. Architecture sketch: High-level component breakdown (keep it simple — avoid over-engineering)
5. Name the project: Suggest a name if the user hasn't chosen one (or invoke the project-namer skill)

Ask the user: "Here's the proposed design. What adjustments?"

Phase 3: Plan

Goal: Create an executable implementation plan.

1. Write a plan file to the repo (.claude/plans/[project-name].md or a location the user specifies)
2. 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
3. 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.

1. Initialize project:
   • Create directory structure
   • Initialize module/package (go mod init, npm init, etc.)
   • Set up linting and formatting config
   • Create .gitignore
2. 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
3. Verify: Run the full test suite, lint, and build before moving on

Phase 5: Polish & Document

Goal: Make the tool usable by others.

1. README: Write a README with:
   • Clear description and tagline
   • Installation instructions
   • Quick start / usage examples
   • Configuration reference (if applicable)
2. CLI help: Ensure all commands have proper help text and examples
3. License: Add an appropriate license file (default: MIT unless user specifies)
4. 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 + usage

Example 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 steps

Example 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