jumpstart-mode 1.1.13 → 1.1.14

package/.github/skills/company-research/examples/sample.md

@@ -0,0 +1,98 @@
+# Company Research Example
+
+Illustrative example for a Jump Start prep brief.
+
+```markdown
+# Buckeye Regional Health Plan Research Brief
+
+## 1. Brief Purpose
+- **Primary Use:** Jump Start prep brief
+- **Company:** Buckeye Regional Health Plan
+- **Industry / Subsector:** Healthcare payer / Medicaid managed care
+- **Geography:** Midwest United States
+- **Prepared For:** Facilitator, seller, AI Innovation Pod lead
+- **Date:** April 2026
+
+## 2. Executive Summary
+- **Why this account matters now:**
+  - Margin pressure and member service expectations are rising at the same time.
+  - The company appears to be modernizing customer operations and digital channels.
+  - The combination of document-heavy workflows and regulated operations suggests multiple bounded AI opportunities.
+- **Working point of view:** The strongest near-term fit is likely operational AI that improves service, document handling, or knowledge access without crossing into high-risk autonomous decisioning.
+- **Recommended next move:** Jump Start with strong readiness and governance framing, then route to Ignition or Turbo depending on data and sponsor clarity.
+
+## 3. Company Snapshot
+- **Business model / footprint:** Regional payer serving Medicaid and marketplace populations through a mix of member service, care management, claims, and provider operations.
+- **Recent strategic signals:** Cost containment, member experience improvement, provider friction reduction, and pressure to do more with constrained operations teams.
+- **AI / digital signals:** Public references to digital experience, member self-service, analytics modernization, and hiring signals that suggest ongoing data and platform investment.
+
+## 4. Why Now
+- **Confirmed signals:**
+  - Public messaging emphasizes digital member experience and operational efficiency.
+  - Regulated payer operations remain document-heavy and SLA-sensitive.
+- **Hypotheses:**
+  - Leadership may be looking for AI that reduces manual effort without increasing compliance exposure.
+  - Knowledge access and document workflows may be more tractable than member-facing generative AI at first.
+- **Unknowns:**
+  - Whether there is an active executive AI sponsor.
+  - Whether the team has usable non-production data and environment access.
+
+## 5. Executive And Stakeholder Map
+| Role | Likely Agenda | Likely Concerns | Confidence |
+| --- | --- | --- | --- |
+| Executive sponsor | Cost, experience, visible progress | Risk, ROI, governance | Medium |
+| Business owner | Faster service operations | Adoption, workflow fit | Medium |
+| Technical owner | Secure delivery in existing platform | Integration effort, approvals | Medium |
+| Risk / compliance | Explainability and auditability | PHI, bias, vendor risk | High |
+| Likely skeptic | Avoid AI theater or disruption | Readiness, change fatigue | Medium |
+
+## 6. Business Pressure And Pain Hypotheses
+- **Likely pain points:**
+  - Manual work across service, claims support, authorization support, or policy interpretation.
+  - Information trapped across portals, documents, and operational teams.
+  - Slow response times when staff need consistent answers from policy-heavy content.
+- **What may be driving urgency:**
+  - Cost pressure, staffing constraints, and demand for better member and provider experience.
+- **Potential business outcomes they may care about:**
+  - Lower average handle time, reduced manual processing, improved consistency, faster onboarding of staff, better SLA performance.
+
+## 7. AI Opportunity Hypotheses
+| Hypothesis | Why it fits | Likely data / system needs | Delivery risk |
+| --- | --- | --- | --- |
+| Internal policy and procedure copilot | High document density and knowledge friction | Policy docs, search index, access controls | Medium |
+| Document intake and summarization workflow | Repetitive back-office work with bounded input types | Document repositories, workflow metadata | Medium |
+| Service agent assist | Clear operational value if guardrails are strong | Knowledge sources, CRM / case data | High |
+
+## 8. Readiness And Qualification View
+- **Strategic clarity:** Likely moderate. Public pressure is visible, but the exact AI priority is unknown.
+- **Executive sponsorship:** Unknown. Must validate quickly.
+- **Data maturity clues:** Some modernization signals exist, but data accessibility is unclear.
+- **Technical environment clues:** Appears digitally active, but delivery ownership and approval paths are unknown.
+- **Governance / regulatory constraints:** High. Any solution must be privacy-aware, auditable, and explainable.
+- **Overall qualification view:** Mixed but promising if a sponsor and a bounded use case exist.
+
+## 9. Jump Start Or Pod Implications
+- **Best-fit starting motion:** Jump Start
+- **Why:** The likely opportunity is strong, but stakeholder alignment, bounded use case selection, and governance framing need to happen before a build motion is safe.
+- **Workshop implications:**
+  - Invite operations, digital, IT/platform, data, and compliance voices.
+  - Emphasize current-state process pain, information access, and governance boundaries.
+  - Surface what is off-limits early, especially PHI exposure and production integration assumptions.
+
+## 10. Recommended Discovery Questions
+- Which operational workflows currently create the most manual effort or delay?
+- Where is information hard to find, inconsistent, or trapped across teams and systems?
+- What AI or automation initiatives are already underway, and how are they performing?
+- Who would own success for a pilot like this on the business side and on the platform side?
+- What governance or compliance constraints would immediately shape what is feasible?
+
+## 11. Assumptions To Validate
+- [ASSUMPTION] There is executive appetite for a bounded AI pilot tied to operational improvement.
+- [ASSUMPTION] Non-production data and a pilot environment can be made available.
+- [ASSUMPTION] Knowledge access or document-heavy workflows are a higher-confidence first move than member-facing generative AI.
+
+## 12. Sources
+- Company site and public leadership messaging
+- Public news and job postings
+- Internal industry playbook and readiness guidance
+```

package/.github/skills/company-research/references/jumpstart-company-research-workflow.md

@@ -0,0 +1,65 @@
+# Jump Start Company Research Workflow
+
+Use this reference when creating a company brief for Jump Start preparation or AI Innovation Pod account planning.
+
+## What Good Looks Like
+
+A good research brief helps the team answer five questions before discovery:
+
+1. Why might this company care right now?
+2. Which executive, business, technical, and risk stakeholders are likely to matter?
+3. Which AI opportunities are plausible and bounded enough to discuss credibly?
+4. Which readiness or qualification risks could derail the motion?
+5. What should the next conversation or workshop focus on?
+
+## Repo Sources To Use
+
+Read the most relevant of these based on the ask:
+
+* `../../../01-sell/engaging-clients-conversation-guide.md`: pre-meeting research mindset and contact prep
+* `../../../02-scope-and-propose/discovery/discovery-questions.md`: discovery questions the brief should feed
+* `../../../02-scope-and-propose/assessments/ai-readiness-assessment-tool.md`: readiness dimensions and blocker framing
+* `../../../01-sell/qualification/qualification-scorecard.md`: qualification language and go/no-go logic
+* `../../../01-sell/qualification/ai-innovation-pod-tier-internal-routing-guide.md`: routing cues for Jump Start, Ignition, Turbo, and Overdrive
+* `../../../05-reference/ai-innovation-pod-tier-matrix.md`: tier positioning and delivery-stage language
+* `../../../03-facilitate/facilitation-guides/facilitation-playbook.md`: pre-workshop preparation expectations and output style
+* relevant industry playbooks in `../../../01-sell/industry-playbooks/`: domain pressures, use cases, objections, and stakeholder concerns
+
+## Minimum Research Sections
+
+At minimum, the brief should cover:
+
+* company snapshot,
+* why now,
+* executive and stakeholder map,
+* business pressure and pain hypotheses,
+* AI opportunity hypotheses,
+* readiness and qualification view,
+* recommended discovery questions,
+* assumptions to validate.
+
+## Confidence Labels
+
+Use these labels consistently:
+
+* `Confirmed signal`
+* `Hypothesis`
+* `Unknown`
+
+That keeps the brief useful even when inputs are incomplete.
+
+## Output Bias
+
+Favor:
+
+* short sections,
+* role-based stakeholder mapping,
+* implications over description,
+* bounded use-case hypotheses,
+* explicit next moves.
+
+Avoid:
+
+* generic company history,
+* stock-performance commentary unless it affects urgency,
+* abstract AI trend summaries with no account implication.

package/.github/skills/company-research/templates/template.md

@@ -0,0 +1,121 @@
+# Jump Start / Account Strategy Company Research Brief Template
+
+Use this template to produce the anchor research brief for Jump Start preparation or account strategy planning.
+
+## Template
+
+```markdown
+# [Company Name] Research Brief
+
+## 1. Brief Purpose
+- **Primary Use:** [Jump Start prep brief, account strategy brief, or hybrid]
+- **Company:** [Name]
+- **Industry / Subsector:** [Industry]
+- **Geography:** [Primary geography]
+- **Prepared For:** [Seller, facilitator, Pod lead, account team]
+- **Date:** [Date]
+
+## 2. Executive Summary
+- **Why this account matters now:** [2-4 bullets]
+- **Working point of view:** [Short paragraph on likely AI / transformation angle]
+- **Recommended next move:** [Jump Start, Ignition, Turbo, Overdrive, no-go, or needs more validation]
+
+## 3. Company Snapshot
+- **Business model / footprint:** [Short summary]
+- **Recent strategic signals:** [Growth, cost pressure, modernization, regulatory pressure, M&A, customer pressure]
+- **AI / digital signals:** [Publicly visible AI, automation, data, cloud, or platform signals]
+
+## 4. Why Now
+- **Confirmed signals:**
+  - [Signal + source implication]
+- **Hypotheses:**
+  - [What the team believes may be true but must validate]
+- **Unknowns:**
+  - [Critical missing information]
+
+## 5. Executive And Stakeholder Map
+| Role | Likely Agenda | Likely Concerns | Confidence |
+| --- | --- | --- | --- |
+| Executive sponsor | [Agenda] | [Concerns] | [High/Med/Low] |
+| Business owner | [Agenda] | [Concerns] | [High/Med/Low] |
+| Technical owner | [Agenda] | [Concerns] | [High/Med/Low] |
+| Risk / compliance | [Agenda] | [Concerns] | [High/Med/Low] |
+| Likely skeptic | [Agenda] | [Concerns] | [High/Med/Low] |
+
+## 6. Business Pressure And Pain Hypotheses
+- **Likely pain points:**
+  - [Pain point]
+- **What may be driving urgency:**
+  - [Urgency driver]
+- **Potential business outcomes they may care about:**
+  - [Outcome]
+
+## 7. AI Opportunity Hypotheses
+| Hypothesis | Why it fits | Likely data / system needs | Delivery risk |
+| --- | --- | --- | --- |
+| [Use case 1] | [Reason] | [Needs] | [Low/Med/High] |
+| [Use case 2] | [Reason] | [Needs] | [Low/Med/High] |
+| [Use case 3] | [Reason] | [Needs] | [Low/Med/High] |
+
+## 8. Readiness And Qualification View
+- **Strategic clarity:** [Signal]
+- **Executive sponsorship:** [Signal]
+- **Data maturity clues:** [Signal]
+- **Technical environment clues:** [Signal]
+- **Governance / regulatory constraints:** [Signal]
+- **Overall qualification view:** [Strong fit, mixed fit, weak fit]
+
+## 9. Jump Start Or Pod Implications
+- **Best-fit starting motion:** [Jump Start, Ignition, Turbo, Overdrive]
+- **Why:** [Short rationale]
+- **Workshop implications:**
+  - [Participants to invite]
+  - [Topics to emphasize]
+  - [Risks to surface early]
+
+## 10. Recommended Discovery Questions
+- [Question 1]
+- [Question 2]
+- [Question 3]
+- [Question 4]
+- [Question 5]
+
+## 11. Assumptions To Validate
+- [ASSUMPTION] [What needs confirmation]
+- [ASSUMPTION] [What needs confirmation]
+
+## 12. Sources
+- [Source 1]
+- [Source 2]
+- [Source 3]
+
+### Executive Quotes on Strategic Vision
+- **CEO:** [Quote + source + date]
+- **COO:** [Quote + source + date]
+- **VP of Product:** [Quote + source + date]
+- **Group PM:** [Quote + source + date]
+
+### Detailed Product Insights
+- **Product Strategy Overview:** [Summary]
+- **Recent Launches/Innovations:**
+  1. [Launch 1]
+  2. [Launch 2]
+
+### Transformation Strategies
+- **Digital Transformation:** [Summary]
+- **AI Transformation:** [Summary]
+- **Agile Transformation:** [Summary]
+
+### Organizational Impact of Product Management
+- **Role of PM in Strategic Decisions:** [Summary]
+- **Cross-Functional Collaboration:** [Summary]
+- **PM Career Paths:** [Summary]
+
+### Future Roadmap and Challenges
+- **Upcoming Initiatives:** [Summary]
+- **Anticipated Challenges:** [Summary]
+
+### Product-Led Growth Insights
+- **PLG Strategies:** [Summary]
+- **Data-Driven Product Decisions:** [Summary]
+```

package/.github/skills/copilot-sdk/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: copilot-sdk
+description: >
+  Build or modify applications that embed GitHub Copilot SDK for agentic workflows.
+  Use this whenever the user wants to add Copilot-powered chat, streaming responses,
+  custom tools, MCP server access, custom agents, session persistence, BYOK auth,
+  or external Copilot CLI server connectivity in TypeScript, Python, Go, .NET, or
+  Java, even if they ask in product terms like "embed Copilot", "build an agent
+  into our app", or "wire Copilot into this service".
+license: MIT
+compatibility: >
+  Cross-platform. Requires a supported language runtime. Node.js, Python, and .NET
+  bundle the Copilot CLI through the SDK; Go commonly requires the CLI to be installed
+  separately; Java support exists in the public preview SDK but is not templated here.
+metadata:
+  version: "1.1"
+argument-hint: >
+  Optional: language, framework, target app, auth mode, and desired features such as
+  streaming, tools, MCP, persistence, BYOK, or external CLI server mode
+---
+
+# GitHub Copilot SDK
+
+Use this skill when the user needs working integration code or concrete implementation guidance for embedding GitHub Copilot SDK, not just a generic explanation of AI agents.
+
+## Trigger Cues
+
+Use this skill for prompts like:
+- "add Copilot chat to our app"
+- "embed a Copilot agent in this service"
+- "wire GitHub Copilot SDK into our TypeScript backend"
+- "create a Python app that uses Copilot tools and MCP"
+- "persist Copilot conversations between sessions"
+- "connect to an external Copilot CLI server"
+- "restrict which Copilot tools are available"
+- "set up BYOK auth for Copilot SDK"
+
+Do not use this skill for generic prompt-writing help, ordinary GitHub Copilot editor usage, or broad vendor comparisons that do not involve SDK implementation.
+
+## First Response
+
+Lock these inputs before drafting code. If the user already supplied them, do not ask again.
+
+1. Target language and runtime
+2. App shape: CLI, API, background worker, desktop, or web backend
+3. Auth and deployment model: signed-in user, token-based auth, BYOK, or external CLI server
+4. Required features: streaming, tools, MCP, custom agents, persistence, attachments, or observability
+5. Expected output: minimal runnable example, patch to an existing app, or architecture guidance
+
+## Workflow
+
+1. Choose the smallest implementation slice that proves the requested behavior.
+2. Read only the bundled reference files relevant to that slice.
+3. Start from the closest template instead of drafting from scratch.
+4. Add capabilities incrementally: basic session, then streaming, then tools or MCP, then persistence.
+5. Show exactly how to run, configure, and shut down the sample.
+6. Call out preview-status limitations and any security implications of tool access.
+
+## Resource Map
+
+| File | Use when |
+|------|----------|
+| [references/architecture-and-runtime.md](./references/architecture-and-runtime.md) | You need SDK positioning, supported runtimes, auth options, or language-selection guidance |
+| [references/session-patterns.md](./references/session-patterns.md) | You are implementing session lifecycle, streaming, persistence, attachments, or event handling |
+| [references/tools-and-mcp.md](./references/tools-and-mcp.md) | You are adding custom tools, MCP servers, custom agents, or tool restrictions |
+| [references/troubleshooting.md](./references/troubleshooting.md) | The user is blocked on setup, auth, connectivity, cleanup, or runtime failures |
+| [templates/typescript-starter.ts](./templates/typescript-starter.ts) | The user needs a TypeScript starter with streaming and session lifecycle already wired |
+| [templates/python-starter.py](./templates/python-starter.py) | The user needs a Python starter with streaming and session lifecycle already wired |
+| [templates/copilot-sdk-design-template.md](./templates/copilot-sdk-design-template.md) | The user needs a design or implementation plan before code |
+| [examples/copilot-sdk-recipes.md](./examples/copilot-sdk-recipes.md) | You want realistic request patterns, output shapes, and composition examples |
+
+## Design Rules
+
+1. Prefer the smallest runnable example that exercises the requested feature.
+2. Match the idioms of the target language instead of transliterating another language's sample.
+3. Default to streaming for interactive UX, but keep non-streaming examples simpler when the user only needs request-response behavior.
+4. Always show lifecycle cleanup such as `client.stop()` or the equivalent disposal path.
+5. Treat tool access as a security boundary. The SDK exposes broad first-party tool access by default, so tighten with `availableTools` or `excludedTools` when the user needs control.
+6. Mention current product facts when relevant: the SDK is in public preview, Node.js/Python/.NET bundle the CLI, Go often requires separate CLI installation, and BYOK is available.
+7. If the user is choosing a design, separate product facts from recommendations.
+
+## Output Rules
+
+- Return copy-pasteable code, not pseudocode, unless the user explicitly asks for design only.
+- Include the exact install and run commands for the chosen language.
+- Keep setup notes close to the code that depends on them.
+- If the user asks for an existing codebase change, patch the local files instead of dumping a standalone sample.
+- When security, auth, or billing matters, state the relevant assumption explicitly.
+
+## Validation Checklist
+
+Before finishing, confirm that:
+
+1. The sample includes explicit startup and cleanup.
+2. The requested feature surface is present and minimal.
+3. Tool, MCP, or auth choices are intentional rather than defaulted silently.
+4. The run instructions match the chosen runtime.
+5. Preview-status caveats are mentioned where they affect deployment guidance.
+
+## Regression Evals
+
+Starter eval prompts live in [evals/evals.json](./evals/evals.json). Use them when improving or regression-testing this skill.

package/.github/skills/copilot-sdk/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "copilot-sdk",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I have a Node service and I need to add GitHub Copilot SDK so users can chat with an agent from the terminal. Keep it minimal, but I need streaming output, a stable session id per user, and exact install and run commands.",
+      "expected_output": "A minimal TypeScript or Node-oriented implementation that includes streaming, session lifecycle, sessionId handling, and concrete setup commands.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Show me how to build a Python Copilot SDK helper that can connect to GitHub's MCP server and summarize open issues for a repo. I care about the MCP wiring more than the rest of the app.",
+      "expected_output": "A Python-focused answer that centers MCP configuration, keeps the app skeleton small, and mentions credential or connectivity assumptions.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "We want a custom tool in our Copilot-powered app that looks up customer entitlements from an internal API. Please show the SDK pattern and call out how to avoid exposing too many tools by default.",
+      "expected_output": "An answer that defines a narrowly scoped custom tool, wires it into session creation, and explicitly addresses tool restriction or trust-boundary choices.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Our platform team already runs Copilot CLI in server mode on another host. Explain how my app should connect through cliUrl, what that changes, and give me a minimal example in the language you think fits best.",
+      "expected_output": "A concise implementation example that uses cliUrl and clearly explains that the application no longer owns CLI lifecycle management.",
+      "files": []
+    }
+  ]
+}

package/.github/skills/copilot-sdk/examples/copilot-sdk-recipes.md

@@ -0,0 +1,73 @@
+# Copilot SDK Recipes
+
+Use these examples to anchor the response shape before writing code.
+
+## Recipe 1: Internal CLI Assistant In TypeScript
+
+**User ask:**
+"Build a TypeScript CLI assistant for our support engineers. It should stream replies, keep conversation state for the current user, and shut down cleanly."
+
+**How to answer:**
+
+1. Start from [templates/typescript-starter.ts](../templates/typescript-starter.ts).
+2. Keep the first version to session lifecycle plus streaming.
+3. Add a stable `sessionId` strategy and run command.
+
+**What good output includes:**
+
+- Install command for `@github/copilot-sdk` and `tsx`
+- One runnable file
+- Explanation of where user identity maps to `sessionId`
+- Cleanup path in `finally`
+
+## Recipe 2: Python Service With GitHub MCP Access
+
+**User ask:**
+"I need a Python backend endpoint that uses Copilot SDK and can inspect GitHub issues through MCP."
+
+**How to answer:**
+
+1. Start from [templates/python-starter.py](../templates/python-starter.py).
+2. Read [references/tools-and-mcp.md](../references/tools-and-mcp.md).
+3. Add only the MCP server config and one proof prompt.
+
+**What good output includes:**
+
+- MCP configuration block
+- A note about credentials and network reachability
+- One small endpoint or function rather than a whole platform rewrite
+
+## Recipe 3: Safe Custom Tool Integration
+
+**User ask:**
+"Add a custom tool so the agent can look up customer entitlements, but keep the app locked down."
+
+**How to answer:**
+
+1. Use a narrow tool schema with explicit required fields.
+2. Explain why tool descriptions must be concrete.
+3. Add `availableTools` or `excludedTools` guidance so the trust boundary is intentional.
+
+**What good output includes:**
+
+- One custom tool definition
+- Structured return shape
+- Session config showing how the tool is exposed
+- Security note on authorization outside the model
+
+## Recipe 4: External CLI Server Mode
+
+**User ask:**
+"Our platform team already runs a shared Copilot CLI server. Show me how the app should connect to it and what changes operationally."
+
+**How to answer:**
+
+1. Read [references/architecture-and-runtime.md](../references/architecture-and-runtime.md).
+2. Configure `cliUrl` instead of letting the SDK own the CLI lifecycle.
+3. Explain that health checks, restarts, and logging move outside the app process.
+
+**What good output includes:**
+
+- Client construction with `cliUrl`
+- One request path proving connectivity
+- Operational note explaining lifecycle ownership

package/.github/skills/copilot-sdk/references/architecture-and-runtime.md

@@ -0,0 +1,73 @@
+# Architecture And Runtime
+
+Use this reference when the user is deciding whether GitHub Copilot SDK is the right integration path, which runtime to choose, or how authentication and deployment should work.
+
+## Current Product Facts
+
+- The GitHub Copilot SDK is in public preview.
+- Official SDKs currently cover TypeScript, Python, Go, .NET, and Java.
+- Node.js, Python, and .NET bundle the Copilot CLI through the SDK package.
+- Go commonly requires the `copilot` CLI to be installed or otherwise reachable on `PATH`.
+- The SDK talks to the Copilot CLI server over JSON-RPC and can either manage the CLI lifecycle automatically or connect to an external CLI server.
+- Standard usage requires GitHub Copilot access unless the user is configuring BYOK.
+
+## Core Architecture
+
+```text
+Application
+  -> SDK client
+  -> Copilot CLI server
+  -> Model and auth surface
+```
+
+The design implication is simple: treat the CLI as part of the runtime boundary. Startup behavior, environment variables, auth state, logging, and deployment topology all need to account for it.
+
+## When To Use The SDK
+
+Use the SDK when the user needs one or more of these:
+
+- Embedded Copilot-powered chat or agent workflows inside an app or service
+- Built-in planning and tool invocation rather than hand-rolled orchestration
+- Session persistence and resume flows
+- Custom tools that the model can call during reasoning
+- MCP server connectivity for existing tool ecosystems
+- Copilot-managed model access with runtime model selection
+
+Avoid recommending the SDK as the first option when the user only needs a single direct model call with no agent behavior, no tool invocation, and no session lifecycle.
+
+## Runtime Selection Guide
+
+| Runtime | Choose when | Watch for |
+|---------|-------------|-----------|
+| TypeScript | The app is already Node-based, full-stack JS, or needs fast prototyping | Dependency and module-format consistency |
+| Python | The user wants fast experimentation, CLI utilities, or data-heavy workflows | Async lifecycle and environment management |
+| Go | The user needs a compiled service and already operates Go infrastructure | CLI installation and stronger explicit typing across handlers |
+| .NET | The app is already C# or uses Microsoft.Extensions-style infrastructure | Async disposal and package ecosystem choices |
+| Java | The team is JVM-first and wants preview support | Fewer ready-made community examples and changing preview surface |
+
+## Authentication Choices
+
+| Mode | Use when | Notes |
+|------|----------|-------|
+| Signed-in user | Local development or user-driven desktop/CLI usage | Relies on stored Copilot auth state |
+| Token environment variables | The hosting environment manages GitHub tokens centrally | Be explicit about secret handling |
+| BYOK | The user wants to use provider keys instead of GitHub auth | Key-based only; separate governance discussion may be needed |
+| External CLI server | A shared Copilot CLI process is already managed elsewhere | The SDK connects but does not manage that process |
+
+## Design Prompts To Resolve Early
+
+1. Is the SDK running on behalf of a signed-in developer, an app user, or a service principal-like workflow?
+2. Does the app need durable conversations or only stateless requests?
+3. Is tool access acceptable at the CLI default, or must the app narrow it?
+4. Does the app need per-session specialization through system messages or custom agents?
+5. Is the CLI process local to the app instance or shared remotely?
+
+## Minimal Planning Output
+
+If the user asks for design before code, produce:
+
+1. Runtime choice and why
+2. Auth model and secret boundary
+3. Session model: transient or persistent
+4. Tool and MCP boundary
+5. Startup, shutdown, and error-handling plan

package/.github/skills/copilot-sdk/references/session-patterns.md

@@ -0,0 +1,90 @@
+# Session Patterns
+
+Use this reference when the user needs runnable session code, streaming UX, persistence, or lifecycle handling.
+
+## Base Lifecycle Pattern
+
+Every implementation should make these phases explicit:
+
+1. Construct the client
+2. Start or connect the client
+3. Create or resume a session
+4. Register event handlers if streaming or telemetry matters
+5. Send prompts and process outputs
+6. Stop or dispose of the client cleanly
+
+If a sample skips cleanup, fix that before adding features.
+
+## Minimal Session Shape
+
+Use this shape even if the exact syntax changes by language:
+
+```text
+create client
+start client
+create session with model and permission policy
+send prompt
+read response
+stop client
+```
+
+## Streaming Pattern
+
+Use streaming when the user is building an interactive UX.
+
+- Enable `streaming: true`
+- Subscribe to `assistant.message_delta` for incremental text
+- Use `session.idle` as the completion signal for UI cleanup
+- Keep a non-streaming fallback path for logs, tests, or background jobs
+
+## Session Persistence Pattern
+
+Use persistence when the user needs continuity across app restarts or user sessions.
+
+1. Assign a stable `sessionId`
+2. Resume instead of creating a new session when prior context should survive
+3. Offer list and delete flows when the user is building a management UI
+4. Make the retention policy explicit; do not assume infinite history is acceptable
+
+## Attachments Pattern
+
+When the user wants file-aware prompts:
+
+- Attach files explicitly with a path and display name
+- Keep the user prompt focused on what the assistant should do with the file
+- Mention file availability assumptions if the sample spans client and server machines
+
+## System Message And Custom Agent Pattern
+
+Use a system message when the app needs one stable behavior profile for a whole session.
+Use custom agents when the user needs multiple named personas or task modes inside one app.
+
+Prefer custom agents over giant system prompts when the app will expose user-selectable modes.
+
+## Event Handling Reference
+
+Common event types worth wiring into examples:
+
+| Event | Use |
+|------|-----|
+| `assistant.message_delta` | Incremental response rendering |
+| `assistant.message` | Final assembled assistant reply |
+| `tool.execution_start` | Spinner, trace, or audit output |
+| `tool.execution_complete` | Tool result logging |
+| `session.idle` | End-of-turn cleanup or prompt re-enable |
+| `session.error` | Error reporting and fallback behavior |
+
+## Timeouts And Abort
+
+- Use `sendAndWait` timeouts for bounded request-response flows.
+- Use `session.abort()` or the language equivalent for user-cancelable UX.
+- If the user is building a server, define what happens when a request times out but the client process is still alive.
+
+## Sample Response Strategy
+
+When producing code for the user:
+
+1. Show the narrowest session that works.
+2. Add streaming only if requested or clearly beneficial.
+3. Add persistence only when the prompt requires memory across turns.
+4. Keep event handlers close to session creation so the lifecycle is easy to follow.