cc-dev-template 0.1.8 → 0.1.10

package/src/mcp-servers/qa-server/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "qa-server",
+  "version": "1.0.0",
+  "description": "MCP server that spawns a QA sub-agent for frontend visual inspection",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "qa-server": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.30",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/mcp-servers/qa-server/src/index.ts

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * QA Server - MCP server that spawns a QA sub-agent for frontend visual inspection
+ *
+ * This server exposes a single `inspect_frontend` tool that:
+ * 1. Takes a URL and task description
+ * 2. Spawns a Claude sub-agent with chrome-devtools MCP access
+ * 3. The sub-agent navigates, screenshots, clicks, and inspects
+ * 4. Returns a structured QA report
+ *
+ * Token savings: ~20k (26 browser tools) → ~500 (1 tool)
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+// QA Agent system prompt - follows ADR-002: explain WHY, positive framing, clear context
+const QA_SYSTEM_PROMPT = `You are a QA engineer helping developers verify their frontend works correctly.
+
+**Why this matters:** Catching visual bugs, console errors, and broken interactions early saves significant debugging time. Your detailed assessment helps developers ship with confidence.
+
+**Your capabilities:** You can navigate pages, take screenshots to see the visual state, click elements, fill forms, and read console messages. Screenshots show you exactly what users see.
+
+**What makes a great QA report:**
+- Visual Assessment: Describe the layout, colors, and overall appearance
+- Console Errors: List any errors found (or confirm none exist)
+- Task Result: What happened when you performed the requested task
+- Issues Found: Any problems discovered during inspection
+- Overall: PASS or FAIL with a clear reason
+
+Focus on what the developer needs to know: visual issues, broken functionality, and console errors. Be thorough in your inspection and clear in your reporting.`;
+
+// Create MCP server
+const server = new Server(
+  {
+    name: "qa-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "inspect_frontend",
+        description:
+          "Spawn a QA sub-agent to visually inspect a frontend. The sub-agent can navigate, take screenshots, click elements, fill forms, and check console errors. Returns a structured QA report. Uses Opus for best visual understanding.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url: {
+              type: "string",
+              description: "URL to inspect (e.g., http://localhost:3000, https://example.com)",
+            },
+            task: {
+              type: "string",
+              description:
+                "What to inspect or test (e.g., 'Verify the login form works', 'Check for visual regressions on the homepage', 'Test the checkout flow')",
+            },
+          },
+          required: ["url", "task"],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name !== "inspect_frontend") {
+    throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+
+  const { url, task } = request.params.arguments as { url: string; task: string };
+
+  if (!url || !task) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Error: Both 'url' and 'task' parameters are required",
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  console.error(`[QA Server] Starting inspection of ${url}`);
+  console.error(`[QA Server] Task: ${task}`);
+
+  try {
+    // Build the task prompt - follows ADR-002: purpose-driven, positive framing
+    const taskPrompt = `
+**QA Inspection Request**
+
+URL: ${url}
+Task: ${task}
+
+**Context:** A developer needs verification that this frontend is working correctly. Your assessment helps them catch issues before users do.
+
+**Available tools:**
+- navigate_page: Go to the URL
+- take_screenshot: See the visual state (use this to understand what the page looks like)
+- take_snapshot: Get element references for clicking/filling
+- list_console_messages: Check for JavaScript errors
+- click, fill, fill_form: Interact with elements
+
+**Success criteria:** Provide a clear QA report covering visual state, console errors, task completion, and overall pass/fail assessment.
+`;
+
+    // Spawn sub-agent with chrome-devtools MCP access
+    const result = query({
+      prompt: taskPrompt,
+      options: {
+        model: "claude-opus-4-5",
+        cwd: process.cwd(),
+        systemPrompt: QA_SYSTEM_PROMPT,
+        mcpServers: {
+          "chrome-devtools": {
+            command: "npx",
+            args: ["chrome-devtools-mcp@latest", "--headless"],
+          },
+        },
+        allowedTools: [
+          // Navigation
+          "mcp__chrome-devtools__navigate_page",
+          "mcp__chrome-devtools__new_page",
+          "mcp__chrome-devtools__list_pages",
+          "mcp__chrome-devtools__select_page",
+          "mcp__chrome-devtools__wait_for",
+          // Inspection
+          "mcp__chrome-devtools__take_screenshot",
+          "mcp__chrome-devtools__take_snapshot",
+          "mcp__chrome-devtools__list_console_messages",
+          "mcp__chrome-devtools__get_console_message",
+          // Interaction
+          "mcp__chrome-devtools__click",
+          "mcp__chrome-devtools__fill",
+          "mcp__chrome-devtools__fill_form",
+          "mcp__chrome-devtools__hover",
+          "mcp__chrome-devtools__press_key",
+          "mcp__chrome-devtools__handle_dialog",
+        ],
+      },
+    });
+
+    // Collect the agent's final response
+    let report = "";
+    let totalCost = 0;
+
+    for await (const message of result) {
+      // Log progress to stderr (visible in server logs, not returned to client)
+      if (message.type === "system" && message.subtype === "init") {
+        console.error(`[QA Server] Agent initialized with tools: ${message.tools.length} tools`);
+      }
+
+      if (message.type === "assistant") {
+        // Extract text responses from assistant messages
+        const textBlocks = message.message.content.filter(
+          (c: any) => c.type === "text"
+        );
+        for (const block of textBlocks) {
+          report = block.text; // Keep latest text as the report
+        }
+
+        // Log tool calls
+        const toolCalls = message.message.content.filter(
+          (c: any) => c.type === "tool_use"
+        );
+        for (const tool of toolCalls) {
+          console.error(`[QA Server] Tool call: ${tool.name}`);
+        }
+      }
+
+      if (message.type === "result") {
+        totalCost = message.total_cost_usd;
+        console.error(`[QA Server] Completed. Cost: $${totalCost.toFixed(4)}`);
+      }
+    }
+
+    // Return the QA report
+    return {
+      content: [
+        {
+          type: "text",
+          text: report || "No report generated. The agent may have encountered an issue.",
+        },
+      ],
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error(`[QA Server] Error: ${errorMessage}`);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `QA inspection failed: ${errorMessage}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[QA Server] Started and ready for connections");
+}
+
+main().catch((error) => {
+  console.error("[QA Server] Fatal error:", error);
+  process.exit(1);
+});

package/src/mcp-servers/qa-server/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/src/scripts/statusline.js

@@ -8,94 +8,14 @@
  * - Line 1: Git branch + status
  * - Line 2: Context window usage bar with percentage and tokens
  *
- * Input: JSON on stdin with transcript_path
+ * Input: JSON on stdin with context_window data
  * Output: Formatted status to stdout
  */
 
-const { existsSync, readFileSync, readdirSync, statSync } = require('fs');
+const { readFileSync, readdirSync, statSync } = require('fs');
 const { join, basename } = require('path');
 const { execSync } = require('child_process');
 
-/**
- * Get model token limit based on model ID
- */
-function getModelTokenLimit(modelId) {
-  // Claude model context windows
-  if (modelId.includes('claude-3-5-sonnet') || modelId.includes('claude-sonnet-4')) {
-    return 200000;
-  }
-  if (modelId.includes('claude-3-opus')) {
-    return 200000;
-  }
-  if (modelId.includes('claude-3-haiku')) {
-    return 200000;
-  }
-  // Default fallback
-  return 200000;
-}
-
-/**
- * Calculate context window usage from transcript
- * Uses MOST RECENT message only (each message already reports full context)
- */
-function calculateTokenUsage(transcriptPath) {
-  try {
-    if (!existsSync(transcriptPath)) {
-      return null;
-    }
-
-    const content = readFileSync(transcriptPath, 'utf-8');
-    const lines = content.trim().split('\n');
-
-    // Parse all messages
-    const messages = [];
-    for (const line of lines) {
-      if (!line.trim()) continue;
-      try {
-        messages.push(JSON.parse(line));
-      } catch {
-        continue;
-      }
-    }
-
-    // Find most recent main-chain message with usage data
-    const mainChainMessages = messages.filter((m) => m.isSidechain === false);
-    if (mainChainMessages.length === 0) {
-      return null;
-    }
-
-    // Sort by timestamp descending (most recent first)
-    mainChainMessages.sort(
-      (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
-    );
-
-    // Find first message with usage data
-    let contextLength = 0;
-    let modelId = '';
-
-    for (const msg of mainChainMessages) {
-      if (msg.message?.usage) {
-        const usage = msg.message.usage;
-        // Context = input + cache_read + cache_creation
-        // (each message already reports FULL context at that point)
-        contextLength =
-          (usage.input_tokens || 0) +
-          (usage.cache_read_input_tokens || 0) +
-          (usage.cache_creation_input_tokens || 0);
-        modelId = msg.message.model || '';
-        break; // Stop after most recent usage!
-      }
-    }
-
-    const limit = getModelTokenLimit(modelId);
-    const percentage = Math.min(100, Math.round((contextLength / limit) * 100));
-
-    return { used: contextLength, limit, percentage };
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Format number as K (e.g., 84000 -> "084K")
  */
@@ -269,10 +189,20 @@ function main() {
     const DIM_GREY = '\x1b[38;5;245m';
     const RESET = '\x1b[0m';
 
-    // Get token usage from transcript (use transcript_path directly from input)
+    // Get token usage from context_window (available in Claude Code v2.0.70+)
     let tokenData = null;
-    if (data.transcript_path) {
-      tokenData = calculateTokenUsage(data.transcript_path);
+    if (data.context_window?.current_usage) {
+      const usage = data.context_window.current_usage;
+      const used =
+        (usage.input_tokens || 0) +
+        (usage.cache_read_input_tokens || 0) +
+        (usage.cache_creation_input_tokens || 0);
+      const limit = data.context_window.context_window_size || 200000;
+      tokenData = {
+        used,
+        limit,
+        percentage: Math.min(100, Math.round((used / limit) * 100)),
+      };
     }
 
     // Generate context display

package/src/skills/create-agent-skills/references/principles.md

@@ -81,6 +81,27 @@ After writing SKILL.md, ask: **"If Claude reads this right now, does it know wha
 
 If the answer is "it would understand what the skill is about" but not "it would know what to do," rewrite it.
 
+### Agent Prompts Are Different
+
+The red flags above apply to SKILL.md files, not agent prompts. Agent prompts and skills have different characteristics:
+
+| Aspect | Agent Prompt | SKILL.md |
+|--------|--------------|----------|
+| When read | Once per spawn | Repeatedly during session |
+| Purpose | Provide context for focused task | Route to workflows |
+| WHY/WHO/SUCCESS | Appropriate—crucial context | Red flag—wastes tokens |
+| Lifespan | Single invocation | Entire user session |
+
+Agent prompts benefit from a Purpose section with WHY/WHO/SUCCESS because:
+- Agents spawn for a single focused task and need full context upfront
+- The context is read once, not repeatedly
+- Understanding purpose helps agents make better decisions
+
+Skills should route to actions immediately because:
+- Users interact with skills throughout a session
+- Meta-descriptions consume tokens on every activation
+- Instructions are more valuable than context in repeated interactions
+
 ## Progressive Disclosure
 
 ### The Problem Without It

package/src/skills/orchestration/scripts/plan-status.js

@@ -129,6 +129,11 @@ function getPlanInfo(planDir, slug) {
     const taskCounts = countTasks(manifest);
     if (taskCounts) {
       planInfo.tasks = taskCounts;
+
+      // Derive completion status: if all tasks are completed, the plan is completed
+      if (taskCounts.total > 0 && taskCounts.completed === taskCounts.total) {
+        planInfo.status = 'completed';
+      }
     }
   }