Self-Evolution Development Best Practices

Overview

This guide covers the self-evolution pipeline — modifying the project's own codebase via GitHub, triggering Vercel auto-deployment, and rolling back if needed.

Available Tools

Tool	Purpose	When to Use
`github_list_files`	Get full recursive file tree	Once per task, at the start
`github_read_file`	Read a single file's content	Before proposing changes
`github_patch_files`	Apply V4A diffs (preferred)	Editing existing files
`github_commit_push`	Push full file contents	Creating new files or files < 30 lines
`github_check_deploy`	Poll Vercel deployment status	After any commit/patch push
`github_revert_commit`	Revert a commit by SHA	Only when user explicitly requests
`github_compare_commits`	Compare two commits' diffs	Before revert or after push
`github_search_code`	Search code patterns	Before refactoring

Pipeline Flow

1. Search/Understand → 2. Propose → 3. Confirm → 4. Patch/Commit → 5. Monitor → 6. Compare/Revert

Step-by-Step Rules

1. Search & Understand the Codebase

Call github_list_files once with empty path for the full recursive file tree.
Use github_search_code to locate patterns across the codebase.
Read only the files you actually need. Plan your reads upfront.

2. Propose a Modification Plan

Present a clear, complete modification plan before any code push.
Include: which files change, what changes, and a preview of the diff.
For trivial changes (docs, config), a brief summary suffices.

3. Wait for User Confirmation

Never call push tools without explicit user approval.
If the user provides feedback, revise the plan and re-propose.

4. Commit Changes

Choose the right tool:

github_patch_files (preferred) — for editing existing files using V4A diffs.
github_commit_push — for creating entirely new files, or very short files (< 30 lines).

Both require conventional commit messages:

feat: — new feature
fix: — bug fix
docs: — documentation
refactor: — code restructuring
style: — visual/style changes

5. Monitor Deployment

Always pass the full 40-character commit SHA to github_check_deploy.
Call github_check_deploy 2–3 times after a push.
If READY, report success with the deployment URL.
If ERROR, present the key error lines and ask the user to choose: fix or revert.
If fatal: true, STOP immediately.

6. Compare & Revert if Needed

Use github_compare_commits to preview what a revert would undo.
Only revert when the user explicitly requests it.
Failed Vercel builds do not affect production.

Security Principles

The pipeline may be restricted to allowlisted agents via GITHUB_PIPELINE_ALLOWLIST.
Only owner channels can push to GitHub.
All push/revert operations are logged for audit.
Never expose tokens, secrets, or API keys in commit content.