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

ccstart 2.2.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 (14) hide show

package/README.md +50 -27
package/bin/create-project.js +473 -102
package/package.json +3 -12
package/template/claude/CLAUDE.md +11 -92
package/template/claude/agents/backend.md +1 -1
package/template/claude/agents/frontend.md +1 -1
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/docs/ROADMAP.md +0 -62
package/template/claude/docs/agent-orchestration.md +0 -183
package/template/claude/skills/design-principles/skill.md +0 -237

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "ccstart",
-  "version": "2.2.0",
-  "description": "Start your Claude Code projects with a well-organized structure including agents, tickets, skills 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
-│   └── skills/        # Skills for workflow automation
-├── claude/            # Claude Code project organization
-│   ├── agents/        # Custom agents for specialized tasks
-│   ├── docs/          # Project documentation
-│   ├── skills/        # Skill definitions (source of truth)
+├── 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,14 +55,6 @@ Closes #XXX (if applicable)
 [Add any project-specific context, dependencies, or requirements here]
-## Agents
-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
 ## Skills
 Skills extend Claude's capabilities with specialized workflows. Available skills:
@@ -150,10 +68,11 @@ Skills extend Claude's capabilities with specialized workflows. Available skills
 - **/design-feature** - Guide feature development through requirements and design phases
 **Utilities:**
-- **/design-principles** - Enforce a precise, minimal design system
+- **/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/skills/` for skill definitions and `.claude/skills/` for Claude Code integration
+See `.claude/skills/` for skill definitions
 ## Tickets
@@ -169,7 +88,7 @@ See @claude/tickets/README.md for ticket format and management approach
 ## 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
 ## Important Instructions
@@ -177,7 +96,7 @@ See @claude/tickets/README.md for ticket format and management approach
 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
+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

package/template/claude/agents/backend.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: backend
-description: FastAPI and Python backend specialist. Use for API endpoints, database models, authentication, and service logic. Invoke when building or modifying 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.
 ---
 # Backend Agent

package/template/claude/agents/frontend.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: frontend
-description: React and TypeScript frontend specialist. Use for UI components, state management, data fetching, and client-side logic. Invoke when building or modifying frontend features.
+description: Frontend architecture and UI design specialist. Use for UI components, state management, data fetching, and client-side logic. Invoke when building or modifying frontend features.
 ---
 # Frontend Agent

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

@@ -0,0 +1,15 @@
+#!/bin/bash
+: <<'FRONTMATTER'
+---
+name: claude-md-reminder
+description: Reminds Claude to respect CLAUDE.md and ask clarifying questions on every prompt
+---
+FRONTMATTER
+cat << 'EOF'
+<user-prompt-submit-hook>
+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
+</user-prompt-submit-hook>
+EOF

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

@@ -0,0 +1,19 @@
+#!/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

package/template/claude/skills/create-script/SKILL.md ADDED Viewed

@@ -0,0 +1,362 @@
+---
+name: create-script
+description: Codify discovered processes into standalone, reusable Python scripts. Use when the user has figured out a process (API integration, data pipeline, automation task) and wants to turn it into a reusable script, or when the user says "/create-script".
+---
+# Create Script Skill
+Turn discovered processes into production-ready Python scripts with CLI interfaces.
+## When to Use
+- After exploring an API and figuring out the request flow
+- After solving a data transformation problem
+- When automating a manual process
+- When the user wants to capture a working solution as a reusable tool
+## Workflow
+### Step 1: Gather Context
+Review the conversation to identify:
+- What process was discovered or solved
+- What API endpoints, data sources, or operations are involved
+- What worked and what didn't (avoid repeating mistakes)
+### Step 2: Identify Requirements
+Ask about or determine:
+- **Inputs**: What data does the script need? (files, API keys, parameters)
+- **Outputs**: What should the script produce? (files, stdout, API calls)
+- **Configuration**: What might change between runs? (URLs, credentials, options)
+- **Error cases**: What can go wrong and how should it be handled?
+### Step 3: Design Script Structure
+Plan the script organization:
+- Break logic into focused functions
+- Identify what should be configurable via CLI arguments
+- Determine what should come from environment variables (secrets)
+- Plan the main flow and error handling
+### Step 4: Generate the Script
+Create a Python script following the template structure below. Include:
+- Clear CLI interface with help text
+- Environment variable handling for secrets
+- Proper error handling and exit codes
+- Logging for visibility into what's happening
+### Step 5: Provide Usage Examples
+After generating the script:
+- Show example invocations
+- Document required environment variables
+- Suggest next steps (testing, scheduling, extending)
+## Script Template
+```python
+#!/usr/bin/env python3
+"""
+[Script description - what it does and why]
+Usage:
+    python script_name.py [options] <arguments>
+Examples:
+    python script_name.py --input data.json
+    python script_name.py --verbose --output results.csv
+"""
+import argparse
+import logging
+import os
+import sys
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+def get_config():
+    """Load configuration from environment variables."""
+    return {
+        "api_key": os.environ.get("API_KEY"),
+        "base_url": os.environ.get("BASE_URL", "https://api.example.com"),
+    }
+def validate_config(config):
+    """Validate required configuration is present."""
+    missing = [k for k, v in config.items() if v is None and k in ["api_key"]]
+    if missing:
+        logger.error(f"Missing required environment variables: {', '.join(missing)}")
+        sys.exit(1)
+    return config
+def main_logic(args, config):
+    """Core script logic goes here."""
+    logger.info(f"Processing with input: {args.input}")
+    # Implementation here
+    return {"status": "success"}
+def parse_args():
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="[Script description]",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    %(prog)s --input data.json
+    %(prog)s --verbose --output results.csv
+Environment Variables:
+    API_KEY     Required. API authentication key.
+    BASE_URL    Optional. API base URL (default: https://api.example.com)
+        """
+    )
+    parser.add_argument(
+        "--input", "-i",
+        required=True,
+        help="Input file path"
+    )
+    parser.add_argument(
+        "--output", "-o",
+        default="-",
+        help="Output file path (default: stdout)"
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Enable verbose logging"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done without making changes"
+    )
+    return parser.parse_args()
+def main():
+    """Main entry point."""
+    args = parse_args()
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+    try:
+        config = validate_config(get_config())
+        result = main_logic(args, config)
+        if result.get("status") == "success":
+            logger.info("Completed successfully")
+            sys.exit(0)
+        else:
+            logger.error(f"Failed: {result.get('error', 'Unknown error')}")
+            sys.exit(1)
+    except KeyboardInterrupt:
+        logger.info("Interrupted by user")
+        sys.exit(130)
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
+        sys.exit(1)
+if __name__ == "__main__":
+    main()
+```
+## CLI Design Guidelines
+### Use argparse (standard library)
+Prefer argparse over external dependencies like click:
+- Zero dependencies means easier distribution
+- Familiar to most Python developers
+- Sufficient for most CLI needs
+### Argument Patterns
+**Positional arguments** for required, obvious inputs:
+```python
+parser.add_argument("filename", help="File to process")
+```
+**Flags** for optional behavior:
+```python
+parser.add_argument("--verbose", "-v", action="store_true")
+parser.add_argument("--format", choices=["json", "csv"], default="json")
+```
+**Environment variable fallbacks** for secrets:
+```python
+parser.add_argument(
+    "--api-key",
+    default=os.environ.get("API_KEY"),
+    help="API key (default: $API_KEY)"
+)
+```
+### Subcommands for Multi-Action Scripts
+```python
+subparsers = parser.add_subparsers(dest="command", required=True)
+fetch_parser = subparsers.add_parser("fetch", help="Fetch data from API")
+fetch_parser.add_argument("--since", help="Fetch records since date")
+export_parser = subparsers.add_parser("export", help="Export data to file")
+export_parser.add_argument("--format", choices=["json", "csv"])
+```
+## Best Practices
+### Environment Variables
+- Use for secrets (API keys, passwords, tokens)
+- Use for environment-specific config (URLs, paths)
+- Document all required/optional env vars in help text
+- Validate early and fail fast with clear error messages
+### Error Handling
+- Catch specific exceptions, not bare `except:`
+- Log errors before exiting
+- Use appropriate exit codes (0=success, 1=error, 130=interrupted)
+- Include context in error messages
+### Output
+- Default to stdout for piping compatibility
+- Use `--output` flag for file output
+- Support `-` as stdout alias
+- Use JSON for structured output, plain text for human output
+### Logging
+- Use `logging` module, not `print()`
+- Default to INFO level, `--verbose` for DEBUG
+- Include timestamps in format
+- Log to stderr so stdout stays clean for data
+## Examples
+### API Client Script
+```python
+#!/usr/bin/env python3
+"""Fetch user data from Example API."""
+import argparse
+import json
+import logging
+import os
+import sys
+import urllib.request
+import urllib.error
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+logger = logging.getLogger(__name__)
+def fetch_user(user_id, api_key, base_url):
+    """Fetch a single user by ID."""
+    url = f"{base_url}/users/{user_id}"
+    headers = {"Authorization": f"Bearer {api_key}"}
+    req = urllib.request.Request(url, headers=headers)
+    try:
+        with urllib.request.urlopen(req) as response:
+            return json.loads(response.read().decode())
+    except urllib.error.HTTPError as e:
+        logger.error(f"HTTP {e.code}: {e.reason}")
+        return None
+def main():
+    parser = argparse.ArgumentParser(description="Fetch user data from Example API")
+    parser.add_argument("user_id", help="User ID to fetch")
+    parser.add_argument("--api-key", default=os.environ.get("EXAMPLE_API_KEY"))
+    parser.add_argument("--base-url", default="https://api.example.com/v1")
+    args = parser.parse_args()
+    if not args.api_key:
+        logger.error("API key required. Set EXAMPLE_API_KEY or use --api-key")
+        sys.exit(1)
+    user = fetch_user(args.user_id, args.api_key, args.base_url)
+    if user:
+        print(json.dumps(user, indent=2))
+    else:
+        sys.exit(1)
+if __name__ == "__main__":
+    main()
+```
+### Data Transformation Script
+```python
+#!/usr/bin/env python3
+"""Transform CSV data to JSON format."""
+import argparse
+import csv
+import json
+import sys
+def transform_row(row, columns):
+    """Transform a single row to a dictionary."""
+    return {col: row.get(col, "") for col in columns}
+def main():
+    parser = argparse.ArgumentParser(description="Transform CSV to JSON")
+    parser.add_argument("input", nargs="?", default="-", help="Input CSV (default: stdin)")
+    parser.add_argument("--output", "-o", default="-", help="Output JSON (default: stdout)")
+    parser.add_argument("--columns", "-c", help="Comma-separated columns to include")
+    parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON output")
+    args = parser.parse_args()
+    infile = sys.stdin if args.input == "-" else open(args.input)
+    outfile = sys.stdout if args.output == "-" else open(args.output, "w")
+    try:
+        reader = csv.DictReader(infile)
+        columns = args.columns.split(",") if args.columns else reader.fieldnames
+        results = [transform_row(row, columns) for row in reader]
+        indent = 2 if args.pretty else None
+        json.dump(results, outfile, indent=indent)
+        outfile.write("\n")
+    finally:
+        if args.input != "-":
+            infile.close()
+        if args.output != "-":
+            outfile.close()
+if __name__ == "__main__":
+    main()
+```
+## After Script Creation
+1. **Test the script** with sample data
+2. **Make executable**: `chmod +x script.py`
+3. **Consider adding** to a `scripts/` directory in the project
+4. **Document** in README if it's a project utility

package/template/claude/skills/design-feature/SKILL.md CHANGED Viewed

@@ -39,7 +39,7 @@ Output a contract summary:
 ### Phase 2: UI Design
-After contract agreement, draft the UI layout in `claude/docs/UI_LAYOUT.md`.
+After contract agreement, draft the UI layout (to be included in the ticket).
 Include:
@@ -106,6 +106,6 @@ UI Layout template:
 1. User describes feature idea
 2. Ask clarifying questions (no assumptions)
 3. Draft and agree on contract
-4. Draft UI layout in `claude/docs/UI_LAYOUT.md`
+4. Draft UI layout
 5. Review UI together, adjust as needed
-6. Only after agreement, proceed to implementation
+6. Only after agreement, proceed to creation of ticket (include UI layout in the ticket)

package/template/claude/skills/skill-creator/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: skill-creator
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+description: Meta-skill by Anthropic to help guide creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
 license: Complete terms in LICENSE.txt
 ---

package/template/claude/docs/ROADMAP.md DELETED Viewed

@@ -1,62 +0,0 @@
-# ROADMAP
-## Overview
-High-level overview of the project, what it does, the main features
-## Development Workflow
-1. **Task Planning**
-   - Study the existing codebase and understand the current state
-   - Use the **planner** agent to break down complex problems and create implementation roadmaps
-   - Update `ROADMAP.md` to include the new task under Development
-   - Priority tasks should be inserted after the last completed task
-2. **Ticket Creation**
-   - Study the existing codebase and understand the current state
-   - Create a new ticket file in the `/tickets` directory
-   - Name format: `TICKET-XXX-description.md` (e.g., `TICKET-001-user-auth.md`)
-   - Include high-level specifications, relevant files, acceptance criteria, and implementation steps
-   - Refer to last completed ticket in the `/tickets` directory for examples
-   - Note that completed tickets show checked boxes and summary of changes
-   - For new tickets, use empty checkboxes and no summary section
-3. **Task Implementation**
-   - Use the **backend** or **frontend** agent for implementing features, fixing bugs, and optimizing code
-   - Follow the specifications in the ticket file
-   - Implement features and functionality following project conventions
-   - Update step progress within the ticket file after each step
-   - Stop after completing each step and wait for further instructions
-4. **Quality Assurance**
-   - Use the **checker** agent for testing, security analysis, and code review
-   - Verify all acceptance criteria are met
-   - Run tests and ensure code quality standards
-   - Document any issues found and their resolutions
-5. **Roadmap Updates**
-   - Mark completed tasks with ✅ in the roadmap
-   - Add reference to the ticket file (e.g., `See: /tickets/TICKET-001-user-auth.md`)
-## Development
-### Project Setup and Boilerplate
-- [x] Create Claude Code boilerplate structure ✅
-  - Set up CLAUDE.md with project instructions
-  - Create agents directory with planner, checker, backend, and frontend agents
-  - Establish docs, skills, and tickets directories
-  - Add README files to all directories
-### [Add your project tasks here]
-- [ ] Task description
-  - Subtask 1
-  - Subtask 2
-  - See: /tickets/TICKET-XXX-description.md
-## Future Enhancements
-[List potential future features and improvements]
-## Completed Tasks Archive
-[Move completed sections here to keep the active roadmap clean]