Git workflow and milestone closeout

Task Cycle

The complete development loop: checkout → work → review → commit → PR → code review → fix → merge → cleanup.

Parameters

Before starting, confirm these with the user or infer from context:

Parameter	Options	Default
GH Projects active	yes / no	Infer from whether issue # exists
Code reviewer	Macroscope, Gemini3, other	Ask if unknown
Bot identity	Git user.name / user.email	Use repo's configured bot

The Loop

Checkout → Agent Work → Claude+Human Review → HITL Fixes → Bot Commit → PR → Code Review → Fix Loop → Merge → Cleanup → Next

---

Phase 1: Checkout

With GH Projects (issue exists)

gh issue develop <issue-number> --checkout

This creates and checks out a branch linked to the issue automatically.

Verify context:

gh issue view <issue-number>

Without GH Projects (ad-hoc feature)

git checkout -b feature/<descriptive-name>

Naming conventions:

• feature/ — New functionality
• fix/ — Bug fixes
• docs/ — Documentation only
• refactor/ — Code restructure

---

Phase 2: Work

Agent performs the implementation. This phase is outside the skill's scope—the agent follows task requirements, writes code, runs tests.

Handoff signal: Agent indicates work is complete and ready for review.

---

Phase 3: Review (Claude + Human)

Review the agent's work together:

1. Functional review — Does it meet requirements?
2. Code quality — Patterns, readability, maintainability
3. Tests — Coverage, edge cases
4. Documentation — Updated as needed

Identify any HITL (human-in-the-loop) fixes required.

---

Phase 4: HITL Fixes

Human makes direct corrections as needed. This may involve:

• Code fixes the agent couldn't get right
• Style adjustments
• Integration issues
• Judgment calls

Once clean, proceed to commit.

---

Phase 5: Commit

Commit Command

git add .
git commit --author="<BotName> <<bot-email>>" -m "<commit-message>"

Bot Identities

Context	Name	Email
radioastronomyio	AstronomyCodingBot	[email protected]
Personal repos	(configure per repo)	(configure per repo)

Commit Message Format

Follow Conventional Commits:

type(scope): subject

- Detail 1
- Detail 2

[Closes #N]  ← Only if GH Projects active

Types:

Type	Use
feat	New feature
fix	Bug fix or code review feedback
docs	Documentation only
chore	Maintenance, dependencies, config
refactor	Code change without feature/fix

With GH Projects

Include Closes #<issue-number> in the commit body. GitHub auto-closes the issue on merge.

git commit --author="AstronomyCodingBot <[email protected]>" -m "feat(storage): implement RAID configuration

- Add ZFS pool setup
- Configure NFS shares
- Document mount points

Closes #25"

Without GH Projects

Omit the Closes line:

git commit --author="AstronomyCodingBot <[email protected]>" -m "feat(storage): implement RAID configuration

- Add ZFS pool setup
- Configure NFS shares
- Document mount points"

---

Phase 6: Push and PR

Push

git push origin <branch-name>

Create PR

gh pr create \
  --base main \
  --head <branch-name> \
  --title "type(scope): description" \
  --body "<PR body>" \
  --assignee <human-username>

PR body template:

## Summary
<What this PR accomplishes>

## Changes
- Change 1
- Change 2

## Testing
<How it was tested>

## Review Notes
<Anything the reviewer should know>

With GH Projects

Add labels and link to issue:

gh pr create \
  --base main \
  --head <branch-name> \
  --title "[M.T.ST] Description (#N)" \
  --body "..." \
  --assignee <human-username> \
  --label "Sub-Task,<domain-label>"

---

Phase 7: Code Review

The designated code reviewer analyzes the PR:

Reviewer	Trigger
Macroscope	Auto-reviews on PR creation (radioastronomyio)
Gemini3 Code Review	Auto-reviews on PR creation (personal repos)
Other	Per-repo configuration

Wait for review. Do not merge until code review completes.

---

Phase 8: Fix Loop

If code review requests changes:

1. Make the fixes locally
2. Commit (can amend or new commit):

# Option A: Amend (cleaner history)
git add .
git commit --amend --no-edit
git push --force-with-lease origin <branch-name>

# Option B: New commit (audit trail)
git add .
git commit --author="<BotName> <<bot-email>>" -m "fix: address code review feedback

- Issue 1 resolution
- Issue 2 resolution"
git push origin <branch-name>

3. Code reviewer re-reviews automatically on new commits
4. Repeat until approved

---

Phase 9: Merge

Once approved:

gh pr merge <pr-number> --squash --delete-branch

What happens:

• PR merges to main (squashed)
• Remote branch deleted
• Issue auto-closes (if Closes #N was in commit)
• GH Projects card moves to Done (if applicable)

---

Phase 10: Cleanup

git checkout main
git pull origin main

Local branch cleanup (if not auto-deleted):

git branch -d <branch-name>

---

Phase 11: Next Task

Return to Phase 1 with the next task. If using GH Projects, check tasks.md or the project board for the next item.

---

Quick Reference

Minimal Flow (no GH Projects)

git checkout -b feature/thing
# ... work happens ...
git add .
git commit --author="Bot <bot@email>" -m "feat: thing"
git push origin feature/thing
gh pr create --base main --head feature/thing --title "feat: thing" --assignee me
# ... code review ...
gh pr merge --squash --delete-branch
git checkout main && git pull

Structured Flow (with GH Projects)

gh issue develop 25 --checkout
# ... work happens ...
git add .
git commit --author="Bot <bot@email>" -m "feat: thing

Closes #25"
git push origin 25-thing
gh pr create --base main --head 25-thing --title "[2.1.2] Thing (#25)" --assignee me --label "Sub-Task"
# ... code review ...
gh pr merge --squash --delete-branch
git checkout main && git pull

---

References

• references/agent-github-workflow-one-pager.md — Full agent workflow with GH Projects
• references/milestone-closeout-procedure-one-pager.md — Closeout procedures and code review patterns