itential · keepithuman · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "AI agent skills for the Itential Platform — deliver infrastructure automation from spec through build.",
-    "version": "1.0.1"
+    "version": "1.1.1"
   },
   "plugins": [
     {
@@ -16,7 +16,7 @@
         "repo": "itential/builder-skills"
       },
       "description": "AI agent skills for the Itential Platform — deliver infrastructure automation from spec through build. Covers requirements, feasibility, design, build, as-built documentation, FlowAgent, IAG, and MOP.",
-      "version": "1.0.1",
+      "version": "1.1.1",
       "author": {
         "name": "Itential"
       },

@@ -1,7 +1,7 @@
 {
   "name": "itential-builder",
   "description": "AI agent skills for the Itential Platform — deliver infrastructure automation from spec through build. Covers requirements, feasibility, design, build, as-built documentation, FlowAgent, IAG, and MOP.",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "author": {
     "name": "Itential"
   },

@@ -1,7 +1,6 @@
 ---
 name: builder-agent
-description: Builder Agent — owns Build and As-Built. Implements the approved solution design, tests each component, delivers the solution, and records the as-built state. Invoke after /solution-architecture produces an approved solution-design.md.
-argument-hint: "[action or asset-type]"
+description: Use this skill when someone has an approved solution design and is ready to build. Trigger it for phrases like "solution design is approved", "go ahead and build", "implement the design", "create the workflows", "build everything per the design", "start the build", "the design is locked — implement it", or "write the as-built documentation". Also trigger it when a build is failing mid-way and needs debugging. This skill implements the approved solution-design.md end-to-end — creating all workflows, templates, projects, and configs, testing each component, and producing as-built.md. If the user has a solution-design.md and wants to turn it into working automation, this is the right skill. Invoke after /solution-arch-agent produces an approved solution-design.md.
 ---
 
 # Builder Agent

@@ -1,7 +1,6 @@
 ---
 name: documentation
-description: Document any Itential platform asset — workflows, forms, transformations, templates, command templates, analytic templates, OM automations, golden configuration trees/compliance plans, LCM resource models, projects, or all global assets at once. Accepts specific asset names/IDs, project names/IDs, or processes all globals. Discovers relationships, groups into use cases, produces customer-spec.md + solution-design.md per use case and a master README only when multiple use cases exist.
-argument-hint: "[asset-name(s) | 'all' | 'platform' | directory-path]"
+description: Use this skill to survey and catalog an Itential platform — when someone wants to know what's on their platform, document global assets (workflows, templates, LCM models, golden config, OM automations) that are NOT inside a named project, group them into logical use cases, and produce a master catalog or README. Trigger it for phrases like "document everything on the platform", "what use cases do we have?", "catalog all our global workflows", "I inherited this platform and have no idea what's there", "group our automations by use case", or "produce a platform README". The output is a structured catalog: customer-spec.md + solution-design.md per use case + master README. NOT for documenting a specific named project — use /project-to-spec for that. NOT for building new automation.
 ---
 
 # Documentation
@@ -32,21 +31,23 @@ argument-hint: "[asset-name(s) | 'all' | 'platform' | directory-path]"
 
 ## What This Does
 
-Takes undocumented Itential assets — workflows, JSON forms, transformations, templates, command templates, analytic templates, Operations Manager automations, golden configuration trees and compliance plans, LCM resource models, and projects. Accepts specific asset names/IDs, project names/IDs, or the full global asset catalog. Discovers how they relate to each other, groups them into logical use cases, and produces documentation for each group plus a master index when there are multiple use cases.
+Surveys **global** Itential assets — workflows, JSON forms, transformations, templates, command templates, analytic templates, Operations Manager automations, golden configuration trees and compliance plans, and LCM resource models that live outside named projects. Accepts `all`, `platform`, a directory path, or a list of specific global asset names. Discovers how they relate to each other, groups them into logical use cases, and produces documentation for each group plus a master index when there are multiple use cases.
+
+> **For a named project:** Use `/project-to-spec` instead — it reads a single project's components and produces customer-spec.md + solution-design.md tailored to that project.
 
 ---
 
 ## Flow
 
 ```
-User invokes /documentation [asset(s) | 'all' | 'platform' | directory]
+User invokes /documentation ['all' | 'platform' | directory | specific global asset names]
       |
       ├── Step 0: Determine Scope
-      |     ├── Project named? → fetch project components → proceed as scoped asset set
-      |     ├── Specific assets named? → resolve + discover relationships → ask grouping preference
+      |     ├── Project named? → redirect to /project-to-spec
+      |     ├── Specific global assets named? → resolve + discover relationships → ask grouping preference
       |     └── 'all' / platform / directory? → full collection + grouping flow
       |
-      ├── Step 1: Collect + classify assets (in-memory)
+      ├── Step 1: Collect + classify global assets (in-memory)
       ├── Step 2: Discover relationships + group into use cases (in-memory)
       ├── Step 3: Present proposed groupings to engineer for approval
       ├── Step 4: Write per-use-case reports (customer-spec.md + solution-design.md)
@@ -62,29 +63,11 @@ Before collecting assets, determine what the user wants to document.
 
 ### Pattern 1 — Project named
 
-If the user names a project or provides a project ID (or a `.project.json` file is present), fetch the project and its components directly:
-
-1. **Fetch the project:**
-   ```
-   GET /automation-studio/projects/{projectId}
-   ```
-   Or search by name:
-   ```
-   GET /automation-studio/projects?contains=name:{projectName}
-   ```
-   Response shape: `{message, data: {_id, name, components: [...], members: [...]}}`
-
-2. **Fetch each component** from `data.components`:
-   - Workflows: `GET /automation-studio/workflows/detailed/{urlEncodedName}`
-   - Templates: `GET /automation-studio/templates/{id}`
-   - MOP Command Templates: `GET /mop/listATemplate/{name}`
-   - JSON Forms: `GET /automation-studio/json-forms/{id}`
-
-3. **Strip `@projectId:` prefixes** from all workflow names before processing.
+If the user names a specific project, **redirect them to `/project-to-spec`** — that skill is purpose-built for single-project documentation and produces a more thorough analysis.
 
-4. **Continue to Step 1** treating these fetched components as the asset set. This follows the same path as Pattern 2 (specific assets named) — present the discovered cluster, ask how to group it, then proceed through Steps 2–6.
+> "It looks like you want to document a specific project — use `/project-to-spec` for that. It reads the project's components directly and produces a more thorough customer-spec.md and solution-design.md for it."
 
-### Pattern 2 — Specific asset(s) named
+### Pattern 2 — Specific global asset(s) named
 
 If the user provides one or more asset names or IDs:
 

@@ -1,7 +1,6 @@
 ---
 name: explore
-description: Explore an Itential Platform — authenticate, pull platform data, and browse capabilities freely. Use for ad-hoc investigation, freestyle building, or understanding what's available before starting a delivery. Not part of the delivery lifecycle.
-argument-hint: "[use-case-name or environment]"
+description: Use this skill whenever someone wants to connect to an Itential platform and browse, inspect, or discover what's there — without starting a formal delivery. Trigger it for phrases like "connect to my platform", "show me what adapters are running", "authenticate and pull platform data", "I want to poke around before starting", "what workflows exist?", "give me an inventory of the platform", "browse capabilities freely", "check if adapter X is running", or "I just set up a new environment — show me what's there". Also use it for ad-hoc freestyle work where the user wants to build something directly without going through the full spec→design→build lifecycle.
 ---
 
 # Explore

@@ -1,6 +1,6 @@
 ---
 name: project-to-spec
-description: Document an existing Itential project into a requirements spec and solution design. Reads project components (workflows, templates, MOP), analyzes what was built, and produces customer-spec.md and solution-design.md. Use when documenting existing automation or creating a baseline for a rebuild.
+description: Use this skill when a user names a specific existing Itential project and wants it documented — reverse-engineered into a requirements spec and solution design. Trigger it for phrases like "document the DNS_Management project", "create a spec from the Firewall_Rule_Lifecycle project", "reverse-engineer project X into a spec", "I have a project with no docs — produce a customer-spec and solution design for it", or "use this project as a baseline for a rebuild". Reads the project's workflows, templates, and MOP components, infers business purpose and design decisions, and produces customer-spec.md + solution-design.md. For documenting global/unprojectized assets across the whole platform, use /documentation instead.
 argument-hint: "[project-name or project-id]"
 ---
 

@@ -1,7 +1,6 @@
 ---
 name: solution-arch-agent
-description: Solution Architecture Agent — owns Feasibility and Design. Assesses platform fit against the approved requirements spec, then produces the solution design. Invoke after /spec-agent produces an approved customer-spec.md. Can be re-run in design-only mode when requirements are stable but the implementation plan needs to change.
-argument-hint: "[use-case or design-only]"
+description: Use this skill when someone has approved requirements (a customer-spec.md) and needs to assess platform feasibility or produce a solution design. Trigger it for phrases like "requirements are approved", "my spec is done", "check if the platform supports this", "run feasibility", "connect to the platform and design the solution", "I have a customer-spec — now what?", or "produce a solution-design.md". This skill connects to the live platform, checks what adapters and capabilities are available, and produces feasibility.md and solution-design.md. Also trigger it in design-only mode when the implementation plan needs to change but requirements are stable. Invoke after /spec-agent produces an approved customer-spec.md. Hands off to /builder-agent after design approval.
 ---
 
 # Solution Architecture Agent

@@ -1,7 +1,6 @@
 ---
 name: spec-agent
-description: Spec Agent — owns the Requirements stage. Picks a use case spec, refines it with the engineer, and produces an approved HLD (customer-spec.md). Use when starting a delivery from a spec. For ad-hoc platform exploration, use /explore instead.
-argument-hint: "[use-case-name]"
+description: Use this skill to start any new automation delivery — when someone wants to automate something, build a new use case, figure out requirements, write up an HLD, or kick off a project on the Itential Platform. Trigger it for phrases like "I want to automate X", "help me build a workflow for Y", "we're starting a new automation project", "I need to define requirements for Z", "kick off a delivery", or "let's start with requirements". This is the entry point for the spec-driven delivery lifecycle. It picks from 22 built-in use case specs or starts from scratch, refines requirements with the engineer, and produces an approved customer-spec.md. Use it whenever someone is at the beginning of building something new and hasn't yet defined what they're building. For ad-hoc platform exploration, use /explore instead. Hands off to /solution-arch-agent after approval.
 ---
 
 # Spec Agent

@@ -63,11 +63,24 @@ Requirements  →  Feasibility  →  Design  →  Build  →  As-Built
 **Auth happens when first needed** — in `/explore` (explore path) or in `/solution-arch-agent` during Feasibility. The token is saved to `{use-case}/.auth.json`. Every subsequent skill should:
 1. Read `{use-case}/.auth.json` for `platform_url`, `auth_method`, and `token`
 2. Use the token for all API calls (Bearer header for OAuth, query param for local)
-3. On auth error (401/403): re-authenticate using `{use-case}/.env` and update `.auth.json`
+3. On auth error (401/403): re-authenticate silently — see procedure below
 4. **Never ask the user for credentials if `.env` exists**
 
 This means the user authenticates once and every subsequent skill just works.
 
+**Token expiry — silent re-auth procedure:**
+
+When any API call returns 401 or 403, do not stop and do not ask the user. Re-authenticate silently:
+
+1. Read credentials from `{use-case}/.env` (or `${CLAUDE_PLUGIN_ROOT}/environments/*.env` if no use-case `.env`)
+2. Call the appropriate auth endpoint:
+   - **OAuth:** `POST {PLATFORM_URL}/oauth/token` with `Content-Type: application/x-www-form-urlencoded` and body `grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}`
+   - **Local/password:** `POST {PLATFORM_URL}/login` with `{"username": "...", "password": "..."}`
+3. Write the new token back to `{use-case}/.auth.json`
+4. Retry the failed request with the new token
+
+If `.env` does not exist and re-auth is needed, then and only then ask the user for credentials.
+
 ### Key Rule: Look Up Before You Act — Don't Guess
 
 **Skills** teach patterns, workflows, and know-how (how to build a childJob, how to wire variables, how to test).
@@ -187,6 +200,7 @@ Requirements  →  Feasibility  →  Design  →  Build  →  As-Built
 21. **Duplicate transition keys to same target** — JSON doesn't allow two keys with the same name. If a task needs both `success` and `error` to reach `workflow_end`, create an error handler task (e.g., `newVariable` to set error status) and route error there, then route that task to `workflow_end`.
 22. **Respect task schema data types** — When wiring task inputs, match the type from `task-schemas.json` exactly. If a field is typed as `array`, pass an array (e.g., `["joksan@example.com"]`), not a bare string. If typed as `number`, pass a number, not a string. Common offenders: `to`/`cc`/`bcc` in email tasks (arrays, not strings), `pageSize`/`page` in queries (numbers, not strings). Mismatched types cause silent failures or validation errors.
 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: <name>"` 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.
 
 ## Helper JSON Templates
 

@@ -13,6 +13,7 @@ Spec-driven infrastructure automation and orchestration — delivered by AI agen
 - [How to Use It](#how-to-use-it)
 - [Skills](#skills)
 - [Spec Library](#spec-library)
+- [Demo Specs](#demo-specs)
 - [Docs](#docs)
 - [Contributing](#contributing)
 - [Support](#support)
@@ -110,6 +111,9 @@ See [`docs/quickstart.md`](docs/quickstart.md) for the full setup and first deli
 "I have an existing project with no documentation"
 → /itential-builder:project-to-spec
 
+"Document all my global workflows and group them by use case"
+→ /itential-builder:documentation
+
 "I want to explore what's available on my platform"
 → /itential-builder:explore
 
@@ -130,6 +134,7 @@ See [`docs/quickstart.md`](docs/quickstart.md) for the full setup and first deli
 | `/itential-builder:builder-agent` | Implements the approved solution design end-to-end — workflows, templates, configs, projects. Tests each component, verifies acceptance criteria, and produces `as-built.md`. |
 | `/itential-builder:flowagent-to-spec` | Reads a FlowAgent's config and mission history, reconstructs what it actually did, and produces a `customer-spec.md` for the deterministic equivalent. Turns agentic exploration into a governed delivery path. |
 | `/itential-builder:project-to-spec` | Reads an existing Itential project — workflows, templates, MOP — and reverse-engineers a `customer-spec.md` and `solution-design.md`. Use to document undocumented automation or create a baseline for a rebuild. |
+| `/itential-builder:documentation` | Documents any platform asset or the entire global asset catalog. Accepts specific asset names, project names, or runs across all globals. Discovers relationships between assets, groups them into use cases, and produces `customer-spec.md` + `solution-design.md` per use case. Delegates projects to `/project-to-spec`. |
 | `/itential-builder:explore` | Authenticates to a platform, pulls live data, and lets you browse capabilities freely. Use for ad-hoc investigation before starting a delivery or when you need to work outside the lifecycle. |
 
 **Platform**
@@ -159,6 +164,19 @@ See [`docs/quickstart.md`](docs/quickstart.md) for the full setup and first deli
 
 ---
 
+## Demo Specs
+
+Ready-to-run specs in [`spec-files/demo/`](spec-files/demo/) for walkthroughs and demonstrations.
+
+| Spec | Description |
+|------|-------------|
+| [Device Health Troubleshooting Agent](spec-files/demo/device-health-agent.md) | FlowAI agent spec for device health triage — runs diagnostics and surfaces findings |
+| [Linux Diagnostics Agent](spec-files/demo/linux-diagnostics-agent.md) | FlowAI agent spec for Linux system diagnostics |
+| [DNS A Record Provisioning — Simple](spec-files/demo/spec-dns-a-record-infoblox-simple.md) | Simplified DNS A record provisioning via Infoblox |
+| [DNS A Record Provisioning](spec-files/demo/spec-dns-a-record-provisioning.md) | Full DNS A record provisioning lifecycle |
+
+---
+
 ## Docs
 
 - [`docs/quickstart.md`](docs/quickstart.md) — install, setup, and first delivery walkthrough