solution-arch-agent skill

Solution Architecture Agent

Stages: Feasibility → Design Owns: Assessing what is possible, then designing how it will be delivered. Receives from: /spec-agent (approved customer-spec.md) Hands off to: /builder-agent

---

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

(See assets/AGENTS.md's Developer Flow for the six-stage pipeline overview — this is this skill's detail for the two stages it owns.)

Feasibility

Engineer provides	Approved customer-spec.md, platform credentials
Agent does	Connects to platform, assesses capabilities, checks adapters and integrations, finds reuse candidates, records what LCM, FlowAgent and Gateway5 have on the platform, identifies constraints
Engineer action	Reviews assessment and approves decision to proceed
Deliverable	feasibility.md (assessment + decision)
Customer receives	Feasibility assessment with a clear decision (feasible / feasible with constraints / not feasible), flagged constraints, and identified reuse opportunities.

Feasibility confirms what is possible. Decision options: feasible, feasible with constraints, feasible with changes, or not feasible. Design does not start until feasibility is approved.

Design

Engineer provides	Approved feasibility.md
Agent does	Designs the execution model with the engineer (where LCM, FlowAgent and Gateway5 come in), then produces the implementation design — component inventory, adapter mappings, reuse decisions, build order, test plan
Engineer action	Reviews and approves the solution design
Deliverable	solution-design.md (Solution Design / LLD, approved)
Customer receives	Solution Design / LLD — component inventory, adapter mappings, build order, and acceptance criteria mapped to tests. Nothing is built until this is signed off.

Design defines how it will be delivered. Nothing is built until this is approved.

Design-Only Mode

If requirements are unchanged but the implementation plan needs to change, invoke /solution-arch-agent design-only. Skips Feasibility. Reads existing feasibility.md as context and produces an updated solution-design.md.

If feasibility.md has no Execution Capabilities section, run scripts/pull-platform-data.py and use platform-summary.json → execution_capabilities before Design the Execution Model.

Use design-only mode when an agent-first phase comes back from /flowagent-to-spec as {use-case}/<phase>-converted-spec.md: design that phase's deterministic components from it, replace that phase's rows in Sections C–F, and leave the other phases as approved.

---

Artifact Lifecycle

assets/spec-files/spec-*.md          ← Generic library spec (never modified)
        │
        │  forked by /spec-agent
        ▼
{use-case}/customer-spec.md   ← HLD — approved (Requirements)
        │
        │  authenticate, discover, assess
        ▼
{use-case}/feasibility.md     ← Feasibility assessment + decision — approved
        │
        │  design against approved feasibility
        ▼
{use-case}/solution-design.md ← Solution Design / LLD — approved (Design)
        │
        │  /builder-agent: implement locked plan
        ▼
{use-case}/*.json             ← Delivered assets
        │
        │  /qa-agent: acceptance testing
        ▼
{use-case}/test-report.md     ← Test evidence per acceptance criterion
        │
        │  /qa-agent: record as-built
        ▼
{use-case}/as-built.md        ← Delivered state, deviations, learnings

---

Spec File Structure

Spec Section	What to Extract
1. Problem Statement	Context — what are we solving and why
2. High-Level Flow	The major phases to implement
3. Phases	What each phase does, decision points, stop/rollback conditions
4. Key Design Decisions	Constraints to honor during implementation
5. Scope	What to build, what NOT to build
6. Risks & Mitigations	Error handling and fallback behavior to build in
7. Requirements	Capabilities, Integrations, Discovery Questions — drives design
8. Batch/Bulk Strategy	Orchestration pattern if multi-device/multi-record
9. Acceptance Criteria	How to verify the build is correct

Section 7 has three parts:

• Capabilities — what the platform must do → assessed during Feasibility
• Integrations — external systems → checked during Feasibility
• Discovery Questions — ask when platform data can't answer

---

Feasibility

Entered after /spec-agent produces an approved customer-spec.md. Read the spec, connect to the platform, and produce the feasibility assessment.

Step 1: Read the Approved Spec

Read {use-case}/customer-spec.md and extract:

• Phases from Section 3 (workflow stages)
• Design decisions from Section 4 (constraints)
• Capabilities table from Section 7 (platform checks)
• Integrations table from Section 7 (adapter and integration instance checks)
• Discovery questions from Section 7
• Acceptance criteria from Section 9 (test cases)

Step 2: Ask Only What the Spec Can't Answer

Go through the spec's Discovery Questions. Skip anything already answered by the spec. Ask only what platform data won't resolve.

Step 3: Authenticate

Now — and only now — connect to the platform. The approved spec tells you exactly what data you need.

Authenticate

See assets/AGENTS.md's "Auth Reuse" section for the full credential-lookup order, both authentication modes (local /login vs. cloud OAuth), and how to save the result to {use-case}/.auth.json — this is the canonical procedure, used identically by every skill. One environment-specific addition for this skill: pre-configured environment files at assets/environments/*.env are also a valid credential source to check before asking the engineer.

Pull Platform Data

Run the bootstrap script — it pulls all platform data in parallel and writes a compact platform-summary.json with only what's needed for feasibility:

python3 scripts/pull-platform-data.py {use-case}

What gets written:

File	Use for	Load into context?
platform-summary.json	Feasibility — running adapters, integration instances, apps, type names, projects	✅ Yes — compact
openapi.json	API reference — search locally with jq	❌ No — too large
tasks.json	Task catalog — search locally with jq	❌ No — too large
apps.json	Adapter type names — search locally with jq	❌ No
adapters.json	Adapter instances — search locally with jq	❌ No
integrations.json	Integration instances (virtual adapters such as NetBox or ServiceNow) — name, model, active flag, server host. Credentials are removed.	❌ No
applications.json	App health — search locally with jq	❌ No
workflows.json	Existing workflows — search locally with jq	❌ No
projects.json	Existing projects — search locally with jq	❌ No
devices.json	Device inventory — search locally with jq	❌ No
device-groups.json	Device groups — search locally with jq	❌ No
lcm-models.json	LCM resource models with their schemas and actions	❌ No
agents.json, llm-profiles.json	FlowAgent agents and the LLM profiles this client can build with	❌ No
gateways.json, gateway-connections.json, gateway-services.json	Gateway5 clusters, their connection state, registered services	❌ No
inventories.json	Inventory Manager inventories and node counts	❌ No

platform-summary.json carries the compact version of the last four rows as execution_capabilities (see Inventory Execution Capabilities below).

After running, read platform-summary.json for feasibility. Search raw files locally when you need specifics — never load them into context.

File Shapes and jq Queries

Every file has a specific shape. Use these queries — don't guess.

File	Shape	Example query
platform-summary.json	{adapters, integrations, applications, adapter_type_names, projects, workflow_count, device_count, execution_capabilities}	`jq '.adapters[]
platform-summary.json → execution_capabilities	{lcm: {running, models: [{name,id,actions}]}, flowagent: {running, llm_profiles: [{name,provider,models}], agent_count}, gateway5: {running, clusters: [{cluster_id,connection,services}], inventories: [{name,nodes}]}, gateway4_workflows: [names]}	`jq '.execution_capabilities.gateway5.clusters[]
lcm-models.json	{"data":[...], "total":N}	`jq '.data[]
agents.json	{"data":{"items":[...]}}	`jq '.data.items[]
gateway-services.json	{"result":[...]} — location is the cluster ID	`jq '.result[].service_metadata
inventories.json	{"result":{"data":[...]}}	`jq '.result.data[]
tasks.json	plain array [...]	`jq '.[]
apps.json	plain array [...]	`jq '.[]
adapters.json	{"results":[...], "total":N}	`jq '.results[]
integrations.json	{"results":[{name,model,type,active,server:{protocol,host,port,base_path}}], "total":N}	`jq '.results[]
applications.json	{"results":[...], "total":N}	`jq '.results[]
workflows.json	{"items":[...], "count":N}	`jq '.items[]
projects.json	{"data":[...]}	`jq '.data[]
devices.json	{"list":[...]}	`jq '.list[]
device-groups.json	varies by platform	jq 'type' device-groups.json first to check shape
openapi.json	{"paths":{...}}	jq '.paths["/the/endpoint"]' openapi.json

Handling failures: Before parsing any saved file, check if it contains valid JSON:

python3 -c "import json,sys; json.load(open(sys.argv[1])); print('ok')" {use-case}/devices.json 2>/dev/null || echo "empty"

If invalid, treat as "no data available" — don't block the flow.

Resolve Capabilities

For each row in the spec's Capabilities table:

• Can the platform do this? → ✓ Resolved
• Can't + Required? → ⚠ Blocked (stop and discuss)
• Can't + Not Required? → ✗ Skipped (use fallback from spec)

Resolve Integrations

The platform connects to external systems in two ways. Check both before you call a system missing:

Source	What it is	Where to look
Adapter instance	Installed adapter package	platform-summary.json → adapters (from /health/adapters; has RUNNING state and ONLINE/OFFLINE connection)
Integration instance	Virtual adapter built from an integration model (POST /integrations)	platform-summary.json → integrations (from /integrations; has an active flag and server host)

Integration instances do not appear in /health/adapters. A system such as NetBox connected as an integration shows up only as a type name in adapter_type_names (and in tasks.json), so checking adapters alone reports it as not found. Match each row of the spec's Integrations table against both lists — by name, by model, or by the app / locationType on its tasks in tasks.json.

For each row in the spec's Integrations table:

• Found as a running adapter, or as an active integration? → ✓ Resolved (record the instance name, whether it is an adapter or an integration, and the app / locationType from tasks.json)
• Found + Stopped (adapter) or inactive (integration)? → ⚠ Warning (needs to be started or activated)
• 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

An integration's active flag is configuration state, not proof the external system is reachable — integrations have no connection state. Record "reachability not verified" in feasibility.md, and plan a read-only call through the integration's task as one of the first build steps.

⚠ 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.

FlowAI agents: load /flowagent for agent requirements. An agent can call another agent as an agent:<agent-id> tool on Platform 6.5+ and Itential Cloud, so a design can be a parent agent with child agents (see "Agents as tools" in /flowagent). Confirm on the target platform with GET /tools/agent%3A<id> for an existing agent. If it's not supported, say so in the feasibility assessment and propose chaining the agents in a workflow; don't switch to a workflow design without the engineer agreeing.

Inventory Execution Capabilities

Write an Execution Capabilities section in feasibility.md from platform-summary.json → execution_capabilities. Record facts only — don't recommend a model here; Design decides that with the engineer.

Model	What to record	Mark it not available when
LCM	LifecycleManager running; resource models whose names match the spec's objects, with their actions	LifecycleManager isn't running
FlowAgent	Agent apps running; LLM profiles the client can build with; agents whose names match the spec's job	The apps aren't running, or there's no LLM profile
Gateway5	GatewayManager running; connected clusters and their service counts; services whose names match spec steps; inventories and node counts	GatewayManager isn't running, or no cluster is connected
Gateway4	gateway4_workflows — workflows that still call AGManager tasks. Never design new work on Gateway4; if any of these workflows are in this spec's scope, point to /gateway4-to-gateway5	—

List name matches as candidates — name, ID, owning project if known — at most five per kind, with a count of the rest. Don't call them fits; Design checks that. Search with word boundaries: test("\\bport\\b";"i"), not test("port";"i"), which also matches "report". If agents.json reports approxInaccessibleAgentCnt above zero, note that some agents aren't visible to this client — see assets/AGENTS.md → Project Visibility.

If the spec names a model the platform can't run ("use LCM", "build an agent"), treat it as a capability gap (Resolve Capabilities above).

---

Design

Produce the solution design from the approved spec + feasibility results.

Gateway4 → Gateway5 migration: design each item from its readiness-report code (WRAP / REVIEW / ARGS / INV) using assets/helpers/gateway-migration/conversion-guide.md — the inventory mapping, the service per script/playbook, the task-by-task rewire, and a parity test per workflow for Section F. The migrated workflows are built as a new project alongside the originals.

Design the Execution Model

Before decomposing anything, decide with the engineer where LCM, FlowAgent and Gateway5 come into this delivery. Read references/execution-model.md first — it says when to use each one, what to check, what to ask and what to put in the design. Then:

1. Check the candidates. Feasibility lists existing resource models, agents and services by name only. Read each one before building on it — make these read-only calls now:

   • resource model: GET /lifecycle-manager/resources/{id} — schema, actions, owning project
   • agent: GET /agent-project-service/agents/{id} — instructions and tools
   • tools an agent would need: GET /tools?name=...

   Reuse a candidate only if it fits; a matching name isn't enough. If two overlap, ask the engineer which, if either.

2. Ask the engineer what's still open, in one message. Pick from the guide's questions. Leave out anything the spec or Feasibility Step 2 already answered, and merge any question that overlaps a spec question. Ask about the delivery path (agent first or direct) only where agent first is a real option, and give the trade-off.

3. Propose a model for each phase and record it in Section C, with the answer or inventory fact behind anything other than a deterministic workflow.

Follow the spec:

• If it names a model ("use LCM", "build an agent"), use it and record any concern as a risk.
• Apply its Key Design Decisions (Section 4). "Never improvise a fix", for example, rules out an agent choosing the remediation. If your proposal conflicts with one — LCM's one action per operation vs. "one workflow handles turn-up and tear-down" — raise it in review; don't silently follow or override it.