Deploy
Atomic commits. Structured PRs. Never git add -A.
Why this phase exists
Sloppy commit history and unstructured PRs make rollbacks, bisects, and audits painful. Deploy enforces commit discipline, the packaging step that turns workflow artifacts into a clean, reviewable change request.
It comes after Document because documentation updates are part of the commit. Code, tests, and docs all get packaged together.
"Deploy means PR" (Decision 004). The workflow's output is a reviewable change request, not a deployment. Human approval or auto-merge is a team-level configuration, not a framework decision.
Methodology
Receive all artifacts
Code changes, docs, test evidence, review verdict, and plan artifact. Everything the PR needs to tell its story.
Stage changes atomically
Group related files into logical commits. Never git add -A or git add .. Stage specific files by name for each commit.
Write conventional commit messages
Format: type(scope): description. Types: feat, fix, refactor, test, docs, chore. Each commit message is meaningful and searchable.
Create commits
One commit per logical change unit. Implementation, tests, and docs may be separate commits. Each commit is a self-contained, buildable state.
Push and create PR (or merge locally)
Remote flow: push branch and create PR with structured body. Local flow: merge to target branch. Both flows produce a traceable result.
Generate deploy report
List of commits with hashes and messages, PR URL (remote) or merge hash (local).
Inputs and outputs
Inputs
- • All artifacts from previous phases
- • Code changes + documentation updates
- • Test evidence, review verdict
Outputs
- • Atomic commits with conventional messages
- • Structured PR (remote) or merge hash (local)
- • Deploy report
Consumed by: Monitor phase as $deploy_report
## Summary
${plan_summary}
## Changes
- Refactored token validation in auth module
- Added JWT format pre-validation step
- Created test suite (47 tests)
- Updated documentation and ADR
## Test Evidence
- All 47 tests passing
- Coverage: 94.2% statements, 88.1% branches
- Self-healing: 1 fix applied during test phase
## Review Status
- 0 blockers, 1 tech debt item logged
- Review passed on iteration 1
## Plan Reference
${plan_artifact_link}Agent pattern
Deploy is a linear task. Multi-agent coordination would be overkill. A single agent stages files, creates commits, pushes, and creates the PR. The flow is: Stage -> Commit -> Push -> PR Create.
Tool permissions
Execute is needed for git operations (commit, push, PR creation via CLI). Write is denied because no code should change at this point. Everything was finalized in earlier phases. If something still needs editing, it goes back to Build.
Prompt template
# Deploy Phase -- Release Engineer
## Role
You are a Release Engineer. Your job is to create clean,
atomic commits and a structured PR from the completed
implementation.
You do NOT modify code. All code changes are finalized.
You package and ship them with proper commit discipline.
## Context
Plan Artifact:
${plan_artifact}
Build Report:
${build_report}
Test Report:
${test_report}
Review Verdict:
${review_verdict}
Branch: ${branch_name}
Target Branch: ${target_branch} # e.g., main, develop
Remote: ${remote_name} # e.g., origin
PR Workflow: ${pr_workflow} # remote | local
## Commit Strategy
### Conventional Commit Prefixes
- feat: New feature
- fix: Bug fix
- refactor: Code restructuring
- test: Test additions or changes
- docs: Documentation updates
- chore: Build process, tooling changes
### Atomic Commits
Each commit represents ONE logical change:
- Implementation: feat(auth): add JWT pre-validation
- Tests: test(auth): add token validation test suite
- Docs: docs(auth): update token flow documentation
### NEVER Do This
- git add -A (bulk staging)
- git add . (bulk staging)
- Single commit with all changes
- Commit message without type prefix
## Methodology
1. Review all changed files from the Build Report
2. Group files into logical commit units
3. For each commit unit:
a. Stage specific files: git add path/to/file1 path/to/file2
b. Commit with conventional message
4. Push to remote (if remote workflow)
5. Create PR with structured body
6. Report commit list and PR URL
## Remote/Local Fallback
### If ${pr_workflow} == "remote":
1. git push -u ${remote_name} ${branch_name}
2. Create PR via gh pr create or equivalent
3. PR body references plan artifact
### If ${pr_workflow} == "local":
1. git checkout ${target_branch}
2. git merge ${branch_name}
3. Report merge commit hash
## Constraints
- Never git add -A or git add .
- Every commit is atomic and meaningful.
- Conventional commit prefixes required.
- PR body must reference the plan artifact.
- Do not modify any files.
## Output Format
### Remote:
- Commit list: hash, message, files for each commit
- PR URL: ${pr_url}
### Local:
- Commit list: hash, message, files for each commit
- Merge hash: ${merge_hash}Best practices
Do
- Stage files individually by name
- Use conventional commit prefixes
- Reference the plan in the PR body
- Include test evidence in the PR
- Make each commit self-contained and buildable
Don't
- Never git add -A
- Never git add .
- Never create a single monolithic commit
- Never skip the PR body
- Never modify files at this stage
Nuances
"Never bulk-add files" is the single most important constraint
Bulk staging picks up debug files, unrelated changes, and sensitive files (.env, credentials). Stage each file deliberately, by name.
Each commit is atomic and meaningful
If someone runs git bisect, each commit should be a self-contained, buildable state. This means implementation commits include the code that makes tests pass, not code that breaks them.
PR body references plan artifact
This gives you traceability from original task, through the plan, to the final PR. Anyone can trace a change back to why it was made.
Remote/local fallback
Not all teams use GitHub or GitLab. The Deploy phase supports local-only workflows where the output is a merge commit rather than a PR. The template variable ${pr_workflow} controls the routing.