fix(press): dynamic API type detection, registry is hint not gate

b1651b50b60037cfed97b0fa67e3c4fec40c393d · 2026-03-26 07:56:02 -0700 · Matt Van Horn

- Step 0: registry is a speed shortcut, never a blocker
- Step 1.1: search for BOTH REST and GraphQL specs dynamically,
  detect type from first 500 bytes (openapi vs type Query vs __schema)
- Remove "GraphQL-only" label from Linear registry entry - just the URL
- Never refuse because API isn't in registry or is labeled "Skipped"
- Phase 2 type check still decides REST vs GraphQL mode at runtime

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Files touched

M skills/printing-press/SKILL.md
M skills/printing-press/references/known-specs.md

Diff

commit b1651b50b60037cfed97b0fa67e3c4fec40c393d
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date:   Thu Mar 26 07:56:02 2026 -0700

    fix(press): dynamic API type detection, registry is hint not gate
    
    - Step 0: registry is a speed shortcut, never a blocker
    - Step 1.1: search for BOTH REST and GraphQL specs dynamically,
      detect type from first 500 bytes (openapi vs type Query vs __schema)
    - Remove "GraphQL-only" label from Linear registry entry - just the URL
    - Never refuse because API isn't in registry or is labeled "Skipped"
    - Phase 2 type check still decides REST vs GraphQL mode at runtime
    
    Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 skills/printing-press/SKILL.md                  | 31 ++++++++++++++-----------
 skills/printing-press/references/known-specs.md |  2 +-
 2 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index fcfe56ec..8e6cd38c 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -144,10 +144,12 @@ When the user provides an API name, run ALL five phases.
 
 ### Step 0: Parse intent and check known specs
 
-Extract the API name. Check `~/cli-printing-press/skills/printing-press/references/known-specs.md`.
+Extract the API name. Optionally check `~/cli-printing-press/skills/printing-press/references/known-specs.md` for a cached spec URL.
 
-If found in registry: note the URL for Phase 2, but STILL run full Phase 1 research.
-If not found: Phase 1 searches for spec too.
+If found in registry: note the URL as a hint for Phase 1, but STILL run full research.
+If not found: Phase 1 searches for the spec. This is the normal path - most APIs won't be in the registry.
+
+**The registry is a speed shortcut, not a gate.** Never refuse to run because an API isn't in the registry. Never hard-block because the registry says "GraphQL" or "Skipped." Phase 1 discovers the spec type dynamically.
 
 ---
 
@@ -542,22 +544,23 @@ Research the API landscape deeply. You need to understand the competitive terrai
 
 ### Step 1.1: Search for the API spec
 
-If not in known-specs registry:
+Search for BOTH REST and GraphQL specs. Don't assume the API type - discover it.
 
-**For REST APIs:**
 1. **WebSearch**: `"<API name>" openapi spec site:github.com`
 2. **WebSearch**: `"<API name>" openapi.yaml OR openapi.json specification`
-3. Try common URL patterns
-4. If found, **WebFetch** first 500 bytes to verify
+3. **WebSearch**: `"<API name>" graphql schema site:github.com`
+4. **WebSearch**: `"<API name>" API documentation developer reference`
+5. Try common URL patterns for the API docs landing page
+6. If a spec URL is found, **WebFetch** first 500 bytes to determine type:
+   - Starts with `{"openapi":` or `openapi:` -> OpenAPI/REST
+   - Contains `type Query {` or `schema {` -> GraphQL SDL
+   - Contains `"__schema"` -> GraphQL introspection result
+
+**Record the API type** (REST, GraphQL, or hybrid) for Phase 2's type check.
 
-**For GraphQL APIs:**
-1. **WebSearch**: `"<API name>" graphql schema site:github.com`
-2. **WebSearch**: `"<API name>" graphql introspection schema SDL`
-3. Try fetching the schema: `curl -sL <api-url>/graphql/schema` or introspection query
-4. **WebFetch** the API's developer docs for entity/type reference
-5. Note: The GraphQL schema serves the same role as an OpenAPI spec - it defines entities, fields, types, and relationships. Phase 0.7 uses it for entity classification and data gravity scoring.
+If no spec found: plan to write one from docs in Phase 2. For GraphQL APIs, the developer docs or a schema URL fetched via introspection serves the same role as an OpenAPI spec - it defines entities, fields, types, and relationships.
 
-If no spec found: plan to write one from docs in Phase 2.
+**Never refuse to proceed because you can't find a spec.** Write one from docs, or use GraphQL mode.
 
 ### Step 1.2: Search for competing CLIs
 
diff --git a/skills/printing-press/references/known-specs.md b/skills/printing-press/references/known-specs.md
index 24e28c7e..004346f6 100644
--- a/skills/printing-press/references/known-specs.md
+++ b/skills/printing-press/references/known-specs.md
@@ -24,7 +24,7 @@ APIs with verified, publicly accessible OpenAPI specifications. The printing-pre
 | Asana | https://raw.githubusercontent.com/Asana/openapi/main/defs/asana_oas.yaml | YAML | 3.0.x | Yes |
 | Square | https://raw.githubusercontent.com/square/square-openapi/master/openapi.json | JSON | 3.0.x | Yes |
 | Notion | Skipped (official public OpenAPI spec URL not confirmed) | N/A | N/A | No |
-| Linear | GraphQL-only. Schema: https://raw.githubusercontent.com/linear/linear/master/packages/sdk/src/schema.graphql | GraphQL SDL | N/A | Yes (GraphQL mode) |
+| Linear | https://raw.githubusercontent.com/linear/linear/master/packages/sdk/src/schema.graphql | GraphQL SDL | N/A | Yes |
 | HubSpot | https://raw.githubusercontent.com/HubSpot/HubSpot-public-api-spec-collection/main/PublicApiSpecs/CRM/Contacts/Rollouts/424/v3/contacts.json | JSON | 3.0.x | Yes |
 | Front | https://raw.githubusercontent.com/frontapp/front-api-specs/main/core-api/core-api.json | JSON | 3.0.x | Yes |

← 9e8cc5d5 feat(press): support GraphQL APIs - warn but proceed, don't · back to Cli Printing Press · docs: comprehensive README rewrite for 8-phase pipeline 31a8bed4 →