implement

name	implement
description	Execute a task list step-by-step with strict sequencing, branch/PR discipline, GitHub Issue sync, and user approval gates. Single source of truth for implementation. Use when implementing from a tasks-*.md file.

Activity: Implement Task List

RFC 2119 Notice: The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

Goal

Execute a task list step-by-step with strict sequencing, proper branching, PR workflow, GitHub Issue synchronization, and user approval gates.

This is the single source of truth for execution rules. All agents and workflows that perform implementation MUST follow these rules.

Context

This activity assumes:

• A task list file exists in /workstream/tasks-*.md.
• The corresponding GitHub Issue exists and includes a checklist.
• GitHub is the source of truth for execution status.

Package Manager and Command Standards

• For JavaScript/TypeScript repositories, you MUST prefer pnpm over npm for dependency and script commands.
• You MAY use npm only when pnpm is unavailable or the project is explicitly npm-locked.
• For JS/TS repositories, quality and test execution MUST use canonical package.json script names where available: lint, format:check, typecheck, test, audit, and validate.

---

Before Starting Work

1. You MUST confirm the GitHub Issue is open.
2. Branch gate (hard requirement): You MUST verify you are on a feature branch before any implementation work:
   • Run git rev-parse --abbrev-ref HEAD to determine the current branch.
   • If HEAD is the default branch (main) or does not match issue/* or story/* pattern, you MUST create a new branch from the latest default branch by delegating branch naming and creation to github-ops whenever possible.
   • You MUST NOT proceed with any implementation sub-task, write any code, create any files, or make any commits until a feature branch is checked out.
   • If HEAD is already a valid feature branch (matching issue/* or story/*), proceed to step 3.
   • Branch format: issue/<issue-number>-<short-description> or story/<id>-<short-description>
3. You MUST open a draft Pull Request by delegating to github-ops whenever possible.
   • A PR requires at least one commit. Open it immediately after the first commit on the feature branch — never before — and you MUST NOT continue past that first commit without it.
   • Base branch is the default branch unless an orchestrating caller explicitly provides a base-branch override.
   • PR title MUST follow Conventional Commits (e.g., feat: implement issue 37).
   • PR description MUST include Closes #<issue-number>.
4. You MUST ensure the task list in the GitHub Issue matches the local /workstream/tasks-*.md file.

If github-ops delegation is unavailable in the current runtime, you MUST apply github-ops conventions directly and explicitly note that fallback in your status output.

---

During Implementation

Step-by-Step Execution

• You MUST execute one sub-task at a time.
• You MUST NOT start the next sub-task until the user grants permission (says "yes" or "y").
• After completing each sub-task, you MUST immediately:
  1. Mark it [x] in the local task file.
  2. Mark it [x] in the GitHub Issue checklist.
  3. Stop and wait for user approval before proceeding.

Parent Task Completion

• When all sub-tasks under a parent task are [x], you MUST also mark the parent task as [x].

Task List Maintenance

• You MUST regularly update the task list file after finishing significant work.
• You MUST add newly discovered tasks as they emerge.
• You MUST keep the "Relevant Files" section accurate and up to date with every file created or modified.
• You MUST keep the local task list and the GitHub Issue checklist aligned at all times.
• If drift is detected between local and GitHub, you MUST reconcile immediately and report the reconciliation.
• If schema/data-model changes are in scope, migration artifacts MUST be tracked in the task list unless an explicit opt-out rationale is documented.

Progress Updates

• You SHOULD add brief issue or PR comments for major milestones or meaningful changes.
• You SHOULD route issue/PR comment updates through github-ops whenever possible.

---

Before Closing a Story/Issue

1. All acceptance criteria MUST be verified.
2. All tests listed in the checklist MUST be completed and passing.
3. The following quality gates MUST be completed and passing before completion:
   • test
   • lint
   • format:check
   • typecheck
   • audit
4. For schema/data-model changes, migration handling MUST satisfy all of the following:
   • migration artifact created (unless documented opt-out)
   • rollback/impact notes captured
   • explicit user confirmation obtained before any migration apply command
   • apply step executed only after user confirmation
   • post-apply verification recorded
5. technical-writer validation MUST include a drift/stale-doc check report, and completion MUST NOT proceed while unresolved drift remains.
6. A qa-engineer pass MUST have run and coverage_gate MUST be recorded as PASS, FAIL, or SKIPPED(<reason>). The reason MUST be non-empty when skipped; an omitted field is treated as incomplete. A FAIL or SKIPPED value does not block completion — only omission does.
7. A verifier audit in audit mode MUST have run against the delivered implementation, with its human-readable summary posted to the issue/PR. This gate is mandatory and non-skippable — it MUST NOT be skipped regardless of drift findings, and drift findings reported by this audit MUST NOT block completion. This condition is satisfied once the audit has run and been posted; any resulting drift is handled by product-engineer's activity-drift-reconciliation flow after this gate, not before it.
8. The PR MUST be converted from draft to ready for review.
9. The PR MUST be approved by the appropriate reviewer per the merge authority policy in github-ops:
   • PRs targeting an integration branch: planner reviews and approves.

---

GitHub Execution Rules Summary

Phase	Rule
Before coding	Confirm issue open → Create branch (github-ops) → First commit → Open draft PR (github-ops) → Sync checklists
During coding	One sub-task at a time → Mark [x] locally + GitHub → Wait for approval
Before closing	All ACs verified → Quality gates pass (test/lint/format/typecheck/audit) → migration confirmation/apply/verify (when applicable) → docs drift check clear → coverage_gate recorded → verifier audit run + summary posted (non-blocking on drift) → PR ready → Approved → Merged → Then close issue

---

Output

• Keep all changes and status updates in GitHub and /workstream/tasks-*.md.
• You MUST check which sub-task is next before starting work.
• After implementing a sub-task, you MUST update the file and then pause for user approval.

Final Instructions

1. You MUST always respect the task list execution order.
2. You MUST keep the GitHub Issue updated with checklist and progress comments.
3. You MUST ensure branch, PR, and issue naming follow github-ops conventions.
4. You MUST stop after each sub-task and request user approval.
5. You MUST NOT close a GitHub Issue without confirming the PR has been reviewed, approved, and merged.