issue

name	issue
description	Implement a GitHub issue end-to-end — branch, code, test, docs, and commit.
argument-hint	<issue-number>
allowed-tools	Agent Bash(git *) Bash(gh *) Bash(cd *) Bash(make *) Bash(npm *) Bash(uv *) Bash(python *) Bash(cat *) Bash(ls *) Bash(mkdir *) Bash(cp *) Read Edit Write Grep Glob TaskCreate TaskUpdate TaskGet TaskList

Issue Implementation

Implement a GitHub issue end-to-end: fetch the issue, create a feature branch, implement all requirements, test, update docs, and commit.

Input

$ARGUMENTS must be a GitHub issue number (e.g. 78). If missing or non-numeric, ask the user for the issue number.

Step 1: Fetch the Issue

Run gh issue view $ARGUMENTS --json title,body,labels to get the issue details.

Also check if a matching markdown file exists under tmp/issues/ by looking for files that start with a zero-padded version of the issue number (e.g. issue 78 maps to a file starting with 078-). If the file exists, read it for additional context.

Display the issue title and a brief summary to the user.

Step 2: Create Feature Branch

Determine the branch name from the matching issue markdown filename under tmp/issues/, but without the .md extension. For example, if the file is 078-my-feature.md, the branch name is 078-my-feature.

If no matching file exists, derive the branch name from the issue number and title: zero-pad the issue number to 3 digits, kebab-case the title, and join with a hyphen (e.g. 078-my-feature-title).

Create and switch to the feature branch: git checkout -b <branch-name>.

Step 3: Plan the Implementation

Read the full issue body and any linked markdown file. Identify all discrete requirements.

Create a task list using TaskCreate for each requirement so progress can be tracked.

Before writing any code, present the implementation plan to the user and wait for confirmation.

Step 4: Implement

Use an agent team to parallelize independent work where possible:

• Backend changes: Implement in backend/ following project conventions (Python, FastAPI, type hints, SQLAlchemy).
• Frontend changes: Implement in frontend/ following project conventions (TypeScript, ESM, shadcn, Tailwind, Vite).
• Infrastructure changes: Implement in iac/ following AWS SAM / CloudFormation conventions.
• Agent changes: Implement in agents/ with isolated virtual environments.

Update TaskUpdate as each requirement is completed.

Step 5: Test

Run existing tests to check for regressions:

• Backend: cd backend && make test (or the appropriate makefile target)
• Frontend: cd frontend && npm test (if test scripts exist)
• Agent tests: Run tests within each modified agent directory.

If the issue specifies new test cases, implement and run them.

All tests must pass before proceeding.

Step 6: Update Documentation

Update the following documentation files to reflect the new changes:

• SPECIFICATIONS.md: Update any relevant specification files with the latest design decisions. Search for SPECIFICATIONS.md files in all subdirectories.
• README.md: Update any relevant README files with the latest implementation details. Ensure no sensitive or account-specific information is included (no ARNs, account IDs, tokens, or endpoint URLs).

Step 7: Final Validation

Run the full test suite one more time to confirm nothing was broken during documentation updates.

Review all changes with git diff to verify correctness and ensure no secrets or credentials are included.

Step 8: Commit

Stage and commit all changes locally using semantic commit messages. Group related changes into logical commits:

• feat: for new features
• fix: for bug fixes
• docs: for documentation updates
• test: for test additions
• refactor: for code restructuring
• chore: for build/config changes

Do NOT push to remote. Only commit locally.

Append Co-Authored-By: Claude <[e-mail]> to each commit message.

Report a summary of all commits created.