Thomashighbaugh/provision

Provision

The /init-project provision subcommand analyzes a codebase (or user intent for empty directories) and auto-generates project-specific agents, skills, tools, and rules under .opencode/. These project-level artifacts wrap and extend existing global agents with deep project-specific context, making subagents dramatically more effective.

When to Use

• After /init-project setup or /init-project detect to get AI agents that understand the project
• When adding a new subsystem (e.g., adding backend agents after frontend was already set up)
• When the project's architecture has significantly changed
• For brownfield projects being onboarded to OpenCode Hubs
• Any time you want AI agents that deeply understand your codebase conventions

No-Argument Behavior

When invoked without arguments (/init-project provision), list sub-options as plain text:

full       - Provision everything (agents + skills + tools + rules)
agents     - Generate project agent wrappers only
skills     - Generate project skills only
tools      - Generate project tools only
rules      - Generate project rules only
resume     - Resume from last checkpoint
status     - Show provisioning state

Do NOT call hubMenu or any other tool — just output the list directly and ask the user to choose.

With-Argument Behavior

1. Print reminder: "Provisioning project-aware agents, skills, tools, and rules for your codebase. I'll analyze your project and generate tailored artifacts."
2. Check for detection data at .opencode/state/init/init-detection.json — if missing, suggest running /init-project detect first
3. If user provides free-text (not a known sub-option), treat it as a project description and use it to populate detection data for empty directories
4. Delegate to provision.mjs for the heavy lifting
5. Save checkpoint after each phase
6. Report results inline — do NOT offer hand-off to other hubs

Sub-Option Behavior

| Sub-Option | Delegates To | What It Does | |------------|-------------|--------------| | full | provision.mjs | Run all 7 phases — scan, agents, skills, tools, rules, install, verify | | agents | provision.mjs | Phase 2 only — generate project-aware agent wrappers | | skills | provision.mjs | Phase 3 only — generate project-specific skills | | tools | provision.mjs | Phase 4 only — generate project TypeScript tools | | rules | provision.mjs | Phase 5 only — generate project rules and conventions | | resume | self (inline) | Load latest checkpoint and continue from last incomplete phase | | status | self (inline) | Show provisioning state and checkpoint info |

Terse Reminders

| Sub-Option | Reminder on Invoke | |------------|-------------------| | full | Full provisioning: scan codebase, generate agents, skills, tools, rules, install, verify. | | agents | Generating project-aware agent wrappers with deep project context. | | skills | Generating project-specific workflow skills. | | tools | Generating project-specific TypeScript tools. | | rules | Generating project rules and conventions. | | resume | Resuming provisioning from last checkpoint. | | status | Showing provisioning state and checkpoint progress. |

Flags

| Flag | Effect | |------|--------| | --detect-only | Only scan the codebase — don't generate anything. Save detection results and exit. | | --skip-agents | Skip agent generation (Phase 2) | | --skip-skills | Skip skill generation (Phase 3) | | --skip-tools | Skip tool generation (Phase 4) | | --skip-rules | Skip rule generation (Phase 5) | | --force | Overwrite existing files without prompting | | --language <lang> | Force language detection override (e.g., --language python) | | --framework <fw> | Force framework override (e.g., --framework fastapi) |

Default (no flags): Run all phases, prompt before overwriting existing files.

State Management

Provisioning state lives in .opencode/state/init/ (shares state directory with /init-project).

State Paths

| Path | Purpose | |------|---------| | .opencode/state/init/init-detection.json | Phase 1 codebase scan results | | .opencode/state/init/provision-checkpoint.json | Last completed phase checkpoint | | .opencode/state/init/provision-report.md | Phase 8 verification report |

Detection File Format

Generated by Phase 1 (Scan) and saved to .opencode/state/init/init-detection.json:

{
  "language": "typescript",
  "version": "5.x",
  "framework": "nextjs",
  "frameworkVersion": "14",
  "packageManager": "npm",
  "buildSystem": "tsc + next build",
  "testFramework": "jest",
  "testCommand": "npm test",
  "lintCommand": "npm run lint",
  "directories": {
    "source": "src/",
    "tests": "tests/",
    "components": "src/components/",
    "pages": "src/app/",
    "api": "src/app/api/",
    "public": "public/"
  },
  "keyFiles": ["package.json", "tsconfig.json", "next.config.js"],
  "architecture": "Next.js App Router with React Server Components",
  "stateManagement": "React hooks + context",
  "styling": "Tailwind CSS + CSS Modules",
  "testingStrategy": "Jest + React Testing Library",
  "errorHandling": "Custom error boundary + try/catch in API routes",
  "importStyle": "ES modules with path aliases (@/ -> src/)",
  "deployment": "Vercel",
  "namingConventions": {
    "components": "PascalCase",
    "utilities": "camelCase",
    "files": "kebab-case",
    "constants": "UPPER_SNAKE_CASE"
  },
  "ci": "github-actions",
  "confidence": "high"
}

When invoked on an empty directory with free-text intent, populate a minimal detection object from the description:

{
  "language": "python",
  "framework": "fastapi",
  "description": "RESTful API service for inventory management with PostgreSQL backend",
  "directories": {
    "source": "app/",
    "tests": "tests/"
  },
  "confidence": "low"
}

Checkpoint Format

{
  "lastCompletedPhase": 3,
  "timestamp": "2026-06-11T14:30:00Z",
  "subcommand": "full",
  "skipAgents": false,
  "skipSkills": true,
  "skipTools": false,
  "skipRules": false,
  "force": false,
  "generatedFiles": {
    "agents": [".opencode/agents/executor.md", ".opencode/agents/planner.md"],
    "skills": [],
    "tools": [".opencode/tools/project-info.ts", ".opencode/tools/deploy.ts"],
    "rules": [".opencode/rules/00-typescript-conventions.md"],
    "config": ".opencode/opencode.jsonc"
  }
}

Resume Behavior

• Resume: Load latest checkpoint from .opencode/state/init/provision-checkpoint.json, continue from the next uncompleted phase
• Status: List all state files in .opencode/state/init/ with timestamps, show last completed phase

Architecture

| Phase | What | Delegates To | Output Location | |-------|------|--------------|-----------------| | 1 - Scan | Analyze codebase or parse user description for empty dirs | explore agent + provision.mjs | .opencode/state/init/init-detection.json | | 2 - Agents | Generate project-aware agent wrappers around global agents | provision.mjs | .opencode/agents/ | | 3 - Skills | Generate project-specific workflow skills | provision.mjs | .opencode/skills/{name}/ | | 4 - Tools | Generate project-specific TypeScript tools | provision.mjs | .opencode/tools/ | | 5 - Rules | Generate project rules and conventions | provision.mjs | .opencode/rules/ | | 6 - Install | Register in opencode.jsonc, create AGENTS.md | config-orchestrator | .opencode/opencode.jsonc, .opencode/AGENTS.md | | 7 - Verify | Validate everything works end-to-end | verifier agent | .opencode/state/init/provision-report.md |

Phase 1: Scan

Analyze the project codebase to extract architecture, conventions, and patterns. For empty directories, parse the user's free-text description.

DETECTION_FILE=".opencode/state/init/init-detection.json"
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

echo "Scanning codebase for project intelligence..."

# If detection already exists and --force not set, re-use it
if [ -f "$DETECTION_FILE" ] && [ "$FORCE" != "true" ]; then
  echo "Re-using existing detection data from $DETECTION_FILE"
  cat "$DETECTION_FILE"
else
  # Delegate to explore agent for deep codebase analysis
  # Or use provision.mjs --scan-only
  node skills/provision/scripts/provision.mjs --scan-only
fi

Detection captures:

• Language, version, framework
• Package manager, build system, test framework
• Source directories and their purposes
• Architecture style (e.g., "Next.js App Router", "Clean Architecture", "MVP")
• State management approach
• Styling/CSS approach
• Testing strategy and mocking patterns
• Error handling patterns
• Import/module conventions
• Naming conventions across the codebase
• CI/CD configuration
• Deployment targets
• Available LSPs — detects language servers on the system (typescript-language-server, rust-analyzer, gopls, pyright, etc.) and generates the lsp config block in opencode.jsonc

LSP Detection

The scanner checks for installed language server binaries and sets the lsp boolean in opencode.jsonc:

{
  "lsp": true   // Language servers detected on system
}

The lsp key is a boolean (true/false), not an object. Language servers are auto-detected by OpenCode at runtime.

Supported LSPs by language:

| Language | LSP Binary | Detection | |----------|-----------|-----------| | TypeScript/JavaScript | typescript-language-server | Always enabled | | Python | pyright or pylsp | which check | | Rust | rust-analyzer | which check | | Go | gopls | which check | | Lua | lua-language-server | which check | | Vue | vue-language-server | which check | | Svelte | svelte-language-server | which check | | CSS | Built into OpenCode | Always enabled | | HTML | Built into OpenCode | Always enabled | | JSON | Built into OpenCode | Always enabled |

Enabling LSP gives agents instant type feedback via lsp_diagnostics instead of waiting for full build commands.

Phase 2: Agents

Generate project-aware agent wrappers in .opencode/agents/. These extend existing global agents by injecting project-specific context into their prompts.

Agent Wrapper Template:

---
extends: ../global-agent-name
description: Project-aware wrapper for [original agent] with [project] context injected
model: ollama/deepseek-v4-flash:cloud
mode: subagent
---

You are a project-aware [agent type] for a [language]/[framework] project.

## Project Context

### Language & Framework
- Language: [language] [version]
- Framework: [framework] [version]
- Package manager: [packageManager]
- Build system: [buildSystem]

### Architecture
- Architecture: [architecture description]
- Key directories: [list key directories and purposes]
- State management: [approach]
- Styling: [approach]

### Conventions
- File naming: [convention]
- Component naming: [convention]
- Import style: [convention]
- Error handling: [pattern]

### Testing
- Test framework: [framework]
- Test command: `[command]`
- Coverage target: [target]
- Mocking strategy: [approach]

### Commands
- Build: `[command]`
- Test: `[command]`
- Lint: `[command]`
- Dev: `[command]`

Global agents that get wrappers (by default):

| Global Agent | Wrapper Purpose | |-------------|-----------------| | executor | Implementation with project conventions, build commands, testing patterns | | planner | Planning with awareness of project structure, dependencies, and subsystems | | architect | Architecture decisions respecting existing patterns, tradeoffs, and constraints | | critic | Review with project-specific quality bars, conventions, and anti-patterns | | code-reviewer | Code review using project conventions, testing expectations, and naming rules | | security-reviewer | Security audit with awareness of project-specific attack surface (framework, deployment) | | refactoring | Refactoring with knowledge of module boundaries, import conventions, and test coverage | | test-engineer | Test writing matching project test framework, mocking strategy, and coverage targets | | debugger | Debugging with project-specific error handling patterns, logging conventions, and entry points | | verifier | Verification using project-specific test commands, lint commands, and build commands |

Each wrapper agent file is named to match its global counterpart: .opencode/agents/executor.md, .opencode/agents/planner.md, etc. The extends field references ../../agents/{name}.md (relative to .opencode/).

Selection is smart — only create wrappers for agents relevant to the detected stack:

• TypeScript/React: Full set (frontend-specific bias)
• Python/data: executor, planner, test-engineer, debugger (data-science bias)
• Rust/systems: executor, code-reviewer, debugger, security-reviewer (systems bias)
• Go/microservices: executor, planner, code-reviewer, security-reviewer (backend bias)

Phase 3: Skills

Generate project-specific skills in .opencode/skills/{name}/SKILL.md for repeatable workflows unique to the project.

Standard project skills:

build — Build workflow

---
name: build
description: Build the [project] project using [buildSystem] — handles compilation, bundling, and output verification
level: 1
---

# Build

Build instructions for the [project] project.

## Workflow

1. Install dependencies: `[packageManager] install`
2. Build: `[buildCommand]`
3. Verify build output exists: `[verify step]`

## Common Issues

- [Common issue 1 and resolution]
- [Common issue 2 and resolution]

test — Run project tests

---
name: test
description: Run [project] tests using [testFramework] — run all, single file, or watch mode
level: 1
---

# Test

Test execution for the [project] project.

## Commands

| Command | Description |
|---------|-------------|
| `[testCommand]` | Run all tests |
| `[testCommand] -- --coverage` | Run with coverage report |
| `[testCommand] -- --watch` | Watch mode |
| `[testCommand] [file-path]` | Specific test file |

## Conventions

- Test location: [test directory]
- Naming: [test file naming convention]
- Mocking: [mocking strategy]
- Fixtures: [fixture convention]

lint — Lint/format

---
name: lint
description: Lint and format [project] code using [lintTool] — auto-fix, check, format
level: 1
---

# Lint

Lint and format the [project] project.

## Commands

| Command | Description |
|---------|-------------|
| `[lintCommand]` | Run lint check |
| `[lintCommand] -- --fix` | Auto-fix issues |
| `[formatCommand]` | Format code |

deploy — Deploy workflow (if applicable)

Generated when a deployment target is detected (Vercel, Netlify, Docker, etc.).

---
name: deploy
description: Deploy [project] to [deploymentTarget] — preview, production, rollback
level: 1
---

# Deploy

Deployment workflow for [project].

## Environments

- Preview: [preview URL / command]
- Production: [production command]

## Workflow

1. Build: `[buildCommand]`
2. Deploy: `[deployCommand]`
3. Verify: [verification step]

architecture — Architecture reference

---
name: architecture
description: Reference skill describing [project]'s architecture — directory layout, design patterns, data flow
level: 1
---

# Architecture

Architecture reference for the [project] project.

## Directory Layout

[Directory structure with descriptions]

## Design Patterns

[Patterns used in the project]

## Data Flow

[High-level data flow description]

## Key Modules

| Module | Location | Purpose |
|--------|----------|---------|
| [module] | [path] | [purpose] |

conventions — Coding conventions

---
name: conventions
description: Coding conventions for [project] — naming, imports, error handling, testing
level: 1
---

# Conventions

Coding conventions for the [project] project.

## Naming

| Category | Convention | Example |
|----------|-----------|---------|
| Components | [convention] | [example] |
| Utilities | [convention] | [example] |
| Files | [convention] | [example] |
| Constants | [convention] | [example] |

## Imports

[Import style description]

## Error Handling

[Error handling pattern description]

## Testing

[Testing convention description]

Only generate skills that are relevant — skip deploy if no deployment config detected, skip architecture if project is too small/simple.

Phase 4: Tools

Generate project-specific TypeScript tools in .opencode/tools/.

CRITICAL: All generated tools MUST go into .opencode/tools/ — never at the project root. OpenCode auto-discovers tools from .opencode/tools/ via their default exports. Root-level ./tools/, ./scripts/, or standalone .ts/.sh files are NOT auto-discovered and create root directory pollution. See rules/artifact-placement.md for the full rule.

Standard tools:

project-info.ts

Returns project metadata — language, framework, build/test/lint commands. Used by other agents to self-configure.

import { tool } from "@opencode-ai/plugin"

export default tool({
  name: "project-info",
  description: "Returns project metadata including language, framework, build/test/lint commands, and key conventions.",
  args: {},
  async execute(args, context) {
    return {
      language: "[language]",
      framework: "[framework]",
      packageManager: "[packageManager]",
      buildCommand: "[buildCommand]",
      testCommand: "[testCommand]",
      lintCommand: "[lintCommand]",
      devCommand: "[devCommand]",
      sourceDir: "[sourceDir]",
      testDir: "[testDir]",
      conventions: {
        naming: "[naming convention summary]",
        testing: "[testing summary]",
        errors: "[error handling summary]"
      }
    }
  }
})

deploy.ts (if deployment configured)

import { tool } from "@opencode-ai/plugin"

export default tool({
  name: "deploy",
  description: "Deploy the project to [deploymentTarget] — run build then deploy.",
  args: {
    environment: {
      type: "string",
      description: "Deployment environment (preview or production)",
      default: "preview"
    }
  },
  async execute(args, context) {
    const env = args.environment || "preview"
    // Implementation: run build then deploy
    return { environment: env, status: "initiated" }
  }
})

db-migrate.ts (if database ORM detected)

import { tool } from "@opencode-ai/plugin"

export default tool({
  name: "db-migrate",
  description: "Run database migrations for [project] — create, apply, rollback.",
  args: {
    action: {
      type: "string",
      enum: ["create", "up", "down", "status"],
      description: "Migration action"
    },
    name: {
      type: "string",
      description: "Migration name (for create action)"
    }
  },
  async execute(args, context) {
    // Implementation based on detected ORM (Prisma, TypeORM, Alembic, etc.)
    return { action: args.action, status: "executed" }
  }
})

Tool generation is scoped to project needs — only create tools that match the detected stack. A static site with no database doesn't need db-migrate.ts.

Phase 5: Rules

Generate project-specific rule files in .opencode/rules/.

Rule files generated:

| File | Content | Always Generated | |------|---------|:---:| | 00-LANGFRAMEWORK-conventions.md | Language + framework code conventions | Yes | | 01-architecture.md | Project architecture overview | Yes | | 02-testing.md | Testing conventions and commands | Yes | | 03-naming.md | Naming conventions | Yes | | 04-API.md | API conventions (REST endpoints, GraphQL, etc.) | Only if API detected | | 05-database.md | Database conventions (ORM, migrations, queries) | Only if DB detected | | 06-deployment.md | Deployment conventions and CI/CD | Only if deployment detected | | 07-ui.md | UI component conventions (accessibility, styling, variants) | Only if frontend detected |

Template: 00-LANGFRAMEWORK-conventions.md

# [Language]/[Framework] Conventions

Auto-generated from codebase analysis for the [project] project.

## Code Organization

- Source code lives in [sourceDir]
- Tests live in [testDir]
- [Framework-specific structure conventions]

## Imports

- [Import style — e.g., "ES modules with path aliases"]
- [Any ordering or grouping conventions]
- [Barrel file conventions]

## Error Handling

- [Error handling pattern]
- [Custom error classes / error boundaries]
- [Logging approach]

## Async Patterns

- [Promise vs async/await conventions]
- [Error propagation]

Template: 01-architecture.md

# Architecture Overview

Auto-generated from codebase analysis for the [project] project.

## High-Level Architecture

[Architecture description — e.g., "Next.js App Router monolith with API routes"]

## Directory Layout

[sourceDir]/ [component-dir]/ — [description] [page-dir]/ — [description] [api-dir]/ — [description] [lib-dir]/ — [description] [tests-dir]/ [unit/] — [description] [integration/] — [description]

## Data Flow

[High-level data flow description — who talks to whom, what crosses boundaries]

## Key Dependencies

| Dependency | Version | Purpose |
|------------|---------|---------|
| [dep] | [ver] | [purpose] |

Template: 02-testing.md

# Testing Conventions

Auto-generated from codebase analysis for the [project] project.

## Test Framework

- Framework: [testFramework]
- Runner: [testRunner]
- Command: `[testCommand]`

## Test Organization

- Tests live in [testDir]
- Test files mirror source structure
- [File naming pattern]

## Coverage Target

- [Coverage percentage target]
- [Critical paths that must always be tested]

## Mocking

- [Mocking library/approach]
- [External service mocking strategy]
- [Fixture convention]

## Writing Tests

- [Describe what a good test looks like in this project]
- [Snapshot testing conventions if applicable]
- [Integration vs unit split]

Template: 03-naming.md

# Naming Conventions

Auto-generated from codebase analysis for the [project] project.

## General Rules

| Category | Convention | Example |
|----------|-----------|---------|
| Files | [convention] | [example] |
| Directories | [convention] | [example] |
| Classes | [convention] | [example] |
| Functions | [convention] | [example] |
| Variables | [convention] | [example] |
| Constants | [convention] | [example] |
| Types/Interfaces | [convention] | [example] |
| Enums | [convention] | [example] |

## Framework-Specific

| Element | Convention | Example |
|---------|-----------|---------|
| Components | [convention] | [example] |
| Hooks | [convention] | [example] |
| API Routes | [convention] | [example] |
| Database Models | [convention] | [example] |

## Abbreviations

[List of accepted/prohibited abbreviations in the project]

Template: 04-API.md (if API detected)

# API Conventions

Auto-generated from codebase analysis for the [project] project.

## API Style

- Type: [REST / GraphQL / gRPC / ...]
- Base URL: [base URL]
- Auth: [auth mechanism]

## Endpoint Patterns

| Pattern | Method | Example |
|---------|--------|---------|
| List | GET | `/api/[resource]` |
| Detail | GET | `/api/[resource]/:id` |
| Create | POST | `/api/[resource]` |
| Update | PATCH/PUT | `/api/[resource]/:id` |
| Delete | DELETE | `/api/[resource]/:id` |

## Request/Response Format

- Request body: [format — JSON, FormData, etc.]
- Response envelope: [shape — e.g., `{ data, error, meta }`]
- Error format: [error response shape]
- Pagination: [strategy — cursor/page/offset]

## Validation

- [Validation library and approach]
- [Error response for validation failures]

## Versioning

- [Versioning strategy — URL path, header, none]

Phase 6: Install

Register generated artifacts and create .opencode/AGENTS.md. Note that OpenCode auto-discovers agents, skills, tools, rules, and commands from their .opencode/ subdirectories — no config registration is needed for them. The only valid top-level config key for pointing to additional directories is "skills":

{
  // ... existing config ...

  "skills": {
    "paths": [
      "./.opencode/skills",
      // ... existing paths ...
    ]
  }
}

All other artifacts are auto-discovered:

• Agents from .opencode/agents/ — auto-loaded
• Tools from .opencode/tools/ — auto-discovered via default export
• Rules from .opencode/rules/ — auto-loaded via instructions glob patterns
• Commands from .opencode/commands/ — auto-discovered
• Do NOT inject "agents", "commands", "rules", or "agentPaths" keys — they break OpenCode's config loader

AGENTS.md content:

<!-- Parent: ../AGENTS.md -->
<!-- Generated: [DATE] -->

# .opencode — Provisioned Artifacts

Project-specific agents, skills, tools, and rules for [project].

## Agents

| Agent | Extends | Purpose |
|-------|---------|---------|
| [agent-name] | [global-agent] | [description] |

## Skills

| Skill | Purpose |
|-------|---------|
| [skill-name] | [description] |

## Tools

| Tool | Description |
|------|-------------|
| [tool-name] | [description] |

## Rules

| Rule | Description |
|------|-------------|
| [rule-name] | [description] |

Phase 7: Verify

Validate that all generated artifacts work correctly.

echo "=== Verification Report ==="
errors=0

# Check agents exist and have valid frontmatter
for agent in .opencode/agents/*.md; do
  if [ -f "$agent" ]; then
    name=$(basename "$agent" .md)
    has_desc=$(grep -c "^description:" "$agent" 2>/dev/null)
    has_extends=$(grep -c "^extends:" "$agent" 2>/dev/null)
    if [ "$has_desc" -gt 0 ] && [ "$has_extends" -gt 0 ]; then
      echo "  ✓ $name agent"
    else
      echo "  ✗ $name agent — missing description or extends"
      errors=$((errors + 1))
    fi
  fi
done

# Check skills exist and have valid frontmatter
for skill_dir in .opencode/skills/*/; do
  if [ -d "$skill_dir" ] && [ -f "${skill_dir}SKILL.md" ]; then
    name=$(basename "$skill_dir")
    has_name=$(grep -c "^name:" "${skill_dir}SKILL.md" 2>/dev/null)
    has_desc=$(grep -c "^description:" "${skill_dir}SKILL.md" 2>/dev/null)
    if [ "$has_name" -gt 0 ] && [ "$has_desc" -gt 0 ]; then
      echo "  ✓ $name skill"
    else
      echo "  ✗ $name skill — missing name or description"
      errors=$((errors + 1))
    fi
  fi
done

# Check tools compile (or at least parse)
for tool in .opencode/tools/*.ts; do
  if [ -f "$tool" ]; then
    name=$(basename "$tool" .ts)
    has_export=$(grep -c "export default" "$tool" 2>/dev/null)
    if [ "$has_export" -gt 0 ]; then
      echo "  ✓ $name tool"
    else
      echo "  ⚠ $name tool — may lack default export"
      errors=$((errors + 1))
    fi
  fi
done

# Check rules exist
for rule in .opencode/rules/??-*.md; do
  if [ -f "$rule" ]; then
    echo "  ✓ $(basename "$rule")"
  fi
done

# Check skills config (the only one that needs registration)
if grep -q ".opencode/skills" .opencode/opencode.jsonc 2>/dev/null; then
  echo "  ✓ Skills path registered in opencode.jsonc"
else
  echo "  ⚠ Skills path not in opencode.jsonc — add 'skills': { 'paths': ['./.opencode/skills'] } if needed"
fi

echo ""
if [ "$errors" -eq 0 ]; then
  echo "✓ All provisioned artifacts verified successfully"
else
  echo "✗ $errors issue(s) found — review above"
fi

Cross-Hub Hand-Off

• /init-project detect → /init-project provision — detection provides the codebase intelligence needed for generation
• /init-project provision → /harvest-context session — capture generated artifacts as durable context
• /init-project provision → /init-project verify — validate the full setup
• /ideation plans reference generated rules for project-specific context
• /orchestrate subagents load project wrappers for deep context injection
• /project commit workflows use generated conventions for consistency

provision.mjs Script

The scripts/provision.mjs script is the executable engine behind provisioning. It is called by this skill's phases.

Script API

node scripts/provision.mjs [options]

Options:
  --detection <file>     Path to detection JSON (default: .opencode/state/init/init-detection.json)
  --phases <list>        Comma-separated phase numbers (e.g., "1,2,3") or "all" (default: all)
  --skip-agents          Skip agent generation
  --skip-skills          Skip skill generation
  --skip-tools           Skip tool generation
  --skip-rules           Skip rules generation
  --force                Overwrite existing files without prompting
  --output-dir <dir>     Project .opencode directory (default: ./.opencode)
  --templates <dir>      Template directory (default: ./templates/)
  --checkpoint <file>    Checkpoint file path (default: .opencode/state/init/provision-checkpoint.json)
  --scan-only            Only scan the codebase, save detection, no generation
  --project-desc <text>  Project description for empty directories
  --verbose              Verbose output

Exit codes:
  0 — All phases completed successfully
  1 — One or more phases failed
  2 — Detection failed (input not usable)

Phases Implemented by the Script

| Phase Flag | Phase | Output | |------------|-------|--------| | --phases 1 | Scan | Saves detection JSON | | --phases 2 | Agents | Writes to .opencode/agents/*.md | | --phases 3 | Skills | Writes to .opencode/skills/*/SKILL.md | | --phases 4 | Tools | Writes to .opencode/tools/*.ts | | --phases 5 | Rules | Writes to .opencode/rules/*.md | | --phases 6 | Install | Updates opencode.jsonc, creates AGENTS.md | | --phases 7 | Verify | Writes verification report |

The script delegates each phase to the appropriate generation logic, accumulating a manifest of all files created. At the end of each phase, it writes an incremental checkpoint so provisioning can be resumed if interrupted.

Templates

The templates/ directory contains reusable templates used by provision.mjs for generating artifacts:

templates/
├── agents/               # Agent wrapper templates per-language
│   ├── wrapper.md        # Generic wrapper template
│   └── README.md         # Template documentation
├── skills/               # Skill templates
│   ├── build.md          # Build skill template
│   ├── test.md           # Test skill template
│   ├── lint.md           # Lint skill template
│   ├── deploy.md         # Deploy skill template
│   ├── architecture.md   # Architecture skill template
│   └── conventions.md    # Conventions skill template
├── tools/                # Tool templates
│   ├── project-info.ts   # Project info tool template
│   ├── deploy.ts         # Deploy tool template
│   └── db-migrate.ts     # DB migration tool template
├── rules/                # Rule templates per-language/framework
│   ├── conventions.md    # Language conventions template
│   ├── architecture.md   # Architecture overview template
│   ├── testing.md        # Testing conventions template
│   ├── naming.md         # Naming conventions template
│   ├── api.md            # API conventions template
│   ├── database.md       # Database conventions template
│   └── deployment.md     # Deployment conventions template
├── config/
│   └── opencode.jsonc    # opencode.jsonc snippet template
└── agents.md.template    # AGENTS.md template

These templates are populated at generation time by substituting detection data values into [placeholder] tokens.

Idempotency

The provision subcommand is safe to re-run. It:

• Preserves existing files unless --force is passed
• Detects and skips phases that have already completed
• Merges new artifacts without removing existing ones
• Reads detection data from checkpoint instead of re-scanning when possible
• Never deletes user-created project skills, agents, or tools
• Supports resume on interruption (each phase saves a checkpoint)

Resume on Failure

If a phase fails:

mkdir -p ".opencode/state/init"
echo '{"lastCompletedPhase":'$COMPLETED_PHASE',"timestamp":"'$(date -Iseconds)'","subcommand":"full"}' > ".opencode/state/init/provision-checkpoint.json"

Resume with /init-project provision resume or re-run with --force for a fresh start.

Related

• init-project skill — Parent hub that invokes provision
• phases/04-provisioning.md — Original provisioning docs in init-project
• deepinit skill — Documentation generation (complementary)
• opencode-agent-creator skill — Manual agent creation patterns
• skill-creator skill — Manual skill creation patterns
• opencode-command-creator skill — Custom command creation
• opencode-configure skill — Config management
• /harvest-context hub — Capture provisioned artifacts as durable context
• /init-project detect — Provides detection input for provisioning
• /init-project verify — Post-provision validation