A lightweight, .envrc-style workflow (/saw-* skills + isolated Goldfish subagents) for stateful development and fresh-context review—without heavy ceremony.
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.mdplus 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, orfiles/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 inheritableextends: generalpacks.
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"]
(Trivial 1-line fixes fast-path directly without Goldfish. Deep dive: Architecture & Isolation.)
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 --updateOpen /path/to/your-project in your coding agent:
- Antigravity (App, CLI, or VS Code extension): Start a new conversation / reload window (or run
/skills reloadinagyCLI), then run/saw-setup. - GitHub Copilot (VS Code extension): Select the
saw-elephantagent in Chat, then run/saw-setup. - Claude Code (CLI or VS Code extension): Run
/saw-setupdirectly.
Then run /saw-run <task> for end-to-end execution, or /saw-help anytime to view phases and active Goldfish lenses.
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).
| 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. |
| 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. |
| 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 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
generalvia.saw/packs/<name>.mdinstead of editing built-in files—see Customizing Packs & Lenses. - Layer 1 (Static & Installer):
./verify.shvalidatesinstall.sh, YAML-safe skill frontmatter,general.mdlenses, multi-target installs,--updatepreservation/pruning, and self-install. - Layer 2 (Canary Probes):
./probes/canary.sh <harness>(guided runner) +probes/RUNBOOK.md(P1–P6).
