create-kuckit-app 2.0.2 → 2.2.0

package/README.md

@@ -14,15 +14,6 @@ bun run dev
 
 - Node.js 18+
 - [Bun](https://bun.sh) package manager
-- A Kuckit account at [kuckit.dev](https://kuckit.dev)
-
-## Authentication
-
-You need to authenticate before creating a project:
-
-```bash
-npx @kuckit/cli auth login
-```
 
 ## Usage
 
@@ -44,6 +35,7 @@ The generated project includes:
 - **Web** - React + TanStack Router frontend
 - **Database** - Drizzle ORM with PostgreSQL
 - **Kuckit SDK** - Module system ready to go
+- **Example module** - Items module with full Clean Architecture
 
 ## Project Structure
 
@@ -52,7 +44,8 @@ my-app/
 ├── apps/
 │   ├── server/     # Backend API
 │   └── web/        # Frontend app
-├── packages/       # Shared packages & modules
+├── packages/
+│   └── items-module/  # Example module
 └── kuckit.config.ts
 ```
 
@@ -60,10 +53,27 @@ my-app/
 
 After creating your app:
 
-1. Set up your database (see `packages/db/docker-compose.yml`)
-2. Run migrations: `bun run db:push`
-3. Start development: `bun run dev`
-4. Add modules: `npx @kuckit/cli add <module>`
+1. Set up your database (see `docker-compose.yml` or use a cloud provider)
+2. Configure environment: `cp apps/server/.env.example apps/server/.env`
+3. Push schema: `bun run db:push`
+4. Start development: `bun run dev`
+5. Add modules: `bunx kuckit add <module>`
+
+## Deployment
+
+Deploy to GCP with one command:
+
+```bash
+bun add -D @kuckit/infra-gcp
+bunx kuckit infra up
+```
+
+See the [Deployment Guide](https://github.com/draphonix/kuckit/blob/main/docs/DEPLOYMENT.md) for details.
+
+## Documentation
+
+- [kuckit.dev](https://kuckit.dev) - Full documentation
+- [Architecture](https://github.com/draphonix/kuckit/blob/main/docs/ARCHITECTURE.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-kuckit-app",
-	"version": "2.0.2",
+	"version": "2.2.0",
 	"description": "Create a new Kuckit application",
 	"type": "module",
 	"license": "MIT",
@@ -40,12 +40,14 @@
 	},
 	"scripts": {
 		"build": "tsdown",
+		"test:e2e": "playwright test --config e2e/playwright.config.ts",
 		"prepublishOnly": "npm run build && node ../../scripts/resolve-workspace-protocols.cjs && node ../../scripts/check-no-workspace-protocol.cjs"
 	},
 	"dependencies": {
 		"commander": "^13.1.0"
 	},
 	"devDependencies": {
+		"@playwright/test": "^1.52.0",
 		"@types/node": "^22.13.13",
 		"tsdown": "catalog:"
 	}

package/templates/base/.claude/skills/beads/CLAUDE.md

@@ -0,0 +1,87 @@
+# Beads Skill Maintenance Guide
+
+## Architecture Decisions
+
+ADRs in `adr/` document key decisions. These are NOT loaded during skill invocation—they're reference material for maintainers making changes.
+
+| ADR                                                 | Decision                                        |
+| --------------------------------------------------- | ----------------------------------------------- |
+| [ADR-0001](adr/0001-bd-prime-as-source-of-truth.md) | Use `bd prime` as CLI reference source of truth |
+
+## Key Principle: DRY via bd prime
+
+**NEVER duplicate CLI documentation in SKILL.md or resources.**
+
+- `bd prime` outputs AI-optimized workflow context
+- `bd <command> --help` provides specific usage
+- Both auto-update with bd releases
+
+**SKILL.md should only contain:**
+
+- Decision frameworks (bd vs TodoWrite)
+- Prerequisites (install verification)
+- Resource index (progressive disclosure)
+- Pointers to `bd prime` and `--help`
+
+## Keeping the Skill Updated
+
+### When bd releases new version:
+
+1. **Check for new features**: `bd --help` for new commands
+2. **Update SKILL.md frontmatter**: `version: "X.Y.Z"`
+3. **Add resources for conceptual features** (agents, gates, chemistry patterns)
+4. **Don't add CLI reference** — that's `bd prime`'s job
+
+### What belongs in resources:
+
+| Content Type          | Belongs in Resources? | Why                                    |
+| --------------------- | --------------------- | -------------------------------------- |
+| Conceptual frameworks | ✅ Yes                | bd prime doesn't explain "when to use" |
+| Decision trees        | ✅ Yes                | Cognitive guidance, not CLI reference  |
+| Advanced patterns     | ✅ Yes                | Depth beyond `--help`                  |
+| CLI command syntax    | ❌ No                 | Use `bd <cmd> --help`                  |
+| Workflow checklists   | ❌ No                 | `bd prime` covers this                 |
+
+### Resource update checklist:
+
+```
+[ ] Check if bd prime now covers this content
+[ ] If yes, remove from resources (avoid duplication)
+[ ] If no, update resource for new bd version
+[ ] Update version compatibility in README.md
+```
+
+## File Roles
+
+| File            | Purpose                      | When to Update                      |
+| --------------- | ---------------------------- | ----------------------------------- |
+| SKILL.md        | Entry point, resource index  | New features, version bumps         |
+| README.md       | Human docs, installation     | Structure changes                   |
+| CLAUDE.md       | This file, maintenance guide | Architecture changes                |
+| adr/\*.md       | Decision records             | When making architectural decisions |
+| resources/\*.md | Deep-dive guides             | New conceptual content              |
+
+## Testing Changes
+
+After skill updates:
+
+```bash
+# Verify SKILL.md is within token budget
+wc -w skills/beads/SKILL.md  # Target: 400-600 words
+
+# Verify links resolve
+# (Manual check: ensure all resource links in SKILL.md exist)
+
+# Verify bd prime still works
+bd prime | head -20
+```
+
+## Attribution
+
+Resources adapted from other sources should include attribution header:
+
+```markdown
+# Resource Title
+
+> Adapted from [source]
+```

package/templates/base/.claude/skills/beads/README.md

@@ -0,0 +1,123 @@
+# Beads Skill for Claude Code
+
+A comprehensive skill for using [beads](https://github.com/steveyegge/beads) (bd) issue tracking with Claude Code.
+
+## What This Skill Does
+
+This skill teaches Claude Code how to use bd effectively for:
+
+- **Multi-session work tracking** - Persistent memory across conversation compactions
+- **Dependency management** - Graph-based issue relationships
+- **Session handoff** - Writing notes that survive context resets
+- **Molecules and wisps** (v0.34.0+) - Reusable work templates and ephemeral workflows
+
+## Installation
+
+Copy the `beads/` directory to your Claude Code skills location:
+
+```bash
+# Global installation
+cp -r beads ~/.claude/skills/
+
+# Or project-local
+cp -r beads .claude/skills/
+```
+
+## When Claude Uses This Skill
+
+The skill activates when conversations involve:
+
+- "multi-session", "complex dependencies", "resume after weeks"
+- "project memory", "persistent context", "side quest tracking"
+- Work that spans multiple days or compaction cycles
+- Tasks too complex for simple TodoWrite lists
+
+## File Structure
+
+```
+beads/
+├── SKILL.md                 # Main skill file (Claude reads this first)
+├── CLAUDE.md                # Maintenance guide for updating the skill
+├── README.md                # This file (for humans)
+├── adr/                     # Architectural Decision Records
+│   └── 0001-bd-prime-as-source-of-truth.md
+└── resources/               # Detailed documentation (loaded on demand)
+    ├── BOUNDARIES.md        # When to use bd vs TodoWrite
+    ├── CLI_REFERENCE.md     # CLI command reference
+    ├── DEPENDENCIES.md      # Dependency semantics (A blocks B vs B blocks A)
+    ├── INTEGRATION_PATTERNS.md # TodoWrite and other tool integration
+    ├── ISSUE_CREATION.md    # When and how to create issues
+    ├── MOLECULES.md         # Protos, mols, wisps (v0.34.0+)
+    ├── PATTERNS.md          # Common usage patterns
+    ├── RESUMABILITY.md      # Writing notes for post-compaction recovery
+    ├── STATIC_DATA.md       # Using bd for reference databases
+    ├── TROUBLESHOOTING.md   # Common issues and fixes
+    ├── WORKFLOWS.md         # Step-by-step workflow guides
+    ├── AGENTS.md            # Agent bead tracking (v0.40+)
+    ├── ASYNC_GATES.md       # Human-in-the-loop gates
+    ├── CHEMISTRY_PATTERNS.md # Mol vs Wisp decision tree
+    └── WORKTREES.md         # Parallel development patterns
+```
+
+## Key Concepts
+
+### bd vs TodoWrite
+
+| Use bd when...                       | Use TodoWrite when...       |
+| ------------------------------------ | --------------------------- |
+| Work spans multiple sessions         | Single-session tasks        |
+| Complex dependencies exist           | Linear step-by-step work    |
+| Need to resume after weeks           | Just need a quick checklist |
+| Knowledge work with fuzzy boundaries | Clear, immediate tasks      |
+
+### The Dependency Direction Trap
+
+`bd dep add A B` means **"A depends on B"** (B must complete before A can start).
+
+```bash
+# Want: "Setup must complete before Implementation"
+bd dep add implementation setup  # ✓ CORRECT
+# NOT: bd dep add setup implementation  # ✗ WRONG
+```
+
+### Surviving Compaction
+
+When Claude's context gets compacted, conversation history is lost but bd state survives. Write notes as if explaining to a future Claude with zero context:
+
+```bash
+bd update issue-123 --notes "COMPLETED: JWT auth with RS256
+KEY DECISION: RS256 over HS256 for key rotation
+IN PROGRESS: Password reset flow
+NEXT: Implement rate limiting"
+```
+
+## Requirements
+
+- [bd CLI](https://github.com/steveyegge/beads) installed (`brew install steveyegge/beads/bd`)
+- A git repository (bd requires git for sync)
+- Initialized database (`bd init` in project root)
+
+## Version Compatibility
+
+| Version  | Features                                                   |
+| -------- | ---------------------------------------------------------- |
+| v0.43.0+ | Full support: agents, gates, worktrees, chemistry patterns |
+| v0.40.0+ | Agent beads, async gates, worktree management              |
+| v0.34.0+ | Molecules, wisps, cross-project dependencies               |
+| v0.15.0+ | Core: dependencies, notes, status tracking                 |
+| Earlier  | Basic functionality, some features missing                 |
+
+## Contributing
+
+This skill is maintained at [github.com/steveyegge/beads](https://github.com/steveyegge/beads) in the `skills/beads/` directory.
+
+Issues and PRs welcome for:
+
+- Documentation improvements
+- New workflow patterns
+- Bug fixes in examples
+- Additional troubleshooting scenarios
+
+## License
+
+MIT (same as beads)