Cookbook-style recipes that walk you through building real applications end-to-end
using OpenCastle's AI agent team. Each recipe covers setup, execution, iteration, and delivery.
Build a Personal Portfolio Website
Introduction
This cookbook walks you through building a complete personal portfolio website using
OpenCastle's AI agent team — from project setup to deployment-ready code. You'll run a
single start command that decomposes your goal, spins up a convoy of specialist agents,
and delivers production-quality code on a feature branch ready for review.
What you'll build
A personal portfolio site with four pages:
Home — Hero section with name/tagline, recent projects grid, and a call to action
About — Bio paragraph, skills grid, timeline, and social links
Projects — Filterable project cards with tags, links, and screenshots
Contact — Accessible contact form with client and server-side validation
Tech stack chosen by you at init time (Next.js, Astro, or similar). Fully responsive,
dark-mode support, WCAG 2.2 AA accessible, and SEO-optimised out of the box.
Prerequisites
Node.js 18 or later
An AI coding IDE — VS Code with GitHub Copilot, Cursor, or Claude Code
An OpenCastle-supported AI model API key (Anthropic, OpenAI, or GitHub Models)
A fresh project directory (empty folder is fine)
1
Step 1: Initialize your project
Create a new directory, then run the OpenCastle initializer. It detects your IDE,
installs the skill library, and writes all configuration files into .github/.
Select your IDE — VS Code + Copilot, Cursor, or Claude Code
Choose tech tools — e.g. next-js, tailwind, vitest
Choose team tools — e.g. github, linear for issue tracking
🏰 OpenCastle v1.x.x
Multi-agent orchestration framework for AI coding assistants
Scanning repository...
Detected:
Frameworks: Next.js
Languages: TypeScript
Installing for VS Code...
Tech: next-js, tailwind, vitest
Team: github
✓ Created 47 files
✓ Updated .gitignore with OpenCastle entries
✓ Populated 3 config files
Tip: OpenCastle scans your repo to auto-detect existing tools
(package.json, tsconfig.json, .eslintrc, etc.) and pre-selects matching plugins.
You can accept the defaults and customise later.
2
Step 2: Describe your project
Run opencastle start with a plain-English description of what you want
to build. OpenCastle generates a product requirements document, validates it, decomposes
it into an executable convoy spec, and validates that too — all automatically.
Terminal
$ opencastle start --text "Build a personal portfolio website with a home \
page featuring a hero section and recent projects, an about page with bio \
and skills, a projects page with filterable cards, and a contact page with \
a form. Use modern design, dark mode support, responsive layout, and SEO \
optimization."
The start command runs up to seven steps (fix steps are skipped when validation passes):
opencastle start
[1/7] Generating PRD…
✓ PRD written to .opencastle/prds/portfolio.prd.md
[2/7] Validating PRD…
✓ PRD is valid
[4/7] Assessing complexity…
✓ Complexity assessment saved
ℹ Complexity: medium | Strategy: single
Generating task plan…
✓ Task plan generated (12 tasks)
✓ Convoy spec written to .opencastle/convoys/portfolio.convoy.yml
Validating convoy spec…
✓ Spec is valid
Pipeline complete!
PRD: .opencastle/prds/portfolio.prd.md
Convoy spec: .opencastle/convoys/portfolio.convoy.yml
Tip: Add --dry-run to preview the PRD generation prompt
without executing it. Add --skip-validation to speed things up when you
already trust the description.
3
Step 3: Review the generated spec
Open .opencastle/convoys/portfolio.convoy.yml to review the task breakdown.
The spec lists every task with its agent assignment, file scope, and dependencies.
.opencastle/convoys/portfolio.convoy.yml
version: 1
name: portfolio
adapter: claude
concurrency: 3
branch: feat/portfolio
gates:
- npm run lint
- npm run type-check
tasks:
- id: setup-project
agent: developer
description: Scaffold Next.js project with Tailwind CSS and TypeScript
prompt: Set up a Next.js project with Tailwind CSS and TypeScript...
files: ["package.json", "tsconfig.json", "tailwind.config.ts"]
- id: home-page
agent: developer
depends_on: [setup-project]
description: Build home page with hero section and projects grid
prompt: Build the home page with a hero section and recent projects grid...
files: ["app/page.tsx", "components/Hero.tsx", "components/ProjectGrid.tsx"]
- id: about-page
agent: developer
depends_on: [setup-project]
description: Build about page with bio, skills grid, and social links
prompt: Build the about page with a bio paragraph, skills grid...
files: ["app/about/page.tsx", "components/SkillGrid.tsx"]
- id: seo-meta
agent: developer
depends_on: [home-page, about-page]
description: Add SEO meta tags, Open Graph, and sitemap
prompt: Add SEO meta tags, Open Graph tags, and a sitemap...
files: ["app/layout.tsx", "app/sitemap.ts"]
Tip: You can edit the spec manually before running it — add tasks,
adjust files, change agent assignments, or reorder dependencies.
The spec is just a YAML file.
4
Step 4: Preview the execution plan
Run the convoy with --dry-run to see the dependency graph and execution
order without writing any code.
Terminal
$ opencastle run -f .opencastle/convoys/portfolio.convoy.yml --dry-run
Convoy: portfolio · 12 tasks · dry-run mode
Execution plan (topological order):
Phase 1 [parallel] setup-project
Phase 2 [parallel] home-page, about-page, projects-page, contact-page
Phase 3 [parallel] seo-meta, dark-mode, accessibility-audit
Phase 4 [parallel] e2e-smoke, integration-tests
Phase 5 [serial] final-review
Agents required: developer (x3), reviewer (x1)
No code will be written in dry-run mode.
5
Step 5: Execute the convoy
Remove --dry-run to start execution. Each task runs in an isolated
git worktree so agents work safely in parallel without conflicts. Tasks that
pass their gates are merged back automatically; failed tasks go to the dead-letter queue.
Terminal
$ opencastle run -f .opencastle/convoys/portfolio.convoy.yml
Note: If your machine sleeps or the process is interrupted, resume any time
with opencastle run -f portfolio.convoy.yml --resume.
Use --retry-failed to re-run only tasks that failed.
6
Step 6: Monitor progress
While the convoy runs (or after it completes), open the local dashboard
to see task status, agent activity, gate results, and event timelines.
Terminal — new tab
$ opencastle dashboard
The dashboard opens at http://localhost:4300 and shows:
Live task status grid (queued → running → passed / failed)
Per-agent activity log and retry history
Gate results (lint, type-check, tests) per task
Dead-letter queue for tasks that exhausted retries
Tip: The dashboard also starts automatically when you run
opencastle run — it opens in your browser alongside the convoy execution.
7
Step 7: Review and iterate
Checkout the feature branch and review the generated code. Run the dev server
to inspect the result in your browser, then iterate with quick-refinement prompts.
Terminal
$ git checkout feature/portfolio-convoy-cvy_3kx9
$ npm run dev
# Open http://localhost:3000 in your browser
For tweaks, use the quick-refinement prompt template in your IDE
rather than re-running a full convoy:
VS Code Copilot Chat
# Open Copilot Chat (Ctrl+Alt+I) → type /quick-refinement
# Describe the change, for example:
"Polish the hero section animation — fade in from below
rather than appear instantly. Respect prefers-reduced-motion."
When satisfied, run the test suite and open a pull request:
Terminal
$ npm test
$ gh pr create --title "feat: personal portfolio (convoy cvy_3kx9)"
Tips & Troubleshooting
Start command fails at validation
The PRD or convoy spec didn't pass the validation gate. Add --skip-validation
to bypass it while iterating, or rewrite the description to be more specific about
scope and requirements.
A task keeps failing
Check the dead-letter queue: opencastle run --dlq-list. It shows the
error, the agent's last output, and which gate failed. Fix the spec or the gate config,
then retry with --retry-failed.
Need to change scope mid-run
Stop the convoy with Ctrl+C — the state is saved to .opencastle/convoy.db.
Edit the spec YAML — add, remove, or adjust tasks. Then resume: opencastle run --resume.
Already-completed tasks are not re-run.
Want to run overnight
Convoy execution is crash-safe by design. Each task writes its state to
.opencastle/convoy.db before and after execution. If your machine
sleeps or the process is killed, --resume picks up exactly where
it left off.
What's next
Now that you've shipped a portfolio, try these next steps:
More complex projects — Use the same start command to scaffold
an e-commerce store, SaaS dashboard, or API backend. The agent team scales to
any size project.
Explore Prompt Templates — The Prompt Templates
page has ready-to-use templates for brainstorming, feature implementation, PR
review, and skill creation.
Read the Agentic Development guide — The Agentic Development
guide covers best practices for multi-agent orchestration, quality gates,
and how to get the most out of your agent team.
Explore the CLI — The CLI Reference
documents every opencastle command with all flags and examples.
Team Work with Linear
Introduction
This recipe shows how to run OpenCastle in a team context with Linear as the canonical issue tracker. You’ll connect Linear, generate tracked issues from a PRD, partition work across convoy tasks, and run an agentic convoy that produces review-ready feature branches for each task.
Integrating Linear provides traceability and auditability — every generated commit maps to a Linear issue, agents update issue status automatically, and PRs reference the originating issues so work can be triaged and closed in a single workflow. This setup enables parallel development with clear ownership and automatic issue transitions when code lands.
What you'll set up
A Linear → OpenCastle → Agents → PR workflow that keeps issues, tasks and code tightly coupled. The convoy will create branches for tasks, attach Linear issue IDs to commits, and update issue status as work progresses.
Linear — Your Team
Linear board
To Do
PRJ-101 · Create login form
PRJ-102 · Auth API
In Progress
PRJ-103 · Session management
Done
PRJ-100 · Design auth flow
LinearOpenCastleAgentsPR
Connect Linear — grant an API key so OpenCastle can create and update issues.
Generate issues — create an epic and child issues from a PRD or by hand.
Partition code — map issue ownership to file globs so agents don't collide.
Run a convoy — agents produce branches and PR-ready changes that reference Linear issues.
Prerequisites
Node.js 22.5 or later (required for built-in SQLite support)
Git installed and available on your PATH
An AI coding IDE — VS Code with GitHub Copilot, Cursor, or Claude Code
A Linear workspace with at least one project
A LINEAR_API_KEY (Settings → API → Personal API keys)
A shared repository that your team has access to
1
Step 1: Initialize
Initialize OpenCastle in your team repo. From your local clone, run the initializer and select the Linear team plugin when prompted.
Terminal
$ cd your-team-repo
$ npx opencastle init
Interactive prompts will ask you to:
Select IDE — choose VS Code (with Copilot) or another supported editor.
Select Team Tools — pick Linear so OpenCastle can create and update issues.
Accept defaults — OpenCastle writes the skills and agent configs into .github/.
Configuring project...
✓ Populated 3 config files
✓ Created 47 files
✓ Updated .gitignore with OpenCastle entries
Tip: Keep your API keys ready — you'll need LINEAR_API_KEY later. Store keys in .env locally and use CI secrets for pipelines.
2
Step 2: Connect Linear
Provide a Linear API key and verify your OpenCastle setup with the doctor command. Store the key in your .env file so it's available to MCP servers.
Terminal
$ echo 'LINEAR_API_KEY=lin_api_ABC123def456...' >> .env
$ npx opencastle doctor
Tip: Add the key to .env for local development and to your CI provider as a secret for pipeline runs. After updating secrets, restart your terminal or IDE to pick up the change. Verify the key works by testing Linear connectivity from your MCP-enabled IDE.
3
Step 3: Create issues
Create Linear issues from a PRD generated by the start command. The pipeline generates a PRD, validates it, assesses complexity, and produces a convoy spec with tasks you can map to Linear issues.
Terminal
$ npx opencastle start --text "Add user authentication with login, sessions, and role-based access"
The start command runs up to seven steps (fix steps are skipped when validation passes):
opencastle start
[1/7] Generating PRD…
✓ PRD written to .opencastle/prds/user-authentication.prd.md
[2/7] Validating PRD…
✓ PRD is valid
[4/7] Assessing complexity…
✓ Complexity assessment saved
ℹ Complexity: medium | Strategy: single
Generating task plan…
✓ Task plan generated (4 tasks)
✓ Convoy spec written to .opencastle/convoys/user-authentication.convoy.yml
Validating convoy spec…
✓ Spec is valid
Pipeline complete!
PRD: .opencastle/prds/user-authentication.prd.md
Convoy spec: .opencastle/convoys/user-authentication.convoy.yml
Review the generated PRD to confirm it captures the right scope before continuing:
# User Authentication
## Overview
Add authentication with login, server-side sessions, and role-based access control.
## Requirements
- Login form with email/password validation
- Server-side session management with JWT tokens
- Role-based access control: admin, member
- Secure password hashing (bcrypt)
- Session expiry and refresh token rotation
## Scope
- src/server/auth/ — API routes and middleware
- src/ui/auth/ — login form and auth context
- tests/integration/auth/ — integration tests
Once the PRD looks right, create matching Linear issues — either manually in Linear's UI, or via the Linear MCP tools in your IDE. Map each convoy task to a Linear issue ID by adding descriptions in the convoy spec.
Tip: If you prefer full manual control, create the epic and child issues in Linear first, then write the convoy spec by hand referencing those tasks.
4
Step 4: Assign & partition
Edit the generated convoy spec to partition repository ownership so each task runs in an isolated worktree and only modifies allowed paths. Reference Linear issue IDs in task descriptions for traceability.
version: 1
name: auth-flow
branch: feat/user-authentication
concurrency: 3
gates:
- npm run lint
- npm run type-check
tasks:
- id: api-auth
description: "PRJ-210 · Implement authentication API with sessions and JWTs"
agent: developer
prompt: "Implement authentication API with sessions and JWTs..."
files:
- src/server/auth/**
- id: login-form
description: "PRJ-211 · Create login form with client-side validation"
agent: developer
prompt: "Create login form with client-side validation..."
files:
- src/ui/auth/**
depends_on:
- api-auth
- id: session-tests
description: "PRJ-212 · Add integration tests for auth flow"
agent: developer
prompt: "Add integration tests for auth flow..."
files:
- tests/integration/auth/**
Tip: Use depends_on for tasks that require artifacts from prior tasks — this enforces ordering and reduces merge conflicts.
5
Step 5: Execute convoy
Start the convoy — agents will run tasks in parallel where possible, each in an isolated git worktree. Tasks that pass their gates are merged back automatically; failed tasks go to the dead-letter queue.
Terminal
$ npx opencastle run -f .opencastle/convoys/user-authentication.convoy.yml
Tip: Use --retry-failed to selectively re-run failed tasks and --resume after interruptions. Each task persists state so resumes pick up where they left off.
6
Step 6: Review together
Open the dashboard to review task logs, diffs and per-task gate results. Confirm each task’s branch and the associated Linear issue before opening a consolidated PR.
Tip: Visit the local dashboard at http://localhost:4321 to see per-agent logs, gate failures, and the dead-letter queue. Use the dashboard to add reviewers and assign manual checks before merging.
7
Step 7: Ship the PR
Push the feature branch and open a pull request. Include all related Linear issue IDs in the PR body — Linear will use those references to auto-close issues when the PR merges.
Tip: Use the exact Linear IDs in the PR body (e.g. PRJ-210). When the PR merges, Linear will detect the references and transition issues to Done automatically if your workspace rules allow it.
Tips & Troubleshooting
LINEAR_API_KEY not found
Make sure you exported the full key (starts with lin_api_) into your shell or .env. After saving the file, restart your terminal or IDE so environment variables are reloaded, then re-run npx opencastle doctor to confirm connectivity.
Doctor reports missing MCP environment variables
Check that your .env file contains the LINEAR_API_KEY and any other MCP-required keys. Use the Linear web UI to verify the key permissions; if needed, create a new personal API key and update your .env.
Task descriptions don't match Linear issues
Open your convoy spec and confirm the description fields reference the correct Linear issue IDs. If an issue was renamed or moved, update the task description and re-run the convoy.
Merge conflicts between tasks
Ensure each task has exclusive file globs under files in the convoy spec. If a conflict occurs, resolve it in a short-lived integration branch and update the convoy spec to avoid future overlap.
What's next
Automated reviews — Integrate CI checks and require the dashboard’s gates before merge; see the Agentic Development guide.
Advanced tracing — Enable richer telemetry and per-task annotations so commits include reviewer notes and trace IDs.
Custom trackers — Swap or augment Linear with Jira or GitHub Issues by enabling another tracker plugin in .github/skills/.
Policy-driven merges — Create branch protection rules that require convoy gates and manual approvals before PR merge.
Build a REST API Backend
Introduction
This recipe covers building a production-ready Node.js REST API with CRUD endpoints for users, projects, and tasks, JWT authentication middleware, input validation with Zod, and automated test coverage. It walks through initializing the workspace, authoring a PRD, running OpenCastle's pipeline to generate routes, models, middleware, and tests, and verifying the result locally.
Using OpenCastle streamlines repetitive boilerplate — the convoy spawns parallel agents to generate server scaffolding, route handlers, validation, auth, and tests, while enforcing quality gates and review steps so you get a working API faster with consistent standards.
What you'll build
A task management REST API served at /api/v1 with endpoints for users, projects, and tasks, role-based access control, and full test coverage. The mockup below represents a sample JSON response from the generated API.
Auth — JWT authentication and role-based access control
Validation — Zod schemas for request bodies and params
Data — lightweight SQLite models (Node 22+), migrations, and seeds
Tests — unit and integration tests with CI-friendly tooling
Docs — generated endpoint docs and example responses
Prerequisites
Node.js 22.5 or later (required for built-in SQLite support)
Git installed and available on your PATH
An AI coding IDE — VS Code with GitHub Copilot, Cursor, or Claude Code
An OpenCastle-supported AI model API key
1
Step 1: Initialize
Create a new directory, initialize git and npm, then run the OpenCastle initializer. During the interactive prompts, select your IDE and choose tech tools that match your server stack (e.g., express or fastify, vitest).
Configuring project...
✓ Populated 3 config files
✓ Created 47 files
✓ Updated .gitignore with OpenCastle entries
Tip: Choose Express for widest community support or Fastify for performance and built-in schema validation support.
2
Step 2: Describe the API
Run opencastle start with a description of the API. The start command generates a PRD, validates it, assesses complexity, and produces a convoy spec — all automatically.
Terminal
$ npx opencastle start --text "Build a REST API for a task management app \
with users, projects, and tasks. Include JWT authentication, role-based \
access control, input validation with Zod, and comprehensive test coverage."
opencastle start
[1/7] Generating PRD…
✓ PRD written to .opencastle/prds/rest-api-task-management.prd.md
[2/7] Validating PRD…
✓ PRD is valid
[4/7] Assessing complexity…
✓ Complexity assessment saved
ℹ Complexity: high | Strategy: single
Generating task plan…
✓ Task plan generated (8 tasks)
✓ Convoy spec written to .opencastle/convoys/rest-api-task-management.convoy.yml
Validating convoy spec…
✓ Spec is valid
Pipeline complete!
PRD: .opencastle/prds/rest-api-task-management.prd.md
Convoy spec: .opencastle/convoys/rest-api-task-management.convoy.yml
Tip: Keep the prompt focused and include explicit constraints (e.g., "use Zod", "JWT", "SQLite") so generated code matches your stack.
3
Step 3: Review the PRD
OpenCastle writes a machine-readable PRD in .opencastle/prds/. Review and tweak endpoints, auth rules, and validation before running the convoy.
File
# .opencastle/prds/rest-api-task-management.prd.md
## Endpoints
| Method | Path | Auth | Description |
| GET | /api/v1/users | admin, user | list users
| POST | /api/v1/users | admin | create user
| GET | /api/v1/users/:id | admin, user | get user
| PUT | /api/v1/users/:id | admin | update user
| DELETE | /api/v1/users/:id | admin | delete user
| GET | /api/v1/projects | admin, user | list projects
| POST | /api/v1/projects | admin | create project
| GET | /api/v1/projects/:id | admin, user | get project
| PUT | /api/v1/projects/:id | admin | update project
| DELETE | /api/v1/projects/:id | admin | delete project
| GET | /api/v1/tasks | admin, user | list tasks
| POST | /api/v1/tasks | admin, user | create task
| GET | /api/v1/tasks/:id | admin, user | get task
| PUT | /api/v1/tasks/:id | admin, user | update task
| DELETE | /api/v1/tasks/:id | admin, user | delete task
## Auth
- JWT in `Authorization: Bearer <token>`
- Roles: admin, user
- Role checks applied per-route
## Validation
- Users: `email` (email), `password` (min 8)
- Projects: `name` (string, required)
- Tasks: `title` (string, required), `status` (enum: open|in_progress|done), `assigneeId` (uuid)
Tip: Edit the PRD to reflect custom policies — the convoy will regenerate affected artifacts when you re-run the pipeline.
4
Step 4: Preview the plan
Preview the convoy execution plan with --dry-run on the run command. This shows the dependency graph and execution order without writing any code.
Terminal
$ npx opencastle run -f .opencastle/convoys/rest-api-task-management.convoy.yml --dry-run
Convoy: rest-api-task-management · 8 tasks · dry-run mode
Execution plan (topological order):
Phase 1 [parallel] setup-project
Phase 2 [parallel] user-model, project-model, task-model
Phase 3 [parallel] routes, auth-middleware
Phase 4 [parallel] integration-tests
Phase 5 [serial] final-review
No code will be written in dry-run mode.
Tip: Use the dry-run to confirm the decomposition and catch unwanted changes before executing.
5
Step 5: Execute
Run the convoy to execute the plan. Each task runs in an isolated git worktree so agents work in parallel without conflicts. Tasks that pass their gates are merged back automatically; failed tasks go to the dead-letter queue.
Terminal
$ npx opencastle run -f .opencastle/convoys/rest-api-task-management.convoy.yml
Phase 1: setup-project
▶ [setup-project] Scaffold Express project with TypeScript
✓ [setup-project] completed (2m 14s)
Phase 2: user-model, project-model, task-model
▶ [user-model] Create user model and migration
▶ [project-model] Create project model and migration
▶ [task-model] Create task model and migration
✓ [user-model] completed (1m 45s)
✓ [project-model] completed (1m 38s)
✓ [task-model] completed (1m 52s)
Phase 3: routes, auth-middleware
▶ [routes] Generate CRUD route handlers
▶ [auth-middleware] Add JWT auth and RBAC middleware
✓ [routes] completed (3m 02s)
✓ [auth-middleware] completed (2m 05s)
✓ Convoy complete · 8/8 tasks passed · total 12m 36s
Dashboard: http://localhost:4300
Tip: If an agent fails, the convoy will retry automatically. To resume after an interruption, use npx opencastle run --resume. Use --retry-failed to re-run only tasks that failed.
6
Step 6: Test the API
Run the generated test suite and exercise a sample endpoint locally.
Tip: Use the OpenCastle dashboard to inspect generated PRs and agent diffs if you want to review changes before merging.
7
Step 7: Review & iterate
Checkout the feature branch created by the convoy, review the generated code, and use your IDE chat to request tweaks. Then push the branch and open a PR.
Terminal
$ git checkout feat/rest-api-task-management
$ npm test
$ git push -u origin feat/rest-api-task-management
$ gh pr create --title "feat: REST API for task management" --body "Generated by OpenCastle convoy"
Tip: Use iterative PR feedback from reviewers to refine the PRD and re-run opencastle start rather than full regenerations. For quick tweaks, use the /quick-refinement prompt template in your IDE.
Tips & Troubleshooting
Port 3000 already in use
Change the PORT environment variable before starting the server: PORT=4000 npm start.
Authentication middleware not applied
Check route ordering in the convoy spec and ensure auth middleware is mounted before protected routes in routes/index.ts.
Tests failing on CI
Ensure CI provides required env vars (JWT secret, DB URL) and run migrations in the CI job before tests.
Want to add more endpoints later
Run npx opencastle start --text "..." with a description of the new endpoints. This generates a new PRD and convoy spec for the additions. For quick changes, use the /quick-refinement prompt template in your IDE chat.
Team Work — recipe for multi-agent collaboration on larger features
Existing Project — how to onboard OpenCastle into a repo with existing code
Add OpenCastle to an Existing Project
Introduction
This recipe shows how to add OpenCastle to a repository that already contains code, tests, CI, and established conventions. OpenCastle is non-destructive — it adds configuration and support files without modifying your existing source. The opencastle init command auto-detects your tech stack during setup and pre-selects matching plugins.
What you'll set up
A fully configured OpenCastle workspace layered on top of your existing project, with auto-detected plugins and a first feature built through the convoy. The mockup below represents the init flow scanning an existing repo.
~/projects/my-app
$ npx opencastle init
🏰 OpenCastle v0.x.x
Multi-agent orchestration framework for AI coding assistants
Scanning repository...
Detected:
Frameworks: Next.js
Languages: TypeScript
Installing for VS Code...
Tech: next-js, tailwind, vitest
Configuring project...
✓ Populated 3 config files
✓ Created 47 files
✓ Updated .gitignore with OpenCastle entries
Init ·Review ·Start ·Doctor
Initialize — auto-detect the stack and add OpenCastle config without touching code
Review plugins — verify auto-detected plugins in the manifest
PRD — create a first PRD for a new feature in the existing codebase
Execute — run convoy gated on existing tests and lint
Verify — review, iterate, and merge through your normal workflow
Prerequisites
An existing project with git history and at least one commit
Node.js 22.5 or later
An AI coding IDE — VS Code with GitHub Copilot, Cursor, or Claude Code
An OpenCastle-supported AI model API key
1
Step 1: Initialize OpenCastle
Run opencastle init from the project root. The initializer scans your repo (package.json, tsconfig.json, config files) to auto-detect frameworks, test runners, linters, and databases, then pre-selects matching plugins in the interactive prompts.
Terminal
$ npx opencastle init
🏰 OpenCastle v0.x.x
Multi-agent orchestration framework for AI coding assistants
Scanning repository...
Detected:
Frameworks: Next.js
Languages: TypeScript
Installing for VS Code...
Tech: next-js, tailwind, vitest
Configuring project...
✓ Populated 3 config files
✓ Created 47 files
✓ Updated .gitignore with OpenCastle entries
Tip: OpenCastle reads package.json, tsconfig, and common config files to identify frameworks, linters, test runners, and databases — detected tools are pre-selected in the interactive prompts.
2
Step 2: Review detected plugins
OpenCastle stores your detected stack in .opencastle/manifest.json. Review the stack section to confirm the detected tools are correct. You can re-run npx opencastle init to change selections.
Tip: To change plugins, re-run npx opencastle init — existing files are skipped, and you can adjust tool selections in the interactive prompts. OpenCastle never overwrites existing source files.
3
Step 3: Verify setup with doctor
Run opencastle doctor to verify the workspace is correctly configured. Doctor checks the manifest, customizations, skill matrix, logs, MCP configuration, and IDE-specific rules.
Tip: Doctor checks for common configuration issues. Fix any failing checks before running convoys.
4
Step 4: Generate a PRD for a new feature
Write a PRD describing a small, scoped feature. You can either create it manually or use the start command to generate one from a description. Reference existing code paths so agents understand context.
Terminal
$ npx opencastle start --text "Add user notifications with a server-side API \
at /api/notifications and a UI inbox component. Include a database migration \
for a notifications table and unit tests for both API and UI."
opencastle start
[1/7] Generating PRD…
✓ PRD written to .opencastle/prds/user-notifications.prd.md
[2/7] Validating PRD…
✓ PRD is valid
[4/7] Assessing complexity…
✓ Complexity assessment saved
ℹ Complexity: medium | Strategy: single
Generating task plan…
✓ Task plan generated (5 tasks)
✓ Convoy spec written to .opencastle/convoys/user-notifications.convoy.yml
Validating convoy spec…
✓ Spec is valid
Pipeline complete!
PRD: .opencastle/prds/user-notifications.prd.md
Convoy spec: .opencastle/convoys/user-notifications.convoy.yml
Tip: Reference existing code paths (files and folders) so agents can locate relevant code quickly.
5
Step 5: Review the PRD and run
Review the generated PRD to confirm it captures the right scope. Tweak requirements, file paths, or constraints before running the convoy.
# User Notifications
## Overview
Server-side notification API with a database migration and a UI inbox component.
## Requirements
- Notifications table with id, user_id, title, body, read, created_at
- REST API at /api/notifications (list, mark-read, delete)
- Real-time inbox component with unread badge
- Unit tests for API handlers and inbox component
## Scope
- src/server/notifications/ — API routes
- src/components/NotificationInbox/ — UI component
- db/migrations/ — notifications table migration
- tests/ — unit and integration tests
Once the PRD looks right, preview the execution plan and run:
Terminal
$ npx opencastle run -f .opencastle/convoys/user-notifications.convoy.yml --dry-run
$ npx opencastle run -f .opencastle/convoys/user-notifications.convoy.yml
Tip: Add lint, type-check, and test commands to the gates section of your convoy spec to catch regressions automatically. For example: gates: ["npm run lint", "npm run type-check", "npm test"]
6
Step 6: Verify compatibility
Run your existing test suite and linter to confirm nothing broke. Checkout the feature branch created by the convoy and inspect the changes.
Terminal
$ git checkout feat/user-notifications
$ npm test
$ npm run lint
$ npx opencastle doctor
✓ vitest · 24 tests passed · 1.8s
✓ eslint · no problems found
🏰 OpenCastle Doctor
Checking your setup...
✓ Manifest
✓ Customizations directory
✓ Skill matrix
✓ Observability logs
✓ MCP environment variables
✓ .env file
Tip: Doctor checks your overall setup health. Run your project’s own test suite and linter separately to catch code-level regressions.
7
Step 7: Iterate & expand
Commit OpenCastle config and the generated feature branch, then push and open a PR. Use OpenCastle progressively for additional features — start small and increase scope as confidence grows.
Terminal
$ git push -u origin feat/user-notifications
$ gh pr create --title "feat: user notifications" --body "Generated by OpenCastle convoy"
For the OpenCastle configuration itself, create a separate PR:
Tip: Start with small, well-scoped features to build confidence before tackling larger refactors.
Tips & Troubleshooting
Init missed a framework
Re-run npx opencastle init — the interactive prompts let you adjust tool selections. Detected tools are pre-selected but you can add or remove any.
init reports file conflicts
OpenCastle skips conflicting files — review the skip report and manually merge changes where needed.
Existing tests fail after convoy
Add lint, type-check, and test commands to the gates section of your convoy spec so they run after every task. Inspect failing diffs and revert with git if required.
Want to use OpenCastle alongside existing CI
OpenCastle outputs standard git branches and PRs — your existing CI will run as usual on the generated branches.
