jumpstart-mode 1.1.3 → 1.1.4

package/.jumpstart/compat/assistant-mapping.md

@@ -89,3 +89,35 @@ When setting up Jump Start for a new assistant:
 | Context7 MCP | ✅ | ✅ | ✅ | ✅ |
 
 Legend: ✅ Full support | ⚠️ Partial/workaround needed | ❌ Not supported
+
+---
+
+## Context7 MCP Setup
+
+Context7 MCP provides up-to-date library documentation. Setup is required for each AI assistant.
+
+> **Full documentation:** `.jumpstart/guides/context7-usage.md`
+
+### Installation (All Assistants)
+
+```bash
+npx add-mcp https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_API_KEY"
+```
+
+Add `-y` to skip confirmation. Get an API key at: https://context7.com/dashboard
+
+### Context7 Tools
+
+| Tool | Full MCP Name | Parameters |
+|------|---------------|------------|
+| Resolve Library | `mcp_context7_resolve-library-id` | `libraryName` (required), `query` (required) |
+| Query Documentation | `mcp_context7_query-docs` | `libraryId` (required), `query` (required) |
+
+### Client-Specific Notes
+
+| Client | MCP Configuration Location |
+|--------|---------------------------|
+| VS Code Copilot | MCP settings in VS Code (auto-detected by add-mcp) |
+| Cursor | `Cursor Settings > MCP` or install via Cursor marketplace plugin |
+| Claude Code | MCP configuration via add-mcp CLI |
+| Windsurf | MCP configuration (auto-detected by add-mcp) |

package/.jumpstart/guides/context7-usage.md

@@ -0,0 +1,242 @@
+# Context7 MCP Usage Guide
+
+> **Purpose:** Authoritative reference for calling Context7 MCP tools correctly across all Jump Start agents.
+> **Last Updated:** 2026-02-09
+> **Source:** [Context7 Official Documentation](https://context7.com/docs)
+
+---
+
+## Overview
+
+Context7 MCP provides up-to-date, version-specific documentation for libraries, frameworks, and tools. It eliminates hallucinated APIs and outdated code examples by fetching live documentation directly into the AI assistant's context.
+
+**Rule:** Never rely on training data for API signatures, configuration flags, version compatibility, or setup instructions. Always use Context7.
+
+---
+
+## Available Tools
+
+Context7 MCP exposes two tools. When invoked via MCP clients (VS Code Copilot, Cursor, Claude Code, etc.), tools are prefixed with `mcp_context7_`.
+
+### 1. `resolve-library-id`
+
+Resolves a general library name into a Context7-compatible library ID.
+
+**Full MCP Name:** `mcp_context7_resolve-library-id`
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `libraryName` | string | Yes | The name of the library to search for (e.g., "nextjs", "prisma", "react") |
+| `query` | string | Yes | The user's question or task — used to rank results by relevance |
+
+**Example Invocation:**
+
+```json
+{
+  "libraryName": "nextjs",
+  "query": "How do I set up middleware for authentication?"
+}
+```
+
+**Returns:** A list of matching libraries with their Context7 library IDs (e.g., `/vercel/next.js`).
+
+---
+
+### 2. `query-docs`
+
+Retrieves documentation for a library using a Context7-compatible library ID.
+
+**Full MCP Name:** `mcp_context7_query-docs`
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `libraryId` | string | Yes | Exact Context7-compatible library ID (e.g., `/vercel/next.js`, `/prisma/prisma`) |
+| `query` | string | Yes | The question or task to get relevant documentation for |
+
+**Example Invocation:**
+
+```json
+{
+  "libraryId": "/vercel/next.js",
+  "query": "How do I configure middleware to check JWT cookies?"
+}
+```
+
+**Returns:** Relevant documentation snippets, code examples, and API references for the specified query.
+
+---
+
+## Library ID Format
+
+Context7 library IDs follow the pattern `/{owner}/{repo}`:
+
+| Library | Context7 Library ID |
+|---------|---------------------|
+| Next.js | `/vercel/next.js` |
+| React | `/facebook/react` |
+| Prisma | `/prisma/prisma` |
+| Tailwind CSS | `/tailwindlabs/tailwindcss` |
+| Express | `/expressjs/express` |
+| MongoDB Node Driver | `/mongodb/docs` |
+| Supabase | `/supabase/supabase` |
+
+**Tip:** If you know the exact library ID, you can skip `resolve-library-id` and call `query-docs` directly.
+
+---
+
+## Standard Calling Pattern
+
+### Two-Step Pattern (Recommended)
+
+Use this when you don't know the exact library ID:
+
+```
+Step 1: Resolve the library ID
+  Tool: mcp_context7_resolve-library-id
+  Input: { "libraryName": "prisma", "query": "database migrations setup" }
+  Output: Library ID = /prisma/prisma
+
+Step 2: Fetch documentation
+  Tool: mcp_context7_query-docs
+  Input: { "libraryId": "/prisma/prisma", "query": "database migrations setup" }
+  Output: Documentation snippets about Prisma migrations
+```
+
+### Direct Pattern (When Library ID is Known)
+
+Skip resolution when you already have the library ID:
+
+```
+Tool: mcp_context7_query-docs
+Input: { "libraryId": "/vercel/next.js", "query": "server actions configuration" }
+Output: Documentation about Next.js server actions
+```
+
+---
+
+## Citation Format
+
+After fetching documentation, add a citation marker to your output:
+
+**Standard Format:** `[Context7: library@version]`
+
+**Examples:**
+- `[Context7: next.js@14]`
+- `[Context7: prisma@5.22]`
+- `[Context7: react@18.3]`
+
+Place the citation marker next to the technology reference in your artifact.
+
+---
+
+## When to Use Context7
+
+| Phase | Agent | When Required |
+|-------|-------|---------------|
+| Phase 1 | Analyst | Competitive technology evaluation |
+| Phase 3 | Architect | Documentation Freshness Audit (hard gate, ≥80% score required) |
+| Phase 4 | Developer | Before writing external API integration code |
+| Any | Researcher | Technology claim verification |
+| Any | Any Agent | When making claims about technology capabilities, limitations, or APIs |
+
+---
+
+## Error Handling
+
+### Library Not Found
+
+If `resolve-library-id` returns no results:
+1. Try alternative library names (e.g., "next" vs "nextjs" vs "next.js")
+2. Search for the parent organization (e.g., "vercel" for Next.js)
+3. Fall back to official documentation URL with manual verification
+4. Document in the artifact: "Context7 library not found. Falling back to: [URL]"
+
+### Rate Limiting
+
+If requests are rate-limited:
+1. Wait and retry with exponential backoff
+2. Prioritize "Must Have" technologies for verification
+3. Document unverified technologies as requiring manual verification
+
+### Service Unavailable
+
+If Context7 MCP is unavailable:
+1. Document all technologies as "Unverified — Context7 unavailable"
+2. Provide official documentation URLs for manual verification
+3. Flag in insights file for follow-up verification
+
+---
+
+## MCP Setup Instructions
+
+### Installation
+
+Install Context7 MCP for your AI coding assistant:
+
+```bash
+npx add-mcp https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_API_KEY"
+```
+
+Add `-y` to skip confirmation and install to all detected agents.
+
+### Get an API Key
+
+For higher rate limits, get a free API key at: https://context7.com/dashboard
+
+### Client-Specific Setup
+
+| Client | Configuration Location |
+|--------|------------------------|
+| VS Code Copilot | MCP settings in VS Code |
+| Cursor | `Cursor Settings > MCP` or marketplace plugin |
+| Claude Code | MCP configuration via add-mcp |
+| Windsurf | MCP configuration |
+
+---
+
+## Best Practices
+
+1. **Always use the full MCP tool name** (`mcp_context7_query-docs`) in documentation to avoid ambiguity.
+2. **Include a descriptive query** — the query parameter helps Context7 return the most relevant documentation.
+3. **Verify versions** — confirm the version you're using matches the documentation fetched.
+4. **Cite your sources** — always add the `[Context7: lib@version]` marker.
+5. **Batch related queries** — if verifying multiple technologies, group related lookups by topic.
+6. **Document failures** — if Context7 cannot verify a technology, document the fallback source.
+
+---
+
+## Quick Reference Card
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  CONTEXT7 MCP QUICK REFERENCE                                   │
+├─────────────────────────────────────────────────────────────────┤
+│  RESOLVE LIBRARY ID                                             │
+│  Tool: mcp_context7_resolve-library-id                          │
+│  Params: libraryName (required), query (required)               │
+│  Example: { "libraryName": "prisma", "query": "setup guide" }   │
+├─────────────────────────────────────────────────────────────────┤
+│  FETCH DOCUMENTATION                                            │
+│  Tool: mcp_context7_query-docs                                  │
+│  Params: libraryId (required), query (required)                 │
+│  Example: { "libraryId": "/prisma/prisma", "query": "setup" }   │
+├─────────────────────────────────────────────────────────────────┤
+│  CITATION FORMAT                                                │
+│  [Context7: library@version]                                    │
+│  Example: [Context7: next.js@14]                                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Related Documentation
+
+- [Context7 Official Docs](https://context7.com/docs)
+- [Context7 Troubleshooting](https://context7.com/docs/resources/troubleshooting)
+- [MCP Clients List](https://context7.com/docs/resources/all-clients)
+- Jump Start: `.jumpstart/templates/documentation-audit.md`
+- Jump Start: `.jumpstart/agents/researcher.md`

package/.jumpstart/templates/documentation-audit.md

@@ -28,10 +28,16 @@ Enumerate every external library, framework, CLI tool, or service referenced in
 
 ## Audit Protocol
 
+> **Reference:** See `.jumpstart/guides/context7-usage.md` for complete Context7 MCP calling instructions.
+
 For each technology in the registry:
 
-1. **Resolve** the Context7 library ID using `resolve-library-id`
-2. **Fetch** current documentation using `get-library-docs` with relevant topics (setup, configuration, API, breaking changes)
+1. **Resolve** the Context7 library ID using `mcp_context7_resolve-library-id`:
+   - `libraryName` (required): The technology name (e.g., "nextjs", "prisma")
+   - `query` (required): Your specific question (e.g., "setup and configuration")
+2. **Fetch** current documentation using `mcp_context7_query-docs`:
+   - `libraryId` (required): The resolved ID (e.g., `/vercel/next.js`)
+   - `query` (required): Topics relevant to your usage (setup, configuration, API, breaking changes)
 3. **Verify** that the version referenced in the Architecture Document matches the latest stable version (or document why an older version is chosen)
 4. **Record** a citation marker in the Architecture Document next to each technology reference
 5. **Flag** any breaking changes between the version in use and the latest version

package/CLAUDE.md

@@ -1,52 +1,54 @@
-# Jump Start Framework Instructions
-
-This repository uses the Jump Start spec-driven agentic coding framework.
-
-## Context7 MCP Mandate (HIGH PRIORITY)
-
-**CRITICAL RULE:** When referencing any external library, framework, CLI tool, or service — you MUST use Context7 MCP to fetch live, verified documentation. Never rely on training data for:
-- API signatures, method parameters, or return types
-- Configuration flags, options, or environment variables
-- Version compatibility, breaking changes, or migration guides
-- Setup instructions, installation steps, or prerequisites
-- Feature availability or deprecation status
-
-**How to use Context7:**
-1. Resolve the library ID: Use `mcp_context7_resolve-library-id` with the library name
-2. Fetch current docs: Use `mcp_context7_get-library-docs` with the resolved ID and relevant topic
-3. Cite your source: Add `[Context7: library@version]` marker in your output
-
-**When is this required?**
-- Architect Phase 3: Documentation Freshness Audit before approval
-- Developer Phase 4: Before writing any external API integration code
-- Analyst Phase 1: When evaluating competitive technologies
-- Any agent: When making claims about what a technology can or cannot do
-
-## Spec-First Power Inversion (Item 4)
-
-Specs are the source of truth. Code is derived. If there is a mismatch between a spec artifact and the codebase, update the spec first or regenerate the code. Never silently alter code to diverge from specs.
-
-## Slash Command Routing
-
-| Command | Action |
-|---------|--------|
-| `/jumpstart.scout` | Check `project.type` is `brownfield`. Load `.jumpstart/agents/scout.md`. Follow Reconnaissance Protocol. Output to `specs/codebase-context.md`. |
-| `/jumpstart.challenge [idea]` | Load `.jumpstart/agents/challenger.md`. Follow the Elicitation Protocol. Output to `specs/challenger-brief.md`. |
-| `/jumpstart.analyze` | Verify Phase 0 approved. Load `.jumpstart/agents/analyst.md`. Output to `specs/product-brief.md`. |
-| `/jumpstart.plan` | Verify Phases 0-1 approved. Load `.jumpstart/agents/pm.md`. Output to `specs/prd.md`. |
-| `/jumpstart.architect` | Verify Phases 0-2 approved. Load `.jumpstart/agents/architect.md`. Output to `specs/architecture.md`, `specs/implementation-plan.md`, `specs/decisions/*.md`. |
-| `/jumpstart.build` | Verify Phases 0-3 approved. Load `.jumpstart/agents/developer.md`. Output code to `src/`, tests to `tests/`. |
-| `/jumpstart.party` | Load `.jumpstart/agents/facilitator.md`. Launch multi-agent roundtable discussion. Advisory only — no artifact writes. |
-| `/jumpstart.status` | Read config and all spec files. Report phase completion status. |
-| `/jumpstart.review` | Validate current artifacts against templates. Report gaps. |
-
-## Rules
-
-1. Phases are sequential. Check for Phase Gate Approval (all checkboxes checked, "Approved by" not "Pending").
-2. Follow agent personas exactly. Each agent file has a complete step-by-step protocol.
-3. Always ask for explicit human approval before phase transitions.
-4. Use templates from `.jumpstart/templates/`.
-5. Read `.jumpstart/config.yaml` at the start of every command.
-6. Read `.jumpstart/roadmap.md` at activation. Roadmap principles are non-negotiable and supersede agent-specific instructions.
-7. Read `.jumpstart/roadmap.md` for engineering articles governing code quality and architecture decisions.
-8. Use Context7 MCP for ALL external documentation lookups. Never guess API details from training data.
+# Jump Start Framework Instructions
+
+This repository uses the Jump Start spec-driven agentic coding framework.
+
+## Context7 MCP Mandate (HIGH PRIORITY)
+
+**CRITICAL RULE:** When referencing any external library, framework, CLI tool, or service — you MUST use Context7 MCP to fetch live, verified documentation. Never rely on training data for:
+- API signatures, method parameters, or return types
+- Configuration flags, options, or environment variables
+- Version compatibility, breaking changes, or migration guides
+- Setup instructions, installation steps, or prerequisites
+- Feature availability or deprecation status
+
+**How to use Context7:**
+1. Resolve the library ID: Use `mcp_context7_resolve-library-id` with `libraryName` and `query` parameters
+2. Fetch current docs: Use `mcp_context7_query-docs` with `libraryId` (e.g., `/vercel/next.js`) and `query` parameters
+3. Cite your source: Add `[Context7: library@version]` marker in your output
+
+> **Full documentation:** `.jumpstart/guides/context7-usage.md`
+
+**When is this required?**
+- Architect Phase 3: Documentation Freshness Audit before approval
+- Developer Phase 4: Before writing any external API integration code
+- Analyst Phase 1: When evaluating competitive technologies
+- Any agent: When making claims about what a technology can or cannot do
+
+## Spec-First Power Inversion (Item 4)
+
+Specs are the source of truth. Code is derived. If there is a mismatch between a spec artifact and the codebase, update the spec first or regenerate the code. Never silently alter code to diverge from specs.
+
+## Slash Command Routing
+
+| Command | Action |
+|---------|--------|
+| `/jumpstart.scout` | Check `project.type` is `brownfield`. Load `.jumpstart/agents/scout.md`. Follow Reconnaissance Protocol. Output to `specs/codebase-context.md`. |
+| `/jumpstart.challenge [idea]` | Load `.jumpstart/agents/challenger.md`. Follow the Elicitation Protocol. Output to `specs/challenger-brief.md`. |
+| `/jumpstart.analyze` | Verify Phase 0 approved. Load `.jumpstart/agents/analyst.md`. Output to `specs/product-brief.md`. |
+| `/jumpstart.plan` | Verify Phases 0-1 approved. Load `.jumpstart/agents/pm.md`. Output to `specs/prd.md`. |
+| `/jumpstart.architect` | Verify Phases 0-2 approved. Load `.jumpstart/agents/architect.md`. Output to `specs/architecture.md`, `specs/implementation-plan.md`, `specs/decisions/*.md`. |
+| `/jumpstart.build` | Verify Phases 0-3 approved. Load `.jumpstart/agents/developer.md`. Output code to `src/`, tests to `tests/`. |
+| `/jumpstart.party` | Load `.jumpstart/agents/facilitator.md`. Launch multi-agent roundtable discussion. Advisory only — no artifact writes. |
+| `/jumpstart.status` | Read config and all spec files. Report phase completion status. |
+| `/jumpstart.review` | Validate current artifacts against templates. Report gaps. |
+
+## Rules
+
+1. Phases are sequential. Check for Phase Gate Approval (all checkboxes checked, "Approved by" not "Pending").
+2. Follow agent personas exactly. Each agent file has a complete step-by-step protocol.
+3. Always ask for explicit human approval before phase transitions.
+4. Use templates from `.jumpstart/templates/`.
+5. Read `.jumpstart/config.yaml` at the start of every command.
+6. Read `.jumpstart/roadmap.md` at activation. Roadmap principles are non-negotiable and supersede agent-specific instructions.
+7. Read `.jumpstart/roadmap.md` for engineering articles governing code quality and architecture decisions.
+8. Use Context7 MCP for ALL external documentation lookups. Never guess API details from training data.