This skill isthe interactive development of a business workflow system with acomo as its backend, together with an AI agentfor the canonical source of the development loop and harness. Regardless of whether the user is a developer, it enables agent-led iteration from "description of the business → a working workflow".
Rules for responses to usersfollow the repository-wide rules (
AGENTS.md"Responses to Users (Common to All Skills)"). Do not include skill names, referenced file paths, or acquisition processes in explanations aimed at end users.
What This Package Provides
| Deliverable | Location | Role |
|---|---|---|
| Canonical source of the development loop | references/loop-guide.md | Phase definitions, stop conditions, branching between non-developer/developer modes |
| Static verification harness | scripts/validate-model.mjs |
Schema compliance of draft (definition / dataSchema / policy) + graph and consistency verification |
| Walkthrough plan | scripts/walkthrough-plan.mjs |
Generate path enumeration from model JSON + CLI / UI test procedures + sample data |
| How to use the harness | references/harness-guide.md | Command, option, and error code correspondence table |
| Walkthrough procedure | references/walkthrough-testing.md | Post-release live testing (CLI paths / UI paths, multiple actors) |
| Custom app track | references/custom-app-guide.md | Canonical source for custom frontend development (A1–A4), architecture selection, scaffold recipes |
| Screen design mapping rules | references/screen-design.md | Mapping from model to screens, forms, and operations, and design document templates (A1) |
| Minimal SPA scaffold | references/spa-scaffold-minimal.md | (a) Minimal 3 files for a direct-call SPA configuration (Vite + dev proxy + SuperTokens) (A2) |
| Client implementation guide | references/client-integration.md | @acomo/client / Verified invocation patterns for the public API (A2) |
| Authentication integration guide | references/auth-integration.md | Session passthrough / Client Credentials / non-interactive authentication for local development (A2) |
| E2E for custom UI | references/custom-app-e2e.md | Path coverage testing with walkthrough JSON as the canonical source (A3) |
| Working samples | fixtures/sample-*.json / fixtures/broken-model.json |
Live-verified reference models (basic approval / conditional branching / parallel review / rework loop — see harness-guide.md for the list) and an error catalog |
Skillset structure (routing)
This skill isthe orchestratorand each task is delegated to an existing skill. Always read the relevant skill before performing the task.
| Task | Delegation destination skill |
|---|---|
| Business hearing / model design dialogue (draft generation / clarifying questions) | acomo-workflow-modeling（SKILL.md） |
| Model types, patterns, and design principles | Same as above, philosophy.md / patterns.md |
| Calling the CLI / public API (registration, publishing, process operations) | acomo（SKILL.md. In a monorepo, an external skill — if not present, npm run skills:install. In the distribution repository, it is already included) |
| Guide the user through screen operations (confirmation and acceptance by non-developers) | acomo-ui（SKILL.md） |
| How to run the verification, testing, and improvement loop | This skill（references/） |
| Custom frontend design, implementation, and E2E | This skill（custom-app-guide.md follow from) |
acomo-ui は acomo standard screensguidance skill. For custom app screens, provide guidance in the app's own terms (A4).
Two usage modes
First grasp the user's environment and role, then decide the mode (you may switch modes partway through).
| Companion mode (for non-developers) | Developer mode | |
|---|---|---|
| Assumed users | Business staff and administrators. They do not use code or terminals | Developers using acomo as a backend |
| Model registration and publishing | The agent handles it via CLI on the user's behalf | The user themselves or the agent uses the CLI |
| Verification harness | The agent runs it and explains the results in business terms | The user can also run it directly |
| Walkthrough | The user operates and checks on browser screens (guidance in acomo-ui terms). The agent checks in parallel via CLI | Either CLI or screen |
| Acceptance decision | The user decides by watching behavior on the screen | The user decides based on test results and the screen |
In either mode, confirm business decisions (number of approval stages, permissions, branching conditions, etc.) with the user. The agent autonomously runs technical verification and fixes.
Development loop (overview)
The source of truth is references/loop-guide.md. Each phase has entry conditions and exit conditions (DoD).
Phase 0 環境準備 … 接続先（ローカル or 本番テナント）と認証を確立し、疎通を確認する
Phase 1 ヒアリング設計 … acomo-workflow-modeling に従い draft（definition/dataSchema/policy）を対話生成
Phase 2 静的検証 … validate-model.mjs でエラー 0 になるまで draft を修正（エージェント自律ループ）
Phase 3 登録 … createWorkflowModel でドラフト登録し、モデル ID を控える
Phase 4 ウォークスルー … walkthrough-plan.mjs の計画に沿って公開 → 全結末経路を実走 → 証跡を残す
Phase 5 改善 … ユーザーのフィードバックを差分で draft に反映し、Phase 2 へ戻る
Phase 6 引き渡し … 運用手順（画面操作ベース）をユーザーに説明して完了
If a custom frontend is required, with Phase 4 green as the entry condition, A1–A4 tracks (screen design → implementation → E2E → handover. Source of truth: references/custom-app-guide.md). If the acomo standard UI / CLI is sufficient for the operational surface, complete at Phase 6.
Loop stop conditions (this skill's DoD)
validate-model.mjshas 0 errors (warnings have been individually justified)- All paths in the walkthrough plan (all outcomes such as approval and rejection) were executed, and the expected terminal node was reached
- The user confirmed that it works as intended on the screen (or in CLI output) and accepted it
- (When building a custom app) A3's DoD — all ending paths are reachable via the custom UI as well, and out-of-permission cases have been confirmed
Agent execution rails (if in doubt, follow this order)
The mechanical shortest procedure for creating and handing off one model.Do not proceed to the next row until the gate for each row is satisfied.
For details and exceptions, see references/loop-guide.mdIf in doubt about the JSON shape,
fixtures/sample-*.json is authoritative (fixtures take precedence over fragments in the text).
| # | What to do (commands) | Conditions to proceed (gates) |
|---|---|---|
| 1 | acomo --version(In a monorepo, cross-check with acomo-cli/package.json ) → acomo getCurrentUser |
Authentication, tenant, and mode are finalized |
| 2 | Interactively generate a draft with acomo-workflow-modeling, and/tmp/<モデル名>-draft.json save to(from then on this file is the source of truth) |
The user agrees on the flow, items, and permissions |
| 3 | npm run workflow:validate -- /tmp/<モデル名>-draft.json |
0 errors(warnings explained and agreed upon) |
| 4 | acomo createWorkflowModel '<draft の中身>'(When improving, saveWorkflowModel） |
obtain modelId |
| 5 | npm run workflow:walkthrough -- /tmp/<モデル名>-draft.json → Fill in the entire actor table first → acomo publishWorkflowModel --modelId <ID> → run through all paths |
All ending paths reach the expected terminal node + 1 out-of-permission case confirmed |
| 6 | For feedback, update the draft file as a diff and return to row 3. After acceptance, hand off (if a custom UI is needed, go to A1–A4) | User acceptance |
Harness quick reference
Within the monorepo, use the root npm script (the actual implementation is under this skill scripts/ — a zero-dependency Node script).
# draft の静的検証（fenced ブロック付きテキストも直接渡せる）
npm run workflow:validate -- path/to/draft.json
npm run workflow:validate -- path/to/draft.json --json # 機械可読
# ウォークスルー計画の生成（Markdown。--json で機械可読）
npm run workflow:walkthrough -- path/to/draft.json
Outside the monorepo (for standalone distribution), node scripts/validate-model.mjs <file> can be run directly.
Details and error code mapping table: references/harness-guide.md
Use outside the monorepo (distribution)
This skill does not have the acomo monorepoUsers and custom app developersIt is also distributed to
(distribution channel: acomo-skills repository. The publication procedure is in the monorepo's docs/skills-distribution.md).
It is written so that the following also holds in the distribution layout.
- Dependent skills (
acomo/acomo-workflow-modeling/acomo-ui）はare placed side by side in the same parent directory. Relative links (../acomo/SKILL.mdetc.) resolve as-is. - The harness is a zero-dependency Node script (Node 20+).
node <このスキル>/scripts/validate-model.mjs <file>It runs with. The schema validation layer automatically resolves the co-locatedacomo-workflow-modeling/schemas/(if not present,--schemas-diror specify with the environment variableACOMO_MODEL_SCHEMAS_DIR. If unspecified, skip only the schema layer and emit a warning). npm run workflow:validate/workflow:walkthrough/npm run skills:installはMonorepo-internal onlyentry point. In a distribution environment, use the standalone execution described above.- Local development stack (
dev:up/ Descriptions that touch seed users, etc. are valid only within the monorepo. At the distribution destination, read them as the actual values for the target tenant (URL, authTenantId, users).
Principles of proceeding (loop engineering)
- Show the draft quickly, insert verification, then register. Do not keep doing only hearings (follow the staged generation protocol of acomo-workflow-modeling).
- Static verification is the agent's autonomous loop. Do not report validate errors to the user one by one; fix them first and then report only the results. For warnings, ask the user to confirm only those that "require business judgment."
- Walkthroughs must always cover all outcomes. Not only paths ending in approval, but also rejection, send-back, and branch paths must be covered, and it must be confirmed that the expected end node name was reached.
- Improvements are cycled through diffs. Do not rebuild everything on every feedback; explain what it affects in definition / dataSchema / policy, then update the draft and rerun from Phase 2 (static verification).
- Leave evidence. Record the execution command, process ID, and reached nodes for each walkthrough, and present them to the user at acceptance.
Known failure modes
- Edge
typeにrevertwrite — In the model JSONFlowTypeにrevertdoes not exist (send-back is handled by the node'scanRevertand the runtime API). validate usesE_EDGE_TYPEto detect it. - Writing the condition expression as a single string —
conditions[].expression/actionPolicies[].allowmust always be{operator, expression1, expression2}in the object form ("$token.approveCount >= $token.childTokenLength"strings like this are schema violations and becomeE_SCHEMA_DEFINITION).The source of truth for the correct form isfixtures/sample-*.json— if it conflicts with JSON fragments in the text, fixtures are authoritative. - Writing the policy node ID as a node name or another ID — definition の
idrequires an exact match.E_POLICY_NODEDetect with . - dataSchema property's
_ordermissing — The backend AJV requires_order/_acomoType. Detect with schema validation (E_SCHEMA). - Missing execution of rejection paths — Testing only approval paths and reporting completion. Cover all paths listed by walkthrough-plan.
- In local verification,
acomo loginassume a permanent token for — In the local development stack, use the SuperTokens session access token forACOMO_ACCESS_TOKEN(short-lived). Procedure is references/walkthrough-testing.md。 - Process data
{"data":{...}}wrapped in and sent — The body of engine APIs (submit / approve / reject / save) has dataSchema keys at the top levelflat JSON(confirmed by local execution). If wrapped and sent, it is ignored as keys outside dataSchema. - Reporting as a bug that process data is not visible after completion — If the completion event has no read policy, data in the post-completion retrieval becomes
{}specification. For operations that require viewing after completion, line up read in the completion event. @acomo/clientReceive a process with the high-level generation method of — For engine-related and process-retrieval-related, use*Raw+raw.json()(the high-level version istoken.childProcessTokensfails with the FromJSON mapper. Confirmed by running locally. Source of truth: references/client-integration.md）。Engine:executeBlaming actionPolicies for a 403 when hitting the engine API as a user without the role — Engine-related require the role's SystemActionPoliciesEngine:execute(measured. In the error message,Engine:execute が必要appears). Assign the applicable role to custom app users and E2E test users.- Determining button enablement in a custom app by role name / status string on your own —
getProcessWithNodeActionsのnodeActions(the server-side actionPolicies evaluation result). @acomo/clientGuessing the class name ofgetWorkflowModelfrom the operationId / calling in an ordinary user's app — Generated classes are per OpenAPI tag (getMyModelはMyModelApi）。/models・/processes-related requireModel:readetc. and are for administrators, so ordinary business users get 403 — build the app with/my/...（MyModelApi/MyProcessApi). Correspondence table: references/client-integration.md。- Calling a business API directly from the browser in a custom SPA and failing due to CORS — The CORS allowed headers do not include
x-tenant-id(measured). The auth API can be called directly, but business APIs must be made same-origin (proxy / BFF). Source of truth: references/auth-integration.md。