Skip to content

About

Elephant–Goldfish agentic workflow for small, verified diffs and read-only PR triage across Antigravity, GitHub Copilot, and Claude Code.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

SAW — Simple Agentic Workflow: Stateful Development · Fresh-Context Review

A lightweight, .envrc-style workflow (/saw-* skills + isolated Goldfish subagents) for stateful development and fresh-context review—without heavy ceremony.

License: MIT Zero Dependencies Verified Harnesses


Why SAW?

Single-session coding agents validate their own assumptions and dump noisy diffs, while heavy spec frameworks bury you in approval reports. SAW pairs real verification commands with fresh-context Goldfish audits—like TDD for agentic development:

  • Elephant (Stateful Development): Holds conversation context, drafts specs and code, and runs real verification commands from .saw/profile.md plus bounded Goldfish review loops (recording 1-line reasons for any skipped suggestions).
  • Goldfish (Fresh-Context Review): Read-only subagents spawned with zero chat history to inspect only isolated inputs (spec, diff, seed, symptom+repro, or files/dirs)—catching blind spots without sycophancy.
  • Anti-Slop & Minimal Diff: Prevents bloated "AI grenade" PRs with bounded specs, dual-lens review (critic + simplifier), read-only diff triage, and inheritable extends: general packs.

How /saw-run Works

flowchart LR
    T["Task Prompt"] --> S["Spec<br/>(clarity Goldfish)"]
    S --> C{"1x User<br/>Checkpoint"}
    C -->|"Proceed"| PR["Pre-Review<br/>(critic + simplifier)"]
    PR --> W["Work & Verify<br/>(real tests + optional diagnostician)"]
    W --> DR["Post-Review<br/>(critic + simplifier)"]
    DR --> SY["Sync Docs &<br/>Clean Temp Diffs"]
Loading

(Trivial 1-line fixes fast-path directly without Goldfish. Deep dive: Architecture & Isolation.)


Quick Start (60 Seconds)

Prerequisites: bash, git (plus authenticated gh CLI for GitHub PR triage in /saw-diff-commit). On Windows, run install.sh from Git Bash (bundled with Git for Windows) or WSL; teammates who pull an already-installed project don't need to run it.

git clone https://github.com/jheo4/simple-agentic-workflow.git
cd simple-agentic-workflow

# Install all 3 harness adapters (or --targets copilot,claude,antigravity)
./install.sh /path/to/your-project

# Later updates (preserves .saw/profile.md, custom packs/lenses, and custom skills;
# refreshes built-in SAW files and prunes retired SAW skills)
./install.sh /path/to/your-project --update

Open /path/to/your-project in your coding agent:

  • Antigravity (App, CLI, or VS Code extension): Start a new conversation / reload window (or run /skills reload in agy CLI), then run /saw-setup.
  • GitHub Copilot (VS Code extension): Select the saw-elephant agent in Chat, then run /saw-setup.
  • Claude Code (CLI or VS Code extension): Run /saw-setup directly.

Then run /saw-run <task> for end-to-end execution, or /saw-help anytime to view phases and active Goldfish lenses.


Commands & Examples

Commands marked [pack] take an optional pack from .saw/packs/<pack>.md first (otherwise uses default-pack in .saw/profile.md, fallback: general—see Customizing Packs & Lenses).

Start / Auto

Skill When to Use
/saw-setup Populate or refresh .saw/profile.md (stack, docs, verification commands).
/saw-run [pack] <task> Full auto flow: spec → 1 checkpoint → pre-review, work, tests, post-review, sync.
/saw-help [goal|pack] Show workflow map, active Goldfish lenses per phase, or get a command pick.

Manual Lifecycle

Skill Phase & Lenses
/saw-brainstorm [pack] <topic> brainstorm (incremental, reframe, zoom, reality) — pick the right task.
/saw-spec [pack] <task> spec (clarity) — draft scope, edge cases, and verification criteria.
/saw-review [pack] [spec|diff|focus] review (critic, simplifier) — refine a spec or pending changes.
/saw-work [pack] <spec|task> work (diagnostician on demand + review) — implement, test, and review.
/saw-sync [doc paths] sync — pinpoint-sync .saw/profile.md and docs to current code on disk; proposes pointers for given doc paths.

Read-Only Diffs (No Checkout, No Edits)

Skill Example & Purpose
/saw-diff-commit [pack] <target> /saw-diff-commit #123, HEAD~1..HEAD, feat-x — defuse AI grenade PRs/commits (review phase).
/saw-diff-files [pack] <left> <right> [focus] /saw-diff-files v1/ v2/, a.json b.yaml — compare code, data, or docs (diff phase: concept, direction, detail).

Installed Layout & Verification

Installed files inside <your-project>/ (click to expand)
<your-project>/
├── .saw/               # Core protocol, profile, packs, lenses, gitignored work/
├── .github/            # Copilot: copilot-instructions.md, skills/, saw-elephant/goldfish agents
├── .claude/            # Claude Code skills/ and read-only saw-goldfish agents
├── .agents/            # Antigravity skills/ and .agents/plugins/saw/
├── CLAUDE.md           # Claude Code SAW instructions block
├── AGENTS.md           # Antigravity SAW instructions block
└── .gitignore          # Appends .saw/work/
  • Customization: Extend general via .saw/packs/<name>.md instead of editing built-in files—see Customizing Packs & Lenses.
  • Layer 1 (Static & Installer): ./verify.sh validates install.sh, YAML-safe skill frontmatter, general.md lenses, multi-target installs, --update preservation/pruning, and self-install.
  • Layer 2 (Canary Probes): ./probes/canary.sh <harness> (guided runner) + probes/RUNBOOK.md (P1–P6).

License

MIT

About

Elephant–Goldfish agentic workflow for small, verified diffs and read-only PR triage across Antigravity, GitHub Copilot, and Claude Code.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Contributors

Languages