Development Workflow

Overview

Orchestrates complete feature development from issue to merge: Issue → Branch → Worktree → Implement → Test → Review → PR → Merge → Close.

Prerequisites

• Git repository initialized

• Issue tracker MCP available (Gitea: mcp__gitea__* , GitHub: mcp__github__* )

• Codex CLI installed (codex --version )

• Repository owner/name confirmed

Workflow Steps

1. Get Issue Details

Gitea MCP:

mcp__gitea__get_issue_by_index(owner, repo, index)

GitHub MCP:

mcp__MCP_DOCKER__get_issue(owner, repo, issue_number)

GitHub CLI:

gh issue view {issue_number} --repo {owner}/{repo}

2. Create Branch

git checkout main && git pull origin main git checkout -b feature/{issue-number}-{slug}

3. Create Worktree

git worktree add ../worktrees/feature-{issue}-{slug} feature/{issue}-{slug}

Copy vendor dependencies if present:

cp -R Vendor ../worktrees/feature-{slug}/

4. Implement Feature

Work in worktree. For complex tasks, use Task tool with sub-agents.

5. Write Integration Tests

Add tests for new functionality. See TESTING.md for testing patterns.

6. Run Tests

Project-specific test command (e.g., xcodebuild test , npm test ).

7. Code Review

Ask user which tool to use if not specified:

• Codex CLI: codex review --base main

• Gemini CLI: gemini -p "/code-review"

• GitHub Copilot: gh copilot (interactive, ask for review)

• OpenCode: opencode -p "review changes" (provider-agnostic)

Run exactly once per review cycle:

Codex (detailed P1-P4 findings)

codex review --base main

OR Gemini (quick quality analysis)

gemini -p "/code-review"

OR GitHub Copilot (interactive)

gh copilot # then ask: "review my changes against main"

OR OpenCode (works with any LLM provider)

opencode -p "review my code changes against main branch"

IMPORTANT: Wait for the full output. Do NOT run a second review unless you've made code changes to fix issues.

If critical/high issues found:

• Fix all issues in code

• Commit fixes

• THEN run review again (this is a new review cycle)

If no critical issues: Proceed to commit.

See CODE-REVIEW.md for handling specific findings.

8. Commit & Push

git add . && git commit -m "feat(scope): description" git push -u origin feature/{issue}-{slug}

9. Create Pull Request

Gitea MCP:

mcp__gitea__create_pull_request(owner, repo, title, body, head, base="main")

GitHub MCP:

mcp__MCP_DOCKER__create_pull_request(owner, repo, title, body, head, base)

GitHub CLI:

gh pr create --title "title" --body "body" --base main --head feature/{issue}-{slug}

10. Merge to Main

git checkout main && git pull origin main git merge feature/{issue}-{slug} --no-ff && git push origin main

11. Close Issue

Gitea MCP:

mcp__gitea__edit_issue(owner, repo, index, state="closed")

GitHub MCP:

mcp__MCP_DOCKER__update_issue(owner, repo, issue_number, state="closed")

GitHub CLI:

gh issue close {issue_number} --repo {owner}/{repo}

12. Cleanup

git worktree remove ../worktrees/feature-{issue}-{slug} git branch -d feature/{issue}-{slug}

Parallel Workflow

For multiple independent issues, see PARALLEL.md.

Error Recovery

See ERRORS.md for handling build failures, Codex P1 issues, and merge conflicts.

Examples

Example: Implement Feature from Issue

Input: "Implement issue #42 - Add user authentication"

Process:

• Get issue details via MCP

• Create branch feature/42-user-auth

• Create worktree

• Implement authentication feature

• Write tests

• Run code review

• Create PR and merge

Output:

✅ Issue #42 implemented ✅ PR #15 created and merged ✅ Issue #42 closed

Guidelines

Do

• Confirm repository owner/name before starting

• Create worktree for isolation

• Run code review before PR

• Close issue after merge

Don't

• Skip the code review step

• Work directly on main branch

• Leave worktrees after merge

• Forget to push before creating PR