create-kuckit-app 0.1.1 → 0.2.0

package/templates/base/.claude/commands/create-plan.md

@@ -0,0 +1,159 @@
+---
+description: Generate a structured Kuckit module implementation plan from brainstorming
+argument-hint: <module-name-or-raw-plan-description>
+---
+
+# Create Structured Module Implementation Plan
+
+You are tasked with transforming raw brainstorming or rough feature ideas into a complete, structured implementation plan following Kuckit module conventions.
+
+## Step 1: Gather Raw Plan Input
+
+First, review the context provided: `$ARGUMENTS`
+
+If no specific plan/brainstorming is provided, ask the user:
+
+> What module would you like to plan? Please describe:
+>
+> 1. **Module name** (e.g., "notifications", "billing", "analytics")
+> 2. **Core features** (what should it do?)
+> 3. **User flows** (how will users interact with it?)
+> 4. **Data needs** (what entities/tables are needed?)
+
+## Step 2: Read the Template
+
+Read the plan template to understand the required structure:
+
+```
+history/PLAN_TEMPLATE.md
+```
+
+Reference this template for all 10 sections that must be populated.
+
+## Step 3: Extract Module Metadata
+
+From the raw input, identify and confirm with the user:
+
+| Field               | Example                        | Your Value |
+| ------------------- | ------------------------------ | ---------- |
+| Module ID           | `kuckit.notifications`         | ?          |
+| Module Display Name | `Notifications`                | ?          |
+| Package Name        | `@kuckit/notifications-module` | ?          |
+| Primary Route       | `/notifications`               | ?          |
+| Brief Description   | One-line summary               | ?          |
+
+## Step 4: Design Data Model
+
+Based on the features, design the database schema:
+
+1. **Identify Entities** - What are the core objects? (e.g., Notification, NotificationPreference)
+2. **Define Tables** - What columns does each table need?
+3. **Map Relationships** - How do entities relate to each other and to `user`?
+4. **Define Enums** - What status/type enums are needed?
+5. **Plan Indexes** - What queries will be common?
+
+Document your proposed schema before proceeding.
+
+## Step 5: Identify Use Cases
+
+List all use cases following the naming convention `make{Action}{Entity}`:
+
+| Use Case                   | Type  | Description               |
+| -------------------------- | ----- | ------------------------- |
+| `makeCreateNotification`   | write | Create a new notification |
+| `makeGetUserNotifications` | read  | List user's notifications |
+| `makeMarkNotificationRead` | write | Mark notification as read |
+
+For each use case, identify:
+
+- Input parameters
+- Output shape
+- Auth requirements (public vs authed)
+- Side effects (emails, webhooks, etc.)
+
+## Step 6: Map User Flows
+
+Create sequence diagrams for the main flows:
+
+1. **Primary happy path** - The main user journey
+2. **Secondary flows** - Alternative paths, edge cases
+3. **Error flows** - What happens when things fail?
+
+Use ASCII sequence diagrams as shown in the template.
+
+## Step 7: Generate the Complete Plan
+
+Now generate the full plan document with ALL 10 sections:
+
+1. **Executive Summary** - 3-4 bullet points on what this implements
+2. **Module Structure** - Directory tree with actual file names
+3. **Architecture Overview** - ASCII diagram showing layer interactions
+4. **Flows** - Sequence diagrams and data tables
+5. **Module Implementation** - Complete code snippets for:
+   - 5.1 Package.json
+   - 5.2 Database Schema (Drizzle)
+   - 5.3 Repository (interface + factory)
+   - 5.4 Use Cases (at least 2-3 examples)
+   - 5.5 oRPC Router
+   - 5.6 Server Module Definition
+   - 5.7 Client Module Definition
+   - 5.8 Client Page/Component
+6. **External Integrations** (if applicable)
+7. **Security Considerations** - Table of security measures
+8. **Error Handling** - Table of error codes/messages
+9. **Implementation Order** - Day-by-day breakdown
+10. **Summary** - Exports, patterns, scope
+
+## Step 8: Save the Plan
+
+Save the generated plan to:
+
+```
+history/{{MODULE_NAME}}_PLAN.md
+```
+
+For example: `history/NOTIFICATIONS_PLAN.md`
+
+## Step 9: Summarize and Next Steps
+
+After saving, provide:
+
+1. **Plan location** - Where the file was saved
+2. **Key decisions made** - Summarize the main design choices
+3. **Open questions** - Any ambiguities that need user input
+4. **Suggested next steps**:
+   - Review the plan
+   - Run `/file-beads` to create issues from the plan
+   - Begin implementation following the Implementation Order
+
+## Quality Checklist
+
+Before finalizing, verify:
+
+- [ ] All 10 template sections are populated
+- [ ] Code snippets follow Kuckit conventions (factory functions, typed cradles)
+- [ ] Database schema includes proper indexes
+- [ ] Use cases have clear input/output types
+- [ ] Flows show complete user journeys
+- [ ] Security considerations are addressed
+- [ ] Error handling covers common failure modes
+- [ ] Implementation order is realistic (5 days typical)
+
+## Iteration
+
+You may iterate on the plan up to 3 times based on user feedback. After 3 iterations, suggest moving to implementation.
+
+Track iterations:
+
+- Iteration 1: Initial plan generation
+- Iteration 2: Refinements based on feedback
+- Iteration 3: Final polish
+
+## Reference Documents
+
+For context on Kuckit conventions, you may reference:
+
+- `AGENTS.md` - Project architecture overview
+- `packages/sdk/docs/MODULE_DEVELOPMENT.md` - Module development guide
+- `history/CLI_AUTHORIZATION_PLAN.md` - Example completed plan
+- `apps/server/AGENTS.md` - Server-specific patterns (especially oRPC routes)

package/templates/base/.claude/commands/file-beads.md

@@ -0,0 +1,98 @@
+---
+description: File detailed Beads epics and issues from a plan
+argument-hint: <plan-description-or-context>
+---
+
+# File Beads Epics and Issues from Plan
+
+You are tasked with converting a plan into a comprehensive set of Beads epics and issues. Follow these steps carefully:
+
+## Step 1: Understand the Plan
+
+First, review the plan context provided: `$ARGUMENTS`
+
+If no specific plan is provided, ask the user to share the plan or point to a planning document (check `history/` directory for recent plans).
+
+## Step 2: Analyze and Structure
+
+Before filing any issues, analyze the plan for:
+
+1. **Major workstreams** - These become epics
+2. **Individual tasks** - These become issues under epics
+3. **Dependencies** - What must complete before other work can start?
+4. **Parallelization opportunities** - What can be worked on simultaneously?
+5. **Technical risks** - What needs spikes or investigation first?
+
+## Step 3: File Epics First
+
+Create epics for major workstreams using:
+
+```bash
+bd create "Epic: <title>" -t epic -p <priority> --json
+```
+
+Epics should:
+
+- Have clear, descriptive titles
+- Include acceptance criteria in the description
+- Be scoped to deliverable milestones
+
+## Step 4: File Detailed Issues
+
+For each epic, create child issues with:
+
+```bash
+bd create "<task title>" -t <type> -p <priority> --deps <parent-epic-id> --json
+```
+
+Each issue MUST include:
+
+- **Clear title** - Action-oriented (e.g., "Implement X", "Add Y", "Configure Z")
+- **Detailed description** - What exactly needs to be done
+- **Acceptance criteria** - How do we know it's done?
+- **Technical notes** - Implementation hints, gotchas, relevant files
+- **Dependencies** - Link to blocking issues with `--deps bd-<id>`
+
+## Step 5: Map Dependencies Carefully
+
+For each issue, consider:
+
+- Does this depend on another issue completing first?
+- Can this be worked on in parallel with siblings?
+- Are there cross-epic dependencies?
+
+Use `--deps bd-X,bd-Y` for multiple dependencies.
+
+## Step 6: Set Priorities Thoughtfully
+
+- `0` - Critical path blockers, security issues
+- `1` - Core functionality, high business value
+- `2` - Standard work items (default)
+- `3` - Nice-to-haves, polish
+- `4` - Backlog, future considerations
+
+## Step 7: Verify the Graph
+
+After filing all issues, run:
+
+```bash
+bd list --json
+bd ready --json
+```
+
+Verify:
+
+- All epics have child issues
+- Dependencies form a valid DAG (no cycles)
+- Ready work exists (some issues have no blockers)
+- Priorities make sense for execution order
+
+## Output Format
+
+After completing, provide:
+
+1. Summary of epics created
+2. Summary of issues per epic
+3. Dependency graph overview (what unblocks what)
+4. Suggested starting points (ready issues)
+5. Parallelization opportunities

package/templates/base/.claude/commands/review-beads.md

@@ -0,0 +1,161 @@
+---
+description: Review, proofread, and refine filed Beads epics and issues
+argument-hint: [optional: specific epic or issue IDs to focus on]
+---
+
+# Review and Refine Beads Issues
+
+You are tasked with thoroughly reviewing, proofreading, and polishing the filed Beads epics and issues to ensure workers have a smooth implementation experience.
+
+## Step 1: Load Current Issues
+
+First, get the current state:
+
+```bash
+bd list --json
+bd ready --json
+```
+
+If specific IDs were provided (`$ARGUMENTS`), focus on those. Otherwise, review all issues.
+
+## Step 2: Systematic Review Checklist
+
+For EACH issue, verify:
+
+### Clarity
+
+- [ ] Title is action-oriented and specific
+- [ ] Description is clear and unambiguous
+- [ ] A developer unfamiliar with the codebase could understand the task
+- [ ] No jargon without explanation
+
+### Completeness
+
+- [ ] Acceptance criteria are defined and testable
+- [ ] Technical implementation hints are provided where helpful
+- [ ] Relevant file paths or modules are mentioned
+- [ ] Edge cases and error handling are considered
+
+### Dependencies
+
+- [ ] All blocking dependencies are linked
+- [ ] No circular dependencies exist
+- [ ] Dependencies are minimal (not over-constrained)
+- [ ] Ready issues exist for parallel work
+
+### Scope
+
+- [ ] Issue is appropriately sized (not too large)
+- [ ] Large issues are broken into subtasks
+- [ ] No duplicate or overlapping issues
+
+### Priority
+
+- [ ] Priority reflects actual importance
+- [ ] Critical path items are prioritized correctly
+- [ ] Dependencies and priorities align
+
+## Step 3: Common Issues to Fix
+
+Watch for and correct:
+
+1. **Vague titles**: "Fix bug" → "Fix null pointer in UserService.getProfile when user not found"
+2. **Missing context**: Add relevant file paths, function names, or module references
+3. **Implicit knowledge**: Make assumptions explicit
+4. **Missing acceptance criteria**: Add "Done when..." statements
+5. **Over-coupling**: Break dependencies that aren't strictly necessary
+6. **Under-specified**: Add technical notes for complex tasks
+7. **Duplicate work**: Merge or link related issues
+8. **Missing dependencies**: Link issues that should be sequenced
+9. **Wrong priorities**: Adjust based on critical path analysis
+10. **Typos and grammar**: Fix for professionalism
+
+## Step 4: Update Issues
+
+Use bd update to fix issues:
+
+```bash
+bd update <id> --title "Improved title" --json
+bd update <id> --priority <new-priority> --json
+bd update <id> --description "New description" --json
+bd update <id> --acceptance "Acceptance criteria" --json
+```
+
+Manage dependencies separately with `bd dep`:
+
+```bash
+bd dep add <issue-id> <dependency-id> --json   # Add dependency
+bd dep remove <issue-id> <dependency-id> --json # Remove dependency
+bd dep tree <issue-id> --json                   # View dependency tree
+bd dep cycles --json                            # Check for circular deps
+```
+
+For major rewrites, close and recreate:
+
+```bash
+bd close <id> --reason "Replaced by <new-id>" --json
+bd create "Better title" -t <type> -p <priority> --deps <dep-id> --json
+```
+
+## Step 5: Dependency Graph Validation
+
+After refinements, validate:
+
+```bash
+bd list --json                    # View all issues
+bd list --status open --json      # View only open issues
+bd ready --json                   # View unblocked issues ready for work
+bd dep cycles --json              # Check for circular dependencies
+bd dep tree <epic-id> --json      # View dependency tree for an epic
+```
+
+Check:
+
+- No orphaned issues (except entry points)
+- No circular dependencies
+- Critical path is clear
+- Parallelization opportunities are preserved
+
+## Step 6: Final Quality Gate
+
+Before completing, ensure:
+
+1. **Readability**: Any developer can pick up any ready issue
+2. **Traceability**: Issues link to epics, epics link to the plan
+3. **Testability**: Each issue has clear "done" criteria
+4. **Parallelism**: Multiple issues can be worked simultaneously
+5. **Completeness**: No gaps in the plan coverage
+
+## Output Format
+
+Provide a review report:
+
+### Summary
+
+- Total issues reviewed: X
+- Issues updated: Y
+- Issues created: Z
+- Issues closed/merged: W
+
+### Changes Made
+
+- List significant updates with rationale
+
+### Remaining Concerns
+
+- Any issues that need user input
+- Ambiguities that couldn't be resolved
+
+### Ready for Implementation
+
+- List of ready issues workers can start with
+- Suggested execution order for optimal flow
+
+## Iteration Tracking
+
+You may iterate on refinements up to 5 times if asked. Track iterations:
+
+- Iteration 1: Initial review pass
+- Iteration 2-5: Deeper refinements based on feedback
+
+After 5 iterations, respond: "I don't think we can do much better than this. The issues are thoroughly reviewed, well-documented, and ready for workers to implement."

package/templates/base/.claude/settings.json

@@ -0,0 +1,11 @@
+{
+	"permissions": {
+		"allow": ["Bash(bd:*)"]
+	},
+	"mcpServers": {
+		"shadcn": {
+			"command": "npx",
+			"args": ["shadcn@latest", "mcp"]
+		}
+	}
+}