AGENTS.md — Building a business process

Playbook for adding a new business process (claims, loans, onboarding, …) on top of BusinessProcessCore. Read core/AGENTS.md first for the tables, choice values, step trigger contract, and human task contract. Use order-processing/ as the template to copy — every recipe below points at the order-processing component that implements it.

Ground rules: a process is its own solution layered on the installed core; it contributes workflows, agents, review widgets, security roles, and environment variables, and does not modify the core (except registering its widgets in the console). Ask the user for the Option A/B solution authoring choice from the root AGENTS.md before creating components.

Folder template

business-processes/<process-name>/            kebab-case, e.g. car-insurance-claim
├── README.md                                  process design, stages, agents, contracts, demo limits, before you deploy
├── AGENTS.md                                  process-specific notes for coding agents (copy the order-processing one)
├── docs/                                      process-flow diagram, screenshots
└── solution/
    ├── DEPLOYMENT.md                          step-by-step install; mirrored in .github/skills/deploy-<process>/references/
    ├── export/                                unpacked solution (pac solution unpack layout)
    │   ├── Other/Solution.xml                 UniqueName, Version, publisher faf001, RootComponents
    │   ├── Other/Customizations.xml           connection references
    │   ├── Workflows/<flow>-<GUID>.json(.data.xml)
    │   ├── bots/faf001_<agent>/               bot.xml, configuration.json
    │   ├── botcomponents/faf001_<agent>.*     skills, SKILL.md + knowledge files (filedata/)
    │   ├── Roles/<Role>.xml
    │   └── environmentvariabledefinitions/faf001_<Var>/
    ├── build/<SolutionName>_<ver>_unmanaged.zip
    ├── config/                                deployment-settings.<env>.json (git-ignored)
    └── scripts/activate-flows.ps1             activates this process's workflows after import

Review widgets go in the core console: core/codeapps/workflow-console/src/features/tasks/widgets/<process-name>/ — see the console AGENTS.md.

Design first — agree it with the user before building

Produce this design (in the process README) and confirm it before generating components:

1. Stage map — intake → automated/agent stages → human gates → finalization; what happens on reject / needs-more-info at each gate.
2. Step names — one per stage, unique across all processes in the environment (prefix with the domain: Claim Damage Assessment, not Assessment). They are API.
3. Triggers — for each workflow, the faf001_bpstep filter it listens on (created vs. human step completed — see core contract).
4. Agents and skills — which stages need reasoning; inline agent node vs. published agent; one skill per body of business rules; the knowledge files each skill reads; the JSON output schema each agent must return.
5. Human tasks — task name, task type, widget ID (<domain>-<purpose>-ui), the faf001_inputdata JSON shape, the security role (and optional notification team), and the output keys the widget writes.
6. Data keys — every faf001_bpdatavalue key written and read (<step>.<field>, <widget-prefix>.<field>, globals) with its datatype.
7. Artifacts and attachments — what comes in, what is produced, file names.
8. Environment variables and connections — mailbox, endpoints, thresholds; which connectors (Outlook, Teams, agent node, others).

Recipes (copy from order-processing)

Copy the order-processing JSON for these actions and adapt names, step names, keys, and schemas — do not invent new connector operation shapes.

Solution conventions

• Publisher faf001 (same as core); solution UniqueName in PascalCase (OrderProcessing); zip <UniqueName>_<major>_<minor>_<build>_<rev>_unmanaged.zip.
• Workflows: kebab-case verb-noun names (extract-order-data), Copilot Studio agent flows (.data.xml Category 5, ModernFlowType 1), meaningful Description, new GUID per flow, RootComponent type="29" in Solution.xml. Ship them deactivated; the process's activate-flows.ps1 activates them after import, downstream first so every trigger exists before upstream stages start writing rows.
• Agents: schema name faf001_<name>agent; GitHub Copilot harness; one skill per rule set with SKILL.md (frontmatter name, description, metadata.version) plus its knowledge files.
• Security roles: dedicated custom roles (never Basic User), RootComponent type="20", granting Read on Security Role, Team, Team Membership and the needed faf001_bp* privileges, or tasks silently disappear from the queue.
• Connection references: reuse the core faf001_sharedcommondataserviceforapps; define process-owned references for other connectors with logical names unique to the process so two solutions never own the same component.
• Environment variables: faf001_<PascalName>; no environment values committed.
• No process may hardcode GUIDs of roles, users, teams, or environments.

Deliverables checklist

• Design (above) agreed with the user and written into README.md (mirror the order-processing README sections: key features, process flow, stage by stage, agents, contributed vs. inherited, demo data and limits, before you deploy).
• Workflows, agents/skills/knowledge, roles, env vars, connection refs in export/.
• Widgets registered in the console, with tests; core repacked if the console changed.
• build/ zip packed; imported into a dev environment and an end-to-end run verified when an environment is available.
• solution/scripts/activate-flows.ps1 for this process's flow names.
• solution/DEPLOYMENT.md and a .github/skills/deploy-<process>/ skill cloned from deploy-order-processing (SKILL.md, references/, readiness scripts), kept consistent.
• Process AGENTS.md; root README.md reference-implementations list updated.
• Demo data clearly labelled as fictional; no secrets or environment values committed.