refactor: trim 11 secondary ArcheFlow skills from 3340 to 952 lines
Remove verbose YAML examples, bash pseudo-code, tutorial prose, and motivational content from configuration/integration skills while preserving all operational protocols, reference tables, and rules. Skills trimmed: domains, colette-bridge, multi-project, cost-tracking, git-integration, custom-archetypes, workflow-design, templates, autonomous-mode, progress, presence.
This commit is contained in:
@@ -6,263 +6,86 @@ description: |
|
||||
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
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
./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*.
|
||||
|
||||
---
|
||||
Every run creates branch `archeflow/<run_id>`. Each phase transition and agent completion produces a commit. On success, merge back. On failure, branch stays for inspection.
|
||||
|
||||
## 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>"
|
||||
main
|
||||
+-- archeflow/<run_id>
|
||||
+-- archeflow(plan): explorer research
|
||||
+-- archeflow(plan): creator outline
|
||||
+-- archeflow(plan->do): phase transition
|
||||
+-- archeflow(do): maker draft
|
||||
+-- archeflow(check): guardian review
|
||||
+-- archeflow(act): cycle 1 complete
|
||||
+-- archeflow(run): complete
|
||||
```
|
||||
|
||||
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>` |
|
||||
|
||||
---
|
||||
| Trigger | Message format |
|
||||
|---------|----------------|
|
||||
| `agent.complete` | `archeflow(<phase>): <archetype> <summary>` |
|
||||
| `phase.transition` | `archeflow(<from>-><to>): phase transition` |
|
||||
| `fix.applied` | `archeflow(fix): <source> -- <finding>` |
|
||||
| `cycle.boundary` | `archeflow(act): cycle <N> <status>` |
|
||||
| `run.complete` | `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`.
|
||||
- Stage only relevant files: `.archeflow/artifacts/<run_id>/`, event log, project files from maker
|
||||
- Never `git add -A`
|
||||
- Exclude: `progress.md`, `explorer-cache/`, `session-log.md`
|
||||
- Use conventional commit format
|
||||
- Signing opt-in via `git.signing_key` config
|
||||
|
||||
### Integration with the Run Skill
|
||||
## All operations go through `./lib/archeflow-git.sh`:
|
||||
|
||||
The `archeflow:run` skill calls git operations at these points:
|
||||
| Run event | Command |
|
||||
|-----------|---------|
|
||||
| `run.start` | `init <run_id>` (create+switch branch) |
|
||||
| `agent.complete` | `commit <run_id> <phase> "<msg>" [files]` |
|
||||
| `phase.transition` | `phase-commit <run_id> <phase>` |
|
||||
| `run.complete` (ok) | `merge <run_id> [--squash|--no-ff]` |
|
||||
| `run.complete` (fail) | branch preserved |
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
## Merge
|
||||
|
||||
---
|
||||
|
||||
## Run Lifecycle
|
||||
|
||||
### 1. Initialization (`run.start`)
|
||||
|
||||
```bash
|
||||
./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:
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
./lib/archeflow-git.sh cleanup <run_id>
|
||||
```
|
||||
|
||||
Deletes the branch after the user has confirmed the merge is correct.
|
||||
|
||||
---
|
||||
1. Verify all changes committed
|
||||
2. Switch to base branch
|
||||
3. Merge with configured strategy (squash default)
|
||||
4. Branch NOT auto-deleted (user may inspect)
|
||||
|
||||
## Rollback
|
||||
|
||||
Roll back to the end of any completed phase:
|
||||
`./lib/archeflow-git.sh rollback <run_id> --to <target>`
|
||||
|
||||
```bash
|
||||
./lib/archeflow-git.sh rollback <run_id> --to plan
|
||||
```
|
||||
Targets: `plan`, `do`, `check`, `act`, `cycle-N`. Only works on `archeflow/<run_id>` branch. Resets to last commit for target phase and trims event JSONL.
|
||||
|
||||
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
|
||||
## Post-Merge Validation
|
||||
|
||||
**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:
|
||||
|
||||
```bash
|
||||
./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
|
||||
```
|
||||
|
||||
---
|
||||
After merge, runs project test suite (from `test_command` in config) with 5-min timeout. If tests fail: `git revert --no-edit HEAD`.
|
||||
|
||||
## Configuration
|
||||
|
||||
In `.archeflow/config.yaml` or a team preset:
|
||||
|
||||
```yaml
|
||||
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)
|
||||
enabled: true
|
||||
branch_prefix: "archeflow/"
|
||||
merge_strategy: squash # squash | no-ff | rebase
|
||||
auto_push: false
|
||||
signing_key: null
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
```bash
|
||||
./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`:
|
||||
```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.
|
||||
- Never force-push
|
||||
- Never modify main history
|
||||
- Branch stays intact on failure
|
||||
- Clean merge or abort (no force-resolve on conflicts)
|
||||
- Worktree-compatible (Maker's worktree branch is sub-branch of run branch)
|
||||
|
||||
Reference in New Issue
Block a user