claude-archeflow-plugin/skills/git-integration/SKILL.md

name, description

name

description

git-integration

Git-per-phase commit strategy for ArcheFlow runs. Creates a branch per run, commits after every phase transition and agent completion, and merges (squash or no-ff) on success. Enables rollback to any phase boundary and full audit trail via git history. <example>Automatically loaded by archeflow:run when git.enabled is true</example> <example>User: "archeflow rollback --to plan"</example> <example>User: "Show me the git history for this run"</example>

Git Integration — Per-Phase Commit Strategy

Every ArcheFlow run creates a dedicated branch. Each phase transition and agent completion produces a commit. At run completion, the branch is merged back to the base branch. On failure, the branch stays intact for inspection or rollback.

Prerequisites

• archeflow:orchestration — workflow rules and safety constraints
• archeflow:process-log — event schema (git events are emitted alongside process events)
• archeflow:artifact-routing — artifact paths that get committed

Helper Script

All git operations go through the helper script:

./lib/archeflow-git.sh <command> <run_id> [args...]

See lib/archeflow-git.sh for full usage. The skill describes when to call the script; the script handles how.

---

Branch Strategy

main (or current base branch)
└── archeflow/<run_id>                    # Created at run.start
    ├── commit: "archeflow(plan): explorer research"
    ├── commit: "archeflow(plan): creator outline"
    ├── commit: "archeflow(plan→do): phase transition"
    ├── commit: "archeflow(do): maker draft"
    ├── commit: "archeflow(do→check): phase transition"
    ├── commit: "archeflow(check): guardian review"
    ├── commit: "archeflow(check): sage review"
    ├── commit: "archeflow(check→act): phase transition"
    ├── commit: "archeflow(act): apply 6 fixes"
    ├── commit: "archeflow(act): cycle 1 complete"
    └── commit: "archeflow(run): complete — <summary>"

Branch naming: archeflow/<run_id> (e.g., archeflow/2026-04-03-jwt-auth).

---

Commit Points

Trigger	What to commit	Message format
After agent.complete	Agent artifacts + any created/modified files	archeflow(<phase>): <archetype> <summary>
After phase.transition	All artifacts from completed phase	archeflow(<from>→<to>): phase transition
After each fix.applied	The fixed file	archeflow(fix): <source> — <finding summary>
After cycle.boundary	Everything staged	archeflow(act): cycle <N> <status>
After run.complete	Final state + process report	archeflow(run): complete — <summary>

---

Commit Protocol

1. Stage only relevant files. Never git add -A. Stage:
   • .archeflow/artifacts/<run_id>/ — artifacts produced by the current agent/phase
   • .archeflow/events/<run_id>.jsonl — updated event log
   • Any project files created or modified by the current agent (from do-maker-files.txt or explicit file list)
2. Exclude ephemeral files. Never commit:
   • .archeflow/progress.md (live progress display, ephemeral)
   • .archeflow/explorer-cache/ (local cache, not run-specific)
   • .archeflow/session-log.md (separate concern)
3. Use conventional commit format: archeflow(<scope>): <message>
4. Signing: If git.signing_key is configured, pass -c user.signingkey=<key> to git commit.

Integration with the Run Skill

The archeflow:run skill calls git operations at these points:

run.start          → ./lib/archeflow-git.sh init <run_id>
agent.complete     → ./lib/archeflow-git.sh commit <run_id> <phase> "<archetype> <summary>" [files...]
phase.transition   → ./lib/archeflow-git.sh phase-commit <run_id> <phase>
fix.applied        → ./lib/archeflow-git.sh commit <run_id> fix "<source> — <finding>"
cycle.boundary     → ./lib/archeflow-git.sh commit <run_id> act "cycle <N> <status>"
run.complete (ok)  → ./lib/archeflow-git.sh merge <run_id> [--squash|--no-ff]
run.complete (fail) → branch preserved, not merged

---

Run Lifecycle

1. Initialization (run.start)

./lib/archeflow-git.sh init <run_id>

This will:

1. Verify a clean working tree (or stash uncommitted changes)
2. Create branch archeflow/<run_id> from current HEAD
3. Switch to the new branch

2. During Execution (phase commits)

After each agent completes or phase transitions, the run skill calls:

# After an agent completes:
./lib/archeflow-git.sh commit <run_id> plan "explorer research" \
  .archeflow/artifacts/<run_id>/plan-explorer.md

# After a phase transition:
./lib/archeflow-git.sh phase-commit <run_id> plan

The commit command stages artifact directories and event logs automatically. Additional files can be passed as trailing arguments.

The phase-commit command stages all artifacts matching the phase prefix and commits with a transition message.

3. Completion (merge)

# Success — squash merge (default):
./lib/archeflow-git.sh merge <run_id> --squash

# Success — preserve history:
./lib/archeflow-git.sh merge <run_id> --no-ff

# Failure or user abort:
# Do nothing. Branch stays for inspection.
echo "Branch archeflow/<run_id> preserved for inspection."

The merge command:

1. Verifies all changes on the branch are committed
2. Switches to the base branch (main or wherever the run started)
3. Merges with the chosen strategy
4. If squash: creates a single commit with feat: <task summary>
5. Does NOT delete the branch (user may want to inspect)

4. Cleanup (optional, after inspection)

./lib/archeflow-git.sh cleanup <run_id>

Deletes the branch after the user has confirmed the merge is correct.

---

Rollback

Roll back to the end of any completed phase:

./lib/archeflow-git.sh rollback <run_id> --to plan

This will:

1. Find the last commit for the target phase by searching commit messages
2. Show the user what commits will be lost (everything after the target)
3. Perform git reset --hard <commit> on the branch
4. Trim the events JSONL to remove events that occurred after the rollback point

Supported rollback targets: plan, do, check, act, or any cycle number (cycle-1, cycle-2).

Safety: Rollback only works on the run's branch, never on main. The script verifies you are on archeflow/<run_id> before proceeding.

---

Status

View the git state of a run:

./lib/archeflow-git.sh status <run_id>

Output:

Branch: archeflow/2026-04-03-jwt-auth
Base: main (3 commits ahead)

Commits:
  abc1234 archeflow(plan): explorer research
  def5678 archeflow(plan): creator outline
  ghi9012 archeflow(plan→do): phase transition
  jkl3456 archeflow(do): maker implementation

Current phase: do
Files changed (total): 8
Uncommitted changes: none

---

Configuration

In .archeflow/config.yaml or a team preset:

git:
  enabled: true                # Default: true. Set false to disable all git operations.
  branch_prefix: "archeflow/"  # Default. The run_id is appended.
  commit_style: conventional   # conventional (archeflow(<scope>): msg) | simple (<phase>: msg)
  merge_strategy: squash       # squash | no-ff | rebase
  auto_push: false             # Push branch to remote after each commit
  signing_key: null            # SSH key path for signed commits (e.g., ~/.ssh/id_ed25519.pub)

The helper script reads this config if it exists. All values have sensible defaults.

---

Post-Merge Rollback

After merging, the run skill validates the merge by running the project's test suite. If tests fail, the merge is automatically reverted.

Script

./lib/archeflow-rollback.sh <run_id> [--test-cmd <cmd>]

Behavior:

1. Reads test_command from .archeflow/config.yaml (or uses --test-cmd override)
2. Runs the test suite with a 5-minute timeout
3. If tests pass: exits 0 (merge is good)
4. If tests fail: runs git revert --no-edit HEAD, emits a decision event, exits 1
5. Verifies HEAD is an ArcheFlow merge commit before reverting (warning if not, proceeds anyway)

Integration with run skill: Called in section 4c (All Approved) after archeflow-git.sh merge. If it returns non-zero, the orchestrator cycles back with "integration test failure" feedback or reports to the user if max cycles are reached.

Configuration: Set test_command in .archeflow/config.yaml:

test_command: "npm test"       # or "pytest", "cargo test", etc.

---

Safety Rules

These rules are inherited from archeflow:orchestration and reinforced here:

1. Never force-push. No --force, no --force-with-lease. If a push fails, diagnose and fix.
2. Never modify main history. Merges are forward-only. No rebasing main.
3. Branch stays intact on failure. If a run fails or is aborted, the branch is preserved for inspection. Never auto-delete failed branches.
4. All commits are individually revertable. Each commit represents a discrete unit of work.
5. Worktree mode compatibility. If the Maker runs in a worktree, git-integration commits go to the worktree's branch. The merge happens at the run level, not the worktree level. The Maker's worktree branch is a sub-branch of archeflow/<run_id>.
6. Clean merge or abort. If a merge produces conflicts, do not force-resolve. Report the conflict, leave the branch intact, and let the user decide.
7. No signing by default. Signing is opt-in via config. If configured, all commits on the branch are signed.

---

Design Principles

1. Git is the audit trail. Every phase transition is a commit. git log tells the full story of a run.
2. Rollback is cheap. Reset to any phase boundary, re-run from there. No need to start over.
3. Merge strategy is a project decision. Squash for clean history, no-ff for detailed history. Both are valid.
4. Events + git = full observability. Process events capture what happened (decisions, verdicts, timing). Git captures what changed (files, diffs). Together they provide complete run archaeology.
5. Fail-safe by default. Every safety rule defaults to the conservative option. The user must explicitly opt in to destructive operations.