Skip to main content

Implement Feature

Coordinate feature implementation as a master coordinator with non-master subagents, page-by-page Playwright coverage, QA, and code review gates. Use when the user asks to implement a feature, execute a spec, build a multi-step change, assign subagents, use worktrees, or run a master checklist. The master coordinates only; implementation code must be written by non-master subagents.

Source: .agents/skills/implement-feature/SKILL.md

Metadata​

  • name: implement-feature

Content​

Implement Feature

Use this skill when a feature needs coordinated implementation across tasks, subagents, worktrees, QA, and code review. This is a master-coordinator workflow. The master agent owns requirements, planning, delegation, subagent management, verification orchestration, integration decisions, and handoff. The master agent does not perform the actual implementation work.

Worker-Only Implementation Rule​

The master agent must not directly edit feature implementation code, even when the user asks to implement the feature. "Multiple agents" means the master coordinator plus at least one separate non-master implementation subagent. QA and code review should also be delegated to separate agents when platform support is available.

If work cannot reasonably be delegated, the master agent must narrow the scope, split the task, create a subagent assignment, or stop and report the blocker. It must not fall back to direct implementation.

Terminology​

In this skill, subagent is the explicit term for the non-master implementation worker, task owner, implementer, or worktree-backed task thread. The master agent plans, assigns, manages, reviews, and coordinates integration of subagent work; subagents perform the actual code or document changes.

Hard Gate​

Do not start coding, spawn implementation subagents, or assign implementation tasks until the master agent has:

  1. Clarified or marked not applicable all required inputs.
  2. Loaded repo rules and relevant feature context.
  3. Classified API/backend dependencies as provided, ui-only, blocked, or not-applicable.
  4. If the task uses Figma, identified the relevant top frame nodes for each design section/state/variant, captured screenshots from those section-level frames, and recorded them as implementation references. Do not screenshot every nested sub-frame inside a section unless it is itself an independent reusable component or the section frame cannot isolate the needed state. If any expected section/state cannot be captured, marked it blocked or asked for the missing node before implementation. Treat all screenshot files as temporary QA artifacts that must be deleted before final completion and must never be pushed.
  5. Resolved/indexed the exact current worktree with codebase-memory MCP and used graph search/traces to identify dependencies, relevant tests, reusable code, and likely file ownership.
  6. Completed a page/file placement and duplication check for new or substantially changed code.
  7. Created a page test inventory that maps every affected page or route to its owner, Playwright spec, planned cases, execution command, and current blocker. Map shared-component changes to the pages through which users exercise them. Use not-applicable only when the feature has no user-facing page impact and record the reason.
  8. Created the master checklist in chat/task tracker.
  9. Created the temporary resumable plan file.
  10. Assigned each implementation task to a specific non-master subagent/thread and worktree.
  11. Confirmed every repo-editing integration task, if any, is assigned to a dedicated non-master integration subagent.
  12. Initialized progress tracking for every task with owner subagent/thread, status, current work, blockers, last update, next action, and verification state.

If any item is missing, stop and complete it before implementation begins.

Required Context​

Load these before task breakdown:

  • AGENTS.md
  • .agents/rules/*.mdc
  • .agents/references/coding-standard/codebase-memory-guidance.md
  • .agents/skills/feature-context/SKILL.md
  • Relevant .agents/references/features/*.md
  • Relevant .agents/references/coding-standard/*.md
  • .agents/skills/code-review/SKILL.md
  • For Figma-driven UI: .agents/skills/figma-spacing/SKILL.md and .agents/skills/implement-design-identical-ui/SKILL.md

Use feature references as context only. Use codebase-memory graph discovery and live code inspection before assigning subagent task scopes.

Flow​

Workflow​

  1. Clarify requirements

    • Follow .agents/references/implementation/requirements-clarification.md.
    • Resolve or index the exact current worktree, then use get_architecture, search_graph, and trace_path to establish feature boundaries, reusable code, dependencies, consumers, and relevant tests before asking discoverable questions.
    • Ask for a Lark channel link when it may contain product, API, QA, or rollout context. If no link is provided, explicitly record it as skipped or not applicable and continue.
    • If API docs are missing, offer a UI-only implementation option before treating the missing API as a blocker.
    • If UI-only is selected, record excluded API work and do not invent API contracts, service methods, response shapes, backend behavior, backend error handling, or end-to-end API tests.
    • Ask blocking questions before checklist creation.
    • Inventory every affected page or route and its acceptance-criteria flows. For each page, record the planned Playwright spec, runnable command, required test cases, data/auth/fixture needs, and blockers. Shared-component work must name the pages that exercise the changed behavior. Use not-applicable only when there is no user-facing page impact, and record why.
    • For Figma-driven UI, enumerate every relevant design section and state before planning: default, empty, loading, error, hover/active/focus, mobile/desktop, modal open/closed, and any variants visible in Figma or the request. Prefer screenshots from the top frame node that represents a whole section/state instead of nested implementation-detail sub-frames. Capture nested sub-frame screenshots only when the sub-frame is the actual reusable component being implemented, the parent frame contains unrelated sections that would confuse QA, or the parent frame cannot expose the needed state. Store the screenshot paths/URLs in the checklist. The implementation target is pixel-equivalent UI, not an approximate interpretation. Screenshot files are temporary references only: do not commit, push, or include them in the PR.

  2. Create the master checklist

    • Follow .agents/references/implementation/master-checklist-template.md.
    • Keep the checklist live in chat/task tracker and mirrored in a temporary repo plan file.
    • Add a progress tracker table with these columns: task ID, task name, assigned subagent/thread, worktree/branch, status, current work, blockers, last update, next action, QA status, review status, Playwright status, and merge/integration status.
    • Use consistent statuses: planned, assigned, in-progress, blocked, qa, review, retrying, passed, merged, skipped.
    • Record whether a Lark channel link was provided, skipped, or not applicable.
    • Record API integration mode and any UI-only exclusions in the dependency section.
    • Add a page test inventory with one entry per affected page or route. Default each new spec to playwright/tests/<page-slug>.spec.ts with one top-level test.describe('<route-or-page>') block. Record the page owner, planned cases, execution command, result, and blocker.
    • Assign each page's Playwright spec to the same subagent that owns that page implementation. Include the spec in the task's write scope and tests/checks. Existing specs do not need retroactive reorganization.
    • For new pages, shared components, services, utilities, or substantial refactors, record the placement decision and duplication search required by .agents/references/coding-standard/page-structure.md.
    • Record the codebase-memory project/root, index status, architecture/search queries, dependency traces, and any justified shell-search fallback in the dependency section.
    • For React component work, record how react-one-fc-per-file.mdc will be satisfied: one top-level React functional component per .tsx file, with additional JSX components extracted into colocated component files unless they fit that rule's documented tiny-helper exceptions.
    • For repeated UI elements, prefer semantic layout primitives such as flex or grid with centered children over per-item absolute coordinates or duplicated hard-coded width/height values. Centralize shared dimensions as named constants when a fixed size is required.
    • For Figma-driven UI, add a design-reference section grouped by product/page section. Each reference must include a clear label, parent section name, Figma top frame node ID, state/variant, viewport/breakpoint, why this screenshot matters, related implementation scope, and visible acceptance criteria. Do not assign implementation until each UI subagent has section-level screenshots and context for its write scope.
    • Track every local screenshot path in the checklist so cleanup can be verified before final summary.

  3. Assign worktrees and subagents

    • Follow .agents/references/implementation/worktree-assignment.md.
    • Implementation task branch names must start with feat/, unless the user provides a different branch naming convention.
    • Prefer Codex subagent/thread/worktree tools when available.
    • Fall back to manual git worktree instructions when tools are unavailable.
    • Assign every implementation task to a non-master subagent. The master agent may write prompts, checklists, and summaries, but must not own a feature-code write scope.
    • After creating each new worktree, copy .env and .env.* files from the source checkout into the new worktree, or record that no env files existed in the source checkout.
    • When splitting work into tasks, every task assignment must explicitly mention creating or using the assigned subagent/thread for that task. Do not leave a split task as an unowned checklist item.
    • If a task is too small for a dedicated subagent, merge it into another delegated subagent task or record why it is only planning/coordination work. Do not keep implementation work with the master agent.
    • Assign write scopes so page-local code, shared components, services, and utilities each have a clear subagent.
    • For every affected page, include its Playwright spec in the page owner's write scope. If a shared component affects multiple pages, assign coverage for each affected page without creating overlapping spec ownership.
    • Record which conflicts each subagent is responsible for resolving if their branch/worktree falls behind or collides with a dependency.
    • Update the progress tracker immediately after each assignment. No task may stay as an unowned checklist item after assignment begins.

  4. Dispatch implementation tasks

    • Use .agents/references/implementation/subagent-prompts.md.
    • Give each worker the exact worktree graph project/root plus the required search/trace targets. Require the worker to index its worktree when no exact project exists and to read live source before editing.
    • Each worker owns exactly one task and one disjoint write scope.
    • For Figma-driven UI, include the relevant section-level Figma screenshots and labels in each worker prompt. Tell workers which screenshot maps to which component/page area and require the implemented UI to match it exactly: structure, spacing, radius, typography, color, copy, icons, image treatment, and interaction states.
    • For .tsx component files, tell workers to follow react-one-fc-per-file.mdc: do not place multiple top-level JSX components in the same file; extract sibling components into their own colocated files.
    • Tell workers they are not alone in the codebase, must not revert others' work, and must resolve task-scoped conflicts correctly before reporting completion.
    • Require each page owner to add or update that page's Playwright spec. Cover the main user flow and the relevant validation, error, permission, empty, and loading states identified in the acceptance criteria.
    • Require page owners to run bun run playwright:test -- playwright/tests/<page-slug>.spec.ts. Use existing documented contracts, fixtures, and route-mocking patterns. For UI-only work, do not invent service contracts or response shapes; mark a contract-dependent flow blocked or excluded when no documented contract exists.
    • Require each subagent report to include: task ID, status, files changed, completed work, remaining work, blockers, checks run, exact Playwright command/result per affected page, QA evidence, and requested master action.
    • After every subagent report, update the progress tracker before starting another coordination step.

  5. Run QA and code review loops

    • Follow .agents/references/implementation/qa-and-review-loop.md.
    • A task is not complete until implementation, QA, and code review all pass.
    • A page task cannot enter QA until its required Playwright spec exists and its page-level command passes. A failure or missing prerequisite is a recorded blocker, not a silent skip.
    • QA must inspect the page test inventory, run the recorded page-level command, and confirm the cases exercise the acceptance criteria rather than only checking that the page loads.
    • For Figma-driven UI, QA must compare implementation screenshots against every captured section-level Figma screenshot, using the labels and context from the checklist to map each design reference to the correct implemented area. Any visible mismatch is a failed QA item unless the user explicitly accepts the deviation.
    • Failed QA or review feedback goes back into the master checklist.
    • Reflect QA/review transitions in the progress tracker: move the task to qa, review, retrying, or passed, and record the Playwright result plus next owner/action.

  6. Respond to progress checks

    • When the user asks for progress, status, where things stand, what agents are doing, or similar wording in the main thread or side chat, answer from the current progress tracker before doing more work.
    • Show a compact task list grouped by status with each task's subagent/thread, current work, blockers, last update, next action, QA status, and review status. Include overall counts such as 3/8 passed, 2 in progress, 1 blocked.
    • Include each affected page's Playwright status and latest command result in progress snapshots.
    • When the user asks for browser, HTML, standalone, or dashboard progress, render a temporary standalone HTML dashboard with bun run progress-dashboard -- --input <tracker-json> --out /private/tmp/<name>.html. Use .agents/templates/progress-dashboard.html as the reusable template. The generated HTML auto-refreshes every 10 seconds by default and must stay outside tracked files unless the user explicitly asks to save a copy.
    • If a subagent has not reported recently, say waiting on subagent update and list the last known assigned scope instead of guessing.
    • After the progress snapshot, continue coordinating unless the user explicitly asks to pause.

  7. Integrate and clean up

    • Coordinate merge or application of passed task outputs in dependency order.
    • If integration requires repo edits beyond mechanical merge/application, assign those edits to a dedicated non-master integration subagent with an explicit write scope and conflict policy.
    • Run final verification for the whole feature.
    • Refresh the integration worktree index after substantial integrated code changes, then use detect_changes and targeted trace_path calls to verify cross-task impact and relevant tests.
    • After all page tasks are integrated, run bun run playwright:test. Treat any feature-related failure as an integration failure and return it to the responsible page owner or integration subagent.
    • Create or update the relevant .agents/references/features/*.md file with durable feature context from the implemented work before final completion. Use .agents/references/features/_template.md for a new feature reference, and keep one-off branch details out of the reference.
    • Follow .agents/references/implementation/plan-file-lifecycle.md and delete the temporary plan file after all tasks pass and integration is complete, unless the user explicitly asks to preserve it.
    • Delete all temporary Figma and implementation screenshots after QA passes and before any push or PR handoff. Verify with git status --short or a scoped file check that no screenshot artifacts are staged, tracked as new files, or left in the worktree.
    • After pushing feature changes to the remote branch, run .agents/skills/pr-description/SKILL.md so the PR title and description match the pushed branch diff.

Master Agent Responsibilities​

  • Clarify requirements and design details.
  • Ask for a Lark channel link when useful for requirement context, but do not block implementation if the link is not provided and can be skipped.
  • Classify API/backend dependencies and choose whether missing API docs mean ui-only, blocked, or not-applicable before task assignment.
  • Break work into small, independently executable tasks.
  • Check whether new files should be page-local or shared, and search for reusable existing code before assigning implementation.
  • Own codebase-memory project selection, architecture discovery, dependency/consumer tracing, and graph refresh decisions for the integration worktree.
  • Maintain the page test inventory and ensure every affected page has one owner, spec path, case list, execution command, result, and blocker state.
  • Avoid parallel tasks that write the same files.
  • Keep the master checklist current.
  • Keep the progress tracker current after every assignment, subagent report, QA result, review result, retry, integration step, and blocker.
  • Answer user progress-check requests with the tracker: task list, owner agent/thread, current status, blockers, next action, QA/review state, and aggregate counts.
  • Assign each implementation task to a specific non-master subagent/thread and worktree.
  • Ensure every subagent resolves conflicts in their own write scope, while cross-task or integration conflicts are escalated to the master agent or a dedicated integration subagent.
  • Review subagent reports before QA/review dispatch.
  • Reassign failed tasks with exact feedback.
  • Preserve durable implementation learnings by writing or updating the matching feature reference under .agents/references/features/.
  • Own final integration decisions, verification orchestration, and summary.

The master agent must not directly implement task code. If implementation work cannot reasonably be delegated, the master agent must split it differently, re-scope it, ask for direction, or mark it blocked. User requests to "just implement it" still go through non-master subagent assignment.

Completion Criteria​

The feature is complete only when:

  • Every checklist task is passed or merged.
  • The progress tracker is current and every task has an owner/status/blocker/next-action record.
  • Every implementation task was completed by a non-master subagent in an assigned worktree.
  • Any repo-editing integration work was completed by a dedicated non-master integration subagent.
  • QA issues are resolved.
  • Code review issues are resolved using .agents/skills/code-review/SKILL.md.
  • React component files comply with .agents/rules/react-one-fc-per-file.mdc.
  • Relevant tests/checks pass.
  • Every affected page or route has a page-owned Playwright spec at playwright/tests/<page-slug>.spec.ts, or an explicitly recorded blocker that prevents completion.
  • Each new page spec has one top-level route/page test.describe block and covers the main flow plus the acceptance-criteria states relevant to that page.
  • Every page-level Playwright command passes, and bun run playwright:test passes after integration.
  • not-applicable Playwright coverage is used only when the feature has no user-facing page impact, with the reason recorded in the checklist.
  • No unrelated files are changed.
  • Any conflicts were resolved by the responsible subagent or integration subagent and reviewed before merge.
  • Acceptance criteria are satisfied.
  • API integration mode is resolved; UI-only work has no invented service contracts or backend behavior.
  • For Figma-driven UI, every captured section-level design screenshot has a matching implementation screenshot or a documented user-approved exception, and QA has confirmed visual parity using the recorded section labels and context.
  • All temporary screenshots and visual QA artifacts are deleted before final completion and before any push; no screenshot files are staged, committed, pushed, or included in the PR.
  • The matching .agents/references/features/*.md file is created or updated with durable context from the implemented feature, including routes/components/hooks/services, data flow, gotchas, and useful searches.
  • The temporary master checklist plan file is deleted or intentionally preserved by user request.
  • After pushed changes, .agents/skills/pr-description/SKILL.md has been run to update the PR title and description from the branch diff.
  • Final summary is prepared.

References​

  • .agents/references/implementation/requirements-clarification.md
  • .agents/references/implementation/master-checklist-template.md
  • .agents/references/implementation/worktree-assignment.md
  • .agents/references/implementation/subagent-prompts.md
  • .agents/references/implementation/qa-and-review-loop.md
  • .agents/references/implementation/plan-file-lifecycle.md
  • .agents/skills/pr-description/SKILL.md