ccstart 2.2.0 → 3.0.1

package/README.md

@@ -5,67 +5,152 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm downloads](https://img.shields.io/npm/dm/ccstart.svg)](https://www.npmjs.com/package/ccstart)
 
-Quick setup for Claude Code projects with built-in agents, skills, tickets, and orchestration workflows.
+Quick setup for Claude Code projects with built-in agents, skills, hooks, and ticket tracking.
 
-## Installation
+## Why ccstart?
+
+Setting up new projects or repositories and plugging in Claude Code into it requires more than just generating a 
+CLAUDE.md for most developers who wants a more customized workflow such as manual 
+creation of agents, skills, hooks, and project structure. 
+
+There isn't a standardized approach, leading to inconsistent setups and repeated boilerplate work across projects. 
+We already have boilerplate for our codebase to build CRUD and stuff, having one for something heavily customized 
+like Claude seems like the obvious solution.
+
+ccstart provides a complete, opinionated scaffolding with basic agents, skills, and workflows out of the box so that we
+can focus on immediately prompting and building while trying to keep context bloat and overengineering as low as 
+possible.
+
+## Quick Start Installation
 
 ```bash
-# Create a new project
-npx ccstart my-project
+# To set up in a specific directory
+npx ccstart <project directory>
 
 # Setup in current directory
 npx ccstart .
 
 # Install globally (optional)
 npm install -g ccstart
-ccstart my-project
+ccstart <project directory>
 ```
 
 ## What You Get
 
 ```
 my-project/
-├── CLAUDE.md                 # Project instructions for Claude
+├── CLAUDE.md                        # Project instructions for Claude
 ├── claude/
-│   ├── agents/               # 4 specialized agents
-│   ├── docs/                 # ROADMAP.md + agent-orchestration.md
-│   ├── skills/               # Workflow automation (commit, create-pr, etc.)
-│   └── tickets/              # Task tracking system
+│   └── tickets/
+│       ├── README.md                # Ticket format and structure guide
+│       └── ticket-list.md           # Centralized ticket index
 └── .claude/
-    ├── agents/               # Agents for Claude Code integration
-    └── skills/               # Skills for Claude Code integration
+    ├── agents/
+    │   ├── planner.md               # Strategic planning
+    │   ├── checker.md               # QA and code review
+    │   ├── backend.md               
+    │   └── frontend.md              
+    ├── skills/
+    │   ├── commit/                  # Conventional commits
+    │   ├── create-pr/               # Structured pull requests
+    │   ├── create-ticket/           # Ticket creation workflow
+    │   ├── design-feature/          # Opinionated design phases
+    │   ├── create-script/           # Python CLI generation for ideation
+    │   ├── skill-creator/           # Create new skills
+    │   └── update-claude-md/        # CLAUDE.md maintenance
+    └── hooks/
+        ├── ticket-reminder.sh       # Prompts ticket creation after planning
+        └── claude-md-reminder.sh    # Enforces CLAUDE.md instructions every prompt
 ```
 
-## The Workflow
+## The Integrated Workflow
+
+ccstart components work together to provide a complete development workflow:
+
+Generally, this is what I do personally:
+
+1. **Start with `/design-feature`** - Establish requirements and acceptance criteria before writing code
+2. **Persist requirements with `/create-ticket`** - Keep a clear record of work in the ticket system
+3. **Use the Planner agent** - Break down implementation into actionable tasks
+4. **Use Backend/Frontend agents** - Follow established patterns for consistent, high-quality code
+5. **Use the Checker agent** - Review code for quality, security, and performance before merging
+6. **Use `/commit` and `/create-pr`** - Maintain clean git history with conventional commits
+
+
+## Agents
+
+Agents in Claude's context basically works outside of your main context window, so you can use them for tasks and 
+analysis that will not pollute your context and bloat unnecessarily. 
+
+Invoke them with `@agent-name` in Claude Code or through natural language.
+
+
+## Skills
+
+Skills are basically macros, they can be explicitly invoked with `/skill-name` as if using slash commands, or 
+through natural language by triggering keywords. 
+
+They are best suited for repetitive action that you don't want to 
+keep typing the same thing for.
+
+
+## Hooks
+
+Hooks are shell scripts that run automatically in response to Claude Code events, such as before prompting, after 
+prompting. 
+
+If you know what lifespans are in context of backend development, this is basically it but for lifecycle 
+of prompt!
 
-### How Claude Uses Your Project
+### ticket-reminder
 
-1. **CLAUDE.md** provides context and instructions
-2. **Agents** handle specialized tasks:
-   - `planner` - Strategic planning and task breakdown
-   - `checker` - Quality assurance and code review
-   - `backend` - FastAPI/Python backend development
-   - `frontend` - React/TypeScript frontend development
-3. **Skills** automate common workflows:
-   - `/commit` - Conventional commits
-   - `/create-pr` - Structured pull requests
-   - `/create-ticket` - Task ticket creation
-   - `/design-feature` - Feature design phases
-4. **Tickets** track tasks with status emojis
+**Triggers:** After exiting plan mode (PostToolUse on ExitPlanMode)
 
-### Agent Orchestration Workflows
+**Purpose:** Prompts Claude to create a ticket for significant features or bug fixes after a plan is approved. Helps ensure work is tracked without manual reminders.
 
-Pre-configured workflows that coordinate agents:
+### claude-md-reminder
 
-| Workflow | Flow |
-|----------|------|
-| Feature Development | Planner → Backend/Frontend → Checker |
-| Bug Fix | Planner → Backend/Frontend → Checker |
-| API Development | Planner → Backend → Frontend → Checker |
-| UI Components | Planner → Frontend → Checker |
-| Quality Assurance | Planner → Checker → Fix → Checker |
+**Triggers:** On every user prompt submission
 
-See `claude/docs/agent-orchestration.md` for detailed workflow documentation.
+**Purpose:** Reminds Claude to:
+1. Review and respect all instructions in CLAUDE.md
+2. Ask clarifying questions instead of making assumptions
+
+## Ticket System
+
+A lightweight task tracking system built into your project so that you can have persistency for your implementation 
+plans across Claude session, while leaving an audit trace that Claude can refer back to whenever needed.
+
+### Status Emojis
+
+| Emoji | Status | Description |
+|-------|--------|-------------|
+| 🔴 | Todo | Not started |
+| 🟡 | In Progress | Currently being worked on |
+| 🟢 | Done | Completed |
+| 🔵 | Blocked | Waiting on dependencies |
+| ⚫ | Cancelled | No longer needed |
+
+### File Structure
+
+```
+tickets/
+├── ticket-list.md              # Centralized index of all tickets
+├── README.md                   # Ticket format guide
+├── TICKET-001-user-auth.md     # Individual ticket files
+├── TICKET-002-api-docs.md
+└── TICKET-003-testing.md
+```
+
+### Ticket Naming Convention
+
+Format: `TICKET-XXX-brief-description.md`
+
+Example: `TICKET-042-implement-dark-mode.md`
+
+### ticket-list.md
+
+The centralized index organizes tickets by priority (High/Medium/Low) with status emojis and links to individual ticket files. Update this file whenever you create, modify, or complete tickets.
 
 ## Command Line Options
 
@@ -84,26 +169,46 @@ Examples:
   ccstart my-app --all-agents  # Include all agents
   ccstart . --force            # Overwrite in current directory
   ccstart --agents             # Preview available agents
+  ccstart my-app --dry-run     # Preview changes without applying
 ```
 
-## Key Features
+## Interactive Setup
 
-- **Interactive Agent Selection** - Choose which agents to include during setup
-- **Agent Orchestration Workflows** - Pre-defined workflows that coordinate multiple agents
-- **Smart Conflict Resolution** - Handle existing files with skip/rename/overwrite options
-- **Auto-detects Claude Code** - Creates .claude directory structure automatically
-- **Dry Run Mode** - Preview changes before applying them
-- **Force Mode** - Skip all prompts for automated workflows
+When you run `ccstart`, you'll be guided through selection prompts:
 
-## Quick Start
+### Agent Selection
 
-```bash
-npx ccstart my-project
-cd my-project
+```
+? Choose your agents: (Press <space> to select, <a> to toggle all)
+❯◯ planner
+     Strategic planning and task breakdown specialist
+ ◯ checker
+     Quality assurance and code review specialist
+ ◯ backend
+     Backend architecture and API design specialist
+ ◯ frontend
+     Frontend architecture and UI design specialist
+```
+
+### Skill Selection
 
-# Edit CLAUDE.md with your project details
-# Start using Claude Code with pre-configured agents and workflows
 ```
+? Choose your skills: (Press <space> to select, <a> to toggle all)
+❯◯ commit
+     Generate and execute git commits following conventional commit format
+ ◯ create-pr
+     Create GitHub pull requests with properly structured descriptions
+ ◯ create-ticket
+     Create task tickets with proper numbering and update ticket-list.md
+ ◯ design-feature
+     Guide feature development through requirements and design phases
+ ◯ skill-creator
+     Guide for creating new skills
+ ◯ update-claude-md
+     Update CLAUDE.md sections through interactive Q&A
+```
+
+Use `--all-agents` to skip selection and include everything.
 
 ## Local Development
 
@@ -122,7 +227,7 @@ npm unlink -g ccstart
 
 ## Credits
 
-Born from our discussions in TechOverflow with [vichannnnn](https://github.com/vichannnnn), [MrMarciaOng](https://github.com/MrMarciaOng), and [nasdin](https://github.com/nasdin)
+Born from our discussions in TechOverflow with [vichannnnn](https://github.com/vichannnnn) and [MrMarciaOng](https://github.com/MrMarciaOng).
 
 ## License