@cubis/foundry 0.3.30 → 0.3.32

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/ask-questions-if-underspecified/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: ask-questions-if-underspecified
+description: Clarify requirements before implementing. Use when serious doubts arise.
+---
+
+# Ask Questions If Underspecified
+
+## When to Use
+
+Use this skill when a request has multiple plausible interpretations or key details (objective, scope, constraints, environment, or safety) are unclear.
+
+## When NOT to Use
+
+Do not use this skill when the request is already clear, or when a quick, low-risk discovery read can answer the missing details.
+
+## Goal
+
+Ask the minimum set of clarifying questions needed to avoid wrong work; do not start implementing until the must-have questions are answered (or the user explicitly approves proceeding with stated assumptions).
+
+## Workflow
+
+### 1) Decide whether the request is underspecified
+
+Treat a request as underspecified if after exploring how to perform the work, some or all of the following are not clear:
+- Define the objective (what should change vs stay the same)
+- Define "done" (acceptance criteria, examples, edge cases)
+- Define scope (which files/components/users are in/out)
+- Define constraints (compatibility, performance, style, deps, time)
+- Identify environment (language/runtime versions, OS, build/test runner)
+- Clarify safety/reversibility (data migration, rollout/rollback, risk)
+
+If multiple plausible interpretations exist, assume it is underspecified.
+
+### 2) Ask must-have questions first (keep it small)
+
+Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.
+
+Make questions easy to answer:
+- Optimize for scannability (short, numbered questions; avoid paragraphs)
+- Offer multiple-choice options when possible
+- Suggest reasonable defaults when appropriate (mark them clearly as the default/recommended choice; bold the recommended choice in the list, or if you present options in a code block, put a bold "Recommended" line immediately above the block and also tag defaults inside the block)
+- Include a fast-path response (e.g., reply `defaults` to accept all recommended/default choices)
+- Include a low-friction "not sure" option when helpful (e.g., "Not sure - use default")
+- Separate "Need to know" from "Nice to know" if that reduces friction
+- Structure options so the user can respond with compact decisions (e.g., `1b 2a 3c`); restate the chosen options in plain language to confirm
+
+### 3) Pause before acting
+
+Until must-have answers arrive:
+- Do not run commands, edit files, or produce a detailed plan that depends on unknowns
+- Do perform a clearly labeled, low-risk discovery step only if it does not commit you to a direction (e.g., inspect repo structure, read relevant config files)
+
+If the user explicitly asks you to proceed without answers:
+- State your assumptions as a short numbered list
+- Ask for confirmation; proceed only after they confirm or correct them
+
+### 4) Confirm interpretation, then proceed
+
+Once you have answers, restate the requirements in 1-3 sentences (including key constraints and what success looks like), then start work.
+
+## Question templates
+
+- "Before I start, I need: (1) ..., (2) ..., (3) .... If you don't care about (2), I will assume ...."
+- "Which of these should it be? A) ... B) ... C) ... (pick one)"
+- "What would you consider 'done'? For example: ..."
+- "Any constraints I must follow (versions, performance, style, deps)? If none, I will target the existing project defaults."
+- Use numbered questions with lettered options and a clear reply format
+
+```text
+1) Scope?
+a) Minimal change (default)
+b) Refactor while touching the area
+c) Not sure - use default
+2) Compatibility target?
+a) Current project defaults (default)
+b) Also support older versions: <specify>
+c) Not sure - use default
+
+Reply with: defaults (or 1a 2a)
+```
+
+## Anti-patterns
+
+- Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
+- Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/atlassian-mcp/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: atlassian-mcp
+description: Use when querying Jira issues, searching Confluence pages, creating tickets, updating documentation, or integrating Atlassian tools via MCP protocol.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: platform
+  triggers: Jira, Confluence, Atlassian, MCP, tickets, issues, wiki, JQL, CQL, sprint, backlog, project management
+  role: expert
+  scope: implementation
+  output-format: code
+  related-skills: mcp-developer, api-designer, security-reviewer
+---
+
+# Atlassian MCP Expert
+
+Senior integration specialist with deep expertise in connecting Jira, Confluence, and other Atlassian tools to AI systems via Model Context Protocol (MCP).
+
+## Role Definition
+
+You are an expert in Atlassian MCP integration with mastery of both official and open-source MCP servers, JQL/CQL query languages, OAuth 2.0 authentication, and production deployment patterns. You build robust workflows that automate issue triage, documentation sync, sprint planning, and cross-tool integration while respecting permissions and maintaining security.
+
+## When to Use This Skill
+
+- Querying Jira issues with JQL filters
+- Searching or creating Confluence pages
+- Automating sprint workflows and backlog management
+- Setting up MCP server authentication (OAuth/API tokens)
+- Syncing meeting notes to Jira tickets
+- Generating documentation from issue data
+- Debugging Atlassian API integration issues
+- Choosing between official vs open-source MCP servers
+
+## Core Workflow
+
+1. **Select server** - Choose official cloud, open-source, or self-hosted MCP server
+2. **Authenticate** - Configure OAuth 2.1, API tokens, or PAT credentials
+3. **Design queries** - Write JQL for Jira, CQL for Confluence, test filters
+4. **Implement workflow** - Build tool calls, handle pagination, error recovery
+5. **Deploy** - Configure IDE integration, test permissions, monitor rate limits
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Server Setup | `references/mcp-server-setup.md` | Installation, choosing servers, configuration |
+| Jira Operations | `references/jira-queries.md` | JQL syntax, issue CRUD, sprints, boards |
+| Confluence Ops | `references/confluence-operations.md` | CQL search, page creation, spaces, comments |
+| Authentication | `references/authentication-patterns.md` | OAuth 2.0, API tokens, permission scopes |
+| Common Workflows | `references/common-workflows.md` | Issue triage, doc sync, sprint automation |
+
+## Constraints
+
+### MUST DO
+- Respect user permissions and workspace access controls
+- Validate JQL/CQL queries before execution
+- Handle rate limits with exponential backoff
+- Use pagination for large result sets (50-100 items per page)
+- Implement error recovery for network failures
+- Log API calls for debugging and audit trails
+- Test with read-only operations first
+- Document required permission scopes
+
+### MUST NOT DO
+- Hardcode API tokens or OAuth secrets in code
+- Ignore rate limit headers from Atlassian APIs
+- Create issues without validating required fields
+- Skip input sanitization on user-provided query strings
+- Deploy without testing permission boundaries
+- Update production data without confirmation prompts
+- Mix different authentication methods in same session
+- Expose sensitive issue data in logs or error messages
+
+## Output Templates
+
+When implementing Atlassian MCP features, provide:
+1. MCP server configuration (JSON/environment vars)
+2. Query examples (JQL/CQL with explanations)
+3. Tool call implementation with error handling
+4. Authentication setup instructions
+5. Brief explanation of permission requirements
+
+## Knowledge Reference
+
+Atlassian MCP Server (official), mcp-atlassian (sooperset), atlassian-mcp (xuanxt), JQL (Jira Query Language), CQL (Confluence Query Language), OAuth 2.1, API tokens, Personal Access Tokens (PAT), Model Context Protocol, JSON-RPC 2.0, rate limiting, pagination, permission scopes, Jira REST API, Confluence REST API

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/atlassian-mcp/references/authentication-patterns.md

@@ -0,0 +1,520 @@
+# Authentication Patterns
+
+---
+
+## Authentication Methods Overview
+
+| Method | Platform | Use Case | Security Level |
+|--------|----------|----------|----------------|
+| OAuth 2.1 | Cloud | User-facing apps, integrations | Highest |
+| API Token | Cloud | Personal automation, scripts | Medium |
+| PAT | Server/DC | Server integrations | Medium |
+| Basic Auth | Legacy | Deprecated, avoid | Low |
+
+## OAuth 2.1 (Atlassian Cloud)
+
+### Authorization Code Flow
+
+For applications that act on behalf of users.
+
+**Step 1: Register Your App**
+
+1. Go to [developer.atlassian.com](https://developer.atlassian.com/console/myapps/)
+2. Create new app
+3. Configure OAuth 2.0 (3LO)
+4. Add callback URL
+5. Request necessary scopes
+
+**Step 2: Authorization Request**
+
+```typescript
+const authUrl = new URL('https://auth.atlassian.com/authorize');
+authUrl.searchParams.set('audience', 'api.atlassian.com');
+authUrl.searchParams.set('client_id', CLIENT_ID);
+authUrl.searchParams.set('scope', 'read:jira-work write:jira-work read:confluence-content.all write:confluence-content');
+authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
+authUrl.searchParams.set('state', generateState());
+authUrl.searchParams.set('response_type', 'code');
+authUrl.searchParams.set('prompt', 'consent');
+
+// Redirect user to authUrl.toString()
+```
+
+**Step 3: Exchange Code for Token**
+
+```typescript
+async function exchangeCodeForToken(code: string): Promise<TokenResponse> {
+  const response = await fetch('https://auth.atlassian.com/oauth/token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      grant_type: 'authorization_code',
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      code,
+      redirect_uri: REDIRECT_URI,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Token exchange failed: ${response.statusText}`);
+  }
+
+  return response.json();
+}
+
+interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  scope: string;
+  token_type: 'Bearer';
+}
+```
+
+**Step 4: Refresh Token**
+
+```typescript
+async function refreshAccessToken(refreshToken: string): Promise<TokenResponse> {
+  const response = await fetch('https://auth.atlassian.com/oauth/token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      grant_type: 'refresh_token',
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      refresh_token: refreshToken,
+    }),
+  });
+
+  return response.json();
+}
+```
+
+**Step 5: Get Accessible Resources**
+
+```typescript
+async function getAccessibleResources(accessToken: string): Promise<Resource[]> {
+  const response = await fetch(
+    'https://api.atlassian.com/oauth/token/accessible-resources',
+    {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json',
+      },
+    }
+  );
+
+  return response.json();
+}
+
+interface Resource {
+  id: string;        // Cloud ID
+  name: string;      // Site name
+  url: string;       // https://your-site.atlassian.net
+  scopes: string[];
+  avatarUrl: string;
+}
+```
+
+### OAuth Scopes Reference
+
+**Jira Scopes:**
+
+| Scope | Description |
+|-------|-------------|
+| `read:jira-work` | Read issues, projects, boards |
+| `write:jira-work` | Create/update issues |
+| `manage:jira-project` | Manage project settings |
+| `manage:jira-configuration` | Manage global settings |
+| `read:jira-user` | Read user profiles |
+| `manage:jira-data-provider` | Data provider integrations |
+
+**Confluence Scopes:**
+
+| Scope | Description |
+|-------|-------------|
+| `read:confluence-content.all` | Read all content |
+| `write:confluence-content` | Create/update content |
+| `read:confluence-content.summary` | Read content summaries |
+| `read:confluence-space.summary` | Read space summaries |
+| `write:confluence-space` | Create/manage spaces |
+| `read:confluence-user` | Read user profiles |
+
+**Granular Scopes (v2):**
+
+```
+read:issue-details:jira
+write:issue:jira
+read:sprint:jira-software
+write:sprint:jira-software
+read:page:confluence
+write:page:confluence
+read:comment:confluence
+write:comment:confluence
+```
+
+## API Tokens (Atlassian Cloud)
+
+### Creating API Token
+
+1. Go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Click "Create API token"
+3. Give it a descriptive label
+4. Copy token immediately (shown only once)
+
+### Using API Token
+
+```typescript
+// Basic authentication with API token
+const credentials = Buffer.from(`${email}:${apiToken}`).toString('base64');
+
+const response = await fetch('https://your-site.atlassian.net/rest/api/3/myself', {
+  headers: {
+    Authorization: `Basic ${credentials}`,
+    Accept: 'application/json',
+  },
+});
+
+// For MCP server configuration
+const config = {
+  JIRA_URL: 'https://your-site.atlassian.net',
+  JIRA_USERNAME: 'your-email@company.com',
+  JIRA_API_TOKEN: 'your-api-token',
+};
+```
+
+### Token Security Best Practices
+
+```typescript
+// Store tokens securely
+import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
+import { SecretsManager } from '@aws-sdk/client-secrets-manager';
+
+// Option 1: Environment variables (development only)
+const token = process.env.ATLASSIAN_API_TOKEN;
+
+// Option 2: GCP Secret Manager
+async function getTokenFromGCP(secretName: string): Promise<string> {
+  const client = new SecretManagerServiceClient();
+  const [version] = await client.accessSecretVersion({
+    name: `projects/my-project/secrets/${secretName}/versions/latest`,
+  });
+  return version.payload?.data?.toString() || '';
+}
+
+// Option 3: AWS Secrets Manager
+async function getTokenFromAWS(secretName: string): Promise<string> {
+  const client = new SecretsManager({ region: 'us-east-1' });
+  const response = await client.getSecretValue({ SecretId: secretName });
+  return response.SecretString || '';
+}
+
+// Option 4: HashiCorp Vault
+async function getTokenFromVault(path: string): Promise<string> {
+  const response = await fetch(`${VAULT_ADDR}/v1/${path}`, {
+    headers: { 'X-Vault-Token': VAULT_TOKEN },
+  });
+  const data = await response.json();
+  return data.data.data.token;
+}
+```
+
+## Personal Access Tokens (Server/Data Center)
+
+### Creating PAT
+
+**Jira Server/DC:**
+1. Profile > Personal Access Tokens
+2. Create token
+3. Set expiration date
+4. Select permissions
+
+**Confluence Server/DC:**
+1. Profile > Settings > Personal Access Tokens
+2. Create token
+3. Configure permissions
+
+### Using PAT
+
+```typescript
+// Bearer token authentication
+const response = await fetch('https://jira.internal.company.com/rest/api/2/myself', {
+  headers: {
+    Authorization: `Bearer ${personalAccessToken}`,
+    Accept: 'application/json',
+  },
+});
+
+// MCP server configuration
+const config = {
+  JIRA_URL: 'https://jira.internal.company.com',
+  JIRA_PERSONAL_TOKEN: 'your-personal-access-token',
+};
+```
+
+### PAT Permissions
+
+| Permission | Jira | Confluence |
+|------------|------|------------|
+| Read | Browse projects, view issues | View pages |
+| Write | Create/edit issues | Create/edit pages |
+| Admin | Project administration | Space administration |
+
+## Token Management
+
+### Token Lifecycle Manager
+
+```typescript
+interface TokenInfo {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt: Date;
+  scopes: string[];
+}
+
+class TokenManager {
+  private tokenInfo: TokenInfo | null = null;
+  private refreshThreshold = 5 * 60 * 1000; // 5 minutes
+
+  async getValidToken(): Promise<string> {
+    if (!this.tokenInfo) {
+      throw new Error('Not authenticated');
+    }
+
+    // Check if token needs refresh
+    const timeUntilExpiry = this.tokenInfo.expiresAt.getTime() - Date.now();
+
+    if (timeUntilExpiry < this.refreshThreshold) {
+      await this.refreshToken();
+    }
+
+    return this.tokenInfo.accessToken;
+  }
+
+  private async refreshToken(): Promise<void> {
+    if (!this.tokenInfo?.refreshToken) {
+      throw new Error('No refresh token available');
+    }
+
+    const response = await refreshAccessToken(this.tokenInfo.refreshToken);
+
+    this.tokenInfo = {
+      accessToken: response.access_token,
+      refreshToken: response.refresh_token || this.tokenInfo.refreshToken,
+      expiresAt: new Date(Date.now() + response.expires_in * 1000),
+      scopes: response.scope.split(' '),
+    };
+  }
+
+  isAuthenticated(): boolean {
+    return this.tokenInfo !== null && this.tokenInfo.expiresAt > new Date();
+  }
+
+  getScopes(): string[] {
+    return this.tokenInfo?.scopes || [];
+  }
+
+  hasScope(scope: string): boolean {
+    return this.getScopes().includes(scope);
+  }
+}
+```
+
+### Token Rotation Strategy
+
+```typescript
+class TokenRotationManager {
+  private rotationInterval = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+  async checkAndRotate(tokenCreatedAt: Date): Promise<boolean> {
+    const age = Date.now() - tokenCreatedAt.getTime();
+
+    if (age > this.rotationInterval) {
+      console.warn('API token is due for rotation');
+      return true;
+    }
+
+    return false;
+  }
+
+  async sendRotationReminder(email: string, tokenLabel: string): Promise<void> {
+    // Integrate with your notification system
+    await sendEmail({
+      to: email,
+      subject: 'Atlassian API Token Rotation Reminder',
+      body: `Your API token "${tokenLabel}" is due for rotation.
+             Please create a new token and update your integrations.`,
+    });
+  }
+}
+```
+
+## Permission Verification
+
+### Check Current Permissions
+
+```typescript
+async function verifyPermissions(
+  client: MCPClient,
+  requiredOperations: string[]
+): Promise<PermissionReport> {
+  const report: PermissionReport = {
+    hasAllPermissions: true,
+    details: [],
+  };
+
+  for (const operation of requiredOperations) {
+    try {
+      switch (operation) {
+        case 'read:jira':
+          await client.callTool({
+            name: 'jira_get_issue',
+            arguments: { issue_key: 'TEST-1' },
+          });
+          break;
+        case 'write:jira':
+          // Create and immediately delete a test issue
+          const created = await client.callTool({
+            name: 'jira_create_issue',
+            arguments: {
+              project_key: 'TEST',
+              issue_type: 'Task',
+              summary: '[Permission Test] Delete me',
+            },
+          });
+          // Clean up
+          await client.callTool({
+            name: 'jira_delete_issue',
+            arguments: { issue_key: JSON.parse(created.content[0].text).key },
+          });
+          break;
+        case 'read:confluence':
+          await client.callTool({
+            name: 'confluence_search',
+            arguments: { cql: 'type = page', limit: 1 },
+          });
+          break;
+      }
+
+      report.details.push({ operation, status: 'granted' });
+    } catch (error: any) {
+      report.hasAllPermissions = false;
+      report.details.push({
+        operation,
+        status: 'denied',
+        error: error.message,
+      });
+    }
+  }
+
+  return report;
+}
+```
+
+## Security Checklist
+
+### Do:
+- Use OAuth 2.1 for user-facing applications
+- Store secrets in dedicated secrets management systems
+- Implement token rotation policies
+- Use minimal required scopes
+- Log authentication events (without secrets)
+- Implement rate limiting at application level
+- Validate tokens before use
+
+### Don't:
+- Hardcode tokens in source code
+- Log tokens or secrets
+- Share tokens between environments
+- Use Basic Auth (deprecated)
+- Request more scopes than needed
+- Store tokens in browser localStorage
+- Commit `.env` files with real credentials
+
+### Environment Configuration Template
+
+```bash
+# .env.example (commit this)
+ATLASSIAN_SITE_URL=https://your-site.atlassian.net
+ATLASSIAN_AUTH_TYPE=oauth  # or 'api_token' or 'pat'
+
+# OAuth settings (if using OAuth)
+ATLASSIAN_CLIENT_ID=
+ATLASSIAN_CLIENT_SECRET=
+
+# API Token settings (if using API token)
+ATLASSIAN_USERNAME=
+ATLASSIAN_API_TOKEN=
+
+# PAT settings (if using Server/DC)
+ATLASSIAN_PERSONAL_TOKEN=
+```
+
+```bash
+# .gitignore
+.env
+.env.local
+.env.*.local
+credentials.json
+**/secrets/**
+```
+
+## Troubleshooting
+
+### Common Authentication Errors
+
+**401 Unauthorized:**
+- Invalid or expired token
+- Wrong authentication method
+- Missing Authorization header
+
+**403 Forbidden:**
+- Token valid but lacks required scope
+- Resource-level permission denied
+- IP allowlist blocking request
+
+**Token refresh fails:**
+- Refresh token expired (after 90 days of inactivity)
+- Client secret changed
+- App permissions revoked
+
+### Debug Authentication
+
+```typescript
+async function debugAuth(token: string): Promise<void> {
+  // Check token validity
+  const meResponse = await fetch(
+    'https://api.atlassian.com/me',
+    { headers: { Authorization: `Bearer ${token}` } }
+  );
+
+  console.log('Token status:', meResponse.status);
+
+  if (meResponse.ok) {
+    const me = await meResponse.json();
+    console.log('Authenticated as:', me.email);
+  }
+
+  // Check accessible resources
+  const resourcesResponse = await fetch(
+    'https://api.atlassian.com/oauth/token/accessible-resources',
+    { headers: { Authorization: `Bearer ${token}` } }
+  );
+
+  if (resourcesResponse.ok) {
+    const resources = await resourcesResponse.json();
+    console.log('Accessible sites:', resources.map((r: any) => r.name));
+  }
+}
+```
+
+## Related References
+
+- `mcp-server-setup.md` - Server configuration with credentials
+- `jira-queries.md` - Operations that require authentication
+- `confluence-operations.md` - Content operations with auth