project-docs

Initialize a new feature/fix/refactor/chore branch from develop

Discover and articulate project purpose, vision, and boundaries

Extract project structure and patterns as a reusable recipe

Generate comprehensive project summary and current state

Start development work from a DEV_KICKOFF.md file. Use when opening a fresh session to begin or resume implementation — finds DEV_KICKOFF.md, reads the mission, and follows the workflow defined in the document.

Automate dependency updates with testing and validation

Use this agent when you need to create a detailed technical development plan from a proposal, feature request, or implementation instructions. This includes transforming high-level requirements into actionable development guidance, breaking down complex features into implementable phases, or creating structured plans that developers can follow for implementation. <example> Context: User has a proposal document and needs a development plan created from it. user: "I have a proposal for adding real-time notifications to our app. Can you create a dev plan for it?" assistant: "I'll use the dev-plan-generator agent to create a comprehensive development plan from your proposal." <uses Task tool to launch dev-plan-generator agent> </example> <example> Context: User describes a feature they want implemented and needs a plan. user: "We need to implement OAuth2 authentication with support for Google and GitHub providers. Please create a development plan for this." assistant: "Let me use the dev-plan-generator agent to create a detailed technical development plan for the OAuth2 implementation." <uses Task tool to launch dev-plan-generator agent> </example> <example> Context: User has completed a proposal review and needs to move to planning phase. user: "The team approved the API versioning proposal in docs/projects/api-versioning/proposal.md. Now I need a dev plan." assistant: "I'll launch the dev-plan-generator agent to transform this approved proposal into an actionable development plan." <uses Task tool to launch dev-plan-generator agent> </example>

Use this agent to review a single document for accuracy, implementation status, and whether it needs updates or archival. Assign ONE document per agent for thorough review. The agent validates documentation against the codebase and recommends appropriate actions based on document type. Examples: <example> Context: User wants to check if a specific proposal has been implemented. user: "Can you review docs/projects/user-defined-ai-operations/proposal.md?" assistant: "I'll launch the docs-curator agent to review this proposal against the codebase." <Task tool call to launch docs-curator agent with the document path> </example> <example> Context: User completed work and wants to verify a plan is done. user: "Check if the PowerSync migration plan is complete" assistant: "I'll use the docs-curator agent to verify the plan's implementation status." <Task tool call to launch docs-curator agent> </example> <example> Context: User wants to validate architecture documentation. user: "Is the MCP server architecture doc still accurate?" assistant: "I'll launch the docs-curator agent to validate this architecture doc against current code." <Task tool call to launch docs-curator agent> </example> <example> Context: User wants batch review of multiple documents. user: "Review all the proposals in docs/projects/" assistant: "I'll launch multiple docs-curator agents in parallel, one per project proposal, for thorough review." <Multiple Task tool calls, one per document> </example>

Use this agent when you need quick, focused development tasks completed efficiently. Ideal for small code changes, fixing individual functions, updating configuration files, renaming variables, adding simple features, or making targeted modifications. Not intended for architectural decisions, complex refactoring, or tasks requiring deep analysis.\n\nExamples:\n\n<example>\nContext: User needs a small function fixed.\nuser: "The formatDate function in utils.ts is returning the wrong format, it should be YYYY-MM-DD not MM-DD-YYYY"\nassistant: "I'll use the gopher-dev agent to quickly fix that date format issue."\n<Task tool launches gopher-dev agent>\n</example>\n\n<example>\nContext: User needs a quick file modification.\nuser: "Add a loading spinner to the submit button in LoginForm.vue"\nassistant: "Let me dispatch the gopher-dev agent to add that loading state to the button."\n<Task tool launches gopher-dev agent>\n</example>\n\n<example>\nContext: User needs a simple configuration change.\nuser: "Update the timeout value in the API client from 5000 to 10000ms"\nassistant: "I'll have the gopher-dev agent make that quick config update."\n<Task tool launches gopher-dev agent>\n</example>\n\n<example>\nContext: User needs a small feature addition.\nuser: "Add a console.log at the start of the handleSubmit function to debug the form data"\nassistant: "Perfect task for the gopher-dev agent - let me dispatch it to add that debug log."\n<Task tool launches gopher-dev agent>\n</example>

Use this agent when you need to conduct structured technical research, evaluate options, debug complex problems, or reduce uncertainty. This includes technology evaluation, library/framework comparisons, migration feasibility, root cause analysis, architecture research, system archaeology, performance debugging, security analysis, or any situation requiring systematic evidence gathering and documented findings. Examples: <example> Context: The user wants to evaluate technology options. user: "What state management library should we use for our new React project?" assistant: "I'll use the investigator agent to evaluate state management options and recommend the best fit for your project." <Task tool call to investigator> </example> <example> Context: The user needs to debug a complex issue. user: "Our API response times have increased from 200ms to 2 seconds over the past week. Can you investigate?" assistant: "I'll launch the investigator agent to systematically investigate this performance regression." <Task tool call to investigator> </example> <example> Context: The user wants to understand migration implications. user: "We're considering moving from MongoDB to PostgreSQL. Can you investigate what that would involve?" assistant: "I'll use the investigator agent to analyze the migration path, effort, and risks." <Task tool call to investigator> </example> <example> Context: The user needs to understand an unfamiliar system. user: "I need to understand how our authentication system works - can you research it?" assistant: "I'll launch the investigator agent to conduct a thorough analysis of the authentication system." <Task tool call to investigator> </example> <example> Context: Proactive use - uncertainty identified during development. user: "Let's add real-time notifications to the app." assistant: "Before implementing, there are several approaches (WebSockets, SSE, polling) with different tradeoffs. Let me use the investigator agent to evaluate the options." <Task tool call to investigator> </example>

Use this agent when the user needs to create a formal proposal document from investigation findings, research notes, or other input materials. This agent should be triggered when translating discovered information into actionable, structured proposals. Examples: <example> Context: User has completed an investigation and wants to formalize findings into a proposal. user: "I've finished investigating the authentication refactor. Can you help me create a proposal for it?" assistant: "I'll use the proposal-writer agent to create a formal proposal from your investigation findings." <commentary> Since the user has completed an investigation and wants to create a proposal, use the Task tool to launch the proposal-writer agent to read the investigation document and generate a properly structured proposal. </commentary> </example> <example> Context: User provides raw information and wants it turned into a proposal. user: "I have some notes about implementing a caching layer. Here's what I'm thinking: [details]. Can you write this up as a proposal?" assistant: "I'll use the proposal-writer agent to transform your notes into a formal proposal document." <commentary> Since the user wants to convert informal notes into a formal proposal, use the proposal-writer agent to structure the information according to the proposal template and create the documentation. </commentary> </example> <example> Context: User references an existing investigation file. user: "Please create a proposal based on the investigation in docs/investigations/database-migration.md" assistant: "I'll use the proposal-writer agent to read the investigation and generate a project folder with a proposal." <commentary> Since the user is asking to create a proposal from an existing investigation document, use the proposal-writer agent to analyze the investigation, create a project folder, and produce a well-structured proposal. </commentary> </example>

Use this agent when the user asks to create a slide deck, generate slides from project documents, or needs a visual summary of dense documentation for human review. Also use proactively when a proposal, investigation, or dev plan is ready for review and a slide deck would help orient the reviewer before reading the full document. Examples: <example> Context: User has a completed investigation and wants to review it visually. user: "Can you create a slide deck from the markdown-slide-deck-tooling investigation?" assistant: "I'll use the slide-deck-author agent to generate an executive slide deck from that investigation." <commentary> User wants to convert documentation into a reviewable slide deck — the slide-deck-author agent handles the end-to-end synthesis. </commentary> </example> <example> Context: User wants to present a proposal for review before development begins. user: "Generate slides from the oauth-upgrade proposal so I can review it before we plan." assistant: "I'll launch the slide-deck-author agent to distill that proposal into a slide deck." <commentary> Proposal review is a primary use case — agent reads the source, synthesizes key decisions and risks, and produces oriented slides. </commentary> </example> <example> Context: Agent has just completed writing a dev plan and wants to prepare it for human review. assistant: "The plan is written. Let me use the slide-deck-author agent to generate a slide deck so you can review the key decisions before implementation begins." <commentary> Proactive use — agent surfaces a slide deck to help reviewer navigate dense documentation without reading the full plan. </commentary> </example>

Use this agent when you need to create a structured test plan from a development plan. This includes generating tiered verification scenarios (smoke, critical path, edge cases) for agent-implemented features, creating test plans that bridge implementation and verification, or defining what to test and at what priority before implementation begins. <example> Context: User has a development plan and wants a test plan created from it. user: "I have a development plan for the new document editor. Can you create a test plan?" assistant: "I'll use the test-plan-generator agent to create a tiered test plan from your development plan." <uses Task tool to launch test-plan-generator agent> </example> <example> Context: User wants verification scenarios before implementation starts. user: "Before we start implementing the sync feature, I want a test plan that defines what we need to verify." assistant: "I'll launch the test-plan-generator agent to create verification scenarios from the plan and proposal." <uses Task tool to launch test-plan-generator agent> </example> <example> Context: User is setting up parallel worktree development and wants test coverage defined. user: "We're about to spin up worktrees for the auth feature. Can you generate a test plan so the implementing agent knows what to verify?" assistant: "I'll use the test-plan-generator agent to define the verification scenarios for the auth implementation." <uses Task tool to launch test-plan-generator agent> </example>

Use this agent when you need to write, update, or improve unit tests for any part of the Operator monorepo. This includes tests for the desktop app (Electron + Vue 3 + Vitest), mobile app (Expo + React Native + Jest), API (Bun + Elysia), or shared packages. The agent understands the different testing frameworks, patterns, and conventions used across each ecosystem.\n\nExamples:\n\n<example>\nContext: User has just implemented a new Vue composable in the desktop app.\nuser: "I just created a new useDocumentSync composable in the desktop renderer"\nassistant: "I can see you've created the useDocumentSync composable. Let me use the unit-test-writer agent to create comprehensive tests for it."\n<Task tool invocation to launch unit-test-writer agent>\n</example>\n\n<example>\nContext: User has added a new service to the mobile app.\nuser: "Can you write tests for the new DocumentService I created in apps/mobile/src/services/document.service.ts?"\nassistant: "I'll use the unit-test-writer agent to create Jest tests for your DocumentService that follow the mobile app's service layer testing patterns."\n<Task tool invocation to launch unit-test-writer agent>\n</example>\n\n<example>\nContext: User has implemented a new API endpoint.\nuser: "I need unit tests for the new /documents endpoint in the API"\nassistant: "I'll launch the unit-test-writer agent to create Bun tests for your documents endpoint following the Elysia handler testing conventions."\n<Task tool invocation to launch unit-test-writer agent>\n</example>\n\n<example>\nContext: User has just finished implementing a feature and wants test coverage.\nuser: "I just finished the version history feature, can you add tests?"\nassistant: "I'll use the unit-test-writer agent to analyze your implementation and create appropriate unit tests across any affected packages."\n<Task tool invocation to launch unit-test-writer agent>\n</example>

Rapid online research specialist for discovering how technologies integrate, finding current documentation, and identifying best practices. Use this agent when you need to quickly understand integration patterns, configuration requirements, authentication flows, or migration strategies for modern tools and frameworks. Examples: <example> Context: User needs to understand how two technologies work together. user: "How does PowerSync integrate with BetterAuth? What do we need for authentication?" assistant: "I'll use the web-researcher agent to find official documentation and integration patterns for PowerSync and BetterAuth." <Task tool invocation to launch web-researcher agent> </example> <example> Context: User is setting up infrastructure and needs configuration guidance. user: "What's the recommended Docker Compose setup for PowerSync with Postgres and MongoDB?" assistant: "Let me launch the web-researcher agent to find current best practices for PowerSync infrastructure setup." <Task tool invocation to launch web-researcher agent> </example> <example> Context: User needs to understand migration patterns. user: "We're migrating from Turso to PowerSync. What do we need to know about the differences?" assistant: "I'll use the web-researcher agent to research migration patterns and identify key differences between Turso and PowerSync." <Task tool invocation to launch web-researcher agent> </example> <example> Context: User needs to validate multiple approaches by running parallel research. user: "Research PowerSync Sync Rules, authentication setup, and Docker deployment - run three researchers in parallel" assistant: "I'll spawn three web-researcher agents in parallel to cover these different aspects of PowerSync setup." <Task tool invocations to launch multiple web-researcher agents> </example>

Review backlog items and organize them into project groupings with parallelism analysis. This skill should be used when the user asks to "organize the backlog", "group backlog items into projects", "review backlog for project planning", "what projects should we create from the backlog", "prioritize backlog items", or when the backlog has accumulated enough items that grouping and project creation would be valuable.

Create a structured investigation document from a rough idea, voice note, or freeform thoughts. Use when the user has an unstructured question or concern they want to explore — transforms conversational input into a formal investigation in docs/investigations/. Triggers when user says "investigate this", "I've been thinking about", "should we look into", "start an investigation", or provides rough voice-to-text or bullet-point input that needs structuring.

Create a new project folder with proposal scaffold in docs/projects/. Use when work needs a project home — whether starting from an investigation, writing a new proposal, or beginning any feature that warrants structured tracking. This is a prerequisite for generate-dev-plan, generate-design- resolution, and generate-test-plan. Triggers when user says "let's create a project", "start a proposal", "we should work on this", "let's build this", or when transitioning from an investigation to actionable work. Also use when generate-proposal needs a project folder to write into.

Pre-planning technical discovery for complex features. Orchestrates explorers to gather codebase context, validates architecture docs, and prepares comprehensive input for the dev-plan-generator. Use when the user has a proposal or feature idea that needs codebase analysis before planning — maps existing patterns, validates assumptions, and surfaces constraints. Triggers when user says "explore the codebase for this feature", "do technical discovery", "what does the codebase look like for this", "analyze the code before we plan", or wants pre-planning research documented as a discovery artifact.

Orchestrate the full proposal-to-implementation process, either via a git worktree (isolated branch) or directly in the main repo. Use when the user has a finalized proposal and is ready to begin development — creates a branch or worktree, writes a DEV_KICKOFF.md handoff document, optionally runs dev-discovery and generates the development plan. Triggers when user says "kick off dev", "start implementation", "ready to implement", "let's build this", or references a proposal that needs implementation. Replaces parallel-worktree-dev.

Methodology for validating documentation against codebases. Covers document type lifecycles, review steps, evidence gathering, and structured output. Use when reviewing whether documentation (proposals, plans, architecture docs) accurately reflects what the code actually does. Triggers when user says "validate this doc", "is this documentation accurate", "check docs against the code", "audit documentation", or wants to verify that written documentation hasn't drifted from the implementation.

Methodology for evaluating options, comparing technologies, and making evidence-based decisions between alternatives. Use when the user needs to choose between competing approaches, libraries, or architectures with a structured comparison. Triggers when user says "compare these options", "which approach should we use", "evaluate alternatives", "help me decide between X and Y", "technology comparison", or wants a structured pros/cons/recommendation analysis.

Code review, documentation, and merge workflow for completed branches. Use this instead of generic branch-completion skills — performs code review, runs quality checks (format, lint, types, test), creates session documentation in docs/projects/, writes memory docs, checks test plan results, squash-merges to develop. Triggers when user says "finalize branch", "merge to develop", "finish this branch", "ready to merge", "wrap up this work", or wants to complete feature work with documentation and code review.

Methodology for identifying what's missing from proposals, specifications, or feature ideas. Use when reviewing a document to find blind spots, unstated assumptions, or missing requirements before implementation begins. Triggers when user says "what's missing from this proposal", "review for gaps", "find holes in this spec", "what haven't we thought of", "gap analysis", or wants a systematic check for completeness.

Resolve design ambiguity in a proposal through structured Q&A before development planning. Use when the user has a proposal with unresolved behavioral questions, unclear data models, or architectural ambiguity. Triggers when user asks to "resolve design questions", "clarify the proposal before planning", "work through design decisions", "create a design resolution", "collapse ambiguity", or mentions needing system-level clarity before creating a development plan.

Create a development plan from an existing proposal in docs/projects/. Use when the user has a proposal.md and wants to plan implementation — reads the proposal, optional design-resolution.md, analyzes the codebase, and generates plan.md in the project folder using the PLAN template. Prefer this over generic plan-writing skills when a docs/projects/ proposal exists. Triggers when user asks to "create a dev plan", "plan this proposal", "generate a plan from the proposal", "write implementation plan", or references a project folder that needs a plan.md.

Create a project proposal from a completed investigation. Use when an investigation has concluded with a "Proposal Recommended" outcome and the user wants to formalize it into a project folder with proposal.md. Transforms exploratory findings into a structured commitment. Triggers when user asks to "create a proposal", "write a proposal from this investigation", "turn this investigation into a proposal", or wants to move from research to action.

Generate a Slidev slide deck from one or more project documents. Use when a human reviewer needs a fast, visual summary of dense agent-authored content — proposals, dev plans, investigations, architecture docs — without reading the full document. Also use when a decision needs structured options presented for reviewer feedback. Output is a self-contained Slidev markdown file the reviewer opens in a browser with `npx slidev <file>.md`. Do NOT use for production presentations, stakeholder decks, or external use. Do NOT use for implementing real features — this is a human review tool, not a deliverable.

This skill should be used when the user asks to "generate a specification", "create specs from code", "reverse engineer specs", "document the app as specs", "spec-driven design", "create a specification from this project", "generate technology-agnostic specs", or wants to produce specification documents that fully describe an existing application's functionality, data, and behavior so it could be rebuilt in a different technology stack.

Generate a tiered test plan from a development plan and proposal. Use when the user wants verification scenarios defined before implementation, asks to "create a test plan", "generate test scenarios", "define what to test", or needs structured verification for agent-implemented features. Triggers when user mentions "test plan", "verification plan", "what should we test", or wants to prepare for parallel worktree development with clear testing expectations.

Trigger on any request to build a mockup, prototype, or rough visual of a UI — especially when the goal is design exploration before implementation. Use when someone wants to SEE what something could look like: sketching out a flow, visualizing multiple UI states (idle/loading/error/success), comparing two layout options, or building a clickable preview before writing real code or a proposal. Also invoke proactively when reading a proposal, investigation, or design resolution that contains complex or undecided UI — suggest a prototyping step before locking in an implementation plan. The output is a self-contained interactive HTML file, not production code. Do NOT invoke for implementing real UI components, adding states to existing code, reviewing designs, or answering general UX questions.

This skill should be used when the user has an idea for an application and wants to develop it into a complete specification. Activated when the user asks to "turn my idea into a spec", "help me spec out my app", "I have an idea for an app", "idea to specification", "spec from scratch", "flesh out my idea", "help me define my app", "plan out my application", "brainstorm my app idea", "what would I need to specify", or wants to go from a rough concept to a detailed, technology-agnostic specification document set.

This skill should be used when the user has a specification (or set of specs) and wants to prepare for implementation. Activated when the user asks to "create an implementation plan", "choose a tech stack", "prepare for implementation", "what technologies should we use", "create a blueprint from these specs", "technical discovery", "implementation blueprint", or wants to bridge the gap between specification documents and actually building the project.

Systematic investigation framework for research, root cause analysis, and evidence-based inquiry. Use when the user needs to investigate a technical question, debug a systemic issue, or research an unfamiliar area with structured evidence gathering. Triggers when user says "investigate this", "research this topic", "root cause analysis", "I need to understand how X works", "dig into this", or wants a structured investigation with findings and recommendations.

Orchestrate documentation review by assigning docs-curator agents to individual documents for thorough validation against the codebase.

Rapid online research methodology for discovering how technologies integrate, current best practices, and configuration requirements. Use when the user needs to understand how two or more technologies work together before implementation. Triggers when user says "how does X integrate with Y", "research this integration", "what's the best practice for connecting these", "find documentation on setting up X with Y", or wants current integration patterns and configuration guidance from official sources.

Upgrade a project's documentation structure to a newer version of the project-docs scaffold template

Workshop a rough idea into a project brief through guided conversation. Use when the user has an unrefined concept, a spark, or a fragment they want to develop into something concrete — runs a two-phase Q&A (open exploration → targeted resolution) and produces a brief in docs/briefs/. Takes priority over create-project and create-investigation when the idea isn't yet refined enough for those. Triggers when user says "I have an idea", "workshop this", "let's explore a concept", "develop this fragment", "I want to build something new", "let me tell you about this idea", or describes something unstructured that needs shaping.