Project Bootstrap

Default Bootstrap Mode (Quick Intake)

Use this as the default for new projects unless the user explicitly asks for advanced/manual setup.

Quick intake asks only:

1. Project name
2. Optional GitHub repo URL
3. One freeform context drop (paste text and optional image attachments)

Assume the user wants the agent system. Do not ask an enable/disable question.

After creation, default immediately to PRD kickoff so Planner can define scope and suggest architecture options.

Step 1: Determine Project Type

Ask the user:

═══════════════════════════════════════════════════════════════════════
                         ADD NEW PROJECT
═══════════════════════════════════════════════════════════════════════

Choose an option:

  A. Add existing local project folder
  B. Create new project (quick intake: name + context paste/images)
  C. Create from GitHub repo URL (quick intake + clone)
  D. Advanced/manual stack setup

> _
═══════════════════════════════════════════════════════════════════════

Flow by choice:

• Option A → Step 2a: Existing Project Path
• Option B → Step 2b: Quick New Project Creation
• Option C → Step 2c: New Project from GitHub Repo
• Option D → Step 2d: Advanced Manual Stack Selection

Step 2a: Existing Project Path

If Option A (existing project):

Enter the full path to your project:

> _

Example: ~/code/my-project

Validate the path:

• Check folder exists: ls <path>
• Check it's a git repo: git -C <path> rev-parse --git-dir

If not a git repo, ask:

This folder is not a git repository. Initialize git? (y/n)

Continue to: Step 3: Auto-Detect Stack

Step 2b: Quick New Project Creation

If Option B (quick new project):

Ask for only the essentials:

Project name: _

Paste project context (goals, scope, constraints). You can also drop image attachments now.
> _

Then:

1. Create ~/code/<project-name-kebab>
2. Initialize git
3. Run spec analysis from the pasted context (+ images)
4. Continue with stack recommendation and project setup

Agent system is always enabled in this flow.

Step 2c: New Project from GitHub Repo

If Option C (GitHub repo bootstrap):

Project name: _
GitHub repo URL: _

Paste project context (goals, scope, constraints). You can also drop image attachments now.
> _

Then:

1. Clone repository to ~/code/<project-name-kebab>
2. Read existing codebase for stack detection
3. Merge user context with detected stack/capabilities
4. Generate docs manifests and agent system files

Agent system is always enabled in this flow.

Step 2d: Advanced Manual Stack Selection

If Option D (manual stack selection):

Use the existing advanced stack interview flow below.

Step 2e: Spec-Driven Creation (Detailed)

If user explicitly requests deeper spec-driven analysis beyond quick intake, run the detailed flow below.

2b.1: Invoke Spec Analyzer

Load and invoke the spec-analyzer skill:

═══════════════════════════════════════════════════════════════════════
                      NEW PROJECT FROM SPEC
═══════════════════════════════════════════════════════════════════════

Let's start with your project requirements. This helps me recommend
the best technology stack for your needs.

I'll analyze your spec/PRD and extract:
  • Product type (SaaS, API, CLI, etc.)
  • Features needed (auth, payments, realtime, etc.)
  • Scale expectations
  • Technical constraints
  • Core entities and user stories

───────────────────────────────────────────────────────────────────────

[spec-analyzer skill takes over — see spec-analyzer/SKILL.md]

───────────────────────────────────────────────────────────────────────

The spec-analyzer will:

1. Acquire the spec (paste, file, URL, or interactive)
2. Extract structured requirements
3. Present findings for confirmation
4. Output a RequirementsManifest JSON

2b.2: Invoke Stack Advisor

Once spec analysis is complete, invoke the stack-advisor skill:

───────────────────────────────────────────────────────────────────────

Requirements analysis complete! Now let me recommend some tech stacks...

[stack-advisor skill takes over — see stack-advisor/SKILL.md]

───────────────────────────────────────────────────────────────────────

The stack-advisor will:

1. Load the stack database from ~/.config/opencode/data/stacks.yaml
2. Score archetypes against requirements
3. Present top 3 recommendations with trade-offs
4. Allow user to select or customize
5. Output a StackDecision JSON

2b.3: Project Creation

Once stack is selected:

Project name: _
(will be converted to kebab-case for folder name)

Parent directory: ~/code
(press Enter to accept default, or enter a different path)

Create the project:

mkdir -p <parent>/<project-name-kebab>
cd <parent>/<project-name-kebab>
git init

2b.4: Scaffold Generation

Based on the selected archetype from StackDecision, invoke the project-scaffold skill to generate boilerplate code:

───────────────────────────────────────────────────────────────────────

Stack selected! Now generating project scaffold...

[project-scaffold skill takes over — see project-scaffold/SKILL.md]

───────────────────────────────────────────────────────────────────────

The project-scaffold will:

1. Select the appropriate scaffold template based on archetype (e.g., nextjs-prisma, go-chi-postgres)
2. Process template variables from StackDecision and RequirementsManifest
3. Generate all boilerplate files (package.json, config files, source code)
4. Create database schema from entities (if applicable)
5. Run post-scaffold commands (npm install, prisma generate, git init)
6. Output the list of generated files

Available Scaffolds

If scaffold not available: Skip scaffold generation and continue to Step 2b.5. The user will need to manually set up their project structure.

2b.5: Generate Project Agents

Generate project-specific agent definitions from templates based on the selected stack. These agents contain project-tailored guidance that the global routers (critic, tester) will use instead of generic agents.

Templates Directory: ~/.config/opencode/agent-templates/

Template Selection Logic

Based on docs/project.json values, select applicable templates:

Template Rendering

Templates use Handlebars-style syntax. Render them with context from project.json and CONVENTIONS.md:

Template Variables:

const context = {
  PROJECT: projectJson,                    // Full project.json object
  CONVENTIONS: conventionsMarkdown,        // Raw CONVENTIONS.md content
  PROJECT_NAME: projectJson.name,
  PROJECT_PATH: projectPath,
  
  // Computed booleans for conditionals
  HAS_DARK_MODE: projectJson.styling?.darkMode?.enabled,
  DARK_MODE_STRATEGY: projectJson.styling?.darkMode?.strategy,
  USES_TAILWIND: projectJson.styling?.framework === 'tailwind',
  TAILWIND_VERSION: projectJson.styling?.version || '4',
  USES_TYPESCRIPT: projectJson.stack?.languages?.includes('typescript'),
  USES_SUPABASE: projectJson.database?.client === 'supabase',
  USES_PRISMA: projectJson.database?.client === 'prisma',
  USES_DRIZZLE: projectJson.database?.client === 'drizzle',
  DATABASE_TYPE: projectJson.database?.type,
  TESTING_FRAMEWORK: projectJson.testing?.unit,
  E2E_FRAMEWORK: projectJson.testing?.e2e,
};

Conditional Syntax:

{{#if HAS_DARK_MODE}}
## Dark Mode
Always include dark: variants for colors.
{{/if}}

{{#if DARK_MODE_STRATEGY == 'class'}}
Use .dark class on html element.
{{else if DARK_MODE_STRATEGY == 'media'}}
Use prefers-color-scheme media query.
{{/if}}

{{#if USES_PRISMA}}
Use Prisma client for database queries.
{{else if USES_DRIZZLE}}
Use Drizzle ORM for type-safe queries.
{{else if USES_SUPABASE}}
Use Supabase client for database operations.
{{/if}}

Generation Process

1. Create agents directory:

   mkdir -p docs/agents
   

2. For each applicable template:

   • Read template from ~/.config/opencode/agent-templates/<category>/<template>.md
   • Replace {{VARIABLE}} placeholders with context values
   • Process {{#if CONDITION}}...{{else}}...{{/if}} blocks
   • Write rendered agent to docs/agents/<output-name>.md

3. Create agents manifest at docs/agents/manifest.json:

   {
     "generated": "<timestamp>",
     "fromStack": {
       "languages": ["typescript", "go"],
       "framework": "nextjs",
       "styling": "tailwind",
       "testing": "jest"
     },
     "agents": [
       {
         "name": "typescript-critic",
         "template": "critics/typescript.md",
         "output": "docs/agents/typescript-critic.md"
       },
       {
         "name": "react-dev",
         "template": "frontend/react.md",
         "output": "docs/agents/react-dev.md"
       }
     ]
   }
   

4. Update project.json to indicate agents were generated:

   {
     "agents": {
       ...existing config...,
       "projectAgents": "docs/agents/",
       "agentsManifest": "docs/agents/manifest.json"
     }
   }
   

Continue to: Step 9: Agent System Setup

Step 2d: Manual Stack Selection

If Option D (manual stack selection):

User knows their stack and just wants to set up the project structure.

═══════════════════════════════════════════════════════════════════════
                      MANUAL PROJECT SETUP
═══════════════════════════════════════════════════════════════════════

Project name: _
(will be converted to kebab-case for folder name)

Parent directory: ~/code
(press Enter to accept default, or enter a different path)

Create the project:

mkdir -p <parent>/<project-name-kebab>
cd <parent>/<project-name-kebab>
git init

Then ask about stack choices one by one:

───────────────────────────────────────────────────────────────────────
FRONTEND
───────────────────────────────────────────────────────────────────────

  1. Next.js (React, full-stack)
  2. Remix (React, edge-focused)
  3. Nuxt (Vue, full-stack)
  4. SvelteKit (Svelte, full-stack)
  5. Vite + React (SPA)
  6. Vite + Vue (SPA)
  7. Astro (content-focused)
  8. None (API only)

> _

Continue through:

• Backend (if not fullstack frontend)
• Database — Supabase, Postgres, PlanetScale, MongoDB, etc.
• Auth — Based on previous choices
• Styling — Tailwind, CSS Modules, etc.
• Testing — Jest/Vitest, Playwright/Cypress

After collecting choices, continue to: Step 9: Agent System Setup

Step 3: Auto-Detect Stack

Scan the project directory for common files and infer the stack.

Detection Rules

Run these checks in parallel for speed:

# Check for various config files
ls package.json 2>/dev/null          # Node.js/JavaScript/TypeScript
ls go.mod 2>/dev/null                 # Go
ls Cargo.toml 2>/dev/null             # Rust
ls pyproject.toml setup.py requirements.txt 2>/dev/null  # Python
ls pom.xml build.gradle 2>/dev/null   # Java
ls Gemfile 2>/dev/null                # Ruby
ls composer.json 2>/dev/null          # PHP
ls *.csproj *.sln 2>/dev/null         # C#/.NET

package.json Analysis

If package.json exists, read it and detect:

go.mod Analysis

If go.mod exists, detect:

Directory Structure Detection

# Check for monorepo patterns
ls apps/ packages/ 2>/dev/null        # Turborepo/monorepo style
ls src/ 2>/dev/null                   # Single app style

# Check for specific frameworks
ls app/ 2>/dev/null                   # Next.js App Router
ls pages/ 2>/dev/null                 # Next.js Pages Router
ls routes/ 2>/dev/null                # Remix/SvelteKit

# Check for existing agent system
ls docs/prd-registry.json 2>/dev/null
ls docs/project.json 2>/dev/null

# Check for database
ls supabase/ 2>/dev/null              # Supabase
ls prisma/ 2>/dev/null                # Prisma
ls drizzle/ 2>/dev/null               # Drizzle
ls migrations/ 2>/dev/null            # Generic migrations

# Check for config files
ls tailwind.config.* 2>/dev/null      # Tailwind
ls jest.config.* 2>/dev/null          # Jest
ls vitest.config.* 2>/dev/null        # Vitest
ls playwright.config.* 2>/dev/null    # Playwright
ls .eslintrc* eslint.config.* 2>/dev/null  # ESLint

Build Detection Summary

After scanning, compile a detection summary:

const detected = {
  languages: [],           // ['typescript', 'go']
  runtime: null,           // 'node' | 'go' | 'python' | etc
  packageManager: null,    // 'npm' | 'yarn' | 'pnpm' | 'bun'
  framework: null,         // 'nextjs' | 'express' | 'chi' | 'electron' | 'tauri' | etc
  frameworkVersion: null,
  appType: null,           // 'frontend' | 'backend' | 'fullstack' | 'desktop' | 'mobile' | 'cli'
  webContent: null,        // For desktop/mobile: 'bundled' | 'remote' | 'hybrid'
  remoteUrl: null,         // For webContent='remote' or 'hybrid': base URL
  structure: null,         // 'monorepo' | 'single-app'
  styling: null,           // 'tailwind' | 'css-modules' | etc
  database: null,          // 'postgres' | 'mysql' | etc
  databaseClient: null,    // 'supabase' | 'prisma' | etc
  testing: {
    unit: null,            // 'jest' | 'vitest' | etc
    e2e: null              // 'playwright' | 'cypress' | etc
  },
  linting: [],             // ['eslint', 'prettier']
  integrations: [],        // ['stripe', 'resend', 'openai']
  hasAgentSystem: false,
  confidence: {}           // Track confidence per detection
};

Step 4: Present Detection Results

Show what was auto-detected and ask for confirmation/corrections:

═══════════════════════════════════════════════════════════════════════
                      DETECTED PROJECT STACK
═══════════════════════════════════════════════════════════════════════

I scanned your project and detected the following:

  ✅ Languages:      TypeScript, Go
  ✅ Runtime:        Node.js
  ✅ Package Mgr:    npm
  ✅ Framework:      Next.js 15
  ✅ Structure:      Monorepo (apps/, packages/)
  ✅ Styling:        Tailwind CSS v4
  ✅ Database:       Postgres (via Supabase)
  ✅ Unit Testing:   Jest
  ✅ E2E Testing:    Playwright
  ✅ Linting:        ESLint, Prettier
  ✅ Integrations:   Supabase, Stripe, Resend, OpenAI

  ⚠️  Could not detect:
     - Dark mode strategy (class vs media query)
     - Multi-tenant architecture
     - Development server port

═══════════════════════════════════════════════════════════════════════

Is this correct? (y/n, or enter numbers to fix specific items)
> _

Step 5: Clarifying Questions

For items that couldn't be auto-detected or need confirmation, ask targeted questions.

Question Format

Use lettered options for quick responses:

1. Does your app support dark mode?
   A. Yes, using class strategy (.dark on html)
   B. Yes, using media query (prefers-color-scheme)
   C. Yes, using system preference with toggle
   D. No dark mode

2. What port does your dev server run on?
   A. 3000 (default)
   B. 5000
   C. 5001
   D. Other: ___
   E. No local runtime (code-only project, can't run locally)

3. Is this a multi-tenant application?
   A. Yes (data isolated per organization/tenant)
   B. No (single tenant or user-based only)

4. What git workflow should agents use?
   A. Trunk-based (commit directly to main)
   B. Feature branches with PRs
   C. Feature branches without PRs

User can respond: 1A, 2C, 3A, 4A

Desktop/Mobile App Questions

If a desktop or mobile app is detected (Electron, Tauri, React Native, etc.), ask:

═══════════════════════════════════════════════════════════════════════
                       DESKTOP/MOBILE APP CONFIGURATION
═══════════════════════════════════════════════════════════════════════

5. How does your app load web content?
   A. Bundled — HTML/JS/CSS packaged inside the app (typical Electron/Tauri)
   B. Remote — App loads an external URL (WebView wrapping a web app)
   C. Hybrid — Mix of bundled UI with some remote content

   ℹ️  This affects how AI agents verify UI changes:
      • Bundled: Agents launch the app directly for verification
      • Remote: Agents can verify via the web URL without launching the app
      • Hybrid: Agents need to determine which verification method per feature

If user selects B (Remote) or C (Hybrid):

6. What is the base URL for the remote content?
   > _
   
   Example: https://app.myservice.com

Store these in apps.<appName>.webContent and apps.<appName>.remoteUrl.

Step 6: App Structure Discovery

For monorepos or complex projects, discover the app structure:

I found multiple apps in your project:

  apps/
  ├── web/          (Next.js frontend)
  └── api/          (Go backend)

  packages/
  └── types/        (shared)

Should I map these? (y/n)
> _

If yes, for each app ask:

• Entry point directory
• Key structure directories (components, hooks, handlers, etc.)
• Development port

Or attempt auto-detection:

# For Next.js apps
ls app/ pages/ 2>/dev/null            # Entry point
ls components/ 2>/dev/null
ls hooks/ lib/ utils/ 2>/dev/null

# For Go apps
ls cmd/ 2>/dev/null                   # Entry point
ls internal/ pkg/ 2>/dev/null

Step 7: Commands Discovery

Detect available commands from package.json scripts or Makefile:

// From package.json
const scripts = packageJson.scripts || {};
const commandMapping = {
  'dev': scripts.dev || scripts.start || scripts.serve,
  'build': scripts.build,
  'test': scripts.test,
  'testUnit': scripts['test:unit'] || scripts.test,
  'testE2E': scripts['test:e2e'] || scripts.e2e,
  'typecheck': scripts.typecheck || scripts['type-check'] || scripts.tsc,
  'lint': scripts.lint,
  'lintFix': scripts['lint:fix'] || scripts.fix,
  'format': scripts.format || scripts.prettier
};

Present for confirmation:

Detected commands (from package.json):

  dev:       npm run dev
  build:     npm run build
  test:      npm run test
  typecheck: npm run typecheck
  lint:      npm run lint
  
  ⚠️  Not found: test:e2e, format

Are these correct? (y/n)
> _

Step 8: Features Detection

Ask about higher-level features:

Which features does your project include?

  [x] Authentication (detected: @supabase/ssr)
  [x] Payments (detected: stripe)
  [x] Email (detected: resend)
  [x] AI/LLM (detected: openai)
  [ ] Internationalization (i18n)
  [x] Dark mode
  [ ] Marketing pages
  [ ] Support documentation
  [ ] Real-time updates
  [x] API (detected: app/api/)

Enter letters to toggle, or press Enter to confirm:
  A=Auth, B=Payments, C=Email, D=AI, E=i18n, F=DarkMode, 
  G=Marketing, H=SupportDocs, I=Realtime, J=API

> _

Step 8b: Infrastructure Conventions

For projects with backend/API components, ask about infrastructure patterns that critics and dev agents need to know:

═══════════════════════════════════════════════════════════════════════
                    INFRASTRUCTURE CONVENTIONS
═══════════════════════════════════════════════════════════════════════

AI agents can review network, security, and API patterns more accurately 
if they know your conventions. Answer what applies to your project:

───────────────────────────────────────────────────────────────────────
NETWORK & HTTP
───────────────────────────────────────────────────────────────────────

1. Do you have a standard HTTP client wrapper with built-in retries/timeouts?
   A. Yes (I'll provide the path)
   B. No, we use fetch/axios/http directly
   C. N/A (no external HTTP calls)

2. What are your timeout conventions? (Enter to skip if not standardized)
   Internal API connect/read: ___/___ms  (e.g., 5000/30000)
   External API connect/read: ___/___ms
   Database timeout: ___ms

> _

If they have a wrapper, ask for the path:

Path to HTTP client wrapper (relative to project root):
> lib/http/client.ts

Continue with security if they have backend code:

───────────────────────────────────────────────────────────────────────
SECURITY
───────────────────────────────────────────────────────────────────────

3. Where is your authentication middleware defined?
   > _ (e.g., src/middleware/auth.ts, or "Supabase auth" for managed)

4. What CSRF protection strategy do you use?
   A. Double-submit cookie
   B. Synchronizer token
   C. SameSite cookie only
   D. None / N/A (API-only with token auth)

5. Where is CORS configured?
   > _ (e.g., src/config/cors.ts, or "Next.js middleware")

6. What input validation library do you use?
   A. Zod
   B. Yup  
   C. Joi
   D. class-validator
   E. None / manual validation
   F. Other: ___

> _

Continue with AWS if detected:

───────────────────────────────────────────────────────────────────────
AWS (detected: aws-sdk usage)
───────────────────────────────────────────────────────────────────────

7. Do you have a standard AWS client wrapper?
   A. Yes (I'll provide the path)
   B. No, direct SDK usage
   
8. Do AWS services run locally in development?
   A. Yes (LocalStack, DynamoDB Local, etc.)
   B. No, we use real AWS in dev
   C. Mixed (some local, some real)

9. What infrastructure-as-code tool do you use?
   A. CDK
   B. CloudFormation
   C. Terraform
   D. SAM
   E. Serverless Framework
   F. None

> _

Continue with API conventions:

───────────────────────────────────────────────────────────────────────
API DESIGN
───────────────────────────────────────────────────────────────────────

10. What pagination style do you use?
    A. Offset-based (page, pageSize)
    B. Cursor-based (cursor, limit)
    C. Limit-offset (offset, limit)
    D. None / not applicable

11. Do you use a standard response envelope?
    A. Yes: { data: ..., meta?: ... }
    B. Yes: { result: ... }
    C. No envelope (return data directly)
    D. Other (I'll describe in CONVENTIONS.md)

> _

Step 8c: Documentation & AI Tools Systems

If the project has support documentation or AI features, ask about the systems:

───────────────────────────────────────────────────────────────────────
DOCUMENTATION SYSTEM (for docs-writer, support-article-writer)
───────────────────────────────────────────────────────────────────────

12. What documentation system do you use for user-facing docs?
    A. Markdown files (in docs/ or content/)
    B. Docusaurus
    C. VitePress
    D. Database-backed (stored in Supabase/Postgres)
    E. Notion
    F. None yet

If database-backed:
    Table name for articles: ___
    
> _

If AI features detected:

───────────────────────────────────────────────────────────────────────
AI TOOLS SYSTEM (for tools-writer)
───────────────────────────────────────────────────────────────────────

13. What AI tool system do you use for chatbot/agent tools?
    A. OpenAI function calling
    B. LangChain tools
    C. MCP (Model Context Protocol)
    D. Custom system
    E. None yet

If a system is selected:
    Tool schema file: ___
    Tool implementation file: ___

> _

Step 8d: Testing Conventions

For projects with test frameworks detected:

───────────────────────────────────────────────────────────────────────
TESTING CONVENTIONS
───────────────────────────────────────────────────────────────────────

14. Where are your tests located?
    A. Co-located (*.test.ts next to source)
    B. Co-located in __tests__/ directories
    C. Centralized (test/ or tests/ directory)
    D. Mixed

15. What should be mocked in tests?
    (Select all that apply)
    A. External HTTP APIs
    B. Time/dates
    C. Database (we use test DB)
    D. AWS services (we use LocalStack)
    E. Nothing specific

16. What should NOT be mocked?
    (Select all that apply)
    A. Database (test against real/local DB)
    B. AWS services (test against local services)
    C. Internal services (test integration)
    
> _

If E2E tests detected:

17. For E2E tests, what selector strategy do you prefer?
    A. Role-based (getByRole) - recommended
    B. Test IDs (getByTestId)
    C. Text content (getByText)
    D. Mixed / no strong preference

18. How do E2E tests handle authentication?
    A. Storage state from global setup
    B. Mock auth API responses
    C. Real login flow each test
    D. Not sure yet

> _

If project has a UI (detected frontend framework):

19. How should AI agents verify UI changes?
    A. Playwright required - must verify with browser test (recommended)
    B. No UI verification - backend/CLI only project
    
    Note: Playwright verification generates reusable test scripts in tests/ui-verify/
    and captures screenshots for visual confirmation.

> _

Store all infrastructure convention answers for use when generating CONVENTIONS.md.

Step 8e: Git Workflow

Ask about branching strategy:

───────────────────────────────────────────────────────────────────────
GIT WORKFLOW
───────────────────────────────────────────────────────────────────────

19. What branching strategy do you use?

    A. Trunk-based
       All work happens on main with short-lived feature branches (< 1 day).
       No long-running branches. Merge directly to main.
       → Best for: Solo devs, small teams, rapid iteration, CI/CD-heavy
       
    B. GitHub Flow
       Feature branches → Pull Request → Merge to main → Deploy from main.
       Simple and effective for continuous deployment.
       → Best for: Most SaaS projects, continuous deployment
       
    C. Git Flow
       Feature branches → develop branch → release branches → main.
       Structured workflow with develop for integration, release/* for 
       stabilization, and main for production.
       → Best for: Projects with formal release cycles, multiple environments
       
    D. Release Branches
       Feature branches → develop → release/* → main.
       Similar to Git Flow but with emphasis on scheduled releases.
       Release branches progress through test → stage → production.
       → Best for: Enterprise, regulated industries, scheduled releases

    Default: A (Trunk-based)

> _

If they choose C (Git Flow) or D (Release Branches), ask follow-up:

20. What is your integration branch called?
    This is where feature branches merge before release.
    Default: develop
    > _

21. What pattern do you use for release branches?
    Default: release/*
    > _

Step 9: Agent System Setup

Always enable PRD-based agent system for bootstrap flows.

Create:

mkdir -p docs/prds docs/drafts docs/completed docs/bugs docs/memory docs/abandoned

And create registry files (see Step 10).

Do not ask an enable/disable question for agent system setup.

Step 9a: Seed Architecture Guardrails and Bounded-Context Docs

During bootstrap, generate baseline architecture automation artifacts by default.

1. Seed architecture guardrails from detected structure:
   • import boundary rules
   • layer constraints (UI/app/domain/data)
   • restricted direct-access rules
2. Seed bounded-context docs:
   • docs/architecture/bounded-contexts.md
   • optional docs/architecture/contexts/*.md
3. Persist default policies in docs/project.json:

{
  "architecture": {
    "guardrails": {
      "enabled": true,
      "strictness": "standard",
      "exceptionsPath": "docs/architecture/guardrail-exceptions.md"
    },
    "boundedContexts": {
      "enabled": true,
      "policy": "strict",
      "docsPath": "docs/architecture/bounded-contexts.md"
    }
  }
}

Supported strictness values for guardrails: fast, standard, strict.

Only ask users to override these defaults when they explicitly request policy customization.

Step 9b: Documentation Templates

Generate both documentation templates by default:

• docs/ARCHITECTURE.md
• docs/CONVENTIONS.md

Do not prompt for this in quick intake mode.

Templates are located at:

• ~/.config/opencode/templates/ARCHITECTURE.md
• ~/.config/opencode/templates/CONVENTIONS.md

When generating, replace placeholders with detected values:

Basic Placeholders

Infrastructure Convention Placeholders

For sections that can't be auto-filled, leave the placeholder with a <!-- BOOTSTRAP NOTE: ... --> comment explaining what to add.

Step 9c: Generate Project-Specific Agents

Generate project-specific agent definitions from templates. These agents are tailored to the project's stack and conventions, and are used by routers (critic, tester) instead of generic global agents.

═══════════════════════════════════════════════════════════════════════
                    PROJECT-SPECIFIC AGENTS
═══════════════════════════════════════════════════════════════════════

I can generate project-specific AI agents that understand your exact 
stack and conventions. These replace generic agents with tailored ones:

  Based on your stack, I'll generate:
  
    ✅ typescript-critic.md   (TypeScript code review)
    ✅ react-dev.md           (React development patterns)
    ✅ react-tester.md        (Jest + React Testing Library)
    ✅ tailwind.md            (Tailwind CSS patterns)
    ⬜ go-critic.md           (not applicable - no Go detected)
    
  These agents know:
    • Your database: Supabase with Prisma
    • Your styling: Tailwind v4 with class-based dark mode
    • Your testing: Jest + Playwright
    • Your conventions from CONVENTIONS.md

Generate project-specific agents?

  A. Yes, generate all applicable agents (recommended)
  B. Let me select which agents to generate
  C. No, use global agents only

> _
═══════════════════════════════════════════════════════════════════════

Agent Selection (if Option B)

If user wants to select specific agents:

Select agents to generate (enter letters, e.g., A,B,D):

  Critics (code review):
    A. typescript-critic.md  - TypeScript-specific review patterns
    B. python-critic.md      - Python-specific review patterns  
    C. go-critic.md          - Go-specific review patterns

  Development (implementation guidance):
    D. react-dev.md          - React/Next.js patterns
    E. vue-dev.md            - Vue/Nuxt patterns
    F. svelte-dev.md         - Svelte/SvelteKit patterns
    G. express-dev.md        - Express.js patterns
    H. fastapi-dev.md        - FastAPI patterns
    I. go-dev.md             - Go Chi patterns

  Styling:
    J. tailwind.md           - Tailwind CSS patterns

  Testing:
    K. react-tester.md       - Jest + React Testing Library
    L. jest-tester.md        - Jest for backend TypeScript
    M. go-tester.md          - Go testify patterns
    N. pytest-tester.md      - Python pytest patterns
    O. playwright-tester.md  - Playwright E2E testing

> _

Agent Generation Process

1. Create agents directory:

   mkdir -p docs/agents
   

2. For each selected template:

   a. Read template from ~/.config/opencode/agent-templates/<category>/<name>.md

   b. Build context object:

   const context = {
     PROJECT: projectJson,
     PROJECT_NAME: projectJson.name,
     PROJECT_PATH: projectPath,
     
     // From project.json
     HAS_DARK_MODE: projectJson.styling?.darkMode?.enabled,
     DARK_MODE_STRATEGY: projectJson.styling?.darkMode?.strategy,
     USES_TAILWIND: projectJson.styling?.framework === 'tailwind',
     TAILWIND_VERSION: projectJson.styling?.version || '4',
     USES_TYPESCRIPT: projectJson.stack?.languages?.includes('typescript'),
     DATABASE_TYPE: projectJson.database?.type,
     DATABASE_CLIENT: projectJson.database?.client,
     TESTING_FRAMEWORK: projectJson.testing?.unit,
     E2E_FRAMEWORK: projectJson.testing?.e2e,
     
     // Computed from detection/selection
     USES_SUPABASE: projectJson.database?.client === 'supabase',
     USES_PRISMA: projectJson.database?.client === 'prisma',
     USES_DRIZZLE: projectJson.database?.client === 'drizzle',
     USES_ZOD: projectJson.security?.inputValidation === 'zod',
     USES_NEXT_APP_ROUTER: projectJson.apps?.web?.framework === 'nextjs' && projectJson.apps?.web?.router === 'app',
   };
   

   c. Process template:

   • Replace {{VARIABLE}} with context values
   • Evaluate {{#if CONDITION}}...{{else}}...{{/if}} blocks
   • Remove unfulfilled conditional blocks entirely

   d. Write to docs/agents/<output-name>.md

3. Create manifest at docs/agents/manifest.json:

   {
     "generated": "2026-02-19T10:30:00Z",
     "fromStack": {
       "languages": ["typescript"],
       "framework": "nextjs",
       "styling": "tailwind",
       "testing": "jest"
     },
     "agents": [
       {
         "name": "typescript-critic",
         "template": "critics/typescript.md",
         "output": "docs/agents/typescript-critic.md",
         "purpose": "TypeScript code review"
       }
     ]
   }
   

4. Update project.json:

   {
     "agents": {
       "gitWorkflow": "trunk-based",
       "autoCommit": true,
       "projectAgents": "docs/agents/",
       "agentsManifest": "docs/agents/manifest.json"
     }
   }
   

Template Syntax Reference

Templates use Handlebars-style syntax:

Example template snippet:

## Database Queries

{{#if USES_PRISMA}}
Use Prisma client for all database operations:
\`\`\`typescript
import { prisma } from '@/lib/prisma';
const users = await prisma.user.findMany();
\`\`\`
{{else if USES_DRIZZLE}}
Use Drizzle ORM for type-safe queries:
\`\`\`typescript
import { db } from '@/lib/db';
const users = await db.select().from(users);
\`\`\`
{{else if USES_SUPABASE}}
Use Supabase client for database operations:
\`\`\`typescript
import { createClient } from '@/lib/supabase/server';
const supabase = await createClient();
const { data: users } = await supabase.from('users').select();
\`\`\`
{{/if}}

Step 10: Generate Files

Data Sources

The data for file generation comes from different sources depending on how the project was created:

10a: Generate docs/project.json

Compile all detected and confirmed information into the manifest:

{
  "$schema": "https://opencode.ai/schemas/project.json",
  
  "name": "<Project Name>",
  "description": "<user-provided or auto-generated>",
  
  "stack": {
    "languages": [/* detected or from StackDecision */],
    "runtime": "<detected or from StackDecision>",
    "packageManager": "<detected or from StackDecision>"
  },
  
  "apps": {/* discovered structure or generated from scaffold */},
  "packages": {/* discovered packages */},
  
  "database": {/* detected or from StackDecision */},
  "styling": {/* detected or from StackDecision */},
  "testing": {/* detected or from StackDecision */},
  "linting": {/* detected or defaults */},
  
  "git": {
    "branchingStrategy": "<from Step 8e Q19: trunk-based|github-flow|git-flow|release-branches>",
    "defaultBranch": "main",
    "developBranch": "<from Step 8e Q20 if applicable, default: develop>",
    "releaseBranchPattern": "<from Step 8e Q21 if applicable, default: release/*>"
  },
  
  "commands": {/* discovered or scaffold defaults */},
  "qualityGates": {/* inferred from commands */},
  
  "features": {
    "authentication": true,
    "multiTenant": false,
    "payments": true,
    "email": true,
    "i18n": false,
    "darkMode": true,
    "marketing": false,
    "api": true,
    "realtime": false,
    "documentation": {
      "system": "<from Step 8c Q12: markdown|docusaurus|database|none>",
      "userDocsPath": "<if provided>",
      "supportArticlesPath": "<if provided>",
      "databaseTable": "<if database-backed>"
    },
    "aiTools": {
      "system": "<from Step 8c Q13: openai-functions|langchain|mcp|none>",
      "schemaPath": "<if provided>",
      "implementationPath": "<if provided>"
    }
  },
  
  "integrations": [/* detected */],
  
  "aws": {
    "services": ["dynamodb", "s3", "sqs"],
    "sdkVersion": "v3",
    "infrastructure": "<from Step 8b Q9: cdk|cloudformation|terraform|none>",
    "infrastructurePath": "<if provided>",
    "clientWrapperPath": "<from Step 8b Q7 if provided>",
    "localDevelopment": "<from Step 8b Q8: true|false>"
  },
  
  "security": {
    "authMiddleware": "<from Step 8b Q3>",
    "csrfProtection": "<from Step 8b Q4: double-submit|synchronizer-token|samesite-cookie|none>",
    "corsConfigPath": "<from Step 8b Q5>",
    "inputValidation": "<from Step 8b Q6: zod|yup|joi|class-validator>"
  },
  
  "agents": {
    "autoCommit": true,
    "autoPush": true,
    "prReviewRequired": false,
    "workingDir": "ai-tmp",
    "verification": {
      "mode": "playwright-required",
      "selectorStrategy": "strict",
      "testDir": "tests/ui-verify",
      "screenshotDir": "ai-tmp/verification/screenshots",
      "reviewGeneratedTests": true
    }
  },
  
  "context": {
    "architecture": "docs/ARCHITECTURE.md",
    "conventions": "docs/CONVENTIONS.md",
    "designSystem": null
  }
}

Note: Only include sections that apply to the project. Omit aws if no AWS services detected, omit security fields that weren't answered, etc.

10b: Generate docs/prd-registry.json (if agent system)

{
  "version": "1.0",
  "prds": [],
  "completed": []
}

10c: Generate docs/session-locks.json (if agent system)

{
  "sessions": []
}

10d: Generate docs/ARCHITECTURE.md

Use the template from ~/.config/opencode/templates/ARCHITECTURE.md.

Replace placeholders with detected values. For a Next.js + Supabase project:

# Architecture

> This document describes the high-level architecture of Example Scheduler.
> It helps AI agents and new developers understand how the codebase is organized.

## Overview

Scheduling application for flooring businesses.

## Directory Structure

\`\`\`
example-scheduler/
├── apps/
│   └── web/                    # Next.js 15 frontend
│       ├── app/               # App Router pages
│       ├── components/        # React components
│       └── lib/               # Utilities
├── packages/
│   └── types/                 # Shared TypeScript types
├── supabase/
│   └── migrations/            # Database migrations
└── docs/                      # Documentation and PRDs
\`\`\`

## Database Schema

**Type:** PostgreSQL
**Client:** Supabase
**Migrations:** `supabase/migrations/`

<!-- Continue filling in detected values... -->

10e: Generate docs/CONVENTIONS.md

Use the template from ~/.config/opencode/templates/CONVENTIONS.md.

Replace placeholders with detected values. For a TypeScript + Tailwind project:

# Conventions

> This document describes the coding conventions and patterns used in Example Scheduler.
> AI agents should follow these patterns to maintain consistency.

## File Naming

| Type | Convention | Example |
|------|------------|---------|
| Components | PascalCase | `UserProfile.tsx` |
| Hooks | camelCase with `use` prefix | `useAuth.ts` |
| Utilities | camelCase | `formatDate.ts` |

## Styling

### Framework: Tailwind CSS v4

### Dark Mode

**Strategy:** class-based (.dark on html)

\`\`\`tsx
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
  Content adapts to theme
</div>
\`\`\`

<!-- Continue filling in detected values... -->

10f: Generate/Update AGENTS.md (if doesn't exist)

Create a minimal AGENTS.md with key information:

# <Project Name>

## Development

\`\`\`bash
<detected dev command>    # Start dev server
<detected test command>   # Run tests
<detected build command>  # Production build
\`\`\`

## Documentation

For detailed information, see:
- [Architecture](docs/ARCHITECTURE.md) - System overview and data flow
- [Conventions](docs/CONVENTIONS.md) - Coding patterns and style guidelines

## Project Structure

\`\`\`
<discovered structure>
\`\`\`

## Tech Stack

- **Frontend**: <detected>
- **Backend**: <detected>
- **Database**: <detected>
- **Testing**: <detected>

Step 10g: Generate Initial PRD (for spec-driven new projects)

If the project was created via spec-driven flow (Option B), generate an initial PRD from the extracted user stories:

From RequirementsManifest

The RequirementsManifest contains:

• entities — Core domain objects
• userStories — Extracted user stories with priorities

Generate docs/drafts/prd-mvp.md

Use the prd skill to format, or generate directly:

# PRD: MVP - <Project Name>

> Initial PRD generated from project spec analysis.

## Overview

<Description from RequirementsManifest or user input>

## Entities

| Entity | Description |
|--------|-------------|
{{#each entities}}
| {{name}} | {{description}} |
{{/each}}

## User Stories

{{#each userStories}}
### {{id}}: {{title}}

**Priority:** {{priority}}

{{description}}

**Acceptance Criteria:**
- [ ] TBD — refine with @planner

{{/each}}

## Technical Notes

**Selected Stack:** {{stackDecision.archetype}}
- Frontend: {{stackDecision.stack.frontend.framework}}
- Backend: {{stackDecision.stack.backend.framework}}
- Database: {{stackDecision.stack.database.provider}}
- Auth: {{stackDecision.stack.auth.provider}}

## Open Questions

{{#if requirementsManifest.openQuestions}}
{{#each requirementsManifest.openQuestions}}
- [ ] {{question}}
{{/each}}
{{else}}
None identified during spec analysis.
{{/if}}

Update docs/prd-registry.json

Add the generated PRD:

{
  "version": "1.0",
  "prds": [
    {
      "id": "prd-mvp",
      "name": "MVP",
      "status": "draft",
      "filePath": "docs/drafts/prd-mvp.md",
      "createdAt": "<timestamp>",
      "stories": [/* extracted story IDs */]
    }
  ],
  "completed": []
}

Save Analysis Files

Also save the analysis outputs for reference:

• docs/requirements.json — The RequirementsManifest
• docs/stack-decision.json — The StackDecision

These can be referenced later for understanding why certain choices were made.

Step 10h: Generate Project-Specific Skills (US-009)

After generating the project manifest, auto-invoke meta-skill generators based on detected capabilities.

Skill Trigger Mapping

Load the capability-to-skill mapping from ~/.config/opencode/data/meta-skill-triggers.json:

{
  "capabilityTriggers": {
    "authentication": { "metaSkill": "auth-skill-generator", "generates": "auth-flow" },
    "multiTenant": { "metaSkill": "multi-tenant-skill-generator", "generates": "tenant-context" },
    "api": { "metaSkill": "api-endpoint-skill-generator", "generates": "api-patterns" },
    "email": { "metaSkill": "email-skill-generator", "generates": "email-patterns" },
    "ai": { "metaSkill": "ai-tools-skill-generator", "generates": "ai-tools" }
  },
  "integrationTriggers": {
    "stripe": { "metaSkill": "stripe-skill-generator", "generates": "payments" }
  },
  "alwaysGenerate": [
    { "metaSkill": "crud-skill-generator", "generates": "crud-patterns", "condition": "hasDatabase" },
    { "metaSkill": "database-migration-skill-generator", "generates": "migrations", "condition": "hasDatabase" },
    { "metaSkill": "form-skill-generator", "generates": "form-patterns", "condition": "hasFrontend" },
    { "metaSkill": "table-skill-generator", "generates": "table-patterns", "condition": "hasFrontend" }
  ]
}

Determine Skills to Generate

Based on the detected/confirmed capabilities and integrations:

const skillsToGenerate = [];

// Check capabilities from project.json.capabilities (or features for legacy)
for (const [capability, config] of Object.entries(capabilityTriggers)) {
  if (projectJson.capabilities?.[capability] || projectJson.features?.[capability]) {
    skillsToGenerate.push(config);
  }
}

// Check integrations
for (const [integration, config] of Object.entries(integrationTriggers)) {
  if (projectJson.integrations?.includes(integration)) {
    skillsToGenerate.push(config);
  }
}

// Always-generate skills based on conditions
for (const config of alwaysGenerate) {
  if (config.condition === 'hasDatabase' && projectJson.database) {
    skillsToGenerate.push(config);
  }
  if (config.condition === 'hasFrontend' && projectJson.apps?.web) {
    skillsToGenerate.push(config);
  }
}

Ask User Permission

═══════════════════════════════════════════════════════════════════════
                    PROJECT-SPECIFIC SKILLS
═══════════════════════════════════════════════════════════════════════

Based on your project's capabilities, I can generate these skills:

  ✅ auth-flow         Authentication patterns (capabilities.authentication)
  ✅ tenant-context    Multi-tenant isolation (capabilities.multiTenant)
  ✅ api-patterns      API endpoint conventions (capabilities.api)
  ✅ payments          Stripe integration patterns (integrations: stripe)
  ✅ crud-patterns     Entity CRUD operations (database detected)
  ✅ migrations        Database migration patterns (database detected)
  ✅ form-patterns     Form handling (frontend detected)
  ✅ table-patterns    Data tables (frontend detected)

These skills help AI agents understand YOUR project's specific patterns.

Generate project-specific skills?

  Y. Yes, generate all (recommended)
  S. Select which ones to generate
  N. Skip skill generation

> _
═══════════════════════════════════════════════════════════════════════

Generate Skills

For each skill to generate:

1. Create the skills directory:

   mkdir -p docs/skills
   

2. Invoke the meta-skill generator: The meta-skill generator (e.g., auth-skill-generator) will:

   • Analyze the codebase for existing patterns
   • Ask any necessary clarifying questions
   • Generate docs/skills/<skill-name>/SKILL.md

   Generating auth-flow skill...
   
   [auth-skill-generator runs, may ask questions about auth patterns]
   
   ✅ Created: docs/skills/auth-flow/SKILL.md
   

3. Track generated skills: After each skill is generated, record it in project.json:

   {
     "skills": {
       "projectSkillsPath": "docs/skills/",
       "generated": [
         {
           "name": "auth-flow",
           "generatedFrom": "auth-skill-generator",
           "generatedAt": "2026-02-20",
           "triggeredBy": "capabilities.authentication"
         },
         {
           "name": "tenant-context",
           "generatedFrom": "multi-tenant-skill-generator",
           "generatedAt": "2026-02-20",
           "triggeredBy": "capabilities.multiTenant"
         }
       ]
     }
   }
   

Output

After skill generation completes:

═══════════════════════════════════════════════════════════════════════
                    SKILLS GENERATED
═══════════════════════════════════════════════════════════════════════

Generated 6 project-specific skills:

  docs/skills/
  ├── auth-flow/SKILL.md         Authentication patterns
  ├── tenant-context/SKILL.md    Multi-tenant isolation
  ├── api-patterns/SKILL.md      API endpoint conventions
  ├── payments/SKILL.md          Stripe integration
  ├── crud-patterns/SKILL.md     Entity CRUD operations
  └── migrations/SKILL.md        Database migrations

These skills will be automatically loaded when agents work on
related tasks. You can customize them in docs/skills/.

═══════════════════════════════════════════════════════════════════════

Step 10i: Configure Vectorization (US-016)

If the environment has OPENAI_API_KEY available, offer to set up semantic search vectorization:

═══════════════════════════════════════════════════════════════════════
                    SEMANTIC SEARCH (VECTORIZATION)
═══════════════════════════════════════════════════════════════════════

Vectorization enables AI agents to search your codebase semantically — 
finding relevant code by meaning, not just keywords.

Benefits:
  • Ask "How does authentication work?" instead of grepping for "auth"
  • 49% fewer retrieval failures with Contextual Retrieval
  • Database schema awareness for agents
  • Hybrid search combining semantic + keyword matching

Requirements:
  ✅ OPENAI_API_KEY found in environment
  ✅ ANTHROPIC_API_KEY found (enables Contextual Retrieval)

Estimated cost for this project:
  Files: ~<detected file count>
  Initial indexing: ~$<estimated cost>
  Incremental updates: ~$0.01/commit

Enable vectorization?

  A. Yes, initialize now (recommended)
  B. Yes, but defer indexing (configure only)
  C. No, skip vectorization

> _
═══════════════════════════════════════════════════════════════════════

If Option A (Initialize Now)

1. Add vectorization config to docs/project.json:

   {
     "vectorization": {
       "enabled": true,
       "storage": "local",
       "embeddingModel": "openai",
       "contextualRetrieval": "auto",
       "codebase": {
         "include": ["src/**", "lib/**", "app/**", "docs/**"],
         "exclude": ["node_modules/**", "dist/**", "build/**", ".git/**", "*.test.ts"],
         "chunkStrategy": "ast"
       },
       "search": {
         "hybridWeight": 0.7,
         "topK": 20
       },
       "refresh": {
         "onGitChange": true,
         "onSessionStart": true,
         "maxAge": "24h"
       },
       "credentials": {
         "openai": "env:OPENAI_API_KEY",
         "anthropic": "env:ANTHROPIC_API_KEY"
       }
     }
   }
   

2. Run initial indexing:

   cd <project-root>
   npx @opencode/vectorize init
   

3. Show progress:

   Building vector index...
     Scanning: 1,247 files
     Chunking: → 8,453 chunks
     Contextual: Adding descriptions (Claude Haiku)
     Embedding: 8,453 chunks → vectors
     [████████████████████] 100%
   
   ✅ Vectorization ready!
      Index: 8,453 chunks (42MB)
      Cost: $2.34 (one-time)
   

If Option B (Defer Indexing)

1. Add vectorization config with enabled: false:

   {
     "vectorization": {
       "enabled": false,
       ...same config as above...
     }
   }
   

2. Show message:

   Vectorization configured but deferred.
   
   To initialize later:
     cd <project-root>
     npx @opencode/vectorize init
   
   Or @builder will prompt you on next session.
   

If Option C (Skip)

Do not add vectorization section to project.json.

Database Integration

If database was detected and configured:

Database detected (PostgreSQL via Supabase).

Include database schema in vector index?
  • Tables and columns will be searchable
  • Agents can find relevant tables for features
  
  A. Yes, index schema
  B. No, code only

> _

If yes, add to vectorization config:

{
  "vectorization": {
    ...
    "database": {
      "enabled": true,
      "connection": "env:DATABASE_URL",
      "type": "postgres",
      "schema": {
        "enabled": true,
        "include": ["public.*"],
        "exclude": ["public._prisma_migrations"]
      }
    }
  }
}

Config Table Detection

If database indexing is enabled, optionally ask about config tables:

Some tables contain reference/config data that helps agents understand
business logic (pricing tiers, feature flags, etc.).

Do you have config tables to index?
  A. Yes (I'll list them)
  B. No / not sure (skip)

> _

If yes:

Enter config table names (comma-separated):
> pricing_tiers, feature_flags

How many sample rows per table?
  A. 10 rows
  B. 50 rows
  C. All rows (small tables only)

> _

Step 10j: Configure Related Projects

Ask about relationships to other registered projects. This enables agents to find companion projects (e.g., documentation sites, marketing sites, API backends) without guessing based on names.

═══════════════════════════════════════════════════════════════════════
                       RELATED PROJECTS
═══════════════════════════════════════════════════════════════════════

Does this project have related companion projects?

Related projects help agents automatically find:
  • Documentation sites (for syncing docs updates)
  • Marketing sites (for feature announcements)
  • API backends (for contract alignment)
  • Admin dashboards (for operational features)

Registered projects:
  1. yo-go (AI toolkit)
  2. helm-ade (SaaS application)
  3. helm-api (Go API backend)
  4. opencode-toolkit-website (documentation)

Select related projects (comma-separated numbers, or 'skip'):
> _
═══════════════════════════════════════════════════════════════════════

For Each Selected Project

Ask about the relationship type:

Selected: yo-go

What is the relationship of THIS project to yo-go?
(How does this project relate to yo-go?)

  Common types:
    • documentation-site    This documents yo-go
    • documented-project    This is documented by yo-go
    • marketing-site        This markets yo-go
    • marketed-product      This is marketed by yo-go
    • api-backend           This is the API for yo-go
    • frontend-client       This is a frontend for yo-go
    • admin-dashboard       This manages yo-go
    • managed-service       This is managed by yo-go
    • shared-library        This is shared code for yo-go
    • dependent-project     This depends on yo-go
    • monorepo-sibling      This is in the same monorepo as yo-go
    • test-harness          This tests yo-go
    • tested-system         This is tested by yo-go

Or type a custom relationship name.

> documented-project

Add a label? (for multiple same-type relationships, e.g., 'user-docs' vs 'api-docs')
Press Enter to skip.
> _

Optional description:
> The AI toolkit this site documents

Inverse Relationship Offer

After configuring a relationship, offer to add the inverse:

───────────────────────────────────────────────────────────────────────

Add inverse relationship to yo-go?

This will add to yo-go/docs/project.json:
  {
    "projectId": "<this-project-id>",
    "relationship": "documentation-site",
    "description": "Public documentation website for the AI toolkit"
  }

Add inverse? (y/n)
> y

✅ Updated yo-go/docs/project.json
───────────────────────────────────────────────────────────────────────

Add more related projects? (y/n)
> n

Inverse Relationship Mapping

Use this mapping to determine the inverse relationship type:

For custom relationship types, ask the user what the inverse should be called.

Label Disambiguation

If the user tries to add a relationship type that already exists for this project (e.g., a second documentation-site), require a label:

⚠️  This project already has a documentation-site relationship.

To add another, you must provide a label for disambiguation.

Label for the existing relationship (opencode-toolkit-website):
> user-docs

Label for this new relationship (api-docs-site):
> api-docs

Add to project.json

After configuring related projects, add to the project's docs/project.json:

{
  "relatedProjects": [
    {
      "projectId": "yo-go",
      "relationship": "documented-project",
      "description": "The AI toolkit this site documents"
    }
  ]
}

Step 11: Update Global Registry

Add the project to ~/.config/opencode/projects.json:

{
  "id": "<kebab-case-name>",
  "name": "<Display Name>",
  "path": "<full-path>",
  "description": "<description>",
  "devPort": <port-number-or-null>,
  "hasAgentSystem": true,
  "projectManifest": "docs/project.json",
  "prdRegistry": "docs/prd-registry.json" or null,
  "sessionLocks": "docs/session-locks.json" or null
}

devPort assignment:

• Use the port from user's answer to question 2 (e.g., 3000, 5000, 5001, or custom)
• If user selected "No local runtime" (option E), set devPort: null
• When devPort is null, E2E tests and dev server startup are skipped for this project

Set as activeProject.

Step 13: Summary

Display completion summary based on flow used:

For Existing Projects

═══════════════════════════════════════════════════════════════════════
                      PROJECT SETUP COMPLETE
═══════════════════════════════════════════════════════════════════════

✅ Created: docs/project.json (with stack, features, integrations)
✅ Created: docs/prd-registry.json
✅ Created: docs/session-locks.json
✅ Created: docs/ARCHITECTURE.md
✅ Created: docs/CONVENTIONS.md (with infrastructure conventions)
✅ Created: docs/agents/ (project-specific agents)
✅ Created: AGENTS.md
✅ Updated: ~/.config/opencode/projects.json
✅ Vectorization: Enabled (8,453 chunks indexed)

Project "<Name>" is now ready!

📦 Generated agents (in docs/agents/):
   - typescript-critic.md    TypeScript code review
   - react-dev.md            React/Next.js patterns
   - react-tester.md         Jest + RTL testing
   - tailwind.md             Tailwind CSS styling

🎯 Generated skills (in docs/skills/):
   - auth-flow/              Authentication patterns
   - tenant-context/         Multi-tenant isolation
   - api-patterns/           API endpoint conventions
   - crud-patterns/          Entity CRUD operations
   (Skills are generated based on detected capabilities)

📝 Next steps (default):
  1. Start PRD kickoff now with @planner to define project scope
  2. Include architecture options/tradeoffs in the PRD as part of scope definition
  3. Move PRD to ready
  4. Start implementation with @builder

💡 Infrastructure conventions collected:
   - Network/HTTP: <summary of what was configured>
   - Security: <auth middleware, CSRF, validation>
   - AWS: <services, local dev, IaC tool>
   - API Design: <pagination, response envelope>
   - Testing: <locations, mocking conventions>

💡 The ARCHITECTURE.md and CONVENTIONS.md files have placeholders 
   marked with <!-- BOOTSTRAP NOTE: ... --> comments. Fill these in 
   to help AI agents better understand your codebase.

═══════════════════════════════════════════════════════════════════════

For Spec-Driven New Projects

═══════════════════════════════════════════════════════════════════════
                      PROJECT CREATED FROM SPEC
═══════════════════════════════════════════════════════════════════════

✅ Analyzed: Your project spec/PRD
✅ Selected: <Archetype Name> stack
✅ Created:  <project-path>/

Files generated:
  docs/project.json          Project manifest
  docs/requirements.json     Extracted requirements
  docs/stack-decision.json   Stack selection rationale
  docs/drafts/prd-mvp.md     Initial PRD with <N> user stories
  docs/prd-registry.json     PRD registry
  docs/session-locks.json    Session coordination
  docs/ARCHITECTURE.md       Architecture overview
  docs/CONVENTIONS.md        Coding conventions
  docs/agents/               Project-specific agents
  docs/skills/               Project-specific skills
  AGENTS.md                  Quick reference

Stack selected:
  Frontend:   <frontend>
  Backend:    <backend>
  Database:   <database>
  Auth:       <auth>
  Hosting:    <hosting>

📦 Generated agents (in docs/agents/):
   - typescript-critic.md    TypeScript code review
   - react-dev.md            React/Next.js patterns
   - react-tester.md         Jest + RTL testing
   - tailwind.md             Tailwind CSS styling
   - playwright-tester.md    E2E testing

🎯 Generated skills (in docs/skills/):
   - <list based on detected capabilities>
   (e.g., auth-flow, api-patterns, crud-patterns)

Project "<Name>" is ready for development!

📝 Next steps (default):
  1. Continue PRD kickoff with @planner to lock scope + architecture direction
  2. Move PRD to ready: @planner move prd-mvp to ready
  3. Start implementation: @builder (will claim the ready PRD)

💡 The PRD contains <N> user stories extracted from your spec.
   Use @planner to refine acceptance criteria before building.

═══════════════════════════════════════════════════════════════════════

For Manual New Projects

═══════════════════════════════════════════════════════════════════════
                      PROJECT CREATED
═══════════════════════════════════════════════════════════════════════

✅ Created: <project-path>/
✅ Stack:   <selected stack summary>

Files generated:
  docs/project.json          Project manifest
  docs/prd-registry.json     PRD registry
  docs/session-locks.json    Session coordination
  docs/ARCHITECTURE.md       Architecture overview
  docs/CONVENTIONS.md        Coding conventions
  docs/agents/               Project-specific agents
  docs/skills/               Project-specific skills
  AGENTS.md                  Quick reference

📦 Generated agents (in docs/agents/):
   - <list based on selected stack>

🎯 Generated skills (in docs/skills/):
   - <list based on detected capabilities>

Project "<Name>" is ready!

📝 Next steps (default):
  1. Start PRD kickoff with @planner to define project scope
  2. Add architecture recommendations in the PRD
  3. Move PRD to ready and start implementation with @builder

═══════════════════════════════════════════════════════════════════════

Error Handling

Path doesn't exist

❌ Path not found: ~/code/nonexistent

Please check the path and try again.

Not a git repo (and user declines init)

⚠️  Project must be a git repository for agent coordination.

You can:
  A. Let me initialize git now
  B. Cancel and initialize manually

> _

project.json already exists

⚠️  This project already has docs/project.json

What would you like to do?
  A. Overwrite with fresh detection
  B. Keep existing and just add to registry
  C. Cancel

> _

Quick Mode

For experienced users, support a quick mode:

# In the future, could support:
# @bootstrap /path/to/project --quick

This would:

1. Auto-detect everything possible
2. Use sensible defaults for unknowns
3. Skip all confirmation prompts
4. Generate files immediately

Output

Return a summary of what was created and the path to the project, so the calling agent can proceed with displaying the status dashboard.