opencode-onboard 0.4.4 → 0.4.7

package/content/AGENTS.md

@@ -6,13 +6,36 @@
 
 ## Trigger
 
-When the user says anything resembling initialization, "init", "initialize", "setup", "start", "bootstrap", "get started", "prepare", execute all steps below in order. Do not ask for confirmation before starting.
+When the user says anything resembling initialization, "init", "initialize", "setup", "start", "bootstrap", "get started", "prepare", execute the steps below. Follow the greenfield/brownfield branching exactly.
 
 ---
 
 ## Initialization Sequence
 
-### Step 1, Archive project history into OpenSpec
+### Step 1, Detect project type
+
+Ask the user exactly this question before doing anything else:
+
+> "Is this a **greenfield** project (starting from scratch, little or no existing code) or a **brownfield** project (existing codebase)?"
+>
+> - Reply **greenfield** to skip architecture/design/history analysis
+> - Reply **brownfield** to generate docs from your existing code
+
+Wait for the answer. Then follow the matching path below.
+
+---
+
+### Greenfield path
+
+Skip steps 2, 3, and 4. Jump directly to Step 5.
+
+Greenfield note: `ARCHITECTURE.md` and `DESIGN.md` are left as placeholders. Run `/ob-create-architecture` and `/ob-create-design` once the codebase has meaningful content.
+
+---
+
+### Brownfield path
+
+#### Step 2, Archive project history into OpenSpec
 
 Scan the codebase for any existing documentation, changelogs, ADRs, README files, or notable history that describes decisions already made in this project. Create an OpenSpec archive entry that captures this history so agents have context going forward.
 
@@ -35,37 +58,23 @@ openspec archive "project-history"
 
 ---
 
-### Step 2, Generate DESIGN.md
+#### Step 3, Generate ARCHITECTURE.md
 
-`DESIGN.md` contains a prompt. You MUST follow this exact sequence, do not skip or reorder steps:
-
-1. **Read `DESIGN.md` now** using a file read tool. The file contains a prompt with instructions and an output format.
-2. **Store the full prompt text** in your context.
-3. **Overwrite `DESIGN.md` with an empty string** (zero bytes). Do this before generating any content.
-4. **Analyze the actual codebase**: use `.agents/source-roots.json` as source roots when present, then read CSS files, Tailwind config, component files, token definitions. Do not rely on prior knowledge, read the files.
-5. **Write the result into `DESIGN.md`** following exactly the format and sections described in the stored prompt.
-
-The output must be a real, populated `DESIGN.md` based on what you found in the codebase, not from memory or assumptions.
+Run `/ob-create-architecture` now. Follow every step defined in that command.
 
 ---
 
-### Step 3, Generate ARCHITECTURE.md
-
-`ARCHITECTURE.md` contains a prompt. You MUST follow this exact sequence, do not skip or reorder steps:
+#### Step 4, Generate DESIGN.md
 
-1. **Read `ARCHITECTURE.md` now** using a file read tool. The file contains a prompt with instructions and an output format.
-2. **Store the full prompt text** in your context.
-3. **Overwrite `ARCHITECTURE.md` with an empty string** (zero bytes). Do this before generating any content.
-4. **Analyze the actual codebase**: use `.agents/source-roots.json` as source roots when present, then read folder structure, config files, route definitions, data models, integration points. Do not rely on prior knowledge, read the files.
-5. **Write the result into `ARCHITECTURE.md`** following exactly the format and sections described in the stored prompt.
-
-The output must be a real, populated `ARCHITECTURE.md` based on what you found in the codebase, covering all sections the prompt describes.
+Run `/ob-create-design` now. Follow every step defined in that command.
 
 ---
 
-### Step 4, Populate OpenSpec config
+### Step 5, Populate OpenSpec config
+
+Write `openspec/config.yaml` with real project information. For greenfield projects, use what little is known (language choice, intended stack, domain). For brownfield, use what was discovered in steps 2–4.
 
-Write `openspec/config.yaml` with the real project information discovered during steps 1-3. Overwrite whatever is currently in the file. The output must contain `schema: spec-driven` and a populated `context:` block. Do not leave placeholder text.
+The output must contain `schema: spec-driven` and a populated `context:` block. Do not leave placeholder text.
 
 ```yaml
 schema: spec-driven
@@ -78,19 +87,19 @@ context: |
   Domain: <what this project does, in one line>
 ```
 
-Replace every `<…>` with real values from the codebase. Add a `rules:` section only if the codebase has clear conventions worth enforcing (e.g., max task size, proposal format). Do not invent rules that aren't evidenced by the codebase.
+Replace every `<…>` with real values. Add a `rules:` section only if the codebase has clear conventions worth enforcing. Do not invent rules that aren't evidenced by the codebase.
 
 ---
 
-### Step 5, Rewrite this file
+### Step 6, Rewrite this file
 
 Replace the entire contents of this file (`AGENTS.md`) with everything below the line `<!-- AGENTS-TEMPLATE-START -->` in this same file. Delete the bootstrap section and the template marker, the file should contain only the template content when done.
 
 ---
 
-### Step 6, Confirm
+### Step 7, Confirm
 
-Tell the user:
+For **brownfield**, tell the user:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -110,6 +119,28 @@ Nothing will work correctly until you do.
 After restarting you are ready to work.
 ```
 
+For **greenfield**, tell the user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Initialization complete (greenfield).
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- openspec/config.yaml populated
+- AGENTS.md updated with real guidance
+- ARCHITECTURE.md and DESIGN.md left as placeholders
+
+Once your codebase has meaningful content, run:
+  /ob-create-architecture   → generate architecture docs
+  /ob-create-design         → generate design system docs
+
+!! RESTART OPENCODE NOW !!
+
+Quit and reopen OpenCode before doing anything else.
+Nothing will work correctly until you do.
+After restarting you are ready to work.
+```
+
 ---
 
 ## Guardrails During Init
@@ -143,9 +174,10 @@ Source scope is defined by mandatory `ob-global` skill.
 - Follow the generated `## Source Roots` section from that skill.
 - Do not duplicate source-scope rules here.
 
-## I Am the Lead, Full Workflow Ownership
-
-When the user provides a work item URL or says "implement the plan" or "I've added comments to the PR", **I own the full lifecycle**. I load `ob-global` skill first, then the appropriate userstory skill, and use ensemble tools to coordinate the agent team.
+## I Am the Lead, Full Workflow Ownership
+
+<!-- OB-PLATFORM-WORKFLOW-START -->
+When the user provides a work item URL or says "implement the plan" or "I've added comments to the PR", **I own the full lifecycle**. I load `ob-global` skill first, then the appropriate userstory skill, and use ensemble tools to coordinate the agent team.
 
 Trigger patterns, I recognize ALL of these, exact wording does not matter:
 - User pastes or mentions a GitHub Issue URL → load `ob-userstory-gh` skill → parse issue → run `/opsx-propose` → confirm with user → run `/opsx-apply` → ship
@@ -154,9 +186,20 @@ Trigger patterns, I recognize ALL of these, exact wording does not matter:
 - `I've added comments to the PR` → read PR comments → fix → update PR
 - Any GitHub/Azure DevOps PR URL in a feedback/fix request (e.g. "check comments", "fix PR feedback") → run PR Feedback Loop
 
-**A GitHub or Azure DevOps URL anywhere in the user's message is always a trigger, regardless of surrounding words.**
-
-**Never delegate without a plan. Never write implementation code directly, always spawn specialists, no exceptions. "Small feature", "faster to do it directly", or "environment issues" are not valid reasons to skip ensemble.**
+**A GitHub or Azure DevOps URL anywhere in the user's message is always a trigger, regardless of surrounding words.**
+<!-- OB-PLATFORM-WORKFLOW-END -->
+
+**Never delegate without a plan. Default to specialists for implementation. If ensemble is clearly non-functional in the current session (idle teammate, no claim, or repeated spawn failure after one retry), stop forcing it: report the failure, then continue in the main session or ask the user whether to retry later.**
+
+## Engineer Selection
+
+Before spawning implementation workers:
+- Inspect `.agents/agents/*.md` and build the list of engineers that actually exist in this project.
+- Exclude `devops-manager` from implementation selection.
+- Prefer the most specialized custom engineer whose description and abilities clearly match the task domain.
+- Use `basic-engineer` only when no custom engineer is a clear fit or as a recovery fallback.
+- Never spawn engineer names that are not present in `.agents/agents/`.
+- When multiple engineers could fit, choose the narrower specialist before the generalist.
 
 ## Multi-Agent Execution, opencode-ensemble
 
@@ -171,11 +214,14 @@ Core tools used in this workflow:
 **Dashboard**: Monitor running agents at **http://localhost:4747/**
 
 **Hard limits:**
+- **Sequential by default.** Default `{{MAX_CONCURRENT_AGENTS}}` to `1`. Raise only when tasks are provably independent and user approves. More concurrency = more tokens burned in parallel.
 - **Max {{MAX_CONCURRENT_AGENTS}} truly concurrent agents.** All {{MAX_CONCURRENT_AGENTS}} must be spawned and running simultaneously, not sequentially. Spawn in waves if more than {{MAX_CONCURRENT_AGENTS}} are needed. Wait for wave N to finish before spawning wave N+1.
 - **Non-overlapping file domains.** Each agent owns exclusive directories. Two agents must NEVER touch the same file.
 - **Immediate shutdown on completion.** The moment an agent's domain has no more pending tasks → `team_shutdown` → `team_merge`. Keep agents alive if more tasks in their domain are pending (rolling batch).
-- **Rolling batch assignment.** Agents receive up to 3 tasks initially. When they complete a batch, lead assigns the next batch of up to 3 from the board. Never leave pending tasks orphaned.
-- **Stall detection at 5 minutes.** No commits after 5 min → nudge message → 2 min grace → force shutdown + respawn.
+- **Rolling batch assignment.** Agents receive up to 3 tasks initially. When they complete a batch, lead assigns the next batch of up to 3 from the board. Never leave pending tasks orphaned.
+- **Stall detection at 5 minutes.** No commits after 5 min → nudge message → 2 min grace → force shutdown + respawn.
+- **Idle-without-claim is an earlier stall.** If a spawned teammate sits idle with no claimed task after a short wait, resend one short claim-only message with the exact task IDs. If still idle, force shutdown + respawn once with a shorter prompt. If the retry repeats the same failure, treat ensemble as unavailable for that session and stop recycling equivalent workers.
+- **Retry limit.** Max 3 retries per failing task → stop-and-report to user. Never retry indefinitely.
 
 **Progress inspection commands (tell user explicitly after spawning):**
 - `team_status` for live team snapshot
@@ -190,11 +236,12 @@ If a teammate stalls due to model quota/rate-limit exhaustion:
 
 ---
 
-## Pipeline
-
-```
-devops-manager (lead mode)
-  → load ob-global + parse work item via skill
+## Pipeline
+
+<!-- OB-PLATFORM-PIPELINE-START -->
+```
+devops-manager (lead mode)
+  → load ob-global + parse work item via skill
         ↓
   openspec-propose
   → proposal.md + specs + tasks
@@ -221,13 +268,17 @@ devops-manager (ship mode)
 ### Phase 2, Implement
 
 ```
-1. Run /opsx-apply.
-   - Lead adds all tasks to board.
-   - Lead spawns engineers with initial batch of up to 3 tasks each (rolling batch model).
+0. Run /quota to check remaining budget before spawning.
+1. Run /opsx-apply.
+   - Step 5b: classify cost tier, announce scope, ask user to confirm if ≥4 tasks.
+   - Lead adds all tasks to board.
+   - When dependencies exist, lead uses multiple `team_tasks_add` waves so later tasks can reference real task IDs returned by earlier waves.
+   - Lead discovers available engineers from `.agents/agents/*.md`, prefers matching custom engineers, then spawns engineers with initial batch of up to 3 tasks each (rolling batch model).
    - Each engineer claims tasks, implements, completes, messages lead.
    - Lead assigns next batch (up to 3) to agents that report done. Repeat until board empty.
    - Lead merges each engineer branch after shutdown, then marks tasks done in tasks.md.
 2. Verify with tests/build/lint according to task scope.
+3. Run /quota after all agents are merged.
 ```
 
 ### Phase 3, Ship
@@ -255,9 +306,10 @@ When user says "I've added comments to the PR" or asks to fix PR comments from P
 6. Wait for engineer results → team_shutdown + team_merge per engineer
 7. Run verification tasks (tests/build/lint) and fix blockers if any
 8. team_spawn devops-manager (ship mode) with "push + update PR threads" task ID + team_message "Start now"
-9. Wait → team_results → report what was updated
-10. team_cleanup
-```
+9. Wait → team_results → report what was updated
+10. team_cleanup
+```
+<!-- OB-PLATFORM-PIPELINE-END -->
 
 ---
 
@@ -270,7 +322,7 @@ All agents are universal, no project-specific knowledge. Platform and tech knowl
 | `devops-manager` | .agents/agents/devops-manager.md | Reads work items, creates PRs, handles review feedback |
 | `basic-engineer` | .agents/agents/basic-engineer.md | Generic implementation worker using ability-loaded skills |
 
-User can add more custom engineer agents and run them in parallel. Keep behavior ability-driven via skill mappings.
+User can add more custom engineer agents and run them in parallel. Keep behavior ability-driven via skill mappings. Custom engineers are the primary specialization mechanism; `basic-engineer` is the general fallback when no custom engineer is a clear fit.
 
 Default `basic-engineer` abilities:
 
@@ -284,7 +336,7 @@ Default `basic-engineer` abilities:
 
 ## Skills
 
-Skills provide platform and tech-specific knowledge. Agents detect and load them automatically, **you never tell an agent which skill to use**.
+Skills provide platform and tech-specific knowledge. Agents usually detect and load them automatically. Prefer auto-detection, but explicitly naming a skill in a spawn prompt is allowed when a workflow requires it or repeated misses show the agent is not loading the right context.
 
 `ob-global` is always loaded first, it provides baseline rules for all agents.
 
@@ -356,6 +408,66 @@ Minimal non-negotiables:
 - Use `gh`/`az` CLI for platform operations.
 - In multi-repo source scope, run git operations per repository.
 
+### Config file conflict: `opencode.jsonc` vs `.opencode/opencode.json`
+
+This project uses `.opencode/opencode.json` as the single OpenCode configuration file. Some tools (e.g., codegraph) may create an `opencode.jsonc` file at the project root. **These two files cannot coexist.**
+
+If you detect both `opencode.jsonc` (project root) and `.opencode/opencode.json` exist:
+1. **Stop immediately** and warn the user: "Conflicting OpenCode config files detected. This project uses `.opencode/opencode.json` only. The root `opencode.jsonc` must be removed or its contents merged into `.opencode/opencode.json`."
+2. Do NOT proceed with any task until the conflict is resolved.
+3. If the user asks you to fix it: merge any `mcpServers` or other config from `opencode.jsonc` into `.opencode/opencode.json`, then delete `opencode.jsonc`.
+
+---
+
+## Token Budget & Safety
+
+Prevent runaway token spend from unattended sessions. Apply in this priority order.
+
+### 1. Provider-side caps (primary safety layer)
+
+Set monthly soft-limit + hard usage cap in your provider dashboard **before** running any agent session:
+- **OpenAI**: [platform.openai.com/account/limits](https://platform.openai.com/account/limits)
+- **Anthropic**: [console.anthropic.com](https://console.anthropic.com)
+- **Google AI Studio**: [aistudio.google.com/app/usage](https://aistudio.google.com/app/usage)
+
+Provider caps are the only guarantees that survive agent bugs, infinite loops, or runaway retries.
+
+### 2. Model-cost routing
+
+| Task type | Model tier |
+|-----------|-----------|
+| Orchestration loops, task classification, status checks, PR parsing, triage | Fast / cheap (e.g. `haiku`, `gpt-4o-mini`) |
+| Implementation, code review, hard reasoning | Expensive (e.g. `sonnet`, `opus`, `gpt-4o`) |
+
+devops-manager orchestrates — use fast model for it. Engineers implement — use expensive model there only.
+
+### 3. Sequential-by-default concurrency
+
+Default: **1 agent at a time**. Set `{{MAX_CONCURRENT_AGENTS}}` to `1` unless tasks are provably independent and the user approves higher concurrency. More agents = more tokens burned in parallel; slow down unless scope justifies it.
+
+### 4. Retry limits
+
+Max **3 retries** per failing task. On the third failure:
+1. Shut down the stuck agent.
+2. Summarize what failed and why.
+3. Stop — wait for user guidance before retrying.
+
+Never silently retry indefinitely. Repeated failures = a design problem, not a retry problem.
+
+### 5. Inactivity and time cutoffs
+
+- **No commits after 10 minutes** of cumulative agent runtime → auto-stop, summarize blockers to user.
+- **Max 1 hour** total runtime per `/opsx-apply` session → stop and report at the limit, regardless of remaining tasks.
+
+### 6. Quota checkpoints
+
+Use the `opencode-quota` plugin (`/quota` command) to surface real-time token usage:
+- Run `/quota` at **session start** (before spawning any agents) and **after each agent wave**.
+- "When to stop" thresholds:
+  - **50% consumed** → review remaining scope; consider reducing
+  - **75% consumed** → pause; summarize completed work; ask user whether to continue
+  - **90% consumed** → stop immediately; ship what's done; open follow-up change for remainder
+
 ---
 
 ## Communication Style

package/content/ARCHITECTURE.md

@@ -1,327 +1,16 @@
-> Execute this command.
-
-Analyze the architecture of this codebase with the goal of creating an ARCHITECTURE.md file in the project root and giving the user a file for easy copy & pasting.
-
-Reference material:
-  Website : https://architecture.md/
-  Repo    : https://github.com/timajwilliams/architecture
-
-Requirements:
-- Create a complete ARCHITECTURE.md document that enables rapid codebase comprehension for both human developers and AI agents.
-- The file must be entirely self-contained. Do not say “see X file” as a substitute for explanation; include the relevant architectural facts directly in the document.
-- Be specific and concrete: include actual directories, important files, modules, services, classes, APIs, commands, data stores, configuration points, and integration boundaries where they are discoverable from the codebase.
-- Do not invent systems, services, infrastructure, deployment targets, databases, queues, third-party APIs, or security mechanisms that are not supported by evidence in the repository.
-- When something cannot be determined from the codebase, explicitly mark it as “Not evident from the repository” rather than guessing.
-- Prefer durable architectural facts over transient implementation details. Focus on things that help someone understand where to make changes and how the system fits together.
-- Include diagrams using Mermaid where helpful, especially for system context, component relationships, request/data flow, and deployment topology.
-- If Mermaid is not appropriate or the architecture is simple, include a clear text-based diagram instead.
-- If architecture decisions or tradeoffs are visible from the code, document the rationale and consequences.
-- Include technical debt, risks, unclear boundaries, and future architecture considerations when supported by TODOs, comments, docs, issue references, or code structure.
-- Use Markdown only. Do not rely on external images, generated assets, or links to local files.
-- Write the document as if it will be committed to the repository and maintained over time.
-
-Recommended ARCHITECTURE.md structure:
-
-# Architecture Overview
-
-Briefly describe what the system is, what problem it solves, who/what uses it, and the major architectural style or pattern if evident.
-
-## 1. Project Structure
-
-Provide a high-level annotated tree of the repository. Explain the purpose of each major directory and the architectural layer or concern it represents.
-
-Include:
-- Root-level files that affect architecture, build, runtime, deployment, or developer workflow
-- Source directories and their responsibilities
-- Test directories and their scope
-- Configuration, scripts, generated code, migrations, schemas, or infrastructure directories if present
-
-## 2. High-Level System Diagram
-
-Provide a Mermaid diagram or text diagram showing the major actors, applications, services, data stores, and external systems.
-
-The diagram should emphasize:
-- User or client entry points
-- Application/runtime boundaries
-- Internal services or modules
-- Data stores
-- External APIs or platforms
-- Direction of communication/data flow
-
-## 3. Core Components
-
-Describe each major component of the system.
-
-For each component include:
-- Name
-- Responsibility
-- Important files/directories
-- Key technologies/frameworks
-- Runtime role
-- Main inputs and outputs
-- Dependencies on other components
-- Notes about ownership of business logic, state, or side effects
-
-Use subsections such as:
-
-### 3.1 Frontend / User Interface
-
-If present, document:
-- Framework and rendering model
-- Routing/page structure
-- State management
-- API/data access pattern
-- Component organization
-- Styling/design-system approach if architecturally relevant
-- Build output and deployment assumptions
-
-### 3.2 Backend / Server / API
-
-If present, document:
-- Framework/runtime
-- Entry points
-- Routing/controller structure
-- Service/business-logic layer
-- Persistence layer
-- Middleware
-- Authentication/authorization flow
-- Background jobs/workers if present
-
-### 3.3 Shared Libraries / Common Code
-
-If present, document:
-- Shared types
-- Utilities
-- Domain models
-- Validation schemas
-- Cross-cutting abstractions
-
-### 3.4 CLI / Scripts / Automation
-
-If present, document:
-- Command entry points
-- Build/test/deploy automation
-- Code generation
-- Data seeding/migration scripts
-
-## 4. Data Flow
-
-Explain how data moves through the system.
-
-Include:
-- Main request lifecycle
-- Important user journeys or system workflows
-- Read/write paths
-- Validation boundaries
-- Serialization/deserialization points
-- Error handling paths
-- Async/event-driven flows if present
-
-Add a Mermaid sequence diagram for the most important runtime flow when possible.
-
-## 5. Data Stores
-
-List and describe all persistent or semi-persistent storage mechanisms evident in the codebase.
-
-For each data store include:
-- Name
-- Type/technology
-- Purpose
-- Main schemas/tables/collections/entities if discoverable
-- Ownership boundaries
-- Migration or schema management approach
-- Backup, retention, or lifecycle details if evident
-
-If no persistent storage is evident, say so.
-
-## 6. External Integrations / APIs
-
-Document all external systems the codebase integrates with.
-
-For each integration include:
-- Service name
-- Purpose
-- Integration method, such as REST, GraphQL, SDK, webhook, OAuth, file import/export, message queue
-- Where it is configured or called
-- Authentication method if evident
-- Failure/retry behavior if evident
-
-## 7. Key Technologies
-
-Summarize the technical stack.
-
-Include:
-- Languages
-- Frameworks
-- Runtime/platform
-- Package managers
-- Build tools
-- Testing tools
-- Linters/formatters
-- Infrastructure/deployment tools
-- Observability tools
-- Important libraries that shape the architecture
-
-Explain why each technology matters architecturally, not just that it exists.
-
-## 8. Deployment & Infrastructure
-
-Describe how the system appears to be built, packaged, configured, and deployed.
-
-Include:
-- Build artifacts
-- Environment variables/configuration model
-- Containerization if present
-- Hosting/deployment target if evident
-- CI/CD workflows
-- Infrastructure-as-code
-- Runtime process model
-- Scaling assumptions if evident
-
-If deployment is not evident from the repository, state that clearly and summarize what would need to be known.
-
-## 9. Security Architecture
-
-Document security-relevant architecture.
-
-Include:
-- Authentication
-- Authorization
-- Session/token handling
-- Secrets management
-- Input validation
-- Data encryption in transit/at rest if evident
-- CORS/CSP/security headers if present
-- Dependency or supply-chain security measures
-- Trust boundaries
-- Sensitive data handling
-
-Do not claim security controls exist unless the codebase shows them.
-
-## 10. Monitoring & Observability
-
-Document how the system can be debugged and observed.
-
-Include:
-- Logging approach
-- Metrics
-- Tracing
-- Error reporting
-- Health checks
-- Audit logs
-- Debug tooling
-- Operational dashboards or monitoring services if evident
-
-If observability is minimal or absent, say so and identify the current gaps.
-
-## 11. Performance & Scalability
-
-Document performance-sensitive parts of the architecture.
-
-Include:
-- Caching
-- Pagination
-- Batching
-- Background processing
-- Database query patterns
-- Asset optimization
-- Concurrency model
-- Known bottlenecks
-- Scaling limits or assumptions
-
-Only include claims supported by code, configuration, or documentation.
-
-## 12. Development Workflow
-
-Explain how developers work with the project.
-
-Include:
-- Local setup
-- Required tools/runtime versions
-- Install commands
-- Development server commands
-- Test commands
-- Build commands
-- Lint/format/typecheck commands
-- Database setup/migrations if present
-- Common development loops
-
-Keep this section architecture-focused; do not duplicate a README unless the workflow affects system structure.
-
-## 13. Testing Strategy
-
-Describe the testing architecture.
-
-Include:
-- Test frameworks
-- Unit/integration/e2e test locations
-- Fixtures/mocks
-- Test data strategy
-- CI test execution
-- Coverage or quality gates if evident
-- Gaps in test coverage if inferable from the repository
-
-## 14. Architectural Decisions & Rationale
-
-Capture important architectural choices visible in the codebase.
-
-For each decision include:
-- Decision
-- Evidence in the codebase
-- Rationale if inferable
-- Consequences/tradeoffs
-- Alternatives if mentioned in docs/comments
-
-Do not invent historical rationale. If rationale is unclear, say “Rationale not documented.”
-
-## 15. Constraints, Risks, and Technical Debt
-
-Document:
-- Architectural constraints
-- Known limitations
-- Tight coupling
-- Duplicated abstractions
-- Missing boundaries
-- Incomplete migrations
-- TODO/FIXME items with architectural impact
-- Operational risks
-- Security or scalability concerns
-
-Each item should include why it matters and where the evidence appears in the codebase.
-
-## 16. Future Considerations / Roadmap
-
-Summarize future architectural changes that are evident from code comments, docs, TODOs, roadmap files, or incomplete abstractions.
-
-Separate:
-- Explicitly documented future work
-- Reasonable architectural recommendations based on current structure
-
-Clearly label recommendations as recommendations.
-
-## 17. Project Identification
-
-Include:
-- Project name
-- Repository purpose
-- Primary language(s)
-- Application type
-- Main runtime(s)
-- Date of last architecture review
-- Maintainer/team if evident
-
-Use today’s date for “Date of last architecture review.”
-
-## 18. Glossary / Acronyms
-
-Define project-specific terms, acronyms, domain concepts, and internal names that a new developer or AI agent needs to know.
-
-Validation pass:
-- Verify every named component, service, data store, integration, and technology against the repository.
-- Remove placeholders.
-- Remove generic template text.
-- Replace vague statements with concrete codebase-specific facts.
-- Ensure every major source directory is represented somewhere in the document.
-- Ensure the high-level diagram matches the written component descriptions.
-- Ensure the document is useful to someone trying to answer: “Where do I make a change, and what will it affect?”
-- If access to a running local server, tests, build output, generated docs, API schema, database schema, Docker environment, or screenshots is available, use them to validate and revise the architecture description.
+> NOT GENERATED YET
+>
+> This file has not been populated yet. It is intentionally empty.
+>
+> **If this is a greenfield project** (no codebase exists yet): skip this for now.
+> Come back and run `/ob-create-architecture` once you have meaningful code, structure, or infrastructure in place.
+>
+> **If this is a brownfield project** (existing codebase): run this command now to generate the architecture documentation:
+>
+> ```
+> /ob-create-architecture
+> ```
+>
+> This command analyzes your folder structure, config files, routes, data models, integrations, and build setup,
+> then writes a complete ARCHITECTURE.md covering components, data flow, tech stack, deployment, and more.
+> It is safe to rerun any time the architecture changes significantly.