ccstart 3.0.0 → 3.0.2

package/README.md

@@ -5,9 +5,23 @@
 [![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, and tickets.
+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
 # To set up in a specific directory
@@ -25,33 +39,118 @@ ccstart <project directory>
 
 ```
 my-project/
-├── CLAUDE.md                 # Project instructions for Claude
+├── CLAUDE.md                        # Project instructions for Claude
 ├── claude/
-│   └── 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
-    └── hooks/                # Hooks 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
-
-### How Claude Uses Your Project
-
-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` - Backend architecture and API design
-   - `frontend` - Frontend architecture and UI design
-3. **Skills** automate common workflows:
-   - `/commit` - Conventional commits
-   - `/create-pr` - Structured pull requests
-   - `/create-ticket` - Task ticket creation
-   - `/design-feature` - Feature design phases
-   - `/skill-creator` - Create new skills
-   - `/update-claude-md` - Update CLAUDE.md sections
-4. **Tickets** track tasks with status emojis
+## 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!
+
+### ticket-reminder
+
+**Triggers:** After exiting plan mode (PostToolUse on ExitPlanMode)
+
+**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.
+
+### claude-md-reminder
+
+**Triggers:** On every user prompt submission
+
+**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
 
@@ -70,11 +169,12 @@ 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
 ```
 
 ## Interactive Setup
 
-When you run `ccstart`, you'll be guided through three selection prompts:
+When you run `ccstart`, you'll be guided through selection prompts:
 
 ### Agent Selection
 
@@ -108,25 +208,7 @@ When you run `ccstart`, you'll be guided through three selection prompts:
      Update CLAUDE.md sections through interactive Q&A
 ```
 
-Use `--all-agents` to skip agent selection and include all agents.
-
-## Key Features
-
-- **Interactive Agent & Skill Selection** - Choose which agents and skills to include during setup
-- **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
-
-## Quick Start
-
-```bash
-npx ccstart my-project
-cd my-project
-
-# Edit CLAUDE.md with your project details
-# Start using Claude Code with pre-configured agents and workflows
-```
+Use `--all-agents` to skip selection and include everything.
 
 ## Local Development
 

package/bin/create-project.js

@@ -566,8 +566,9 @@ async function initializeClaudeDirectory(selectedAgentFiles, selectedSkillDirs,
     // Copy .claude/hooks directory
     const claudeHooksDir = path.join(claudeDir, 'hooks');
     const templateHooksDir = path.join(templateDir, 'claude', 'hooks');
-    
-    if (fs.existsSync(templateHooksDir)) {
+    const copiedHookFiles = [];
+
+    if (fs.existsSync(templateHooksDir) && selectedHookFiles.length > 0) {
       // Create .claude/hooks directory
       if (!fs.existsSync(claudeHooksDir)) {
         if (!dryRun) {
@@ -578,14 +579,13 @@ async function initializeClaudeDirectory(selectedAgentFiles, selectedSkillDirs,
           console.log('  📁 Would create directory: .claude/hooks/');
         }
       }
-      
-      // Copy all files from template hooks directory
-      const hookFiles = fs.readdirSync(templateHooksDir);
-      for (const hookFile of hookFiles) {
+
+      // Copy only selected hook files
+      for (const hookFile of selectedHookFiles) {
         const hookSrc = path.join(templateHooksDir, hookFile);
         const hookDest = path.join(claudeHooksDir, hookFile);
-        
-        if (fs.statSync(hookSrc).isFile()) {
+
+        if (fs.existsSync(hookSrc) && fs.statSync(hookSrc).isFile()) {
           if (!fs.existsSync(hookDest)) {
             if (!dryRun) {
               fs.copyFileSync(hookSrc, hookDest);
@@ -594,6 +594,7 @@ async function initializeClaudeDirectory(selectedAgentFiles, selectedSkillDirs,
                 fs.chmodSync(hookDest, '755');
               }
             }
+            copiedHookFiles.push(hookFile);
             createdItems.push(`.claude/hooks/${hookFile}`);
             if (dryRun) {
               console.log(`  ✨ Would copy: .claude/hooks/${hookFile}`);
@@ -606,6 +607,7 @@ async function initializeClaudeDirectory(selectedAgentFiles, selectedSkillDirs,
                   fs.chmodSync(hookDest, '755');
                 }
               }
+              copiedHookFiles.push(hookFile);
               if (dryRun) {
                 console.log(`  ♻️  Would replace: .claude/hooks/${hookFile}`);
               }
@@ -624,6 +626,8 @@ async function initializeClaudeDirectory(selectedAgentFiles, selectedSkillDirs,
                   fs.chmodSync(newDest, '755');
                 }
               }
+              const renamedFile = path.basename(newDest);
+              copiedHookFiles.push(renamedFile);
               const relativePath = path.relative(claudeDir, newDest);
               createdItems.push(relativePath);
               if (dryRun) {
@@ -639,6 +643,46 @@ async function initializeClaudeDirectory(selectedAgentFiles, selectedSkillDirs,
         }
       }
     }
+
+    // Create settings.local.json with hooks configuration
+    const settingsLocalDest = path.join(claudeDir, 'settings.local.json');
+    if (copiedHookFiles.length > 0) {
+      const hooksConfig = {
+        hooks: {
+          UserPromptSubmit: []
+        }
+      };
+
+      // Add each copied hook to UserPromptSubmit (all current hooks use this event)
+      for (const hookFile of copiedHookFiles) {
+        hooksConfig.hooks.UserPromptSubmit.push({
+          hooks: [{
+            type: "command",
+            command: `.claude/hooks/${hookFile}`
+          }]
+        });
+      }
+
+      // Merge with existing settings.local.json if it exists
+      if (fs.existsSync(settingsLocalDest)) {
+        const existingSettings = JSON.parse(fs.readFileSync(settingsLocalDest, 'utf8'));
+        existingSettings.hooks = hooksConfig.hooks;
+        if (!dryRun) {
+          fs.writeFileSync(settingsLocalDest, JSON.stringify(existingSettings, null, 2));
+        }
+        if (dryRun) {
+          console.log('  ♻️  Would update: .claude/settings.local.json with hooks config');
+        }
+      } else {
+        if (!dryRun) {
+          fs.writeFileSync(settingsLocalDest, JSON.stringify(hooksConfig, null, 2));
+        }
+        if (dryRun) {
+          console.log('  ✨ Would create: .claude/settings.local.json with hooks config');
+        }
+      }
+      createdItems.push('.claude/settings.local.json');
+    }
     
     // Copy settings.json.example if it doesn't exist
     const settingsExampleSrc = path.join(templateDir, 'settings.json.example');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccstart",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Start your Claude Code projects with a well-organized structure including agents, tickets, and skills",
   "bin": {
     "ccstart": "bin/create-project.js"

package/template/claude/hooks/claude-md-reminder.sh

@@ -11,5 +11,6 @@ cat << 'EOF'
 REMINDER: Before responding to this prompt:
 1. Review and respect all instructions in CLAUDE.md
 2. Ask clarifying questions if any requirements are unclear - do not make assumptions
+3. If you just exited plan mode and the user approved a significant feature or bug fix, consider using /create-ticket to capture the implementation plan
 </user-prompt-submit-hook>
 EOF

package/template/claude/skills/update-claude-md/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: update-claude-md
+description: Update CLAUDE.md sections through interactive Q&A. Use when the user wants to update project documentation, refresh CLAUDE.md content, or says "/update-claude-md". Guides user through questions to update auto-generated sections (overview, objectives, commands, notes).
+---
+
+# Update CLAUDE.md Skill
+
+Update auto-generated sections in CLAUDE.md through interactive Q&A with the user.
+
+## Target Sections
+
+CLAUDE.md contains auto-generated sections marked with special comments:
+
+```markdown
+<!-- auto-generated-start:SECTION_NAME -->
+[content]
+<!-- auto-generated-end:SECTION_NAME -->
+```
+
+**Sections to update:**
+- `overview` - Brief project description
+- `objectives` - Key project objectives (bullet list)
+- `commands` - Common project commands (code block)
+- `notes` - Additional important information
+
+## Workflow
+
+1. Read current CLAUDE.md content
+2. Ask user which sections to update (or update all)
+3. For each section, ask targeted questions
+4. Generate updated content based on responses
+5. Replace content between section markers
+
+## Questions by Section
+
+### Overview
+- "What does this project do in one or two sentences?"
+- "What problem does it solve?"
+
+### Objectives
+- "What are the main goals of this project?"
+- "What key features or capabilities should it provide?"
+
+### Commands
+- "What commands do you commonly run for development?"
+- "What are the test, build, and run commands?"
+
+### Notes
+- "What technology stack does this project use?"
+- "Are there any important dependencies or requirements?"
+- "Any other context that would help when working on this project?"
+
+## Update Process
+
+1. Find section markers using pattern: `<!-- auto-generated-start:SECTION_NAME -->`
+2. Replace content between start and end markers
+3. Preserve marker comments
+4. Keep all content outside markers unchanged
+
+## Example
+
+User: "/update-claude-md"
+
+Assistant asks: "Which sections would you like to update?"
+- Overview
+- Objectives
+- Commands
+- Notes
+- All sections
+
+User selects "Overview"
+
+Assistant asks: "What does this project do in one or two sentences?"
+
+User responds: "It's a REST API for managing a book library with search and recommendations"
+
+Assistant updates:
+```markdown
+<!-- auto-generated-start:overview -->
+A REST API for managing a book library, providing search functionality and personalized book recommendations.
+<!-- auto-generated-end:overview -->
+```
+
+## Guidelines
+
+- Keep overview concise (1-3 sentences)
+- Format objectives as bullet points starting with action verbs
+- Include actual commands in the commands section, not placeholders
+- Notes should capture technology-specific details and gotchas

package/template/claude/hooks/ticket-reminder.sh

@@ -1,19 +0,0 @@
-#!/bin/bash
-: <<'FRONTMATTER'
----
-name: ticket-reminder
-description: Reminds Claude to create a ticket for significant features or bug fixes after plan approval
-hooks:
-  - event: PostToolUse
-    matcher: ExitPlanMode
----
-FRONTMATTER
-
-cat << 'EOF'
-<post-tool-use-hook>
-REMINDER: After the user approves this plan, consider whether this feature or bug fix justifies creating a ticket:
-- If this is a significant feature, enhancement, or bug fix, use /create-ticket to create a ticket that captures the plan
-- Include the implementation details from the plan in the ticket
-- Skip ticket creation for trivial changes (typos, minor tweaks, quick fixes)
-</post-tool-use-hook>
-EOF