Workflow

Goga organizes feature development as two global workrounds — a workround is a ready-made sequence of stages — refinement and development — separated by review stages. Each command produces a concrete artifact (PRD, ADR, task, architecture, design, plan) — this lets you review decisions before they turn into code.

Two workrounds

Workround	Purpose	Commands
Refinement	Settle the what and why: turn a product idea into a verified engineering task	`define` → `discover` → `specify` → `review(task)`
Development	Build the how: from a verified task to accepted implementation	`prototype` → `apply` → `design` → `plan` → `build` → `change` → `accept`

The refinement workround ends with a task review: once the task in .goga/history/<year>/<topic>/task.md is verified, the product side is settled and development can start. The development workround picks up the verified task and takes it all the way to an acceptance report.

Command examples in this section use the slash-command form /goga:<command> — see Slash commands for where the form works and how to invoke the same skills in agents without command registration.

Refinement turns a raw idea into a task definition that is worth engineering. Three entry depths exist, depending on how much elaboration the idea needs:

define — the product is not yet understood: the problem, users, goals, and success criteria are extracted into a PRD (.goga/history/<year>/<topic>/prd.md). The longest refinement path opens here.
discover — the product is clear, but hard-to-reverse technical decisions are not: discover interviews them out and records short ADRs (.goga/history/<year>/<topic>/adr.md).
specify — everything above is already settled: the request is formulated directly as a structured task (.goga/history/<year>/<topic>/task.md).

define → discover → specify → review(task)

Every stage is optional on its own — a workround may start at discover or specify when the earlier artifacts already exist. The workround closes with review in its task mode, which verifies the formulated task before implementation begins.

Development

Development takes a verified task to accepted code. Its length depends on how much technical elaboration the task needs — three depths again:

Full path — the task requires new architecture, new cells, or contract changes. prototype produces the architecture plan, apply materializes it into cell file structure, design details the modified CODEMANIFESTs, plan compiles the execution plan, and build implements it.
Short path — the architecture is clear and contracts stay stable (for example, an external dependency changes and the implementation is rewritten against a new usage file). Start at change directly.
Point fix — a bug fix or behavior tweak that does not touch contracts: change alone.

prototype → apply → design → plan → build → change (bugfix loop) → accept
change → accept                                   # short path / point fix

Reviews of architecture, design, and plan artifacts are run via review between the stages — see below on when they are worth running.

A point fix with no contract change can skip the refinement workround entirely: change → accept.

Choosing a path

Is the product side (problem, users, success criteria) settled?
│
├─ No
│   └─ Start refinement at define
│
├─ Yes, but hard-to-reverse technical decisions remain
│   └─ Start refinement at discover
│
├─ Yes, the task just needs formulation
│   └─ Start refinement at specify
│
└─ A verified task exists
    │
    ├─ Requires new architecture / cells / contract changes
    │   └─ Full development path (prototype → … → accept)
    │
    ├─ Architecture clear, contracts stable
    │   └─ Short path (change → accept)
    │
    └─ Point fix without a contract change
        └─ Standalone change (change → accept)

Reviews

Reviews are optional at every stage — you decide how much verification each artifact needs. Skipping a review is acceptable when the change is small, the artifact is straightforward, or you are confident in the result. Run a review when the artifact introduces risk: large architectural changes, ambiguous contracts, or unfamiliar domains. Reviews catch drift while it is still cheap to fix.

The task review that closes refinement is the natural checkpoint between the two workrounds — it verifies the handoff artifact before implementation effort is spent.

define → discover → specify → review(task)
   → prototype → review(arch)
      → apply → design → review(design)
         → plan → review(plan)
            → goga build
               → change (bugfix loop)
                  → accept

Commands and artifacts

Command	Workround	Input artifact	Output artifact
`define`	Refinement	Product idea	`.goga/history/<year>/<topic>/prd.md` (PRD)
`discover`	Refinement	A decision worth recording	`.goga/history/<year>/<topic>/adr.md` (short ADR)
`specify`	Refinement	User request text	`.goga/history/<year>/<topic>/task.md`
`review`	both	Any reviewable artifact in `.goga/history/` — task, arch, design, plan — (or a cell)	Review report
`prototype`	Development	`.goga/history/<year>/<topic>/task.md` (or a raw description)	`.goga/history/<year>/<topic>/arch.md`
`apply`	Development	`.goga/history/<year>/<topic>/arch.md`	Cell file structure (CODEMANIFEST, `.usages/`)
`design`	Development	Modified CODEMANIFEST	`.goga/history/<year>/<topic>/design.md`
`plan`	Development	`.goga/history/<year>/<topic>/design.md`	`.goga/history/<year>/<topic>/plan.md`
`build`	Development	`.goga/history/<year>/<topic>/plan.md`	Implemented code; the plan moves to `.goga/history/<year>/<topic>/completed/` on success
`change`	Development	Change description	Modified code + reconciled contracts and usages
`accept`	Development	Completed implementation	Final acceptance report

Workflow artifacts live at .goga/history/<year>/<topic>/<kind>.md (<kind> ∈ todo | prd | adr | task | arch | design | plan): <year> is the current year as YYYY, and <topic> is a lowercase kebab-case slug — non-ASCII dropped, anything outside [a-z0-9] as -, repeat hyphens collapsed, edges trimmed (branch release/1.3.0 → release-1-3-0). The topic directory is created lazily by the stage that first writes into it, and the whole .goga/history/ tree is meant to stay out of git — add it to your .gitignore. goga pipeline <name> -t <topic> switches onto the branch hosting an existing topic before a run, or creates both a fresh branch and its fresh topic when nothing hosts it; goga topics create <branch> prepares both directly.

Next steps

Product side not settled — open define.
Starting work that needs deep elaboration — open discover.
Starting a straightforward task — open specify.
Need a point fix — change.
Want to accept completed work — accept.