create-kuckit-app 2.0.2 → 2.2.0

package/templates/base/.claude/skills/beads/resources/WORKTREES.md

@@ -0,0 +1,95 @@
+# Git Worktree Support
+
+> Adapted from ACF beads skill
+
+**v0.40+**: First-class worktree management via `bd worktree` command.
+
+## When to Use Worktrees
+
+| Scenario             | Worktree? | Why                                         |
+| -------------------- | --------- | ------------------------------------------- |
+| Parallel agent work  | Yes       | Each agent gets isolated working directory  |
+| Long-running feature | Yes       | Avoids stash/switch dance for interruptions |
+| Quick branch switch  | No        | `git switch` is simpler                     |
+| PR review isolation  | Yes       | Review without disturbing main work         |
+
+## Why `bd worktree` over `git worktree`
+
+**Always use `bd worktree`** instead of raw `git worktree` commands.
+
+```bash
+bd worktree create .worktrees/{name} --branch feature/{name}
+bd worktree remove .worktrees/{name}
+```
+
+**Why?** `bd worktree` auto-configures:
+
+- Beads database redirect files
+- Proper gitignore entries
+- Daemon bypass for worktree operations
+
+## Architecture
+
+All worktrees share one `.beads/` database via redirect files:
+
+```
+main-repo/
+├── .beads/              ← Single source of truth
+└── .worktrees/
+    ├── feature-a/
+    │   └── .beads       ← Redirect file (not directory)
+    └── feature-b/
+        └── .beads       ← Redirect file
+```
+
+**Key insight**: Daemon auto-bypasses for wisp operations in worktrees.
+
+## Commands
+
+```bash
+# Create worktree with beads support
+bd worktree create .worktrees/my-feature --branch feature/my-feature
+
+# List worktrees
+bd worktree list
+
+# Show worktree info
+bd worktree info .worktrees/my-feature
+
+# Remove worktree cleanly
+bd worktree remove .worktrees/my-feature
+```
+
+## Debugging
+
+When beads commands behave unexpectedly in a worktree:
+
+```bash
+bd where              # Shows actual .beads location (follows redirects)
+bd doctor --deep      # Validates graph integrity across all refs
+```
+
+## Protected Branch Workflows
+
+For repos with protected `main` branch:
+
+```bash
+bd init --branch beads-metadata    # Use separate branch for beads data
+bd init --contributor              # Auto-configure sync.remote=upstream for forks
+```
+
+This creates `.git/beads-worktrees/` for internal management.
+
+## Multi-Clone Support
+
+Multi-clone, multi-branch workflows:
+
+- Hash-based IDs (`bd-abc`) eliminate collision across clones
+- Each clone syncs independently via git
+- See [WORKTREES.md](https://github.com/steveyegge/beads/blob/main/docs/WORKTREES.md) for comprehensive guide
+
+## External References
+
+- **Official Docs**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Sync Branch**: [PROTECTED_BRANCHES.md](https://github.com/steveyegge/beads/blob/main/docs/PROTECTED_BRANCHES.md)
+- **Worktrees**: [WORKTREES.md](https://github.com/steveyegge/beads/blob/main/docs/WORKTREES.md)

package/templates/base/.claude/skills/browser-skill/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: browser-skill
+description: Minimal Chrome DevTools Protocol tools for browser automation and scraping. Use when you need to start Chrome, navigate pages, execute JavaScript, take screenshots, or interactively pick DOM elements.
+---
+
+# Browser Tools
+
+Minimal CDP tools for collaborative site exploration and scraping.
+
+## Installation
+
+Install dependencies before first use:
+
+```bash
+cd .claude/skills/browser-skill/scripts && npm install
+```
+
+## Start Chrome
+
+```bash
+node .claude/skills/browser-skill/scripts/start.js              # Fresh profile
+node .claude/skills/browser-skill/scripts/start.js --profile    # Copy your profile (cookies, logins)
+```
+
+Start Chrome on `:9222` with remote debugging.
+
+## Navigate
+
+```bash
+node .claude/skills/browser-skill/scripts/nav.js https://example.com
+node .claude/skills/browser-skill/scripts/nav.js https://example.com --new
+```
+
+Navigate current tab or open new tab.
+
+## Evaluate JavaScript
+
+```bash
+node .claude/skills/browser-skill/scripts/eval.js 'document.title'
+node .claude/skills/browser-skill/scripts/eval.js 'document.querySelectorAll("a").length'
+```
+
+Execute JavaScript in active tab (async context).
+
+**IMPORTANT**: The code must be a single expression or use IIFE for multiple statements:
+
+- Single expression: `'document.title'`
+- Multiple statements: `'(() => { const x = 1; return x + 1; })()'`
+- Avoid newlines in the code string - keep it on one line
+
+## Screenshot
+
+```bash
+node .claude/skills/browser-skill/scripts/screenshot.js
+```
+
+Screenshot current viewport, returns temp file path.
+
+## Pick Elements
+
+```bash
+node .claude/skills/browser-skill/scripts/pick.js "Click the submit button"
+```
+
+Interactive element picker. Click to select, Cmd/Ctrl+Click for multi-select, Enter to finish.
+
+## Usage Notes
+
+- Start Chrome first before using other tools
+- The `--profile` flag syncs your actual Chrome profile so you're logged in everywhere
+- JavaScript evaluation runs in an async context in the page
+- Pick tool allows you to visually select DOM elements by clicking on them

package/templates/base/.claude/skills/knowledge/SKILL.md

@@ -1,281 +1,231 @@
 ---
 name: knowledge
-description: Extract knowledge from Amp thread chains and update project documentation. Use when synthesizing learnings from multi-session work, updating docs after major features, or capturing architectural decisions from conversation history.
+description: Extracts knowledge from Amp threads and updates project docs. Use when asked to document recent work, sync docs after an epic, summarize what changed, or update AGENTS.md from thread history.
 ---
 
 # Knowledge Extraction & Documentation Sync
 
-## Overview
+Extracts knowledge from Amp threads and synchronizes project documentation.
 
-This skill enables extracting knowledge from Amp thread chains and synchronizing project documentation. It bridges the gap between ephemeral conversation context and persistent project knowledge.
+## Pipeline
 
-## When to Use This Skill
-
-### Use knowledge extraction when:
+```
+REQUEST → THREADS → TOPICS → CODE → DOCS
+```
 
-- **Major feature completed** - Need to update docs to reflect new capabilities
-- **Architecture changed** - Decisions made across threads need documenting
-- **Epic finished** - Multi-session work produced learnings worth capturing
-- **Patterns emerged** - Repeated approaches should be documented for consistency
-- **Onboarding prep** - Capture context that would help future contributors
+| Phase        | Action                     | Tools                  |
+| ------------ | -------------------------- | ---------------------- |
+| 1. Discover  | Find threads by query/time | `find_thread`          |
+| 2. Extract   | Parallel topic extraction  | `Task` + `read_thread` |
+| 3. Verify    | Ground topics in code      | `gkg`, `finder`        |
+| 4. Map       | Find target docs           | `Read`, `Grep`         |
+| 5. Reconcile | Compare all sources        | `Oracle`               |
+| 6. Apply     | Surgical updates           | `edit_file`, `mermaid` |
 
-### Don't use when:
+## Phase 1: Discover Threads
 
-- **Single conversation** - Use Episteme agent for same-session updates
-- **Simple edits** - Direct edit_file is sufficient
-- **Code changes only** - No documentation impact
+Start from user request:
 
-## Thread Chain Traversal
+```bash
+# "Document last 2 weeks"
+find_thread after:2w
 
-### Finding Related Threads
+# "Summarize auth work"
+find_thread "authentication"
 
-Use `find_thread` to locate related work:
+# "What touched the SDK?"
+find_thread file:packages/sdk
 
+# Combined
+find_thread "refactor" after:1w file:packages/api
 ```
-find_thread query patterns:
 
-# By topic
-find_thread "Framework Refactor"
+## Phase 2: Extract Topics
 
-# By file touched
-find_thread file:packages/sdk/src/module.ts
+Spawn parallel `Task` agents (2-3 threads each):
 
-# By date range
-find_thread "auth" after:7d
-
-# By author
-find_thread author:me after:2w
 ```
+Task prompt:
+"Read threads [T-xxx, T-yyy] using read_thread.
+Goal: 'Extract topics, decisions, changes'
 
-### Reading Thread Content
-
-Use `read_thread` with specific goals:
-
-| Extraction Goal        | Goal Parameter                                                       |
-| ---------------------- | -------------------------------------------------------------------- |
-| Architecture decisions | "Extract architectural decisions, patterns, and design rationale"    |
-| CLI changes            | "Extract CLI command changes, new options, and usage patterns"       |
-| API changes            | "Extract API changes, new endpoints, breaking changes"               |
-| Module changes         | "Extract module structure changes, hooks, and registration patterns" |
-| Bug context            | "Extract bug description, root cause, and fix approach"              |
-| Feature details        | "Extract feature requirements, implementation, and usage examples"   |
+Return JSON:
+{
+  'topics': [{
+    'name': 'topic name',
+    'threads': ['T-xxx'],
+    'summary': '1-2 sentences',
+    'decisions': ['...'],
+    'patterns': ['...'],
+    'changes': ['...']
+  }]
+}"
+```
 
-### Chain Traversal Pattern
+Collect outputs → Oracle synthesizes:
 
 ```
-1. Start with provided thread ID or search query
-2. Read initial thread with broad goal
-3. Extract references to parent/related threads
-4. Use find_thread to discover connected threads
-5. Build chronological list (oldest → newest)
-6. Read each thread with focused goal
-7. Synthesize across all threads
+Oracle: "Cluster these extractions. Deduplicate.
+Latest thread wins conflicts. Output unified topic list."
 ```
 
-**Stop conditions:**
-
-- Reached epic/feature start
-- 10+ threads traversed
-- No more related threads found
-
-## Knowledge Extraction Framework
-
-### Phase 1: Discovery
-
-For each thread, extract:
-
-| Field        | Description                            |
-| ------------ | -------------------------------------- |
-| Thread ID    | Unique identifier                      |
-| Date         | When the work occurred                 |
-| Summary      | 1-2 sentence description               |
-| Key Changes  | Files modified, features added         |
-| Decisions    | Architectural or design decisions      |
-| Patterns     | Code patterns, conventions established |
-| Dependencies | What this work required or enabled     |
-
-### Phase 2: Synthesis
-
-Combine thread knowledge into structured output:
-
-```markdown
-## Knowledge Summary: [Epic/Feature Name]
-
-### Timeline
-
-- [Date]: [Thread ID] - [Summary]
-- [Date]: [Thread ID] - [Summary]
-
-### Architectural Decisions
-
-| Decision | Rationale | Thread  |
-| -------- | --------- | ------- |
-| [What]   | [Why]     | [T-xxx] |
-
-### New Patterns
-
-| Pattern   | When to Use | Example     |
-| --------- | ----------- | ----------- |
-| [Pattern] | [Context]   | [Code/Link] |
-
-### Breaking Changes
+See `reference/extraction-prompts.md` for full templates.
 
-- [Change]: [Migration path]
+## Phase 3: Verify Against Code
 
-### New Capabilities
+For each topic, verify claims:
 
-- [Capability]: [How to use]
 ```
+Topic: "Added retry logic to API client"
 
-### Phase 3: Mapping
+1. finder "retry logic API client"
+   → finds src/api/client.ts
 
-Map extracted knowledge to documentation targets:
+2. gkg__search_codebase_definitions "retry"
+   → RetryPolicy class at L45
 
-| Change Type     | Target Files                                       |
-| --------------- | -------------------------------------------------- |
-| Architecture    | `AGENTS.md`, `docs/ARCHITECTURE.md`                |
-| CLI commands    | `packages/kuckit-cli/AGENTS.md`                    |
-| SDK/API         | `packages/sdk/AGENTS.md`, `packages/api/AGENTS.md` |
-| Patterns        | `.claude/skills/*/SKILL.md`                        |
-| Quick start     | `README.md`                                        |
-| Templates       | `packages/create-kuckit-app/AGENTS.md`             |
-| Troubleshooting | `docs/TROUBLESHOOTING.md`                          |
+3. gkg__get_references "RetryPolicy"
+   → 12 usages across 4 files
 
-## Documentation Update Guidelines
-
-### Update Principles
-
-1. **Preserve structure** - Maintain existing formatting and organization
-2. **Surgical changes** - Only modify sections affected by new knowledge
-3. **Add, don't overwrite** - Enhance existing content, don't replace unless outdated
-4. **Cross-reference** - Link related sections across documents
-5. **Version awareness** - Note when changes apply to specific versions
-
-### Content Guidelines by File Type
-
-**AGENTS.md files:**
-
-- Command references with examples
-- Architecture diagrams (ASCII or mermaid)
-- Dependency rules tables
-- File structure trees
-- Quick reference tables
+→ Confirmed: topic matches code
+```
 
-**README.md:**
+| Claim Type        | Verification                           |
+| ----------------- | -------------------------------------- |
+| "Added X"         | `gkg__search_codebase_definitions "X"` |
+| "Refactored Y"    | `finder "Y"` → `gkg__get_references`   |
+| "Changed pattern" | `warpgrep "pattern implementation"`    |
+| "Updated config"  | `gkg__repo_map` on config paths        |
 
-- Quick start commands
-- Feature lists with brief descriptions
-- Installation/setup instructions
-- Links to detailed docs
+## Phase 4: Map to Docs
 
-**SKILL.md files:**
+Discover existing documentation:
 
-- When to use guidance
-- Patterns with examples
-- Reference tables
-- Troubleshooting sections
+```bash
+# Structure
+gkg__repo_map on docs/, .claude/skills/, */AGENTS.md
 
-### Quality Checklist
+# Find existing mentions
+Grep "topic keyword" docs/
+Grep "RetryPolicy" AGENTS.md
+```
 
-Before finalizing updates:
+Read target files before updating:
 
 ```
-Documentation Update Checklist:
-- [ ] All affected files identified
-- [ ] Changes match source thread content
-- [ ] Code examples are syntactically correct
-- [ ] Links are valid (file paths, URLs)
-- [ ] Terminology is consistent with existing docs
-- [ ] No duplicate information introduced
-- [ ] Deprecated info marked or removed
+Read docs/ARCHITECTURE.md
+→ Note structure, sections, voice
+→ Identify insertion point
 ```
 
-## Verification
-
-After updates:
-
-1. **Type check**: `bun run check-types` (if code examples included)
-2. **Link check**: Verify file:// links point to existing files
-3. **Consistency check**: Grep for conflicting information
-4. **Summary**: Report what was updated and why
+See `reference/doc-mapping.md` for target file conventions.
 
-## Reference: Thread Goal Templates
+## Phase 5: Reconcile
 
-Copy these goals when using `read_thread`:
-
-### For Architecture Work
+Oracle compares three sources:
 
 ```
-"Extract architectural decisions made, patterns established,
-design rationale, and any trade-offs discussed. Include
-specific file paths and code patterns where mentioned."
+Oracle prompt:
+"Compare:
+1. TOPICS: [extracted]
+2. CODE: [verified state]
+3. DOCS: [current content]
+
+Output:
+- GAPS: topics not in docs
+- STALE: docs ≠ code
+- UPDATES: [{file, section, change, rationale}]"
 ```
 
-### For Feature Implementation
+## Phase 6: Apply Updates
+
+**Text updates**:
 
 ```
-"Extract feature requirements, implementation approach,
-API surface, usage examples, and any configuration options.
-Note breaking changes or migration needs."
+Read target → edit_file with precise changes
+Preserve structure and voice
 ```
 
-### For Refactoring Work
+**Architecture diagrams**:
 
 ```
-"Extract what was refactored, why (motivation), how (approach),
-what patterns changed, and any migration guidance for existing code."
+mermaid with citations:
+{
+  "code": "flowchart LR\n  A[Client] --> B[RetryPolicy]",
+  "citations": {
+    "Client": "file:///src/api/client.ts#L10",
+    "RetryPolicy": "file:///src/api/retry.ts#L45"
+  }
+}
 ```
 
-### For Bug Fixes
+**Parallel updates**: Multiple unrelated files → spawn Task per file.
 
-```
-"Extract the bug description, root cause analysis, fix approach,
-and any patterns to avoid similar issues in the future."
-```
+## Concrete Example
 
-### For Documentation Updates
+User: "Document the auth refactor from last week"
 
 ```
-"Extract what documentation was updated, what information was added,
-and any structural changes to documentation organization."
-```
+1. find_thread "auth" after:7d
+   → [T-abc, T-def, T-ghi]
 
-## Integration with Other Skills
+2. Task agents extract (parallel):
+   Agent A: T-abc → {topics: [{name: "JWT migration"}]}
+   Agent B: T-def, T-ghi → {topics: [{name: "session cleanup"}]}
 
-### With Beads (bd)
+3. Oracle clusters:
+   → "Auth Refactor" with sub-topics
 
-- Check `bd list --status closed` for completed work to document
-- Use bead notes as additional context source
-- Create follow-up beads for documentation gaps
+4. Verify:
+   gkg__search_codebase_definitions "JWTService"
+   → confirmed at packages/auth/jwt.ts
 
-### With Episteme
+5. Map docs:
+   Grep "authentication" AGENTS.md
+   → Section exists at line 45
 
-- Episteme handles same-session updates
-- Knowledge skill handles cross-session synthesis
-- Hand off to Episteme for final polish
+6. Oracle reconciles:
+   → Gap: JWT migration not documented
+   → Update: AGENTS.md auth section
 
-## Troubleshooting
+7. Apply:
+   edit_file AGENTS.md add JWT details
+   mermaid auth flow diagram
+```
 
-**Thread not found:**
+## Tool Quick Reference
 
-- Verify thread ID format: `T-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
-- Try `find_thread` with topic keywords instead
-- Check date range if searching
+| Goal                | Tool                                     |
+| ------------------- | ---------------------------------------- |
+| Find threads        | `find_thread query\|after:Xd\|file:path` |
+| Read thread         | `read_thread` with focused goal          |
+| Parallel extraction | `Task` (spawn multiple)                  |
+| Find definitions    | `gkg__search_codebase_definitions`       |
+| Find references     | `gkg__get_references`                    |
+| Semantic search     | `finder` or `warpgrep`                   |
+| Area overview       | `gkg__repo_map`                          |
+| Synthesis           | `Oracle`                                 |
+| Read doc            | `Read`                                   |
+| Search docs         | `Grep`                                   |
+| Update doc          | `edit_file`                              |
+| Diagram             | `mermaid` with citations                 |
 
-**Too many threads:**
+## Quality Checklist
 
-- Narrow with date range: `after:7d`
-- Filter by file: `file:packages/sdk`
-- Focus on specific keywords
+```
+- [ ] Topics verified against code (GKG)
+- [ ] Existing docs read before updating
+- [ ] Changes surgical, not wholesale
+- [ ] Mermaid diagrams have citations
+- [ ] Terminology matches existing docs
+```
+
+## Troubleshooting
 
-**Conflicting information across threads:**
+**Thread not found**: Try topic keywords, widen date range
 
-- Use chronological order (latest wins)
-- Note evolution in documentation
-- Ask user to clarify if critical
+**Too many threads**: Add `file:` filter, narrow dates
 
-**Documentation structure unclear:**
+**Topic ≠ code**: Code is truth; note as "planned" or "historical"
 
-- Read target file first to understand format
-- Match existing section patterns
-- When in doubt, add new section at end
+**Doc structure unclear**: Read first, match existing patterns

package/templates/base/.claude/skills/knowledge/reference/doc-mapping.md

@@ -0,0 +1,49 @@
+# Documentation Target Mapping
+
+## By Topic Type
+
+| Topic Type      | Target Files                              |
+| --------------- | ----------------------------------------- |
+| Architecture    | `AGENTS.md`, `docs/ARCHITECTURE.md`       |
+| CLI commands    | `packages/cli/AGENTS.md`                  |
+| SDK/API         | `packages/sdk/AGENTS.md`                  |
+| Patterns        | `.claude/skills/*/SKILL.md`               |
+| Quick start     | `README.md`                               |
+| Module dev      | `packages/sdk/docs/MODULE_DEVELOPMENT.md` |
+| Troubleshooting | `docs/TROUBLESHOOTING.md`                 |
+| Deployment      | `docs/DEPLOYMENT.md`                      |
+| Migration       | `docs/MIGRATION.md`                       |
+
+## By Change Type
+
+| Change          | Primary Doc        | Secondary          |
+| --------------- | ------------------ | ------------------ |
+| New command     | Package AGENTS.md  | README.md          |
+| New hook        | SDK AGENTS.md      | Skill if pattern   |
+| Breaking change | MIGRATION.md       | Affected AGENTS.md |
+| New pattern     | Relevant SKILL.md  | AGENTS.md          |
+| Bug fix pattern | TROUBLESHOOTING.md | -                  |
+| Config change   | README.md          | DEPLOYMENT.md      |
+
+## Section Conventions
+
+### AGENTS.md
+
+- Commands table with examples
+- Architecture diagrams (mermaid)
+- Dependency rules tables
+- Quick reference tables
+
+### README.md
+
+- Quick start commands
+- Feature lists (brief)
+- Installation steps
+- Links to detailed docs
+
+### SKILL.md
+
+- When to use section
+- Patterns with examples
+- Reference tables
+- Troubleshooting section