The agent produces a design document — a complete architectural specification derived from CODEMANIFEST changes.
The design document specifies what to implement and how to implement it.
\nThe agent does not write implementation code. The agent does not produce an execution plan.\nThe agent produces an architectural specification where every detail is fully elaborated.
\nThe agent invokes goga-cell via the Skill tool.
Use goga-cell for:
.usages/)The agent invokes goga-cookbook via the Skill tool.
Use goga-cookbook for:
.usages/The agent diffs all CODEMANIFEST files between the current branch and the base branch.
\nIdentify:
\nOutput: Change list grouped by CODEMANIFEST file with entity-level detail.
\nThe agent executes goga schema to retrieve the cell hierarchy.
Apply --depends-on <cell_path> for each path from Step 1 to locate affected cells.
Output: Dependency map scoped to affected cells.
\nThe phase objective: produce a clean CODEMANIFEST before deep tracing begins. Resolve all static contract defects at this stage.
\nDetermine which Usages entries require reading:
\nAnnotationsFor each Usages entry with a path value, read the file (paths resolve relative to project root; files reside in .goga/usages/).\nFor each imported usage from Imports → Usages, read {from_path}/.usages/{usage_name}.md.
Output: Complete set of resolved Usages specifications.
\nCompare CODEMANIFEST contracts against the current implementation.
\nValidate with goga-cell:
:: mutations, -> embeddings, Imports directiveslocation correctness (file at the same directory level, with extension, no parent traversal)Validate with goga-cookbook:
methods/properties present where required, absent where inappropriate)Check for:
\nlocation values<current_cell_path>/.usages/ directories and their contents (when present, only for referenced usages)Imports → Usages — verify that referenced files exist at {from_path}/.usages/{usage_name}.mdOutput: Gap report with specific files and entities.
\nVerify four consistency dimensions.
\nValidate DSL rules with goga-cell at each check:
:: mutation rules (base type validation, multi-level chain resolution)-> embedding rules (type must appear in Imports)Imports rules (no cross-dependencies; same level or below only)Validate architectural decisions with goga-cookbook:
Imports dependencyConsistency dimensions:
\nInterface ↔ Type consistency: For each entity that accepts or returns a type from Imports or Usages, confirm the type is declared and its shape matches expected usage (fields, methods, and properties referenced by annotations exist in the source type).
Type ↔ Mutation consistency: For each Type:: mutation, confirm:
Imports (correct name/alias) or Usages (qualified name)A::B::Cls) form a valid chain where each segment resolvesInterface ↔ Interface consistency: For interacting entities (one entity calls methods on another, one entity passes data to another):
\nAnnotations ↔ Entity consistency: Annotations reference types, usages, and parameters that exist in the current CODEMANIFEST context.
\nRecord each detected inconsistency as a CODEMANIFEST defect specifying:
\nPresent all CODEMANIFEST defects to the user via AskUserQuestion (grouped by file). Offer:
\nAlso raise questions about:
\nIf no defects or questions exist — skip this step.
\nFor each approved change:
\ngoga-cell (:: mutations, -> embeddings, Imports structure, key casing)goga-cookbook (connection form, Entity vs Routine, granularity)goga lintOutput: Clean CODEMANIFEST ready for tracing.
\nDesign document core. Starting from the clean CODEMANIFEST produced in Phase 3, perform detailed elaboration.
\nValidate design decisions at each step using goga-cell and goga-cookbook.
This phase operates as a self-correcting loop — any step may surface a CODEMANIFEST defect that Phase 3 static analysis missed. Each step defines explicit transition conditions.
\nFor each contract entry point (method, function, constructor), trace the complete logical chain through the code from start to finish:
\nEstablish checkpoints at each step. Verify:
\nContract interaction checkpoints — additionally verify at each step where entities interact:
\nType:: mutation is involved, the mutated type must satisfy the consumer's contractual expectations. If not — record as a CODEMANIFEST defect.Important: Trace by reading actual source files of existing code and actual library documentation for Usages. If a Usages entry points to a specification file — read it. Do not assume — verify.
\ngoga-cell, goga-cookbook, linter), check usages,\nre-trace the current entry point. Then continue.Do not work around contract errors — the defect is in CODEMANIFEST, not in the implementation.
\nAll entry points traced → proceed to Step 2.
\nAnalyze the stack trace results:
\nUsages/Practices as interface bridges: A practice (Usages entry) is a bridging entity between cells. When an entity must interact with an external library, another cell, or a shared interface — it MUST route through a declared practice. The practice defines the interaction contract. Always route external system connections through the corresponding Usages entry — never bypass a declared practice with a direct dependency.
\nImport Usages analysis: When Imports contains Usages: groups, the agent:
Reads each imported usages file at {from_path}/.usages/{usage_name}.md
Analyzes how the imported practice applies to the current cell's entities
\nTraces which entities depend on which imported usages
\nDocuments the traced dependency in the design (imported usages create traceable cross-cell links, not contractual obligations)
\nAnalysis completed without defects → proceed to Step 3
\nContract defect detected → Propose a fix via AskUserQuestion.\nUpon approval — apply the edit, validate (goga-cell, goga-cookbook, linter), check usages,\nreturn to Step 1 to re-trace the affected entry points.
For each Usages entry:
\nFor each imported usage from Imports → Usages:
Read the file at {from_path}/.usages/{usage_name}.md
Document the traceable dependency
\nAll practices used correctly → proceed to Step 4
\nPractice unreferenced in any annotation → Propose a fix (add annotation reference or remove the practice).\nUpon approval — apply the edit, validate (goga-cell, goga-cookbook, linter),\nreturn to Step 1 to re-trace the affected entry points.
Specify cross-cutting concerns:
\nError handling: Global strategy
\nValidation: Locations, rules, behavior on invalid data
\nLogging: What is logged, at what level, what data
\nCaching: What is cached, the strategy (if applicable)
\nConcurrency: Thread safety requirements (if applicable)
\nCross-cutting concerns consistent with the contract → proceed to Step 5
\nContract defect detected (e.g., error strategy contradicts method signatures) → Propose a fix via AskUserQuestion.\nUpon approval — apply the edit, validate (goga-cell, goga-cookbook, linter), check usages,\nreturn to Step 1 to re-trace the affected entry points.
Generate and record test scenarios with full call stacks. Each test is written into the design document — tests are deliverables, not intermediate artifacts.
\n6 mandatory elements per test:
\n<test name> — self-documenting, following target language conventionsCategories:
\nPositive — happy path, defaults, explicit values
\nNegative — invalid input, missing dependencies
\nEdge cases — empty data, boundary values, idempotency
\nTests reveal no contract defects → proceed to Step 6
\nTest exposes type or logic incompatibility in contract → Propose a fix via AskUserQuestion.\nUpon approval — apply the edit, validate (goga-cell, goga-cookbook, linter), check usages,\nreturn to Step 1 to re-trace the affected entry points.
.usages/ consistencyCritical distinction — Usages directive vs practice directories: These are independent concepts:
Usages directive (in CODEMANIFEST header) — internal practices consumed by cell entities (libraries, patterns, conventions). Path values resolve to .goga/usages/<current_cell_path>/.usages/ directory (in the cell folder) — external documentation for consumers importing this cell. Describes how to work with the cell APIFor each affected cell:
\n.usages/ does not exist — skip.usages/ exists — read and verify:\nUse goga-cookbook for decision-making: .usages/ file update rules, usage file authoring principles, criteria for supplementing an existing file versus creating a new one.
Functional categories: A cell implements logic divisible into semantic domains. If existing .usages/ files follow a category-based organization — preserve that structure.
Decision rules:
\nUsages references pointing to own .usages/ files — .usages/ is consumer documentation, not a source of contractual requirementsPropose changes and obtain user confirmation.
\nPhase complete → proceed to Phase 5.
\nWrite results to a file using the template from design-doc-template.md.
Path: docs/design/<feature-name>.md.
docs/design/ directory if it does not exist