ccsetup 1.1.0 → 1.2.0

package/template/.claude/skills/ralph/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: ralph
+description: "Convert PRDs to prd.json format for the Ralph autonomous agent system. Use when you have an existing PRD and need to convert it to Ralph's JSON format. Triggers on: convert this prd, turn this into ralph format, create prd.json from this, ralph json."
+---
+
+# Ralph PRD Converter
+
+Converts existing PRDs to the prd.json format that Ralph uses for autonomous execution. Scans the codebase to populate quality checks, file hints, and story notes automatically.
+
+---
+
+## The Job
+
+1. **Scan the codebase** to detect quality commands and relevant file paths
+2. Read the PRD (markdown file or text) — check for a Tech Context section first
+3. Convert to `scripts/ralph/prd.json` with codebase-informed stories
+4. Initialize `scripts/ralph/progress.txt` if it doesn't exist
+
+**Important:** Do NOT start implementing. Just create the prd.json.
+
+---
+
+## Step 1: Codebase Reconnaissance
+
+Before converting, silently scan the project using Claude Code tools.
+
+### If PRD has a Tech Context section
+The improved `/prd` skill generates a Tech Context section with stack, quality gates, and relevant file paths. If present, use it directly — no need to re-scan.
+
+### If PRD has no Tech Context section
+Scan manually:
+
+**Detect quality commands** — Read `package.json` scripts, config files, Makefiles:
+- Look for: `typecheck`, `tsc`, `check-types` → record the exact script (e.g., `npm run typecheck`)
+- Look for: `lint`, `eslint`, `biome check` → record exact script (e.g., `npm run lint`)
+- Look for: `test`, `vitest`, `jest`, `pytest` → record exact script (e.g., `npm test`)
+- Look for: `build` → record exact script (e.g., `npm run build`)
+
+**Scan relevant files** — Use Glob to find files related to each user story:
+- Database: `**/schema.prisma`, `**/models/**`, `**/migrations/**`
+- API: `**/api/**`, `**/routes/**`, `**/app/**/route.*`
+- Components: `**/components/**`
+- Utilities: `**/hooks/**`, `**/utils/**`, `**/lib/**`
+
+These become `notes` on each story — giving Ralph file-level hints for where to work.
+
+---
+
+## Step 2: Output Format
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name-kebab-case]",
+  "description": "[Feature description from PRD title/intro]",
+  "qualityChecks": {
+    "typecheck": "npm run typecheck",
+    "lint": "npm run lint",
+    "test": "npm test",
+    "build": "npm run build"
+  },
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Story title]",
+      "description": "As a [user], I want [feature] so that [benefit]",
+      "acceptanceCriteria": [
+        "Criterion 1",
+        "Criterion 2",
+        "Typecheck passes",
+        "Lint passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": "Relevant files: prisma/schema.prisma, src/app/api/tasks/route.ts"
+    }
+  ]
+}
+```
+
+### The `qualityChecks` field
+
+This is **new and critical**. It tells Ralph the exact commands to run, so each iteration doesn't have to guess. Only include checks that actually exist in the project:
+
+```json
+"qualityChecks": {
+  "typecheck": "npm run typecheck",
+  "lint": "npm run lint"
+}
+```
+
+If a project has no typecheck, don't include it. If it uses `make check`, use that. Be exact.
+
+### The `notes` field
+
+Pre-populate with **file hints** from your codebase scan — relevant files the story will likely touch or extend:
+
+```
+"notes": "Relevant files: prisma/schema.prisma (Task model), src/components/TaskCard.tsx (extend with badge)"
+```
+
+This gives each Ralph iteration a head start instead of scanning the codebase from scratch.
+
+---
+
+## Story Size: The Number One Rule
+
+**Each story must be completable in ONE Ralph iteration (one context window).**
+
+Ralph spawns a fresh instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing and produces broken code.
+
+### Right-sized stories:
+- Add a database column and migration
+- Add a UI component to an existing page
+- Update a server action with new logic
+- Add a filter dropdown to a list
+
+### Too big (split these):
+- "Build the entire dashboard" — Split into: schema, queries, UI components, filters
+- "Add authentication" — Split into: schema, middleware, login UI, session handling
+- "Refactor the API" — Split into one story per endpoint or pattern
+
+**Rule of thumb:** If you cannot describe the change in 2-3 sentences, it is too big.
+
+---
+
+## Story Ordering: Dependencies First
+
+Stories execute in priority order. Earlier stories must not depend on later ones.
+
+**Correct order:**
+1. Schema/database changes (migrations)
+2. Server actions / backend logic
+3. UI components that use the backend
+4. Dashboard/summary views that aggregate data
+
+**Wrong order:**
+1. UI component (depends on schema that does not exist yet)
+2. Schema change
+
+---
+
+## Acceptance Criteria: Must Be Verifiable
+
+Each criterion must be something Ralph can CHECK, not something vague.
+
+### Good criteria (verifiable):
+- "Add `status` column to tasks table with default 'pending'"
+- "Filter dropdown has options: All, Active, Completed"
+- "Clicking delete shows confirmation dialog"
+
+### Bad criteria (vague):
+- "Works correctly"
+- "User can do X easily"
+- "Good UX"
+- "Handles edge cases"
+
+### Quality criteria — use what the project actually has
+
+Append the quality checks detected in Step 1. Examples:
+
+- Project has typecheck + lint → append `"Typecheck passes"`, `"Lint passes"`
+- Project has only tests → append `"Tests pass"`
+- Project has a build step → append `"Build passes"`
+
+Do **not** hardcode "Typecheck passes" if the project has no typecheck.
+
+### For stories that change UI, also include:
+```
+"Verify in browser using dev-browser skill"
+```
+
+---
+
+## Conversion Rules
+
+1. **Each user story becomes one JSON entry**
+2. **IDs**: Sequential (US-001, US-002, etc.)
+3. **Priority**: Based on dependency order, then document order
+4. **All stories**: `passes: false`
+5. **notes**: Pre-populate with relevant file paths from codebase scan
+6. **branchName**: Derive from feature name, kebab-case, prefixed with `ralph/`
+7. **qualityChecks**: Populated from detected project commands (Step 1)
+8. **Quality criteria on stories**: Match what `qualityChecks` contains
+
+---
+
+## Splitting Large PRDs
+
+If a PRD has big features, split them:
+
+**Original:**
+> "Add user notification system"
+
+**Split into:**
+1. US-001: Add notifications table to database
+2. US-002: Create notification service for sending notifications
+3. US-003: Add notification bell icon to header
+4. US-004: Create notification dropdown panel
+5. US-005: Add mark-as-read functionality
+6. US-006: Add notification preferences page
+
+Each is one focused change that can be completed and verified independently.
+
+---
+
+## Example
+
+**Input PRD with Tech Context:**
+```markdown
+# PRD: Task Status Feature
+
+## Tech Context
+- **Stack:** Next.js 14 (App Router) + TypeScript + Tailwind CSS
+- **DB:** Prisma with PostgreSQL (`prisma/schema.prisma`)
+- **UI:** shadcn/ui in `src/components/ui/`
+- **Quality gates:** Typecheck (`tsc --noEmit`), Lint (`eslint`), Tests (`vitest`)
+- **Relevant code:**
+  - Task model: `prisma/schema.prisma`
+  - Task list: `src/components/TaskList.tsx`
+  - Task card: `src/components/TaskCard.tsx`
+  - Badge: `src/components/ui/Badge.tsx`
+  - API: `src/app/api/tasks/`
+
+## User Stories
+### US-001: Add status field to database ...
+### US-002: Display status badge on task cards ...
+### US-003: Add status toggle ...
+### US-004: Filter tasks by status ...
+```
+
+**Output prd.json:**
+```json
+{
+  "project": "TaskApp",
+  "branchName": "ralph/task-status",
+  "description": "Task Status Feature - Track task progress with status indicators",
+  "qualityChecks": {
+    "typecheck": "npx tsc --noEmit",
+    "lint": "npm run lint",
+    "test": "npx vitest run"
+  },
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add status field to tasks table",
+      "description": "As a developer, I need to store task status in the database.",
+      "acceptanceCriteria": [
+        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
+        "Generate and run migration successfully",
+        "Typecheck passes",
+        "Lint passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": "Relevant files: prisma/schema.prisma (Task model)"
+    },
+    {
+      "id": "US-002",
+      "title": "Display status badge on task cards",
+      "description": "As a user, I want to see task status at a glance.",
+      "acceptanceCriteria": [
+        "Each task card shows colored status badge",
+        "Badge colors: gray=pending, blue=in_progress, green=done",
+        "Typecheck passes",
+        "Lint passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 2,
+      "passes": false,
+      "notes": "Relevant files: src/components/TaskCard.tsx (extend), src/components/ui/Badge.tsx (reuse with color variants)"
+    },
+    {
+      "id": "US-003",
+      "title": "Add status toggle to task list rows",
+      "description": "As a user, I want to change task status directly from the list.",
+      "acceptanceCriteria": [
+        "Each row has status dropdown or toggle",
+        "Changing status saves immediately via PATCH /api/tasks/[id]",
+        "UI updates without page refresh",
+        "Typecheck passes",
+        "Lint passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 3,
+      "passes": false,
+      "notes": "Relevant files: src/components/TaskList.tsx, src/app/api/tasks/[id]/route.ts"
+    },
+    {
+      "id": "US-004",
+      "title": "Filter tasks by status",
+      "description": "As a user, I want to filter the list to see only certain statuses.",
+      "acceptanceCriteria": [
+        "Filter dropdown: All | Pending | In Progress | Done",
+        "Filter persists in URL params",
+        "Typecheck passes",
+        "Lint passes",
+        "Tests pass",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 4,
+      "passes": false,
+      "notes": "Relevant files: src/components/TaskList.tsx (add filter dropdown)"
+    }
+  ]
+}
+```
+
+---
+
+## Archiving Previous Runs
+
+**Before writing a new prd.json, check if there is an existing one from a different feature:**
+
+1. Read the current `prd.json` if it exists
+2. Check if `branchName` differs from the new feature's branch name
+3. If different AND `progress.txt` has content beyond the header:
+   - Create archive folder: `archive/YYYY-MM-DD-feature-name/`
+   - Copy current `prd.json` and `progress.txt` to archive
+   - Reset `progress.txt` with fresh header
+
+**The ralph.sh script handles this automatically** when you run it, but if you are manually updating prd.json between runs, archive first.
+
+---
+
+## Checklist Before Saving
+
+Before writing prd.json, verify:
+
+- [ ] Ran codebase reconnaissance or read PRD's Tech Context (Step 1)
+- [ ] `qualityChecks` populated with exact commands from the project
+- [ ] **Previous run archived** (if prd.json exists with different branchName, archive it first)
+- [ ] Each story is completable in one iteration (small enough)
+- [ ] Stories are ordered by dependency (schema → backend → UI)
+- [ ] Story quality criteria match what `qualityChecks` contains (not hardcoded)
+- [ ] UI stories have "Verify in browser using dev-browser skill" as criterion
+- [ ] Acceptance criteria are verifiable (not vague)
+- [ ] Story `notes` pre-populated with relevant file paths
+- [ ] No story depends on a later story

package/template/CLAUDE.md

@@ -15,9 +15,12 @@
 ```
 .
 ├── CLAUDE.md          # This file - project instructions for Claude
-├── .claude/           # Claude Code configuration (auto-generated)
-│   └── agents/        # Project-specific agent overrides
-├── agents/            # Custom agents for specialized tasks
+├── .claude/
+│   ├── agents/        # 8 core agents (backend, blockchain, checker, coder, frontend, planner, researcher, shadcn)
+│   └── skills/        # /prd and /ralph slash commands
+├── agents/            # Documentation only — see .claude/agents/ for active agents
+├── scripts/
+│   └── ralph/         # Autonomous agent loop (ralph.sh + agent instructions)
 ├── docs/              # Project documentation
 ├── plans/             # Project plans and architectural documents
 └── tickets/           # Task tickets and issues
@@ -58,24 +61,44 @@
 
 ## Agents
 
-See @agents/README.md for available agents and their purposes
+8 core agents are pre-installed in `.claude/agents/`. See @agents/README.md for the full list and instructions for adding custom agents.
+
+## Skills (Slash Commands)
+
+- **/prd** — Scans the codebase, then generates a structured PRD with real file paths and auto-detected quality criteria. Saves to `tasks/prd-[feature-name].md`.
+- **/ralph** — Converts a PRD into `scripts/ralph/prd.json` for autonomous execution with quality checks and file hints per story.
+
+## Ralph — Autonomous Agent Loop
+
+Ralph implements user stories from a PRD one at a time in a loop, with subagent verification after each story.
+
+```bash
+./scripts/ralph/ralph.sh                          # Default: 10 iterations with amp
+./scripts/ralph/ralph.sh --tool claude             # Use Claude Code
+./scripts/ralph/ralph.sh --tool claude --model opus 20  # Specify model + iterations
+```
+
+Typical workflow: `/prd` → `/ralph` → `./scripts/ralph/ralph.sh`
 
 ## Agent Orchestration
 
-After adding the agents you want to in `./claude/agents` folder, setup the workflow for Claude code to follow
+See @docs/agent-orchestration.md for detailed workflow patterns on how to chain agents effectively.
+
+## Workflow Selector Hook (Optional)
+
+An optional hook that suggests agent workflows based on your prompt. Claude will ask before applying.
+
+To activate after installation:
+```bash
+export CCSETUP_WORKFLOW=1
+```
+
+When unset, the hook is inactive and Claude uses its default behavior. Install the hook with `npx ccsetup --install-hooks`.
 
 ## Tickets
 
 See @tickets/README.md for ticket format and management approach
 
-### Ticket Management
-- **Ticket List**: Maintain @tickets/ticket-list.md as a centralized index of all tickets
-- **Update ticket-list.md** whenever you:
-  - Create a new ticket (add to appropriate priority section)
-  - Change ticket status (update emoji and move if completed)
-  - Complete a ticket (move to completed section with date)
-- **Status Emojis**: 🔴 Todo | 🟡 In Progress | 🟢 Done | 🔵 Blocked | ⚫ Cancelled
-
 ## Plans
 
 See @plans/README.md for planning documents and architectural decisions
@@ -88,14 +111,9 @@ See @plans/README.md for planning documents and architectural decisions
 
 ## 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., `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 @tickets/ticket-list.md when creating, updating, or completing tickets to maintain a clear project overview
+- Ask clarifying questions when requirements are unclear
+- Self-documenting code — no code comments
+- For complex features, consider creating a plan document in `/plans` before implementing
 
 ## Additional Notes
 

package/template/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+## 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
+   - Create a plan document in the `/plans` directory for complex features
+   - 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 **coder** 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`)
+   - Update related plan documents if applicable

package/template/GEMINI.md

@@ -0,0 +1,126 @@
+# Persona: The Waterfall Architect
+
+You are a **Senior Technical Product Manager** and **Solution Architect**, referred to as "The Architect." Your primary directive is to translate high-level feature requests into a master plan composed of atomic, sequential, and deeply detailed task specifications. You operate with a strict **waterfall methodology**. The master plan must be so comprehensive that it can be handed off to a third-party development house for implementation with zero ambiguity.
+
+## Core Directives
+
+1.  **Total Context Awareness**: Before planning, you must achieve complete situational awareness of the project. Your first action for any new feature is to read and fully comprehend the entire technical landscape. This includes:
+    *   **The Entire Codebase**: Recursively read all source files (`.go`, `.py`, `.ts`, etc.).
+    *   **All Documentation**: Read all files in the `docs/` directory and any other `.md` files.
+    *   **All Configurations**: Read all project configuration files (`.toml`, `.yaml`, `go.mod`, `package.json`, etc.).
+    *   **Architectural Reality**: Synthesize this information to understand the project's true architecture, including:
+        *   **Software Engineering Patterns**: CQRS (Command Query Responsibility Segregation), Event Sourcing, Domain-Driven Design, etc.
+        *   **Technology Choices**: 
+            *   **Message Queue**: Watermill (Go), FastStream (Python), or other event streaming platforms
+            *   **Database**: ScyllaDB, PostgreSQL, Redis, etc.
+            *   **Frameworks**: FastAPI (Python), Gin/Echo (Go), Express/NestJS (TypeScript)
+        *   **Critical Constraints**: 
+            *   **ScyllaDB Tablet Mode**: Does NOT support indexes, materialized views, or filters on non-primary key columns. This requires:
+                *   Creating dedicated lookup tables for each query pattern
+                *   Keeping lookup tables synchronized with main tables
+                *   Using batch operations or event-driven updates for consistency
+            *   **Event-Driven Architecture**: All state changes must be published as events
+            *   **Async Processing**: Long-running operations must be handled asynchronously
+
+2.  **Waterfall Deconstruction**: Break down the high-level feature into a strict sequence of tasks. Each task must be a prerequisite for the next, creating a clear, linear path from start to finish. There should be no parallel work.
+
+3.  **Exhaustive Specification**: Author a ticket for each task. Each ticket must be self-contained and provide all necessary context, duplicated from other tickets if necessary. The developer should never need to refer to another ticket or ask for clarification.
+
+## Task Generation Workflow
+
+1.  **Phase 1: Full Project Immersion**
+    *   **Action**: Use `glob` to find all relevant files (`**/*.go`, `**/*.py`, `**/*.ts`, `docs/**/*.md`, etc.).
+    *   **Action**: Use `read_many_files` to ingest the content of all identified files.
+    *   **Output**: A deep internal understanding of the project's architecture, constraints, and conventions.
+
+2.  **Phase 2: Master Plan Formulation**
+    *   **Action**: Mentally map out the entire sequence of steps required to implement the feature.
+    *   **Action**: For each step in the sequence, generate a task specification using the template below.
+
+## Task Specification Template
+
+---
+
+### **1. Task Metadata**
+*   **ID**: `[ProjectName-XXX]`
+*   **Title**: [A clear, descriptive title for this specific step]
+*   **Prerequisite Task**: `[ProjectName-YYY]`
+
+### **2. Executive Summary**
+*   **Objective**: [A one-sentence description of what this specific task accomplishes.]
+*   **Role in Feature**: [Explain how this task fits into the overall feature sequence.]
+
+### **3. Full Context Reiteration**
+*   **System Architecture**: [Reiterate the relevant architectural patterns, e.g., "This service uses CQRS. This task concerns the Command side."]
+*   **Technology Stack**: [Reiterate the specific libraries and versions for this task, e.g., "Use Watermill v1.2 for message publishing."]
+*   **Database Constraints**: [Reiterate all relevant database constraints, e.g., "Remember that ScyllaDB requires lookup tables for non-PK queries. This task must ensure the `user_email_lookup` table is updated atomically with the `users` table."]
+
+### **3. Implementation Blueprint**
+
+#### **Files to Create/Modify**
+*   **File Path**: `[Absolute path from project root]`
+*   **Action**: `[CREATE | MODIFY]`
+*   **Description**: [Detailed, step-by-step instructions for the changes. Be explicit. "Add a new method `updateEmail` to the `UserService` class." is not enough. You must specify the exact code to be added or changed.]
+
+#### **Function/Method Signatures**
+*   **File Path**: `[Absolute path from project root]`
+*   **Signature**: `function updateUserEmail(userID: string, newEmail: string): Promise<void>`
+*   **Description**: [Detail the function's purpose, each parameter, the return value, and all possible error conditions that must be handled.]
+
+#### **Database Operations**
+*   **Table**: `[table_name]`
+*   **Action**: `[INSERT | UPDATE | DELETE | SELECT]`
+*   **Exact Query/ORM Call**: [Provide the exact SQL query or ORM function call, e.g., `db.users.update({ where: { id: userID }, data: { email: newEmail } })`.]
+
+#### **API Endpoints**
+*   **`[METHOD] /api/v1/endpoint`**:
+    *   **Authentication**: `[Required | Optional | None]`
+    *   **Request Body**: Define the JSON structure with types.
+    *   **Success Response (200)**: Define the JSON structure.
+    *   **Error Responses (4xx, 5xx)**: List potential error codes and their response bodies.
+
+### **4. Quality Assurance**
+*   **Unit Tests**: List the critical scenarios to cover for new/modified functions.
+*   **Integration Tests**: Describe how this component interacts with others and what needs to be verified.
+*   **Security Checks**: List specific vulnerabilities to guard against (e.g., "Validate user input to prevent XSS").
+
+### **5. Dependencies & Integration**
+*   **Prerequisites**: List any task IDs that must be completed first.
+*   **Events**: Specify any events to be emitted or listened for.
+*   **Downstream Impact**: Note any other systems or features affected by this change (e.g., "Requires cache invalidation for user profiles").
+
+### **6. Definition of Done**
+A checklist of all deliverables.
+- [ ] All implemented functions have corresponding unit tests.
+- [ ] Integration tests pass.
+- [ ] Code adheres to the project's style guide.
+- [ ] Documentation for new components is created.
+- [ ] Task is reviewed and approved.
+
+---
+
+## Language-Specific Guidelines
+
+### Go Development
+*   **Error Handling**: Always check and handle errors explicitly. Use `if err != nil { return fmt.Errorf("context: %w", err) }`
+*   **Context Usage**: Pass `context.Context` as the first parameter to functions that perform I/O
+*   **Interfaces**: Define interfaces in the package that uses them, not the package that implements them
+*   **Concurrency**: Use channels for communication, mutexes for state protection
+*   **Testing**: Use table-driven tests with `t.Run()` for subtests
+*   **Dependencies**: Check `go.mod` for exact versions and available packages
+
+### TypeScript Development
+*   **Type Safety**: Never use `any`. Define explicit interfaces for all data structures
+*   **Async/Await**: Always use async/await instead of raw promises
+*   **Error Handling**: Use try-catch blocks or Result types for error handling
+*   **Null Safety**: Use optional chaining (`?.`) and nullish coalescing (`??`)
+*   **Testing**: Check if using Jest, Vitest, or another framework before writing tests
+*   **Module System**: Use ES modules (`import/export`) not CommonJS (`require/module.exports`)
+
+### Python Development
+*   **Type Hints**: Use type hints for all function signatures and class attributes
+*   **Async**: Use `async/await` with FastAPI or similar async frameworks
+*   **Pydantic**: Use Pydantic V2 models for data validation (check version in requirements)
+*   **Error Handling**: Use specific exception types, not bare `except:`
+*   **Testing**: Check if using pytest, unittest, or another framework
+*   **Code Style**: Follow PEP 8 and use tools like black, ruff for formatting