@aifabrix/builder 2.54.1 → 2.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/README.md +8 -0
  2. package/lib/agent-kit/apply-ops.js +82 -0
  3. package/lib/agent-kit/checksums.js +28 -0
  4. package/lib/agent-kit/classify.js +113 -0
  5. package/lib/agent-kit/claude-shim.js +61 -0
  6. package/lib/agent-kit/constants.js +55 -0
  7. package/lib/agent-kit/file-list.js +103 -0
  8. package/lib/agent-kit/host-approve.js +130 -0
  9. package/lib/agent-kit/hosting/github.js +63 -0
  10. package/lib/agent-kit/hosts.js +71 -0
  11. package/lib/agent-kit/init.js +319 -0
  12. package/lib/agent-kit/kit-root.js +17 -0
  13. package/lib/agent-kit/managed-section.js +79 -0
  14. package/lib/agent-kit/package-load.js +45 -0
  15. package/lib/agent-kit/plan-ops.js +69 -0
  16. package/lib/agent-kit/remote-prompts.js +239 -0
  17. package/lib/agent-kit/render-host-markdown.js +40 -0
  18. package/lib/agent-kit/repo-guard.js +47 -0
  19. package/lib/agent-kit/report.js +107 -0
  20. package/lib/agent-kit/run.js +82 -0
  21. package/lib/agent-kit/scm/git.js +122 -0
  22. package/lib/agent-kit/state-file.js +83 -0
  23. package/lib/agent-kit/status.js +50 -0
  24. package/lib/agent-kit/v1-detect.js +81 -0
  25. package/lib/agent-kit/validate-kit.js +87 -0
  26. package/lib/agent-kit/workspace-name.js +40 -0
  27. package/lib/agent-kit/workspace-skeleton.js +103 -0
  28. package/lib/api/role-assistant-test-pack.api.js +86 -0
  29. package/lib/api/work-search.api.js +31 -4
  30. package/lib/api/work.api.js +19 -12
  31. package/lib/app/list-external-systems.js +2 -1
  32. package/lib/app/show-display.js +33 -6
  33. package/lib/app/show.js +25 -2
  34. package/lib/channels/add-channel.js +1 -0
  35. package/lib/channels/approval-guides/claude.js +2 -2
  36. package/lib/channels/channel-add-failure.js +1 -0
  37. package/lib/channels/channel-add-remaining.js +15 -9
  38. package/lib/channels/channel-definition-status.js +115 -0
  39. package/lib/channels/channel-description.js +2 -1
  40. package/lib/channels/channel-install-envelope.js +4 -2
  41. package/lib/channels/channel-integration-generator.js +2 -0
  42. package/lib/channels/channel-runtime-resolver.js +14 -0
  43. package/lib/channels/channel-targets.js +31 -5
  44. package/lib/channels/claude-setup-values.js +4 -1
  45. package/lib/channels/slack-channel-add.js +59 -6
  46. package/lib/channels/slack-mcp-callback.js +51 -0
  47. package/lib/channels/slack-mcp-runtime.js +156 -0
  48. package/lib/channels/slack-provisioning/install-cli.js +14 -2
  49. package/lib/channels/slack-provisioning/with-curl-on-path.js +6 -1
  50. package/lib/cli/index.js +4 -0
  51. package/lib/cli/setup-certification-commands.js +2 -2
  52. package/lib/cli/setup-certification.help.js +3 -1
  53. package/lib/commands/agent-kit-help.js +79 -0
  54. package/lib/commands/agent-kit.js +346 -0
  55. package/lib/commands/channel-add-help.js +5 -5
  56. package/lib/commands/datasource-capability-relate-cli.js +5 -4
  57. package/lib/commands/repair-auth-apply.js +1 -1
  58. package/lib/commands/repair-datasource-key-skip.js +39 -0
  59. package/lib/commands/repair-datasource-keys.js +24 -12
  60. package/lib/commands/repair-rbac.js +16 -10
  61. package/lib/commands/role-assistant-copy-output.js +61 -0
  62. package/lib/commands/role-assistant-copy.js +155 -0
  63. package/lib/commands/role-assistant-test-output.js +8 -9
  64. package/lib/commands/role-assistant-test-result-rows.js +42 -0
  65. package/lib/commands/role-assistant.js +117 -48
  66. package/lib/commands/search.js +143 -0
  67. package/lib/commands/test-trust-external.js +7 -5
  68. package/lib/commands/upload-sidecar-followups.js +4 -1
  69. package/lib/commands/verify-operations-skip-e2e.js +131 -0
  70. package/lib/commands/verify-operations-step-plan.js +6 -33
  71. package/lib/commands/verify-operations-steps.js +3 -1
  72. package/lib/datasource/capability/relate-operations.js +28 -10
  73. package/lib/datasource/capability/run-capability-relate.js +48 -25
  74. package/lib/datasource/datasource-identifier.js +13 -5
  75. package/lib/deployment/deployer-poll-run.js +117 -35
  76. package/lib/external-system/deploy-dataplane-published.js +70 -0
  77. package/lib/external-system/deploy.js +12 -2
  78. package/lib/external-system/download-role-assistant.js +41 -15
  79. package/lib/external-system/download.js +7 -1
  80. package/lib/generator/wizard-datasource-key.js +54 -0
  81. package/lib/generator/wizard.js +55 -54
  82. package/lib/integration-definition/apply-datasource-keys.js +75 -0
  83. package/lib/integration-definition/apply-relationships.js +195 -0
  84. package/lib/integration-definition/apply-static-enterprise.js +229 -0
  85. package/lib/integration-definition/apply-system-file.js +71 -0
  86. package/lib/integration-definition/apply-test-endpoint.js +89 -0
  87. package/lib/integration-definition/apply-viewpoint-defaults.js +157 -0
  88. package/lib/integration-definition/apply.js +78 -59
  89. package/lib/integration-definition/enrich-openapi-operations.js +36 -10
  90. package/lib/integration-definition/enrich-openapi-pick.js +87 -0
  91. package/lib/lifecycle/role-assistant-governance.js +56 -21
  92. package/lib/programmatic/capability-registry.js +1 -0
  93. package/lib/programmatic/index.js +2 -0
  94. package/lib/programmatic/openapi-apply-result-schemas.js +8 -0
  95. package/lib/programmatic/openapi-channel-install-schemas.js +4 -1
  96. package/lib/programmatic/openapi-component-schemas.js +1 -0
  97. package/lib/programmatic/openapi-descriptions.js +9 -3
  98. package/lib/programmatic/openapi-envelope-examples.js +7 -0
  99. package/lib/programmatic/openapi-operation-bindings.js +5 -0
  100. package/lib/programmatic/openapi-request-schemas.js +5 -0
  101. package/lib/programmatic/openapi-schema-descriptions-channel.js +8 -5
  102. package/lib/programmatic/openapi-schema-descriptions-operations.js +19 -0
  103. package/lib/programmatic/openapi-spec.js +1 -0
  104. package/lib/programmatic/request-timeout.js +3 -0
  105. package/lib/programmatic/route-handler-map.js +7 -0
  106. package/lib/programmatic/run-channel-catalog.js +50 -8
  107. package/lib/programmatic/run-channel-install-options.js +5 -1
  108. package/lib/programmatic/run-download.js +41 -0
  109. package/lib/protection/auth-context.js +3 -1
  110. package/lib/protection/protection-display.js +3 -2
  111. package/lib/protection/report-exit.js +50 -0
  112. package/lib/protection/run-commands.js +2 -0
  113. package/lib/role-assistant/package-validate.js +175 -0
  114. package/lib/role-assistant/test-case-assertion-row.js +36 -0
  115. package/lib/role-assistant/test-case-copy-bind.js +77 -0
  116. package/lib/role-assistant/test-case-copy-expected.js +127 -0
  117. package/lib/role-assistant/test-case-copy-from-work.js +90 -0
  118. package/lib/role-assistant/test-case-copy-interactions.js +67 -0
  119. package/lib/role-assistant/test-case-copy.js +119 -0
  120. package/lib/role-assistant/test-case-expected-catalog.js +135 -0
  121. package/lib/role-assistant/test-case-validate.js +88 -0
  122. package/lib/role-assistant/test-cases-bid.js +117 -4
  123. package/lib/role-assistant/test-cases-evaluate.js +137 -30
  124. package/lib/role-assistant/test-cases-honesty.js +155 -6
  125. package/lib/role-assistant/test-cases-lifecycle.js +291 -0
  126. package/lib/role-assistant/test-cases-search-graph.js +122 -0
  127. package/lib/role-assistant/test-cases-search.js +20 -2
  128. package/lib/role-assistant/test-cases.js +34 -168
  129. package/lib/role-assistant/test-pack-map.js +180 -0
  130. package/lib/role-assistant/test-pack-sync.js +187 -0
  131. package/lib/role-assistant/test-runner-debug.js +54 -0
  132. package/lib/role-assistant/test-runner-respond-body.js +36 -0
  133. package/lib/role-assistant/test-runner-search.js +20 -5
  134. package/lib/role-assistant/test-runner-start-payload.js +63 -10
  135. package/lib/role-assistant/test-runner-workhub-answers.js +45 -16
  136. package/lib/role-assistant/test-runner-workhub.js +45 -21
  137. package/lib/role-assistant/test-runner.js +50 -10
  138. package/lib/schema/external-datasource.schema.json +36 -5
  139. package/lib/schema/external-system.schema.json +20 -2
  140. package/lib/schema/role-assistant-test-case.schema.json +408 -0
  141. package/lib/search/dataplane-context.js +23 -0
  142. package/lib/search/search-args.js +211 -0
  143. package/lib/search/search-display.js +238 -0
  144. package/lib/search/search-errors.js +50 -0
  145. package/lib/search/search-prompts.js +119 -0
  146. package/lib/search/search-roles.js +85 -0
  147. package/lib/search/search-run.js +241 -0
  148. package/lib/search/search-skills.js +198 -0
  149. package/lib/utils/authentication-slot-show.js +153 -0
  150. package/lib/utils/credential-display.js +43 -1
  151. package/lib/utils/external-system-readiness-compact-blocks.js +5 -1
  152. package/lib/utils/external-system-readiness-compact-display.js +30 -1
  153. package/lib/utils/external-system-validators.js +2 -1
  154. package/lib/utils/help-builder.js +3 -1
  155. package/lib/utils/schema-loader.js +37 -0
  156. package/lib/validation/validate-external-file.js +5 -1
  157. package/lib/validation/validate.js +3 -2
  158. package/package.json +1 -1
  159. package/templates/agent-kit/adapters/claude/nested.CLAUDE.md +1 -0
  160. package/templates/agent-kit/adapters/claude/root.CLAUDE.md +5 -0
  161. package/templates/agent-kit/adapters/cursor/commands/cust-0-plan.md +5 -0
  162. package/templates/agent-kit/adapters/cursor/commands/cust-1-validate.md +5 -0
  163. package/templates/agent-kit/adapters/cursor/commands/cust-2-build.md +5 -0
  164. package/templates/agent-kit/adapters/cursor/commands/cust-3-push.md +5 -0
  165. package/templates/agent-kit/adapters/cursor/commands/cust-biz-1-validate.md +5 -0
  166. package/templates/agent-kit/adapters/cursor/commands/cust-biz-2-build.md +5 -0
  167. package/templates/agent-kit/adapters/cursor/commands/cust-biz-3-prove.md +5 -0
  168. package/templates/agent-kit/agent-kit.yaml +45 -0
  169. package/templates/agent-kit/instructions/AGENTKIT.md +83 -0
  170. package/templates/agent-kit/instructions/integration.AGENTS.md +25 -0
  171. package/templates/agent-kit/instructions/role-assistant.AGENTS.md +22 -0
  172. package/templates/agent-kit/instructions/root.AGENTS.md +37 -0
  173. package/templates/agent-kit/parity-inventory.yaml +188 -0
  174. package/templates/agent-kit/skills/aifabrix-connected-system/SKILL.md +58 -0
  175. package/templates/agent-kit/skills/aifabrix-connected-system/references/contract-checklist.md +40 -0
  176. package/templates/agent-kit/skills/aifabrix-connected-system/references/delivery-gates.md +54 -0
  177. package/templates/agent-kit/skills/aifabrix-connected-system/references/production-safety.md +35 -0
  178. package/templates/agent-kit/skills/aifabrix-connected-system/scripts/reserved-system-key.js +19 -0
  179. package/templates/agent-kit/skills/aifabrix-plan/SKILL.md +51 -0
  180. package/templates/agent-kit/skills/aifabrix-plan/references/challenge-checklist.md +108 -0
  181. package/templates/agent-kit/skills/aifabrix-plan/references/interaction.md +34 -0
  182. package/templates/agent-kit/skills/aifabrix-plan/references/plan-template.md +182 -0
  183. package/templates/agent-kit/skills/aifabrix-prove/SKILL.md +50 -0
  184. package/templates/agent-kit/skills/aifabrix-prove/references/demo-template.md +65 -0
  185. package/templates/agent-kit/skills/aifabrix-prove/references/evidence-lifecycle.md +68 -0
  186. package/templates/agent-kit/skills/aifabrix-prove/references/learning-template.md +66 -0
  187. package/templates/agent-kit/skills/aifabrix-role-assistant/SKILL.md +42 -0
  188. package/templates/agent-kit/skills/aifabrix-role-assistant/references/package-boundary.md +21 -0
  189. package/templates/agent-kit/skills/shared/hosts.md +78 -0
  190. package/templates/agent-kit/workspace/.cursor/plans/README.md +22 -0
  191. package/templates/agent-kit/workspace/LICENSE.mit +21 -0
  192. package/templates/agent-kit/workspace/README.md +89 -0
  193. package/templates/applications/builder-api/Dockerfile +3 -1
  194. package/templates/applications/dataplane/application.yaml +2 -2
  195. package/templates/applications/dataplane/env.template +1 -1
  196. package/templates/applications/dataplane/rbac.yaml +28 -0
  197. package/templates/applications/keycloak/env.template +3 -3
  198. package/templates/applications/miso-controller/application.yaml +1 -1
  199. package/templates/applications/miso-controller/env.template +8 -9
  200. package/templates/channels/claude/TROUBLESHOOTING.md +3 -0
  201. package/templates/channels/claude/channel.json +1 -1
  202. package/templates/channels/claude/install.template.md.hbs +1 -0
  203. package/templates/channels/claude/integration/claude-system.json +1 -1
  204. package/templates/channels/slack/channel.json +11 -0
  205. package/templates/channels/slack/install.template.md.hbs +9 -0
  206. package/templates/channels/slack/integration/slack-system.json +11 -0
  207. package/templates/channels/slack/manifest.template.json.hbs +6 -3
  208. package/templates/channels/teams-bot/channel.json +1 -0
  209. package/templates/python/docker-compose.hbs +14 -0
  210. package/templates/typescript/docker-compose.hbs +14 -0
@@ -0,0 +1,182 @@
1
+ # Cursor plan template (mandatory section order)
2
+
3
+ Every `/cust-0-plan` output uses **this order**. Do not rename, skip, or reorder H2 sections. Empty sections get `TBD` plus an Open-question id — never omit the heading.
4
+
5
+ File: `.cursor/plans/{major}.0-{slug}.plan.md`
6
+ `{major}` = next integer after existing plans (including `done/`). `{slug}` = kebab from capability name / proposed `system-key`.
7
+
8
+ ## Frontmatter (exact keys)
9
+
10
+ ```yaml
11
+ ---
12
+ name: {major}.0-{slug}
13
+ overview: |
14
+ {2–4 lines: purpose + systems + proof. No secrets.}
15
+ todos:
16
+ - id: lock-open-questions
17
+ content: Close Open questions (or defer with owner) until PLAN_READY
18
+ status: pending
19
+ - id: map-catalog-roles
20
+ content: Map spec role labels to COM catalog keys (aifabrix role list)
21
+ status: pending
22
+ - id: author-bid
23
+ content: Author BID (or wizard config) for each new Connected System key
24
+ status: pending
25
+ - id: cust-1-validate
26
+ content: /cust-1-validate <system-key> → READY
27
+ status: pending
28
+ - id: cust-2-build
29
+ content: /cust-2-build <system-key> → BUILT
30
+ status: pending
31
+ - id: cust-3-push
32
+ content: /cust-3-push <system-key> → PASS or PASS_WITH_SKIPS
33
+ status: pending
34
+ - id: viewpoints-fk-dims
35
+ content: Viewpoints have FK + dimensions + ABAC (not raw storage dumps)
36
+ status: pending
37
+ - id: identity-fixtures
38
+ content: Catalog roles + fixtures/groups (skill aifabrix-identity-rbac) — push-scoped
39
+ status: pending
40
+ - id: ra-packages
41
+ content: Role Assistant packages ra-<catalogRole> after CS published
42
+ status: pending
43
+ - id: cust-biz-1-validate
44
+ content: /cust-biz-1-validate — prove-ready scope + learning.md
45
+ status: pending
46
+ - id: cust-biz-2-build
47
+ content: /cust-biz-2-build — demo / Knowledge / candidate Evidence / tests
48
+ status: pending
49
+ - id: cust-biz-3-prove
50
+ content: /cust-biz-3-prove — happy + refusal; Evidence summary
51
+ status: pending
52
+ status: draft # draft until PLAN_READY, then active
53
+ isProject: false
54
+ ---
55
+ ```
56
+
57
+ Duplicate `author-bid` / `cust-1-validate` / `cust-2-build` / `cust-3-push` **per additional** `system-key` (`author-bid-personio`, …). Do not add extra todo ids unless the spec requires a named workstream.
58
+
59
+ When `/cust-0-plan` status is **NEEDS_DECISIONS**, keep `lock-open-questions` pending and `status: draft`. When **PLAN_READY**, set `status: active` and mark `lock-open-questions` completed if none remain.
60
+
61
+ ## Body (copy all H2s)
62
+
63
+ ```markdown
64
+ # {major}.0 — {Capability title}
65
+
66
+ **Plan status:** PLAN_READY | NEEDS_DECISIONS | BLOCKED
67
+ **Proposed system-key(s):** …
68
+ **Authoritative source(s):** … (in this workspace / to-be-connected / internal)
69
+ **Role Assistant(s):** `ra-<catalogRole>` (after D5) or TBD
70
+ **Operational SSOT (after build):** `integration/<system-key>/README.md`
71
+ **Public docs:** [Build AI-ready systems](https://docs.aifabrix.ai/docs/build-ai-ready-systems)
72
+
73
+ ## Goal
74
+
75
+ {Business purpose — verbatim spirit of the spec. Why this capability exists.}
76
+
77
+ ## Non-goals
78
+
79
+ - {From spec out-of-scope}
80
+ - Extra authority, entities, or source fields not in the spec
81
+ - Prompt-only enforcement of business rules
82
+
83
+ ## Authoritative sources
84
+
85
+ | Source | Role | In this workspace? | Approved fields only |
86
+ | --- | --- | --- | --- |
87
+ | … | identity / facts / … | yes path / **no — to-be-connected** | list |
88
+
89
+ Least privilege: the capability may retrieve **only** fields the spec approves.
90
+
91
+ ## Business entities
92
+
93
+ For each entity: key fields, identity, source. `heroId`-style keys **resolve** to the source identity — they do not create a second master.
94
+
95
+ ## Relationship model
96
+
97
+ ASCII diagram from the spec. Then the FK list. Call out dual relationships to the same entity (e.g. voter + nominee).
98
+
99
+ ## Foreign-key integrity
100
+
101
+ - Current eligibility = source of record
102
+ - Historical Evidence keeps stable FKs
103
+ - **Do not** cascade-delete history when a source row becomes inactive
104
+
105
+ ## Business roles
106
+
107
+ | Spec label | COM catalog key | Can | Cannot |
108
+ | --- | --- | --- | --- |
109
+ | … | from `aifabrix role list` or **TBD** | … | … |
110
+
111
+ If the label is not a catalog key → Open question (do not invent).
112
+
113
+ ## Language handling
114
+
115
+ | Artifact | Kind | Rule |
116
+ | --- | --- | --- |
117
+ | Original human text | Evidence | Never overwrite |
118
+ | Normalized / translated text | Derived Knowledge | Separate field |
119
+
120
+ ## Core business rules
121
+
122
+ Table `BR-ID` | Rule | Enforced as (governed rule, not prompt).
123
+
124
+ ## Governed operations
125
+
126
+ Grouped by role. Inputs / outputs / window. No extra ops.
127
+
128
+ ## Result Viewpoints
129
+
130
+ Each viewpoint: returns, **does not return** (no voter identities, no raw text, …). Viewpoints are governed aggregates — not dumps of join tables.
131
+
132
+ ## Validation cases
133
+
134
+ Keep spec IDs (`VAL-001`, …). These become acceptance tests.
135
+
136
+ ## Security / attack validations
137
+
138
+ Keep spec IDs (`ATTACK-001`, …). Expected: denied / rejected by BR-*.
139
+
140
+ ## Evidence to capture
141
+
142
+ Actor, Business Role, operation, authority result, rule version, success/refusal, source, Viewpoint, taxonomy version. Include the spec’s **Evidence summary** shape if given.
143
+
144
+ ## Identity join (most important relationship)
145
+
146
+ Authenticated person → catalog role → business entity → source record. Nominations (or equivalent) reference **ids**, never display names.
147
+
148
+ ## Locked decisions
149
+
150
+ | # | Question | Decision | Date |
151
+ | --- | --- | --- | --- |
152
+ | 1 | … | … | … |
153
+
154
+ ## Open questions
155
+
156
+ | ID | Question | Blocks | Owner |
157
+ | --- | --- | --- | --- |
158
+ | Q1 | … | PLAN_READY / build / push / prove | … |
159
+
160
+ ## Delivery mapping
161
+
162
+ | Track | Command | When |
163
+ | --- | --- | --- |
164
+ | CS | `/cust-1-validate` → `/cust-2-build` → `/cust-3-push` | After PLAN_READY; one ladder per new `system-key` |
165
+ | PoC | `/cust-biz-1-validate` ↔ `/cust-biz-2-build` ↔ `/cust-biz-3-prove` | After CS published (or explicit waiver) |
166
+
167
+ Existing connected sources: reuse package; do not duplicate the employee/master.
168
+
169
+ ## Success criteria
170
+
171
+ Numbered, testable. Include authority-change demo if the spec has one (same person, new role, same interface).
172
+
173
+ ## Next
174
+
175
+ - **PLAN_READY** → AskQuestion `cust-next` → `/cust-1-validate <system-key>` on **`next-yes`**
176
+ - **NEEDS_DECISIONS** → AskQuestion challenge rows ([challenge-checklist.md](challenge-checklist.md)); lock answers into this file; do not start `/cust-1-validate`
177
+ - **BLOCKED** → stop; do not author BID
178
+ ```
179
+
180
+ ## Rewrite rule
181
+
182
+ Re-running `/cust-0-plan` for the same capability **updates** this file (same `{major}.0-{slug}`). Do not mint a new major for Q&A.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: aifabrix-prove
3
+ description: >
4
+ Prove a business case on a published Connected System and Role Assistant.
5
+ Updates learning, keeps candidate Evidence separate from certified Evidence,
6
+ and iterates validate, build, and prove. Do not use for Builder product
7
+ source changes or to skip Connected System publish.
8
+ ---
9
+
10
+ # aifabrix-prove
11
+
12
+ Phases: `validate` | `build` | `prove`.
13
+ Loop: validate ↔ build ↔ prove ↔ learn.
14
+
15
+ `READY` means prove-ready, not permission to stop authoring. Build may run without READY.
16
+
17
+ Every phase **must** update [learning-template.md](references/learning-template.md).
18
+ Evidence rules: [evidence-lifecycle.md](references/evidence-lifecycle.md).
19
+ Demo shape: [demo-template.md](references/demo-template.md).
20
+ Next-step: [interaction.md](../aifabrix-plan/references/interaction.md).
21
+ Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
22
+
23
+ ## Keys
24
+
25
+ Connected System: same resolution as `aifabrix-connected-system`.
26
+ Role: existing COM catalog key; on disk `role-assistant/ra-<roleKey>/`.
27
+
28
+ CS must be published (`deploy` + `show --online`) before live prove. Upload-only draft is BLOCKED for prove.
29
+
30
+ ## Validate
31
+
32
+ Clarify scope and unknowns. Classify MISSING rows. Drafting may continue offline.
33
+
34
+ ## Build
35
+
36
+ Repeatable: demo, Knowledge, candidate Evidence, tests. Do not refuse because validate is not READY.
37
+
38
+ ## Prove
39
+
40
+ Run assistant tests. Record observations and gap owner (`none` | `product-gap` | `missing-customer-fact` | `scope-decision`).
41
+ Happy + safe-stop coverage for authority scenarios.
42
+ Never report candidates as certified.
43
+
44
+ ## Narrative
45
+
46
+ Prefer public product language from https://docs.aifabrix.ai and, when present, sibling website masters. Do not invent slogans. AI has no authority of its own.
47
+
48
+ ## Trigger examples
49
+
50
+ - Prove this business case and update learning
@@ -0,0 +1,65 @@
1
+ # demo.md template (Finnish, customer-facing)
2
+
3
+ **Path:** `role-assistant/ra-<roleKey>/demo/demo.md`
4
+
5
+ Feeds PowerPoint / ChatGPT / Gamma. Business language only — no MCP/API how-to.
6
+
7
+ **Narrative SSOT:** `aifabrix-docs/anchor-docs/web-site/` — especially `evaluate.md`, `homepage.md`, `solutions.md`, `platform.md`, `use-cases.md`. Do not invent slogans; use pillar language from those masters (Enterprise Knowledge, Operational Trust, Role Assistants, Evidence Fabrix). AI has no authority of its own.
8
+
9
+ ## Outline
10
+
11
+ ```md
12
+ # PoC-demo — <prosessi / rooli>
13
+
14
+ ## 1. Ongelma (nykytila)
15
+ - Mitä työtä tehdään tänään (raportit, Excel, ad-hoc kyselyt)?
16
+ - Kuka odottaa vastausta? Kuinka kauan?
17
+ - Missä luottamus pettää (väärä data, väärä näkyvyys)?
18
+
19
+ ## 2. Mitä todistamme
20
+ - Yksi prosessi, yksi rooli, mitattava lopputulos
21
+ - Omistaja:
22
+ - Onnistumisen mittarit (FACT vs oletus merkitty):
23
+
24
+ ## 3. Miksi AI Fabrix
25
+ - Neljä pilaria (solutions/platform): Enterprise Knowledge → Operational Trust → Role Assistants → Evidence Fabrix
26
+ - Luotettu liiketoimintakonteksti (ei raakadata-dumppi); AI:lla ei omaa toimivaltaa
27
+ - Oikeat ihmiset näkevät / päättävät vain oman organisaatiovaltuutuksensa rajoissa
28
+ - Role Assistant + Evidence — tarkastettavissa (evaluate.md / architecture-evidence-observability.md)
29
+ - Lähde: `aifabrix-docs/anchor-docs/web-site/` (ei vapaa markkinointimuisti)
30
+
31
+ ## 4. Demo-skenaariot
32
+ ### <DOMAIN>-010 — <lyhyt nimi>
33
+ - Kysymys (liiketoimintakieli):
34
+ - Odotettu lopputulos:
35
+ - Mitä ei saa tapahtua (safe stop / refusal):
36
+ - Liittyvä rooli / oikeusraja:
37
+
38
+ ### <DOMAIN>-020 — …
39
+ …
40
+
41
+ ## 5. Mitattava hyöty
42
+ - Säästetyt tunnit / kierros / virheet — FACT vs oletus
43
+ - Miten mitataan PoCissa
44
+
45
+ ## 6. Mitä ei tehdä tässä PoCissa
46
+ - …
47
+
48
+ ## 7. Päätös (Day 10 -kehys)
49
+ - Proceed / Refine / Stop — kriteerit
50
+ ```
51
+
52
+ ## English scenario map (for agents; keep out of customer slide deck)
53
+
54
+ For each Finnish scenario, maintain in `learning.md` scenario map:
55
+
56
+ | Field | English |
57
+ | --- | --- |
58
+ | scenarioId | e.g. FIN-010 |
59
+ | intent | One sentence business intent |
60
+ | happyExpected | What success looks like |
61
+ | safeStopExpected | Refusal / authority / insufficient info |
62
+ | capabilitiesInScope | Approved capability keys if known |
63
+ | evidenceCandidate | Path under `evidence/candidates/` or — |
64
+ | testHappy | YAML path |
65
+ | testSafeStop | YAML path |
@@ -0,0 +1,68 @@
1
+ # Evidence lifecycle (PoC)
2
+
3
+ ## Flow
4
+
5
+ ```text
6
+ Demo / workshop / prove observations
7
+ → learning.md (FACT | ASSUMPTION)
8
+ → evidence/candidates/ (drafts — not consumed)
9
+ → validate + certify path
10
+ → governed Evidence (consumable by Role Assistant)
11
+ ```
12
+
13
+ ## Directories
14
+
15
+ | Path | Role |
16
+ | --- | --- |
17
+ | `learning/learning.md` | Delivery log only |
18
+ | `evidence/candidates/` | Candidate drafts (English). **Do not** treat as production-like Evidence |
19
+ | `evidence/` (package root, non-candidates) | Only rows ready for the Evidence certification / consume path |
20
+ | `knowledge/` | Reusable **business understanding** from governed content — not operational decision rules |
21
+
22
+ If Builder upload processes every file under `evidence/`, keep candidates **out of** the upload consume set:
23
+
24
+ - Prefer `evidence/candidates/` and document in learning.md that upload must exclude candidates until certified, **or**
25
+ - Keep drafts only under `.temp/cust-biz-2-build/<roleKey>/evidence-candidates/` until promotion.
26
+
27
+ Default convention for this skill: **`evidence/candidates/`** + explicit prove/build note: do not promote; do not claim Runtime consumption.
28
+
29
+ ## Candidate draft shape (English)
30
+
31
+ One purpose per file or per row. Trace to scenario ID in `key` / filename / title.
32
+
33
+ Example filename: `FIN-010-cost-centre-authority.json` (array or single object matching platform Evidence row schema when known).
34
+
35
+ Minimum fields to author:
36
+
37
+ - `key` — includes scenario id slug
38
+ - `title` / `description`
39
+ - `when` — business condition
40
+ - `expectedBehavior` — ground in Reality; respect authority; refuse raw dump / cross-partition; safe-stop when insufficient
41
+ - Mark in learning.md: `ASSUMPTION` vs `FACT`-backed
42
+
43
+ ## Promotion gate
44
+
45
+ Promote candidate → governed Evidence only when:
46
+
47
+ 1. Business intent confirmed (FACT in learning.md)
48
+ 2. Happy + safe-stop tests observed for the scenario
49
+ 3. Contract validation + certification path for Evidence completed (public Evidence Fabrix / operate-first RA docs)
50
+ 4. learning.md records promotion date + commit
51
+
52
+ ## Tests
53
+
54
+ For each in-scope scenario ID:
55
+
56
+ | Case | Purpose |
57
+ | --- | --- |
58
+ | `*-happy.yaml` | Agreed business outcome under authority |
59
+ | `*-safestop.yaml` | Refusal / missing authority / insufficient information |
60
+
61
+ Prefer `role-assistant/ra-<roleKey>/tests/<suiteId>/` in this customer repo (package SSOT).
62
+
63
+ ## Forbidden
64
+
65
+ - Calling workshop acceptance alone “governed Evidence”
66
+ - Hiding process law in Knowledge
67
+ - Uploading candidates as if certified
68
+ - Skipping safe-stop coverage for authority scenarios
@@ -0,0 +1,66 @@
1
+ # learning.md template
2
+
3
+ **Path:** `role-assistant/ra-<roleKey>/learning/learning.md`
4
+
5
+ Delivery learning artifact only. Not Runtime Knowledge. Not governed Evidence.
6
+
7
+ ## Skeleton
8
+
9
+ ```md
10
+ # PoC learning log
11
+
12
+ ## Current PoC hypothesis
13
+ - Process:
14
+ - Role (responsibility / capabilities / safe boundaries):
15
+ - Expected decision / value:
16
+ - Connected System:
17
+ - Audience:
18
+
19
+ ## Confirmed facts
20
+ | Fact | Source | Date | Owner | Confidence |
21
+ | --- | --- | --- | --- | --- |
22
+ | … | … | … | … | high/med |
23
+
24
+ ## Assumptions
25
+ | Assumption | Why needed | Risk if wrong | Scenario IDs |
26
+ | --- | --- | --- | --- |
27
+ | … | … | … | FIN-010 |
28
+
29
+ ## Open questions and safe stops
30
+ - Missing authority / data / baseline / policy / capability:
31
+ - Scenario IDs affected:
32
+
33
+ ## Scenario map
34
+ | ID | Demo ask (short) | demo.md | Knowledge | Evidence candidate | Tests |
35
+ | --- | --- | --- | --- | --- | --- |
36
+ | FIN-010 | … | y/n | path or — | candidates/… | happy + safestop |
37
+
38
+ ## Observations from proof runs
39
+ | Date | Scenario | Commit | Env | Outcome | Gap class | Notes |
40
+ | --- | --- | --- | --- | --- | --- | --- |
41
+ | … | FIN-010 | abc123 | dev | pass/fail/safestop | none \| product-gap \| missing-customer-fact \| scope-decision | … |
42
+
43
+ ## Changes made
44
+ - YYYY-MM-DD — command — what changed and why
45
+
46
+ ## Decision for next iteration
47
+ - Build | Prove | Obtain customer decision | Stop
48
+ - Rationale:
49
+ ```
50
+
51
+ ## Mandatory updates by command
52
+
53
+ | Command | Sections to update |
54
+ | --- | --- |
55
+ | `/cust-biz-1-validate` | Hypothesis, facts, assumptions, open questions, baseline / prove-ready decision |
56
+ | `/cust-biz-2-build` | Changes made; scenario map (demo / Knowledge / candidates / tests) |
57
+ | `/cust-biz-3-prove` | Observations table; gap class; decision for next iteration |
58
+
59
+ ## Gap class (prove)
60
+
61
+ | Value | Meaning |
62
+ | --- | --- |
63
+ | `none` | Result matches intent |
64
+ | `product-gap` | Platform / capability / Evidence contract issue |
65
+ | `missing-customer-fact` | Need customer answer (baseline, policy, owner) |
66
+ | `scope-decision` | In/out of PoC scope — not a defect |
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: aifabrix-role-assistant
3
+ description: >
4
+ Download, author, validate, test, or upload a Role Assistant package under
5
+ role-assistant/ra-*. Use for catalog digital workers. Do not use to invent
6
+ Connected System operations or to edit platform product source.
7
+ ---
8
+
9
+ # aifabrix-role-assistant
10
+
11
+ See [package-boundary.md](references/package-boundary.md) and nested `role-assistant/AGENTS.md`.
12
+ Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
13
+
14
+ ## Preconditions
15
+
16
+ ```bash
17
+ aifabrix auth status
18
+ aifabrix role list --page-size 1000
19
+ ```
20
+
21
+ Catalog Business Role and an active user binding are prerequisites.
22
+ Connected Systems this assistant needs must be dataplane **published** (deploy, not upload-only).
23
+
24
+ ## Workflow
25
+
26
+ 1. `aifabrix download <catalogRoleOrRaKey>` before editing an existing assistant.
27
+ 2. Author settings, Knowledge, Evidence, tests, and sidecars per current Builder contracts. Read `aifabrix role-assistant --help`.
28
+ 3. `aifabrix role-assistant test …` is allowed without local RA publish.
29
+ 4. Upload/deploy RA only when the user explicitly asks in this turn.
30
+ 5. Report results honestly.
31
+
32
+ ## Hard rules
33
+
34
+ - Package key `ra-<catalogRole>` from the catalog — never `ra-<systemKey>-reader`.
35
+ - Candidate Evidence cannot be reported as certified.
36
+ - Missing subscribed CS capability → fail in CS ownership; no RA-local workaround.
37
+ - No hidden authority, actor, or identity injection.
38
+ - Do not convert RA folders with `aifabrix convert`.
39
+
40
+ ## Trigger examples
41
+
42
+ - Create or update the Finance Controller Role Assistant
@@ -0,0 +1,21 @@
1
+ # Role Assistant package boundary
2
+
3
+ Public docs: https://docs.aifabrix.ai/docs/role-assistants
4
+
5
+ ```text
6
+ integration/<systemKey>/ Connected System
7
+ role-assistant/ra-<roleKey>/ Role Assistant
8
+ ```
9
+
10
+ Download writes `role-assistant.yaml` and keeps sidecars. It does not write CS files (`application.*`, `*-system.*`, `*-datasource-*`, `env.template`). Delete those leftovers if they reappear.
11
+
12
+ If download also writes `integration/ra-*`, move sidecars into `role-assistant/ra-*`.
13
+
14
+ Generated RA FKs target **CS** datasource keys. Missing RA FK → fix the CS, re-download.
15
+
16
+ Hand-edit leftover CS manifests under `role-assistant/` is forbidden.
17
+
18
+ Do not invent an API key for `authType: system`.
19
+ Do not treat passivated invent packages (`ra-<vendor>-*`) as catalog workers.
20
+
21
+ Operator **Make available** is separate from CS publish.
@@ -0,0 +1,78 @@
1
+ # Coding hosts — local vs SSH
2
+
3
+ Use this workspace from **Cursor**, **Claude Code**, and **Codex**. Skills live in `.agents/skills/`. Invoke `/aifabrix-*` in Cursor and Claude Code, and `$aifabrix-*` in Codex.
4
+
5
+ Install and sign-in steps are in `AGENTKIT.md`. This file is how to **run** each host on a local machine or over SSH.
6
+
7
+ Do not start Claude or Codex in your home directory. `cd` into this git workspace first.
8
+
9
+ ## Auto-approve (optional)
10
+
11
+ `aifabrix agent-kit install` can write gitignored host configs so Claude Code and Codex do not prompt for every tool:
12
+
13
+ - Claude Code: `.claude/settings.local.json` (`permissions.defaultMode` = `bypassPermissions`, `allow` = `Bash(aifabrix *)` and `Read(~/**)`)
14
+ - Codex: `.codex/config.toml` (`approval_policy = "never"`, `sandbox_mode = "workspace-write"`)
15
+
16
+ Those files stay in **this workspace**. Claude may **read** files under the developer home (`Read(~/**)`) and run the delivery CLI (`Bash(aifabrix *)`). They do not add sibling folders as extra workspaces, do not grant Write outside this repo, and do not allow every shell command. TTY asks (default yes). `--yes` or a non-TTY / `--json` run writes them. `--skip-approve-all` skips. `--force` overwrites existing local files. Builder never writes `~/.claude` or `~/.codex`.
17
+
18
+ ## Cursor
19
+
20
+ **Local.** Open this folder in Cursor. Skills appear as `/aifabrix-plan` and the other `/aifabrix-*` commands.
21
+
22
+ **SSH.** Use Cursor Remote SSH to the machine that holds the repo. The session is the Cursor window — no tmux required. Same `/aifabrix-*` skills.
23
+
24
+ ## Claude Code
25
+
26
+ **Local.**
27
+
28
+ ```bash
29
+ cd /path/to/this-workspace
30
+ claude
31
+ ```
32
+
33
+ Then `/aifabrix-plan` (or another `/aifabrix-*` skill). First run in a project asks you to trust the folder; accept only this workspace.
34
+
35
+ **SSH (keep the session after you disconnect).** tmux holds the process on the remote machine:
36
+
37
+ ```bash
38
+ tmux new -s claude -c /path/to/this-workspace
39
+ claude --remote-control
40
+ ```
41
+
42
+ Detach without killing Claude: `Ctrl-b` then `d`. Reattach: `tmux attach -t claude`.
43
+
44
+ **Phone and web.** `--remote-control` (or `claude remote-control` in server mode) publishes the same session to [claude.ai/code](https://claude.ai/code) and the Claude mobile app (**Code**). Press space in server mode for a QR code. In an interactive session, `/remote-control` or `/mobile`. Requires a Claude Pro/Max/Team login (`claude auth login`), not an API key.
45
+
46
+ Closing SSH does not stop a tmux session. Stopping tmux or the machine does.
47
+
48
+ ## Codex
49
+
50
+ **Local.**
51
+
52
+ ```bash
53
+ cd /path/to/this-workspace
54
+ codex
55
+ ```
56
+
57
+ Then `$aifabrix-plan` (and the other `$aifabrix-*` skills). Codex reads `AGENTS.md`.
58
+
59
+ **SSH (keep the session after you disconnect).**
60
+
61
+ ```bash
62
+ tmux new -s codex -c /path/to/this-workspace
63
+ codex
64
+ ```
65
+
66
+ Detach: `Ctrl-b` then `d`. Reattach: `tmux attach -t codex`. Codex has no Claude-style phone/web Remote Control; stay in tmux (or reattach later) to see the session.
67
+
68
+ ## tmux cheat sheet
69
+
70
+ | Action | Keys / command |
71
+ | --- | --- |
72
+ | New named session | `tmux new -s <name> -c /path/to/this-workspace` |
73
+ | Detach (leave it running) | `Ctrl-b`, then `d` |
74
+ | List sessions | `tmux ls` |
75
+ | Attach | `tmux attach -t <name>` |
76
+ | Kill session | `tmux kill-session -t <name>` |
77
+
78
+ Use separate session names (`claude` vs `codex`) if both run on the same host.
@@ -0,0 +1,22 @@
1
+ # Plans (customer workspace)
2
+
3
+ Delivery plans for Connected Systems in this workspace.
4
+ **Operational limits for a system live in `integration/<systemKey>/README.md`**, not in Agent Kit skills.
5
+
6
+ ## Active
7
+
8
+ | Plan | Focus |
9
+ | --- | --- |
10
+ | — | No active delivery plan yet |
11
+
12
+ ## Done
13
+
14
+ | Plan | Focus | Archived |
15
+ | --- | --- | --- |
16
+ | — | — | — |
17
+
18
+ ## Naming
19
+
20
+ - `{N}.{m}-{slug}.plan.md` under `.cursor/plans/`
21
+ - Archive completed plans under `done/` when finished
22
+ - New delivery work from a business specification starts with **`aifabrix-plan`**
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) {{year}} {{copyrightHolder}}
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.