npm - ccstart - Versions diffs - 2.1.0 → 3.0.0 - Mend

ccstart 2.1.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/README.md +83 -58
package/bin/create-project.js +478 -110
package/package.json +3 -12
package/template/claude/CLAUDE.md +16 -105
package/template/claude/agents/README.md +4 -7
package/template/claude/agents/backend.md +231 -75
package/template/claude/agents/checker.md +76 -50
package/template/claude/agents/frontend.md +295 -68
package/template/claude/agents/planner.md +86 -31
package/template/claude/hooks/claude-md-reminder.sh +15 -0
package/template/claude/hooks/ticket-reminder.sh +19 -0
package/template/claude/skills/create-script/SKILL.md +362 -0
package/template/claude/skills/design-feature/SKILL.md +3 -3
package/template/claude/skills/skill-creator/SKILL.md +1 -1
package/template/claude/agents/blockchain.md +0 -80
package/template/claude/agents/coder.md +0 -45
package/template/claude/agents/researcher.md +0 -55
package/template/claude/agents/shadcn.md +0 -105
package/template/claude/docs/ROADMAP.md +0 -64
package/template/claude/docs/agent-orchestration.md +0 -152
package/template/claude/skills/design-principles/skill.md +0 -237

package/package.json CHANGED Viewed

@@ -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": "3.0.0",
+  "description": "Start your Claude Code projects with a well-organized structure including agents, tickets, and skills",
   "bin": {
     "ccstart": "bin/create-project.js"
   },
@@ -16,8 +16,7 @@
   "author": "vichannnnn",
   "contributors": [
     "marcia_ong",
-    "hima7459",
-    "nasdin"
+    "hima7459"
   ],
   "license": "MIT",
   "repository": {
@@ -35,13 +34,5 @@
   },
   "dependencies": {
     "@inquirer/checkbox": "^4.0.4"
-  },
-  "devDependencies": {
-    "jest": "^30.0.5"
-  },
-  "scripts": {
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage"
   }
 }

package/template/claude/CLAUDE.md CHANGED Viewed

@@ -17,13 +17,12 @@
 ```
 .
 ├── 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
-├── claude/            # Claude Code project organization
-│   ├── agents/        # Custom agents for specialized tasks
-│   ├── docs/          # Project documentation
-│   ├── plans/         # Project plans and architectural documents
+├── ROADMAP.md         # Project roadmap and goals
+├── .claude/           # Claude Code configuration
+│   ├── agents/        # Specialized agents for Claude Code
+│   ├── skills/        # Skills for workflow automation
+│   └── hooks/         # Event hooks for Claude Code
+├── claude/            # Project organization
 │   └── tickets/       # Task tickets and issues
 └── [your project files and directories]
 ```
@@ -42,79 +41,6 @@
 - Add tests for new functionality
 - Ensure all tests pass
-### Git Workflow
-- Create descriptive commit messages
-- Keep commits focused and atomic
-- Review changes before committing
-## Commit Convention and Pull Request Guidelines
-### Commit Message Format
-Follow the conventional commits specification:
-```
-<type>(<scope>): <subject>
-<body>
-<footer>
-```
-**Types:**
-- `feat`: New feature
-- `fix`: Bug fix
-- `docs`: Documentation changes
-- `style`: Code style changes (formatting, missing semicolons, etc.)
-- `refactor`: Code refactoring without changing functionality
-- `test`: Adding or modifying tests
-- `chore`: Maintenance tasks (updating dependencies, build process, etc.)
-- `perf`: Performance improvements
-**Examples:**
-```
-feat(auth): add password reset functionality
-fix(api): handle null values in user response
-docs: update API documentation for book endpoints
-refactor(frontend): extract BookTable into separate components
-chore(deps): update FastAPI to 0.104.1
-```
-### Pull Request Guidelines
-**PR Title**: Use the same format as commit messages
-**PR Description Template:**
-```markdown
-## Summary
-Brief description of what this PR does and why it's needed.
-## Changes
-- List of specific changes made
-- Technical implementation details if relevant
-## Testing
-- [ ] Tests pass (if applicable)
-- [ ] Manual testing completed
-- [ ] No console errors or warnings
-## Manual Testing Steps
-1. Describe steps to manually test the feature
-2. Expected behavior and edge cases tested
-## Screenshots (if UI changes)
-Attach relevant screenshots here
-## Related Issues
-Closes #XXX (if applicable)
-## Checklist
-- [ ] Code follows project conventions
-- [ ] Self-documented code without unnecessary comments
-- [ ] All tests pass
-- [ ] Documentation updated if needed
-- [ ] No sensitive information exposed
-```
 ## Common Commands
 <!-- auto-generated-start:commands -->
 ```bash
@@ -129,32 +55,24 @@ Closes #XXX (if applicable)
 [Add any project-specific context, dependencies, or requirements here]
-## Agents
+## Skills
-See @claude/agents/README.md for available agents and their purposes
-## Agent Orchestration
-After adding the agents you want to in `./claude/agents` folder, setup the workflow for Claude code to follow
-## Custom Commands
-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
+- **/create-script** - Codify processes into standalone Python scripts with CLI interfaces
+- **/skill-creator** - Guide for creating new skills
+- **/update-claude-md** - Update CLAUDE.md sections through interactive Q&A
-See `.claude/commands/README.md` for creating your own commands
+See `.claude/skills/` for skill definitions
 ## Tickets
@@ -168,26 +86,19 @@ 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
+- See @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
 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
+2. **Ask clarifying questions**: Never make assumptions - always ask questions when requirements are unclear
+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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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: Backend architecture and API design 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