@jgamaraalv/ts-dev-kit 1.2.0 → 2.0.0

package/skills/task/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: task
+description: "Use this skill when the user wants to implement a new task in the project. Covers feature development, refactoring, bug fixes, and any code change that requires context analysis, role assignment, and structured execution. For changes under ~30 lines in a single file, implement directly without this workflow."
+argument-hint: "[task-description or task-md-file-path]"
+---
+
+<trigger_examples>
+- "Implement the search feature"
+- "Build the user creation flow end-to-end"
+- "Refactor the auth module to use shared schemas"
+- "Add the notifications endpoint to the API"
+- "Fix the pagination bug"
+- "Execute this task"
+</trigger_examples>
+
+<workflow>
+Follow each phase in order. Each one feeds the next.
+
+<phase_1_context_analysis>
+Before writing any code, build a mental model of the task scope.
+
+1. Read the project CLAUDE.md and root package.json — understand the project structure, available commands, and dependency graph.
+2. Search the codebase for existing patterns — use Grep/Glob to find related files, similar implementations, and reusable code.
+3. Identify the affected packages/directories — determine which parts of the project will be touched and in what order.
+</phase_1_context_analysis>
+
+<phase_2_role_assignment>
+Determine the full execution context: role persona, domain area, domain technologies, project context, required skills, and available MCPs.
+
+<domain_areas>
+Map the task to one or more domain areas AND sub-areas. Sub-areas determine the specialist agent type and skill set.
+
+**Backend**
+| Sub-area | Agent type | When | Key skills |
+|----------|-----------|------|------------|
+| Database | `database-expert` | Schema design, migrations, complex queries, indexes | drizzle-pg, postgresql |
+| Endpoints | `api-builder` | Routes, validation, handlers, API contracts | fastify-best-practices |
+| Queues | `general-purpose` | Job processing, workers, schedulers | bullmq, ioredis |
+| Security | `security-scanner` | Auth flows, RBAC, input sanitization | owasp-security-review |
+
+**Frontend**
+| Sub-area | Agent type | When | Key skills |
+|----------|-----------|------|------------|
+| Components | `react-specialist` | Component architecture, hooks, state management, composition | react-best-practices, composition-patterns |
+| Pages/routing | `general-purpose` | Pages, layouts, data fetching, RSC boundaries | nextjs-best-practices |
+| UI/UX | `ux-optimizer` | User flows, form UX, friction reduction | ui-ux-guidelines |
+| Accessibility | `accessibility-pro` | WCAG compliance, keyboard nav, screen readers | — |
+| Performance | `performance-engineer` | Core Web Vitals, bundle size, re-renders | react-best-practices |
+
+**Shared packages** — `typescript-pro` or `general-purpose` (shared types, schemas, utilities)
+
+**Cross-cutting specialists** (use alongside any domain)
+| Agent type | When |
+|-----------|------|
+| `test-generator` | Writing test suites, improving coverage |
+| `debugger` | Investigating errors, stack traces |
+| `docker-expert` | Dockerfiles, compose, container config |
+| `code-reviewer` | Post-implementation review |
+| `playwright-expert` | E2E browser tests |
+
+A single task may require agents from multiple sub-areas. For example, "add a new resource endpoint with list UI" needs `database-expert` (schema) + `api-builder` (route) + `react-specialist` (component).
+</domain_areas>
+
+<domain_technologies>
+Read the relevant package.json to identify installed packages and their versions. Use the actual versions found — do not assume.
+</domain_technologies>
+
+<role_persona>
+Compose a role persona that combines the domain sub-area, project context, technologies, and task nature.
+
+<examples>
+- "You are a database specialist working with [ORM] and [database] on schema design for [brief project description from CLAUDE.md]"
+- "You are a React component architect specialized in composition patterns, hooks, and state management with [React version] and [UI library]"
+- "You are a [framework] API developer building REST endpoints with validation and type-safe request/response contracts"
+- "You are a frontend performance engineer optimizing Core Web Vitals and bundle size for a [framework] application"
+- "You are a queue specialist designing job flows with [queue library] and retry strategies"
+</examples>
+
+Discover the actual technologies and versions from package.json. Describe the project based on CLAUDE.md or README.
+</role_persona>
+
+<required_skills>
+Call the Skill tool for each relevant skill before writing any code or dispatching agents. Skills inject domain-specific rules and best practices.
+
+Identify the required skills from the domain area, then call each one:
+
+```
+Skill(skill: "fastify-best-practices")
+Skill(skill: "drizzle-pg")
+Skill(skill: "postgresql")
+```
+
+<skill_map>
+Match skills to the sub-area identified in domain_areas:
+
+**Backend sub-areas:**
+- Database → /drizzle-pg, /postgresql
+- Endpoints → /fastify-best-practices
+- Queues → /bullmq, /ioredis
+- Security → /owasp-security-review
+
+**Frontend sub-areas:**
+- Components → /react-best-practices, /composition-patterns
+- Pages/routing → /nextjs-best-practices
+- UI/UX → /ui-ux-guidelines
+- Performance → /react-best-practices
+
+**Cross-cutting** → combine skills from each sub-area involved.
+</skill_map>
+
+In SINGLE-ROLE mode: call each skill yourself before starting phase 4.
+In MULTI-ROLE mode: include explicit Skill() call instructions in each subagent prompt (see references/agent-dispatch.md).
+</required_skills>
+
+<available_mcps>
+Identify MCPs that can assist execution:
+- context7 — query up-to-date library documentation (see below)
+- playwright — test frontend in the browser, take screenshots, verify UI
+- chrome-devtools — inspect pages, debug network requests, check console
+- firecrawl — fetch external documentation or references from the web
+
+**Context7 usage**: When the task involves library APIs, version-specific patterns, or unfamiliar method signatures, use Context7 to query current documentation before writing code:
+1. `mcp__context7__resolve-library-id` — resolve the library name (e.g., "fastify", "drizzle-orm", "next", "react", "bullmq") to its Context7 ID.
+2. `mcp__context7__query-docs` — query with the specific API, pattern, or feature you need.
+Check the project's package.json for installed versions first. In MULTI-ROLE mode, include these instructions in each agent prompt so agents can query docs themselves.
+</available_mcps>
+</phase_2_role_assignment>
+
+<phase_2b_multi_role_decomposition>
+When a task spans multiple domains, decompose it into separate roles with isolated execution contexts.
+
+<when_to_decompose>
+Decompose into multiple roles when ANY of these apply:
+1. The task touches 2+ packages or major directories (e.g., shared code + backend + frontend).
+2. The task involves distinct skill sets (e.g., database schema design + frontend UI).
+3. The changes in one domain are large enough to benefit from a focused agent.
+
+Do not decompose if:
+1. The task is small and contained within a single package.
+2. The cross-package changes are trivial (e.g., adding one type to shared and importing it).
+</when_to_decompose>
+
+<decomposition_rules>
+<rule_1_define_roles_independently>
+Each role gets its own persona, skill set, context files, and success criteria.
+
+<example>
+Role A: Database specialist (sub-area: Database). Agent: database-expert. Task: design schema + migration for the new feature. Skills: drizzle-pg, postgresql.
+Role B: API endpoint developer (sub-area: Endpoints). Agent: api-builder. Task: build REST routes consuming the new schema. Skills: fastify-best-practices.
+Role C: Component architect (sub-area: Components). Agent: react-specialist. Task: build the result card and list components. Skills: react-best-practices, composition-patterns.
+Role D: Page builder (sub-area: Pages/routing). Agent: general-purpose (ad-hoc). Task: wire components into the search results page with data fetching. Skills: nextjs-best-practices.
+Role E: TypeScript library developer. Agent: typescript-pro. Task: add shared schemas and types. Skills: none extra.
+</example>
+</rule_1_define_roles_independently>
+
+<rule_2_dispatch_agents>
+For each role, spawn a specialized subagent via the Task tool.
+
+**Selecting the agent type:**
+1. Check if a project agent exists in `.claude/agents/` that matches the sub-area (see domain_areas table above for the mapping).
+2. If a matching agent exists, use its name as `subagent_type` (e.g., `database-expert`, `api-builder`, `react-specialist`).
+3. If no matching agent exists, use `general-purpose` as `subagent_type` and embed the full role definition directly in the prompt — this creates an ad-hoc specialist without needing a .md file.
+
+**Ad-hoc agent creation** — when `subagent_type: "general-purpose"` is used as a specialist surrogate, the prompt must include:
+- **Role persona**: who the agent is and what it specializes in.
+- **Domain expertise**: specific technologies, frameworks, and versions.
+- **Project context**: how this sub-area fits into the project (discover from CLAUDE.md and package.json).
+- **Constraints**: patterns to follow, files to reference, conventions to match.
+- **Skills to load**: explicit `Skill(skill: "...")` calls for domain-specific rules.
+
+<example_adhoc_agent>
+Task(
+  description: "Implement notification worker",
+  subagent_type: "general-purpose",
+  model: "sonnet",
+  prompt: """
+You are a queue specialist working on this project.
+
+Your expertise: Redis-backed job queues, workers, flow producers, retry strategies, rate limiting, and graceful shutdown.
+
+## Before writing any code
+1. Read CLAUDE.md and relevant package.json files to understand the project structure and conventions.
+2. Call the Skill tool to load these domain skills:
+   - Skill(skill: "bullmq")
+   - Skill(skill: "ioredis")
+
+## Your task
+[task details...]
+
+## Project context
+Discover from the codebase:
+- Redis connection configuration (search for Redis imports)
+- Existing queue/worker patterns (search for queue or worker files)
+- Import conventions (check existing code for named vs default imports)
+[...]
+"""
+)
+</example_adhoc_agent>
+
+Each agent prompt must follow the template in references/agent-dispatch.md. The agent must be able to complete its work independently.
+</rule_2_dispatch_agents>
+
+<rule_3_execution_order>
+Decide the execution order based on file conflicts and dependencies:
+- **Parallel**: roles touch independent files with no data dependency → launch multiple Task calls in one message.
+- **Sequential**: one role's output is another's input → await the blocker first.
+- **Worktree isolation**: roles touch overlapping files but are otherwise independent → set `isolation: "worktree"` on the Task tool.
+</rule_3_execution_order>
+
+<rule_4_model_selection>
+Choose the model for each dispatched agent based on task complexity:
+- **haiku**: simple, well-defined tasks — adding a type, writing a small utility, updating config, barrel file exports.
+- **sonnet**: moderate tasks — implementing a feature within a single domain, writing tests, building a component.
+- **opus**: complex tasks — cross-cutting concerns, architectural decisions, novel implementations requiring deep reasoning.
+
+Set the `model` parameter on the Task tool call accordingly.
+</rule_4_model_selection>
+</decomposition_rules>
+
+<dispatch_pattern>
+The main session acts as the orchestrator:
+1. Analyze the task and define roles (this phase).
+2. Create TaskCreate entries for each role to track progress.
+3. Dispatch the first wave of agents (those with no blockers).
+4. When a blocking agent completes, dispatch the next wave.
+5. After all agents complete, run the final quality gates.
+6. Produce the completion report (see references/output-templates.md).
+
+Constraints:
+1. Subagents cannot spawn other subagents. All dispatch happens from the main session.
+2. Each agent prompt must be fully self-contained — do not assume agents have conversation history.
+3. Review each agent's output before dispatching dependents.
+</dispatch_pattern>
+
+<execution_mode_decision>
+At the end of phase 2, make an explicit execution mode decision and state it to the user:
+
+> **EXECUTION MODE: SINGLE-ROLE** — I will implement all changes directly.
+
+OR
+
+> **EXECUTION MODE: MULTI-ROLE** — I will act as orchestrator, dispatching specialized agents via the Task tool.
+
+OR
+
+> **EXECUTION MODE: PLAN** — The task is highly complex. I will enter plan mode to design a structured implementation plan before executing.
+
+Use PLAN mode when:
+- The task has 4+ distinct roles or implementation phases.
+- The scope is large enough that context window management becomes a concern.
+- The task benefits from upfront architectural planning before any code is written.
+
+In PLAN mode: use EnterPlanMode to design the full plan. Once the user approves it, exit plan mode and execute phases sequentially as MULTI-ROLE orchestrator, with context cleanup between major phases when needed.
+
+Follow this decision in phase 4. In MULTI-ROLE and PLAN modes, delegate application code to agents — your job is dispatch, review, integration, and quality gates.
+</execution_mode_decision>
+</phase_2b_multi_role_decomposition>
+
+<phase_3_task_analysis>
+1. Extract task-defined criteria — scan the task document for explicit:
+   - **Success criteria** (checklists, acceptance conditions)
+   - **Initial/baseline tests** (to run BEFORE changes, for comparison)
+   - **Post-change tests** (to run AFTER changes, for verification)
+   - **Performance benchmarks** (bundle size, API call counts, Lighthouse metrics)
+
+   Look for section names like: "Initial Tests", "Before Changes", "Baseline", "Post-Change Tests", "After Changes", "Success Criteria", "Acceptance Criteria", "Functionality Tests", "Performance Tests".
+
+   If found, state them to the user:
+   > **Task-defined criteria found:**
+   > - Success criteria: [list]
+   > - Baseline tests (before changes): [list or "none"]
+   > - Post-change tests (after changes): [list or "none"]
+
+   These are binding requirements that extend the default quality gates. Do not skip them.
+
+2. Understand the request — identify what is being asked, which files will be created or modified, and what the expected outcome is.
+3. Define success criteria — combine the task's own criteria (from step 1) with your analysis. Task-defined criteria take priority over defaults.
+4. For questions about project libraries, use Context7 (`mcp__context7__resolve-library-id` → `mcp__context7__query-docs`) to query up-to-date documentation. If anything is ambiguous, ask the user before proceeding.
+5. Check for helpful MCPs — does the task involve browser testing, external docs?
+6. Plan the implementation order — determine which changes must happen first (e.g., types before lib before hooks before components before pages).
+</phase_3_task_analysis>
+
+<phase_4_execution>
+Before writing any code, check the execution mode decision from phase 2.
+
+**MULTI-ROLE → Follow <multi_role_orchestration> below.**
+**SINGLE-ROLE → Follow <single_role_implementation> below.**
+
+<multi_role_orchestration>
+As orchestrator, dispatch agents, review their output, and verify integration. Do not implement application code yourself.
+
+You may write code directly only for trivial glue (under 15 lines total):
+- Adding an export line to a barrel file
+- Adding a small schema to the shared package that multiple agents need
+- Wiring an import in a top-level file after agents complete
+
+Everything else should be delegated to an agent. For the agent prompt template and dispatch details, see references/agent-dispatch.md.
+
+Dispatch steps:
+1. Create TaskCreate entries for each role.
+2. For each role, dispatch a specialized agent via the Task tool with a self-contained prompt. Set the `model` parameter according to rule_4_model_selection.
+3. Launch independent agents in parallel. Launch dependent agents sequentially.
+4. Each agent runs its own quality gates before reporting completion. Review the agent's output and gate results before dispatching dependents.
+5. After all agents complete, proceed to phase 5 for the final cross-package quality gates.
+
+If you find yourself creating application files (routes, components, services, hooks, tests) while in MULTI-ROLE mode, delegate to an agent instead.
+</multi_role_orchestration>
+
+<single_role_implementation>
+Think through each step before acting. Share your reasoning at key decision points.
+
+<build_order>
+Work from micro to macro — build dependencies before dependents:
+1. Shared code first — new constants, types, schemas, or enums needed by multiple packages go in the shared/common package (discover its location from the project structure).
+2. Check for reuse — before creating a helper, hook, component, or utility, search the codebase for existing code that can be used or extended.
+3. Implement the core change — build the feature/fix in the target package.
+4. Wire it together — connect the pieces across packages if needed.
+
+Decision tree:
+- Is this code used by multiple modules? YES → Create in the shared/common package.
+- Is this code used by multiple modules? NO → Is this component multi-file? YES → Create folder with index.tsx + related files. NO → Single file, co-located with usage.
+</build_order>
+
+If you created any temporary files or scripts for iteration, remove them at the end.
+</single_role_implementation>
+</phase_4_execution>
+
+<phase_5_quality_gates>
+A task is not done until all quality gates pass. Run them in order for every affected package. If any gate fails, fix the issue and re-run all gates from the beginning.
+
+Discover the available commands from package.json scripts for each affected package. Common gates:
+
+1. Type checking — run the project's typecheck command (e.g., `tsc`, `typecheck`)
+2. Linting — run the project's lint command (e.g., `lint`, `eslint`)
+3. Tests (if available) — run the project's test command (e.g., `test`, `vitest`)
+4. Build — run the project's build command (e.g., `build`)
+5. Self-check — review your changes against the success criteria defined in phase 3.
+
+For monorepos, run these for each affected workspace/package. Discover the workspace command pattern from CLAUDE.md or the root package.json (e.g., `yarn workspace <name> <script>`, `pnpm --filter <name> <script>`, `npm -w <name> <script>`, `turbo run <script> --filter=<name>`).
+
+If a gate fails:
+- Read the error output carefully.
+- Fix the root cause (do not suppress or ignore errors).
+- Re-run all gates from step 1, since a fix may introduce new issues.
+- Repeat until all gates pass cleanly.
+</phase_5_quality_gates>
+
+<phase_6_documentation>
+After all quality gates pass, review whether the changes require documentation updates:
+
+- CLAUDE.md — new commands, architecture changes, dependency graph updates, new conventions.
+- Existing docs — new environment variables, setup steps, API contract changes.
+
+Only update documentation directly affected by the changes. Do not create new documentation files unless the changes introduce a new package or major feature with no existing docs.
+</phase_6_documentation>
+</workflow>
+
+<output>
+When complete, produce the completion report. See references/output-templates.md for the exact format.
+
+Do not add explanations, caveats, or follow-up suggestions unless the user explicitly asks. The report is the final output.
+</output>
+
+<task>
+{{task}}
+</task>

package/skills/task/references/agent-dispatch.md

@@ -0,0 +1,156 @@
+# Agent Dispatch Reference
+
+## Agent prompt template
+
+Project agents (`.claude/agents/`) already include project context, workflow, principles, quality gates, and output format in their system prompt. The dispatch prompt only needs **task-specific** information:
+
+```
+## Your task
+[Specific task scope — what to build, what files to create/modify]
+
+## Existing patterns to follow
+[Paste relevant code snippets, file paths, or describe the patterns the agent should match]
+
+## Success criteria
+[What "done" looks like — be specific]
+```
+
+For agents that load skills dynamically (debugger, performance-engineer), also include:
+
+```
+## Skills to load
+Call the Skill tool before starting:
+- Skill(skill: "[skill-1]")
+- Skill(skill: "[skill-2]")
+```
+
+### Preloaded skills by agent
+
+Agents with preloaded skills (via `skills` frontmatter) do NOT need Skill() calls for their primary domain. Only include Skill() calls for additional skills beyond what the agent already has:
+
+| Agent | Preloaded skills | Dynamic skills (add when needed) |
+|-------|-----------------|----------------------------------|
+| api-builder | fastify-best-practices | drizzle-pg, postgresql (if DB-heavy) |
+| react-specialist | react-best-practices, composition-patterns | nextjs-best-practices (if page-level) |
+| database-expert | drizzle-pg, postgresql | — |
+| docker-expert | docker | — |
+| security-scanner | owasp-security-review | — |
+| ux-optimizer | ui-ux-guidelines | — |
+| accessibility-pro | ui-ux-guidelines | — |
+| debugger | (none) | Load based on bug domain |
+| performance-engineer | (none) | Load based on optimization domain |
+| code-reviewer | (none) | Read-only agent, no Write/Edit |
+| test-generator | (none) | fastify-best-practices (for API tests) |
+| typescript-pro | (none) | — |
+| playwright-expert | (none) | — |
+
+### Agent tool restrictions
+
+| Agent | Restriction |
+|-------|------------|
+| code-reviewer | `disallowedTools: Write, Edit` — review only, cannot modify code |
+| All others | Full tool access (inherited from parent) |
+
+Plan accordingly: if a review finds issues, dispatch a separate agent to fix them.
+
+## Model selection
+
+Choose the model for each agent based on task complexity:
+
+| Complexity | Model | Examples |
+|-----------|-------|---------|
+| Simple | `haiku` | Adding a type, writing a small utility, updating config, barrel file exports |
+| Moderate | `sonnet` | Implementing a feature within a single domain, writing tests, building a component |
+| Complex | `opus` | Cross-cutting concerns, architectural decisions, novel implementations requiring deep reasoning |
+
+All agents default to `sonnet`. Override with the Task tool's `model` parameter when needed.
+
+## Dispatch example
+
+```
+Task(
+  description: "Build resource API routes",
+  subagent_type: "api-builder",
+  model: "sonnet",
+  prompt: """
+## Your task
+Create REST endpoints for the [feature name]:
+- POST /api/<resource> — create a new resource
+- GET /api/<resource>/:id — get resource details
+- PATCH /api/<resource>/:id — update resource
+
+## Existing patterns to follow
+Discover from the codebase:
+- Route structure: look for existing route handlers and follow the same pattern
+- Shared schemas: look for existing schema/type definitions in shared packages
+- Use case pattern: look for existing use case or service implementations
+
+## Success criteria
+- All endpoints respond with correct status codes
+- Request/response validated with shared schemas
+- Endpoints follow the project's routing conventions
+"""
+)
+```
+
+## Agent type resolution
+
+Before dispatching, resolve the agent type for each role:
+
+1. **Check `.claude/agents/`** — if a project agent matches the sub-area from the domain mapping (e.g., `database-expert` for DB work, `api-builder` for endpoints, `react-specialist` for components), use it as `subagent_type`.
+2. **Use a built-in agent type** — if the Task tool has a matching built-in type (e.g., `typescript-pro`, `performance-engineer`, `security-scanner`), use it directly.
+3. **Create an ad-hoc specialist** — if no existing agent matches, use `subagent_type: "general-purpose"` and embed the full specialist definition in the prompt.
+
+### Ad-hoc specialist prompt structure
+
+When no matching agent exists, the prompt must be fully self-contained — `general-purpose` has no pre-loaded domain knowledge, project context, or skills:
+
+```
+You are a [specialist title] working on this project.
+
+Your expertise: [specific technologies, frameworks, and techniques].
+
+## Before writing any code
+1. Read CLAUDE.md and relevant package.json files to understand the project structure, conventions, and available commands.
+2. Call the Skill tool to load domain skills:
+   - Skill(skill: "[skill-1]")
+   - Skill(skill: "[skill-2]")
+
+## Project context
+Discover from CLAUDE.md and package.json:
+- Project structure (monorepo layout, key directories, packages)
+- Technologies and versions (frameworks, libraries, language settings)
+- Import conventions (named vs default, module system)
+- Code style (formatter config, linting rules)
+[add more context specific to the task if known]
+
+## Library documentation lookup
+When you need to verify API signatures or version-specific behavior, use Context7:
+1. `mcp__context7__resolve-library-id` — resolve the library name to its ID.
+2. `mcp__context7__query-docs` — query the specific API or pattern.
+
+## Your task
+[task details]
+
+## Existing patterns to follow
+[code snippets or file references]
+
+## Success criteria
+[what "done" looks like]
+
+## Quality gates
+Run the project's type checking, linting, testing, and build commands for every package you touched. Discover available commands from package.json scripts. Fix failures before reporting done.
+
+## Output
+Report when done:
+- Summary: one sentence of what was done.
+- Files: each file created/modified.
+- Quality gates: pass/fail for each.
+```
+
+## Key constraints
+
+1. **Subagents cannot spawn other subagents.** All dispatch happens from the main session.
+2. **Agent prompts should be concise and task-specific.** Project agents already include project context, conventions, principles, and quality gates in their system prompt. Only include information the agent doesn't already have.
+3. **Ad-hoc prompts must be fully self-contained.** The `general-purpose` agent has no project context, so the prompt must include everything: role, project context, conventions, skills to load, quality gates, and output format.
+4. **Review each agent's output before dispatching dependents.** If an agent failed or produced unexpected results, fix the issue before continuing.

package/skills/task/references/output-templates.md

@@ -0,0 +1,53 @@
+# Output Templates
+
+## Role completion report
+
+Each role (whether a dispatched subagent or a single-role execution) produces this report:
+
+```
+Summary: one sentence of what was done.
+Files: list each file path created/modified/deleted.
+Skills loaded: list each Skill() call made during execution.
+MCPs used: list each MCP called, or "none".
+Quality gates: pass/fail for each gate (tsc, lint, test, build).
+```
+
+## Final orchestrator report (MULTI-ROLE only)
+
+When all roles are complete and all quality gates pass:
+
+```
+## Task complete
+
+Summary: one sentence describing the overall outcome.
+
+### Roles executed
+| Role | Sub-area | Agent type | Ad-hoc? | Status | Summary |
+|------|----------|-----------|---------|--------|---------|
+| [role name] | [sub-area] | [subagent_type] | yes/no | pass/fail | [one-line summary] |
+
+### Aggregated files
+List every file created/modified/deleted across all roles.
+
+### Quality gates (final)
+- tsc: pass/fail (per package)
+- lint: pass/fail (per package)
+- test: pass/fail (count)
+- build: pass/fail (per package)
+
+### Task-defined test results
+If the task document defined tests, report results here:
+| Test | Baseline (before) | Result (after) | Delta |
+|------|-------------------|----------------|-------|
+| [test name] | [baseline value] | [post-change value] | [improvement or regression] |
+
+If no task-defined tests existed, omit this section.
+
+### Skills loaded
+List every skill called across all roles.
+
+### MCPs used
+List every MCP called across all roles, or "none".
+```
+
+In SINGLE-ROLE mode, skip the "Roles executed" table — use the role completion report format directly.