@every-env/compound-plugin 0.7.0 → 0.8.0

package/docs/specs/copilot.md

@@ -0,0 +1,122 @@
+# GitHub Copilot Spec (Agents, Skills, MCP)
+
+Last verified: 2026-02-14
+
+## Primary sources
+
+```
+https://docs.github.com/en/copilot/reference/custom-agents-configuration
+https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
+https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent
+```
+
+## Config locations
+
+| Scope | Path |
+|-------|------|
+| Project agents | `.github/agents/*.agent.md` |
+| Project skills | `.github/skills/*/SKILL.md` |
+| Project instructions | `.github/copilot-instructions.md` |
+| Path-specific instructions | `.github/instructions/*.instructions.md` |
+| Project prompts | `.github/prompts/*.prompt.md` |
+| Org/enterprise agents | `.github-private/agents/*.agent.md` |
+| Personal skills | `~/.copilot/skills/*/SKILL.md` |
+| Directory instructions | `AGENTS.md` (nearest ancestor wins) |
+
+## Agents (.agent.md files)
+
+- Custom agents are Markdown files with YAML frontmatter stored in `.github/agents/`.
+- File extension is `.agent.md` (or `.md`). Filenames may only contain: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`.
+- `description` is the only required frontmatter field.
+
+### Frontmatter fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | No | Derived from filename | Display name |
+| `description` | **Yes** | — | What the agent does |
+| `tools` | No | `["*"]` | Tool access list. `[]` disables all tools. |
+| `target` | No | both | `vscode`, `github-copilot`, or omit for both |
+| `infer` | No | `true` | Auto-select based on task context |
+| `model` | No | Platform default | AI model (works in IDE, may be ignored on github.com) |
+| `mcp-servers` | No | — | MCP config (org/enterprise agents only) |
+| `metadata` | No | — | Arbitrary key-value annotations |
+
+### Character limit
+
+Agent body content is limited to **30,000 characters**.
+
+### Tool names
+
+| Name | Aliases | Purpose |
+|------|---------|---------|
+| `execute` | `shell`, `Bash` | Run shell commands |
+| `read` | `Read` | Read files |
+| `edit` | `Edit`, `Write` | Modify files |
+| `search` | `Grep`, `Glob` | Search files |
+| `agent` | `Task` | Invoke other agents |
+| `web` | `WebSearch`, `WebFetch` | Web access |
+
+## Skills (SKILL.md)
+
+- Skills follow the open SKILL.md standard (same format as Claude Code and Cursor).
+- A skill is a directory containing `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`.
+- YAML frontmatter requires `name` and `description` fields.
+- Skills are loaded on-demand when Copilot determines relevance.
+
+### Discovery locations
+
+| Scope | Path |
+|-------|------|
+| Project | `.github/skills/*/SKILL.md` |
+| Project (Claude-compatible) | `.claude/skills/*/SKILL.md` |
+| Project (auto-discovery) | `.agents/skills/*/SKILL.md` |
+| Personal | `~/.copilot/skills/*/SKILL.md` |
+
+## MCP (Model Context Protocol)
+
+- MCP configuration is set via **Repository Settings > Copilot > Coding agent > MCP configuration** on GitHub.
+- Repository-level agents **cannot** define MCP servers inline; use repository settings instead.
+- Org/enterprise agents can embed MCP server definitions in frontmatter.
+- All env var names must use the `COPILOT_MCP_` prefix.
+- Only MCP tools are supported (not resources or prompts).
+
+### Config structure
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "type": "local",
+      "command": "npx",
+      "args": ["package"],
+      "tools": ["*"],
+      "env": {
+        "API_KEY": "COPILOT_MCP_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Server types
+
+| Type | Fields |
+|------|--------|
+| Local/stdio | `type: "local"`, `command`, `args`, `tools`, `env` |
+| Remote/SSE | `type: "sse"`, `url`, `tools`, `headers` |
+
+## Prompts (.prompt.md)
+
+- Reusable prompt files stored in `.github/prompts/`.
+- Available in VS Code, Visual Studio, and JetBrains IDEs only (not on github.com).
+- Invoked via `/promptname` in chat.
+- Support variable syntax: `${input:name}`, `${file}`, `${selection}`.
+
+## Precedence
+
+1. Repository-level agents
+2. Organization-level agents (`.github-private`)
+3. Enterprise-level agents (`.github-private`)
+
+Within a repo, `AGENTS.md` files in directories provide nearest-ancestor-wins instructions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@every-env/compound-plugin",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "private": false,
   "bin": {

package/plugins/coding-tutor/.cursor-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "coding-tutor",
+  "displayName": "Coding Tutor",
+  "version": "1.2.1",
+  "description": "Personalized coding tutorials that use your actual codebase for examples with spaced repetition quizzes",
+  "author": {
+    "name": "Nityesh Agarwal"
+  },
+  "homepage": "https://github.com/EveryInc/compound-engineering-plugin",
+  "repository": "https://github.com/EveryInc/compound-engineering-plugin",
+  "license": "MIT",
+  "keywords": [
+    "cursor",
+    "plugin",
+    "coding",
+    "programming",
+    "tutorial",
+    "learning",
+    "spaced-repetition"
+  ]
+}

package/plugins/compound-engineering/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-engineering",
-  "version": "2.34.0",
+  "version": "2.35.0",
   "description": "AI-powered development tools. 29 agents, 22 commands, 19 skills, 1 MCP server for code review, research, design, and workflow automation.",
   "author": {
     "name": "Kieran Klaassen",

package/plugins/compound-engineering/.cursor-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "compound-engineering",
+  "displayName": "Compound Engineering",
+  "version": "2.33.0",
+  "description": "AI-powered development tools. 29 agents, 22 commands, 19 skills, 1 MCP server for code review, research, design, and workflow automation.",
+  "author": {
+    "name": "Kieran Klaassen",
+    "email": "kieran@every.to",
+    "url": "https://github.com/kieranklaassen"
+  },
+  "homepage": "https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it",
+  "repository": "https://github.com/EveryInc/compound-engineering-plugin",
+  "license": "MIT",
+  "keywords": [
+    "cursor",
+    "plugin",
+    "ai-powered",
+    "compound-engineering",
+    "workflow-automation",
+    "code-review",
+    "rails",
+    "ruby",
+    "python",
+    "typescript",
+    "knowledge-management",
+    "image-generation",
+    "agent-browser",
+    "browser-automation"
+  ],
+  "mcpServers": ".mcp.json"
+}

package/plugins/compound-engineering/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}

package/plugins/compound-engineering/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to the compound-engineering plugin will be documented in thi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.35.0] - 2026-02-17
+
+### Fixed
+
+- **`/lfg` and `/slfg` first-run failures** — Made ralph-loop step optional with graceful fallback when `ralph-wiggum` skill is not installed (#154). Added explicit "do not stop" instruction across all steps (#134).
+- **`/workflows:plan` not writing file in pipeline** — Added mandatory "Write Plan File" step with explicit Write tool instructions before Post-Generation Options. The file is now always written to disk before any interactive prompts (#155). Also adds pipeline-mode note to skip AskUserQuestion calls when invoked from LFG/SLFG (#134).
+- **Agent namespace typo in `/workflows:plan`** — `Task spec-flow-analyzer(...)` now uses the full qualified name `Task compound-engineering:workflow:spec-flow-analyzer(...)` to prevent Claude from prepending the wrong `workflows:` prefix (#193).
+
+---
+
 ## [2.34.0] - 2026-02-14
 
 ### Added

package/plugins/compound-engineering/commands/lfg.md

@@ -5,9 +5,9 @@ argument-hint: "[feature description]"
 disable-model-invocation: true
 ---
 
-Run these slash commands in order. Do not do anything else.
+Run these slash commands in order. Do not do anything else. Do not stop between steps — complete every step through to the end.
 
-1. `/ralph-wiggum:ralph-loop "finish all slash commands" --completion-promise "DONE"`
+1. **Optional:** If the `ralph-wiggum` skill is available, run `/ralph-wiggum:ralph-loop "finish all slash commands" --completion-promise "DONE"`. If not available or it fails, skip and continue to step 2 immediately.
 2. `/workflows:plan $ARGUMENTS`
 3. `/compound-engineering:deepen-plan`
 4. `/workflows:work`
@@ -17,4 +17,4 @@ Run these slash commands in order. Do not do anything else.
 8. `/compound-engineering:feature-video`
 9. Output `<promise>DONE</promise>` when video is in PR
 
-Start with step 1 now.
+Start with step 2 now (or step 1 if ralph-wiggum is available).

package/plugins/compound-engineering/commands/slfg.md

@@ -5,11 +5,11 @@ argument-hint: "[feature description]"
 disable-model-invocation: true
 ---
 
-Swarm-enabled LFG. Run these steps in order, parallelizing where indicated.
+Swarm-enabled LFG. Run these steps in order, parallelizing where indicated. Do not stop between steps — complete every step through to the end.
 
 ## Sequential Phase
 
-1. `/ralph-wiggum:ralph-loop "finish all slash commands" --completion-promise "DONE"`
+1. **Optional:** If the `ralph-wiggum` skill is available, run `/ralph-wiggum:ralph-loop "finish all slash commands" --completion-promise "DONE"`. If not available or it fails, skip and continue to step 2 immediately.
 2. `/workflows:plan $ARGUMENTS`
 3. `/compound-engineering:deepen-plan`
 4. `/workflows:work` — **Use swarm mode**: Make a Task list and launch an army of agent swarm subagents to build the plan

package/plugins/compound-engineering/commands/workflows/plan.md

@@ -150,7 +150,7 @@ Think like a product manager - what would make this issue clear and actionable?
 
 After planning the issue structure, run SpecFlow Analyzer to validate and refine the feature specification:
 
-- Task spec-flow-analyzer(feature_description, research_findings)
+- Task compound-engineering:workflow:spec-flow-analyzer(feature_description, research_findings)
 
 **SpecFlow Analyzer Output:**
 
@@ -475,6 +475,20 @@ end
 - [ ] Add names of files in pseudo code examples and todo lists
 - [ ] Add an ERD mermaid diagram if applicable for new model changes
 
+## Write Plan File
+
+**REQUIRED: Write the plan file to disk before presenting any options.**
+
+```bash
+mkdir -p docs/plans/
+```
+
+Use the Write tool to save the complete plan to `docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md`. This step is mandatory and cannot be skipped — even when running as part of LFG/SLFG or other automated pipelines.
+
+Confirm: "Plan written to docs/plans/[filename]"
+
+**Pipeline mode:** If invoked from an automated workflow (LFG, SLFG, or any `disable-model-invocation` context), skip all AskUserQuestion calls. Make decisions automatically and proceed to writing the plan without interactive prompts.
+
 ## Output Format
 
 **Filename:** Use the date and kebab-case filename from Step 2 Title & Categorization.

package/src/commands/install.ts

@@ -25,7 +25,7 @@ export default defineCommand({
     to: {
       type: "string",
       default: "opencode",
-      description: "Target format (opencode | codex | droid | cursor | pi | gemini)",
+      description: "Target format (opencode | codex | droid | cursor | pi | copilot | gemini)",
     },
     output: {
       type: "string",
@@ -187,6 +187,10 @@ function resolveTargetOutputRoot(
     const base = hasExplicitOutput ? outputRoot : process.cwd()
     return path.join(base, ".gemini")
   }
+  if (targetName === "copilot") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".github")
+  }
   return outputRoot
 }
 

package/src/commands/sync.ts

@@ -6,10 +6,10 @@ import { syncToOpenCode } from "../sync/opencode"
 import { syncToCodex } from "../sync/codex"
 import { syncToPi } from "../sync/pi"
 import { syncToDroid } from "../sync/droid"
-import { syncToCursor } from "../sync/cursor"
+import { syncToCopilot } from "../sync/copilot"
 import { expandHome } from "../utils/resolve-home"
 
-const validTargets = ["opencode", "codex", "pi", "droid", "cursor"] as const
+const validTargets = ["opencode", "codex", "pi", "droid", "copilot"] as const
 type SyncTarget = (typeof validTargets)[number]
 
 function isValidTarget(value: string): value is SyncTarget {
@@ -40,21 +40,21 @@ function resolveOutputRoot(target: SyncTarget): string {
       return path.join(os.homedir(), ".pi", "agent")
     case "droid":
       return path.join(os.homedir(), ".factory")
-    case "cursor":
-      return path.join(process.cwd(), ".cursor")
+    case "copilot":
+      return path.join(process.cwd(), ".github")
   }
 }
 
 export default defineCommand({
   meta: {
     name: "sync",
-    description: "Sync Claude Code config (~/.claude/) to OpenCode, Codex, Pi, Droid, or Cursor",
+    description: "Sync Claude Code config (~/.claude/) to OpenCode, Codex, Pi, Droid, or Copilot",
   },
   args: {
     target: {
       type: "string",
       required: true,
-      description: "Target: opencode | codex | pi | droid | cursor",
+      description: "Target: opencode | codex | pi | droid | copilot",
     },
     claudeHome: {
       type: "string",
@@ -97,8 +97,8 @@ export default defineCommand({
       case "droid":
         await syncToDroid(config, outputRoot)
         break
-      case "cursor":
-        await syncToCursor(config, outputRoot)
+      case "copilot":
+        await syncToCopilot(config, outputRoot)
         break
     }
 

package/src/converters/{claude-to-cursor.ts → claude-to-copilot.ts}

@@ -1,43 +1,63 @@
 import { formatFrontmatter } from "../utils/frontmatter"
 import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
-import type { CursorBundle, CursorCommand, CursorMcpServer, CursorRule } from "../types/cursor"
+import type {
+  CopilotAgent,
+  CopilotBundle,
+  CopilotGeneratedSkill,
+  CopilotMcpServer,
+} from "../types/copilot"
 import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
 
-export type ClaudeToCursorOptions = ClaudeToOpenCodeOptions
+export type ClaudeToCopilotOptions = ClaudeToOpenCodeOptions
 
-export function convertClaudeToCursor(
+const COPILOT_BODY_CHAR_LIMIT = 30_000
+
+export function convertClaudeToCopilot(
   plugin: ClaudePlugin,
-  _options: ClaudeToCursorOptions,
-): CursorBundle {
-  const usedRuleNames = new Set<string>()
-  const usedCommandNames = new Set<string>()
+  _options: ClaudeToCopilotOptions,
+): CopilotBundle {
+  const usedAgentNames = new Set<string>()
+  const usedSkillNames = new Set<string>()
+
+  const agents = plugin.agents.map((agent) => convertAgent(agent, usedAgentNames))
+
+  // Reserve skill names first so generated skills (from commands) don't collide
+  const skillDirs = plugin.skills.map((skill) => {
+    usedSkillNames.add(skill.name)
+    return {
+      name: skill.name,
+      sourceDir: skill.sourceDir,
+    }
+  })
 
-  const rules = plugin.agents.map((agent) => convertAgentToRule(agent, usedRuleNames))
-  const commands = plugin.commands.map((command) => convertCommand(command, usedCommandNames))
-  const skillDirs = plugin.skills.map((skill) => ({
-    name: skill.name,
-    sourceDir: skill.sourceDir,
-  }))
+  const generatedSkills = plugin.commands.map((command) =>
+    convertCommandToSkill(command, usedSkillNames),
+  )
 
-  const mcpServers = convertMcpServers(plugin.mcpServers)
+  const mcpConfig = convertMcpServers(plugin.mcpServers)
 
   if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
-    console.warn("Warning: Cursor does not support hooks. Hooks were skipped during conversion.")
+    console.warn("Warning: Copilot does not support hooks. Hooks were skipped during conversion.")
   }
 
-  return { rules, commands, skillDirs, mcpServers }
+  return { agents, generatedSkills, skillDirs, mcpConfig }
 }
 
-function convertAgentToRule(agent: ClaudeAgent, usedNames: Set<string>): CursorRule {
+function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): CopilotAgent {
   const name = uniqueName(normalizeName(agent.name), usedNames)
   const description = agent.description ?? `Converted from Claude agent ${agent.name}`
 
   const frontmatter: Record<string, unknown> = {
     description,
-    alwaysApply: false,
+    tools: ["*"],
+    infer: true,
   }
 
-  let body = transformContentForCursor(agent.body.trim())
+  if (agent.model) {
+    frontmatter.model = agent.model
+  }
+
+  let body = transformContentForCopilot(agent.body.trim())
   if (agent.capabilities && agent.capabilities.length > 0) {
     const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
     body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
@@ -46,39 +66,44 @@ function convertAgentToRule(agent: ClaudeAgent, usedNames: Set<string>): CursorR
     body = `Instructions converted from the ${agent.name} agent.`
   }
 
+  if (body.length > COPILOT_BODY_CHAR_LIMIT) {
+    console.warn(
+      `Warning: Agent "${agent.name}" body exceeds ${COPILOT_BODY_CHAR_LIMIT} characters (${body.length}). Copilot may truncate it.`,
+    )
+  }
+
   const content = formatFrontmatter(frontmatter, body)
   return { name, content }
 }
 
-function convertCommand(command: ClaudeCommand, usedNames: Set<string>): CursorCommand {
+function convertCommandToSkill(
+  command: ClaudeCommand,
+  usedNames: Set<string>,
+): CopilotGeneratedSkill {
   const name = uniqueName(flattenCommandName(command.name), usedNames)
 
-  const sections: string[] = []
-
+  const frontmatter: Record<string, unknown> = {
+    name,
+  }
   if (command.description) {
-    sections.push(`<!-- ${command.description} -->`)
+    frontmatter.description = command.description
   }
 
+  const sections: string[] = []
+
   if (command.argumentHint) {
     sections.push(`## Arguments\n${command.argumentHint}`)
   }
 
-  const transformedBody = transformContentForCursor(command.body.trim())
+  const transformedBody = transformContentForCopilot(command.body.trim())
   sections.push(transformedBody)
 
-  const content = sections.filter(Boolean).join("\n\n").trim()
+  const body = sections.filter(Boolean).join("\n\n").trim()
+  const content = formatFrontmatter(frontmatter, body)
   return { name, content }
 }
 
-/**
- * Transform Claude Code content to Cursor-compatible content.
- *
- * 1. Task agent calls: Task agent-name(args) -> Use the agent-name skill to: args
- * 2. Slash commands: /workflows:plan -> /plan (flatten namespace)
- * 3. Path rewriting: .claude/ -> .cursor/
- * 4. Agent references: @agent-name -> the agent-name rule
- */
-export function transformContentForCursor(body: string): string {
+export function transformContentForCopilot(body: string): string {
   let result = body
 
   // 1. Transform Task agent calls
@@ -88,24 +113,25 @@ export function transformContentForCursor(body: string): string {
     return `${prefix}Use the ${skillName} skill to: ${args.trim()}`
   })
 
-  // 2. Transform slash command references (flatten namespaces)
+  // 2. Transform slash command references (replace colons with hyphens)
   const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
   result = result.replace(slashCommandPattern, (match, commandName: string) => {
     if (commandName.includes("/")) return match
     if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) return match
-    const flattened = flattenCommandName(commandName)
-    return `/${flattened}`
+    const normalized = flattenCommandName(commandName)
+    return `/${normalized}`
   })
 
-  // 3. Rewrite .claude/ paths to .cursor/
+  // 3. Rewrite .claude/ paths to .github/ and ~/.claude/ to ~/.copilot/
   result = result
-    .replace(/~\/\.claude\//g, "~/.cursor/")
-    .replace(/\.claude\//g, ".cursor/")
+    .replace(/~\/\.claude\//g, "~/.copilot/")
+    .replace(/\.claude\//g, ".github/")
 
   // 4. Transform @agent-name references
-  const agentRefPattern = /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi
+  const agentRefPattern =
+    /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi
   result = result.replace(agentRefPattern, (_match, agentName: string) => {
-    return `the ${normalizeName(agentName)} rule`
+    return `the ${normalizeName(agentName)} agent`
   })
 
   return result
@@ -113,29 +139,47 @@ export function transformContentForCursor(body: string): string {
 
 function convertMcpServers(
   servers?: Record<string, ClaudeMcpServer>,
-): Record<string, CursorMcpServer> | undefined {
+): Record<string, CopilotMcpServer> | undefined {
   if (!servers || Object.keys(servers).length === 0) return undefined
 
-  const result: Record<string, CursorMcpServer> = {}
+  const result: Record<string, CopilotMcpServer> = {}
   for (const [name, server] of Object.entries(servers)) {
-    const entry: CursorMcpServer = {}
+    const entry: CopilotMcpServer = {
+      type: server.command ? "local" : "sse",
+      tools: ["*"],
+    }
+
     if (server.command) {
       entry.command = server.command
       if (server.args && server.args.length > 0) entry.args = server.args
-      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
     } else if (server.url) {
       entry.url = server.url
       if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
     }
+
+    if (server.env && Object.keys(server.env).length > 0) {
+      entry.env = prefixEnvVars(server.env)
+    }
+
     result[name] = entry
   }
   return result
 }
 
+function prefixEnvVars(env: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith("COPILOT_MCP_")) {
+      result[key] = value
+    } else {
+      result[`COPILOT_MCP_${key}`] = value
+    }
+  }
+  return result
+}
+
 function flattenCommandName(name: string): string {
-  const colonIndex = name.lastIndexOf(":")
-  const base = colonIndex >= 0 ? name.slice(colonIndex + 1) : name
-  return normalizeName(base)
+  return normalizeName(name)
 }
 
 function normalizeName(value: string): string {