---
name: erp-kit-app-3-plan
description: Create Tier 3-4 documentation (screens, resolvers) by breaking down business flows and existing stories. Use after completing requirements review with erp-kit-app-2-requirements-review.
disable-model-invocation: true
metadata:
  erp-kit-version: "0.59.0"
---

# Business Flow Breakdown to Stories, Screens, and Resolvers

Convert Tier 2 business flows and stories into Tier 3 (screens) and Tier 4 (resolvers) documentation using parallel extraction agents.

## 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.

## Progress Logging

Run `npx erp-kit app progress schema` once to load the schema before your first log. Log at every step boundary marked with **Log:** below using `npx erp-kit app progress log --json '<payload>'`. Every payload requires: `v` (always `1`), `sessionId`, `prompt` (user's original request), `event`, `data`, and `conversation` (array of `{role, message}` since last log). See [progress-protocol.md](../erp-kit-shared/references/progress-protocol.md) for the full schema reference.

## When to Use

- User has Tier 1-2 documentation and wants to plan Tier 3-4
- User asks to create story, screen, or resolver documentation
- User wants to break down business flows into actionable specs

## Prerequisites

Tier 1-2 documentation must exist:

- `README.md` (requirements)
- `docs/actor/*.md` (actor definitions)
- `docs/business-flow/*/README.md` (business workflows)
- `docs/business-flow/<flow>/story/<actor>--<name>.md` (story definitions)

## Step 1: Setup

Define shared context for all agents:

- `APP_ROOT`: from argument or current working directory. Must contain a `docs/` directory.
- `APP_NAME`: basename of APP_ROOT
- `BUSINESS_FLOW_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/README.md`
- `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actor/*.md`
- `STORY_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/story/*.md`
- `MODULE_OVERVIEW`: output of `erp-kit doc modules`

Verify at least `BUSINESS_FLOW_DOCS` is non-empty. If no business flow docs exist, stop with: "No business flow docs found under <APP_ROOT>/docs/. Run erp-kit-app-1-requirements first."

Verify at least `STORY_DOCS` is non-empty. If no story docs exist, stop with: "No story docs found. Run erp-kit-app-1-requirements first to create stories."

Collect module overview:

```bash
npx erp-kit doc modules
```

This returns each module's name, overview, command/query/model counts, and dependencies. Save the full output as `MODULE_OVERVIEW` — both agents receive it.

> **Sync barrier:** `MODULE_OVERVIEW` must be collected before dispatching agents.

> **Log:** `step.start` with `data: { skill: "erp-kit-app-3-plan", context: { app: APP_NAME, flows: count, stories: count } }`

## Step 2: Dispatch Agents (parallelize if possible)

For each business flow in BUSINESS_FLOW_DOCS, launch 2 Agent tool calls in parallel — one per extraction concern.

Each agent pair receives: APP_NAME, ACTOR_DOCS, the single business flow's STORY_DOCS, MODULE_OVERVIEW, and only that flow's BUSINESS_FLOW_DOC (singular).

| Agent | Prompt Template                                                        |
| ----- | ---------------------------------------------------------------------- |
| A     | [references/screen-extraction.md](references/screen-extraction.md)     |
| B     | [references/resolver-extraction.md](references/resolver-extraction.md) |

For each agent:

1. Read the prompt template file
2. Replace `{{APP_NAME}}` with the resolved app name
3. Replace `{{ACTOR_DOCS}}` with the actor doc file paths
4. Replace `{{BUSINESS_FLOW_DOCS}}` with ONLY the single business flow doc for this iteration
5. Replace `{{STORY_DOCS}}` with ONLY the stories under this flow's `story/` directory
6. Replace `{{MODULE_OVERVIEW}}` with the output from `erp-kit doc modules`
7. Dispatch the agent with the filled prompt

With N business flows, this produces N × 2 parallel agents.

> **Log:** `agent.dispatch` for each flow with `data: { agentName: "screen-extraction|resolver-extraction", task: "<flow-name>", inputs: { flow: "<name>" } }`

## Step 3: Aggregate & Present Plan

After ALL agents return:

1. Collect extraction results from each agent, grouped by business flow
2. **Deduplicate screens**: Screens referenced by multiple flows should appear once — merge field lists and story references
3. Present consolidated plan to user:
   - Existing stories (from STORY_DOCS, for reference)
   - Screens to create (deduplicated, with type, fields, actions)
   - Resolvers to create (with operation type, module mapping)
## Step 4: Resolve Module Gaps

Step 2's resolver agent mapped resolvers to erp-kit modules using `MODULE_OVERVIEW` and flagged any operations that could not be mapped as module gaps.

If there are no gaps, proceed to Step 5.

**If resolvers require functionality that no erp-kit module provides:**

1. Group the unmapped operations by domain to identify what custom modules are needed
2. Create each custom module using `erp-kit-module-1-requirements` skill
3. Return to this step after the custom modules are ready

For resolvers that reference erp-kit modules, use `MODULE_OVERVIEW` as the source of truth. For resolvers that reference custom modules, use the custom module's own documentation.

## Step 5: Update & Create Documentation

Update existing docs under `docs/screen/` and `docs/resolver/` to match the actual requirements, remove docs for features that don't apply, and create new ones:

```bash
# Tier 3: New screens (only for screens not already in the reference)
npx erp-kit app generate doc screen <screen-name> -p {APP_ROOT}/{APP_NAME}

# Tier 4: New resolvers (only for resolvers not already in the reference)
npx erp-kit app generate doc resolver <resolver-name> -p {APP_ROOT}/{APP_NAME}
```

Fill new docs and update existing ones with details from agent extraction results.

**After creating resolvers**, replace `- TBD` placeholders in the `## Resolvers` section of each story with actual links:

```markdown
- [resolverName](../../../resolver/resolverName.md)
```

Read-only stories should have `None` under `## Resolvers`.

## Step 6: Validate

```bash
# NOTE: -p takes {APP_ROOT} (parent directory), NOT {APP_ROOT}/{APP_NAME}.
# generate doc uses -p {APP_ROOT}/{APP_NAME}, but check uses -p {APP_ROOT}.
npx erp-kit app check -p {APP_ROOT}
```

> **Log:** `validation` with `data: { command: "erp-kit app check", status: "pass"|"fail", issues: [] }`

> **Log:** `step.complete` with `data: { status: "pass"|"fail"|"blocked", summary: "<one-line result with screen/resolver counts>", artifacts: ["<list of created doc paths>"] }`

## Naming Conventions

See [erp-kit-shared/references/naming-conventions.md](../erp-kit-shared/references/naming-conventions.md).

## Schema Reference

| Schema         | Tier | Output Path               |
| -------------- | ---- | ------------------------- |
| `screen.yml`   | 3    | `docs/screen/<name>.md`   |
| `resolver.yml` | 4    | `docs/resolver/<name>.md` |

## Common Patterns

| Flow Element         | Documentation Type           |
| -------------------- | ---------------------------- |
| User action step     | Story                        |
| UI requirement       | Screen                       |
| Actor in flow        | Story actor                  |
| Create/Update/Delete | Resolver (Mutation)          |
| View/List/Search     | Resolver (Query) or built-in |

## Tips

- Stories are created in erp-kit-app-1-requirements — this step consumes them
- Stories should be completable in a single user session
- Screens can be shared across multiple stories
- Prefer built-in queries over custom resolvers for simple list/get operations

## Next Step

After completing Tier 3-4, use `/erp-kit-app-4-plan-review` to validate documentation parity.