ccstart 2.1.0 → 2.2.0

package/README.md

@@ -5,7 +5,7 @@
 [![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, ticket system, planning tools and agent orchestration workflow.
+Quick setup for Claude Code projects with built-in agents, skills, tickets, and orchestration workflows.
 
 ## Installation
 
@@ -21,40 +21,51 @@ npm install -g ccstart
 ccstart my-project
 ```
 
-## What's Included
+## What You Get
 
-- **CLAUDE.md** - Project instructions for Claude (references claude/ subdirectories)
-- **claude/** - All Claude-related files in one organized directory:
-  - **agents/** - 8 specialized AI agents (planner, coder, checker, researcher, etc.)
-  - **tickets/** - Task tracking system with ticket templates
-  - **plans/** - Project planning documents
-  - **docs/** - ROADMAP.md and agent orchestration workflows
-- **.claude/** - Claude Code configuration (created automatically):
-  - **agents/** - Selected agents for Claude Code integration
-  - **commands/** - Custom slash commands including `/update-claude-md`
-  - **hooks/** - Automatic workflow detection
-  - **settings.json.example** - Hook configuration
+```
+my-project/
+├── 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
+└── .claude/
+    ├── agents/               # Agents for Claude Code integration
+    └── skills/               # Skills for Claude Code integration
+```
 
-## Key Features
+## The Workflow
 
-- 🎯 **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
-- 🎭 **Workflow Commands** - Execute complex workflows with single commands
-- 🪝 **Intelligent Hooks** - Automatically detect task patterns and suggest workflows
+### How Claude Uses Your Project
 
-## Quick Start
+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
 
-```bash
-npx ccstart my-project
-cd my-project
+### Agent Orchestration Workflows
 
-# Edit CLAUDE.md with your project details
-# Start using Claude Code with pre-configured agents and workflows
-```
+Pre-configured workflows that coordinate agents:
+
+| 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 |
+
+See `claude/docs/agent-orchestration.md` for detailed workflow documentation.
 
 ## Command Line Options
 
@@ -75,33 +86,24 @@ Examples:
   ccstart --agents             # Preview available agents
 ```
 
-## Agent Orchestration
-
-The template includes pre-configured workflows that automatically coordinate agents:
-
-- **Feature Development** → Researcher → Planner → Coder → Checker
-- **Bug Fix** → Researcher → Coder → Checker
-- **API Development** → Planner → Backend → Frontend → Checker
-- **Refactoring** → Researcher → Planner → Coder → Checker
-- **UI Components** → Frontend → Shadcn → Checker
-- **Quality Assurance** → Researcher → Checker → Coder → Checker
-
-See `claude/docs/agent-orchestration.md` for detailed workflow documentation.
+## Key Features
 
-## Custom Commands & Hooks
+- **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
 
-### Slash Commands
-- `/update-claude-md` - Automatically populate project information in CLAUDE.md
-- `/workflow-*` commands - Execute orchestrated workflows (coming soon)
+## Quick Start
 
-### Automatic Workflow Detection
-Hooks automatically detect task patterns and suggest appropriate workflows:
-- Feature requests → suggests `/workflow-feature`
-- Bug reports → suggests `/workflow-bug`
-- API tasks → suggests `/workflow-api`
-- And more! (QA, refactoring, UI components, blockchain)
+```bash
+npx ccstart my-project
+cd my-project
 
-Hooks are automatically enabled - no setup required!
+# Edit CLAUDE.md with your project details
+# Start using Claude Code with pre-configured agents and workflows
+```
 
 ## Local Development
 
@@ -124,4 +126,4 @@ Born from our discussions in TechOverflow with [vichannnnn](https://github.com/v
 
 ## License
 
-MIT
+MIT

package/bin/create-project.js

@@ -807,17 +807,15 @@ async function main() {
     'claude': [],
     'agents': [],
     'docs': [],
-    'plans': [],
     'tickets': []
   };
-  
+
   // Store conflict strategies per category
   const conflictStrategies = {
     'CLAUDE.md': 'skip',
     'claude': 'skip',
     'agents': 'skip',
     'docs': 'skip',
-    'plans': 'skip',
     'tickets': 'skip'
   };
 
@@ -898,7 +896,7 @@ async function main() {
           }
           
           // Process claude subdirectories (except agents which we handle specially)
-          const claudeSubdirs = ['docs', 'plans', 'tickets'];
+          const claudeSubdirs = ['docs', 'skills', 'tickets'];
           claudeSubdirs.forEach(subdir => {
             const subdirSrc = path.join(src, subdir);
             const subdirDest = path.join(dest, subdir);
@@ -1033,8 +1031,8 @@ async function main() {
             conflictsByCategory['agents'].push(relativePath);
           } else if (relativePath.startsWith('claude/docs/')) {
             conflictsByCategory['docs'].push(relativePath);
-          } else if (relativePath.startsWith('claude/plans/')) {
-            conflictsByCategory['plans'].push(relativePath);
+          } else if (relativePath.startsWith('claude/skills/')) {
+            conflictsByCategory['docs'].push(relativePath);
           } else if (relativePath.startsWith('claude/tickets/')) {
             conflictsByCategory['tickets'].push(relativePath);
           }
@@ -1073,7 +1071,6 @@ async function main() {
           { key: 'claude', name: 'Claude Directory', emoji: '📁' },
           { key: 'agents', name: 'Agents', emoji: '🤖' },
           { key: 'docs', name: 'Documentation', emoji: '📚' },
-          { key: 'plans', name: 'Plans', emoji: '📋' },
           { key: 'tickets', name: 'Tickets', emoji: '🎫' }
         ];
         
@@ -1140,8 +1137,8 @@ async function main() {
               strategy = conflictStrategies['agents'];
             } else if (item.relativePath.startsWith('claude/docs/')) {
               strategy = conflictStrategies['docs'];
-            } else if (item.relativePath.startsWith('claude/plans/')) {
-              strategy = conflictStrategies['plans'];
+            } else if (item.relativePath.startsWith('claude/skills/')) {
+              strategy = conflictStrategies['docs'];
             } else if (item.relativePath.startsWith('claude/tickets/')) {
               strategy = conflictStrategies['tickets'];
             } else {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ccstart",
-  "version": "2.1.0",
-  "description": "Start your Claude Code projects with a well-organized structure including agents, tickets, plans and orchestration workflows",
+  "version": "2.2.0",
+  "description": "Start your Claude Code projects with a well-organized structure including agents, tickets, skills and orchestration workflows",
   "bin": {
     "ccstart": "bin/create-project.js"
   },

package/template/claude/CLAUDE.md

@@ -19,11 +19,11 @@
 ├── CLAUDE.md          # This file - project instructions for Claude
 ├── .claude/           # Claude Code configuration (auto-generated)
 │   ├── agents/        # Project-specific agent overrides
-│   └── commands/      # Custom slash commands for Claude Code
+│   └── skills/        # Skills for workflow automation
 ├── claude/            # Claude Code project organization
 │   ├── agents/        # Custom agents for specialized tasks
 │   ├── docs/          # Project documentation
-│   ├── plans/         # Project plans and architectural documents
+│   ├── skills/        # Skill definitions (source of truth)
 │   └── tickets/       # Task tickets and issues
 └── [your project files and directories]
 ```
@@ -137,24 +137,23 @@ See @claude/agents/README.md for available agents and their purposes
 
 After adding the agents you want to in `./claude/agents` folder, setup the workflow for Claude code to follow
 
-## Custom Commands
+## Skills
 
-Custom slash commands are available in `.claude/commands/`:
+Skills extend Claude's capabilities with specialized workflows. Available skills:
 
 **Git Workflow:**
 - **/commit** - Generate and execute git commits following conventional commit format
 - **/create-pr** - Create GitHub pull requests with structured descriptions
-- **/review-pr** - Review pull requests with systematic quality checks
 
 **Project Management:**
 - **/create-ticket** - Create task tickets with proper numbering and update ticket-list.md
 - **/design-feature** - Guide feature development through requirements and design phases
-- **/create-plan** - Create timestamped planning documents
 
 **Utilities:**
-- **/update-claude-md** - Automatically updates this file with project-specific information
+- **/design-principles** - Enforce a precise, minimal design system
+- **/skill-creator** - Guide for creating new skills
 
-See `.claude/commands/README.md` for creating your own commands
+See `claude/skills/` for skill definitions and `.claude/skills/` for Claude Code integration
 
 ## Tickets
 
@@ -168,15 +167,10 @@ See @claude/tickets/README.md for ticket format and management approach
   - Complete a ticket (move to completed section with date)
 - **Status Emojis**: 🔴 Todo | 🟡 In Progress | 🟢 Done | 🔵 Blocked | ⚫ Cancelled
 
-## Plans
-
-See @claude/plans/README.md for planning documents and architectural decisions
-
 ## Development Context
 
 - See @claude/docs/ROADMAP.md for current status and next steps
 - Task-based development workflow with tickets in `claude/tickets` directory
-- Use `claude/plans` directory for architectural decisions and implementation roadmaps
 
 ## Important Instructions
 
@@ -184,10 +178,8 @@ Before starting any task:
 
 1. **Confirm understanding**: Always confirm you understand the request and outline your plan before proceeding
 2. **Ask clarifying questions**: Never make assumptions - ask questions when requirements are unclear
-3. **Create planning documents**: Before implementing any code or features, create a markdown file documenting the approach
-4. **Use plans directory**: When discussing ideas or next steps, create timestamped files in the plans directory (e.g., `claude/plans/next-steps-YYYY-MM-DD-HH-MM-SS.md`) to maintain a record of decisions
-5. **No code comments**: Never add comments to any code you write - code should be self-documenting
-6. **Maintain ticket list**: Always update @claude/tickets/ticket-list.md when creating, updating, or completing tickets to maintain a clear project overview
+3. **No code comments**: Never add comments to any code you write - code should be self-documenting
+4. **Maintain ticket list**: Always update @claude/tickets/ticket-list.md when creating, updating, or completing tickets to maintain a clear project overview
 
 ## Additional Notes
 <!-- auto-generated-start:notes -->

package/template/claude/agents/README.md

@@ -26,10 +26,7 @@ Agents are specialized prompts or tools that help Claude perform specific tasks
 ```
 
 ## Available Agents
-- **planner** - Strategic planning specialist for breaking down complex problems and creating implementation roadmaps
-- **coder** - Expert software developer for implementing features, fixing bugs, and optimizing code
-- **checker** - Quality assurance and code review specialist for testing, security analysis, and validation
-- **researcher** - Research specialist for both online sources and local codebases, gathering comprehensive information from multiple sources
-- **blockchain** - Blockchain and Web3 expert for smart contracts, DeFi protocols, and blockchain architecture
-- **frontend** - Frontend development specialist for UI/UX, responsive design, and modern web frameworks
-- **shadcn** - shadcn/ui component library expert for building beautiful, accessible React interfaces
+- **planner** - Strategic planning and task breakdown specialist
+- **checker** - Quality assurance and code review specialist
+- **backend** - FastAPI and Python backend specialist
+- **frontend** - React and TypeScript frontend specialist

package/template/claude/agents/backend.md

@@ -1,79 +1,235 @@
 ---
 name: backend
-description: Backend development specialist. Use PROACTIVELY for API design, database architecture, authentication, microservices, and server-side optimization. Invoke when building APIs, services, or backend infrastructure.
+description: FastAPI and Python backend specialist. Use for API endpoints, database models, authentication, and service logic. Invoke when building or modifying backend infrastructure.
 ---
 
-You are a senior backend engineer with expertise in server-side technologies and distributed systems. Your role is to design and implement scalable, secure, and performant backend services.
-
-## Core Responsibilities:
-1. **API Design**: Create RESTful and GraphQL APIs with proper documentation
-2. **Database Architecture**: Design efficient schemas and optimize queries
-3. **Authentication & Security**: Implement secure auth flows and data protection
-4. **Microservices**: Build scalable, distributed service architectures
-5. **Performance & Scaling**: Ensure high availability and optimal response times
-
-## Expertise Areas:
-
-### Languages & Frameworks:
-- **Node.js**: Express, Fastify, NestJS, middleware patterns
-- **Python**: Django, FastAPI, Flask, async programming
-- **Java**: Spring Boot, microservices, reactive programming
-- **Go**: High-performance services, concurrent programming
-- **Ruby**: Rails, API-only applications, background jobs
-
-### Technical Skills:
-- **Databases**: PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch
-- **Message Queues**: RabbitMQ, Kafka, Redis Pub/Sub, AWS SQS
-- **Caching**: Redis, Memcached, CDN strategies
-- **Testing**: Unit, integration, load testing, TDD/BDD
-- **DevOps**: Docker, Kubernetes, CI/CD, monitoring
-
-## Development Process:
-1. Analyze requirements and define API contracts
-2. Design database schema and relationships
-3. Implement service layer with business logic
-4. Create comprehensive error handling
-5. Add authentication and authorization
-6. Optimize queries and implement caching
-7. Write thorough tests and documentation
-
-## Best Practices:
-- **API Design**: RESTful principles, versioning, consistent responses
-- **Security**: Input validation, SQL injection prevention, rate limiting
-- **Performance**: Query optimization, connection pooling, caching strategies
-- **Scalability**: Horizontal scaling, load balancing, stateless design
-- **Error Handling**: Graceful degradation, meaningful error messages
-- **Monitoring**: Logging, metrics, distributed tracing
-
-## Architecture Patterns:
-- **Microservices**: Service boundaries, API gateway, service mesh
-- **Event-Driven**: Event sourcing, CQRS, message-driven architecture
-- **Serverless**: Lambda functions, edge computing, FaaS patterns
-- **Monolithic**: When appropriate, modular monoliths
-- **Database**: Repository pattern, unit of work, migrations
-
-## Security Considerations:
-- Authentication: JWT, OAuth2, session management
-- Authorization: RBAC, ABAC, policy engines
-- Data Protection: Encryption at rest and in transit
-- API Security: Rate limiting, CORS, input sanitization
-- Compliance: GDPR, PCI DSS, HIPAA considerations
-
-## Performance Optimization:
-- **Database**: Indexing, query optimization, connection pooling
-- **Caching**: Multi-level caching, cache invalidation strategies
-- **Async Processing**: Background jobs, message queues
-- **Load Balancing**: Round-robin, least connections, health checks
-- **Monitoring**: APM tools, custom metrics, alerting
-
-## Output Format:
-Structure backend solutions with:
-- **Architecture Overview**: Service boundaries and interactions
-- **API Documentation**: Endpoints, request/response formats
-- **Database Schema**: Tables, relationships, indexes
-- **Implementation**: Clean, maintainable service code
-- **Security Measures**: Auth flow and data protection
-- **Performance Strategy**: Caching, optimization techniques
-- **Deployment Plan**: Infrastructure and scaling approach
-
-Remember: Backend services are the foundation. Focus on reliability, security, and scalability in every implementation.
+# Backend Agent
+
+Build backend services using FastAPI, SQLAlchemy 2.0, and PostgreSQL. Follow the patterns and conventions defined below strictly.
+
+## When to Use This Agent
+
+- Creating or modifying API endpoints
+- Designing database models and schemas
+- Implementing authentication and authorization
+- Writing service layer business logic
+- Adding validation, error handling, or pagination
+- Database migrations with Alembic
+
+## Stack
+
+- **Framework**: FastAPI with async/await
+- **ORM**: SQLAlchemy 2.0 async with asyncpg
+- **Database**: PostgreSQL
+- **Validation**: Pydantic v2
+- **Auth**: JWT tokens in HTTP-only cookies, bcrypt password hashing
+- **Migrations**: Alembic
+
+## Project Structure
+
+Follow this directory layout:
+
+```
+app/
+├── main.py                    # FastAPI app setup
+├── config.py                  # Pydantic Settings for env vars
+├── api/
+│   ├── api.py                 # Router aggregation
+│   ├── deps.py                # Dependency injection (auth, session)
+│   └── endpoints/
+│       └── {resource}.py      # One file per resource
+├── models/
+│   └── {resource}.py          # SQLAlchemy models
+├── schemas/
+│   └── {resource}/
+│       ├── request.py         # Create/Update schemas
+│       └── response.py        # Response schemas
+├── services/
+│   └── {resource}.py          # Business logic
+├── crud/
+│   └── base.py                # Generic CRUD mixin
+├── db/
+│   └── database.py            # Engine and session setup
+├── utils/
+│   ├── auth.py                # JWT and password utilities
+│   └── exceptions.py          # AppError class
+└── enum/
+    └── {name}.py              # Enum definitions
+```
+
+## Implementation Patterns
+
+### Router Structure
+
+Create one router file per resource in `api/endpoints/`. Register in `api/api.py`:
+
+```python
+api_router = APIRouter()
+api_router.include_router(auth.router, tags=["Authentication"], prefix="/auth")
+api_router.include_router(books.router, tags=["Book"], prefix="/books")
+```
+
+### Endpoint Pattern
+
+Use type-annotated dependencies. Keep endpoints thin—delegate to services:
+
+```python
+@router.post("", response_model=BookResponse)
+async def create_book(
+    session: CurrentSession,
+    user: CurrentUser,
+    book: CreateBookRequest,
+) -> BookResponse:
+    new_book = await BookService.create(session, data=book)
+    return BookResponse.model_validate(new_book)
+```
+
+### Model Pattern
+
+Use SQLAlchemy 2.0 with `Mapped` type hints. UUID primary keys. Inherit from `Base` and `CRUD`:
+
+```python
+class Book(Base, CRUD):
+    __tablename__ = "book"
+
+    book_id: Mapped[UUID] = mapped_column(
+        PG_UUID(as_uuid=True), primary_key=True, index=True, default=uuid4
+    )
+    title: Mapped[str] = mapped_column(nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+```
+
+### Schema Pattern
+
+Use Pydantic v2 with `CustomBaseModel`. Separate request and response schemas:
+
+```python
+class CreateBookRequest(CustomBaseModel):
+    title: str
+    author: str
+
+class BookResponse(CustomBaseModel):
+    book_id: UUID
+    title: str
+    author: str
+    created_at: datetime
+```
+
+### Service Pattern
+
+Static methods containing business logic. Never put business logic in endpoints:
+
+```python
+class BookService:
+    @staticmethod
+    async def create(session: AsyncSession, data: CreateBookRequest) -> Book:
+        book = Book(**data.model_dump())
+        session.add(book)
+        await session.commit()
+        await session.refresh(book)
+        return book
+```
+
+### Dependency Pattern
+
+Define dependencies in `api/deps.py` using `Annotated`:
+
+```python
+async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        yield session
+
+CurrentSession = Annotated[AsyncSession, Depends(get_db_session)]
+CurrentUser = Annotated[UserMetadata, Depends(get_current_user)]
+```
+
+### Error Handling
+
+Use centralized `AppError` class. Raise `HTTPException` with proper status codes:
+
+```python
+class AppError:
+    RESOURCES_NOT_FOUND_ERROR = HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail="Resource not found",
+    )
+
+    @staticmethod
+    def bad_request(detail: str) -> HTTPException:
+        return HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=detail)
+```
+
+### Pagination Pattern
+
+Return paginated results with metadata:
+
+```python
+@staticmethod
+async def get_all_paginated(
+    session: AsyncSession, page: int = 1, size: int = 50
+) -> dict[str, Any]:
+    skip = (page - 1) * size
+    total = await session.scalar(select(func.count()).select_from(Book))
+    result = await session.execute(select(Book).offset(skip).limit(size))
+    pages = (total + size - 1) // size if total else 0
+    return {
+        "items": result.scalars().all(),
+        "page": page,
+        "pages": pages,
+        "size": size,
+        "total": total,
+    }
+```
+
+### Authentication Pattern
+
+JWT tokens stored in HTTP-only cookies. bcrypt for password hashing:
+
+```python
+# Creating token
+access_token = Authenticator.create_access_token(data=user_metadata.model_dump())
+response.set_cookie(
+    key="access_token",
+    value=access_token,
+    httponly=True,
+    secure=True,
+    max_age=decoded_token["exp"],
+)
+
+# Verifying token
+async def get_current_user(request: Request) -> UserMetadata:
+    token = request.cookies.get("access_token")
+    if not token:
+        raise AppError.INVALID_CREDENTIALS_ERROR
+    payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+    return UserMetadata.model_validate(payload)
+```
+
+## Quality Standards
+
+### Every Endpoint Must Have
+- Response model defined
+- Proper HTTP status codes
+- Error handling for expected failures
+- Type-annotated parameters
+
+### Every Model Must Have
+- UUID primary key
+- Proper indexes on frequently queried columns
+- `created_at` timestamp with `server_default=func.now()`
+- Foreign keys with `index=True`
+
+### Every Service Method Must
+- Be a static method
+- Accept session as first parameter
+- Handle database errors and raise appropriate `AppError`
+- Commit transactions explicitly
+
+### Never Do
+- Put business logic in endpoints
+- Use raw SQL without parameterization
+- Store passwords in plain text
+- Return database models directly (use response schemas)
+- Skip validation on user input