@ultrakit/ultrakit 0.0.0 → 0.0.2

package/dist/template/{.opencode → opencode}/skill/reflection-checkpoints/SKILL.md

@@ -5,8 +5,8 @@ description: >
   checkpoints that detect scope drift, stalled progress, and premature completion claims.
   Inspired by ByteRover's reflection prompt architecture.
 version: 1.0.0
-tags: [workflow, quality, autonomous]
-dependencies: [verification-before-completion]
+tags: [workflow, planning, code-quality]
+dependencies: []
 ---
 
 # Reflection Checkpoints

package/dist/template/opencode/skill/research-tool-routing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: research-tool-routing
+description: >
+  Use when choosing research tools or documenting workflows that need library docs,
+  current web content, URL extraction, crawling, or semantic/deep web search.
+  Defines UltraKit's canonical routing policy: Context7 for package/library docs,
+  Webclaw for web extraction/crawling/current pages, and Exa only as an optional
+  power-preset semantic search provider.
+version: 1.0.0
+tags: [research, workflow, integration]
+dependencies: []
+---
+
+# Research Tool Routing
+
+## When to Use
+
+- You need to choose between Context7, Webclaw, grepsearch/codesearch, opensrc, or optional Exa for research work
+- You are documenting command, agent, or skill guidance for library docs, web extraction, crawling, or semantic/deep web search
+- A workflow needs a canonical default research stack and fallback policy
+
+## When NOT to Use
+
+- The answer is already available in local code, tests, or project memory
+- The task does not involve external documentation, web content, package docs, or research-provider routing
+- A user explicitly requires a specific provider and no routing decision is needed
+
+## Purpose
+
+This skill is the canonical routing policy for research tools in UltraKit workflows.
+Use it anywhere a command, agent, or skill must decide between library documentation,
+web extraction, code examples, or semantic web search.
+
+## Canonical Policy
+
+**Default research stack:** Context7 + Webclaw.
+
+- **Context7** is the default for package, library, framework, SDK, and API documentation.
+- **Webclaw** is the default for arbitrary web pages, URL extraction, scraping, crawling,
+  sitemap discovery, batch extraction, structured page extraction, diffing, brand identity,
+  and bot-protection-aware retrieval.
+- **Exa** is optional and power-preset only. Use it for semantic/deep web search,
+  category indexes, or structured search across multiple sources when explicitly configured.
+  Exa is not part of the default or recommended runtime path.
+
+## Preset Defaults
+
+| Preset                    | Included Tools                    | Use When                                                                                                     |
+| ------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **Minimal**               | Context7                          | The workflow only needs package/library documentation.                                                       |
+| **Recommended / Default** | Context7 + Webclaw                | The workflow needs library docs plus current web content, URLs, crawling, or extraction.                     |
+| **Power**                 | Context7 + Webclaw + optional Exa | The workflow explicitly needs semantic/deep web search, category indexes, or structured cross-source search. |
+
+Do not add Exa to default or recommended guidance. Mention Exa only as optional/power-only unless a user explicitly asks to configure it.
+
+## Need → Tool Routing
+
+| Need                                                               | Primary Tool               | Fallback / Notes                                                        |
+| ------------------------------------------------------------------ | -------------------------- | ----------------------------------------------------------------------- |
+| Library/package/framework docs                                     | Context7                   | Use the library ID resolver first, then query the specific topic.       |
+| SDK/API signatures or version-specific examples                    | Context7                   | Prefer official docs before source examples.                            |
+| Package internals beyond docs                                      | opensrc                    | Use after Context7 if docs are incomplete or ambiguous.                 |
+| Real production code examples                                      | grepsearch / codesearch    | Search literal code patterns, not tutorial keywords.                    |
+| Current web page content from a URL                                | Webclaw scrape             | Use webfetch only if Webclaw is unavailable or unnecessary.             |
+| 403, Cloudflare, or bot-protected pages                            | Webclaw scrape             | Prefer Webclaw before plain fetch.                                      |
+| Crawl a documentation site                                         | Webclaw crawl              | Set depth and page limits; stop when the answer is supported.           |
+| Batch-extract multiple URLs                                        | Webclaw batch              | Use for independent URL sets to reduce tool overhead.                   |
+| Sitemap discovery                                                  | Webclaw map                | Use before crawl when the site structure matters.                       |
+| Structured data from one page                                      | Webclaw extract            | Provide a schema or precise extraction prompt.                          |
+| Brand colors, logos, or favicon                                    | Webclaw brand              | Use before visual design or brand-sensitive mockups.                    |
+| Page change detection                                              | Webclaw diff               | Compare against a previous extraction snapshot.                         |
+| Semantic/deep web search                                           | Exa, optional power preset | Use only when configured and when Webclaw/basic search is insufficient. |
+| Company, people, research paper, news, or financial-report indexes | Exa, optional power preset | Do not require Exa for default UltraKit workflows.                      |
+
+## Decision Rules
+
+1. **Known library docs → Context7.** Resolve the library first, then query the exact API or topic.
+2. **Specific URL or site content → Webclaw.** Scrape, crawl, map, batch, extract, diff, summarize, or brand-extract as needed.
+3. **Real-world code usage → grepsearch / codesearch.** Search literal code patterns with a language filter.
+4. **Deep semantic discovery → optional Exa.** Use only in the power preset or when the user explicitly asks for Exa.
+5. **Do not duplicate providers by default.** If Context7 + Webclaw answer the question with medium+ confidence, stop.
+6. **No secrets in templates.** Reference `CONTEXT7_API_KEY`, `WEBCLAW_API_KEY`, and `EXA_API_KEY` as optional environment variables only.
+
+## Workflow Integration
+
+Commands and agents that perform research should reference this policy instead of recreating provider-specific guidance:
+
+- `/create` uses it when writing PRDs that mention research tools or external-source verification.
+- `/research` uses it as the source priority for docs, web content, and optional semantic search.
+- `/plan` uses it when selecting discovery depth and external research tasks.
+- `scout` uses it as the canonical Need → Tool table for external research.
+- `deep-research` uses it during external research after internal code exploration.
+- `webclaw` uses it to clarify boundaries with Context7 and optional Exa.
+
+## Anti-Patterns
+
+- Do not use Webclaw for package API documentation when Context7 can answer it.
+- Do not use Context7 to fetch arbitrary URLs or current web pages.
+- Do not make Exa a default dependency or a recommended prerequisite.
+- Do not add Exa routing without labeling it optional or power-preset only.
+- Do not fall back to broad generic web search before checking codebase patterns, Context7 docs, or Webclaw URL extraction.
+- Do not hardcode API keys, remote credentials, or paid-provider assumptions in template files.
+
+## Output Guidance
+
+When documenting tool choices, state the policy tersely:
+
+> Use Context7 for library/API docs, Webclaw for web search, scraping, crawling, and structured extraction, and Exa only when the optional power preset is configured for semantic/deep search.
+
+## Quick Reference
+
+```
+Library docs?             Context7
+Specific URL/page?        Webclaw
+Crawl or sitemap?         Webclaw
+Batch URLs?               Webclaw
+Brand or page diff?       Webclaw
+Production code examples? grepsearch / codesearch
+Semantic/deep search?     Optional Exa power preset
+Default stack?            Context7 + Webclaw
+```

package/dist/template/{.opencode → opencode}/skill/verification-before-completion/references/VERIFICATION_PROTOCOL.md

@@ -17,11 +17,18 @@ CHANGED=$({
   git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx'
 } | sort -u)
 
-# If in a bead worktree, diff against the branch point:
-# CHANGED=$({
-#   git diff --name-only --diff-filter=d main...HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx'
-#   git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx'
-# } | sort -u)
+# If in a bead worktree, diff against the branch point instead of HEAD:
+WORKTREE_FILE=".beads/artifacts/$ARGUMENTS/worktree.txt"
+if [ -f "$WORKTREE_FILE" ]; then
+  # Worktree detected — use merge-base to find branch point
+  BRANCH_POINT=$(git merge-base main HEAD 2>/dev/null || git merge-base origin/main HEAD 2>/dev/null)
+  if [ -n "$BRANCH_POINT" ]; then
+    CHANGED=$({
+      git diff --name-only --diff-filter=d "$BRANCH_POINT"...HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx'
+      git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx'
+    } | sort -u)
+  fi
+fi
 
 # Count for mode decision
 FILE_COUNT=$(echo "$CHANGED" | grep -c .)

package/dist/template/{.opencode → opencode}/skill/verification-gates/SKILL.md

@@ -3,7 +3,8 @@ name: verification-gates
 description: >
   Use when running pre-merge or pre-PR verification checks. Detects project type and runs appropriate build, test, lint, and typecheck commands.
 version: 1.0.0
-tags: [verification, testing, lint, typecheck, ci]
+tags: [testing, automation, devops]
+dependencies: []
 ---
 
 # Verification Gates

package/dist/template/{.opencode → opencode}/skill/webclaw/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: webclaw
 description: MUST load when webfetch returns 403 or bot protection errors, when crawling documentation sites, batch-extracting pages, or extracting brand identity. Primary web scraping tool — prefer over webfetch for all non-trivial scraping.
+version: 1.0.0
+tags: [research, mcp, integration]
+dependencies: []
 ---
 
 # Webclaw Skill
@@ -14,6 +17,10 @@ Fast, local-first web content extraction for LLMs. Rust-based scraper with TLS f
 - Or: download from https://github.com/0xMassi/webclaw/releases
 - MCP server must be enabled in `.opencode/opencode.json` (`"enabled": true`)
 
+## Canonical Routing Boundary
+
+Follow [research-tool-routing](../research-tool-routing/SKILL.md) before choosing a web research provider. Use Webclaw for arbitrary URLs, scraping, crawling, sitemap discovery, batch extraction, page diffing, brand identity, and bot-protection-aware retrieval. Use Context7 instead for package/library/API documentation. Use Exa only when the optional power preset is configured for semantic/deep web search or category indexes; Exa is not a default or recommended dependency.
+
 ## When to Use
 
 | Scenario               | Tool                   | Why                                        |
@@ -26,6 +33,11 @@ Fast, local-first web content extraction for LLMs. Rust-based scraper with TLS f
 | Extract brand identity | `brand`                | Colors, fonts, logos from any site         |
 | LLM-optimized output   | `scrape` with `-f llm` | 67% fewer tokens than raw HTML             |
 
+## When NOT to Use
+
+- For simple library API lookups; use Context7 instead.
+- For internal codebase search; use code search tools instead.
+
 ## MCP Tools (8 local, no API key needed)
 
 ### scrape

package/dist/template/opencode/skill/workspace-setup/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: workspace-setup
+description: >
+  Use when a command needs to create a feature branch, worktree, or set up a workspace for bead work. Shared by /create, /ship, and /lfg.
+version: 1.1.0
+tags: [git, workflow]
+dependencies: []
+---
+
+# Workspace Setup
+
+Set up a git workspace (branch, worktree, or current) for bead-based work.
+
+## When to Use
+
+- In `/create` after bead creation, before task conversion
+- In `/ship` when auto-claiming an unclaimed bead
+- In `/lfg` when setting up for autonomous execution
+- Any command that needs to transition from "no workspace" to "active workspace"
+
+## When NOT to Use
+
+- If bead is already `in_progress` with an existing branch
+- If user explicitly chose "Use current workspace" and the workspace is already correct
+
+## Protocol
+
+### Step 1: Ask the user
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Workspace",
+      question: "How do you want to set up the workspace?",
+      options: [
+        {
+          label: "Create feature branch",
+          description:
+            "Best for simple/sequential work. Lowest overhead and cleanup. git switch -c <prefix>/<bead-id>-<title>",
+        },
+        {
+          label: "Create worktree",
+          description:
+            "Best for parallel PRs, dirty workspace, or multi-agent work. Creates isolated checkout in .worktrees/.",
+        },
+        {
+          label: "Use current workspace",
+          description: "Work on current branch without creating a new one. Advanced/manual mode.",
+        },
+      ],
+    },
+  ],
+});
+```
+
+**Selection guidance:**
+
+| Situation                               | Recommend         |
+| --------------------------------------- | ----------------- |
+| One bead at a time, clean working tree  | Feature branch    |
+| Multiple active beads, pushing many PRs | Worktree          |
+| Dirty working tree, don't want to stash | Worktree          |
+| Already on the correct branch/workspace | Current workspace |
+| Long-running feature needing isolation  | Worktree          |
+| Quick fix or small task                 | Feature branch    |
+
+### Step 2A: Create branch (if selected)
+
+Map bead type to branch prefix:
+
+| Bead Type | Branch Prefix |
+| --------- | ------------- |
+| feature   | feat          |
+| bug       | fix           |
+| task      | task          |
+| epic      | epic          |
+
+Create the branch:
+
+```bash
+git switch -c $PREFIX/$BEAD_ID-$TITLE_SLUG
+```
+
+Where `$TITLE_SLUG` is the bead title lowercased with spaces replaced by hyphens, truncated to ~50 chars.
+
+### Step 2B: Create worktree (if selected)
+
+Load the [using-git-worktrees](../skill/using-git-worktrees/SKILL.md) skill and follow its protocol:
+
+```typescript
+skill({ name: "using-git-worktrees" });
+```
+
+The worktree skill handles:
+
+1. Directory selection (`.worktrees/` preferred)
+2. `.gitignore` verification
+3. Branch creation + worktree creation (`git worktree add <path> -b <branch>`)
+4. Dependency setup (`npm install`, etc.)
+5. Baseline test verification
+6. Tracking file (`.beads/artifacts/$BEAD_ID/worktree.txt`)
+
+After the worktree is created, all subsequent work happens from the worktree directory.
+
+**Submodule caveat:** Git marks multiple checkout support as experimental with incomplete submodule handling. If the repo uses submodules, warn the user before proceeding with a worktree.
+
+### Step 2C: Current workspace (if selected)
+
+No action needed. Verify the current branch/workspace is appropriate for the bead and continue.
+
+### Step 3: Confirm
+
+```bash
+git branch --show-current
+git rev-parse --show-toplevel
+```
+
+Verify:
+
+- You're on the correct branch (or in the correct worktree)
+- The working directory matches the expected workspace
+
+If a worktree was created, also verify:
+
+```bash
+cat .beads/artifacts/$BEAD_ID/worktree.txt
+git worktree list --porcelain | grep "worktree $(cat .beads/artifacts/$BEAD_ID/worktree.txt)"
+```
+
+Report:
+
+```
+Workspace ready:
+- Mode: [branch | worktree | current]
+- Branch: [branch-name]
+- Directory: [working-directory]
+- Worktree tracking: [.beads/artifacts/$BEAD_ID/worktree.txt if worktree]
+```

package/package.json

@@ -1,12 +1,15 @@
 {
 	"name": "@ultrakit/ultrakit",
-	"version": "0.0.0",
-	"description": "CLI tool for bootstrapping and managing UltraKit projects",
+	"version": "0.0.2",
+	"description": "Scaffolding and maintenance CLI for OpenCode projects — generates and upgrades validated project templates with agents, commands, skills, memory, tools, and plugins",
 	"keywords": [
 		"agents",
 		"cli",
+		"developer-tools",
 		"mcp",
 		"opencode",
+		"project-generator",
+		"scaffolding",
 		"template",
 		"ultrakit"
 	],
@@ -34,7 +37,7 @@
 	},
 	"scripts": {
 		"dev": "tsx src/index.ts",
-		"build": "tsdown && mkdir -p dist/template && cp -r .opencode/ dist/template/.opencode/ && rm -rf dist/template/.opencode/node_modules dist/template/.opencode/.git dist/template/.opencode/coverage dist/template/.opencode/.next dist/template/.opencode/.turbo dist/template/.opencode/logs dist/template/.opencode/package-lock.json dist/template/.opencode/memory.db dist/template/.opencode/memory.db-shm dist/template/.opencode/memory.db-wal dist/template/.opencode/memory.db.corrupt.* dist/template/.opencode/memory-recovery.log dist/template/.opencode/plugin/*.bak",
+		"build": "tsdown && mkdir -p dist/template && rm -rf dist/template/opencode && cp -R template/opencode dist/template/opencode && rm -rf dist/template/opencode/node_modules dist/template/opencode/.git dist/template/opencode/coverage dist/template/opencode/.next dist/template/opencode/.turbo dist/template/opencode/logs dist/template/opencode/package-lock.json dist/template/opencode/memory.db dist/template/opencode/memory.db-shm dist/template/opencode/memory.db-wal dist/template/opencode/memory.db.corrupt.* dist/template/opencode/memory-recovery.log dist/template/opencode/plugin/*.bak && rm -rf dist/template/opencode/plans dist/template/opencode/memory/research",
 		"typecheck": "tsgo --noEmit",
 		"test": "vitest run",
 		"test:watch": "vitest",
@@ -45,7 +48,10 @@
 		"lint": "oxlint .",
 		"lint:fix": "oxlint --fix .",
 		"format": "oxfmt",
-		"format:check": "oxfmt --check"
+		"format:check": "oxfmt --check",
+		"prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build",
+		"release": "bash scripts/publish.sh",
+		"link:local": "npm link"
 	},
 	"dependencies": {
 		"@ai-sdk/provider": "^3.0.8",
@@ -55,8 +61,6 @@
 		"cac": "^6.7.14",
 		"cli-table3": "^0.6.5",
 		"diff": "^8.0.3",
-		"env-paths": "^4.0.0",
-		"node-machine-id": "^1.1.12",
 		"ora": "^9.3.0",
 		"picocolors": "^1.1.1",
 		"zod": "^3.25.76"
@@ -67,11 +71,14 @@
 		"@typescript/native-preview": "latest",
 		"oxfmt": "^0.23.0",
 		"oxlint": "^1.48.0",
-		"tsdown": "latest",
+		"tsdown": "0.21.10",
 		"tsx": "latest",
 		"typescript": "^5.9.3",
 		"vitest": "latest"
 	},
+	"overrides": {
+		"unrun": "0.2.37"
+	},
 	"engines": {
 		"node": ">=20.19.0"
 	}