# General Project Conventions for Contract-Oriented Package Implementation

## Purpose

This file defines **general, language-independent project conventions** for implementing code from package contracts.

These conventions are not tied to a specific programming language.
They define how implementation should be organized relative to:
- cell contracts,
- facade boundaries,
- internal decomposition,
- traceability,
- testing.

Language-specific conventions, such as syntax, typing style, exception style, or naming mechanics, should be defined separately in a language-specific conventions file.

---

## Rule Types

This file contains:
- **Mandatory rules** — must be followed unless an explicit contract or project directive states otherwise
- **Recommended rules** — should be followed when they improve clarity and consistency

When a project contains both general and language-specific conventions:
1. follow the contract first,
2. follow the package boundary and facade obligations second,
3. follow explicit project conventions next,
4. follow target language idioms next.

---

## Scope

These conventions apply within a single user package.

They govern:
- internal code organization,
- public surface vs internal implementation,
- traceability from contract to code and tests,
- test classification,
- project consistency.

These conventions do **not** authorize:
- creating new packages,
- redefining package boundaries,
- modifying user facade contracts.

---

## Internal Cell Structure

### Mandatory
- Implementation may be decomposed into additional internal files within the current cell.
- Internal helpers may be extracted into separate internal modules if this improves clarity, cohesion, reuse, or testability.
- Public facade code and internal helper code must remain clearly distinguishable.
- Internal decomposition must preserve the contract surface and required placement in `location`.

### Recommended
- Group implementation by responsibility so that contract-facing code remains easily discoverable.
- Keep facade assembly logic near the cell surface, and reusable internal details deeper in internal modules.
- Prefer decomposition that simplifies contract coverage tracking and testing.

### Clarification
There is **no** general rule that one public contract entity must map to one implementation file.
Multiple contract entities may legitimately point to the same `location` if the contract provides for this.

---

## Public Surface vs Internal Implementation

### Mandatory
- The public contract surface must remain explicit and stable.
- Internal helper code may be freely added as long as it does not replace or shadow contract entities.
- Internal implementation details must not be treated as a replacement for facade-level contract behavior.
- Planning and coding must clearly distinguish between:
  - public items facing the contract,
  - internal implementation items.

### Recommended
- Keep contract-facing entry points easily identifiable.
- Avoid unnecessary mixing of facade behavior and private implementation details in the same place when separation improves clarity.

---

## Naming Principles

### Mandatory
- Use naming conventions idiomatic to the target language and consistent with the existing project.
- Keep naming consistent with the contract vocabulary wherever possible.
- Use naming that makes public entities, internal helpers, and tests distinguishable by role.

### If the project already has code
- Follow existing project naming patterns unless they directly contradict the contract.

### If the project has no code yet
- Use naming idiomatic to the target language.
- Use the contract vocabulary as the semantic foundation.
- Keep naming consistent between entities, helpers, and tests so the emerging project style starts with a consistent base.

### Recommended
- Prefer names reflecting responsibility and relationship to the contract.
- Let internal helper names reflect support intent, not facade intent.
- Let test names reflect the entity under test, scenario, and expected behavior.

---

## Traceability Rules

### Mandatory
Implementation and tests must be traceable back to the contract.

For any meaningful unit of implementation or test, it must be possible to determine:
- which contract entity it supports,
- which contract property or method it covers,
- whether it supports facade behavior or internal behavior,
- which described requirement it verifies.

### Recommended
- Maintain a clear mapping: contract entity → implementation location → validation → tests.
- Make it easy to verify whether each contract requirement has corresponding implementation and corresponding tests.

---

## Contract-to-Test Mapping

### Mandatory
Every contract element must have explicit test coverage.

At minimum, for each meaningful contract entity and each meaningful contract behavior:
- facade accessibility must be tested,
- declared API shape must be tested,
- behavior described in the contract must be tested.

Descriptions in the contract are not optional.
If a behavior or constraint is described there, test coverage must reflect it.

### Recommended
- Make contract test coverage easily auditable by grouping tests around entities, methods, or behaviors in a way natural to the target language and project.

---

## Test Classification

Tests are classified into three categories.

### 1. Contract Tests
Verify the package's contract surface.

They must cover:
- facade accessibility,
- public API shape,
- method/property signatures.

These tests are written FIRST in each coding task (TDD approach) and are expected to fail initially.

These tests are mandatory.

### 2. Logic Tests
Verify behavioral requirements from contract descriptions.

They must cover:
- positive scenarios,
- negative scenarios,
- edge cases.

These tests are written AFTER implementation in each coding task.

These tests are mandatory.

### 3. Integration Tests
Verify cross-entity interactions and end-to-end scenarios.

They are written as separate tasks after all coding tasks for a package.

They are created when internal complexity or cross-entity interactions justify direct verification.

### Mandatory Rule
Integration tests do **not** replace contract or logic tests.

A package does not have sufficient coverage if only integration tests exist while contract and logic tests per entity are missing.

---

## Test Naming Principles

### Mandatory
Test names must clearly indicate:
- the contract entity or internal item under test,
- the scenario,
- the expected behavior or result.

### Language-Independent Rule
Do not enforce a specific casing style here.
Instead:
- use the naming mechanics natural to the target language and test framework,
- maintain clarity of the covered subject, scenario, and expectation.

### Recommended
A good test name should communicate:
- **who/what** is being tested,
- **under what condition**,
- **what should happen**.

---

## Internal Decomposition Guidelines

### Recommended
- Introduce internal helpers when they reduce duplication or cleanly isolate behavior.
- Decompose internal logic when it improves contract traceability, readability, or testability.
- Prefer internal structure that facilitates absorbing future contract changes.

### Mandatory Boundary
Internal decomposition must remain within the current cell and must not create new cells.

---

## Relationship to Language-Specific Conventions

This file intentionally avoids language-specific rules such as:
- exact naming casing,
- typing mechanics,
- exception mechanics,
- async/sync details,
- import syntax,
- file naming syntax,
- language-specific test framework rules.

These should be defined in a supplementary language-specific conventions file when needed.

This layer of general conventions defines **structural expectations and traceability expectations**, not language syntax policy.

# Plan Output Template

Result of Phase 1 (structure) + Phase 2 (Usages calibration).
Saved to the path printed by `goga history path -f plan.md`.
This format is compatible with ralphex execution.

---

# Plan: `<topic>`

<!-- `<topic>` — the topic name (the topic directory under `.goga/history/<year>/<topic>/`) -->

## Purpose

A brief statement of what will be implemented or changed.
Cover:
- what the package must provide after implementation,
- the most important gaps between contract and code,
- the overall implementation strategy.

## Context

### Contract Surface

For each contract entity:

**Entity: `<entity name>`**
- Type: `<class | function | re-export>`
- Declared `location`: `<file path>`
- Facade obligation: must be importable from `<package>`
- Mutations: `Type::` declarations (if any)
- Properties: (list with types and descriptions)
- Methods: (list with signatures and descriptions)
- Semantic requirements from descriptions: (key behavioral expectations)
- Imported dependencies: (types from `Imports` used by this entity)
- Annotation context: (if present, include cascade: file level → entity level → method level)

Repeat for each contract entity.

### Re-exports

For each re-export block (`->Name: {}` or `->usage.Type: {}`):
- Name:
- Source: corresponding entry from `Imports` (for internal types, resolved from `Types` list with optional `AS` aliases) or entry from `Usages` (for external types)
- Facade obligation: must be importable from the facade
- Hierarchy constraint (for `Imports` only): source must be at a lower filesystem level

### Usages Context

For each usage entry:
- Name:
- Description or specification reference:
- Relevance to implementation:

### Imported Usages

For each imported usage from `Imports` → `Usages`:
- Name:
- From cell:
- Source path: `{from_path}/.usages/{usage_name}.md`
- Description or specification content:
- Relevance to implementation:

### Local Usages

For each planned local usage file (from the design document):
- File path: `.usages/<category-name>.md`
- Functional category: <what semantic area this category covers>
- Status: <new file / extends existing>
- Related entities: <which entities use practices from this category>
- Description: <what practices this file describes>
- Creation task reference: <Task N>

### External Dependencies

List all external dependencies the implementation depends on:
- External library types from `Usages` (third-party packages)
- References to patterns/conventions from `Usages`
- Required tools or frameworks

## Facts

List all facts explicitly stated in the contract or observable in the workspace:
- ...

## Gap Analysis

Compare the contract with the current visible state of the package:
- Missing contract entities:
- Missing facade exposure:
- Incorrect `location` placement:
- API mismatches:
- Behavioral mismatches:
- Existing code that can be reused:
- Test coverage gaps:
- Missing visibility in workspace or git:

---

## Tasks

> **Package ordering rule**: coding tasks for each package are completed before starting the next. Within each coding task, contract tests are written first (TDD workflow).

<!-- Repeat this block for each package: -->

### Task 1: `<descriptive title>` (infrastructure)

<Context paragraph: what this task does — Cell structure, facade, re-exports. Provide enough context for an AI agent to implement this task independently.>

**Usages relevant to this task:**
- `<usage name>`: <specific information — what to use, how to call it, what it provides>
  (This section is populated during Phase 2 calibration. If no relevant Usages exist for this task, omit this section.)

**CRITICAL: `CODEMANIFEST` files — read-only contract definitions. Do NOT modify them. If implementation does not match the contract, fix the implementation — never fix the contract.**

- [ ] <specific implementation step 1 — e.g., "Create file `path/to/location.{ext}`">
- [ ] <specific implementation step 2 — e.g., "Add re-export `EntityName` to facade">
- [ ] Verify facade accessibility: <facade check command>
- [ ] Lint: <lint command> — fix formatting if necessary

### Task 2: `<descriptive title>`

<Context paragraph: what this task does, which contract entities it covers, relevant imports/annotations. Provide enough context for an AI agent to implement this task independently.>

**Usages relevant to this task:**
- `<usage name>`: <specific information>

**CRITICAL: `CODEMANIFEST` files — read-only contract definitions. Do NOT modify them. If implementation does not match the contract, fix the implementation — never fix the contract.**

- [ ] **Contract tests**: <specific tests — facade accessibility, API shape, method signatures for entities in this task> (expected to fail at this stage)
- [ ] **Code**: <specific implementation step 1>
- [ ] **Code**: <specific implementation step 2>
- [ ] **Code**: <specific implementation step N>
- [ ] **Interface verification**: run the contract tests above — <entity test run command> — all must pass
- [ ] **Logic tests**: <specific behavioral tests — positive, negative, edge cases from the plan>
- [ ] **Debugging**: <run all tests command> — fix implementation code until all tests pass (do NOT fix test code)
- [ ] **Contract re-verification**: verify all contract obligations — facade, API shape, behavior
- [ ] **Lint**: <lint command> — fix formatting, apply decomposition if necessary

Continue for all coding tasks **for this package**.

### Task N: Integration tests for `<scope>`

<Context: which cross-entity scenarios are being tested for this package>

**Usages relevant to this task:**
- `<usage name>`: <specific information — e.g., mocking instructions, test fixtures>

- [ ] Create test file <test file>
- [ ] Test cross-entity interaction: <specific scenario>
- [ ] Test edge case: <specific edge condition>
- [ ] Run validation: <test run command>

<!-- Repeat the entire block (coding tasks + integration tests) for the next package -->

---

## Validation Commands

- `<command>`: <what it verifies>
- `<command>`: <what it verifies>
- <run all tests command>: Run all tests
- <facade check command>: Verify that all facade entities are importable

---

## Completion Criteria

- [ ] Every contract entity is implemented in the correct `location`
- [ ] Every contract entity is accessible from the facade
- [ ] Properties and methods match the declared API
- [ ] Descriptions are reflected in behavior
- [ ] Contract dependencies are met
- [ ] Re-exports are accessible from the facade
- [ ] Every coding task followed the TDD workflow (contract tests → code → verification → logic tests → debugging → re-verification → lint)
- [ ] Contract tests and logic tests cover facade, API, and behavior within each coding task
- [ ] Integration tests exist where cross-entity scenarios require them
- [ ] No package boundary was expanded
- [ ] `CODEMANIFEST` files were not modified (contract is read-only)
- [ ] All validation commands pass
- [ ] Every Usages entry is mentioned in at least one task (Phase 2 calibration)

---
name: goga-plan-by-design
description: Compile a design document into a ralphex execution plan
---
# Planning Agent: Design Document → ralphex Plan

## Purpose

Compiles a finalized **architectural decision from a design document** into a **ralphex-compatible execution plan** —
a structured markdown file that [ralphex](https://github.com/umputun/ralphex) can autonomously execute through Claude Code.
You **decompose** a finalized architectural decision into coding tasks.

---

### Phase 1: Context Loading

#### Step 1: Load DSL Specification

Use the **Skill tool** to invoke `goga-cell`.

Use for:
- Understanding DSL terminology when compiling the design document into tasks

#### Step 2: Load DSL Application Principles

Use the **Skill tool** to invoke `goga-cookbook`.

Use for:
- Understanding Entity vs Routine when compiling entities into tasks
- Principles for working with `.usages/` when planning tasks for creating/updating usage files

#### Step 3: Load Language Implementation Rules

Use the **Skill tool** to invoke `goga-lang-disp`.

The language skill defines implementation conventions: cell structure, facade, signature rules, **naming**.
Examples in other skills (DSL, cookbook, templates) may use naming from one language
(e.g., snake_case) while the target language requires another (e.g., PascalCase) — the language skill
contains authoritative rules for the target language. Apply them when compiling the plan.

#### Step 4: Load Plan Template

Read the file `output-template.md` from the current skill.

Use for:
- Plan structure (sections, headings, checkboxes)
- Templates for three task types (infrastructure, TDD coding, integration tests)
- Format for "Validation Commands" and "Completion Criteria" sections

#### Step 5: Load Project Conventions

Read the file `conventions.md` from the current skill.

Use for:
- Implementation rules (internal cell structure, public surface, naming)
- Traceability rules and contract-to-test mapping
- Test classification (contract, logic, integration)

#### Step 6: Load Design Document

Read the file from the path printed by `goga history path -f design.md`.
If the design document does not exist — stop and ask the user to run `/goga:design` first.

---

### Phase 2: Compile Design Document into Plan

Goal: decompose the architectural decision from the design document into ralphex tasks.

#### Step 1: Extract Data from Design Document

Extract from the design document:

- **Contract changes** → determine task scope (which entities are new/modified/deleted)
- **Applied fixes** → context for tasks (what was fixed and why)
- **Entity interactions** → transfer diagrams and data flows verbatim into task context
- **Code Stack Trace** → include verified logical chains into task context
- **Algorithm Design** → algorithm steps become implementation checkboxes in tasks
- **Cross-cutting concerns** → distribute across relevant tasks
- **Usages Analysis** → include usages context in tasks where they are used
- **.usages/ updates** → tasks for creating/updating usage files
- **Test Stack Trace** → test scenarios become instructions in task checkboxes
- **Additional instructions** → include in task context

**Critical**: traces, diagrams, and test scenarios from the design document contain verified knowledge.
Transfer them verbatim into relevant task context, do not summarize.

#### Step 2: Compile into ralphex Tasks

For each entity from the design document, create tasks following the rules:
- DSL → plan compilation table (see "DSL Compilation Rules" section)
- Cell boundaries (see "Boundaries" section)
- ralphex format requirements (see "Ralphex Integration" section)
- task ordering principles (see "Task Ordering Principles" in "DSL Compilation Rules" section)
- TDD workflow (see "Test Planning Rules" section)
- task formation rules (see "Execution Planning Rules": task structure, requirements, checkbox granularity, validation command placement, anti-patterns)
- templates from `output-template.md` (loaded in Step 4)
- project conventions from `conventions.md` (loaded in Step 5)

Use the `goga-cell` skill for correct interpretation of DSL elements during compilation.

#### Step 3: Save the Plan

Write the plan to the path printed by `goga history path -f plan.md`, using the template from `output-template.md`.

The topic is the current one in the history tree; name it to reflect the plan's scope, not the Cell name.
Run `goga history ensure` first if the topic directory does not exist.

---

### Phase 3: Plan Verification

Before completion, verify:

1. Is every entity from the contract changes in the design document covered by a task?
2. Is every test scenario from the design document included in task test instructions?
3. Is every Usages Analysis entry from the design document included in at least one task?
4. Does every planned `.usages/` entry from the design document have a creation task or step?
5. Are interaction diagrams and traces transferred verbatim, not summarized?
6. Do all coding tasks follow the TDD workflow?
7. Is the ralphex format correct (`### Task N:` headings, `- [ ]` checkboxes)?
8. Is every task atomic and self-contained?
9. Are validation commands defined?
10. Are `CODEMANIFEST` files marked as read-only?

If any answer is "no" — rework the plan.

---

### Phase 4: Present Summary

After saving the plan, output a brief summary for the user:

- **Task table**: numbered list of all tasks with type (infrastructure / TDD coding / integration tests) and one-line description
- **Key design decisions**: maximum 3-5 points
- **Total test count**: how many test scenarios are planned

Do NOT repeat the full plan contents. Keep it to a minimum of lines.

---

## Ralphex Integration

### Plan Format Requirements
The plan **must** follow this structure for ralphex compatibility:
- `### Task N: <title>` headings define individual tasks
- `- [ ]` checkboxes mark incomplete items within each task
- `- [x]` checkboxes mark completed items (none initially)
- `## Validation Commands` section contains commands for verifying correctness
- Only ONE task is executed per ralphex iteration

### Designing Tasks for AI Execution
Each task must be:
- **Atomic** — executable by an AI agent in a single Claude Code session
- **Self-contained** — includes all context needed for implementation without reading other tasks
- **Ordered** — within a Cell: infrastructure before entities; simple before complex; each task follows the TDD workflow
- **Verifiable** — has clear completion criteria and validation commands

### ralphex Execution Protocol
Steps 1–7 must be present as checkboxes in each coding task of the plan — the protocol is self-enforcing through the plan structure.
When ralphex executes a coding task, the AI agent follows these checkboxes:
1. **STEP 0 (DECLARATION)** — declare which task is being worked on
2. **STEP 1 (CONTRACT TESTS)** — write contract tests for the entities/interfaces in this task (they will fail — this is expected)
3. **STEP 2 (IMPLEMENTATION)** — write the code for this one task
4. **STEP 3 (INTERFACE VERIFICATION)** — run the contract tests from step 1 to verify implemented interfaces match the contract
5. **STEP 4 (LOGIC TESTS)** — write tests verifying behavioral logic (positive, negative, edge cases)
6. **STEP 5 (DEBUGGING)** — run all tests and fix implementation code until all tests pass
7. **STEP 6 (CONTRACT RE-VERIFICATION)** — verify that all contract obligations are still met (facade, API shape, behavior)
8. **STEP 7 (LINT)** — run linter, fix formatting and decompose if necessary
9. **STEP 8 (COMPLETION)** — mark checkboxes as completed
10. **→ REVIEW → APPROVAL → NEXT TASK** — after completion, ralphex submits the task for code review; review must be approved before moving to the next task

---

## Boundaries

### Allowed Within the Current Cell
You may plan:
- additional internal files and modules
- helper functions and classes
- private abstractions
- internal restructuring
- decomposition of implementation into smaller internal units

### Prohibited
You must not plan:
- creating new Cells
- defining new interfaces at the Cell level outside the current one
- expanding system boundaries beyond the current Cell
- replacing contract entities with internally-only-accessible abstractions
- violating facade accessibility requirements
- ignoring `location`
- modifying `CODEMANIFEST` files — they are **read-only** for the implementation agent

---

## DSL Compilation Rules

Use the `goga-cell` skill to interpret DSL elements during compilation.
Follow the project conventions from `conventions.md`.

### Compilation Mapping

| DSL Element                  | Result in Plan                                                          |
|------------------------------|-------------------------------------------------------------------------|
| `Types Import`               | Context section — internal types grouped under a single `From`          |
| `Usages Import`              | Context section — imported practice from another cell's `.usages/`      |
| `Usages`                     | Context section with implementation guidance                            |
| `Annotations`                | Contextual hints embedded into task descriptions                        |
| `->Re-exports`               | Task: ensure importability from the facade                              |
| `Entity` with `properties`   | Task: create entity in `location`, implement properties                 |
| `Entity` with `methods`      | Task: implement methods in `location` with behavior from descriptions   |
| `Standalone function`        | Task: implement function in `location`                                  |
| `Type::` mutation            | Task: implement interface mutation mechanism                            |
| Method/property descriptions | Reflected in task implementation instructions                           |

### Task Ordering Principles
Tasks are ordered **within a Cell**. Each Cell is completed before moving to the next.

Within a single Cell:
1. **Infrastructure tasks** — Cell structure, facade, re-exports
2. **Entity skeleton tasks** — creating classes/functions in correct `location`s
3. **Property implementation tasks** — implementing facade-visible properties
4. **Method implementation tasks** — implementing methods with described behavior
5. **Interface mutation tasks** — implementing `Type::` mutations
6. **Integration test tasks** — cross-entity, edge cases

When the plan spans multiple Cells:
- Leaf Cells first, then parent Cells
- Respect dependency order: if A imports from B, complete B first

Entities with the same `location` are grouped into one task.

### Descriptions Are Mandatory
Descriptions attached to properties, methods, and functions define semantics, behavioral expectations,
constraints, and implementation requirements. They must appear in task instructions.

### Imports — Internal Dependencies and Tracked Practice References
Imports define:
1. **Contract dependencies** — types from other `CODEMANIFEST` via `Types:` + `From:`
2. **Practice dependencies** — usages from other cells' `.usages/` via `Usages:` + `From:`
External library types are described in `Usages`, not in `Imports`.

### Usages — Documentation for Cell API Consumers
`Usages` provides context: external library types, specifications, conventions.
Include Usages context in the plan from the design document (Usages Analysis section).

**Two-level usages model**:
- **Global** — project root `.goga/usages/`
- **Local** — `.usages/` inside the cell
- **Imported** — from other cells via `Imports` → `Usages`

### Re-exports — Facade Obligations
Re-export blocks (`->Name: {}`) define names that must be available on the facade.
Every re-exported name must be importable.

### Annotations — Prescriptive Instructions
`annotations` at the file, entity, or function level provide instructions for the implementation agent.
Embed them as requirements in task descriptions.

---

## Execution Planning Rules

### Task Structure

Task templates are defined in `output-template.md`. Follow them when forming each task in the plan.

There are three task types:
- **Infrastructure** — Cell structure, facade, re-exports (code → verification → lint)
- **TDD Coding** — entity implementation with the ralphex protocol (steps 0–8 from "ralphex Execution Protocol" section)
- **Integration Tests** — cross-entity scenarios (separate tasks)

### Task Requirements
Each task must:
- have a clear, descriptive title
- include enough context for implementation without reading other tasks, including:
  - which contract entities it covers
  - which `location` files are involved
  - relevant imports and usages
  - behavioral requirements from descriptions
  - annotations as prescriptive instructions for the implementation agent
- list implementation steps as `- [ ]` checkboxes
- explicitly specify target files
- identify covered contract entities
- include at least one validation checkpoint
- be executable in a single Claude Code session

### Checkbox Granularity
Each `- [ ]` checkbox must be:
- a specific, verifiable action (e.g., "Create implementation file for `location`", "Implement method `load()` returning a collection of items")
- verifiable by running a command or checking file existence
- not a vague goal (avoid "Implement service" without specifics)

### Validation Command Placement
- Each task includes at least one inline validation step (checkbox with a verification command).
- The `## Validation Commands` section at the plan level lists global commands.
- Task-level commands verify the outcome of a specific task.
- Plan-level commands verify overall contract compliance.

### Anti-patterns
- Vague tasks like "implement X" without specific steps
- Tasks covering multiple unrelated contract entities
- Tasks without validation commands
- Tasks assuming context from previous tasks without restating it
- Tasks too large for a single AI session
- Tasks that propose modifying `CODEMANIFEST` files
- Coding tasks without contract tests (violates TDD)
- Coding tasks without a debugging step

---

## Test Planning Rules

### Tests Within Coding Tasks
1. **Contract tests** — written FIRST; verify facade, API shape, signatures
2. **Logic tests** — written AFTER implementation; verify behavior

Both types are embedded in coding task checkboxes.

### Integration Test Tasks
Create for cross-entity scenarios spanning multiple entities or multiple Cells.

### Test Categories
- **Contract** — facade and API shape (mandatory, embedded in coding tasks)
- **Logic** — behavioral requirements (mandatory, embedded in coding tasks)
- **Integration** — cross-entity interactions (separate tasks, when appropriate)

---

## Validation Commands

The plan must include a `## Validation Commands` section.
Specific commands are defined based on project specifications and practices.

```markdown
## Validation Commands
- <run all tests command>: Run all tests
- <lint command>: Lint check
- <facade check command>: Facade accessibility
```

---