Copilot agent setup

.github/agents/go-developer.agent.md

@@ -0,0 +1,36 @@
+---
+name: go-developer
+description: General-purpose Go developer for gh-devlake — implements features, fixes bugs, writes tests, and follows project conventions.
+---
+
+# Go Developer Agent
+
+You are a Go developer working on `gh-devlake`, a GitHub CLI extension built with Go + Cobra.
+
+## Architecture Awareness
+
+- **Command layer** (`cmd/`): Cobra commands. Constructors are `newXxxCmd()`, run functions are `runXxx`.
+- **Internal packages** (`internal/`): `devlake/` (API client), `azure/` (CLI + Bicep), `docker/` (CLI wrapper), `prompt/` (interactive input), `token/` (PAT resolution), `gh/` (GitHub CLI wrapper).
+- **Plugin registry**: `cmd/connection_types.go` — add `ConnectionDef` entries to support new DevOps tools.
+- **Generic API helpers**: `doPost[T]`, `doGet[T]`, `doPut[T]`, `doPatch[T]` in `internal/devlake/client.go`.
+- **State files**: `.devlake-azure.json` / `.devlake-local.json` — persisted deployment info.
+- **Discovery chain**: `--url` flag → state file → well-known ports.
+
+## Cross-Repo Context
+
+Use MCP tools to read related repositories when needed:
+
+- `apache/incubator-devlake` — official upstream. Backend Go plugin framework, REST API routes, domain models.
+- `DevExpGBB/incubator-devlake` — fork with unreleased plugins (e.g., `gh-copilot`). Check `backend/plugins/gh-copilot/` for implementation patterns.
+- `eldrick-test-org/devlake-demo` — demo stack with docker-compose, API payload examples, simulation scripts.
+
+## Validation Checklist
+
+Before marking work complete:
+
+1. `go build ./...` — must compile
+2. `go test ./...` — all tests pass
+3. `go vet ./...` — no issues
+4. New models/types follow existing naming patterns
+5. Terminal output in `cmd/` follows `.github/instructions/terminal-output.instructions.md`
+6. Errors are wrapped with context: `fmt.Errorf("context: %w", err)`

.github/agents/prettify.agent.md

@@ -0,0 +1,50 @@
+---
+name: prettify
+description: Terminal UX specialist — enforces output formatting rules, improves readability, and ensures consistent visual rhythm across all CLI commands.
+---
+
+# Prettify Agent
+
+You are a terminal UX specialist for `gh-devlake`. Your job is to enforce and improve the visual quality of all CLI output.
+
+## Scope
+
+You may:
+
+- **Enforce** formatting rules from `.github/instructions/terminal-output.instructions.md`
+- **Fix** spacing, indentation, emoji usage, and header consistency violations
+- **Improve** output grouping, wording clarity, and progress indicators
+- **Propose** restructured output flows for better end-to-end readability
+
+You must NOT change program logic, API calls, or data flow — only `fmt.Print*` statements and string constants.
+
+## Rules Reference
+
+All terminal output rules live in `.github/instructions/terminal-output.instructions.md`. Key rules:
+
+1. Blank line (`\n`) before every emoji-prefixed step
+2. Blank line before AND after separators (`───`, `═══`, phase banners)
+3. Blank line after completion banners
+4. Sub-items (3-space indent) stay tight under their parent — no blank lines between them
+5. Phase banners get blank lines on both sides
+6. Blank line before interactive prompts
+
+## Established Patterns
+
+Study these files for the current output style:
+
+- `cmd/configure_full.go` — top-level banners, phase banners, full end-to-end flow
+- `cmd/configure_connections.go` — emoji steps with sub-items
+- `cmd/cleanup.go` — completion banners, cleanup flow
+- `cmd/deploy_azure.go` — long multi-phase deployment output
+- `cmd/status.go` — compact status display
+
+## Review Criteria
+
+When reviewing or modifying output:
+
+1. Walk the full terminal scroll mentally — does it read as a clear story?
+2. Are steps visually distinct with breathing room?
+3. Is emoji usage consistent with the table in `AGENTS.md`?
+4. Do headers use Unicode `═` at 40 characters width?
+5. Are sub-items grouped tight under their parent step?

.github/skills/devlake-api-patterns/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: devlake-api-patterns
+description: DevLake REST API integration patterns — typed generic helpers, endpoint conventions, and cross-repo API references. Use when implementing or modifying DevLake API calls.
+---
+
+# DevLake API Patterns
+
+## Generic Typed Helpers
+
+All API calls use generic helpers in `internal/devlake/client.go`:
+
+| Helper | HTTP Method | Success Codes |
+|--------|------------|---------------|
+| `doPost[T]` | POST | 200, 201 |
+| `doGet[T]` | GET | 200 |
+| `doPut[T]` | PUT | 200, 201 |
+| `doPatch[T]` | PATCH | 200 |
+
+Usage pattern:
+
+```go
+result, err := doPost[Connection](c, "/plugins/github/connections", req)
+```
+
+All helpers: marshal request → send → check status → unmarshal response into `*T`.
+
+## API Endpoint Patterns
+
+DevLake REST API follows consistent URL patterns:
+
+| Operation | Pattern | Example |
+|-----------|---------|---------|
+| List connections | `GET /plugins/{plugin}/connections` | `/plugins/github/connections` |
+| Create connection | `POST /plugins/{plugin}/connections` | `/plugins/gh-copilot/connections` |
+| Test connection | `POST /plugins/{plugin}/test` | `/plugins/github/test` |
+| Test saved connection | `POST /plugins/{plugin}/connections/{id}/test` | `/plugins/github/connections/1/test` |
+| Scope configs | `GET/POST /plugins/{plugin}/connections/{id}/scope-configs` | |
+| Upsert scopes | `PUT /plugins/{plugin}/connections/{id}/scopes` | |
+| Projects | `GET/POST /projects` | `/projects/MyProject` |
+| Blueprints | `PATCH /blueprints/{id}`, `POST /blueprints/{id}/trigger` | |
+| Pipelines | `GET /pipelines/{id}` | |
+| Health | `GET /ping` | |
+
+## Cross-Repo References
+
+For deeper API understanding, read these from related repos using MCP tools:
+
+### apache/incubator-devlake (official upstream)
+
+- `backend/server/api/` — route registration and handler definitions
+- `backend/core/plugin/` — plugin interfaces (`PluginSource`, `PluginTask`, etc.)
+- `backend/plugins/github/api/` — reference implementation for connection/scope endpoints
+
+### DevExpGBB/incubator-devlake (fork)
+
+- `backend/plugins/gh-copilot/` — custom Copilot plugin with `listGhCopilotRemoteScopes`
+- Check for unreleased API changes not yet in upstream
+
+### eldrick-test-org/devlake-demo
+
+- `scripts/` — PowerShell examples of API calls via `Invoke-RestMethod`
+- `README.md` — API payload examples for connections, scopes, blueprints

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,30 @@
+# Setup steps for the GitHub Copilot Coding Agent.
+# This workflow installs Go, downloads dependencies, and validates
+# that the project compiles and passes tests — giving the agent a
+# working environment identical to local development.
+
+name: Copilot Setup Steps
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # The job MUST be called copilot-setup-steps or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+          cache: true
+
+      - run: go mod download
+
+      - run: go build ./...
+
+      - run: go test ./... -short

AGENTS.md

@@ -40,106 +40,11 @@ The `gh-copilot` plugin computes scope IDs as: enterprise + org → `"enterprise
 ## Roadmap
 See `.github/skills/gh-devlake-roadmap/SKILL.md` for version plan, milestones, and design decisions. Project board: https://github.com/orgs/DevExpGbb/projects/21
 
-## Terminal Output & UX — CRITICAL
+## Terminal Output & UX
 
-**The terminal IS the UI.** Every `fmt.Print` call is a UX decision. Readability, rhythm, and breathing room are non-negotiable.
+**The terminal IS the UI.** See `.github/instructions/terminal-output.instructions.md` for the full formatting rules (auto-applied to `cmd/**/*.go`).
 
-### Line Spacing Rules
-
-These rules are mandatory for all terminal output in `cmd/` files.
-
-**Rule 1: Blank line before every step.**
-Every step (emoji + action text) MUST be preceded by `\n`:
-```go
-// ✅ CORRECT — blank line before step
-fmt.Println("\n🔍 Discovering DevLake instance...")
-
-// ❌ WRONG — no breathing room, steps run together
-fmt.Println("🔍 Discovering DevLake instance...")
-```
-
-**Rule 2: Blank line before AND after section separators.**
-Separator lines (`───`, `═══`, phase banners) must have blank lines on both sides:
-```go
-// ✅ CORRECT
-fmt.Println("\n" + strings.Repeat("─", 50))
-fmt.Println("✅ Connection configured!")
-fmt.Println(strings.Repeat("─", 50))
-fmt.Println()
-
-// ❌ WRONG — separator jammed against previous/next output
-fmt.Println(strings.Repeat("─", 50))
-fmt.Println("✅ Connection configured!")
-fmt.Println(strings.Repeat("─", 50))
-```
-
-**Rule 3: Blank line after completion banners.**
-After a success/summary block, always add a trailing blank line:
-```go
-fmt.Println("═══════════════════════════════════════")
-fmt.Println("  ✅ Setup Complete!")
-fmt.Println("═══════════════════════════════════════")
-fmt.Println()  // ← always trail with blank line
-```
-
-**Rule 4: Sub-items stay tight under their parent.**
-Detail lines (3-space indent) do NOT get blank lines between them:
-```go
-// ✅ CORRECT — grouped tight under parent step
-fmt.Println("\n📡 Creating GitHub connection...")
-fmt.Printf("   Endpoint: %s\n", endpoint)
-fmt.Printf("   Token:    %s\n", masked)
-fmt.Printf("   ✅ Created (ID=%d)\n", conn.ID)
-
-// ❌ WRONG — unnecessary blank lines break grouping
-fmt.Println("\n📡 Creating GitHub connection...")
-fmt.Println()
-fmt.Printf("   Endpoint: %s\n", endpoint)
-```
-
-**Rule 5: Phase banners get a blank line before and after.**
-```go
-fmt.Println()  // or use \n prefix on next line
-
-fmt.Println("╔══════════════════════════════════════╗")
-fmt.Println("║  PHASE 1: Configure Connections      ║")
-fmt.Println("╚══════════════════════════════════════╝")
-
-fmt.Println()  // blank line after banner before first step
-```
-
-### Header Standards
-
-All headers use Unicode double-line `═` at **40 characters** width:
-
-**Top-level command banner:**
-```go
-fmt.Println("\n════════════════════════════════════════")
-fmt.Println("  DevLake — Command Title")
-fmt.Println("════════════════════════════════════════")
-```
-
-**Phase banner (box-drawing):**
-```go
-fmt.Println("\n╔══════════════════════════════════════╗")
-fmt.Println("║  PHASE N: Description                ║")
-fmt.Println("╚══════════════════════════════════════╝")
-```
-
-**Section separator (thin line):**
-```go
-fmt.Println("\n" + strings.Repeat("─", 50))
-```
-
-**Completion banner:**
-```go
-fmt.Println("\n════════════════════════════════════════")
-fmt.Println("  ✅ Action Complete!")
-fmt.Println("════════════════════════════════════════")
-fmt.Println()
-```
-
-### Emoji Usage
+Quick reference — standard emoji vocabulary:
 
 | Emoji | Meaning | Example |
 |-------|---------|---------|
@@ -158,27 +63,15 @@ fmt.Println()
 | 💾 | Save / persist | `State saved to ...` |
 | 🧹 | Cleanup | `Cleaning up resources...` |
 
-### Indentation
-
-- **Steps**: No indent — start at column 0 with emoji
-- **Sub-items under a step**: 3-space indent (`"   "`)
-- **Content inside banners**: 2-space indent (`"  "`)
-- **Bullet lists**: 2-space indent + `•` (`"  • item"`)
-- **Numbered steps**: 2-space indent + number (`"  1. step"`)
-
-### UX Principles
-
-1. **Think end-to-end.** Before adding output, mentally walk through the entire command flow. Does the full terminal scroll look clean? Are steps visually distinct? Can a user scan from top to bottom and understand what happened?
-
-2. **Breathing room over density.** When in doubt, add a blank line. Cramped output is harder to scan than output with generous spacing.
-
-3. **Group related output, separate unrelated steps.** Sub-items under a step stay tight; different steps get blank lines between them.
-
-4. **Every command tells a story.** The output should read as: banner → steps with progress → summary. The user should never wonder "is it still running?" or "did that work?"
+## Related Repositories
 
-5. **Consistency is UX.** If one command uses `═══` headers and another uses `===`, it feels broken even if it works. Match the established patterns exactly.
+These repos provide essential context. Use MCP tools (`mcp_github_get_file_contents`, `mcp_github_search_code`) to read them.
 
-6. **Prompts go to stderr, output to stdout.** Keep stdout clean for piping. All `prompt.*` functions write to `os.Stderr`.
+| Repository | Purpose |
+|------------|---------|
+| `apache/incubator-devlake` | Official upstream — backend Go code, plugin framework, domain models, REST API routes |
+| `DevExpGBB/incubator-devlake` | Fork with unreleased custom plugins (gh-copilot). Rolls up to apache upstream |
+| `eldrick-test-org/devlake-demo` | Demo stack — docker-compose, simulation scripts, API payload examples |
 
 ## Code Conventions