generate-spec

name	generate-spec
description	Researches REST APIs and produces marten.yaml spec files for generating Go CLIs via marten generate. Triggers on requests to create a CLI for an API, research API endpoints and authentication, generate a marten spec, or build an agent-native CLI from documentation. Also triggers when the user mentions marten.yaml, API spec generation, or adding support for a new API.

Generating Marten Specs

Research a REST API and produce a valid marten.yaml spec that generates a working Go CLI via marten generate.

Model Recommendation

Use Sonnet for this skill. Benchmarking across Opus, Sonnet, and Haiku showed that Sonnet with this skill matches Opus output quality (identical subcommand counts) at lower token cost. Without the skill, Sonnet produces ~30% fewer endpoints than Opus — the skill closes that gap entirely. Haiku works but uses 3-4x more tokens and produces less consistent results.

Parallelizing Research

Phase 1 (Intent Discovery) is sequential and interactive — it requires user input and cannot be parallelized. Starting at Phase 2, use named agents to speed up research:

• Phase 2: Dispatch marten-cli:source-discoverer to fetch auth docs, endpoint reference, and rate limit docs simultaneously
• Phase 4: Dispatch one marten-cli:resource-cartographer per scoped resource group — one agent per included group (from intent-map.md) researching in parallel, then merge results
• Phase 7: Dispatch marten-cli:docs-drafter for LLM.md, SKILL.md, and research-log.md in parallel since they draw from the same research but produce independent files

Keep Phases 3 (Auth Deep-Dive) and 6 (Spec Assembly) sequential — auth decisions affect the entire spec, and assembly requires all research plus the intent map to be complete.

If agents fail to dispatch or the API is small enough not to need parallelism, do the work inline. The methodology instructions in references/research-methodology.md cover both paths.

What This Produces

File	Purpose
marten.yaml	Spec file — input to marten generate
LLM.md	Draft command reference for LLM consumption
SKILL.md	Draft Claude Code skill for the generated CLI
research-log.md	Sources, decisions, uncertainties
intent-map.md	User intents, required fields, acceptance criteria, verdicts
<cli-binary>	Compiled CLI binary, tested against live API

Before You Start

• Confirmed which API to research
• Clarified user intent — what questions should the CLI answer?
• Got target repository name and Go module path
• Collected API credentials — if available, configure them now (set env vars, run auth login, obtain profile field values like user/account IDs). For bearer-token CLIs, prefer the interactive auth set prompt or --token-stdin over raw command-line secrets. For OAuth CLIs, complete auth login before Phase 9; routine refresh should work from stored metadata after login without needing CLIENT_ID exported for every command. Phases 2-8 don't need credentials, but Phase 9 blocks without them. Collecting upfront lets all 12 phases run in a single session without interruption. If credentials are unavailable, Phases 2-8 still produce a working spec and binary; Phase 11 is skipped and intent-map.md is delivered as an unvalidated checklist.

Progress Tracker

Copy this checklist and update as you work:

- [ ] Phase 1: Intent Discovery
- [ ] Phase 2: Source Discovery
- [ ] Phase 3: Auth Deep-Dive
- [ ] Phase 4: Endpoint Inventory
- [ ] Phase 5: Constraint Mining
- [ ] Phase 6: Spec Assembly
- [ ] Phase 7: Documentation Draft
- [ ] Phase 8: Generate & Build
- [ ] Phase 9: Live API Validation
- [ ] Phase 10: Fix Loop
- [ ] Phase 11: Intent Review
- [ ] Phase 12: SKILL.md Finalization

Research Process

Follow the 12-phase methodology in references/research-methodology.md:

1. Intent Discovery — Capture user goals, scan API surface, scope the build
2. Source Discovery — Find official docs, OpenAPI specs, SDK source
3. Auth Deep-Dive — Map strategy, URLs, scopes, quirks completely
4. Endpoint Inventory — Catalog endpoints in scoped resource groups
5. Constraint Mining — Rate limits, format rules, known issues
6. Spec Assembly — Map research into marten.yaml, guided by intent map
7. Documentation Draft — LLM.md, SKILL.md, research log

Read the methodology reference for detailed per-phase checklists.

Phase boundary: Phase 1 requires user interaction. Phases 2-7 need only documentation access. Phases 8-12 need the marten binary, a Go toolchain, and (for 9-12) live API credentials. If running as a subagent, intents and credentials must be provided in the initial prompt. If running interactively, collect credentials before Phase 9 begins.

Build & Validation Process

After research and spec assembly, build the CLI and validate it against the live API. Read references/testing-methodology.md for detailed protocols.

8. Generate & Build — Generate code, compile, verify binary runs
9. Live API Validation — Auth gate, profile field discovery, test every command
10. Fix Loop — Classify failures, fix spec bugs, regenerate, retest
11. Intent Review — Validate responses against intent map acceptance criteria
12. SKILL.md Finalization — Replace draft with production SKILL.md from verified behavior

Auth Gate

Before Phase 9, you MUST check auth status and bootstrap credentials if missing. Do not ask the user to manually set environment variables — use the CLI's own auth commands.

Step 1: Check auth status

./<binary> auth status

Step 2: If not authenticated, launch the auth flow interactively

Auth Strategy	Action
oauth2	Ask the user to set CLIENT_ID and CLIENT_SECRET env vars, then suggest they run ! ./<binary> auth login (interactive — opens browser)
static_token / api_key	Suggest the user runs ! ./<binary> auth set (interactive hidden prompt — no secrets in Claude's context)
basic_auth	Suggest the user runs ! ./<binary> auth set (interactive hidden prompt)
Credentials unavailable	Produce smoke test checklist, mark SKILL.md as untested draft

Step 3: Verify auth landed

./<binary> auth status

Do not proceed to Phase 9 until auth status confirms authentication. The ! prefix runs the command in the user's terminal so interactive prompts (browser OAuth, hidden input) work correctly.

Failure Classification

Category	Definition	Action
spec_bug	Spec doesn't match API reality	Fix YAML, regenerate
framework_limitation	Generator can't express what the API does	Document, add workaround to SKILL.md
api_bug	API contradicts its own docs	Document, flag for user

Fix loop cap: Max 3 cycles without reducing spec_bug count → reclassify remaining as framework_limitation, proceed to Phase 11.

Spec Assembly

When writing the marten.yaml, consult these schema references:

• Core fields, config & models: references/spec-schema.md
• Auth configuration: references/spec-auth.md
• Commands & flags: references/spec-commands.md
• Workflows: references/spec-workflows.md
• Pagination: references/spec-pagination.md
• Validation & reserved names: references/spec-validation.md
• SKILL.md authoring: references/skill-authoring.md

Key decisions:

Choosing Auth Strategy

API Pattern	Strategy
OAuth 2.0 with authorization flow	oauth2
Bearer token from dashboard	static_token
Named API key in header	api_key
Username + password/secret	basic_auth

Designing the Command Tree

• Resource groups become parent commands: media, comments, orders
• CRUD operations become subcommands: list, get, create, delete
• Standalone endpoints become leaf commands: health, rate-limit
• Multi-step operations get workflow definitions

Identifying Workflows

Look for these patterns — they need workflow steps, not single API calls:

Pattern	Example
Create → publish	Instagram media publishing
Create → poll → use	Upload with async processing
Create children → create parent → publish	Carousel/batch operations
Request → poll until complete	Long-running operations

Profile Fields vs Flags

• Profile fields (path_params: { user_id: profile }) — values that stay constant across commands (user IDs, account IDs, store IDs). Set once via auth set or config.
• Flags (path_params: { item_id: flag }) — values that change per invocation (resource IDs).

Rule of thumb: If the user would type the same value in every command, it's a profile field. If it changes, it's a flag.

Discoverability: For each profile field, determine how a user finds their value — a /me endpoint, a dashboard settings page, a token introspection response, or a field on an existing record. Document this in the generated SKILL.md and research-log.md so users can self-serve setup without guessing.

Pagination

Most list endpoints are paginated. Check the API docs for:

• Cursor-based: look for cursor, after, next_token in responses
• Offset-based: look for page, offset, skip query params
• Keyset-based: look for sort + ID-based pagination
• Link header: check response headers for Link: <url>; rel="next"

Also check if the list is wrapped under a key (e.g., {"messages": [...]} uses response_list_key: "messages").

Validation

After writing the spec, validate it:

marten validate marten.yaml

Fix any errors — the validator reports exact YAML paths (e.g., auth.oauth2.auth_url: must not be empty).

Then generate and build to prove the spec produces valid Go:

marten generate ./output-dir/
cd output-dir && go mod tidy && go build ./...

Common Mistakes

Mistake	Fix
Model named Error or Response	Rename — these collide with pkg/contract types
Command named help or completion	Rename — Cobra reserves these
paginated: true without pagination_style	Add the style field
path_params: { id: flag } without matching flag	Add a flag with maps_to_path: id
Workflow step without step name	Every step needs a name
response_model referencing nonexistent model	Define the model in models section
Using response_model with complex nested JSON	Define only the fields you need — Go's omitempty handles the rest
Flag defined in both request_params[].flag and flags[]	Use one or the other — duplicates cause redeclaration errors in generated code
per_page or page in request_params on paginated command	Remove — the generator adds pagination params automatically based on pagination_style

Output Quality Checks

Before delivering the spec to the user:

• marten validate passes
• Every endpoint in scoped resource groups is represented
• Every required field from intent-map.md is present in response models
• intent-map.md statuses updated after Phase 11
• Auth strategy matches the API's actual auth mechanism
• Pagination style matches per endpoint
• response_list_key set for endpoints with wrapped list responses
• Workflow commands handle the full multi-step flow
• Profile fields capture values that stay constant
• Constraint information captured in documentation and command descriptions
• Model field types match API response JSON types
• research-log.md documents all sources and flags uncertainties
• Every command tested against live API (or smoke test checklist produced)
• Response models verified against actual API responses
• Framework limitations documented in research-log.md
• SKILL.md reflects verified behavior, not spec assumptions