@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/portless/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: portless
+description: Use when local web app, browser, OAuth callback, webhook, or multi-service verification would benefit from stable named localhost URLs via Portless. Keeps Portless optional and safety-gated because it can alter local networking, trust stores, and hosts files.
+version: 1.0.0
+tags: [workflow, integration, testing]
+dependencies: []
+---
+
+# Portless Local URL Workflow
+
+## Overview
+
+Portless replaces ad-hoc port numbers with stable, named local URLs such as `https://myapp.localhost`. In OpenCodeKit, treat it as an **optional verification aid** for local web workflows, not as a project dependency or default dev-server wrapper.
+
+Core rule: **read-only checks are allowed; installation, proxy startup, CA trust, hosts changes, cleanup, and LAN exposure require explicit user approval.**
+
+## When to Use
+
+- A PRD or task requires browser verification, OAuth callbacks, webhooks, cookies, cross-origin flows, or multiple local services.
+- Port numbers are brittle across git worktrees, parallel dev servers, or subagent/browser automation.
+- A user asks for stable local URLs, Portless setup, Portless troubleshooting, or named `.localhost` routes.
+- You need to record a human-verifiable local URL in `/ship`, `/verify`, or PR testing notes.
+
+## When NOT to Use
+
+- Pure CLI, library, docs, config, or unit-test-only work.
+- CI verification or non-interactive environments where privileged proxy setup could hang or fail.
+- The user has not approved installing Portless or making local machine changes.
+- The only goal is to run a single test or inspect code; use normal project commands instead.
+
+## Safety Model
+
+Portless can touch machine-level state. Classify commands before running them:
+
+| Class            | Examples                                                              | Policy                                             |
+| ---------------- | --------------------------------------------------------------------- | -------------------------------------------------- |
+| Read-only        | `portless --version`, `portless list`, `portless get <service>`       | OK if binary exists                                |
+| Process-local    | `portless run npm run dev`                                            | Ask first; starts a long-running server/proxy path |
+| Machine-mutating | install, CA trust, hosts sync, proxy start/stop, aliases, prune/clean | Ask first; explain impact                          |
+| Network-exposing | LAN mode, `.local` sharing                                            | Ask first; mention local network exposure          |
+
+Never run `sudo`, trust a CA, edit `/etc/hosts`, start/stop global proxies, prune/clean state, or expose LAN services without explicit approval in the current conversation.
+
+## Detection Checklist
+
+Before suggesting Portless:
+
+```bash
+command -v portless >/dev/null 2>&1 && portless --version
+```
+
+If installed, read current state without mutating it:
+
+```bash
+portless list
+```
+
+If a service is already known, resolve its URL:
+
+```bash
+portless get <service>
+```
+
+If Portless is not installed, do **not** install automatically. Ask whether the user wants global/user-local Portless setup and state that it may configure local proxy, HTTPS trust, and hosts entries depending on the chosen setup path.
+
+## Verification Workflow
+
+When approved and useful for a local web task:
+
+1. Prefer the project's existing dev command from `package.json`, `Makefile`, or docs.
+2. Ask before wrapping it with Portless.
+3. Start the dev server with Portless in a visible terminal/process:
+   ```bash
+   portless run npm run dev
+   ```
+4. Resolve the stable URL:
+   ```bash
+   portless get <service>
+   ```
+5. Use the stable URL for browser automation, OAuth/webhook callback notes, manual checkpoints, or PR testing instructions.
+6. Keep normal verification gates (`typecheck`, `lint`, `test`, `build`) separate; a reachable Portless URL does not prove code correctness.
+
+## Command Integration Rules
+
+- `/create` and `/plan`: mention Portless only when success criteria involve browser/manual local-web verification or callback URLs.
+- `/ship`: use Portless during Phase 4 only if approved and relevant; never auto-install or auto-start it.
+- `/verify`: may use read-only `portless list` / `portless get` evidence and approved stable URLs for manual or browser checks.
+- `/status`: may include `portless list` if installed; no Portless mutations from status.
+- `/lfg`: inherits Portless behavior through `/plan`, `/ship`, and `/verify`; do not add a separate Portless branch.
+
+## Reporting
+
+When Portless is used, report:
+
+```text
+Portless: [not installed | installed | approved active]
+Service: <name>
+URL: https://<name>.localhost
+Evidence: <command used to resolve or verify>
+Limitations: normal gates still required
+```
+
+If setup was skipped because approval was missing, say exactly what was skipped and continue with normal localhost/port verification.
+
+## Gotchas
+
+- **Privileged local networking is not a harmless helper** — Portless may bind 80/443, invoke sudo, add a local CA, or mutate hosts/proxy state. Always separate read-only discovery from machine-mutating setup.
+- **Pre-1.0 tool behavior can churn** — Verify current CLI behavior with `portless --version` and read-only commands before relying on exact subcommand output.
+- **Stable URL reachability is not correctness** — A named URL only proves routing. Still run project gates and feature-specific tests before claiming completion.

package/dist/template/.opencode/skill/prd/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: prd
+description: Use when planning new features, migrations, or refactors that need a structured requirements document. MUST load before writing any PRD or defining acceptance criteria for a feature.
+version: 1.0.0
+tags: [planning, documentation]
+dependencies: []
+---
+
+# PRD Creation Skill
+
+## When to Use
+
+- After a design is validated and you need formal requirements and acceptance criteria
+- Before breaking work into tasks or plans for features, migrations, or refactors
+
+## When NOT to Use
+
+- When you already have an approved PRD and only need task conversion
+- For small, mechanical changes where a PRD would be overhead
+
+
+
+
+
+## Beads-Native Output (Recommended)
+
+When you are working on a Beads task (you have a bead id like `br-...`), the PRD should live with the task artifacts:
+
+- Write PRD to: `.beads/artifacts/<bead-id>/prd.md`
+
+This keeps requirements + execution tasks colocated with the bead.
+
+If no bead id exists, create one first: `br create "Feature Name"`, then use the artifact path.
+
+## Workflow
+
+1. Confirm if the user has an existing bead id.
+   - If yes: use `.beads/artifacts/<bead-id>/prd.md`
+   - If no: create bead with `br create "Feature Name"`, then use artifact path
+2. Read template from `.opencode/memory/_templates/prd.md`
+3. Ask clarifying questions (5–7 max).
+4. Explore codebase patterns and constraints.
+5. Write a PRD following the template structure, including:
+   - Bead Metadata (dependencies, parallel, conflicts)
+   - Requirements with WHEN/THEN scenarios
+   - Machine-convertible `## Tasks` section
+
+## Clarifying Questions
+
+### Problem & Motivation
+
+- What problem does this solve? Who experiences it?
+- What's the cost of NOT solving this? (user pain, revenue, tech debt)
+- Why now? What triggered this work?
+
+### Users & Stakeholders
+
+- Who are the primary users? Secondary users?
+
+### End State & Success
+
+- What does "done" look like? How will users interact with it?
+
+### Scope & Boundaries
+
+- What's explicitly OUT of scope?
+- What's deferred to future iterations?
+- Are there adjacent features that must NOT be affected?
+
+### Constraints & Requirements
+
+- Performance requirements?
+- Security requirements? (auth, data sensitivity, compliance)
+- Compatibility requirements? (browsers, versions, APIs)
+- Accessibility requirements? (WCAG level, screen readers)
+
+### Risks & Dependencies
+
+- What could go wrong? Technical risks?
+- External service dependencies?
+- What decisions are still open/contentious?
+
+## Output Format
+
+**Read the template:** `.opencode/memory/_templates/prd.md`
+
+Follow the template structure which includes:
+
+- Bead Metadata (dependencies, parallel execution, conflicts)
+- Problem Statement with WHEN/THEN scenarios
+- Scope (In/Out)
+- Requirements (Functional + Non-Functional)
+- Success Criteria with verification commands
+- Technical Context and Affected Files
+- Tasks section with Metadata (depends_on, parallel, files)
+
+### Task Format (Critical)
+
+Tasks must include **Metadata** for dependency tracking:
+
+````markdown
+### <Task Title> [category]
+
+<One sentence describing the end state>
+
+**Metadata:**
+
+```yaml
+depends_on: []
+parallel: true
+conflicts_with: []
+files: []
+```
+````
+
+**Verification:**
+
+- [Command or check]
+
+```
+
+## Next Steps
+
+After PRD is written, tell the user:
+
+```
+
+PRD written: .beads/artifacts/<bead-id>/prd.md
+
+Next: Convert to executable tasks:
+skill({ name: "prd-task" })
+
+Or view the full lifecycle:
+skill({ name: "development-lifecycle" })
+
+```
+
+## Key Principles
+
+- Problem Before Solution
+- Define End State, Not Process
+- Technical Context Enables Autonomy
+- Non-Goals Prevent Scope Creep
+- Risks & Alternatives Show Rigor
+- Include Metadata for parallel execution
+```

package/dist/template/.opencode/skill/prd-task/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: prd-task
+description: Convert a Beads PRD markdown file to executable JSON tasks for autonomous execution. Use after writing `.beads/artifacts/<bead-id>/prd.md`.
+references:
+  - references/prd-schema.json
+version: 1.0.0
+tags: [planning, workflow]
+dependencies: [prd]
+---
+
+# PRD Task Skill (Beads-Native)
+
+## When to Use
+
+- After a PRD is complete at `.beads/artifacts/<bead-id>/prd.md` and you need executable tasks
+- When you need to generate `prd.json` and initialize `progress.txt` for a bead
+
+## When NOT to Use
+
+- Before a PRD exists or when requirements are still being gathered
+- If you only need a human-readable plan (use writing-plans instead)
+
+
+
+
+## Beads-Native File Locations (Recommended)
+
+This template uses Beads artifacts (no `.opencode/state`).
+
+```
+.beads/artifacts/<bead-id>/
+├── prd.md         # PRD created by `prd` skill
+├── prd.json       # Generated task list with passes field
+└── progress.txt   # Cross-iteration memory (append-only)
+```
+
+## Workflow
+
+1. Input: bead id (`br-...`).
+2. Read `.beads/artifacts/<bead-id>/prd.md`.
+3. Extract tasks from `## Tasks`.
+4. Write `.beads/artifacts/<bead-id>/prd.json`.
+5. Ensure `.beads/artifacts/<bead-id>/progress.txt` exists (create if missing).
+
+## Input Format
+
+`prd-task` expects a `## Tasks` section with tasks of the form:
+
+```markdown
+## Tasks
+
+### User Registration [functional]
+
+User can register with email and password.
+
+**Verification:**
+
+- POST /api/auth/register with valid email/password
+- Verify 201 response with user object
+- Attempt duplicate email, verify 409
+```
+
+## Output Format
+
+Write JSON to `.beads/artifacts/<bead-id>/prd.json`.
+
+```json
+{
+  "beadId": "br-...",
+  "prdName": "<optional-slug>",
+  "tasks": [
+    {
+      "id": "functional-1",
+      "category": "functional",
+      "description": "User can register with email and password",
+      "steps": [
+        "POST /api/auth/register with valid email/password",
+        "Verify 201 response with user object",
+        "Attempt duplicate email, verify 409"
+      ],
+      "passes": false,
+      "metadata": {
+        "depends_on": [],
+        "parallel": true,
+        "conflicts_with": [],
+        "files": ["src/routes/auth.ts", "src/db/users.ts"]
+      }
+    }
+  ],
+  "context": {
+    "patterns": ["API routes: src/routes/"],
+    "keyFiles": ["src/db/schema.ts"],
+    "nonGoals": ["OAuth/social login"]
+  },
+  "beadMetadata": {
+    "depends_on": [],
+    "parallel": true,
+    "conflicts_with": [],
+    "blocks": [],
+    "estimated_hours": 4
+  }
+}
+```
+
+## Task Schema
+
+See `references/prd-schema.json`.
+
+## Conversion Rules
+
+### Tasks from Markdown
+
+- Each `### Title [category]` becomes a task
+- Generate `id` as `<category>-<number>` (e.g., `api-1`, `db-2`) or a descriptive slug
+- Text after title becomes `description`
+- Items under `**Verification:**` become `steps`
+- `passes` always starts `false`
+- Extract `**Metadata:**` yaml block for dependency info:
+  - `depends_on`: Task titles or IDs that must complete first
+  - `parallel`: Can run concurrently (default: true)
+  - `conflicts_with`: Tasks modifying same files
+  - `files`: Files this task will modify
+
+### Bead Metadata
+
+Extract the `## Bead Metadata` yaml block from the PRD header:
+
+```yaml
+depends_on: [] # Bead IDs
+parallel: true
+conflicts_with: [] # Bead IDs
+blocks: []
+estimated_hours: 2
+```
+
+Store in `beadMetadata` field in the JSON output.
+
+### Steps Are Verification
+
+Steps must be written as **verification steps**, not implementation instructions.
+
+Bad: "Add a controller and write a service"
+Good: "POST /api/foo returns 201" / "bun test passes"
+
+## Progress File
+
+If `.beads/artifacts/<bead-id>/progress.txt` does not exist, create it with:
+
+```markdown
+# Progress Log
+
+Bead: <bead-id>
+Started: <YYYY-MM-DD>
+
+## Codebase Patterns
+
+<!-- Consolidate reusable patterns here -->
+
+---
+
+<!-- Task logs below - APPEND ONLY -->
+```
+
+## After Conversion
+
+Tell the user:
+
+```
+PRD converted:
+  - .beads/artifacts/<bead-id>/prd.md
+  - .beads/artifacts/<bead-id>/prd.json
+  - .beads/artifacts/<bead-id>/progress.txt
+
+Next: Create detailed implementation plan
+  skill({ name: "writing-plans" })
+
+Or start execution directly:
+  /start <bead-id>
+
+Full lifecycle reference:
+  skill({ name: "development-lifecycle" })
+```

package/dist/template/.opencode/skill/prd-task/references/prd-schema.json

@@ -0,0 +1,124 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"title": "PRD Task Schema",
+	"description": "Executable task list converted from PRD markdown",
+	"type": "object",
+	"required": ["beadId", "tasks"],
+	"properties": {
+		"beadId": {
+			"type": "string",
+			"description": "Bead identifier (e.g., br-abc123)"
+		},
+		"prdName": {
+			"type": "string",
+			"description": "Optional slug for the PRD"
+		},
+		"tasks": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["id", "category", "description", "steps", "passes"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"description": "Task identifier (e.g., functional-1, api-2)"
+					},
+					"category": {
+						"type": "string",
+						"description": "Task category (e.g., functional, api, db, ui)"
+					},
+					"description": {
+						"type": "string",
+						"description": "One sentence describing the end state"
+					},
+					"steps": {
+						"type": "array",
+						"items": { "type": "string" },
+						"description": "Verification steps that prove the task is complete"
+					},
+					"passes": {
+						"type": "boolean",
+						"default": false,
+						"description": "Whether all verification steps pass"
+					},
+					"metadata": {
+						"type": "object",
+						"description": "Task dependency and execution metadata",
+						"properties": {
+							"depends_on": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Task IDs that must complete first"
+							},
+							"parallel": {
+								"type": "boolean",
+								"default": true,
+								"description": "Can run concurrently with other parallel tasks"
+							},
+							"conflicts_with": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Task IDs that modify same files (cannot parallelize)"
+							},
+							"files": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Files this task will modify"
+							}
+						}
+					}
+				}
+			}
+		},
+		"context": {
+			"type": "object",
+			"description": "Technical context from the PRD",
+			"properties": {
+				"patterns": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Existing codebase patterns to follow"
+				},
+				"keyFiles": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Key files to reference"
+				},
+				"nonGoals": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Explicitly out of scope items"
+				}
+			}
+		},
+		"beadMetadata": {
+			"type": "object",
+			"description": "Bead-level metadata from PRD",
+			"properties": {
+				"depends_on": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Bead IDs that must complete before this one"
+				},
+				"parallel": {
+					"type": "boolean",
+					"description": "Can run concurrently with other parallel beads"
+				},
+				"conflicts_with": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Bead IDs that modify same files"
+				},
+				"blocks": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Bead IDs waiting on this one"
+				},
+				"estimated_hours": {
+					"type": "number",
+					"description": "Time estimate for planning"
+				}
+			}
+		}
+	}
+}

package/dist/template/.opencode/skill/prompt-leverage/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: prompt-leverage
+description: >-
+  Strengthen raw user prompts into execution-ready instruction sets. Use when processing
+  user input to upgrade it with clear objective, context, work style, tool rules, output
+  contract, verification, and done criteria before planning or execution.
+metadata:
+  dependencies: []
+---
+
+# Prompt Leverage
+
+Strengthen the user's current prompt into a stronger working instruction set without changing the underlying intent. Preserve the task, fill in missing execution structure, and add only enough scaffolding to improve reliability.
+
+This skill acts as a **pre-processing layer** — it runs on user input BEFORE planning/execution to ensure every prompt is execution-ready.
+
+## Workflow
+
+1. Read the raw prompt and identify the real job to be done.
+2. Infer the task type: coding, research, writing, analysis, planning, or review.
+3. Rebuild the prompt with the framework blocks in `references/framework.md`.
+4. Keep the result proportional: do not over-specify a simple task.
+5. Return both the improved prompt and a short explanation of what changed when useful.
+
+## Transformation Rules
+
+- Preserve the user's objective, constraints, and tone unless they conflict.
+- Prefer adding missing structure over rewriting everything stylistically.
+- Add context requirements only when they improve correctness.
+- Add tool rules only when tool use materially affects correctness.
+- Add verification and completion criteria for non-trivial tasks.
+- Keep prompts compact enough to be practical in repeated use.
+
+## Framework Blocks
+
+Use these blocks selectively.
+
+- `Objective`: state the task and what success looks like.
+- `Context`: list sources, files, constraints, and unknowns.
+- `Work Style`: set depth, breadth, care, and first-principles expectations.
+- `Tool Rules`: state when tools, browsing, or file inspection are required.
+- `Output Contract`: define structure, formatting, and level of detail.
+- `Verification`: require checks for correctness, edge cases, and better alternatives.
+- `Done Criteria`: define when the agent should stop.
+
+## Output Modes
+
+Choose one mode based on the user request.
+
+- `Inline upgrade`: provide the upgraded prompt only.
+- `Upgrade + rationale`: provide the prompt plus a brief list of improvements.
+- `Template extraction`: convert the prompt into a reusable fill-in-the-blank template.
+- `Hook spec`: explain how to apply the framework automatically before execution.
+
+## Quality Bar
+
+Before finalizing, check the upgraded prompt:
+
+- still matches the original intent
+- does not add unnecessary ceremony
+- includes the right verification level for the task
+- gives the agent a clear definition of done
+
+If the prompt is already strong, say so and make only minimal edits.
+
+## Intensity Levels
+
+Use the minimum level that matches the task.
+
+- `Light`: simple edits, formatting, quick rewrites.
+- `Standard`: typical coding, research, and drafting tasks.
+- `Deep`: debugging, architecture, complex research, or high-stakes outputs.
+
+## Task-Type Adjustments
+
+### Coding
+
+- Emphasize repo context, file inspection, smallest correct change, validation, and edge cases.
+
+### Research
+
+- Emphasize source quality, evidence gathering, synthesis, uncertainty, and citations.
+
+### Writing
+
+- Emphasize audience, tone, structure, constraints, and revision criteria.
+
+### Review
+
+- Emphasize fresh-eyes critique, failure modes, alternatives, and explicit severity.