/graphos-factory

name: graphos-factory
description: Build and iterate on an Apollo Connectors subgraph for a GraphOS supergraph from a REST API, with or without an OpenAPI or Swagger spec, in a dedicated git workspace that records what the API offers, the user's operation and field selection, every design decision, and the evidence each verification layer produced. Use whenever the user wants to wrap a REST API as a GraphQL subgraph for their supergraph, add or remove operations or fields from an existing connector subgraph, refresh one against a new spec, or record live API traffic as test fixtures, even if they do not say "connector", "subgraph" or "Apollo".
license: MIT
compatibility: macOS or Linux (WSL on Windows) with bash, curl, git and jq; Java 17+ for the end-to-end and live layers. Any Agent Skills host (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and others) that can run shell commands.
metadata:
  version: "0.11.0"

graphos-factory

You turn a REST API into an Apollo Connectors **subgraph** for the user's GraphOS supergraph, and keep it maintainable. The subgraph is the deliverable: a schema the user composes with their other subgraphs. **You are the generator**: no tool writes the schema for you. The `graphos-factory` binary (the shared references write `graphos-factory-core <command>`; here that is `graphos-factory`, installed beside it as the same binary) and the shell wrappers under `graphos-factory-core/scripts/` do the mechanical work — reading a source into an inventory, rendering placeholders, running rover, checking the invariants — and make no design decisions at all.

**Source kinds.** `workspace.yaml`'s `source_kind` names the source. Only `rest` is built: a REST API wrapped with Apollo Connectors, with or without an OpenAPI document. gRPC / protobuf, databases and existing GraphQL APIs are planned, not built: if a user asks for one, say so plainly and stop — never approximate one with the REST path. The workspace contract is source-agnostic; each kind adds its own intake reference and key grammar.

Everything durable lives in the **workspace**, a git repo you create per subgraph: `inventory.json` is what the source offers, `selection.yaml` is what the user chose, `<name>.graphql` is the subgraph schema the engineer edits, the decision log (the calls, each with its alternatives: `decisions.json`, then one file per decision under `decisions/`, written only via `graphos-factory decisions`), the findings log (settled facts, likewise, via `graphos-factory findings`) and `memory.md` are what you and your predecessors learned. Read [`workspace-contract.md`](graphos-factory-core/references/workspace-contract.md) once for the full layout. The core's references are in `graphos-factory-core/references/`, this target's in `references/`.

**Never regenerate the schema wholesale after the first commit.** Compute the delta and edit only what changed. Losing hand edits to a regeneration is the specific failure this skill exists to avoid — and a hand edit you have not codified (see "Hand edits" below) blocks an `apply` until you have.

**This target's contract** is the subgraph's place in the user's supergraph; what the references leave open is listed under their "Open" headings. What holds today, enforced by the binary: `{{BASE_URL}}` and `{{AUTH_EXPR}}` are the only placeholders, with the scheme prefix *outside* the placeholder, and `template.yaml` gives each a local test value (`export` renders them with the production values, [`export-graphos.md`](references/export-graphos.md)); the Federation directives the schema may import are `@key`, `@shareable`, `@requires`, `@provides`, `@external`, `@inaccessible`, `@listSize`, `@cost` and `@tag` ([`federation-subgraph.md`](references/federation-subgraph.md)); one `@source` is the shape the layers model, and a second is a lint warning (unmodelled, not forbidden). **`@tag` is for GraphOS Contracts, and off by default**: apply it only when the user's supergraph uses contracts, with the names their contracts already filter on, recorded as a decision. Never invent a tag; this target imposes no tag names, so `unknown-tag` never fires.

**Setup, before the first command.** `<skill>` below is the directory that holds this file. Under the Claude Code plugin, its SessionStart hook (`scripts/session-start.sh`) has already run `bootstrap.sh` and put the binary on `PATH`: its output says so. Anywhere else (`npx skills add`, `gh skill install`, a copied directory; Codex, Cursor, GitHub Copilot, Gemini CLI or any other agent), check with `bash <skill>/scripts/bootstrap.sh --check`, and on exit 127 run `bash <skill>/scripts/bootstrap.sh` once (about 3 MB into `~/.cache/graphos-factory-core/`). Then run `. <skill>/scripts/env.sh` in your shell, or at the start of every command when your shell keeps no state between commands: it puts `graphos-factory`, its `graphos-factory-core` link and rover on `PATH` and sets `GRAPHOS_FACTORY_CORE_SCRIPTS` (the `$S` below). The toolchain (`toolchain.sh`) is installed only once the user agrees, whatever the host.

<!-- core:begin -->

Before anything else

1. If a workspace exists, read the decision log (`graphos-factory-core decisions list .`, including `--open` for questions still awaiting the user), the findings (`graphos-factory-core findings list .`) and `.factory/memory.md` **in full**. Do not re-open a `resolved` decision unless the user asks. When they want to revise an answer to the same question, `graphos-factory-core decisions reopen . --id D-id` clears it and puts the record back to `open`, then settle it again with `decisions resolve`; when the question itself has changed, record a new decision instead. Never edit a record in place — the file is written only through that command. If the workspace still carries a legacy `.factory/decisions.md` and no `decisions.json`, run `graphos-factory-core decisions migrate .` once to import it (it preserves the `D-nnnn` ids and remov