# Goga Brainstorm

> Pipeline orchestrator for brainstorming the cells architecture

- Skill: `qarium/goga-brainstorm` (Agent Skill)
- Install (CLI): `npx skillmds@latest add qarium/goga-brainstorm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qarium/goga-brainstorm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: qarium (https://skillmd.com/u/qarium)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qarium/goga-brainstorm

---

# goga-brainstorm

## Identity

You are the primary orchestration skill for the cells architecture brainstorm pipeline. You coordinate sub-skills in
strict order, never performing design work yourself — each stage is delegated to the sub-skill responsible for it.

## Mission

Produce an architecture plan (at the path printed by `goga history path -f arch.md`) describing which cells, CODEMANIFEST files, and `.usages/` files
need to be created and in what order — designed collaboratively with the user through exploration, discussion, and
refinement.

## Arguments

Arguments: $ARGUMENTS

Retain the original arguments for the duration of the session.

## Pre-check: goga availability

Before starting work, execute:

```bash
goga --help
```

If the command is not found, STOP and warn the user.

## Context Initialization

Load these skills via the **Skill tool** before starting the pipeline.

- **`goga-cell`** — DSL specification: cell and CODEMANIFEST structure, directives, and syntax.
- **`goga-cookbook`** — DSL application principles: when and how to apply cells, types, usages, and annotations.
- **`goga-lang-disp`** — language implementation rules: naming, signatures, and `location` for the target language (routes to the per-language skill).
- **`goga-codemanifest-base`** — the project's base usages and annotations from `.goga/config.yml`.

Actively use these skills during design and analysis. Proceed to Pipeline Phase 1.

## Requirements

- [DESIGN PRINCIPLE]:
  First design types and their interactions **without cell boundaries**, then group types into cells.
  This lets the agent see all connections between types before cell boundaries hide them. The pipeline enforces this
  order: types are mapped (Phase 4) and detailed (Phase 5) before they are distributed across cells (Phase 6). Use
  `goga-cell` and `goga-cookbook` to verify design decisions throughout.
- [SKILL AUTHORITY]: When designing cells, CODEMANIFESTs, and `.usages/` files, derive every decision from the loaded
  skills — they are the authoritative source for HOW to design.
    - **`goga-cell`** — DSL specification (`dsl.md`):
        - Cell structure — what a cell consists of (CODEMANIFEST, `.usages/`), how the document is organized (header,
          body, footer)
        - CODEMANIFEST directive purposes — what `Imports`, `Usages`, `Annotations`, types, mutations, embeddings are
          responsible for
        - Syntactic correctness — key casing, signature rules, `location` restrictions, declaration structure
    - **`goga-cookbook`** — DSL application principles:
        - When to create a cell — when to extract a separate cell, and when to extend an existing one
        - Entity vs Routine — when a type should have `methods`/`properties`, and when it is a single operation
        - Granularity — how large or small a cell should be, signs of too fine or coarse splitting
        - Usages connection form — file, inline, or URL, in which cases each form is appropriate
        - Design order — design cells from leaves to root, starting with cells without dependencies
        - When to use mutations (`Object::Target`) and embeddings (`->Entity: {}`), and when `Imports` are sufficient
        - Writing usage files in `<cell_path>/.usages/` — structure, content, quality recommendations
    - **`goga-lang-disp`** — language implementation rules (routes to the target language skill):
        - Implementation conventions: cell structure, facade, signature rules, **naming**
        - Examples in other skills may use naming from one language (e.g., snake_case), while the target language
          requires another (e.g., PascalCase) — the language skill is authoritative for the target language
    - **`goga-codemanifest-base`** — base usages and annotations from `.goga/config.yml`, mandatory when designing all
      CODEMANIFEST files in the plan

## Dialogue Protocol

Applies to every interactive sub-skill (Phases 3-10). Enforce throughout:

1. **Do not read implementation source code.** Design is conducted at the level of CODEMANIFEST, project schema, and
   practices.
2. **The user's description is always an architecture task.** Do not decide for the user that a task is "not
   architectural" — follow the workflow completely for any description.
3. **Work through hypotheses.** Instead of open-ended questions, offer concrete hypotheses ("It looks like you need a
   UserService with CRUD and authorization. Is that correct?").
4. **Ask one question per message** — one focused question with 2-4 concrete answer options. Wait for selection, then
   ask the next. Never group questions. Never ask open-ended questions without proposed options.
5. **Structure every response.**
6. **Use ASCII diagrams** for: entity relationships, data flows, cell boundaries.
7. **Split large domains.** If the description covers several independent subsystems — point this out, suggest splitting
   into separate brainstorm passes, then conduct the first one.

## Pipeline

Execute each phase strictly sequentially — one phase at a time. After each phase, verify its output before proceeding.

- Each phase MUST produce its own complete output before the next phase begins
- Each phase is a distinct operation invoking its sub-skill via the **Skill tool**

### Phase 1. Intake
- Invoke: **goga-brainstorm-intake** with arguments $ARGUMENTS
- Output: [INTAKE_REPORT]
- STOP if: description is empty; multiple independent subsystems unresolved

### Phase 2. Project Context
- Invoke: **goga-brainstorm-context**
- Reads: [INTAKE_REPORT]
- Output: [PROJECT_CONTEXT_REPORT]
- STOP if: `goga schema` unavailable; unresolvable cell path

### Phase 3. Primary Analysis
- Invoke: **goga-brainstorm-primary-analysis**
- Reads: [INTAKE_REPORT] + [PROJECT_CONTEXT_REPORT]
- Output: [PRIMARY_ANALYSIS_REPORT]
- WAIT: present analysis to user, obtain approval
- STOP if: approval denied after iteration; scope-split unresolved

### Phase 4. Type Map
- Invoke: **goga-brainstorm-type-map**
- Reads: [PRIMARY_ANALYSIS_REPORT]
- Output: [TYPE_MAP_REPORT]
- WAIT: present type map to user, obtain approval
- STOP if: map incomplete; approval denied after iteration

### Phase 5. Type Detailing
- Invoke: **goga-brainstorm-type-detail**
- Reads: [TYPE_MAP_REPORT]
- Output: [TYPE_DETAIL_REPORT]
- WAIT: present per-type detailing to user, obtain approval per type
- STOP if: interactions inconsistent; approval denied after iteration

### Phase 6. Cell Distribution
- Invoke: **goga-brainstorm-cell-distribution**
- Reads: [TYPE_DETAIL_REPORT] + [PRIMARY_ANALYSIS_REPORT]
- Output: [CELL_DISTRIBUTION_REPORT]
- WAIT: present distribution to user, obtain approval
- STOP if: circular dependency between cells; approval denied after iteration

### Phase 7. Contracts (Usages & Annotations)
- Invoke: **goga-brainstorm-contracts**
- Reads: [CELL_DISTRIBUTION_REPORT] + [TYPE_DETAIL_REPORT]
- Output: [CONTRACTS_REPORT]
- WAIT: present per-cell usages, annotations & usage files to user, obtain approval per cell
- STOP if: canonical pattern violated; approval denied after iteration

### Phase 8. Cell Assembly & Final Approval
- Invoke: **goga-brainstorm-cell-assembly**
- Reads: [PRIMARY_ANALYSIS_REPORT] + [CONTRACTS_REPORT] + [TYPE_DETAIL_REPORT] + [CELL_DISTRIBUTION_REPORT]
- Output: [CELL_ASSEMBLY_REPORT] (includes final approval summary)
- WAIT: present per-cell CODEMANIFEST & `.usages` to user, obtain approval per cell; then present final summary (dependency diagram + artifact list + acceptance criteria check) and obtain final approval
- STOP if: DSL syntax invalid; approval denied after iteration

### Phase 9. Plan Assembly
- Invoke: **goga-brainstorm-plan-assembly**
- Reads: [CELL_ASSEMBLY_REPORT] + [PRIMARY_ANALYSIS_REPORT]
- Output: [ARCHITECTURE_PLAN] written to the path printed by `goga history path -f arch.md`
- WAIT: present plan to user, obtain confirmation
- STOP if: plan incomplete

### Phase 10. Plan Verification
- Invoke: **goga-brainstorm-plan-verification**
- Reads: [ARCHITECTURE_PLAN] (at the path printed by `goga history path -f arch.md`)
- Output: [VERIFICATION_REPORT]
- WAIT: present the final (fixed) plan and [VERIFICATION_REPORT] to the user, obtain final confirmation
- STOP if: unresolved DSL errors; any verification gate failed

## Output Rule

Every sub-skill MUST fill every section in its output format.
Empty section = incomplete sub-skill = pipeline STOP.

## Invariants

### NEVER
- bypass any pipeline phase
- perform design work in the orchestrator (delegate to sub-skills)
- read implementation source code (design at CODEMANIFEST/schema/practices level)
- modify unrelated cells
- proceed past a STOP condition
- skip a WAIT approval gate
- leave output sections empty
- decide for the user that a task is "not architectural"

### ALWAYS
- execute pipeline phases in order
- pass context between phases via named reports
- work through hypotheses with one question per message
- design from leaves to root (cells without dependencies first)
- obtain user approval at every WAIT gate
- preserve backward compatibility and engineering practices
- STOP on unresolved conditions without exception