---
name: erp-kit-module-3-plan
description: Create implementation plan by breaking down feature specs into model, command, and query documentation. Use after requirements review (step 2) to plan the implementation structure.
metadata:
  erp-kit-version: "0.45.0"
---

# Feature Breakdown to Model/Command/Query Docs

Convert feature specifications into structured model, command, and query documentation. The main agent creates the plan and populates scaffolded docs, then parallel subagents refine each doc type.

## Version Check

Run `npx erp-kit internal measure versions` from the repo root. If `status` is `"violations"`, relay the findings (each states its own fix) and stop; otherwise proceed.

## When to Use

- User has feature specs (e.g., `docs/feature/*.md`) and wants implementation docs
- User asks to create model, command, or query documentation
- User references `model.yml` or `command.yml` schemas

## Step 1: Setup

Define shared context:

- `MODULES_ROOT`: glob `**/modules/*/README.md` and derive the parent directory
- `MODULE_NAME`: from argument or detect from current working directory
- `FEATURE_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/feature/*.md`

Verify at least `FEATURE_DOCS` is non-empty. If no feature docs exist, stop with: "No feature docs found for module <MODULE_NAME>. Run erp-kit-module-1-requirements first."

## Step 2: Extract Plan (single agent)

Read ALL feature docs and extract models, commands, and queries yourself (no subagents).

Use the extraction rules from:

- [references/model-extraction.md](references/model-extraction.md) — entity/model identification, field extraction, state machines, relationships
- [references/command-extraction.md](references/command-extraction.md) — write operations, business rules, error scenarios, process flows
- [references/query-extraction.md](references/query-extraction.md) — read operations, lookups, aggregations, conversions

Produce consolidated plan:

- Models to create (with fields, relationships, states)
- Commands to create (with business rules, error scenarios)
- Queries to create (with inputs, outputs)

## Step 3: Scaffold & Populate

Scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):

```bash
npx erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
npx erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
npx erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
```

Fill in the scaffolded docs with details from the extraction in Step 2.

## Step 4: Dispatch Update Agents (parallelize)

Launch 3 Agent tool calls in parallel — one per doc type — to review and refine populated docs.
Each agent receives: MODULE_NAME, the list of created doc file paths, and FEATURE_DOCS for cross-reference.

| Agent | Prompt Template                                                      | Inputs                                       |
| ----- | -------------------------------------------------------------------- | -------------------------------------------- |
| 1     | [references/model-extraction.md](references/model-extraction.md)     | MODULE_NAME, model doc paths, FEATURE_DOCS   |
| 2     | [references/command-extraction.md](references/command-extraction.md) | MODULE_NAME, command doc paths, FEATURE_DOCS |
| 3     | [references/query-extraction.md](references/query-extraction.md)     | MODULE_NAME, query doc paths, FEATURE_DOCS   |

For each agent:

1. Read the prompt template file
2. Replace `{{MODULE_NAME}}` with the resolved module name
3. Replace `{{FEATURE_DOCS}}` with the actual file paths
4. Add to the prompt: "Read the populated docs at [doc paths]. Cross-reference against the feature docs and the extraction rules. Fix any missing fields, incorrect types, incomplete business rules, or inconsistencies. Edit files directly."
5. Dispatch the agent with the filled prompt

## Step 5: Validate

Run `pnpm run module:doc:check` and fix any violations.

## Schema Quick Reference

Schemas are bundled in `@tailor-platform/erp-kit` (model.yml, command.yml).

## Common Patterns

| Feature Element       | Documentation Type               |
| --------------------- | -------------------------------- |
| Entity with fields    | Model doc                        |
| State machine         | Model doc with State Transitions |
| Verb in state diagram | Command doc                      |
| CRUD operation        | Command doc                      |
| Validation logic      | Command doc Business Rules       |
| Data lookup           | Query doc                        |
| Unit/currency convert | Query doc                        |
| Computed aggregation  | Query doc                        |

## Validation

Always run before completing:

```bash
pnpm run module:doc:check
```

## References

- [Naming convention (PascalCase files + command verbs)](references/naming.md)
- [Module structure](../erp-kit-shared/references/structure.md)
