@cubis/foundry 0.3.30 → 0.3.32

package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/copilot-instructions.md

@@ -0,0 +1,137 @@
+# .github/copilot-instructions.md - Cubis Foundry Copilot Protocol
+
+This file defines mandatory behavior for GitHub Copilot projects installed via `cbx workflows`.
+
+## 1) Platform Paths
+
+- Workflows: `.github/copilot/workflows`
+- Agents: `.github/agents`
+- Skills: `.github/skills`
+- Prompt files: `.github/prompts`
+- Rules file (project): `.github/copilot-instructions.md`
+
+## Startup Transparency (Required)
+
+Before executing workflows, agents, or code edits, publish a short `Decision Log` that is visible to the user:
+
+1. Rule file(s) read at startup (at minimum `.github/copilot-instructions.md`, plus any additional rule files loaded).
+2. Workflow decision (`/workflow` or direct mode) and why it was chosen.
+3. Agent routing decision (`@agent` or direct mode) and why it was chosen.
+4. Skill loading decision (skill names loaded) and why they were chosen.
+
+If routing changes during the task, publish a `Decision Update` before continuing.
+Keep this user-visible summary concise and factual; do not expose private chain-of-thought.
+
+## 2) Workflow-First Contract
+
+1. If the user explicitly requests a slash command, run that workflow first.
+2. Otherwise choose the best workflow by intent from `.github/copilot/workflows` and reuse `.github/prompts/workflow-*.prompt.md` when available.
+3. For cross-domain tasks, use `/orchestrate` and `@orchestrator`.
+4. Keep one primary workflow; use others only as supporting references.
+
+## 3) Request Classifier
+
+1. Question/explanation requests: answer directly.
+2. Survey/intel requests: inspect and summarize before editing.
+3. Simple code changes: minimal edits with focused verification.
+4. Complex code/design changes: plan first, then implement and verify.
+
+## 3A) Workflow Pattern Map (Copilot)
+
+Map intent to one primary workflow first:
+
+- Explain codebase -> `/plan`
+- Fix bug -> `/debug`
+- Write test -> `/test` or `/qa`
+- Prototype from screenshot -> `/create` + `@frontend-specialist`
+- Iterate UI updates -> `/create` with verification loop
+- Refactor safely -> `/refactor` (or `@code-archaeologist` for targeted legacy areas)
+- Local code review -> `/review`
+- Documentation update -> `/create` + `@documentation-writer`
+
+## 4) Agent Routing Policy
+
+Use the best specialist first:
+
+- Backend/API/database: `@backend-specialist`, `@database-architect`
+- Frontend/UI: `@frontend-specialist`
+- Mobile: `@mobile-developer`
+- Security: `@security-auditor`, `@penetration-tester`
+- DevOps/release: `@devops-engineer`
+- Testing/QA: `@test-engineer`, `@qa-automation-engineer`
+- Debugging/performance: `@debugger`, `@performance-optimizer`
+- Cross-domain orchestration: `@orchestrator`
+
+## 5) Copilot Schema Compatibility
+
+When authoring custom Copilot assets, keep frontmatter schema compatible:
+
+1. Skill files in `.github/skills/<id>/SKILL.md` must use supported top-level keys only.
+2. Agent files in `.github/agents/*.md` must use supported top-level keys only.
+3. If unsupported keys are detected, reinstall with overwrite to auto-normalize.
+
+## 6) Skill Loading Policy
+
+### Smart Skill Selection (TIER 0)
+
+Before starting ANY task, the agent MUST:
+
+1.  **Analyze** the user's request against the keywords in `.github/skills/skills_index.json`.
+2.  **Select** the most relevant skill(s) if a strong match is found.
+3.  **Load** the selected skill's `SKILL.md` using `view_file` **BEFORE** proceeding.
+4.  **Announce** the selection: "I am loading the `[Skill Name]` skill to handle your request."
+
+### General Loading Rules
+
+1.  Load only skills needed for the active request.
+2.  Prefer progressive disclosure: start from `SKILL.md`, then specific sections.
+3.  Keep context lean; avoid loading unrelated skill documents.
+4.  If a mapped skill is missing, continue with best fallback and state it.
+
+## 7) Socratic Gate (Before Complex Work)
+
+Before multi-file or architecture-impacting changes, ask targeted questions when requirements are unclear:
+
+1. Goal and success criteria
+2. Constraints and compatibility requirements
+3. Validation expectations (tests, lint, release checks)
+
+## 8) Quality and Safety Gates
+
+1. Do not run destructive actions without explicit user confirmation.
+2. Keep diffs small and reversible when possible.
+3. Verify behavior with focused checks before finalizing.
+4. State what was not validated.
+
+## 9) CBX Maintenance Commands
+
+Use these commands to keep this setup healthy:
+
+- Install/update bundle:
+  `cbx workflows install --platform copilot --bundle agent-environment-setup --scope global --overwrite`
+- Rebuild managed routing block:
+  `cbx workflows sync-rules --platform copilot --scope project`
+- Diagnose setup issues:
+  `cbx workflows doctor copilot --scope project`
+
+## 10) Managed Section Contract
+
+1. Preserve all user content outside managed markers.
+2. Do not manually edit content between managed markers.
+3. `cbx workflows sync-rules` is the source of truth for the managed block.
+
+<!-- cbx:workflows:auto:start platform=copilot version=1 -->
+
+## CBX Workflow Routing (auto-managed)
+
+Use the following workflows proactively when task intent matches:
+
+- No installed workflows found yet.
+
+Selection policy:
+
+1. Match explicit slash command first.
+2. Else match user intent to workflow description and triggers.
+3. Prefer one primary workflow; reference others only when needed.
+
+<!-- cbx:workflows:auto:end -->

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/architecture/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: architecture
+description: "Compatibility alias skill. Deprecated: use architecture-designer."
+metadata:
+  deprecated: true
+  replaced_by: architecture-designer
+  removal_target: v0.6.0
+---
+
+# Architecture
+
+## Compatibility Alias
+
+This skill is deprecated and kept for backward compatibility.
+
+Use `architecture-designer` as the canonical skill.
+
+## Migration
+
+1. Replace direct references to `architecture` with `architecture-designer`.
+2. Apply the full workflow from `architecture-designer` for new work.

package/workflows/workflows/agent-environment-setup/platforms/copilot/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/copilot/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