@sysvv/ai-skill 1.2.0 → 1.4.0

package/dist/core/mcp.js

@@ -0,0 +1,190 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as TOML from "smol-toml";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// ── Targets por agent ───────────────────────────────────────────────────
+const AGENT_MCP_TARGETS = {
+    // ── Claude ──────────────────────────────────────────────────────────
+    // .mcp.json → { mcpServers: { name: { command, args, env } } }
+    claude: {
+        format: "json",
+        file: ".mcp.json",
+        serversKey: "mcpServers",
+        buildServerConfig: (mcp) => {
+            if (mcp.transport === "stdio") {
+                const config = { command: mcp.command };
+                if (mcp.args?.length)
+                    config.args = mcp.args;
+                if (mcp.env && Object.keys(mcp.env).length)
+                    config.env = mcp.env;
+                return config;
+            }
+            const config = { url: mcp.url };
+            if (mcp.headers && Object.keys(mcp.headers).length)
+                config.headers = mcp.headers;
+            if (mcp.env && Object.keys(mcp.env).length)
+                config.env = mcp.env;
+            return config;
+        }
+    },
+    // ── Gemini ──────────────────────────────────────────────────────────
+    // .gemini/settings.json → { mcpServers: { name: { command, args, env, cwd, timeout } } }
+    // Gemini usa "httpUrl" para streamable-http
+    gemini: {
+        format: "json",
+        file: ".gemini/settings.json",
+        serversKey: "mcpServers",
+        buildServerConfig: (mcp) => {
+            const config = {};
+            if (mcp.transport === "stdio") {
+                config.command = mcp.command;
+                if (mcp.args?.length)
+                    config.args = mcp.args;
+                if (mcp.cwd)
+                    config.cwd = mcp.cwd;
+            }
+            else if (mcp.transport === "sse") {
+                config.url = mcp.url;
+                if (mcp.headers && Object.keys(mcp.headers).length)
+                    config.headers = mcp.headers;
+            }
+            else if (mcp.transport === "streamable-http") {
+                config.httpUrl = mcp.url;
+                if (mcp.headers && Object.keys(mcp.headers).length)
+                    config.headers = mcp.headers;
+            }
+            if (mcp.env && Object.keys(mcp.env).length)
+                config.env = mcp.env;
+            if (mcp.timeout)
+                config.timeout = mcp.timeout;
+            return config;
+        }
+    },
+    // ── Codex ───────────────────────────────────────────────────────────
+    // .codex/config.toml → [mcp_servers.<name>]
+    // stdio: command, args, env, cwd
+    // streamable-http: url, bearer_token_env_var, http_headers
+    // extras: startup_timeout_sec, tool_timeout_sec, enabled
+    codex: {
+        format: "toml",
+        file: ".codex/config.toml",
+        buildServerEntry: (mcp) => {
+            const entry = {};
+            if (mcp.transport === "stdio") {
+                entry.command = mcp.command;
+                if (mcp.args?.length)
+                    entry.args = mcp.args;
+                if (mcp.cwd)
+                    entry.cwd = mcp.cwd;
+            }
+            else {
+                // sse e streamable-http → Codex usa "url" para ambos
+                entry.url = mcp.url;
+                if (mcp.headers && Object.keys(mcp.headers).length) {
+                    entry.http_headers = mcp.headers;
+                }
+            }
+            if (mcp.env && Object.keys(mcp.env).length)
+                entry.env = mcp.env;
+            if (mcp.timeout)
+                entry.tool_timeout_sec = Math.ceil(mcp.timeout / 1000);
+            return entry;
+        }
+    },
+    // ── Copilot ─────────────────────────────────────────────────────────
+    // .vscode/mcp.json → { inputs: [], servers: { name: { command, args, env } } }
+    copilot: {
+        format: "json",
+        file: ".vscode/mcp.json",
+        serversKey: "servers",
+        buildServerConfig: (mcp) => {
+            if (mcp.transport === "stdio") {
+                const config = { command: mcp.command };
+                if (mcp.args?.length)
+                    config.args = mcp.args;
+                if (mcp.env && Object.keys(mcp.env).length)
+                    config.env = mcp.env;
+                return config;
+            }
+            const config = { url: mcp.url };
+            if (mcp.headers && Object.keys(mcp.headers).length)
+                config.headers = mcp.headers;
+            if (mcp.env && Object.keys(mcp.env).length)
+                config.env = mcp.env;
+            return config;
+        }
+    },
+};
+// ── Writers ─────────────────────────────────────────────────────────────
+async function writeJsonTarget(target, targetPath, mcp) {
+    let existing = {};
+    if (await fs.pathExists(targetPath)) {
+        existing = await fs.readJson(targetPath);
+    }
+    // Copilot: garante que "inputs" exista
+    if (target.serversKey === "servers" && !existing.inputs) {
+        existing.inputs = [];
+    }
+    const servers = existing[target.serversKey] ?? {};
+    servers[mcp.name] = target.buildServerConfig(mcp);
+    existing[target.serversKey] = servers;
+    await fs.ensureDir(path.dirname(targetPath));
+    await fs.writeJson(targetPath, existing, { spaces: 2 });
+}
+async function writeTomlTarget(target, targetPath, mcp) {
+    let existing = {};
+    if (await fs.pathExists(targetPath)) {
+        const content = await fs.readFile(targetPath, "utf8");
+        if (content.trim()) {
+            existing = TOML.parse(content);
+        }
+    }
+    const mcpServers = existing.mcp_servers ?? {};
+    mcpServers[mcp.name] = target.buildServerEntry(mcp);
+    existing.mcp_servers = mcpServers;
+    await fs.ensureDir(path.dirname(targetPath));
+    await fs.writeFile(targetPath, TOML.stringify(existing), "utf8");
+}
+// ── API pública ─────────────────────────────────────────────────────────
+/** Carrega a definição de um MCP pelo nome */
+export async function loadMcp(name) {
+    const mcpFile = path.resolve(__dirname, "../../mcps", `${name}.mcp.json`);
+    if (!(await fs.pathExists(mcpFile))) {
+        throw new Error(`MCP "${name}" não encontrado em mcps/${name}.mcp.json`);
+    }
+    return fs.readJson(mcpFile);
+}
+/** Escreve o MCP no arquivo alvo do agent, fazendo merge com configs existentes */
+export async function writeMcp(agent, mcp) {
+    const target = AGENT_MCP_TARGETS[agent];
+    if (!target)
+        throw new Error(`Agent "${agent}" não tem target de MCP configurado.`);
+    const targetPath = path.resolve(target.file);
+    if (target.format === "json") {
+        await writeJsonTarget(target, targetPath, mcp);
+    }
+    else {
+        await writeTomlTarget(target, targetPath, mcp);
+    }
+    return targetPath;
+}
+/** Retorna o path do arquivo MCP de um agent */
+export function getMcpTargetPath(agent) {
+    return AGENT_MCP_TARGETS[agent]?.file;
+}
+/** Lista todos os MCPs disponíveis */
+export async function listMcps() {
+    const mcpsDir = path.resolve(__dirname, "../../mcps");
+    if (!(await fs.pathExists(mcpsDir)))
+        return [];
+    const files = await fs.readdir(mcpsDir);
+    const results = [];
+    for (const file of files) {
+        if (file.endsWith(".mcp.json")) {
+            const mcp = await fs.readJson(path.join(mcpsDir, file));
+            results.push(mcp);
+        }
+    }
+    return results;
+}

package/dist/index.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { findSkillFiles } from "./core/registry.js";
 import { parseSkillFile } from "./core/frontmatter.js";
 import { loadSkill } from "./core/skill.js";
+import { loadMcp, writeMcp, getMcpTargetPath } from "./core/mcp.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // ── ANSI ────────────────────────────────────────────────────────────────
 const ANSI = {
@@ -18,6 +19,7 @@ const PINK = '\x1b[38;2;238;54;141m';
 const BLUE = '\x1b[38;2;14;93;171m';
 const RED = '\x1b[38;2;255;70;70m';
 const GREEN = '\x1b[38;2;80;200;120m';
+const YELLOW = '\x1b[38;2;255;200;50m';
 const WHITE = '\x1b[97m';
 // ── Inquirer Theme ──────────────────────────────────────────────────────
 const sysTheme = {
@@ -87,7 +89,7 @@ function showBanner() {
     console.log(indent + ANSI.dim + centerPad('│  ' + WHITE + desc + ANSI.reset + ANSI.dim + '  │', maxWidth) + ANSI.reset);
     console.log(indent + ANSI.dim + centerPad('└' + '─'.repeat(boxInner) + '┘', maxWidth) + ANSI.reset);
     console.log('');
-    console.log(indent + ANSI.dim + centerPad('npx @sysvv/ai-skill --claude | --codex | --gemini | --clear', maxWidth) + ANSI.reset);
+    console.log(indent + ANSI.dim + centerPad('npx @sysvv/ai-skill --claude | --codex | --gemini | --copilot | --clear', maxWidth) + ANSI.reset);
     console.log('');
     console.log(separator);
     console.log('');
@@ -97,6 +99,7 @@ const AGENT_DIRS = {
     claude: ".claude/skills",
     codex: ".codex/skills",
     gemini: ".gemini/skills",
+    copilot: ".github/skills",
 };
 // ── Parse args ──────────────────────────────────────────────────────────
 function parseArgs() {
@@ -109,7 +112,7 @@ function parseArgs() {
     }
     return {};
 }
-// ── Install skills for agent ────────────────────────────────────────────
+// ── Install skills + MCPs for agent ─────────────────────────────────────
 async function installSkills(agent) {
     const skillFiles = await findSkillFiles();
     const available = [];
@@ -120,7 +123,8 @@ async function installSkills(agent) {
             file,
             name: metadata.name,
             title: metadata.title ?? metadata.name,
-            description: metadata.description
+            description: metadata.description,
+            mcps: metadata.mcps ?? []
         });
     }
     if (available.length === 0) {
@@ -133,7 +137,7 @@ async function installSkills(agent) {
             name: "selected",
             message: "Escolha as skills:",
             choices: available.map((s) => ({
-                name: `${s.title} ${ANSI.dim}— ${s.description}${ANSI.reset}`,
+                name: `${s.title} ${ANSI.dim}— ${s.description}${s.mcps.length > 0 ? ` ${YELLOW}[MCP]${ANSI.reset}${ANSI.dim}` : ''}${ANSI.reset}`,
                 value: s.file
             })),
             validate: (answer) => answer.length > 0 ? true : "Selecione pelo menos uma skill.",
@@ -141,6 +145,8 @@ async function installSkills(agent) {
         }
     ]);
     const destBase = path.resolve(AGENT_DIRS[agent]);
+    const mcpsToInstall = new Set();
+    // Instala skills
     console.log('');
     for (const file of selected) {
         const skill = await loadSkill(file, agent);
@@ -148,32 +154,58 @@ async function installSkills(agent) {
         await fs.ensureDir(skillDir);
         await fs.writeFile(path.join(skillDir, "SKILL.md"), skill.renderedBody, "utf8");
         console.log(`  ${GREEN}✔${ANSI.reset} ${skill.metadata.name}`);
+        // Coleta MCPs necessários
+        for (const mcpName of skill.metadata.mcps ?? []) {
+            mcpsToInstall.add(mcpName);
+        }
+    }
+    // Instala MCPs automaticamente
+    if (mcpsToInstall.size > 0) {
+        console.log('');
+        let mcpTarget = '';
+        for (const mcpName of mcpsToInstall) {
+            try {
+                const mcp = await loadMcp(mcpName);
+                mcpTarget = await writeMcp(agent, mcp);
+                console.log(`  ${GREEN}✔${ANSI.reset} MCP ${ANSI.bold}${mcpName}${ANSI.reset} ${ANSI.dim}→ ${mcpTarget}${ANSI.reset}`);
+            }
+            catch (err) {
+                console.log(`  ${RED}✖${ANSI.reset} MCP ${mcpName}: ${err.message}`);
+            }
+        }
     }
     console.log(`\n  Skills instaladas em ${ANSI.bold}${destBase}/${ANSI.reset}\n`);
 }
-// ── Clear all skills ────────────────────────────────────────────────────
+// ── Clear all skills + MCPs ─────────────────────────────────────────────
 async function clearSkills() {
-    const existing = [];
+    const found = [];
     for (const [agent, dir] of Object.entries(AGENT_DIRS)) {
-        const full = path.resolve(dir);
-        if (await fs.pathExists(full)) {
-            existing.push(agent);
+        const skillsFull = path.resolve(dir);
+        const mcpTarget = getMcpTargetPath(agent);
+        const mcpFull = mcpTarget ? path.resolve(mcpTarget) : "";
+        const hasSkills = await fs.pathExists(skillsFull);
+        const hasMcp = mcpFull ? await fs.pathExists(mcpFull) : false;
+        if (hasSkills || hasMcp) {
+            found.push({ agent, skillsDir: skillsFull, mcpFile: mcpFull, hasSkills, hasMcp });
         }
     }
-    if (existing.length === 0) {
-        console.log("  Nenhuma pasta de skills encontrada.\n");
+    if (found.length === 0) {
+        console.log("  Nenhuma pasta de skills ou MCP encontrada.\n");
         return;
     }
-    console.log(`  ${RED}⚠${ANSI.reset}  Pastas encontradas:\n`);
-    for (const agent of existing) {
-        console.log(`     ${ANSI.dim}${path.resolve(AGENT_DIRS[agent])}${ANSI.reset}`);
+    console.log(`  ${RED}⚠${ANSI.reset}  Encontrado:\n`);
+    for (const f of found) {
+        if (f.hasSkills)
+            console.log(`     ${ANSI.dim}${f.skillsDir}${ANSI.reset}`);
+        if (f.hasMcp)
+            console.log(`     ${ANSI.dim}${f.mcpFile}${ANSI.reset}`);
     }
     console.log('');
     const { confirm } = await inquirer.prompt([
         {
             type: "confirm",
             name: "confirm",
-            message: "Tem certeza que deseja apagar TODAS as pastas de skills?",
+            message: "Tem certeza que deseja apagar TUDO (skills + MCPs)?",
             default: false,
             theme: sysTheme
         }
@@ -182,12 +214,17 @@ async function clearSkills() {
         console.log("\n  Operação cancelada.\n");
         return;
     }
-    for (const agent of existing) {
-        const full = path.resolve(AGENT_DIRS[agent]);
-        await fs.remove(full);
-        console.log(`  ${RED}✖${ANSI.reset} ${full} removida`);
+    for (const f of found) {
+        if (f.hasSkills) {
+            await fs.remove(f.skillsDir);
+            console.log(`  ${RED}✖${ANSI.reset} ${f.skillsDir}`);
+        }
+        if (f.hasMcp) {
+            await fs.remove(f.mcpFile);
+            console.log(`  ${RED}✖${ANSI.reset} ${f.mcpFile}`);
+        }
     }
-    console.log("\n  Todas as skills foram removidas.\n");
+    console.log("\n  Tudo removido.\n");
 }
 // ── Main ────────────────────────────────────────────────────────────────
 async function main() {

package/mcps/azure-devops.mcp.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "../schemas/mcp.schema.json",
+  "name": "azure-devops",
+  "description": "Integração com Azure DevOps para work items, repos e pipelines.",
+  "transport": "stdio",
+  "command": "npx",
+  "args": [
+    "-y",
+    "@azure-devops/mcp",
+    "sysmanagerdevops",
+    "-d", "core", "work", "work-items"
+  ],
+  "env": {
+    "AZURE_DEVOPS_PAT": "${AZURE_DEVOPS_PAT}"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sysvv/ai-skill",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Instale skills de IA direto no seu projeto. Escolha o agent, escolha as skills.",
   "type": "module",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "mcps",
+    "schemas"
   ],
   "scripts": {
     "build": "tsc",
@@ -28,7 +30,8 @@
   "dependencies": {
     "fs-extra": "^11.3.0",
     "gray-matter": "^4.0.3",
-    "inquirer": "^12.5.2"
+    "inquirer": "^12.5.2",
+    "smol-toml": "^1.6.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/schemas/mcp.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sysvv.dev/schemas/mcp.schema.json",
+  "title": "MCP Server Configuration",
+  "description": "Schema para configuração de servidores MCP (Model Context Protocol). Suporta os transportes stdio, sse e streamable-http. Campos opcionais como timeout e cwd são aplicados conforme o suporte de cada agent.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Referência ao JSON Schema para validação e autocomplete."
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Identificador único do MCP. Deve ser slug (lowercase, hífens). Ex: azure-devops"
+    },
+    "description": {
+      "type": "string",
+      "description": "Descrição curta do que o MCP faz."
+    },
+    "transport": {
+      "type": "string",
+      "enum": ["stdio", "sse", "streamable-http"],
+      "description": "Tipo de transporte do MCP."
+    },
+    "command": {
+      "type": "string",
+      "description": "[stdio] Comando para iniciar o servidor MCP."
+    },
+    "args": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "[stdio] Argumentos passados ao comando."
+    },
+    "cwd": {
+      "type": "string",
+      "description": "[stdio] Diretório de trabalho para o processo do servidor."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "[sse | streamable-http] URL do servidor MCP."
+    },
+    "headers": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "[sse | streamable-http] Headers HTTP enviados nas requisições."
+    },
+    "env": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Variáveis de ambiente. Use ${VAR} para referências dinâmicas."
+    },
+    "timeout": {
+      "type": "number",
+      "description": "Timeout da requisição em milissegundos. Padrão varia por agent."
+    }
+  },
+  "required": ["name", "description", "transport"],
+  "allOf": [
+    {
+      "if": {
+        "properties": { "transport": { "const": "stdio" } },
+        "required": ["transport"]
+      },
+      "then": {
+        "required": ["command"]
+      }
+    },
+    {
+      "if": {
+        "properties": { "transport": { "const": "sse" } },
+        "required": ["transport"]
+      },
+      "then": {
+        "required": ["url"]
+      }
+    },
+    {
+      "if": {
+        "properties": { "transport": { "const": "streamable-http" } },
+        "required": ["transport"]
+      },
+      "then": {
+        "required": ["url"]
+      }
+    }
+  ]
+}

package/skills/ado-workflow/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: ado-workflow
+title: ADO Workflow
+description: gerenciar work items do Azure DevOps integrado com Git local. Sincroniza estados, vincula commits e mantém ADO atualizado.
+version: 1.0.0
+providers:
+  - claude
+  - codex
+  - gemini
+  - copilot
+mcps:
+  - azure-devops
+variables:
+  language: pt-BR
+---
+
+# ADO Workflow Skill
+
+Reusable skill that integrates Azure DevOps work items with local Git operations. Manages work item states, links commits to tasks, and keeps ADO in sync with development progress. Uses MCP tools as primary interface with CLI fallback.
+
+## Setup
+
+1. Verify MCP server "azure-devops" is available (check `mcp__azure-devops__*` tools)
+2. If MCP is NOT available: fall back to `az` CLI commands for all operations
+3. Verify `git` is installed and repository is initialized
+4. **NEVER** print or display the value of `AZURE_DEVOPS_PAT`
+
+## Rules
+
+1. ALWAYS reference ADO work item IDs in commit messages (e.g., `feat: implement login #123`)
+2. NEVER update work item state without verifying current state first
+3. NEVER print or display PAT/token values
+4. Make atomic commits — one logical change per commit
+5. Use Conventional Commits format (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, etc.)
+6. Keep ADO work item state in sync with actual progress
+7. ALWAYS confirm with the user before changing work item states
+8. Organization, project, area paths, and states are project-specific — do not hardcode them
+9. Work item states may use custom/localized names — always verify before updating
+10. When creating Tasks: do NOT assign, ALWAYS ask Area Path, activity requires user selection
+
+## Operations
+
+### list
+
+List work items assigned to the current user.
+
+**MCP:** `mcp__azure-devops__wit_my_work_items` with `project: {project}`, `type: "assignedtome"`, `includeCompleted: false`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards query \
+  --wiql "SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] <> 'Closed'" \
+  --project {project} --organization {organization} --output table
+```
+
+**Output:** Display ID, Title, State, Assigned To, Work Item Type as formatted table.
+
+### show
+
+Show full details of a work item by ID.
+
+**Params:** `id` (required)
+
+**MCP:** `mcp__azure-devops__wit_get_work_item` with `id: {id}`, `project: {project}`, `expand: "relations"`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards work-item show --id {id} --organization {organization} --output json
+```
+
+**Output:** Parse and display id, type, title, state, description, acceptance criteria, assignedTo, iterationPath, areaPath, priority, storyPoints, relations.
+
+### start
+
+Start working on a task — set state to active and begin implementation.
+
+**Params:** `id` (required)
+
+**Process:**
+1. Fetch work item details using "show" operation
+2. Display title, description, and acceptance criteria to user
+3. Update state to the active state in ADO
+4. Create implementation plan based on requirements
+5. Ask user for confirmation before proceeding
+
+**MCP:** `mcp__azure-devops__wit_update_work_item` with `id: {id}`, `updates: [{"path": "/fields/System.State", "value": "{active_state}"}]`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards work-item update --id {id} --state "{active_state}" --organization {organization} --output json
+```
+
+**Output:** Confirm state change. Show implementation plan. Wait for user approval.
+
+### complete
+
+Complete a task — verify criteria, final commit, set state to closed.
+
+**Params:** `id` (required)
+
+**Process:**
+1. Fetch work item details — verify acceptance criteria are met
+2. Run final tests if applicable
+3. Make final commit referencing work item ID
+4. Update state to "Closed" in ADO
+5. Add completion comment with commit SHA
+
+**MCP:** `mcp__azure-devops__wit_update_work_item` with `id: {id}`, `updates: [{"path": "/fields/System.State", "value": "Closed"}]`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards work-item update --id {id} --state "Closed" --organization {organization} --output json
+```
+
+**Output:** Confirm completion. Show final commit SHA, updated state, summary.
+
+### commit
+
+Make an incremental commit linked to a work item.
+
+**Params:** `message` (optional), `work-item-id` (optional)
+
+**Process:**
+1. Delegate to git-cli skill `/git-commit`
+2. Append work item reference to commit message (e.g., `#123`)
+
+**Output:** Commit hash, message, files changed. Tip: use `/git-push` to push.
+
+**Notes:** This operation delegates to the git-cli skill for actual Git operations.
+
+### create
+
+Create a new work item in ADO.
+
+**Params:** `type` (required), `title` (required), `description` (optional), `area-path` (optional — ALWAYS ask user), `activity` (optional — present types to user)
+
+**MCP:** `mcp__azure-devops__wit_create_work_item` with `project: {project}`, `type: "{type}"`, `title: "{title}"`, `additionalFields: {"System.Description": "{description}", "System.AreaPath": "{area-path}", "Microsoft.VSTS.Common.Activity": "{activity}", "Microsoft.VSTS.Scheduling.OriginalEstimate": 0, "Microsoft.VSTS.Scheduling.RemainingWork": 0, "Microsoft.VSTS.Scheduling.CompletedWork": 0}`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards work-item create \
+  --type "{type}" --title "{title}" --project {project} \
+  --organization {organization} --area "{area-path}" \
+  --fields "Microsoft.VSTS.Common.Activity={activity}" \
+  --output json
+```
+
+**Output:** Parse response: extract id, title, state, url.
+
+**Notes:**
+- Omit additionalFields entries for params not provided
+- Do NOT assign unless explicitly requested
+- ALWAYS ask user for Area Path before executing
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| MCP server not available | Not configured or not running | Check `.mcp.json`, verify PAT in `.env`, restart AI tool |
+| 401 / 403 | Invalid or expired PAT | Check PAT scopes: Work Items (Read, Write, Manage), Project (Read) |
+| Work item type not found | Process template mismatch | Agile = "User Story", Scrum = "Product Backlog Item" |
+| State transition not allowed | Invalid state change | Verify allowed transitions for the work item type |
+| MCP tool call fails | Various | Fall back to `az` CLI equivalent command |