---
name: erp-kit-app-1-requirements
description: Create Tier 1-2 documentation (requirements, actors, business-flow) for an application. Use when starting a new application or documenting high-level requirements and workflows.
disable-model-invocation: true
metadata:
  erp-kit-version: "0.59.0"
---

# Application Requirement Analysis Workflow

Create Tier 1-2 documentation: Requirements, Actors, and Business Flows.

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

## Workflow Phases

```
GATHER → CLARIFY → INIT & DEPLOY → ADAPT DOCS → STORY EXTRACTION → VALIDATE
```

### Phase 1: Gather

Understand the application's purpose and scope:

1. **Identify** what the application does (business purpose)
2. **List** target users (actors) and their roles
3. **Understand** business goals and success criteria
4. **Capture** key workflows the application must support

Focus on "what" the application should do, not "how" it will be implemented.

> **Log:** `step.start` with `data: { skill: "erp-kit-app-1-requirements", context: { app: APP_NAME } }`

### Phase 2: Clarify

Use AskUserQuestion to clarify undefined requirements. Focus on business-level scope and workflows — not platform capabilities like authentication.

| Category         | Example Questions                                                           |
| ---------------- | --------------------------------------------------------------------------- |
| Scope            | Which steps are MVP-essential? Any steps that can be deferred?              |
| Edge Cases       | How far to handle cancellation, rejection, or mid-flow abandonment?         |
| Actor Boundaries | Are approver and executor separate? What is each actor's operational scope? |
| Business Rules   | Which steps are automated vs manual? What conditional branches exist?       |

Ask 3-4 questions at a time using multiSelect where appropriate.

> **Log:** `decision` for each user answer with `data: { question, choice, alternatives, rationale }`

### Phase 3: Init & Deploy (new apps only)

Skip this phase if the app already exists.

`app init` creates a new application from a template — a working backend, frontend, and documentation that serves as a starting point. Choose the template closest to the user's requirements so that Phase 4 has less to adapt.

**Template selection:** Based on the requirements gathered in Phase 1-2, pick the best-fit template:

| Template | When to use |
|---|---|
| `user-management` | Users, roles, and permissions only. Default when no other template fits. |

```bash
npx erp-kit app init {APP_NAME} {APP_ROOT} -t {TEMPLATE}
pnpm install
```

Ask the user if they want to deploy the reference app now. If yes, follow [deploy workflow](../erp-kit-shared/references/deploy.md).

### Phase 4: Adapt Documentation

Adapt existing docs to match the actual application requirements gathered in Phase 1-2.

**README.md** — Rewrite Overview and Industry Context to reflect the actual application.

**Actors** — Add, modify, or replace actor docs to match the actual roles:

```bash
# Add new actors
npx erp-kit app generate doc actor {ACTOR_NAME} -p {APP_ROOT}/{APP_NAME}
```

**Business Flows** — Keep what applies, modify what's close, remove what doesn't fit, and add new flows:

```bash
# Add new flows
npx erp-kit app generate doc business-flow {FLOW_NAME} -p {APP_ROOT}/{APP_NAME}
```

**Schema constraints:** See [erp-kit-shared/references/schema-constraints.md](../erp-kit-shared/references/schema-constraints.md) for H1 heading rules, naming conventions, and requirements structure.

**Business flow diagram:** Use `sequenceDiagram` with actors from "Actors Involved" as participants. Show who initiates each step and the system responses.

- **Business-flow granularity** — decisions, state transitions, forks. Implementation detail (file type/size, exact UI messages, single-field validation) belongs in story `## Test Cases`. When trimming such detail from an existing diagram, confirm a Test Case covers it (or the implementation lacks it), so coverage is not silently dropped.
- **The main (non-`alt`) path reads as one thread** — from the initiating actor to the flow's final business outcome. It is the script for the flow's E2E journey.
- **Exceptions sit at their decision point** — place an `alt` before the main-path outcome it replaces, never after it, so the sequence cannot read as both outcomes happening.

**Business flow `## Stories` section:**

Use `- TBD` as a placeholder during flow creation. These will be replaced with actual story links in Phase 4b below.

### Phase 4b: Story Extraction

After adapting business flows, extract and create story documentation.

1. **Collect** all business flow docs: glob `<APP_ROOT>/docs/business-flow/*/README.md`
2. **Dispatch story extraction agents** — one Agent per business flow (parallelize if possible). Each agent:

   - Reads the prompt template from [references/story-extraction.md](references/story-extraction.md)
   - Replace `{{APP_NAME}}` with the resolved app name
   - Replace `{{ACTOR_DOCS}}` with the actor doc file paths
   - Replace `{{BUSINESS_FLOW_DOCS}}` with ONLY the single business flow doc for that agent
   - Dispatch the agent with the filled prompt

3. **Scaffold & populate** story docs from agent results:

```bash
# For each story identified
npx erp-kit app generate doc story <flow>/<actor>--<story> -p {APP_ROOT}/{APP_NAME}
```

4. **Link stories** in business flow READMEs: replace `- TBD` placeholders in each flow's `## Stories` section with actual links:

```markdown
- [Story Title](./story/<actor>--<story-name>.md)
```

### Phase 5: Validate

```bash
npx erp-kit app check -p {APP_ROOT}/{APP_NAME}
```

**Expected passing output:** `✓ No violations found` for each doc type that has files. "No matching files found" appears for doc types not yet created — this is normal and not an error.

> **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>", artifacts: ["<list of created doc paths>"] }`

## Schema Reference

| Schema              | Tier | Output Path                                          |
| ------------------- | ---- | ---------------------------------------------------- |
| `requirements.yml`  | 1    | `README.md`                                          |
| `actor.yml`         | 2    | `docs/actor/<name>.md`                               |
| `business-flow.yml` | 2    | `docs/business-flow/<flow>/README.md`                |
| `story.yml`         | 2    | `docs/business-flow/<flow>/story/<actor>--<name>.md` |

## Next Step

After completing Tier 1-2, use `/erp-kit-app-2-requirements-review` to review documentation quality.
