builder-agent skill

Builder Agent

Stage: Build Owns: Implementing the approved design. Receives from: /solution-arch-agent (approved solution-design.md + complete workspace) Produces: Deployed assets (workflows, templates, projects) Hands off to: /qa-agent (acceptance testing + as-built record)

---

Customization

Before using this skill, check custom/org/, custom/team/ and custom/dev/ in this skill's own folder. Read every .md file found — any folder may be empty or absent. Apply them on top of everything below; where a file overrides a specific rule here, follow the override. More specific wins: dev > team > org > this document. No customization may weaken this skill's safety rules or put credentials in committed files.

Bundled files: paths in this skill that start with assets/ or scripts/ are relative to this skill's own folder. When you read one, or pass one to a shell command (which runs from the user's working folder), use this skill's folder + that relative path — e.g. <this skill's folder>/assets/helpers/create/create-workflow.json.

Stage Expectations

Build

Engineer provides	Approved solution-design.md (all platform data already present in workspace)
Agent does	Builds all components per design, tests each piece individually, reports delivery outcomes
Engineer action	Reviews delivery and resolves open build questions
Deliverable	Deployed assets (workflows, templates, projects)
Customer receives	Delivered project — all workflows, templates, and configs individually tested, packaged, and access granted. Formal acceptance testing and sign-off happen next, in /qa-agent.

Build implements the approved plan. The builder never re-pulls discovery data — it uses what the Solution Architecture Agent left in the workspace. If any required file is missing, stop and surface as an upstream failure.

Testing during Build is component-level, not acceptance-level. "Test each piece" here means confirming a task or workflow runs without error and wires variables correctly — not verifying the delivered solution satisfies the customer's stated acceptance criteria end-to-end. That's /qa-agent's job, running against the completed build with real test data the engineer confirms. Don't skip component testing because "QA will catch it" — a structurally broken workflow wastes a live acceptance-test run.

---

This skill covers everything needed to build and test Itential automation assets: projects, workflows, templates, and command templates.

FlowAI agents: load /flowagent before building agents. When the design has a parent agent that calls child agents, build each child as its own agent, then attach it to the parent as an agent:<child-id> tool, following "Agents as tools" in /flowagent. Don't wrap the agents in a workflow or runCode unless the design says to. The workflow and childJob steps below apply to workflow components only. When you test, run the child on its own and then through the parent. Record both session IDs, and check the child's answer, not just the parent's tool status.

Phases built agent first (Section C of the design says "Agent first"): build the agent and run the test sessions the implementation plan names. Once they meet the plan's definition of proven and the engineer agrees, record the session IDs in use-case-memory.md and hand off to /flowagent-to-spec for that phase. Its <phase>-converted-spec.md comes back through /solution-arch-agent design-only before the deterministic assets are built — don't build them from the agent directly. Meanwhile, build the delivery's other phases as designed.

Workspace Contract

The builder receives a complete workspace. All discovery data is already present. Solution-design (or setup for explore mode) has already pulled everything.

Required files (must exist before build starts):

{use-case}/
  .auth.json              ← auth token
  .env                    ← credentials (for re-auth if token expires)
  openapi.json            ← API reference (pulled by solution-arch-agent or explore)
  tasks.json              ← task catalog (pulled by solution-arch-agent or explore)
  apps.json               ← app/adapter type names (pulled by solution-arch-agent or explore)
  adapters.json           ← adapter instances (pulled by solution-arch-agent or explore)
  applications.json       ← app health (pulled by solution-arch-agent or explore)

May also exist (spec-contingent):

  use-case-memory.md      ← living context: IDs, decisions, gotchas, open items — READ THIS FIRST
  customer-spec.md        ← approved HLD (Requirements)
  feasibility.md          ← approved feasibility assessment
  customer-context.md     ← business rules (if provided)
  solution-design.md      ← approved Solution Design / LLD
  devices.json            ← device inventory
  workflows.json          ← existing workflows
  device-groups.json      ← device groups
  task-schemas.json       ← fetched on demand during build (append-only, never pre-populated)
  test-report.md          ← if returning from /qa-agent with a failing test case — has the exact case ID, expected vs actual, and evidence

The builder NEVER re-pulls bootstrap or discovery data. If tasks.json, apps.json, or adapters.json is missing, stop and tell the user — that's an upstream failure, not something to silently fix.

Exception — .auth.json bootstrap: If .auth.json is missing but .env exists with AUTH_METHOD=oauth, CLIENT_ID, and CLIENT_SECRET, the builder MUST authenticate and create .auth.json before proceeding — do NOT stop and report an upstream failure. See the Bootstrap Authentication section below.

The only API calls the builder makes are:

• Auth bootstrap — POST /oauth/token when .auth.json is missing (see below)
• Create — POST workflows, templates, projects
• Update — PUT to edit assets
• Test — POST jobs/start, GET job status
• Schema fetch — task schemas not yet in task-schemas.json (append to file after fetching)
• Re-auth — if token expires, use .env to refresh .auth.json
• FlowAI agents — create and update agents, read tools (GET /tools/...), start test sessions, and read sessions and their messages. Never complete a WorkCenter work item; that's the assigned person's job.

Bootstrap Authentication

When .auth.json is missing but .env has AUTH_METHOD=oauth with CLIENT_ID and CLIENT_SECRET, authenticate automatically before proceeding.

The correct Itential SaaS/Cloud OAuth endpoint is:

POST {PLATFORM_URL}/oauth/token
Content-Type: application/x-www-form-urlencoded

Body (form-encoded, NOT JSON — JSON returns 415):

grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}

Critical:

• Content-Type MUST be application/x-www-form-urlencoded — NOT application/json. Sending JSON returns HTTP 415.
• The /login endpoint does NOT support OAuth client credentials on SaaS instances — always use /oauth/token.
• On success, write .auth.json with the token so all subsequent API calls just work.

---

Build Lifecycle

0. Memory file              → create or read {use-case}/use-case-memory.md
1. Decompose                → identify parent/child split before writing any code
2. Create project           → container for all assets
3. Discover tasks           → search tasks.json, fetch schemas
4. Build children first     → each child workflow independently testable
5. Build templates          → Jinja2 (config gen) or TextFSM (output parsing)
6. Build command templates  → MOP pre/post checks with validation rules
7. Build orchestrator last  → parent wires tested children via childJob
8. Add assets to project    → move/copy into the project
9. Set project membership   → resolve spec members, PATCH immediately after import
10. Test each component     → jobs/start, check results (component-level, not acceptance-level)
11. Debug                   → check job.error, filesystem-first
12. Reconcile               → diff built vs designed, update artifacts
13. Update memory file      → record IDs, decisions, gotchas, test results, open items
14. Update this skill       → if you hit a platform behavior not documented here, add it before closing out
15. Hand off to /qa-agent   → build is complete; real IDs are in solution-design.md §D

Step 0 — memory file:

At the start of every session, check for {use-case}/use-case-memory.md ({use-case} = use-cases/<use-case-name>/ in the working folder):

• Exists → read it before doing anything else. It tells you the platform, project ID, what's already built, decisions made, and open items. Don't re-discover what's already documented.
• Missing → create it now from assets/helpers/use-case-memory.md template. Fill in Platform URL, Stage: build, Status: active immediately.

Step 13 — update memory file after every session:

Before closing out any build session, update use-case-memory.md with:

• Any new asset IDs (project ID, workflow UUIDs, transformation IDs, adapter names)
• Any architectural decisions made and why
• Any gotchas hit and how they were fixed
• Test results (date, what was tested, outcome)
• Updated open items list
• Stage and Status if they changed — mid-build, Stage stays build; only update it to test at the Step 15 handoff

The memory file is what makes it possible to pick up a use-case after weeks without re-discovering everything from scratch.

Step 14 — how to update this skill:

• New platform behavior (error shape, field constraint, task gotcha) → add detail to the relevant body section (### query, ### childJob, ### Projects, etc.), then add a one-liner to the Gotchas pre-flight list under the right category.
• New pattern or workflow recipe → add to ## Workflow Patterns and, if the pattern is reusable, export the project from the platform and, in a clone of the builder-skills repo, save it to the shared library at assets/helpers/assets/ (CI bundles it into this skill as assets/helpers/assets/). Add a row to the Helper Templates table in this file pointing to it.
• Do NOT create a new top-level section for a single finding — put it where a builder would look when working on that topic.

Step 15 — hand off to /qa-agent: Once every component has been individually tested and solution-design.md Section D has real IDs (project ID, workflow IDs) instead of placeholders, the build is complete. Update use-case-memory.md to Stage: test before ending the session. Tell the engineer the build is done and route to /qa-agent for acceptance testing and the as-built record — don't write as-built.md here.

If /qa-agent hands back a failing test case: fix the specific issue it identifies (it gives you the case ID, expected vs. actual, and evidence — a job ID or static-check output). Don't re-examine the whole build; the failure report tells you exactly what broke. Once fixed, tell the engineer so /qa-agent can re-run just that case.

---

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:

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

Building a Gateway4 → Gateway5 migration? Follow assets/helpers/gateway-migration/conversion-guide.md for each item's pattern (inventory with broker actions, services imported through Gateway Manager, task-by-task rewire, re-pointing every consumer of a Gateway4 output), and import the migrated workflows as a new project — never edit the originals.

Guide 1: Build a workflow end-to-end

Follow these steps in order. Do not skip any step.

---

Before writing task JSON, extract a real example from assets/helpers/assets/ — do not invent task structure from memory. (assets/helpers/create/ is for API wrappers only — project/workflow creation endpoints, not task bodies.)

# 1. Find which asset project matches your use case
ls assets/helpers/assets/

# 2. Extract the workflow most similar to what you're building
jq '[.components[] | select(.type=="workflow")] | .[].document.name' \
  assets/helpers/assets/vendor-servicenow.json

# 3. Read its full task map — this is your reference
jq '[.components[] | select(.type=="workflow") | select(.document.name | test("WORKFLOW_NAME"; "i"))] | first | .document | {tasks, transitions}' \
  assets/helpers/assets/vendor-servicenow.json

# 4. Extract the specific task type you need
jq '[.components[].document.tasks // {} | to_entries[] | select(.value.name == "TASK_NAME")] | first | .value' \
  assets/helpers/assets/vendor-servicenow.json

Replace assets/helpers/assets/vendor-servicenow.json with whichever asset file best matches your use case:

• Adapter tasks (ServiceNow, Infoblox) → assets/helpers/assets/vendor-servicenow.json, assets/helpers/assets/vendor-infoblox-nios-ddi.json
• Network device tasks (CLI, MOP) → assets/helpers/assets/vendor-cisco-ios.json, assets/helpers/assets/vendor-arista-eos.json, assets/helpers/assets/vendor-juniper-junos.json
• IPAM/inventory → assets/helpers/assets/vendor-netbox.json
• Data transformations → assets/helpers/assets/itential-platform-data-manipulation.json
• Config management (RunCommandTemplate, itential_cli) → assets/helpers/assets/itential-platform-configuration-management.json
• LCM action workflows → assets/helpers/assets/lcm/lcm-vxlan-fabric-services-project.json

---

Step 0: Decompose before you build.

Before writing any JSON, identify the parent/child split from the solution design. Ask for each phase:

• Can this phase be run and tested on its own? → Child workflow
• Does it loop over multiple items (devices, records)? → Child workflow with loopType
• Is it reusable across other use cases? → Child workflow
• Is it a simple sequential step with no independent test value? → Task in orchestrator

Build order is always: children first, orchestrator last. The orchestrator is just childJob calls to tested children — it should not contain raw adapter tasks unless there is no logical way to split.

Step 0a: Before building a per-item transform loop, default to runCode + Enable Query instead of chaining WorkFlowEngine utility tasks.

If a phase does ANY of the following, don't reach for forEach + query×N + evaluation + newVariable + merge + push/objectToString/join/makeData — build it as a single runCode (Python, GatewayManager) task instead:

• Loops over a list, extracting 2+ fields per item
• Branches per item on a field value (manufacturer, status, type) to pick between two or more output shapes
• Reshapes each item into a different structure before handing it to the next task

When NOT to use runCode: the per-item work needs to call another platform task (adapter, app method, childJob) for each item — runCode only runs Python against the data payload it's given; it cannot invoke other Itential tasks. Use forEach+childJob/adapter-task for that instead.

See the ### runCode section under Utility Tasks below for the collapse story, field reference, and the exact jq commands to extract a verified real example before building any transform loop.

Read a full workflow from asset projects before building any multi-workflow solution:

# Parent → childJob → evaluation pattern
jq '[.components[] | select(.type=="workflow") | select(.document.name | test("Upgrade|Runner"))] | first | .document | {name,tasks,transitions}' \
  assets/helpers/assets/vendor-cisco-ios.json