ccsetup 1.1.0 → 1.1.1

package/README.md

@@ -48,7 +48,9 @@ Examples:
 ## What's Included
 
 The boilerplate template creates:
+
 - **CLAUDE.md** - Project instructions for Claude
+- **GEMINI.md** - (Optional) Waterfall Architect prompt for comprehensive task planning - optimized for Gemini's larger context window
 - **agents/** - Specialized AI agents (planner, coder, checker, etc.)
 - **tickets/** - Task tracking system
 - **plans/** - Project planning documents
@@ -76,6 +78,7 @@ The boilerplate template creates:
 ## Usage
 
 1. Create a new project:
+
    ```bash
    npx ccsetup my-awesome-project
    cd my-awesome-project
@@ -103,21 +106,26 @@ When running in the current directory (`npx ccsetup .`), it will check for Claud
 The boilerplate includes 50+ specialized agents covering all aspects of development:
 
 ### Core Development Agents
+
 - **planner.md** - Strategic planning and task breakdown
 - **coder.md** - Implementation and development
 - **checker.md** - Testing and quality assurance
 - **researcher.md** - Research and information gathering
 
 ### Language Specialists
+
 - **python-pro.md**, **golang-pro.md**, **rust-pro.md**, **javascript-pro.md**, **c-pro.md**, **cpp-pro.md**, **sql-pro.md**
 
 ### Infrastructure & Operations
+
 - **devops-troubleshooter.md**, **cloud-architect.md**, **terraform-specialist.md**, **database-admin.md**, **network-engineer.md**
 
 ### Quality & Security
+
 - **code-reviewer.md**, **security-auditor.md**, **test-automator.md**, **performance-engineer.md**
 
 ### And Many More!
+
 Over 50 specialized agents for frontend, backend, blockchain, ML/AI, business analysis, and more!
 
 📖 **[View all agents with detailed descriptions →](https://github.com/MrMarciaOng/ccsetup/blob/main/template/agents/README.md)**
@@ -155,11 +163,13 @@ Choose your agents:
 ```
 
 You can also use flags to control agent selection:
+
 - `--all-agents` - Include all available agents
 - `--no-agents` - Skip agent selection entirely
 - `--agents` - Preview available agents without creating a project
 
 Example:
+
 ```bash
 # Include all agents without prompting
 npx ccsetup my-project --all-agents
@@ -181,12 +191,14 @@ npx ccsetup my-project --browse-agents
 ```
 
 In browse mode:
+
 - All 50+ agents are copied to your project's `/agents` folder
 - You can read through each agent to understand their capabilities
 - Manually copy the ones you want to `~/.claude/agents` when ready
 - No overwhelming selection process during setup!
 
 Example workflow:
+
 ```bash
 # 1. Create project with browse mode
 npx ccsetup my-project --browse-agents
@@ -204,6 +216,7 @@ cp python-pro.md ~/.claude/agents/
 ```
 
 This approach is perfect when you:
+
 - Want to explore all available agents
 - Prefer to choose agents based on your project needs as they arise
 - Don't want to be overwhelmed with 50+ choices during setup
@@ -223,10 +236,11 @@ Conflict resolution options:
   2) rename    (r) - Save template files with -ccsetup suffix
   3) overwrite (o) - Replace with template versions
 
-Your choice for CLAUDE.md [s/r/o]: 
+Your choice for CLAUDE.md [s/r/o]:
 ```
 
 Categories are handled separately:
+
 - **CLAUDE.md** - Project instructions (warns before overwriting)
 - **Agents** - AI agent files
 - **Documentation** - docs/ folder files
@@ -313,11 +327,13 @@ The template includes powerful agent orchestration workflows that guide Claude t
 ### 💡 How to Use Agent Orchestration
 
 1. **Read the orchestration guide**:
+
    ```
    "Read docs/agent-orchestration.md to understand available workflows"
    ```
 
 2. **Choose your workflow**:
+
    - Feature Development: Complex new features
    - Bug Fix: Investigating and fixing issues
    - Refactoring: Improving code quality
@@ -327,6 +343,7 @@ The template includes powerful agent orchestration workflows that guide Claude t
    - QA: Quality assurance
 
 3. **Let Claude guide you**:
+
    ```
    "I need to [your task]. Which workflow should we use?"
    ```
@@ -343,24 +360,28 @@ The orchestration ensures nothing is missed and follows best practices automatic
 After setting up your project with `ccsetup`:
 
 1. **Open Claude Code** in your project directory:
+
    ```bash
    cd my-awesome-project
    claude
    ```
 
 2. **Let Claude understand your project** by asking:
+
    - "Read the CLAUDE.md file to understand this project"
    - "Check the roadmap in docs/ROADMAP.md"
    - "What agents are available in the agents directory?"
    - "Read the README files in docs, tickets, and plans folders to understand the workflow"
 
 3. **Start working** with Claude:
+
    - Use the planner agent: "Use the planner agent to help me design a user authentication system"
    - Create tickets: "Create a ticket for implementing user login"
    - Implement features: "Use the coder agent to implement the login functionality"
    - Review code: "Use the checker agent to review the code we just wrote"
 
 4. **Important setup steps**:
+
    - **Update ROADMAP.md**: Define your project's goals, features, and development phases
    - **Read folder documentation**: Each folder (docs/, tickets/, plans/) has a README explaining its purpose and format
    - **Customize CLAUDE.md**: Add project-specific instructions, commands, and context
@@ -375,6 +396,7 @@ After setting up your project with `ccsetup`:
 ## Features
 
 ### Core Features
+
 - ✅ Pre-configured project structure for Claude Code
 - 🤖 50+ specialized agents from the [wshobson/agents](https://github.com/wshobson/agents) collection - [view all →](https://github.com/MrMarciaOng/ccsetup/blob/main/template/agents/README.md)
 - 🎫 Built-in ticket and planning system
@@ -382,6 +404,7 @@ After setting up your project with `ccsetup`:
 - 📁 Automatic .claude directory integration
 
 ### CLI Features
+
 - 🎯 Interactive agent selection with descriptions
 - 🔄 Smart conflict resolution (skip/rename/overwrite)
 - 👀 Dry-run mode to preview changes
@@ -390,7 +413,9 @@ After setting up your project with `ccsetup`:
 - 🛡️ Security validations for file operations
 
 ### Agent Orchestration
+
 The template includes `docs/agent-orchestration.md` which defines workflows for:
+
 - **Feature Development** - Researcher → Planner → Coder → Checker
 - **Bug Fixes** - Researcher → Coder → Checker
 - **Refactoring** - Researcher → Planner → Coder → Checker
@@ -407,4 +432,4 @@ The 44 specialized agents collection is from [wshobson/agents](https://github.co
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccsetup",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Boilerplate for Claude Code projects with 50+ agents, tickets, plans, agent orchestration, and browse mode",
   "bin": {
     "ccsetup": "bin/create-project.js"

package/template/GEMINI.md

@@ -0,0 +1,126 @@
+# Persona: The Waterfall Architect
+
+You are a **Senior Technical Product Manager** and **Solution Architect**, referred to as "The Architect." Your primary directive is to translate high-level feature requests into a master plan composed of atomic, sequential, and deeply detailed task specifications. You operate with a strict **waterfall methodology**. The master plan must be so comprehensive that it can be handed off to a third-party development house for implementation with zero ambiguity.
+
+## Core Directives
+
+1.  **Total Context Awareness**: Before planning, you must achieve complete situational awareness of the project. Your first action for any new feature is to read and fully comprehend the entire technical landscape. This includes:
+    *   **The Entire Codebase**: Recursively read all source files (`.go`, `.py`, `.ts`, etc.).
+    *   **All Documentation**: Read all files in the `docs/` directory and any other `.md` files.
+    *   **All Configurations**: Read all project configuration files (`.toml`, `.yaml`, `go.mod`, `package.json`, etc.).
+    *   **Architectural Reality**: Synthesize this information to understand the project's true architecture, including:
+        *   **Software Engineering Patterns**: CQRS (Command Query Responsibility Segregation), Event Sourcing, Domain-Driven Design, etc.
+        *   **Technology Choices**: 
+            *   **Message Queue**: Watermill (Go), FastStream (Python), or other event streaming platforms
+            *   **Database**: ScyllaDB, PostgreSQL, Redis, etc.
+            *   **Frameworks**: FastAPI (Python), Gin/Echo (Go), Express/NestJS (TypeScript)
+        *   **Critical Constraints**: 
+            *   **ScyllaDB Tablet Mode**: Does NOT support indexes, materialized views, or filters on non-primary key columns. This requires:
+                *   Creating dedicated lookup tables for each query pattern
+                *   Keeping lookup tables synchronized with main tables
+                *   Using batch operations or event-driven updates for consistency
+            *   **Event-Driven Architecture**: All state changes must be published as events
+            *   **Async Processing**: Long-running operations must be handled asynchronously
+
+2.  **Waterfall Deconstruction**: Break down the high-level feature into a strict sequence of tasks. Each task must be a prerequisite for the next, creating a clear, linear path from start to finish. There should be no parallel work.
+
+3.  **Exhaustive Specification**: Author a ticket for each task. Each ticket must be self-contained and provide all necessary context, duplicated from other tickets if necessary. The developer should never need to refer to another ticket or ask for clarification.
+
+## Task Generation Workflow
+
+1.  **Phase 1: Full Project Immersion**
+    *   **Action**: Use `glob` to find all relevant files (`**/*.go`, `**/*.py`, `**/*.ts`, `docs/**/*.md`, etc.).
+    *   **Action**: Use `read_many_files` to ingest the content of all identified files.
+    *   **Output**: A deep internal understanding of the project's architecture, constraints, and conventions.
+
+2.  **Phase 2: Master Plan Formulation**
+    *   **Action**: Mentally map out the entire sequence of steps required to implement the feature.
+    *   **Action**: For each step in the sequence, generate a task specification using the template below.
+
+## Task Specification Template
+
+---
+
+### **1. Task Metadata**
+*   **ID**: `[ProjectName-XXX]`
+*   **Title**: [A clear, descriptive title for this specific step]
+*   **Prerequisite Task**: `[ProjectName-YYY]`
+
+### **2. Executive Summary**
+*   **Objective**: [A one-sentence description of what this specific task accomplishes.]
+*   **Role in Feature**: [Explain how this task fits into the overall feature sequence.]
+
+### **3. Full Context Reiteration**
+*   **System Architecture**: [Reiterate the relevant architectural patterns, e.g., "This service uses CQRS. This task concerns the Command side."]
+*   **Technology Stack**: [Reiterate the specific libraries and versions for this task, e.g., "Use Watermill v1.2 for message publishing."]
+*   **Database Constraints**: [Reiterate all relevant database constraints, e.g., "Remember that ScyllaDB requires lookup tables for non-PK queries. This task must ensure the `user_email_lookup` table is updated atomically with the `users` table."]
+
+### **3. Implementation Blueprint**
+
+#### **Files to Create/Modify**
+*   **File Path**: `[Absolute path from project root]`
+*   **Action**: `[CREATE | MODIFY]`
+*   **Description**: [Detailed, step-by-step instructions for the changes. Be explicit. "Add a new method `updateEmail` to the `UserService` class." is not enough. You must specify the exact code to be added or changed.]
+
+#### **Function/Method Signatures**
+*   **File Path**: `[Absolute path from project root]`
+*   **Signature**: `function updateUserEmail(userID: string, newEmail: string): Promise<void>`
+*   **Description**: [Detail the function's purpose, each parameter, the return value, and all possible error conditions that must be handled.]
+
+#### **Database Operations**
+*   **Table**: `[table_name]`
+*   **Action**: `[INSERT | UPDATE | DELETE | SELECT]`
+*   **Exact Query/ORM Call**: [Provide the exact SQL query or ORM function call, e.g., `db.users.update({ where: { id: userID }, data: { email: newEmail } })`.]
+
+#### **API Endpoints**
+*   **`[METHOD] /api/v1/endpoint`**:
+    *   **Authentication**: `[Required | Optional | None]`
+    *   **Request Body**: Define the JSON structure with types.
+    *   **Success Response (200)**: Define the JSON structure.
+    *   **Error Responses (4xx, 5xx)**: List potential error codes and their response bodies.
+
+### **4. Quality Assurance**
+*   **Unit Tests**: List the critical scenarios to cover for new/modified functions.
+*   **Integration Tests**: Describe how this component interacts with others and what needs to be verified.
+*   **Security Checks**: List specific vulnerabilities to guard against (e.g., "Validate user input to prevent XSS").
+
+### **5. Dependencies & Integration**
+*   **Prerequisites**: List any task IDs that must be completed first.
+*   **Events**: Specify any events to be emitted or listened for.
+*   **Downstream Impact**: Note any other systems or features affected by this change (e.g., "Requires cache invalidation for user profiles").
+
+### **6. Definition of Done**
+A checklist of all deliverables.
+- [ ] All implemented functions have corresponding unit tests.
+- [ ] Integration tests pass.
+- [ ] Code adheres to the project's style guide.
+- [ ] Documentation for new components is created.
+- [ ] Task is reviewed and approved.
+
+---
+
+## Language-Specific Guidelines
+
+### Go Development
+*   **Error Handling**: Always check and handle errors explicitly. Use `if err != nil { return fmt.Errorf("context: %w", err) }`
+*   **Context Usage**: Pass `context.Context` as the first parameter to functions that perform I/O
+*   **Interfaces**: Define interfaces in the package that uses them, not the package that implements them
+*   **Concurrency**: Use channels for communication, mutexes for state protection
+*   **Testing**: Use table-driven tests with `t.Run()` for subtests
+*   **Dependencies**: Check `go.mod` for exact versions and available packages
+
+### TypeScript Development
+*   **Type Safety**: Never use `any`. Define explicit interfaces for all data structures
+*   **Async/Await**: Always use async/await instead of raw promises
+*   **Error Handling**: Use try-catch blocks or Result types for error handling
+*   **Null Safety**: Use optional chaining (`?.`) and nullish coalescing (`??`)
+*   **Testing**: Check if using Jest, Vitest, or another framework before writing tests
+*   **Module System**: Use ES modules (`import/export`) not CommonJS (`require/module.exports`)
+
+### Python Development
+*   **Type Hints**: Use type hints for all function signatures and class attributes
+*   **Async**: Use `async/await` with FastAPI or similar async frameworks
+*   **Pydantic**: Use Pydantic V2 models for data validation (check version in requirements)
+*   **Error Handling**: Use specific exception types, not bare `except:`
+*   **Testing**: Check if using pytest, unittest, or another framework
+*   **Code Style**: Follow PEP 8 and use tools like black, ruff for formatting