OpenCastle

Docs / Prompt Templates

Prompt templates are .prompt.md files that can be invoked directly in VS Code Copilot Chat or any compatible IDE. Each template is pre-wired to the Team Lead agent with the full OpenCastle skill set. 

# How to use a prompt template in VS Code
# 1. Open Copilot Chat  (⌃⌘I / Ctrl+Alt+I)
# 2. Type / to open the prompt picker
# 3. Select the prompt by name
# 4. Fill in the required variables
# 5. Press Enter — the Team Lead takes it from there

# Prompts live in: .github/prompts/
# All prompts target the Team Lead agent (OpenCastle mode)

Planning

Brainstorm

Collaborative brainstorm to explore requirements, approaches, and trade-offs BEFORE committing to a plan. Use when the task has ambiguity, multiple valid approaches, or significant design decisions.

Team Lead (OpenCastle) · Variables: {{request}}

When to use

When a task has ambiguity, multiple valid approaches, or design decisions to make before implementation. Use this before reaching for an implementation prompt.

What it does

Runs a structured brainstorm — clarifies the problem, explores the solution space, generates alternatives, evaluates trade-offs, and defines scope before any code is written.

.github/prompts/brainstorm.prompt.md

Generate Convoy

Generate a .convoy.yml spec file for autonomous convoy execution based on a high-level goal.

Team Lead (OpenCastle) · Variables: {{goal}}, {{context}}

When to use

When you want to run opencastle run for autonomous convoy execution (e.g., overnight or unattended). Generates a YAML convoy spec from a high-level goal.

What it does

Analyzes the goal, decomposes into self-contained tasks with dependency ordering, assigns appropriate agents, and produces a valid .convoy.yml file. The convoy engine handles isolated git worktrees, parallel execution, crash recovery, and merge ordering automatically.

.github/prompts/generate-convoy.prompt.md

Implementation

Implement Feature

Instruct the Team Lead to implement a specific task from your roadmap with full orchestration, validation, and traceability.

Team Lead (OpenCastle) · Variables: {{roadmapTask}}

When to use

When implementing a tracked roadmap task. Provides full orchestration with issue tracking, validation gates, and multi-agent delegation.

What it does

  1. Research & context gathering — reads relevant files, loads skills, and understands scope
  2. Task board setup — creates or locates the tracker issue
  3. Execution strategy — chooses direct delegation (1-2 tasks) or convoy engine (3+ tasks)
  4. Implementation — delegates to agents or generates a convoy spec for autonomous execution
  5. Validation & testing — runs lint, tests, and browser checks
  6. Delivery via PR — opens a pull request linked to the tracker issue
.github/prompts/implement-feature.prompt.md

Bug Fix

Investigate and fix a reported bug with proper triage, root cause analysis, issue tracking, and verification.

Team Lead (OpenCastle) · Variables: {{bugDescription}}

When to use

When a bug is reported. Provides structured triage, root cause analysis, and fix verification — rather than jumping straight to editing code.

What it does

  1. Triage & reproduce — confirms the bug, gathers context
  2. Create tracker issue — opens a bug ticket with reproduction steps
  3. Root cause analysis — traces the defect to its origin
  4. Delegate fix — sends a targeted fix to the appropriate specialist agent
  5. Validate — verifies with tests and browser checks before delivering the PR
.github/prompts/bug-fix.prompt.md

Quick Refinement

Handle follow-up refinements after a roadmap task — bug fixes, UI tweaks, polish, and adjustments that are too small for issue tracking.

Team Lead (OpenCastle) · Variables: {{followUpRequest}}

When to use

For post-task adjustments like UI tweaks, polish, or minor bug fixes that are too small for full issue tracking. Ideal for iterating after an implement-feature run.

What it does

Triages the request to determine the appropriate tracking level, then delegates focused fixes via sub-agents with the same code quality and verification standards as full feature work.

.github/prompts/quick-refinement.prompt.md

Collaboration

Resolve PR Comments

Resolve GitHub PR review comments by reading them, grouping by file, and applying fixes systematically.

Team Lead (OpenCastle) · Variables: {{prReference}}

When to use

When a pull request has review comments that need to be addressed. Reads, groups, and resolves comments systematically rather than ad-hoc.

What it does

  1. Gather PR comments — reads all review comments from GitHub
  2. Group by file — organises comments into file-level batches
  3. Classify — marks each as must-fix, should-fix, or discussion
  4. Delegate fixes — sends batches to appropriate specialist agents
  5. Verify and push — confirms lint/tests pass, then pushes to the branch
.github/prompts/resolve-pr-comments.prompt.md

Setup

Bootstrap Customizations

Bootstrap the .github/customizations/ directory for a new project. Discovers project structure, tech stack, and configuration, then generates all customization files so skills have project-specific context to operate on.

Team Lead (OpenCastle) · Variables: {{context}}

When to use

After running opencastle init, to set up project-specific customization files that give agents concrete context about your codebase. Run this once per project.

What it does

Discovers project structure, tech stack, and config — then generates customization files for project context, stack config, tracker config, and more so every skill has accurate project-specific data to work from.

.github/prompts/bootstrap-customizations.prompt.md

Create Skill

Scaffold a new skill file with proper frontmatter, structure, and registration. Use when adding a new domain skill to the AI configuration.

Team Lead (OpenCastle) · Variables: {{skillDescription}}

When to use

When adding a new domain-specific skill to the AI configuration — either as a process skill (workflow pattern) or a plugin skill (third-party integration).

What it does

Classifies the skill type, names it, creates the SKILL.md file with proper structure, and registers it in the skill matrix so agents can discover and load it automatically.

.github/prompts/create-skill.prompt.md