Explore

Explore

Path: Freeform — not part of the delivery lifecycle Owns: Auth, environment discovery, freestyle skill use Use when: You want to browse adapters, try tasks, build something experimental, or understand the platform before committing to a spec

Customization

Before using this skill, check custom/org/, custom/team/, and custom/dev/ in this skill's own directory. Read every .md file found, in that order (any folder may be empty or absent). Apply them in addition to everything below — where a file overrides a specific rule from this document, prefer the override; more specific wins (dev over team over org). See .claude/CUSTOMIZATION.md for the full framework and what belongs in which layer.

What This Does

Connects you to a platform, pulls everything needed to work freely, and routes you to the right skill for whatever you want to do.

/explore
    │
    ├── Auth (from env file or interactive)
    ├── Pull platform data
    ├── Summarize environment
    └── Use skills directly

Step 1: Authenticate

Check for credentials in this order:

1. {use-case}/.env — use-case-specific
2. ${CLAUDE_PLUGIN_ROOT}/environments/*.env — pre-configured environments at repo root

If found, authenticate automatically. If not, ask:

1. Platform URL
2. Credentials (username/password or client_id/secret)

Local Development (username/password):

POST /login
Content-Type: application/json

{"username": "admin", "password": "admin"}

Returns a token string. Use as query parameter: ?token=TOKEN

Cloud / OAuth:

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

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials

Returns {"access_token": "..."}. Use as Bearer header.

Save to .auth.json:

{
  "platform_url": "https://...",
  "auth_method": "oauth",
  "token": "eyJhbG...",
  "timestamp": "2026-03-25T10:00:00Z"
}

Step 2: Pull Platform Data

Run in two groups. Do not run all in one parallel batch — if one fails, parallel cancellation kills the others.

Group 1 (core — run in parallel):

curl -s "{BASE}/help/openapi?url={ENCODED_BASE}&token=TOKEN" > {use-case}/openapi.json
curl -s "{BASE}/workflow_builder/tasks/list?token=TOKEN"     > {use-case}/tasks.json
curl -s "{BASE}/automation-studio/apps/list?token=TOKEN"    > {use-case}/apps.json
curl -s "{BASE}/health/adapters?token=TOKEN"                > {use-case}/adapters.json
curl -s "{BASE}/health/applications?token=TOKEN"            > {use-case}/applications.json

Group 2 (environment-specific — run in parallel after Group 1):

Devices (note: POST, not GET):

curl -s -w "\n%{http_code}" -X POST "{BASE}/configuration_manager/devices?token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"options":{"start":0,"limit":1000,"sort":[{"name":1}],"order":"ascending"}}' \
  > {use-case}/devices.json

Existing workflows:

curl -s "{BASE}/automation-studio/workflows?limit=500&token=TOKEN" > {use-case}/workflows.json

Before parsing any saved file, validate JSON:

jq type {use-case}/devices.json 2>/dev/null || echo "empty"

If invalid, treat as no data — don't block.

Step 3: Present Summary

Show:

• Adapters: name, state, connection
• Apps: count, key platform apps running
• Tasks: count
• Devices: count and OS types (if available)
• Existing workflows: count

Visibility note: see AGENTS.md's "Project Visibility" section — project-scoped assets are ACL-gated, global assets aren't. If the engineer expects a specific project and it doesn't appear, treat it as possibly access-restricted, not missing.

Step 3b: Initialize Memory File

After pulling platform data, check for {use-case}/use-case-memory.md:

• Exists → read it. It has context from a previous session — platform URL, prior decisions, open items.
• Missing → create it from ${CLAUDE_PLUGIN_ROOT}/helpers/use-case-memory.md. Populate Platform URL, Stage: requirements (explore is freeform — set the real stage once the engineer commits to a delivery path), Status: active, and any adapter/app names discovered in Step 2.

Step 4: Route to Skills

Point to the right skill for what the engineer wants to do:

Gotchas

• OAuth MUST use Content-Type: application/x-www-form-urlencoded, not JSON
• Tokens expire mid-session — re-authenticate silently from .env on auth errors
• OpenAPI spec is ~1.5MB — search locally with jq, never load into context
• tasks/list app field has WRONG casing for adapters — use apps/list for correct names
• Devices endpoint is POST not GET — body required
• Project list responses are RBAC-filtered — absence does NOT mean the project doesn't exist. See AGENTS.md's Project Visibility section. If the engineer names a specific project you can't find, say "not visible to this client ({client_id}) — possibly access-restricted; ask the project owner to add {client_id} to its ACL" rather than "doesn't exist."
• PATCH /automation-studio/projects/{id} silently ignores an accessControl body — use the members array instead: [{"type": "account"|"group", "reference": "<id>", "role": "owner"|"editor"|"operator"|"viewer"}]. See #62