# Spec Grounded Design > > - **Type:** Skill - **Install:** `agentstack add skill-hiteshbandhu-skills-i-use-spec-grounded-design` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [hiteshbandhu](https://agentstack.voostack.com/s/hiteshbandhu) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [hiteshbandhu](https://github.com/hiteshbandhu) - **Source:** https://github.com/hiteshbandhu/skills-i-use/tree/main/skills/spec-grounded-design ## Install ```sh agentstack add skill-hiteshbandhu-skills-i-use-spec-grounded-design ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Spec-Grounded Design Don't code an integration from memory or from docs you assume are right. **Get the real spec, probe the real behavior, treat reality as truth, then design against a contract.** Reverse-engineered and stale specs lag the live API — the live probe is non-negotiable. Works with any agent that can fetch docs and run a shell. No vendor APIs of its own. **Supporting files** (read when needed): - [grounding-checklist.md](grounding-checklist.md) — what to verify live, probe patterns, reality-wins rule - [design-contract-template.md](design-contract-template.md) — the contract output format Output: `{SKILL_OUTPUT_DIR}/spec-grounded-design/` — see [../OUTPUT.md](../OUTPUT.md) --- ## Step 0 — Scope the integration Establish (ask only if missing): 1. **The target** — which protocol / SDK / API, and which version or endpoint. 2. **What you need from it** — the specific operations the feature requires (not the whole surface — ground what you'll actually use). 3. **Probe access** — is there a sandbox/test key/local instance to hit safely? If the only instance is production, see the edge cases (read-only, never mutate prod to "test"). Resolve output dir per [../OUTPUT.md](../OUTPUT.md). Default `./skill-outputs/spec-grounded-design/`. --- ## Step 1 — Pull the primary source Fetch the **actual** spec — the protocol document, the official API reference, the SDK's typed source — not a blog, not memory, not a summary. Record the version and the URL. For each operation you need, capture from the spec: the request shape, the response shape, auth, error codes, pagination, rate limits, and anything stateful (sessions, cursors, idempotency keys). Note where the spec is vague or silent — those are exactly the spots the live probe will resolve. --- ## Step 2 — Probe the live behavior (non-negotiable) Read [grounding-checklist.md](grounding-checklist.md). Hit the real endpoint with the smallest possible request — `curl` or a tiny script — and capture **what actually happens**, not what the spec says should: - Real response shape and field names (casing, nesting, nulls). - Real error behavior — force a 401/404/429 and see the actual body and headers. - Real stateful behavior — session lifetime, what a dropped session returns, cursor format. - Real edge cases — empty results, large payloads, the silent defaults. **Read the probe output before writing any code.** This is the step that catches the spec-vs-reality gap. Show the user the raw probe result. --- ## Step 3 — Reconcile: reality wins Diff the spec against the probe. For every difference, **the live behavior is the truth** and the spec is wrong/stale. Record each delta explicitly: > SPEC says X · REALITY is Y · DESIGN against Y. If the probe contradicts a core assumption the feature depended on, surface that now — it may change the design or the feasibility before a line of code is written. --- ## Step 4 — Write the design contract Fill in [design-contract-template.md](design-contract-template.md): the verified facts per operation, the spec-vs-reality deltas, the edge cases the code must handle, and the **invariants** the implementation must preserve (e.g. "a dropped session returns 404 → re-initialize, do not reauth"). This contract is what you implement against and test against. Save it to the output dir; update `index.md`. --- ## Step 5 — Output to user 1. The path to the saved contract. 2. The 1–3 most important spec-vs-reality deltas — the things that would have caused bugs. 3. The invariants the implementation must hold. 4. A go / caution call: is the integration as expected, or did the probe surface something that changes the plan? 5. Do not implement here — the contract is the input to a separate, confirmed build step (pair with `architecture-review` if the probe revealed a real fork). --- ## Edge cases - **No sandbox, only production** — probe **read-only** (GET/list), never mutate prod to "test." If you must verify a write path, ask the user for a safe test tenant. - **Auth blocks the probe** — get a scoped test credential from the user; don't skip the probe and design blind. A blind design is the failure mode this skill exists to prevent. - **Spec and reality agree everywhere** — great; record that the contract is spec-verified and move on. The probe still paid for itself. - **The API is undocumented** — the probe *is* the spec; be extra thorough on errors and edge cases, and mark the contract "reverse-engineered, verify on upgrades." - **Secrets** — never write keys/tokens into the contract or the saved output; reference them by name. --- ## Invocation examples ``` @spec-grounded-design we're integrating the MCP streamable-HTTP transport — read the protocol and verify before we build design against the Stripe subscriptions API — is the spec right? how does this API actually behave on an expired session? probe it first ground this OAuth flow in the real endpoint before I write the client verify the pagination behavior live before we design the sync ``` ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [hiteshbandhu](https://github.com/hiteshbandhu) - **Source:** [hiteshbandhu/skills-i-use](https://github.com/hiteshbandhu/skills-i-use) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-hiteshbandhu-skills-i-use-spec-grounded-design - Seller: https://agentstack.voostack.com/s/hiteshbandhu - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.