--- phase: 1 name: Research & Investigation description: API discovery, documentation analysis, endpoint extraction skills: - identify-provider-category - list-provider-apis - discover-dynamic-use-cases - investigate-auth-oauth2 - investigate-auth-custom - fetch-endpoint-parts - consolidate-research-output agents: - resource-endpoint-fetcher - use-case-discoverer dependencies: [] entryConditions: - Fresh start or explicit /connector:research invocation exitConditions: - .connector-dev/{{provider}}/research/{{provider}}_research.json passes gates/research.js (R1–R11) - Phase recorded complete via scripts/state/run.js set-phase --- # Phase 1: Research & Investigation ## Purpose Thoroughly research the provider's API documentation to extract all available endpoints, authentication methods, and operational patterns. ## Skills Used (orchestrated by `/connector:research`) | Skill | Phase step | Output | |-------|-----------|--------| | `identify-provider-category` | 2A — categorize | `provider_category.yaml` | | `list-provider-apis` | 2C (Pass 1 discovery) + 2E (Pass 2 classify via `classify_priority.js`) | `api_coverage.json` (all endpoints + MoSCoW priority tiers + `api_type` + provider metadata) | | `discover-dynamic-use-cases` | 2D — via `use-case-discoverer` agent | `use_cases/dynamic_*.yaml` (Layers 3+4) | | `investigate-auth-oauth2` | 2F — auth (per OAuth2 grant type) | `auth/auth_oauth2_.json` | | `investigate-auth-custom` | 2F — auth (per custom type) | `auth/auth_.json` | | `fetch-endpoint-parts` | 4 — endpoint deep-dive (spec) | `endpoints/resources/.yaml` (per resource: all 10 parts, provider-verbatim `description` + LLM-optimized `usage_notes`/`_action_summary`, soft-404 gate, 100% coverage self-check) | | `consolidate-research-output` | 5A + 5B — consolidation | `auth/auth_config.yaml` + 12 derived summary YAMLs | ## Scope control (Phase 3.4 / 3.5) After classification, the orchestrator applies the **70-action gate** on the default investigable pool (must+should+nice tiers, webhooks excluded): `≤70` → fully autonomous (zero questions); `>70` → exactly ONE confirmation (default auto-reduces to the top 70 by priority; user may reply with ONE of: count / resource names / priority tier). Webhook endpoints are **excluded by default** (`--exclude-webhooks`) — webhook coverage lives in webhook support (not part of this flow). Dependency resolution (`resolve_dependencies.js`) then auto-includes producers / removes uncallable actions and reports the delta informationally. ## Agents Used | Agent | Spawn pattern | Purpose | |-------|---------------|---------| | `resource-endpoint-fetcher` | One per resource in Phase 4 — spawned in parallel batches (3–5 at a time) | Executes the `fetch-endpoint-parts` spec for its slice of `api_coverage.json` (entries where `selected == true` and `category == `). Returns only a JSON summary (incl. `soft_404_urls[]` + `coverage_gaps[]`), never raw docs. | | `use-case-discoverer` | Once, Phase 2D | Generates Layer 3 (category dynamic) + Layer 4 (provider dynamic) use-case catalogs in an isolated context. | ## Entry Checkpoint No prerequisites — this is the starting phase for new connectors. Conditions: - Fresh start (no `.connector-dev/{{provider}}/run.json` yet, or research not recorded complete in it) - OR explicit `/connector:research` invocation - OR workflow reset requested ## Exit Checkpoint **Completion is decided by the gate, not by judgement.** Phase 1 is complete when `scripts/gates/research.js` (checks R1–R11) exits 0 against the authoritative artifact `.connector-dev/{{provider}}/research/{{provider}}_research.json` — assembled by `consolidate-research-output` from the working files below. The gate judges only that file; everything else in the research tree is working notes that feed it. Along the way, the sub-skills should have produced: - [ ] Research directory exists: `.connector-dev/{{provider}}/research/` - [ ] `api_coverage.json` lists every endpoint (count > 10) with MoSCoW `priority` tiers, `selected` flags, `api_type` + provider metadata - [ ] `auth/auth_config.yaml` consolidates all detected auth types (Phase 5A) - [ ] `endpoints/resources/*.yaml` covers every `selected: true` endpoint (`verify_completion.js` exits 0; soft-404 stubs count as written) - [ ] All Phase 5B summary YAMLs derived (`api_type.yaml`, `actions.yaml`, `auth/scopes.yaml`, `endpoints/endpoints_master.yaml`, `metadata/*.yaml`) ## Artifacts Produced The authoritative artifact is `{{provider}}_research.json` — the only file the research gate judges. The rest of the tree is intermediate working notes written by the sub-skills; `consolidate-research-output` projects them into the artifact. ``` .connector-dev/{{provider}}/research/ ├── {{provider}}_research.json # AUTHORITATIVE — judged by gates/research.js (R1–R11) ├── _index.md # Human-readable summary incl. soft-404 URLs + coverage gaps (Phase 5D) ├── api_coverage.json # Raw API list + tiers + selected flags + api_type + metadata (Phase 2C/2E/3.4-3.5) ├── provider_category.yaml # Provider category (Phase 2A) ├── selection.yaml # Scope-selection audit trail (Phase 3.4/3.5) ├── dependency_resolution.yaml # Producer additions / removals audit trail (Phase 3.5D) ├── api_type.yaml # REST/GraphQL/SOAP (derived 5B) ├── actions.yaml # Action list, everything except would_not_have (derived 5B) ├── use_cases/ │ ├── static_universal.yaml # Layer 1 (copied, Phase 2B) │ ├── static_category.yaml # Layer 2 (copied, Phase 2B — if category matched) │ ├── dynamic_category.yaml # Layer 3 (use-case-discoverer, Phase 2D) │ └── dynamic_provider.yaml # Layer 4 (use-case-discoverer, Phase 2D) ├── auth/ │ ├── auth_.json # Per detected auth type (Phase 2F) │ ├── auth_config.yaml # Consolidated (Phase 5A) │ └── scopes.yaml # Standalone + recommended sets (derived 5B) ├── endpoints/ │ ├── endpoints_master.yaml # YAML master list (derived 5B) │ └── resources/ │ ├── .yaml # Per resource: 10 parts + verbatim descriptions + usage_notes/_action_summary (Phase 4) │ └── ... └── metadata/ ├── api_info.yaml # Provider name, console URL, key concepts (derived 5B) ├── rate_limits.yaml # Consolidated rate limits (derived 5B) ├── pagination.yaml # Pagination styles across endpoints (derived 5B) ├── error_codes.yaml # Error envelope + retry guidance (derived 5B) ├── auth_per_subapi.yaml # Auth method per resource (derived 5B) ├── use_cases.yaml # Use case → action_id map (derived 5B) ├── priority_breakdown.yaml # Per-tier action_id lists + counts (derived 5B) └── use_case_coverage.yaml # Coverage score + orphan actions (derived 5B) ``` ## Phase Transition Completion is the gate exiting 0 on `{{provider}}_research.json`, then recording the transition — `run.json` is written only by `scripts/state/run.js`, never by hand: ```bash node ${CLAUDE_PLUGIN_ROOT}/scripts/gates/research.js --provider {{provider}} # must exit 0 node ${CLAUDE_PLUGIN_ROOT}/scripts/state/run.js set-phase \ --provider {{provider}} --phase research --status complete # or --status exhausted [--unmet R4,R6] when two consecutive rounds resolve nothing ``` Next phase: **Phase 2 — Build Connector**