From 8b9c0fc66e7e80408d2f6c154e971ab0174e4ab5 Mon Sep 17 00:00:00 2001 From: Laura Cox Date: Thu, 9 Jul 2026 10:13:36 -0400 Subject: [PATCH 1/3] docs: add pending integration stub pattern design spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Derived from useCase-lightningAi — captures the pattern for building and demonstrating delivery progress when customer integrations aren't yet finalized. Co-Authored-By: Claude Sonnet 4.6 --- ...pending-integration-stub-pattern-design.md | 193 ++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-09-pending-integration-stub-pattern-design.md diff --git a/docs/superpowers/specs/2026-07-09-pending-integration-stub-pattern-design.md b/docs/superpowers/specs/2026-07-09-pending-integration-stub-pattern-design.md new file mode 100644 index 0000000..694b649 --- /dev/null +++ b/docs/superpowers/specs/2026-07-09-pending-integration-stub-pattern-design.md @@ -0,0 +1,193 @@ +# Pending Integration Stub Pattern — Design Spec + +**Date:** 2026-07-09 +**Status:** Approved +**Source:** useCase-lightningAi (EmailOpensource adapter not installed on customer cloud instance) + +--- + +## Problem + +A customer's integration list is known but not yet finalized on their side — adapters aren't installed, hostnames aren't confirmed, auth methods are TBD. Under the current skills, this blocks delivery. Engineers either wait for the customer to finalize integrations before building anything, or build informally without guidance on how to structure the stub. + +The goal: let delivery proceed in full, demonstrate progress to the customer via runnable stub workflows, and leave a clear activation path for each pending integration. + +--- + +## Scope + +**In scope:** +- Guidance for solution-arch-agent (feasibility status + design deliverables) +- Guidance for builder-agent (stub workflow structure + placeholder task pattern) +- Guidance for qa-agent (pending criteria handling) +- Four new AGENTS.md key rules from Lightning AI learnings + +**Out of scope:** +- Promoting integration-model files to helpers/ (pattern only — files stay per use-case) +- Changes to spec-agent + +--- + +## Design + +### 1. New Feasibility Status: `⚠ Stub` + +Add a third integration status to `solution-arch-agent` alongside the existing `⚠ Blocked`: + +| Status | Meaning | Action | +|--------|---------|--------| +| `✓ Resolved` | Found, running | Proceed | +| `⚠ Stub` | Required, not yet available | Proceed with stub pattern | +| `⚠ Blocked` | Required, cannot proceed without it | Stop and discuss | +| `✗ Skipped` | Not required | Use fallback | + +A `⚠ Stub` integration is required but either not installed on the platform or pending customer confirmation of connection details. Delivery proceeds — the Design stage produces stub artifacts for it. + +--- + +### 2. Design Stage Deliverables (solution-arch-agent) + +For each `⚠ Stub` integration, the Design stage produces two new artifacts added to the component inventory: + +#### `integration-model-{name}.json` — OpenAPI 3.0.3 stub + +Minimal, use-case scoped. Contains only the endpoints the workflows will actually call — not the full vendor API. + +| Field | Rule | +|-------|------| +| `info.title` | The adapter type name as it will appear in Itential (e.g., `Slack`, `AWX`, `HashiCorpVault`) — becomes the `app` and `locationType` field values | +| `info.description` | One line describing what this integration does in this use case. Append `— STUB: scope TBC with customer` if the scope is still being confirmed. | +| `servers[].url` | Base URL. Use a `variables` block for unknown hostname; add `"description": "STUB: confirm with customer"` to any unknown variable. | +| `components.securitySchemes` | Auth method. Mark description `STUB: confirm auth method with customer` if not yet confirmed. | +| `paths` | Only the operations the stub workflow will test. Use accurate request/response schemas where known; omit optional fields that aren't needed. | + +#### `integration-questions.md` — customer questionnaire + +One section per pending integration. Each section has a three-column table: + +| Column | Purpose | +|--------|---------| +| **Question** | What needs to be answered | +| **Why needed** | What it unblocks (so the customer understands urgency) | +| **Customer answer** | Blank — for the customer to fill in | + +Standard questions per integration: +- What is the hostname / base URL for this system? +- What auth method is used (bearer token / basic auth / API key / mTLS)? +- Where is the token issued / how is it obtained? +- Are there specific API versions or path prefixes that differ from the standard? +- Any firewall rules or IP allowlisting required for the Itential platform to reach this system? + +Close the file with a **Next steps** note: once all questions are answered, the engineer updates the integration model, provisions the adapter, and replaces placeholder tasks using the as-built activation recipes. + +--- + +### 3. Stub Workflow per Integration (builder-agent) + +Named `stub-{integration-name}` (e.g., `stub-slack`, `stub-awx`). Exercises one core connectivity action. Structure: + +``` +workflow_start + → buildPayload (newVariable — assembles minimum input for the core action) + → callIntegration (newVariable placeholder — pending_adapter sentinel) + ↓ error + → workflow_end +workflow_end +``` + +**Rules:** +- `buildPayload` — always a `newVariable` task. Assembles the minimum required input for the core action (e.g., for Slack: `{channel, text}`). No adapter dependency — always runnable. +- `callIntegration` — the `newVariable` placeholder. Sets `{integrationName}Status = "pending_adapter"`. This is the task ID that the real adapter task will occupy when activated. Error transition pre-wired to `workflow_end`. +- One input variable: `dryRun` (boolean, default `true`) — signals this is a connectivity test. Stub ignores it; activated workflow can use it to skip side effects during testing. +- Group all stub workflows in the same project as the main delivery workflows. + +**Choosing the core action:** +- Use the simplest write/action operation (post a message, launch a job, write a secret) +- Prefer an operation that validates auth end-to-end (not just a GET list) +- If the integration is read-only in the use case, use a lightweight read (get current user, health check) + +--- + +### 4. Placeholder Task Pattern (builder-agent) + +When any workflow needs to call an adapter that isn't installed: + +1. Place a `newVariable` task in the exact position the real adapter task will occupy +2. Use the same task ID (hex) that will be used for the real task +3. Set the variable: `{integrationName}Status = "pending_adapter"` — machine-readable pending state +4. Wire transitions identically to how the real task will be wired (including error transitions) + +**As-built "Activate Integration" section** — one entry per pending integration: + +```markdown +## Activate: {Integration Name} + +When the {AdapterType} adapter is provisioned: + +1. Confirm adapter instance name: + jq '.results[] | select(.package_id | test("{name}";"i")) | {id,state}' adapters.json + +2. Replace task `{taskId}` in workflow `{workflowId}` with: + {complete replacement task JSON, all fields pre-filled from integration-model-{name}.json} + Only field to fill in: `adapter_id` — the instance name from step 1. + +3. Verify field names from the live schema: + POST /automation-studio/multipleTaskDetails?dereferenceSchemas=true + body: {"tasks": [{"name": "{taskName}", "app": "{appType}"}]} +``` + +**Reusability:** this pattern works identically for standard Itential adapters (EmailOpensource, Slack) and custom OpenAPI virtual integrations. The integration model file is the contract in both cases. + +--- + +### 5. qa-agent: Pending Criteria Handling + +For acceptance criteria that depend on a `⚠ Stub` integration: + +- Mark status `⏳ Pending adapter` in the test report +- Do not mark as failed — the workflow is structurally correct; the integration is the blocker +- Include the specific activation steps (from the as-built) inline in the test report entry +- All other criteria are evidenced normally + +Example test report entry: +``` +| Criterion | Status | Evidence | +|-----------|--------|----------| +| Email sent to recipient | ⏳ Pending adapter | EmailOpensource not installed. Workflow reaches sendEmail task; placeholder sets emailStatus=pending_adapter. Activate per as-built §Activate: Email. | +``` + +--- + +### 6. AGENTS.md Key Rules (Lightning AI learnings) + +Four rules to add, applying to any cloud/SaaS Itential engagement: + +**Rule 26 — Cloud/SaaS auth:** The `/login` endpoint may return 500 on cloud instances — it is broken server-side on SaaS, not a credential issue. Always use `POST /oauth/token` with `grant_type=client_credentials` on cloud instances. + +**Rule 27 — Workflow variable path:** Job output variables live at `.data.variables.{varName}` (flat), not `.data.variables.job.{varName}`. The `.job` nesting does not exist. Wrong path silently returns null. + +**Rule 28 — Template `group` field:** Cannot be an empty string. Passing `group: ""` causes a validation error. Use a real group name or `"Default"`. + +**Rule 29 — Service account creation:** On cloud instances, creating a service account for API access requires navigating to **Admin Essentials → Service Accounts** — it is not accessible from the main nav. Standard user management screens do not expose this. + +--- + +## Files Changed + +| File | Change | +|------|--------| +| `.claude/skills/solution-arch-agent/SKILL.md` | Add `⚠ Stub` status to Resolve Integrations; add integration model + questionnaire to Design deliverables | +| `.claude/skills/builder-agent/SKILL.md` | Add stub workflow pattern + placeholder task pattern + as-built activation recipe | +| `.claude/skills/qa-agent/SKILL.md` | Add pending criteria handling | +| `AGENTS.md` | Add rules 26–29 | + +--- + +## Connections to Use Case + +All patterns in this spec are directly derived from `useCase-lightningAi`: +- Stub status and `integration-model-*.json` files — 10 integration models produced during design +- `LightningAI-Integration-Questions.xlsx` — the questionnaire pattern (format changed to Markdown) +- `newVariable` placeholder for EmailOpensource — the placeholder task pattern +- As-built activation recipe for `d4e5` task — the activation section pattern +- Rules 26–29 — direct from `as-built.md` Learnings section From aaa980ff454dc69a83c6ebb5e0aea369bbd9d7c1 Mon Sep 17 00:00:00 2001 From: Laura Cox Date: Thu, 9 Jul 2026 10:19:51 -0400 Subject: [PATCH 2/3] feat: add pending integration stub pattern across delivery lifecycle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When a customer's integrations aren't yet finalized, delivery no longer has to stop. Introduces a consistent stub pattern across all three agents: - solution-arch-agent: new ⚠ Stub feasibility status (distinct from Blocked); Design stage produces integration-model-{name}.json stubs and integration-questions.md customer questionnaire per pending adapter - builder-agent: new Pending Integration Pattern section — stub workflow per integration (one core connectivity action), newVariable placeholder task pattern with pending_adapter sentinel, as-built Activate section with pre-filled replacement task JSON - qa-agent: pending-adapter test case type, ⏳ Pending adapter report status — criteria blocked by a pending adapter are accepted residuals, not failures - AGENTS.md: four new rules from Lightning AI engagement (rules 26-29) — cloud OAuth-only auth, flat .data.variables path, template group field, service account Admin Essentials navigation Derived from useCase-lightningAi — EmailOpensource stub + 10 integration model files. Co-Authored-By: Claude Sonnet 4.6 --- .claude/skills/builder-agent/SKILL.md | 66 +++++++++++++++++++++ .claude/skills/qa-agent/SKILL.md | 5 +- .claude/skills/solution-arch-agent/SKILL.md | 31 +++++++++- AGENTS.md | 4 ++ 4 files changed, 104 insertions(+), 2 deletions(-) diff --git a/.claude/skills/builder-agent/SKILL.md b/.claude/skills/builder-agent/SKILL.md index 4d5bc16..7ab35c8 100644 --- a/.claude/skills/builder-agent/SKILL.md +++ b/.claude/skills/builder-agent/SKILL.md @@ -149,6 +149,72 @@ The memory file is what makes it possible to pick up a use-case after weeks with --- +## Pending Integration Pattern + +Use this pattern when the solution design includes `⚠ Stub` integrations — adapters that are required but not yet installed on the platform, or whose connection details (hostname, auth method, credentials) are still being confirmed by the customer. + +**Goal:** deliver a fully buildable, testable project now. The customer sees real workflows and real progress. When the adapter arrives, swapping in the real task is a single targeted update. + +### Stub Workflow (`stub-{integration-name}`) + +Build one stub workflow per pending integration. It exercises one core connectivity action — enough to prove the integration wires up correctly end-to-end when the adapter is provisioned. + +**Structure:** +``` +workflow_start + → buildPayload (newVariable — assembles minimum input for the core action) + → callIntegration (newVariable placeholder — sets {integrationName}Status = "pending_adapter") + ↓ error + → workflow_end +workflow_end +``` + +**Rules:** +- `buildPayload` — `newVariable` task. Assembles the minimum required input per the `integration-model-{name}.json` (e.g., for Slack: `{channel, text}`). No adapter dependency — always runnable without a real adapter. +- `callIntegration` — `newVariable` placeholder. Sets `{integrationName}Status = "pending_adapter"`. Use the hex task ID that the real adapter task will occupy. Error transition pre-wired to `workflow_end`. +- One input variable: `dryRun` (boolean, default `true`). Stub ignores it; activated workflow can use it to skip side effects during testing. +- Add all stub workflows to the same project as the main delivery workflows. + +**Choosing the core action:** +- Prefer the simplest write/action that validates auth end-to-end (post a message, launch a job, write a secret) +- If the integration is read-only in this use case, use a lightweight read (get current user, health check) +- Derive the request payload from `integration-model-{name}.json` — that file is the contract + +### Placeholder Task (in any workflow) + +When a workflow needs to call an adapter that isn't installed, replace the real adapter task with a `newVariable` placeholder — same position, same task ID, same transitions: + +1. Use a `newVariable` task in the exact slot the real adapter task will occupy +2. Assign the same hex task ID the real task will use when activated +3. Set variable: `{integrationName}Status = "pending_adapter"` — machine-readable pending state +4. Wire all transitions identically (including the error transition) to how the real task will be wired + +### As-Built: Activate Integration Section + +For every pending integration, include a dedicated section in `as-built.md`: + +```markdown +## Activate: {Integration Name} + +When the {AdapterType} adapter is provisioned: + +1. Confirm adapter instance name: + jq '.results[] | select(.package_id | test("{name}";"i")) | {id,state}' adapters.json + +2. Replace task `{taskId}` in workflow `{workflowId}` with: + (complete replacement task JSON — all fields pre-filled from integration-model-{name}.json, + app and locationType set to the adapter type name, incoming variables wired from the workflow) + Only field left blank: `adapter_id` — fill from step 1. + +3. Verify exact field names from the live schema before activating: + POST /automation-studio/multipleTaskDetails?dereferenceSchemas=true + body: {"tasks": [{"name": "{taskName}", "app": "{appType}"}]} +``` + +This pattern works for both standard Itential adapters (EmailOpensource, Slack) and custom OpenAPI virtual integrations. The `integration-model-{name}.json` file is the contract in both cases. + +--- + ## Guides ### Guide 1: Build a workflow end-to-end diff --git a/.claude/skills/qa-agent/SKILL.md b/.claude/skills/qa-agent/SKILL.md index 683d63f..628f359 100644 --- a/.claude/skills/qa-agent/SKILL.md +++ b/.claude/skills/qa-agent/SKILL.md @@ -107,6 +107,8 @@ Read `customer-spec.md` Section 9 (Acceptance Criteria) and `solution-design.md` **Not every criterion needs a live job.** Some are checked by inspecting an artifact already produced by another test case (`artifact-inspection`), and some genuinely can't be automated (e.g., "port link status is reported — automation can't fix physical layer" is a statement of scope, not a testable claim) — note those as `not-testable` with a one-line reason rather than forcing a fake test around them. +**Criteria that depend on a pending integration** (`⚠ Stub` in the solution design) get type `pending-adapter`. They are not failed — the workflow is structurally correct; the adapter is the blocker. In the test plan, note what the criterion requires and reference the as-built activation recipe. In the test report, mark them `⏳ Pending adapter` with the activation steps inline. They do not block delivery — they are explicitly accepted residual items unless the engineer says otherwise. + **Static checks are one shared checklist, not itemized per criterion.** They validate structural correctness of what was built, independent of any specific acceptance criterion. Pull the machine-checkable subset of `builder-agent`'s Step 9 pre-submit checklist — skip the visual/canvas-layout items (spacing, crossing lines), since those are aesthetic, not correctness bugs: ```markdown @@ -210,7 +212,7 @@ Once every case passes, or the engineer explicitly accepts a residual known issu ``` **Fields:** -- `type` — `static` (structural, no live call), `acceptance` (live job + outcome check), `artifact-inspection` (checks an artifact from a prior case), or `not-testable` (documented scope limitation, no execution) +- `type` — `static` (structural, no live call), `acceptance` (live job + outcome check), `artifact-inspection` (checks an artifact from a prior case), `not-testable` (documented scope limitation, no execution), or `pending-adapter` (criterion requires an integration marked `⚠ Stub` — not failed, not skipped; documented as an accepted residual with activation steps) - `criterion` — the acceptance-criteria ID this case verifies, or `null` for static checks that apply to the whole build - `check` / `verify` — human-readable enough that a different engineer could execute it manually if needed; this file is evidence, not just automation input @@ -238,6 +240,7 @@ Once every case passes, or the engineer explicitly accepts a residual known issu |---|---|---|---| | AC-1 | Port is in the correct VLAN and mode after turn-up | PASS | Job `67d0...`, post-check shows vlan=100 mode=access | | AC-8 | ITSM ticket is updated with results | FAIL | Job `67d1...` completed, but GET on the change request shows state unchanged — handed back to builder-agent 2026-07-02 | +| AC-9 | Notification sent via Slack | ⏳ Pending adapter | Slack adapter not installed. Stub workflow `stub-slack` runs cleanly; placeholder sets slackStatus=pending_adapter. Activate per as-built §Activate: Slack. | ## Re-runs diff --git a/.claude/skills/solution-arch-agent/SKILL.md b/.claude/skills/solution-arch-agent/SKILL.md index 795d6ec..f2b98e2 100644 --- a/.claude/skills/solution-arch-agent/SKILL.md +++ b/.claude/skills/solution-arch-agent/SKILL.md @@ -222,9 +222,12 @@ For each row in the spec's Capabilities table: For each row in the spec's Integrations table: - Found + Running? → **✓ Resolved** (record adapter name, app name) - Found + Stopped? → **⚠ Warning** (needs to be started) -- Not found + Required? → **⚠ Blocked** (stop and discuss) +- Not found, required, adapter unavailable or customer details TBD? → **⚠ Stub** (proceed — Design produces stub artifacts) +- Not found, required, and nothing can be built without it? → **⚠ Blocked** (stop and discuss) - Not found + Not Required? → **✗ Skipped** +**`⚠ Stub` vs `⚠ Blocked`:** Stub means the integration is required but not yet available — delivery proceeds by building stub workflows and placeholder tasks now, activating the real adapter later. Blocked means the entire delivery is gated on resolving this first (e.g., the main workflow can't be designed without data only this adapter provides). Rule of thumb: if at least one component can be built and tested without the adapter, it's Stub, not Blocked. + ### Find Reuse Opportunities Search `workflows.json` for existing workflows that match spec phases. Flag as **↻ Reuse** candidates. @@ -297,6 +300,32 @@ The orchestrator is always the last thing built, after all children are tested. └────┴──────────────────────────────┴─────────────────────┴──────────┘ ``` +For every `⚠ Stub` integration, add to the inventory: +- `integration-model-{name}.json` — OpenAPI 3.0.3 stub spec (Type: Integration Model, Action: Build) +- `stub-{name}` — stub connectivity workflow (Type: Stub Workflow, Action: Build) +- `integration-questions.md` — customer questionnaire (Type: Questionnaire, Action: Build — one file covers all pending integrations) + +**Producing stub artifacts:** + +`integration-model-{name}.json` — OpenAPI 3.0.3, minimal and use-case scoped: +- `info.title` — the adapter type name as it will appear in Itential (e.g., `Slack`, `AWX`) — this becomes the `app` and `locationType` field values in workflow tasks +- `info.description` — one line: what this integration does in this use case; append `— STUB: scope TBC with customer` if endpoints aren't yet confirmed +- `servers[].url` — use a `variables` block for unknown hostnames; add `"description": "STUB: confirm with customer"` to any unknown variable +- `components.securitySchemes` — mark `description` as `STUB: confirm auth method with customer` if not yet confirmed +- `paths` — only the operations the stub workflow will call; use accurate schemas where known + +`integration-questions.md` — one section per pending integration, three-column table: + +| Question | Why needed | Customer answer | +|----------|-----------|-----------------| +| Hostname / base URL | Needed to configure the adapter server | | +| Auth method (bearer / basic / API key) | Determines how credentials are stored | | +| Token source / how to obtain it | Needed to provision the adapter | | +| API version or path prefix differences | Affects endpoint wiring in workflows | | +| Firewall / IP allowlisting requirements | Platform must be able to reach this system | | + +Close `integration-questions.md` with a **Next steps** note: once all questions are answered, update each integration model, provision the adapter, and replace placeholder tasks using the as-built activation recipes. + **E. Implementation Plan** — ordered build steps with test method for each **F. Acceptance Criteria → Tests** — map each criterion to how to verify it. This is a first-pass mapping — `/qa-agent` refines it into an executable `test-plan.md` once real IDs exist after Build, but the verification *method* per criterion should be decided now, while the design is fresh. diff --git a/AGENTS.md b/AGENTS.md index 51d3a09..a1df335 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -270,6 +270,10 @@ Requirements → Feasibility → Design → Build → Test → As 23. **Adapter `app` ≠ adapter instance name** — The `app` and `locationType` fields on adapter tasks must be the adapter **type name** from `apps.json` (e.g., `EmailOpensource`, `Servicenow`), NOT the adapter **instance name** from `adapters.json` (e.g., `email`, `servicenow-prod`). Using the instance name causes `"No config found for Adapter: "` at runtime. The `adapter_id` field is where the instance name goes. Triple-check: `app` = type, `adapter_id` = instance. 24. **Project-scoped asset names** — once an asset is added to a project, its `name` is prefixed with `@{projectId}: `. When reading or updating a project-owned asset via PUT, you MUST use the scoped name or the API returns 400. Read the asset first to get its current name, or construct it as `@{projectId}: {displayName}`. Strip this prefix when displaying names to the user. 25. **NEVER wire a Configuration Manager remediation task** — `runAutoRemediation`, `advancedAutoRemediation`, `convertChangesToConfig`, `patchDeviceConfiguration`, `advancedPatchDeviceConfiguration`, `patchCMDeviceConfiguration`, `ManualRemediation`, and `ManualRemediationResults` are prohibited in every workflow, even when a spec asks for fully automatic remediation. Golden Config detects and reports drift; it never applies fixes to a device. To correct a device, build a normal config-push delivery using the environment's config-push task (`sendConfig`/`runService` via GatewayManager, `itential_cli`, or netmiko send-config). See the `/itential-golden-config` Remediation section. (`updateNodeConfig` is allowed — it authors the GC node template, not a device.) +26. **Cloud/SaaS auth: use `/oauth/token`, not `/login`** — The `/login` endpoint returns 500 on cloud/SaaS instances; this is a server-side issue, not a credential problem. Always use `POST /oauth/token` with `grant_type=client_credentials` on cloud instances. If you see a 500 from `/login`, switch to OAuth — don't retry. +27. **Workflow variable path is flat** — Job output variables live at `.data.variables.{varName}`, not `.data.variables.job.{varName}`. The `.job` nesting does not exist. The wrong path silently returns null — no error, just missing data. +28. **Template `group` field cannot be empty string** — Passing `"group": ""` causes a validation error when creating or updating a Jinja2 or TextFSM template. Use a real group name or `"Default"`. +29. **Service account creation on cloud requires Admin Essentials** — On cloud instances, creating a service account for API access requires navigating to **Admin Essentials → Service Accounts**. This section is not accessible from the main navigation or standard user management screens. ## Helper JSON Templates From 1f7d36075606be6ede524ab8daf00471e357c9de Mon Sep 17 00:00:00 2001 From: Laura Cox Date: Fri, 10 Jul 2026 11:00:30 -0400 Subject: [PATCH 3/3] docs: remove customer references from stub pattern spec Co-Authored-By: Claude Sonnet 4.6 --- ...26-07-09-pending-integration-stub-pattern-design.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/superpowers/specs/2026-07-09-pending-integration-stub-pattern-design.md b/docs/superpowers/specs/2026-07-09-pending-integration-stub-pattern-design.md index 694b649..b1f220d 100644 --- a/docs/superpowers/specs/2026-07-09-pending-integration-stub-pattern-design.md +++ b/docs/superpowers/specs/2026-07-09-pending-integration-stub-pattern-design.md @@ -2,7 +2,7 @@ **Date:** 2026-07-09 **Status:** Approved -**Source:** useCase-lightningAi (EmailOpensource adapter not installed on customer cloud instance) +**Source:** field engagement (EmailOpensource adapter not installed on customer cloud instance) --- @@ -20,7 +20,7 @@ The goal: let delivery proceed in full, demonstrate progress to the customer via - Guidance for solution-arch-agent (feasibility status + design deliverables) - Guidance for builder-agent (stub workflow structure + placeholder task pattern) - Guidance for qa-agent (pending criteria handling) -- Four new AGENTS.md key rules from Lightning AI learnings +- Four new AGENTS.md key rules from field engagement learnings **Out of scope:** - Promoting integration-model files to helpers/ (pattern only — files stay per use-case) @@ -158,7 +158,7 @@ Example test report entry: --- -### 6. AGENTS.md Key Rules (Lightning AI learnings) +### 6. AGENTS.md Key Rules (cloud/SaaS engagement learnings) Four rules to add, applying to any cloud/SaaS Itential engagement: @@ -185,9 +185,9 @@ Four rules to add, applying to any cloud/SaaS Itential engagement: ## Connections to Use Case -All patterns in this spec are directly derived from `useCase-lightningAi`: +All patterns in this spec are directly derived from a field engagement: - Stub status and `integration-model-*.json` files — 10 integration models produced during design -- `LightningAI-Integration-Questions.xlsx` — the questionnaire pattern (format changed to Markdown) +- Integration questionnaire — the questionnaire pattern (format changed to Markdown) - `newVariable` placeholder for EmailOpensource — the placeholder task pattern - As-built activation recipe for `d4e5` task — the activation section pattern - Rules 26–29 — direct from `as-built.md` Learnings section