-
Find the issue. Locate the GitHub issue for this feature:
GH_PAGER= GH_PROMPT_DISABLED=1 gh issue list --search "$ARGUMENTS" --limit 5 --json number,title,url
Or if given an issue number directly:
GH_PAGER= GH_PROMPT_DISABLED=1 gh issue view <number> --json number,title,body,url
Read the issue body in full — it contains the requirements, design, task list, and test list.
-
Create a feature branch using a worktree. To avoid interfering with other agent work, create a new git worktree for this feature. Work in the new directory:
git fetch origin
git worktree add ../feature-<number>-<short-slug> -b feature/<number>-<short-slug> origin/main
cd ../feature-<number>-<short-slug>
Perform all implementation work within this worktree.
For example, issue #14 "User Profiles" → feature/14-user-profiles.
-
Read the design docs. Check any design documents in docs/design/ referenced by the issue for additional context.
-
Check current state. Look at the codebase to understand what exists. Verify that the task list in the issue still makes sense given the current state of the code. If something has changed, note it and adapt.
-
Work through the task list. Complete each task in order. For each task:
-
Work through the test list. After tasks are complete, verify each test in the test list:
- Run or write the specified test.
- Confirm it passes.
- Check off the test in the issue.
-
Final verification. After all items are complete:
- Run the full test suite for affected areas.
- Run linting/clippy with no warnings.
- Confirm all tasks and tests in the issue are checked off.
-
Push and open a pull request. Push the feature branch and create a PR:
git push -u origin feature/<number>-<short-slug>
GH_PAGER= GH_PROMPT_DISABLED=1 gh pr create \
--title "feat: <short title> (#<number>)" \
--body "Closes #<number>
## Summary
<brief description of what was implemented>
## Changes
<bulleted list of major changes>
## Testing
- All existing tests pass
- <list new tests added>
- cargo clippy -- -D warnings: clean
- pnpm lint: clean" \
--base main
-
Update the issue. Mark the status label to status:complete:
GH_PAGER= GH_PROMPT_DISABLED=1 gh issue edit <number> --remove-label "status:planned" --add-label "status:complete"
# or
GH_PAGER= GH_PROMPT_DISABLED=1 gh issue edit <number> --remove-label "status:partial" --add-label "status:complete"
Do not close the issue — it will be closed automatically when the PR merges via the Closes #<number> reference.
-
Report. Summarize what was built, any deviations from the plan, and provide the PR URL for review.
-
Cleanup. Do NOT automatically remove the worktree. Leave it for local testing unless the user explicitly instructs you to clean it up. If you need to remove it later, use:
cd <original-project-dir>
git worktree remove ../feature-<number>-<short-slug>