@taktdev/coda 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import type { TasksResponse, TaskResponse, CommentsResponse, ProjectsResponse } from './types.js';
+export declare class BugherdClient {
+    private baseUrl;
+    private authHeader;
+    private defaultProjectId?;
+    private userEmail?;
+    constructor(apiKey: string, defaultProjectId?: string, userEmail?: string);
+    private request;
+    private projectPath;
+    listTasks(params: {
+        projectId?: string;
+        status?: string;
+        page?: number;
+    }): Promise<TasksResponse>;
+    getTask(taskId: number, projectId?: string): Promise<TaskResponse>;
+    getComments(taskId: number, projectId?: string): Promise<CommentsResponse>;
+    updateTask(taskId: number, data: Record<string, unknown>, projectId?: string): Promise<TaskResponse>;
+    addComment(taskId: number, text: string, projectId?: string): Promise<void>;
+    listProjects(): Promise<ProjectsResponse>;
+}

package/dist/client.js

@@ -0,0 +1,66 @@
+export class BugherdClient {
+    baseUrl = 'https://www.bugherd.com/api_v2';
+    authHeader;
+    defaultProjectId;
+    userEmail;
+    constructor(apiKey, defaultProjectId, userEmail) {
+        this.authHeader = `Basic ${Buffer.from(`${apiKey}:x`).toString('base64')}`;
+        this.defaultProjectId = defaultProjectId;
+        this.userEmail = userEmail;
+    }
+    async request(path, options) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            ...options,
+            headers: {
+                'Authorization': this.authHeader,
+                'Content-Type': 'application/json',
+                ...options?.headers,
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Bugherd API ${response.status}: ${body}`);
+        }
+        return response.json();
+    }
+    projectPath(projectId) {
+        const id = projectId ?? this.defaultProjectId;
+        if (!id)
+            throw new Error('No project_id provided and BUGHERD_PROJECT_ID not set');
+        return `/projects/${id}`;
+    }
+    async listTasks(params) {
+        const query = new URLSearchParams();
+        if (params.status)
+            query.set('status', params.status);
+        if (params.page)
+            query.set('page', String(params.page));
+        const qs = query.toString();
+        return this.request(`${this.projectPath(params.projectId)}/tasks${qs ? `?${qs}` : ''}`);
+    }
+    async getTask(taskId, projectId) {
+        return this.request(`${this.projectPath(projectId)}/tasks/${taskId}`);
+    }
+    async getComments(taskId, projectId) {
+        return this.request(`${this.projectPath(projectId)}/tasks/${taskId}/comments`);
+    }
+    async updateTask(taskId, data, projectId) {
+        const task = this.userEmail ? { ...data, updater_email: this.userEmail } : data;
+        return this.request(`${this.projectPath(projectId)}/tasks/${taskId}`, {
+            method: 'PUT',
+            body: JSON.stringify({ task }),
+        });
+    }
+    async addComment(taskId, text, projectId) {
+        const comment = { text };
+        if (this.userEmail)
+            comment.email = this.userEmail;
+        await this.request(`${this.projectPath(projectId)}/tasks/${taskId}/comments`, {
+            method: 'POST',
+            body: JSON.stringify({ comment }),
+        });
+    }
+    async listProjects() {
+        return this.request('/projects');
+    }
+}

package/dist/formatters.d.ts

@@ -0,0 +1,5 @@
+import type { BugherdTask, BugherdComment, BugherdProject, BugherdMeta } from './types.js';
+export declare function formatTask(task: BugherdTask): string;
+export declare function formatTaskList(tasks: BugherdTask[], meta: BugherdMeta): string;
+export declare function formatComments(comments: BugherdComment[]): string;
+export declare function formatProjects(projects: BugherdProject[]): string;

package/dist/formatters.js

@@ -0,0 +1,60 @@
+export function formatTask(task) {
+    const lines = [
+        `# BH-${task.local_task_id}: Task #${task.id}`,
+        '',
+        `- **Status:** ${task.status}`,
+        `- **Priority:** ${task.priority}`,
+        `- **Admin link:** ${task.admin_link}`,
+    ];
+    if (task.url) {
+        lines.push(`- **Page URL:** ${task.url}`);
+    }
+    if (task.screenshot_url) {
+        lines.push(`- **Screenshot:** ${task.screenshot_url}`);
+    }
+    if (task.tag_names.length > 0) {
+        lines.push(`- **Tags:** ${task.tag_names.join(', ')}`);
+    }
+    if (task.assigned_to_id) {
+        lines.push(`- **Assigned to:** user #${task.assigned_to_id}`);
+    }
+    lines.push('', '## Description', '', task.description || '_No description_');
+    return lines.join('\n');
+}
+export function formatTaskList(tasks, meta) {
+    if (tasks.length === 0)
+        return '_No tasks found._';
+    const lines = [
+        `**${meta.total_count} tasks** (page ${meta.current_page}/${meta.total_pages})`,
+        '',
+        '| # | ID | Priority | Description |',
+        '|---|-----|----------|-------------|',
+    ];
+    for (const task of tasks) {
+        const desc = task.description
+            ? task.description.slice(0, 80).replace(/\n/g, ' ') + (task.description.length > 80 ? '...' : '')
+            : '_No description_';
+        lines.push(`| BH-${task.local_task_id} | ${task.id} | ${task.priority} | ${desc} |`);
+    }
+    return lines.join('\n');
+}
+export function formatComments(comments) {
+    if (comments.length === 0)
+        return '_No comments._';
+    return comments.map(c => {
+        const date = new Date(c.created_at).toLocaleDateString();
+        return `**User #${c.user_id}** (${date}):\n${c.text}`;
+    }).join('\n\n---\n\n');
+}
+export function formatProjects(projects) {
+    if (projects.length === 0)
+        return '_No projects found._';
+    const lines = [
+        '| ID | Name | URL | Active |',
+        '|----|------|-----|--------|',
+    ];
+    for (const p of projects) {
+        lines.push(`| ${p.id} | ${p.name} | ${p.devurl || '_none_'} | ${p.is_active ? 'Yes' : 'No'} |`);
+    }
+    return lines.join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import 'dotenv/config';

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { BugherdClient } from './client.js';
+import { registerListTasks } from './tools/list-tasks.js';
+import { registerGetTask } from './tools/get-task.js';
+import { registerUpdateTask } from './tools/update-task.js';
+import { registerAddComment } from './tools/add-comment.js';
+import { registerListProjects } from './tools/list-projects.js';
+const apiKey = process.env.BUGHERD_API_KEY;
+if (!apiKey) {
+    console.error('BUGHERD_API_KEY environment variable is required');
+    process.exit(1);
+}
+const projectId = process.env.BUGHERD_PROJECT_ID;
+const userEmail = process.env.BUGHERD_USER_EMAIL;
+const client = new BugherdClient(apiKey, projectId, userEmail);
+const server = new McpServer({
+    name: 'bugherd',
+    version: '0.1.0',
+});
+registerListTasks(server, client);
+registerGetTask(server, client);
+registerUpdateTask(server, client);
+registerAddComment(server, client);
+registerListProjects(server, client);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/add-comment.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BugherdClient } from '../client.js';
+export declare function registerAddComment(server: McpServer, client: BugherdClient): void;

package/dist/tools/add-comment.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export function registerAddComment(server, client) {
+    server.tool('add_comment', 'Add a comment to a Bugherd task.', {
+        task_id: z.number().int().positive().describe('The task ID'),
+        text: z.string().describe('Comment text'),
+        project_id: z.string().optional().describe('Bugherd project ID (uses default if omitted)'),
+    }, async ({ task_id, text, project_id }) => {
+        await client.addComment(task_id, text, project_id);
+        return { content: [{ type: 'text', text: `Comment added to task #${task_id}.` }] };
+    });
+}

package/dist/tools/get-task.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BugherdClient } from '../client.js';
+export declare function registerGetTask(server: McpServer, client: BugherdClient): void;

package/dist/tools/get-task.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { formatTask, formatComments } from '../formatters.js';
+export function registerGetTask(server, client) {
+    server.tool('get_task', 'Get a Bugherd task with full details and comments.', {
+        task_id: z.number().int().positive().describe('The task ID'),
+        project_id: z.string().optional().describe('Bugherd project ID (uses default if omitted)'),
+    }, async ({ task_id, project_id }) => {
+        const [taskResult, commentsResult] = await Promise.all([
+            client.getTask(task_id, project_id),
+            client.getComments(task_id, project_id),
+        ]);
+        const text = [
+            formatTask(taskResult.task),
+            '',
+            '## Comments',
+            '',
+            formatComments(commentsResult.comments),
+        ].join('\n');
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/list-projects.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BugherdClient } from '../client.js';
+export declare function registerListProjects(server: McpServer, client: BugherdClient): void;

package/dist/tools/list-projects.js

@@ -0,0 +1,7 @@
+import { formatProjects } from '../formatters.js';
+export function registerListProjects(server, client) {
+    server.tool('list_projects', 'List all Bugherd projects accessible with the current API key.', {}, async () => {
+        const result = await client.listProjects();
+        return { content: [{ type: 'text', text: formatProjects(result.projects) }] };
+    });
+}

package/dist/tools/list-tasks.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BugherdClient } from '../client.js';
+export declare function registerListTasks(server: McpServer, client: BugherdClient): void;

package/dist/tools/list-tasks.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { formatTaskList } from '../formatters.js';
+export function registerListTasks(server, client) {
+    server.tool('list_tasks', 'List Bugherd tasks filtered by status. Defaults to "development" column.', {
+        project_id: z.string().optional().describe('Bugherd project ID (uses default if omitted)'),
+        status: z.string().default('development').describe('Task status filter: backlog, todo, doing, done, closed, or custom status name'),
+        page: z.number().int().positive().default(1).describe('Page number for pagination'),
+    }, async ({ project_id, status, page }) => {
+        const result = await client.listTasks({ projectId: project_id, status, page });
+        return { content: [{ type: 'text', text: formatTaskList(result.tasks, result.meta) }] };
+    });
+}

package/dist/tools/update-task.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BugherdClient } from '../client.js';
+export declare function registerUpdateTask(server: McpServer, client: BugherdClient): void;

package/dist/tools/update-task.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { formatTask } from '../formatters.js';
+export function registerUpdateTask(server, client) {
+    server.tool('update_task', 'Update a Bugherd task (status, priority, or assignment).', {
+        task_id: z.number().int().positive().describe('The task ID'),
+        project_id: z.string().optional().describe('Bugherd project ID (uses default if omitted)'),
+        status: z.string().optional().describe('New status'),
+        priority: z.string().optional().describe('New priority: critical, important, normal, minor'),
+        assigned_to_id: z.number().int().optional().describe('User ID to assign to'),
+    }, async ({ task_id, project_id, status, priority, assigned_to_id }) => {
+        const data = {};
+        if (status !== undefined)
+            data.status = status;
+        if (priority !== undefined)
+            data.priority = priority;
+        if (assigned_to_id !== undefined)
+            data.assigned_to_id = assigned_to_id;
+        if (Object.keys(data).length === 0) {
+            return { content: [{ type: 'text', text: 'Error: At least one field (status, priority, assigned_to_id) must be provided.' }] };
+        }
+        const result = await client.updateTask(task_id, data, project_id);
+        return { content: [{ type: 'text', text: `Task updated.\n\n${formatTask(result.task)}` }] };
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+export interface BugherdTask {
+    id: number;
+    local_task_id: number;
+    status: string;
+    priority: string;
+    description: string;
+    tag_names: string[];
+    external_id: string | null;
+    requester_id: number;
+    assigned_to_id: number | null;
+    created_at: string;
+    updated_at: string;
+    admin_link: string;
+    screenshot_url: string | null;
+    url: string | null;
+}
+export interface BugherdComment {
+    id: number;
+    user_id: number;
+    text: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface BugherdProject {
+    id: number;
+    name: string;
+    devurl: string;
+    is_active: boolean;
+    is_public: boolean;
+    members: {
+        id: number;
+        display_name: string;
+        email: string;
+        avatar_url: string;
+    }[];
+}
+export interface BugherdMeta {
+    count: number;
+    total_count: number;
+    total_pages: number;
+    current_page: number;
+}
+export interface TasksResponse {
+    tasks: BugherdTask[];
+    meta: BugherdMeta;
+}
+export interface TaskResponse {
+    task: BugherdTask;
+}
+export interface CommentsResponse {
+    comments: BugherdComment[];
+}
+export interface ProjectsResponse {
+    projects: BugherdProject[];
+}
+export interface ProjectResponse {
+    project: BugherdProject;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@taktdev/coda",
+  "version": "1.0.0",
+  "description": "Bugherd QA automation MCP server",
+  "type": "module",
+  "bin": {
+    "coda": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "skills",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "postinstall": "node scripts/postinstall.js",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": {
+    "name": "Takt",
+    "email": "developers@takt.inc",
+    "url": "https://takt.inc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "dotenv": "^17.3.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import { cpSync, mkdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = process.env.INIT_CWD;
+
+if (!projectRoot) {
+  process.exit(0);
+}
+
+// --- Skills ---
+
+const skillsSource = join(__dirname, '..', 'skills');
+const skillsDest = join(projectRoot, '.claude', 'skills');
+
+const skills = ['qa-remediate', 'qa-resume', 'qa-approve'];
+
+for (const skill of skills) {
+  const src = join(skillsSource, skill);
+  const dest = join(skillsDest, skill);
+
+  if (!existsSync(src)) continue;
+
+  mkdirSync(dest, { recursive: true });
+  cpSync(src, dest, { recursive: true, force: true });
+}
+
+console.log('@taktdev/coda: installed skills → .claude/skills/qa-{remediate,resume,approve}');
+
+// --- MCP config ---
+
+const mcpPath = join(projectRoot, '.mcp.json');
+const bugherdServer = {
+  command: 'npx',
+  args: ['-y', '@taktdev/coda'],
+};
+
+if (!existsSync(mcpPath)) {
+  writeFileSync(mcpPath, JSON.stringify({ mcpServers: { bugherd: bugherdServer } }, null, 2) + '\n');
+  console.log('@taktdev/coda: created .mcp.json with bugherd server');
+} else {
+  const config = JSON.parse(readFileSync(mcpPath, 'utf-8'));
+  if (!config.mcpServers?.bugherd) {
+    config.mcpServers = config.mcpServers || {};
+    config.mcpServers.bugherd = bugherdServer;
+    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n');
+    console.log('@taktdev/coda: added bugherd server to existing .mcp.json');
+  }
+}

package/skills/qa-approve/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: qa-approve
+description: "Commit and tag fixes for Bugherd tickets. Triggers Ready for Review in Bugherd."
+argument-hint: "<ticket-id> [ticket-id...]"
+user-invocable: true
+---
+
+# /qa-approve
+
+Merge fix branches into main/current branch with tagged commits that trigger Bugherd's GitHub integration, then shut down the responsible agent to free a team slot.
+
+## Usage
+
+```
+/qa-approve 42
+/qa-approve 42 43 44
+/qa-approve all
+```
+
+## Argument Parsing
+
+- **Single ticket:** `/qa-approve 42`
+- **Multiple tickets:** `/qa-approve 42 43 44`
+- **All pending:** `/qa-approve all` — finds all `.takty/qa/BH-*.md` files that have NOT been renamed to `-fixed` (i.e., excludes `BH-*-fixed.md`)
+
+## Flow
+
+For each ticket:
+
+### 1. Read Remediation File
+
+Read `.takty/qa/BH-{id}.md` to get:
+- The branch name (from the "Worktree" section)
+- The short description (from the `# BH-{id}: {title}` heading)
+- The list of changes made
+- The **agent name** (from the "Agent" section)
+
+### 2. Verify Branch Exists
+
+Check that the branch exists:
+
+```bash
+git branch --list {branch-name}
+```
+
+If the branch doesn't exist, report which tickets couldn't be found and skip them. Continue with remaining tickets.
+
+### 3. Merge the Branch
+
+Merge the ticket's branch into the current branch (usually `main`):
+
+```bash
+git merge {branch-name} --no-ff -m "{short description} [Ready for Review BH-{id}]"
+```
+
+This creates a merge commit with the Bugherd tag in a single step.
+
+If there are merge conflicts:
+- For simple conflicts (whitespace, non-overlapping changes): resolve automatically
+- For complex conflicts: ask the user to resolve manually
+
+### 4. Verify Tagged Commit
+
+Confirm the merge commit was created with the correct tag format:
+
+```bash
+git log -1 --oneline
+```
+
+**Tag format rules:**
+- The Bugherd tag **must be in the commit subject line** (first line), not in the body/description
+- Do NOT add a `Co-Authored-By` line — it can interfere with the tag parsing
+- **Case-sensitive** — must be `Ready for Review` (capital R on Review), not `Ready for review`
+- Multiple tickets in one commit: `{short description} [Ready for Review BH-1,2,3]`
+
+### 5. Mark Remediation File as Fixed
+
+Rename the remediation file to append `-fixed`:
+
+```bash
+mv .takty/qa/BH-{id}.md .takty/qa/BH-{id}-fixed.md
+```
+
+### 6. Shut Down the Agent
+
+If the remediation file has an **Agent** name and that agent is still part of the team:
+
+```
+SendMessage type: "shutdown_request" to the agent
+```
+
+This frees a team slot. If more tickets are waiting in the Bugherd development column, the team lead can spawn a new agent.
+
+### 7. Report Result
+
+Report for each ticket:
+- Commit hash
+- Branch merged
+- Agent shut down (or already idle/gone)
+- Remaining team slots available (out of 10)
+
+## Important Notes
+
+- **One merge commit per ticket** so each ticket moves independently in Bugherd's GitHub integration
+- **Do NOT push** after merging. Report the commits created and tell the user to push when ready.
+- Process tickets sequentially to avoid merge conflicts between branches
+- If using `/qa-approve all`, first list which tickets will be approved and their descriptions before proceeding
+- The commit message format `{description} [Ready for Review BH-{id}]` is required by Bugherd's GitHub integration — tag must be in the subject line, case-sensitive
+- **Do NOT delete the team** after approving. The team persists until the user explicitly requests cleanup. Other agents may still be working or idle.
+- After shutting down an agent, check if there are unassigned tickets that could fill the freed slot

package/skills/qa-remediate/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: qa-remediate
+description: "Fetch Bugherd tickets and fix bugs. Spawns parallel agents for batch mode."
+argument-hint: "[ticket-id] [context/hints]"
+user-invocable: true
+---
+
+# /qa-remediate
+
+Fetch Bugherd tickets, group by similarity, and spawn team members to fix them. Up to 10 agents work in parallel, each on its own branch.
+
+## Usage
+
+```
+/qa-remediate
+/qa-remediate 42
+/qa-remediate 42 The button is misaligned on mobile
+```
+
+## Argument Parsing
+
+- **No arguments** → Batch mode: fetch all tickets from the "development" column
+- **Number only** → Single ticket mode: spawn one agent for that ticket
+- **Number + text** → Single ticket mode with context hints to guide the fix
+
+## Team Lead Role
+
+The team lead (you, the main session) is **only** responsible for:
+
+1. **Fetching** tickets from Bugherd
+2. **Grouping** tickets by similarity
+3. **Spawning and assigning** team members
+4. **Relaying** agent reports and status to the user
+5. **Managing slots** — spawn new agents as slots free up (max 10 concurrent)
+
+The team lead does NOT fix tickets itself. All remediation work is done by spawned agents.
+
+## Batch Mode Flow
+
+1. Call `list_tasks` MCP tool with `status="development"` to get tickets in the development column. **Only take the first 10 tickets** to avoid overloading context. If more exist, note the count and fetch the next batch after the current tickets are processed.
+2. Create a team: `TeamCreate` with name `qa-remediate` (if not already active)
+3. **Group tickets by similarity:**
+   - Same block/module/component
+   - Similar issue type across different components (e.g., "arrow icon wrong" on multiple blocks)
+   - Related CSS/styling changes
+   - Present the grouping to the user before spawning agents
+4. Create a `TaskCreate` for each ticket
+5. Spawn up to 10 remediator agents. Each agent MUST use:
+   - `isolation: "worktree"` — each agent works in its own isolated worktree
+   - `model: "opus"` — Opus 4.6 for complex reasoning
+   - `subagent_type: "general-purpose"`
+   - `team_name: "qa-remediate"`
+   - `name:` a descriptive name based on the ticket group (e.g., `remediator-hero`, `remediator-arrows`)
+   - Grouped tickets can go to the same agent if closely related
+6. Each remediator agent follows the **Remediator Steps** below
+7. As agents finish and report back, relay their summaries to the user
+8. **Do NOT shut down the team or agents.** Agents wait idle until the user reviews and approves via `/qa-approve`.
+
+## Single Ticket Mode Flow
+
+Same as batch but for one ticket. Still spawns an agent — the team lead does not fix it directly.
+
+1. Create a team: `TeamCreate` with name `qa-remediate` (if not already active)
+2. Create a `TaskCreate` for the ticket
+3. Spawn one remediator agent (same settings as batch mode)
+4. Agent follows the **Remediator Steps** below
+5. Relay the agent's report to the user when done
+
+## Slot Management
+
+- Maximum 10 concurrent team members
+- When a ticket is approved via `/qa-approve`, that agent is shut down, freeing a slot
+- If more tickets remain in the current batch, the team lead can spawn a new agent for the next ticket
+- When all tickets from the current batch are assigned or completed, fetch the next 10 from Bugherd via `list_tasks`
+- Check `TaskList` and team config to track active vs idle agents
+
+## Remediator Steps
+
+For each ticket:
+
+### 1. Gather Context
+- Call `get_task` MCP tool with the ticket ID to get full ticket details and comments
+- If a screenshot URL is present, call `WebFetch` on it to view the screenshot
+- Note the priority, description, and any comments from the team
+
+### 2. Find Relevant Code
+- Use `Grep`, `Glob`, and `Read` to search the codebase for relevant code
+- Look at block templates, Blade views, CSS, and JS files related to the reported issue
+- Read the files to understand the current implementation
+
+### 3. Assess Risk
+
+Categorize the fix as **safe** or **risky**:
+
+| Safe (implement directly) | Risky (flag for manual review) |
+|---|---|
+| CSS/Tailwind class changes | PHP logic changes |
+| Copy/text updates | JavaScript state management |
+| Template markup adjustments | Data model / attribute changes |
+| Spacing, colors, typography | Database queries or post meta |
+| Visibility/responsive tweaks | Authentication / permissions |
+| Changes scoped to a single block | **Changes to shared components** (`block-wrapper`, `block-header`, `button`, `eyebrow`) — these affect every block that uses them |
+
+### 4. Implement or Flag
+
+**Safe fixes:** Implement the fix directly in the worktree.
+
+**Risky fixes:** Do NOT implement. Instead:
+- Document the recommended fix in the remediation file
+- Explain why it's flagged in the Analysis section
+- Mark the status as "Flagged for manual review"
+
+### 5. Create Test Page
+
+Always attempt to create a draft page for QA verification. If `ddev exec` fails, note the command in the remediation file so it can be run later.
+
+```bash
+ddev exec wp post create --post_type=page --post_title="QA: BH-{id}" --post_status=draft
+```
+
+When the test page needs block content, assign the block markup to a shell variable first to avoid escaping issues with `!` in `<!-- wp:` markup:
+
+```bash
+CONTENT='<!-- wp:paragraph --><p>Test content for BH-{id}</p><!-- /wp:paragraph -->'
+ddev exec wp post create --post_type=page --post_title="QA: BH-{id}" --post_status=draft --post_content="$CONTENT"
+```
+
+### 6. Write Remediation File
+
+Create `.takty/qa/BH-{id}.md` using this template:
+
+```markdown
+# BH-{id}: {title/short description}
+
+## Ticket
+- **Bugherd ID:** {id}
+- **Priority:** {priority}
+- **Admin link:** {admin_link}
+- **Screenshot:** {screenshot_url}
+
+## Agent
+- **Name:** {agent name, e.g. remediator-hero}
+- **Group:** {ticket group description, e.g. "Hero block styling"}
+
+## Description
+{from Bugherd}
+
+## Analysis
+{root cause, affected files}
+
+## Changes Made
+| File | Change |
+|------|--------|
+| `path/to/file.php` | Fixed XYZ |
+
+## Test Page
+- **URL:** {site_url}/qa-bh-{id}/
+- **What to verify:** {instructions}
+
+## Worktree
+- **Branch:** {branch name from worktree}
+- **Path:** {worktree path}
+
+## Status
+- [x] Analyzed
+- [x] Fixed
+- [ ] Approved
+```
+
+For risky/flagged tickets, replace "Fixed" with "Flagged for manual review" and explain why in the Analysis section.
+
+### 7. Commit Changes
+
+Create a branch and commit all changes:
+
+```bash
+git checkout -b qa/bh-{id}
+git add -A
+git commit -m "fix: BH-{id} {short description}"
+```
+
+**Do NOT add a `Co-Authored-By` line.** Commits from QA workflows must not include co-author trailers.
+
+### 8. Report and Wait
+
+After committing:
+1. Send a message to the team lead with a summary (ticket ID, what was fixed, branch name, any concerns)
+2. Mark the task as completed
+3. **Wait idle** — do NOT shut down. The user will review the report and either approve or request changes via `/qa-resume`.
+
+## Code Style Rules
+
+When writing fixes, follow these project conventions:
+
+- **Tailwind over custom CSS** — use utility classes, not BEM-style class names or `style.css` files (unless the rule truly can't be expressed in Tailwind)
+- **Tailwind scale over arbitrary values** — use the nearest scale value (`pr-16`, `gap-4`, `mt-6`) instead of arbitrary pixel values (`pr-[68px]`, `gap-[14px]`). Pixel-perfect fidelity is not required; round to the closest Tailwind step.
+- **`cn()` takes a single object** — `cn({ 'base': true, 'conditional': flag })`, NOT `cn('base', { 'conditional': flag })`
+- **Blade: use `@class` directive** for conditional classes and `$attributes->class()` for mergeable component classes
+- **Use existing components** — check for shared Blade components (`x-button`, `x-block-header`, `x-eyebrow`) and editor components (`BlockHeader`, `BlockWrapper`) before building inline
+
+For the full checklist, see `.takty/code-standards-checklist.md`.
+
+## Important Notes
+
+- The `.takty/qa/` directory is gitignored — remediation files are local working docs only, they do not get committed
+- ALWAYS use `isolation: "worktree"` when spawning remediator agents via the Task tool. Each agent's worktree gets its own branch automatically.
+- Remediator agents MUST commit their changes before reporting back
+- For risky fixes: still create the `.takty/qa/BH-{id}.md` file but mark it as "Flagged for manual review"
+- When creating test pages with `wp post create`, assign block content to a shell variable first to avoid escaping issues with `!` in `<!-- wp:` markup
+- **Do NOT delete the team** until the user explicitly tells you to. The team persists across `/qa-approve` and `/qa-resume` calls.
+- Each remediation file MUST include the **Agent** section with the team member's name so `/qa-resume` can delegate back to it

package/skills/qa-resume/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: qa-resume
+description: "Resume work on a Bugherd ticket from where it left off."
+argument-hint: "<ticket-number> [context/hints]"
+user-invocable: true
+---
+
+# /qa-resume
+
+Resume work on a Bugherd ticket by delegating to the original idle agent, or falling back to a new agent if the original is unavailable.
+
+## Usage
+
+```
+/qa-resume 42
+/qa-resume 42 The hover state still looks wrong on mobile
+```
+
+A ticket number is **required**. Error if missing.
+
+## Flow
+
+### 1. Parse Argument
+
+Extract the ticket number and any additional context/hints from the argument. If no number is provided, display an error:
+
+```
+Error: Ticket number required. Usage: /qa-resume <ticket-number>
+```
+
+### 2. Read Remediation File
+
+Read `.takty/qa/BH-{id}.md` for context:
+- Previous analysis and root cause
+- Changes already made (file paths and descriptions)
+- Branch name and worktree path
+- Current status (what's done, what's pending)
+- **Agent name** (from the "Agent" section)
+
+If the file doesn't exist, report that no previous work was found for this ticket and suggest using `/qa-remediate {id}` instead.
+
+### 3. Fetch Latest Ticket State
+
+Call `get_task` MCP tool with the ticket ID to:
+- Check for new comments since the last session
+- See if priority or status has changed
+- Get any new screenshots or feedback
+
+### 4. Delegate to the Original Agent
+
+If the remediation file has an **Agent** name (e.g., `remediator-hero`):
+
+1. Read the team config at `~/.claude/teams/qa-remediate/config.json` to check if the agent is still a team member
+2. If the agent exists, send it a message via `SendMessage`:
+   - Include the user's context/instructions from the `/qa-resume` arguments
+   - Include any new ticket comments or feedback from step 3
+   - The agent already has the worktree and branch context from its previous work
+3. Relay the agent's response back to the user when it reports back
+
+**The team lead does NOT do the fix itself.** Always delegate.
+
+### 5. Fallback: Spawn a New Agent
+
+If the original agent is not found (shut down, crashed, etc.):
+
+1. Spawn a new remediator agent with the same settings as `/qa-remediate`:
+   - `isolation: "worktree"`
+   - `model: "opus"`
+   - `subagent_type: "general-purpose"`
+   - `team_name: "qa-remediate"`
+   - `name:` reuse the original agent name from the remediation file
+2. Include in the agent prompt:
+   - The full remediation file content (previous analysis, changes, branch)
+   - The latest ticket state and new comments
+   - The user's context/instructions
+   - Instructions to check out the existing branch if it still exists, or start fresh if not
+3. The agent follows the same remediation steps: fix, commit, update remediation file, report back, wait idle
+
+### 6. Update Remediation File
+
+After the agent reports back, ensure the remediation file is updated with:
+- The new agent name (if a fallback agent was spawned)
+- Any new changes in the "Changes Made" table
+- Updated analysis if the approach changed