brainstorm

8 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

• skills/brainstorm/SKILL.md9.3 KB242292b19cd4upstream ↗

  ---
  description: >-
    Runs a structured design conversation — clarifies intent, proposes 2-3 approaches
    with trade-offs, iterates the design — and writes a user-approved engineering spec
    to docs/specs/ that /optimus:tdd auto-detects. No implementation happens until the
    spec is approved. With the scaffold argument, creates docs/product/ steering
    skeletons instead (never overwrites, authors no content). Recommends /optimus:init first.
  disable-model-invocation: true
  argument-hint: "[topic, JIRA key, or scaffold]"
  ---
  
  # Brainstorm
  
  Guide the user through a design conversation that produces a written, approved spec before any implementation begins.
  
  **The hard gate: no implementation until the design is approved.** Do not invoke an implementation skill, write production code, or scaffold project structure until a spec is written and the user has approved it — even for seemingly simple tasks.
  
  Resolve the target repo first: if `git rev-parse --is-inside-work-tree` does not return `true`, read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` and apply it — in a workspace, operate in the repo the user targets, asking which if ambiguous. Otherwise use `git rev-parse --show-toplevel`, including in a linked worktree or subdirectory. Both modes resolve paths from that root.
  
  ## Scaffold mode
  
  When invoked with the `scaffold` argument, or when the user asks to set up the docs-first steering cascade, run this flow instead of the design conversation:
  
  1. Scaffold in the resolved repo root — a cascade outside the target repo never auto-loads as steering.
  2. For each of `docs/product/product-context.md`, `mvp-prd.md`, and `tech-stack.md`: if it exists, never overwrite — skip it. If missing, copy the matching file from `$CLAUDE_PLUGIN_ROOT/skills/brainstorm/templates/product/` verbatim, creating `docs/product/` if needed. Write nothing else — no `docs/specs/` file (the design flow authors that later), nothing under `.claude/`.
  3. **Emit skeletons with TODO markers only — author no product content (no personas, KPIs, business-value prose, or technology choices) and never fill a TODO; that is the human's job.**
  4. Report created vs skipped files. Tell the user to fill the TODOs top-down (vision → MVP PRD → target stack), then run `/optimus:brainstorm` in a fresh conversation to design the first build.
  
  ## Step 1: Pre-flight
  
  If `.claude/CLAUDE.md` or `.claude/docs/coding-guidelines.md` is missing, recommend `/optimus:init` first; on the user's choice, continue with general best practices.
  
  Load `.claude/CLAUDE.md` and `.claude/docs/coding-guidelines.md`, plus — only if present — the steering cascade `docs/product/product-context.md`, `mvp-prd.md`, and `tech-stack.md`. Steering informs the design; it is never the task itself or content to copy. Authoring boundary and precedence: `$CLAUDE_PLUGIN_ROOT/references/sdd-mapping.md`. In a monorepo, load the subproject's own `docs/` files (testing, architecture, styling) and shared guidelines from the root `.claude/docs/`.
  
  Scan the project's directory structure, key modules, and existing patterns to ground the conversation in what actually exists.
  
  ## Step 2: Gather Intent
  
  Check for JIRA context before prompting the user:
  
  1. Inline input containing a key matching `[A-Z][A-Z0-9]+-\d+` whose `docs/jira/<key>.md` exists → use that file's Goal and Acceptance Criteria as the brainstorm input. If the whole input is a bare key (`^[A-Z][A-Z0-9]+-\d+$`) with no such file, tell the user to run `/optimus:jira <KEY>` first, then gather intent normally.
  2. No inline input and `docs/jira/` contains `.md` files → pick the one with the newest frontmatter `description-refresh-date` and offer it via AskUserQuestion (Use it / Ignore), noting when that date is over 7 days old that re-running `/optimus:jira` refreshes it. **Use it** consumes the file's Goal and Acceptance Criteria and skips the prompts below.
  
  Otherwise use the inline description; if none, ask what to build or change. Distill input longer than ~3 sentences into a single-sentence goal and confirm it with the user.
  
  Surface your key assumptions about scope, constraints, and expected behavior in reply text before the first clarifying question. Then ask at most 3 clarifying questions — a maximum, not a target; one per AskUserQuestion call, preferring multiple-choice — and skip them entirely when intent is already clear.
  
  ## Step 3: Explore and Propose
  
  Explore the code the design will touch: relevant modules and conventions, dependencies and integration points, related tests. Then present 2-3 approaches (a third only if genuinely distinct), each with a name, a 2-3 sentence description, pros/cons, effort (Low / Medium / High), and alignment with existing patterns — plus a recommendation with a one-sentence rationale.
  
  The user selects via AskUserQuestion, one option per approach with the recommendation marked. If they want to combine aspects or redirect, incorporate the feedback and present a revised approach before proceeding.
  
  ## Step 4: Design
  
  Develop a detailed design covering the spec template sections in Step 5, omitting those that don't apply. Include Scenarios when any signal applies — JIRA Acceptance Criteria, an intent naming a user-visible flow (end-user, cross-team, or regulatory), or clarifying answers describing observable outcomes — and omit them for internal refactors, infrastructure changes, and developer-only tooling. When including them, first read `$CLAUDE_PLUGIN_ROOT/skills/brainstorm/references/scenario-style.md` for Given/When/Then discipline — `/optimus:tdd` consumes each scenario as one Red-Green-Refactor cycle.
  
  Present the design in conversation and iterate through an Approve / Adjust AskUserQuestion until the user approves.
  
  ## Step 5: Write the Spec
  
  Write to `docs/specs/YYYY-MM-DD-<topic-slug>.md` (lowercase hyphenated slug from the goal, max 5 words, matching `[a-z0-9]+(-[a-z0-9]+)*`; create `docs/specs/` if needed). If the file already exists, ask the user whether to overwrite or append a `-2`, `-3`, … suffix; on overwrite, carry any existing `### Refined plan` section into the new file — it holds plan-mode iteration. Keep the spec under 200 lines.
  
  ```markdown
  # Spec: <Title>
  
  **Date:** YYYY-MM-DD
  **Status:** Approved
  **Goal:** <single sentence — what and why>
  
  ## Context
  <Why the change is needed; relevant existing state.>
  
  ## Approach
  <How it works; key decisions and their rationale.>
  
  ## Components
  | Component | Responsibility | New / Modified |
  |-----------|----------------|----------------|
  
  ## Interfaces
  <How components interact — APIs, data flow, signatures. Skip for single-file changes.>
  
  ## Edge Cases and Risks
  | Risk | Mitigation |
  |------|------------|
  
  ## Scenarios
  <Conditional — 3-7 Given/When/Then scenarios per scenario-style.md; remove the section if none apply.>
  
  ### Scenario: <concrete user-observable outcome>
  **Given** <starting state in business language>
  **When** <single user action>
  **Then** <observable outcome>
  
  ## Out of Scope
  - <What this design explicitly does not cover>
  
  ## Open Questions
  - <Deferred decisions — remove if none>
  ```
  
  The spec ships with no TODOs or placeholders. If closing a gap would change a design decision the user approved, ask before changing it.
  
  ## Step 6: Report
  
  ```
  ## Design Complete
  
  **Spec:** `<spec-path>`
  **Goal:** <single-sentence goal>
  **Approach:** <chosen approach name>
  **Components:** <count> (<count> new, <count> modified)
  ```
  
  ## Step 7: Next Step
  
  Route by task type. Substitute the actual spec path into every recommendation and emitted block — `/optimus:refactor` and `/optimus:unit-test` do not read `docs/specs/` on their own. Recommend running the routed skill in a fresh conversation.
  
  | Task | Route |
  |------|-------|
  | Refactoring | `/optimus:refactor`, passing the scope and key decisions from `<spec-path>` as the scope argument |
  | Test-only | `/optimus:unit-test`, passing the target paths from `<spec-path>` |
  | Small implementation (1-2 components, <5 behaviors) | `/optimus:tdd` directly — it auto-detects the spec at `<spec-path>` |
  | Medium-to-large implementation | Plan-mode handoff below |
  | Prose deliverable (zero code components, or the goal names a written artifact) | Prose flow below |
  
  ### Plan-mode handoff (medium-to-large)
  
  Read `$CLAUDE_PLUGIN_ROOT/skills/brainstorm/references/plan-mode-handoff.md` and emit its **Prompt skeleton** as a copyable plan-mode prompt, filled from the spec with `<doc-path>` = `<spec-path>`, and closed with the carve-out's `## How this conversation should run` block.
  
  Under Codex, use that reference's **Codex handoff** branch instead of Claude's carve-out blocks/three toggle steps. Otherwise give the three carve-out steps. Emit the execution prompt as a second copyable block from the same skeleton.
  
  ### Prose flow
  
  `/optimus:tdd` does not apply — use the current host's prose flow from plan-mode-handoff.md. Emit the same plan-mode prompt, but close it with a `## How this conversation should run` section saying: iterate on the plan against the actual codebase; once authorized in a write-enabled conversation, produce the deliverable there; afterwards recommend the host's Optimus commit invocation in that same conversation so the implementation context is captured. For Claude Code, tell the user: start a fresh conversation in plan mode, paste the prompt, iterate, and approve the plan when satisfied; under Codex, give the reference's Codex handoff branch. Skip the execution prompt.
  

• skills/brainstorm/README.md4.1 KBb33696ec2001upstream ↗

  # optimus:brainstorm
  
  Guides structured design brainstorming — explores the codebase, asks clarifying questions, proposes 2-3 approaches with trade-offs, and writes a user-approved engineering spec to `docs/specs/YYYY-MM-DD-<slug>.md`. Enforces a hard gate: no implementation until the spec is approved, even for "simple" tasks.
  
  ## When to use
  
  Before implementing a new feature or significant change — especially when the work touches multiple components, multiple valid approaches exist, you want a persistent spec that survives conversation resets, or a JIRA ticket is too vague for direct implementation (brainstorm auto-detects JIRA context from `docs/jira/`).
  
  **When not:** simple, well-understood task → `/optimus:tdd` directly; pure refactoring → `/optimus:refactor`; quick prototyping → plan mode alone.
  
  ## What it does
  
  1. Loads project context, coding guidelines, and the optional `docs/product/` steering cascade
  2. Gathers intent — JIRA auto-detection, then up to 3 clarifying questions
  3. Proposes 2-3 approaches with trade-offs and a marked recommendation
  4. Iterates the design with you until approved
  5. Writes the approved spec, including a conditional Given/When/Then **Scenarios** section that `/optimus:tdd` maps to Red-Green-Refactor cycles
  6. Routes to the right next step (refactor, unit-test, TDD, or a plan-mode handoff)
  
  ## Scaffold mode
  
  `/optimus:brainstorm scaffold` bootstraps spec-driven development on a greenfield project: it creates `docs/product/product-context.md`, `mvp-prd.md`, and `tech-stack.md` as empty TODO skeletons for a human to fill (replacing the 2.x spec-init skill). It never overwrites existing files and authors no product content. Fill the TODOs top-down, then re-run `/optimus:brainstorm` — the design flow reads the cascade as steering. See [`references/sdd-mapping.md`](../../references/sdd-mapping.md) for the precedence contract.
  
  ## Recommended workflow
  
  | Situation | Workflow |
  |-----------|----------|
  | Small (1-2 components) | brainstorm → `/optimus:tdd` (auto-detects the spec) |
  | Medium-to-large | brainstorm → plan mode (review-only, do not approve) → `/optimus:tdd` |
  | From JIRA | `/optimus:jira` → brainstorm → plan mode → `/optimus:tdd` |
  | Greenfield product | brainstorm scaffold → fill the cascade → brainstorm |
  
  Brainstorm generates the plan-mode prompt inline — no separate `/optimus:prompt` step needed for this chain.
  
  Under Codex, the handoff uses its available plan/review controls and `$optimus:tdd`, with a copyable plan when the host cannot save it yet. Claude-specific toggle/approval instructions are not applied to Codex. The durable spec and `### Refined plan` heading are shared between hosts.
  
  ## Relationship to other skills
  
  | Skill | Relationship |
  |-------|--------------|
  | `/optimus:jira` | Brainstorm auto-detects task files in `docs/jira/` — run jira first for JIRA-tracked work |
  | `/optimus:tdd` | Auto-detects specs in `docs/specs/`; consumes each spec scenario as one Red-Green-Refactor cycle |
  | `/optimus:refactor` | For restructuring without new behavior, use refactor instead of brainstorm |
  | `/optimus:prompt` | For handoff prompts outside the brainstorm→plan→tdd chain |
  
  ## Prerequisites
  
  - `/optimus:init` should have been run (CLAUDE.md and coding guidelines inform design decisions); scaffold mode has no prerequisites
  
  ## Skill structure
  
  | File | Purpose |
  |------|---------|
  | `SKILL.md` | Design workflow, scaffold mode, and the spec template |
  | `references/scenario-style.md` | Given/When/Then discipline for the Scenarios section |
  | `references/plan-mode-handoff.md` | Plan-mode handoff procedure (shared — also read by `/optimus:jira` and `/optimus:prompt`) |
  | `templates/product/` | Steering-cascade skeletons emitted by scaffold mode |
  | *(shared)* `references/sdd-mapping.md` | Steering precedence and authoring boundary |
  | *(shared)* `init/references/multi-repo-detection.md` | Multi-repo workspace detection (only outside a Git working tree) |
  
  ## Requirements
  
  - A plugin-capable [Claude Code](https://code.claude.com/docs/en/plugins) or Codex host (see the [supported hosts and versions](../../README.md#supported-hosts-and-versions))
  
  ## License
  
  [MIT](../../LICENSE)
  

• skills/brainstorm/references/plan-mode-handoff.md4.8 KB9aab1b573ae0upstream ↗

  # Plan-mode handoff
  
  Shared procedure for skills that hand a design off through Claude Code's plan mode (`brainstorm`, `jira`, `prompt`). Owned by brainstorm.
  
  ## Codex handoff
  
  Under Codex, use this branch instead of the Claude-specific toggle/approval steps
  below. Keep the same Prompt skeleton and exact `### Refined plan` artifact heading,
  using `$optimus:tdd` in the execution prompt.
  
  Offer plan review in the host's available plan mode, or an ordinary conversation
  explicitly scoped to reviewing the plan without implementation. Do not prescribe
  Claude keyboard shortcuts, ExitPlanMode, or assume that approving a Codex plan
  dispatches a skill. After review, save the refined plan to the actual source path
  only in a write-enabled conversation with the user's authorization. If the host
  cannot save it yet, provide a copyable refined plan and execution prompt containing
  the unresolved decisions and source path; do not claim the file was updated.
  
  For implementation, give a copyable `$optimus:tdd` prompt referencing the approved
  plan in a fresh conversation. For prose, continue writing the approved deliverable
  when authorized, then recommend `$optimus:commit` in that conversation. Use the
  native host controls where available; the durable plan is the shared handoff.
  
  ## Plan-mode facts the handoff relies on
  
  - **Approving a plan executes it immediately in the same conversation.** That is the intended flow and the right default for most deliverables.
  - Plan mode is **read-only** — any file write ("append the refined plan") happens only after the user toggles plan mode off **and sends a follow-up message**; the toggle itself does not trigger Claude.
  - Plan mode is a **client UI toggle** (CLI: `Shift+Tab`; other clients: their equivalent control) — no phrase exits it. Describe the action client-agnostically. An "Ultraplan" approval option executes the plan — treat it like approval.
  
  ## Choosing the flow
  
  - **Default — prose deliverables, or any plan NOT routed to `/optimus:tdd`:** iterate in plan mode, then **approve the plan to implement in the same conversation**. After implementation, `/optimus:commit` and `/optimus:pr` should run in that same conversation so they can capture the implementation context.
  - **Carve-out — work routed to `/optimus:tdd`:** treat plan mode as **review-only**. Approval would execute immediately and bypass TDD's Red-Green-Refactor discipline. Use the canonical blocks below.
  
  ## Prompt skeleton
  
  Both the plan-mode prompt and the execution prompt use this shape. Fill each section from whatever source document the consuming skill holds (a `docs/specs/` spec, a `docs/jira/` task file), and substitute the real path so every pasted block is self-contained.
  
  ````
  ```
  ## Goal
  [Plan-mode prompt: the goal from the source document.
   Execution prompt: "Run /optimus:tdd to implement the refined plan in <doc-path> test-first."]
  
  ## Context
  [Plan-mode prompt only: key decisions, constraints, and the rationale for the chosen approach.
   Omit this section from the execution prompt.]
  
  ## Starting Hints
  - <doc-path>  [execution prompt: note that it now carries a "Refined plan" section]
  - [Key files, modules, or components the source document names]
  
  ## Scope
  - Focus on: [components or area from the source document]
  - Out of scope: [what the source document excludes]
  ```
  ````
  
  ## Carve-out canonical blocks
  
  Close the generated plan-mode prompt with this section, substituting `<doc-path>` with the actual spec/task file path. The `### Refined plan` heading is exact — jira's refresh and enrichment procedures preserve that section by that literal string:
  
  ```
  ## How this conversation should run
  Treat this conversation as a review loop — validate the plan against the actual codebase and iterate with me. When I say I'm done iterating, acknowledge but do not write yet — plan mode is read-only. I will then toggle plan mode off and send a short follow-up message (e.g. "go"). On that follow-up, append a `### Refined plan` section (heading exactly `### Refined plan`) to `<doc-path>` to capture the refined plan, and stop. I will start a fresh conversation to run `/optimus:tdd`.
  ```
  
  After presenting the prompt, tell the user these three steps (substituting `<doc-path>`):
  
  > 1. Start a fresh Claude Code conversation in **plan mode** (CLI: press `Shift+Tab` until the mode indicator shows plan mode; other clients: use the equivalent toggle). Paste the prompt above.
  > 2. Iterate with Claude. **Do not approve the plan** — approval executes immediately and skips `/optimus:tdd`'s Red-Green-Refactor discipline. When you're satisfied, tell Claude you're done iterating; Claude will acknowledge. Then toggle plan mode off using the same control **and send a short follow-up message (e.g. "go")** — Claude will append a `### Refined plan` section to `<doc-path>` in response.
  > 3. Start a **second fresh conversation** and paste the execution prompt below.
  

• skills/brainstorm/references/scenario-style.md2.6 KBbc76859982afupstream ↗

  # Scenario style
  
  How to write the **Scenarios** section of a spec when the task is stakeholder-facing or names explicit acceptance criteria. Scenarios are plain markdown using Given/When/Then phrasing — no `.feature` files, no Cucumber/Gherkin tooling.
  
  ## Format
  
  Each scenario is a `### Scenario:` heading followed by Given/When/Then lines. 3–7 scenarios per feature is the typical range; if you need more, the feature is too large and should be split.
  
  ```markdown
  ## Scenarios
  
  ### Scenario: Shopper applies a valid coupon at checkout
  **Given** a shopper has a $100 cart and a valid 10% coupon
  **When** they apply the coupon at checkout
  **Then** the order total drops to $90 and the discount line shows "10% off"
  
  ### Scenario: Coupon has expired
  **Given** a shopper has a coupon that expired yesterday
  **When** they apply the coupon at checkout
  **Then** the cart total is unchanged and an "expired coupon" message is shown
  ```
  
  `And` / `But` are allowed to chain conditions in Given or outcomes in Then.
  
  ## Discipline
  
  - **One observable behavior per scenario.** A scenario describes one user-visible outcome. If the Then has two unrelated outcomes, split into two scenarios.
  - **Declarative, not imperative.** Describe *what* the user does and observes, not *how* the UI gets them there. Not "click the Apply button, then wait for the spinner to stop" — instead "they apply the coupon."
  - **Business language, not implementation language.** "Total drops to $90" is good; "PriceCalculator returns 9000 cents" is not. Scenarios survive refactoring; implementation details don't.
  - **Concrete examples.** Real numbers, real strings. "A $100 cart" beats "a non-empty cart"; "yesterday" beats "in the past."
  - **Independent.** Each scenario stands alone — no "continuing from the previous scenario" chains.
  
  ## Anti-patterns
  
  - **Multi-When chains.** `When ... When ... When ...` is a workflow, not a behavior. Keep one When per scenario; if a setup action is needed, put it in Given.
  - **Scenario-Outline overuse.** Don't parameterize 12 rows of inputs to test arithmetic — that's a unit-test concern, not an acceptance criterion. Reserve the scenarios for distinct user-observable cases.
  - **Scenarios for refactors or internals.** Internal refactors, infrastructure changes (e.g. switching a cache backend from Redis to an in-process LRU), and developer-only tooling have no stakeholder-facing behavior change — omit the Scenarios section entirely.
  - **Vague Given.** "Given the user is on the checkout page" without state is a setup line, not a precondition. State *what is true* in the world, not which page is loaded.
  

• skills/brainstorm/agents/openai.yaml198 Be767dd35a9eaupstream ↗

  # Codex reads this file; Claude Code reads disable-model-invocation in SKILL.md.
  # Both say the same thing: this skill runs only when the user invokes it.
  policy:
    allow_implicit_invocation: false
  

• skills/brainstorm/templates/product/mvp-prd.md1.7 KBe37f85ac142aupstream ↗

  # MVP — Product Requirements (PRD)
  
  > **Altitude & precedence.** Part of a docs-first cascade — **product vision -> MVP PRD -> target tech-stack -> active build spec**. The full statement of what that means lives in [product vision](./product-context.md); the short version is that when these conflict about current work, the active build spec (in `docs/specs/`) wins.
  > Siblings: [product vision](./product-context.md) · [target tech-stack](./tech-stack.md).
  >
  > **What this document is.** The first product slice (the MVP) — narrower than the
  > [product vision](./product-context.md), broader than any single build. What to build *right now* is
  > the smaller active build spec in `docs/specs/`.
  >
  > **How to use it.** Each section holds a guiding question. Resolve a section by replacing its `TODO`
  > with the decision and a short note on *why*.
  
  ## 1. Problem statement
  
  > TODO — not yet decided. What exact problem does the MVP solve, and for which user first?
  
  ## 2. MVP scope
  
  > TODO — not yet decided. The smallest slice that delivers and validates the core value.
  
  ## 3. Non-goals / out of scope
  
  > TODO — not yet decided. What the MVP deliberately excludes (and defers to the vision).
  
  ## 4. Primary use cases
  
  > TODO — not yet decided. The core things a user can do; mark the single "hero" use case to nail first.
  
  ## 5. Functional requirements
  
  > TODO — not yet decided. What the system must *do*.
  
  ## 6. Non-functional / product requirements
  
  > TODO — not yet decided. How the product must feel and behave, beyond features.
  
  ## 7. Success metrics
  
  > TODO — not yet decided. How you will know the MVP is working — make each signal measurable.
  
  ## 8. Risks and open questions
  
  > TODO — not yet decided.
  

• skills/brainstorm/templates/product/product-context.md1.7 KBa7db16cbc4deupstream ↗

  # Product Context
  
  > **Altitude & precedence.** This document is part of a docs-first cascade, in decreasing altitude:
  > **product vision → MVP PRD → target tech-stack → active build spec**. Higher docs set long-term
  > direction; the active build spec (in `docs/specs/`) governs what to build right
  > now. When they conflict about current work, **the active build spec wins.**
  > Siblings: [MVP PRD](./mvp-prd.md) · [target tech-stack](./tech-stack.md).
  >
  > **What this document is.** The long-term product vision — the destination, not the next build. For
  > what to build now, follow the active build spec in `docs/specs/`; for the first
  > product slice, see [mvp-prd.md](./mvp-prd.md).
  
  ## Big picture
  
  > TODO — not yet decided. In one paragraph: what is the product, who is it for, and what does it let
  > them do?
  
  ## Product vision
  
  > TODO — not yet decided. The longer-term direction — what this becomes over time, and why it matters.
  
  ## Target users
  
  > TODO — not yet decided. The primary users and what they care about. Note how technical they are.
  
  ## Core product principles
  
  > TODO — not yet decided. The handful of principles every product decision should honor.
  
  ## What it is / what it is not
  
  > TODO — not yet decided. Bullet what the product is, and — just as important — what it is not.
  
  ## North star
  
  > TODO — not yet decided. One sentence: the single outcome everything built should support.
  
  ## Guidance for AI coding agents
  
  > TODO — not yet decided. How an agent should treat this doc. Typically: this is vision, not current
  > scope; build the smallest thing that validates the idea; when the vision and the active build spec
  > conflict about what to build now, the spec wins.
  

• skills/brainstorm/templates/product/tech-stack.md1.8 KB118ef1842e38upstream ↗

  # Target Technology Stack
  
  > **Altitude & precedence.** Part of a docs-first cascade — **product vision -> MVP PRD -> target tech-stack -> active build spec**. The full statement of what that means lives in [product vision](./product-context.md); the short version is that when these conflict about current work, the active build spec (in `docs/specs/`) wins.
  > Siblings: [product vision](./product-context.md) · [MVP PRD](./mvp-prd.md).
  >
  > **What this document is.** The **target** stack the product grows toward — *not* a constraint on the
  > current build. The active build spec uses only the small subset it needs. This is forward-looking
  > product/architecture *planning*; it is distinct from any post-code structure notes your engineering
  > setup keeps about the code as it actually exists.
  
  ## Core principles
  
  > TODO — not yet decided. The few rules guiding technology choices (e.g. prefer popular,
  > well-documented tools an AI agent can use reliably; keep the initial architecture simple).
  
  ## Selected stack
  
  > TODO — not yet decided. Fill only the categories you need; leave the rest blank. For each, name the
  > choice and one line on *why*.
  
  - **Language:** TODO
  - **Frontend:** TODO
  - **Backend / API:** TODO
  - **Data / persistence:** TODO
  - **AI layer (if any):** TODO
  - **Auth (if any):** TODO
  - **Testing:** TODO
  - **Observability:** TODO
  
  ## Architectural direction
  
  > TODO — not yet decided. The shape of the system (e.g. modular monolith vs. separate services) and why.
  
  ## Adoption & phasing
  
  > TODO — not yet decided. What to adopt now vs. add only when a real need appears.
  
  ## Notes for AI coding agents
  
  > TODO — not yet decided. How an agent should use this doc. Typically: build to the current spec, not
  > the full target; do not introduce major libraries without explaining why.
  

Plain-text copy, no login: /skill-bundles/oprogramadorreal-optimus-claude-skills-brainstorm.md