opencodekit 0.15.0 → 0.15.2

package/dist/template/.opencode/skill/opensrc/references/cli-usage.md

@@ -0,0 +1,176 @@
+# opensrc CLI Reference
+
+## Contents
+- Fetch command (default)
+- List command
+- Remove command
+- Clean command
+- Global options
+
+## Fetch Command (Default)
+
+Fetch source for packages/repos.
+
+```bash
+opensrc [packages...] [options]
+```
+
+### Package Formats
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| `<name>` | `zod` | npm package (latest or installed version) |
+| `<name>@<version>` | `zod@3.22.0` | npm package at specific version |
+| `npm:<name>` | `npm:react` | Explicit npm prefix |
+| `pypi:<name>` | `pypi:requests` | Python package from PyPI |
+| `pip:<name>` | `pip:flask` | Alias for pypi: |
+| `crates:<name>` | `crates:serde` | Rust crate from crates.io |
+| `cargo:<name>` | `cargo:tokio` | Alias for crates: |
+
+### Repository Formats
+
+| Format | Example |
+|--------|---------|
+| `owner/repo` | `vercel/ai` |
+| `owner/repo@ref` | `vercel/ai@v1.0.0` |
+| `owner/repo#ref` | `vercel/ai#main` |
+| `github:owner/repo` | `github:facebook/react` |
+| `gitlab:owner/repo` | `gitlab:inkscape/inkscape` |
+| `https://github.com/...` | Full URL |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--cwd <path>` | Working directory (default: cwd) |
+| `--modify` | Allow file modifications (skip prompt) |
+| `--modify=false` | Deny file modifications (skip prompt) |
+
+### Examples
+
+```bash
+# Single package
+opensrc zod
+
+# Multiple packages
+opensrc react react-dom next
+
+# Mixed registries
+opensrc zod pypi:requests crates:serde
+
+# Specific versions
+opensrc zod@3.22.0
+opensrc pypi:requests==2.31.0
+
+# GitHub repos
+opensrc vercel/ai
+opensrc facebook/react@v18.2.0
+```
+
+## List Command
+
+List all fetched sources.
+
+```bash
+opensrc list [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+| `--cwd <path>` | Working directory |
+
+### Output
+
+Groups by registry (npm, PyPI, crates.io) and repos:
+
+```
+npm Packages:
+
+  zod@3.22.0
+    Path: opensrc/repos/github.com/colinhacks/zod
+    Fetched: Jan 10, 2025
+
+Repositories:
+
+  github.com/vercel/ai@main
+    Path: opensrc/repos/github.com/vercel/ai
+    Fetched: Jan 10, 2025
+
+Total: 1 package(s) (1 npm), 1 repo(s)
+```
+
+## Remove Command
+
+Remove specific sources.
+
+```bash
+opensrc remove <packages...> [options]
+opensrc rm <packages...>  # alias
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--cwd <path>` | Working directory |
+
+### Examples
+
+```bash
+opensrc remove zod
+opensrc rm pypi:requests
+opensrc remove vercel/ai
+```
+
+## Clean Command
+
+Remove all sources by category.
+
+```bash
+opensrc clean [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--packages` | Only remove packages (all registries) |
+| `--repos` | Only remove repos |
+| `--npm` | Only remove npm packages |
+| `--pypi` | Only remove PyPI packages |
+| `--crates` | Only remove crates.io packages |
+| `--cwd <path>` | Working directory |
+
+### Examples
+
+```bash
+opensrc clean              # Remove everything
+opensrc clean --packages   # Remove all packages, keep repos
+opensrc clean --npm        # Remove only npm packages
+opensrc clean --repos      # Remove only repos
+```
+
+## File Modifications
+
+On first run, prompts to modify:
+
+1. **`.gitignore`** - Adds `opensrc/` entry
+2. **`tsconfig.json`** - Adds `opensrc/` to exclude array
+3. **`AGENTS.md`** - Adds source code reference section
+
+Choice saved to `opensrc/settings.json`.
+
+### AGENTS.md Section
+
+Adds guidance for AI agents:
+
+```markdown
+<!-- opensrc:start -->
+## Source Code Reference
+Source code for dependencies is available in `opensrc/`...
+See `opensrc/sources.json` for the list of available packages.
+<!-- opensrc:end -->
+```

package/dist/template/.opencode/skill/opensrc/references/registry-support.md

@@ -0,0 +1,137 @@
+# Registry Support
+
+## Contents
+- npm (Node.js)
+- PyPI (Python)
+- crates.io (Rust)
+- Repository hosts
+
+## npm (Node.js)
+
+**Prefixes:** `npm:` (or none - default)
+
+**API:** `https://registry.npmjs.org/{package}`
+
+### Version Detection
+
+Auto-detects installed version from (in order):
+1. `node_modules/{pkg}/package.json`
+2. `package-lock.json` (npm v6 and v7+ formats)
+3. `pnpm-lock.yaml`
+4. `yarn.lock`
+5. `package.json` dependencies (strips `^`, `~`, etc.)
+
+### Spec Parsing
+
+```
+zod           → name: zod, version: (detected or latest)
+zod@3.22.0    → name: zod, version: 3.22.0
+@babel/core   → name: @babel/core (scoped)
+@babel/core@7.0.0 → name: @babel/core, version: 7.0.0
+```
+
+### Repo URL Extraction
+
+From `repository` field, normalizes:
+- `git+https://...` → `https://...`
+- `git://...` → `https://...`
+- `git+ssh://git@...` → `https://...`
+- Removes `.git` suffix
+- Handles `github:owner/repo` shorthand
+
+### Monorepo Support
+
+Uses `repository.directory` field for packages in monorepos.
+Path becomes: `repos/{host}/{owner}/{repo}/{directory}`
+
+## PyPI (Python)
+
+**Prefixes:** `pypi:`, `pip:`, `python:`
+
+**API:** `https://pypi.org/pypi/{package}/json`
+
+### Spec Parsing
+
+```
+requests        → name: requests
+requests==2.31.0 → name: requests, version: 2.31.0
+requests@2.31.0  → name: requests, version: 2.31.0
+```
+
+### Repo URL Extraction
+
+Checks `project_urls` in order:
+1. `Source`, `Source Code`
+2. `Repository`, `GitHub`
+3. `Code`, `Homepage`
+
+Falls back to `home_page` if it's a git URL.
+
+## crates.io (Rust)
+
+**Prefixes:** `crates:`, `cargo:`, `rust:`
+
+**API:** `https://crates.io/api/v1/crates/{crate}`
+
+### Spec Parsing
+
+```
+serde       → name: serde
+serde@1.0.0 → name: serde, version: 1.0.0
+```
+
+### Repo URL Extraction
+
+Uses `repository` field, falls back to `homepage` if it's a git URL.
+
+## Repository Hosts
+
+### GitHub
+
+**API:** `https://api.github.com/repos/{owner}/{repo}`
+
+Resolves default branch, constructs clone URL.
+
+**Rate limiting:** 60 req/hour unauthenticated. Error on 403.
+
+### GitLab
+
+**API:** `https://gitlab.com/api/v4/projects/{owner}%2F{repo}`
+
+Resolves default branch, constructs clone URL.
+
+### Bitbucket
+
+Supported for parsing (`bitbucket:owner/repo`), but no API resolution.
+Assumes `main` as default branch.
+
+## Repo Spec Formats
+
+| Format | Example | Host |
+|--------|---------|------|
+| `owner/repo` | `vercel/ai` | github.com |
+| `github:owner/repo` | `github:facebook/react` | github.com |
+| `gitlab:owner/repo` | `gitlab:inkscape/inkscape` | gitlab.com |
+| `bitbucket:owner/repo` | `bitbucket:atlassian/python-bitbucket` | bitbucket.org |
+| `host/owner/repo` | `gitlab.com/owner/repo` | (from URL) |
+| Full URL | `https://github.com/...` | (from URL) |
+
+## Ref Specifications
+
+Append to repo spec:
+
+| Suffix | Example | Meaning |
+|--------|---------|---------|
+| `@ref` | `owner/repo@v1.0.0` | Tag, branch, or commit |
+| `#ref` | `owner/repo#main` | Branch (alternative syntax) |
+
+URL paths also supported: `https://github.com/owner/repo/tree/branch`
+
+## Git Tag Patterns
+
+When cloning packages, tries tags in order:
+1. `v{version}` - Most common (e.g., `v3.22.0`)
+2. `{version}` - No prefix (e.g., `3.22.0`)
+3. Default branch - Fallback with warning
+
+Uses `--depth 1 --single-branch` for efficient cloning.

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

@@ -0,0 +1,212 @@
+---
+name: prd
+description: Create Product Requirements Documents (PRDs) that define the end state of a feature. Use when planning new features, migrations, or refactors. Generates structured PRDs with acceptance criteria.
+---
+
+# PRD Creation Skill
+
+Create Product Requirements Documents suitable for RFC review by Principal Engineers, Designers, and Product Owners.
+
+The PRD describes WHAT to build and WHY, not HOW or in WHAT ORDER.
+
+## Beads-Native Output (Recommended)
+
+When you are working on a Beads task (you have a bead id like `bd-...`), 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, fall back to writing `prd-<feature-name>.md` in the project root.
+
+## Workflow
+
+1. Confirm if the user has an existing bead id.
+   - If yes: use `.beads/artifacts/<bead-id>/prd.md`
+   - If no: write `prd-<feature-name>.md` in project root
+2. Ask clarifying questions (5–7 max).
+3. Explore codebase patterns and constraints.
+4. Write a PRD that includes a machine-convertible `## Tasks` section (see below).
+
+## 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
+
+Write a PRD in markdown using this structure.
+
+IMPORTANT: include a `## Tasks` section that `prd-task` can convert.
+
+```markdown
+# PRD: <Feature Name>
+
+**Bead:** <bd-...>  
+**Date:** <YYYY-MM-DD>
+
+---
+
+## Problem Statement
+
+### What problem are we solving?
+
+Clear description of the problem. Include user impact and business impact.
+
+### Why now?
+
+What triggered this work? Cost of inaction?
+
+### Who is affected?
+
+- **Primary users:** Description
+- **Secondary users:** Description
+
+---
+
+## Proposed Solution
+
+### Overview
+
+One paragraph describing what this feature does when complete.
+
+### User Experience (if applicable)
+
+How will users interact with this feature? Include user flows for primary scenarios.
+
+---
+
+## End State
+
+When this PRD is complete, the following will be true:
+
+- [ ] Capability 1 exists and works
+- [ ] Capability 2 exists and works
+- [ ] All acceptance criteria pass
+- [ ] Tests cover the new functionality
+- [ ] Documentation is updated
+
+---
+
+## Success Metrics
+
+### Quantitative
+
+| Metric   | Current | Target | Measurement Method |
+| -------- | ------- | ------ | ------------------ |
+| Metric 1 | X       | Y      | How measured       |
+
+### Qualitative
+
+- User feedback criteria
+- Team/process improvements expected
+
+---
+
+## Acceptance Criteria
+
+### Feature: <Name>
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+---
+
+## Technical Context
+
+### Existing Patterns
+
+- Pattern 1: `src/path/to/example.ts` - Why relevant
+
+### Key Files
+
+- `src/relevant/file.ts` - Description of relevance
+
+---
+
+## Risks & Mitigations
+
+| Risk   | Likelihood   | Impact       | Mitigation      |
+| ------ | ------------ | ------------ | --------------- |
+| Risk 1 | High/Med/Low | High/Med/Low | How to mitigate |
+
+---
+
+## Non-Goals (v1)
+
+Explicitly out of scope:
+
+- Thing we're not building - why deferred
+
+---
+
+## Tasks
+
+Each task must be written like:
+
+### <Task Title> [category]
+
+One sentence describing the end state.
+
+**Verification:**
+
+- A command or manual check that proves it works
+- Another check
+
+Example:
+
+### Registration API [api]
+
+Users can register with email/password.
+
+**Verification:**
+
+- `curl -X POST /api/auth/register ...` returns 201
+- Duplicate email returns 409
+
+---
+
+## Open Questions
+
+| Question   | Owner | Due Date | Status        |
+| ---------- | ----- | -------- | ------------- |
+| Question 1 | Name  | Date     | Open/Resolved |
+```
+
+## Key Principles
+
+- Problem Before Solution
+- Define End State, Not Process
+- Technical Context Enables Autonomy
+- Non-Goals Prevent Scope Creep
+- Risks & Alternatives Show Rigor

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

@@ -0,0 +1,128 @@
+---
+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
+---
+
+# PRD Task Skill (Beads-Native)
+
+Convert a markdown PRD into executable JSON format for autonomous task completion.
+
+The PRD defines the **end state** via tasks with verification steps. The agent decides HOW to get there.
+
+## 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 (`bd-...`).
+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": "bd-...",
+  "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
+    }
+  ]
+}
+```
+
+## 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`
+
+### 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:
+  /start <bead-id>
+  /complete-next-task <bead-id>
+```

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

@@ -0,0 +1,28 @@
+{
+	"beadId": "bd-abc123",
+	"prdName": "user-authentication",
+	"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",
+				"Verify password is not in response",
+				"Attempt duplicate email, verify 409 response",
+				"Attempt invalid email, verify 400 response"
+			],
+			"passes": false
+		}
+	],
+	"context": {
+		"patterns": [
+			"API routes: src/routes/items.ts",
+			"Validation: src/lib/validate.ts",
+			"DB queries: src/db/queries/"
+		],
+		"keyFiles": ["src/db/schema.ts", "src/routes/index.ts"],
+		"nonGoals": ["OAuth/social login", "Password reset", "Email verification"]
+	}
+}