jumpstart-mode 1.1.13 → 1.1.14

package/.jumpstart/skills/linkerd-patterns/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: linkerd-patterns
+description: Implement Linkerd service mesh patterns for lightweight, security-focused service mesh deployments. Use when setting up Linkerd, configuring traffic policies, or implementing zero-trust networking with minimal overhead.
+---
+
+# Linkerd Patterns
+
+Production patterns for Linkerd service mesh - the lightweight, security-first service mesh for Kubernetes.
+
+## When to Use This Skill
+
+- Setting up a lightweight service mesh
+- Implementing automatic mTLS
+- Configuring traffic splits for canary deployments
+- Setting up service profiles for per-route metrics
+- Implementing retries and timeouts
+- Multi-cluster service mesh
+
+## Core Concepts
+
+### 1. Linkerd Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│                Control Plane                 │
+│  ┌─────────┐ ┌──────────┐ ┌──────────────┐ │
+│  │ destiny │ │ identity │ │ proxy-inject │ │
+│  └─────────┘ └──────────┘ └──────────────┘ │
+└─────────────────────────────────────────────┘
+                      │
+┌─────────────────────────────────────────────┐
+│                 Data Plane                   │
+│  ┌─────┐    ┌─────┐    ┌─────┐             │
+│  │proxy│────│proxy│────│proxy│             │
+│  └─────┘    └─────┘    └─────┘             │
+│     │           │           │               │
+│  ┌──┴──┐    ┌──┴──┐    ┌──┴──┐            │
+│  │ app │    │ app │    │ app │            │
+│  └─────┘    └─────┘    └─────┘            │
+└─────────────────────────────────────────────┘
+```
+
+### 2. Key Resources
+
+| Resource                | Purpose                              |
+| ----------------------- | ------------------------------------ |
+| **ServiceProfile**      | Per-route metrics, retries, timeouts |
+| **TrafficSplit**        | Canary deployments, A/B testing      |
+| **Server**              | Define server-side policies          |
+| **ServerAuthorization** | Access control policies              |
+
+## Templates
+
+### Template 1: Mesh Installation
+
+```bash
+# Install CLI
+curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install | sh
+
+# Validate cluster
+linkerd check --pre
+
+# Install CRDs
+linkerd install --crds | kubectl apply -f -
+
+# Install control plane
+linkerd install | kubectl apply -f -
+
+# Verify installation
+linkerd check
+
+# Install viz extension (optional)
+linkerd viz install | kubectl apply -f -
+```
+
+### Template 2: Inject Namespace
+
+```yaml
+# Automatic injection for namespace
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: my-app
+  annotations:
+    linkerd.io/inject: enabled
+---
+# Or inject specific deployment
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app
+  annotations:
+    linkerd.io/inject: enabled
+spec:
+  template:
+    metadata:
+      annotations:
+        linkerd.io/inject: enabled
+```
+
+### Template 3: Service Profile with Retries
+
+```yaml
+apiVersion: linkerd.io/v1alpha2
+kind: ServiceProfile
+metadata:
+  name: my-service.my-namespace.svc.cluster.local
+  namespace: my-namespace
+spec:
+  routes:
+    - name: GET /api/users
+      condition:
+        method: GET
+        pathRegex: /api/users
+      responseClasses:
+        - condition:
+            status:
+              min: 500
+              max: 599
+          isFailure: true
+      isRetryable: true
+    - name: POST /api/users
+      condition:
+        method: POST
+        pathRegex: /api/users
+      # POST not retryable by default
+      isRetryable: false
+    - name: GET /api/users/{id}
+      condition:
+        method: GET
+        pathRegex: /api/users/[^/]+
+      timeout: 5s
+      isRetryable: true
+  retryBudget:
+    retryRatio: 0.2
+    minRetriesPerSecond: 10
+    ttl: 10s
+```
+
+### Template 4: Traffic Split (Canary)
+
+```yaml
+apiVersion: split.smi-spec.io/v1alpha1
+kind: TrafficSplit
+metadata:
+  name: my-service-canary
+  namespace: my-namespace
+spec:
+  service: my-service
+  backends:
+    - service: my-service-stable
+      weight: 900m # 90%
+    - service: my-service-canary
+      weight: 100m # 10%
+```
+
+### Template 5: Server Authorization Policy
+
+```yaml
+# Define the server
+apiVersion: policy.linkerd.io/v1beta1
+kind: Server
+metadata:
+  name: my-service-http
+  namespace: my-namespace
+spec:
+  podSelector:
+    matchLabels:
+      app: my-service
+  port: http
+  proxyProtocol: HTTP/1
+---
+# Allow traffic from specific clients
+apiVersion: policy.linkerd.io/v1beta1
+kind: ServerAuthorization
+metadata:
+  name: allow-frontend
+  namespace: my-namespace
+spec:
+  server:
+    name: my-service-http
+  client:
+    meshTLS:
+      serviceAccounts:
+        - name: frontend
+          namespace: my-namespace
+---
+# Allow unauthenticated traffic (e.g., from ingress)
+apiVersion: policy.linkerd.io/v1beta1
+kind: ServerAuthorization
+metadata:
+  name: allow-ingress
+  namespace: my-namespace
+spec:
+  server:
+    name: my-service-http
+  client:
+    unauthenticated: true
+    networks:
+      - cidr: 10.0.0.0/8
+```
+
+### Template 6: HTTPRoute for Advanced Routing
+
+```yaml
+apiVersion: policy.linkerd.io/v1beta2
+kind: HTTPRoute
+metadata:
+  name: my-route
+  namespace: my-namespace
+spec:
+  parentRefs:
+    - name: my-service
+      kind: Service
+      group: core
+      port: 8080
+  rules:
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /api/v2
+        - headers:
+            - name: x-api-version
+              value: v2
+      backendRefs:
+        - name: my-service-v2
+          port: 8080
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /api
+      backendRefs:
+        - name: my-service-v1
+          port: 8080
+```
+
+### Template 7: Multi-cluster Setup
+
+```bash
+# On each cluster, install with cluster credentials
+linkerd multicluster install | kubectl apply -f -
+
+# Link clusters
+linkerd multicluster link --cluster-name west \
+  --api-server-address https://west.example.com:6443 \
+  | kubectl apply -f -
+
+# Export a service to other clusters
+kubectl label svc/my-service mirror.linkerd.io/exported=true
+
+# Verify cross-cluster connectivity
+linkerd multicluster check
+linkerd multicluster gateways
+```
+
+## Monitoring Commands
+
+```bash
+# Live traffic view
+linkerd viz top deploy/my-app
+
+# Per-route metrics
+linkerd viz routes deploy/my-app
+
+# Check proxy status
+linkerd viz stat deploy -n my-namespace
+
+# View service dependencies
+linkerd viz edges deploy -n my-namespace
+
+# Dashboard
+linkerd viz dashboard
+```
+
+## Debugging
+
+```bash
+# Check injection status
+linkerd check --proxy -n my-namespace
+
+# View proxy logs
+kubectl logs deploy/my-app -c linkerd-proxy
+
+# Debug identity/TLS
+linkerd identity -n my-namespace
+
+# Tap traffic (live)
+linkerd viz tap deploy/my-app --to deploy/my-backend
+```
+
+## Best Practices
+
+### Do's
+
+- **Enable mTLS everywhere** - It's automatic with Linkerd
+- **Use ServiceProfiles** - Get per-route metrics and retries
+- **Set retry budgets** - Prevent retry storms
+- **Monitor golden metrics** - Success rate, latency, throughput
+
+### Don'ts
+
+- **Don't skip check** - Always run `linkerd check` after changes
+- **Don't over-configure** - Linkerd defaults are sensible
+- **Don't ignore ServiceProfiles** - They unlock advanced features
+- **Don't forget timeouts** - Set appropriate values per route
+
+## Resources
+
+- [Linkerd Documentation](https://linkerd.io/2.14/overview/)
+- [Service Profiles](https://linkerd.io/2.14/features/service-profiles/)
+- [Authorization Policy](https://linkerd.io/2.14/features/server-policy/)

package/.jumpstart/skills/mcp-server-designer/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: mcp-server-designer
+description: Design a Model Context Protocol (MCP) server surface for a specific business domain, including tool definitions, resource URIs, prompt templates, input/output schemas, auth model, rate limits, error contracts, and operational concerns. Use this whenever the user needs to design an MCP server, expose business capabilities to AI agents via MCP, define the tool and resource surface for a domain, or build a structured integration layer between an AI agent and a system-of-record using the MCP standard, even when phrased as "build an MCP server," "expose this as tools," "MCP tool design," or "agent integration layer."
+argument-hint: Paste the business domain, systems to expose, operations needed (read/write/event), auth model, and the agent consumers.
+---
+
+# MCP Server Designer
+
+## Positioning
+
+Use this skill to design the MCP server surface — tools, resources, prompts, schemas, auth, and operational contracts — before writing code. The output gives a developer or Pod a clear spec to implement from, and gives an architect confidence in the scope, security, and operational viability of the MCP integration.
+
+## When To Use This
+
+- The user is exposing a business system to AI agents via MCP.
+- The team needs to define which operations, resources, and prompts to expose and how.
+- Phrased as "build an MCP server," "expose these as tools," "define the MCP surface," or "agent integration layer."
+
+## When Not To Use This Alone
+
+- For agent governance, use `../agent-governance/SKILL.md`.
+- For agent permissioning, use `../agent-permissioning-designer/SKILL.md`.
+- For integration risk, use `../integration-surface-mapper/SKILL.md`.
+
+## Required Inputs
+
+- business domain and systems to expose,
+- operations needed by agent consumers (read, write, event, search),
+- consumer agents and their trust levels,
+- auth model and identity context,
+- data sensitivity and access controls,
+- performance constraints (latency, concurrency).
+
+## MCP Surface Components
+
+### Tools
+Actions the agent can invoke with typed inputs and outputs:
+- Name, description, input schema (JSON Schema), output schema.
+- Side effects (read-only, write, external call, irreversible).
+- Auth and permission requirements.
+- Rate limits and cost.
+- Error contract (error codes, retry guidance).
+- Idempotency model.
+
+### Resources
+Contextual data the agent can read (URIs with content types):
+- URI pattern, description, content type (text, JSON, markdown).
+- Access control and freshness guarantee.
+- Pagination or streaming model.
+
+### Prompts
+Pre-built prompt templates the server offers to agents:
+- Name, description, arguments.
+- When to use vs. when the agent should construct its own.
+
+See [references/mcp-design-guide.md](./references/mcp-design-guide.md) for best practices, schema patterns, and anti-patterns.
+
+## Workflow
+
+1. Inventory the business capabilities to expose.
+2. Classify each as tool (action), resource (read), or prompt (template).
+3. Design the input/output schema for each tool with JSON Schema.
+4. Define the auth model: how the agent authenticates, how user context is passed.
+5. Set rate limits, concurrency, and error contracts per tool.
+6. Design the resource URI hierarchy and access model.
+7. Identify operational concerns: monitoring, versioning, deprecation.
+8. Produce the design using [templates/mcp-server-design-template.md](./templates/mcp-server-design-template.md).
+
+## Output Mode
+
+Default artifact:
+
+- Executive summary (domain, tool count, resource count, auth model).
+- Tool catalog table (name, description, inputs, outputs, side effects, auth, rate limit).
+- Resource catalog table (URI, content type, access, freshness).
+- Prompt catalog (name, arguments, use case).
+- Auth and identity design.
+- Error contract and retry guidance.
+- Rate limit and concurrency model.
+- Versioning and deprecation strategy.
+- Operational monitoring plan.
+- Mermaid diagram of the MCP server and its consumers.
+
+## Working Rules
+
+1. Design tools at the business-operation level, not the CRUD level. "Submit expense report" not "POST /expenses."
+2. Every write tool must declare side effects, reversibility, and idempotency.
+3. Resources should be read-only; do not expose mutable state as resources.
+4. Auth must be explicit per tool. Do not rely on ambient agent credentials alone.
+5. Version the MCP surface; deprecation must be communicated to consumers.
+6. Rate limits exist to protect the backend; make them visible in the contract, not hidden.

package/.jumpstart/skills/mcp-server-designer/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "mcp-server-designer",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design an MCP server for our HR system that lets agents look up employee info, submit leave requests, and check leave balances. The server should enforce that only the employee or their manager can access their data.",
+      "expected_output": "MCP server design with typed tools (lookup_employee, submit_leave_request, get_leave_balance), resources for org-chart context, OBO auth with user-context claims, and error contracts.",
+      "files": [],
+      "assertions": [
+        {"text": "Tools are at business-operation granularity, not CRUD"},
+        {"text": "Auth design enforces user-context for data access scoping"},
+        {"text": "Side effects are declared for each tool (submit_leave_request creates)"},
+        {"text": "Error contract includes standard envelope with retry guidance"}
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "We want to expose our Salesforce CRM to AI agents via MCP. Agents should be able to search accounts, read opportunity details, update opportunity stage, and add notes. Design the MCP server surface.",
+      "expected_output": "MCP server with 4 typed tools, input schemas with constrained enums for stage values, side-effect declarations, rate limits, and versioning strategy.",
+      "files": [],
+      "assertions": [
+        {"text": "Update-stage tool constrains stage to valid enum values"},
+        {"text": "Read tools marked read_only; update and add-note marked as modifies"},
+        {"text": "Rate limits declared per tool"},
+        {"text": "Includes operational monitoring section with metrics and alerts"}
+      ]
+    }
+  ]
+}

package/.jumpstart/skills/mcp-server-designer/examples/example-finance-domain-mcp.md

@@ -0,0 +1,63 @@
+# Example: Finance Domain MCP Server
+
+## Purpose
+Expose finance-domain capabilities to internal agents (forecasting copilot, AP automation, audit assistant) through one MCP surface so each agent does not reimplement integrations.
+
+## Scope
+- Read access to invoices, POs, GL entries, vendor master.
+- Aggregate reports.
+- No payment initiation (separate, higher-trust server).
+
+## Capabilities
+
+### Tools
+| Name | Description | Inputs | Side effect | Auth |
+|---|---|---|---|---|
+| `invoices.search` | Find invoices by criteria | `{vendor_id?, date_range, status?, cost_center?}` | read | OBO |
+| `invoice.get` | Fetch one invoice with line items | `{invoice_id}` | read | OBO + ABAC |
+| `po.get` | Fetch PO and matching status | `{po_id}` | read | OBO + ABAC |
+| `gl.entries.search` | GL entries by account/period | `{account, period, cost_center?}` | read | OBO |
+| `vendor.lookup` | Vendor master record | `{vendor_id\|name}` | read | OBO |
+| `report.run` | Run a defined report (allow-listed) | `{report_id, params}` | read (aggregate) | OBO |
+
+### Resources (URI scheme: `finance://`)
+- `finance://invoice/{invoice_id}` — single invoice doc.
+- `finance://po/{po_id}` — single PO doc.
+- `finance://policy/ap-controls` — current AP control policy.
+- `finance://glossary` — domain glossary.
+
+### Prompts
+- `summarize_invoice` — structured summary template for an invoice resource.
+- `variance_analysis` — prompt for explaining variance vs. budget given GL entries.
+
+## Auth
+- OBO via Entra; agent acts as the calling user.
+- ABAC enforced server-side: cost-center membership filters every read.
+- No service-to-service trust without federated identity.
+
+## Rate limits and quotas
+- Per-user: 120 calls/min on search, 600/min on get.
+- Per-agent: shared quota at app-registration level.
+- Backoff guidance returned in error envelope.
+
+## Errors
+- Standard envelope: `{code, message, retryable, context}`.
+- Specific codes: `auth_required`, `forbidden`, `not_found`, `rate_limited`, `validation_error`, `upstream_unavailable`.
+
+## Observability
+- Every call traced: caller_user, tool, params (PII-scrubbed), latency, status, cost.
+- Sample of payloads stored for eval-on-production.
+- Drift on input distribution monitored.
+
+## Versioning
+- `v1` capability set is frozen; additive changes only without major bump.
+- Deprecation contract: 90-day notice, dual-running.
+
+## Testing
+- Contract tests for every tool and resource.
+- Eval set covering happy path, ABAC enforcement, error envelope correctness.
+- Load test at 5× peak.
+
+## Out of scope
+- Payment initiation (separate MCP server with stricter trust).
+- Cross-tenant queries.

package/.jumpstart/skills/mcp-server-designer/references/mcp-design-guide.md

@@ -0,0 +1,95 @@
+# MCP Design Guide
+
+Best practices, schema patterns, and anti-patterns for designing MCP server surfaces.
+
+## Design Principles
+
+1. **Business-operation granularity**: Expose tools at the level of business operations ("submit_expense", "approve_leave") not CRUD endpoints ("POST /expenses", "PATCH /leave/123").
+2. **Explicit side effects**: Every tool declaration must state what it changes in the world.
+3. **Read via resources, act via tools**: Resources are read-only context; tools are actions.
+4. **Typed contracts**: JSON Schema for every input and output; no freeform "data" fields.
+5. **Fail-safe by default**: Tools should validate inputs and fail-closed rather than accepting partial/ambiguous data.
+
+## Tool Design Patterns
+
+### Input Schema
+- Use JSON Schema with `required`, `enum`, `pattern`, `minLength`, `maxLength`.
+- Constrain IDs to expected formats (UUID, alphanumeric).
+- Use `description` on every property — the agent reads this to understand how to call the tool.
+- Avoid deeply nested schemas; flatten where possible.
+
+### Output Schema
+- Return structured objects, not prose.
+- Include a `status` field ("success", "error", "partial").
+- Include `metadata` (timestamps, resource IDs, links) for the agent to reason over.
+- Avoid returning large blobs; paginate or summarize.
+
+### Side Effects Declaration
+- `read_only: true/false`
+- `creates: [resource_type]`
+- `modifies: [resource_type]`
+- `deletes: [resource_type]`
+- `external_call: true/false` (calls outside the MCP server boundary)
+- `irreversible: true/false`
+
+### Idempotency
+- Write tools should support idempotency keys or natural deduplication.
+- Document what happens on duplicate calls.
+
+### Error Contract
+- Standard error envelope: `{ "error": { "code": "...", "message": "...", "retry_after_seconds": N } }`
+- Document all known error codes per tool.
+- Distinguish client errors (bad input), auth errors, and server errors.
+- Provide retry guidance (retryable vs. terminal).
+
+## Resource Design Patterns
+
+- URI hierarchy mirrors business domain: `/customers/{id}/orders`, not internal DB structure.
+- Content types: prefer `application/json` for structured; `text/markdown` for narrative context.
+- Freshness: declare `max_age_seconds` or `real_time` per resource.
+- Access control: declare required scopes per resource.
+
+## Prompt Design Patterns
+
+- Prompts are pre-built templates the server offers for common tasks.
+- Useful for complex multi-step workflows where the server knows the optimal flow.
+- Include argument descriptions and defaults.
+- Let agents construct their own prompts for novel tasks; don't force all usage through server prompts.
+
+## Auth Patterns for MCP
+
+- Server authenticates agent via OAuth token or API key.
+- User context passed as a claim or header (for on-behalf-of patterns).
+- Tool-level auth: some tools may require elevated scope (declared in tool metadata).
+- Token refresh handled by the MCP protocol layer.
+
+## Rate Limiting
+
+- Declare rate limits per tool in the server manifest.
+- Return `429` with `retry_after_seconds` when exceeded.
+- Consider per-user vs. per-agent limits.
+- Budget-aware tools: include cost estimate in response metadata.
+
+## Versioning
+
+- Semantic versioning for the MCP server.
+- Deprecation notices in tool descriptions before removal.
+- Breaking changes = major version bump.
+- Consumer agents should handle graceful degradation on version mismatch.
+
+## Anti-Patterns
+
+- **CRUD mirrors**: Exposing raw DB operations instead of business operations.
+- **Untyped catch-alls**: Tools that accept "any JSON" as input.
+- **Implicit state**: Tools that depend on hidden session state not visible to the agent.
+- **Giant tools**: One tool that does 15 things based on a "mode" parameter. Split them.
+- **Missing error contracts**: Agent can't tell if it should retry, rephrase, or give up.
+- **Mutable resources**: Resources should be read-only; mutations go through tools.
+- **No side-effect declaration**: Agent can't know which tools are safe to call speculatively.
+
+## Operational Concerns
+
+- **Monitoring**: Log all tool calls with agent identity, user context, input hash, latency, status.
+- **Health check**: Expose a health endpoint or resource for the agent to verify connectivity.
+- **Graceful shutdown**: Return "service unavailable" during deploys; agent should retry or fall back.
+- **Schema evolution**: Add fields freely; remove fields only with deprecation notice and version bump.