Augment

The Autonomous Software Engineering Methodology & Skills Framework for Coding Agents

Why Augment • How It Works • Installation • Skills Catalog • Engineering Principles • Contributing

---

Why Augment?

Standard AI coding agents are eager to please: they jump into writing code on your very first prompt, guess unspoken requirements, produce monolithic changes, and claim "done" without running a single verifiable test.

Augment transforms raw LLMs into disciplined, senior software engineers.

By instilling rigorous engineering workflows directly into your agent's reasoning loop, Augment guarantees that every line of code is backed by an explicit spec, isolated in a safe workspace, driven by automated tests, and validated by independent subagent reviewers.

⚖️ The Augment Advantage

Engineering Dimension	❌ Standard Coding Agent	⚡ Agent with Augment
Requirement Discovery	Jumps into code immediately; invents missing context.	Socratic interview until 100% mutual spec alignment.
Workspace Safety	Edits directly on your active working branch.	Isolated Git Worktree preserving branch hygiene.
Implementation Scope	Monolithic, speculative code dumps that fail silently.	Atomic DAG tasks (2–5 min each) with exact diffs.
Verification Quality	"It compiles, so it's done" (no tests written).	Strict TDD Loop: Failing test (RED) → Code (GREEN) → Refactor.
Quality Control	Grades its own homework (confirmation bias).	Two-Stage Subagent Review (Spec Compliance + Architecture).
Session Handover	Leaves orphaned files and dirty git states.	Clean Finish: Full regression pass, clean squash & PR.

---

How It Works

Augment replaces unconstrained prompt-and-pray coding with a deterministic 5-stage engineering lifecycle:

flowchart TD
    Start([💡 User Prompt / Feature Request]) --> S1

    subgraph Phase1 ["1. Discovery & Alignment"]
        S1[🧠 Socratic Brainstorming] --> S1A{Spec Agreed?}
        S1A -- No --> S1B[Clarify Intent & Edge Cases]
        S1B --> S1
    end

    S1A -- Yes --> S2

    subgraph Phase2 ["2. Environment Isolation"]
        S2[🌳 Isolated Git Worktree] --> S2A[Baseline Test Verification]
    end

    S2A --> S3

    subgraph Phase3 ["3. Deterministic Planning"]
        S3[📋 Bite-Sized Implementation Plan] --> S3A[Atomic DAG Tasks 2-5m each]
    end

    S3A --> S4

    subgraph Phase4 ["4. Subagent TDD Execution Loop"]
        S4[🤖 Subagent Task Implementer]
        S4 --> T1[🔴 Write Failing Test RED]
        T1 --> T2[🟢 Minimal Implementation GREEN]
        T2 --> T3[🔵 Refactor & Simplify]
        T3 --> R1{Independent Subagent Review}
        R1 -- Changes Requested --> S4
        R1 -- Approved --> NextTask{More Tasks?}
        NextTask -- Yes --> S4
    end

    NextTask -- No --> S5

    subgraph Phase5 ["5. Delivery & Verification"]
        S5[🏁 Full Regression Test Suite] --> S5A[Merge / Squash / Pull Request]
        S5A --> S5B[Clean Worktree Teardown]
    end

    S5B --> End([🚀 Production-Ready Feature])

    style Start fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#fff
    style End fill:#0f172a,stroke:#34d399,stroke-width:2px,color:#fff
    style S1 fill:#1e1b4b,stroke:#818cf8,stroke-width:2px,color:#fff
    style S2 fill:#1e293b,stroke:#06b6d4,stroke-width:2px,color:#fff
    style S3 fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fff
    style S4 fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#fff
    style S5 fill:#1e1b4b,stroke:#c084fc,stroke-width:2px,color:#fff

Loading

1. Socratic Discovery (brainstorming)

The agent pauses before touching code. It presents options, surfaces unconsidered edge cases, and seeks your explicit approval on the specification.

2. Workspace Isolation (using-git-worktrees)

Creates an isolated git worktree for the task. Your main branch remains completely untouched, allowing you to continue other work in parallel.

3. Bite-Sized Planning (writing-plans)

Constructs an implementation plan of 2-to-5-minute subtasks. Every subtask specifies target file paths, expected code diffs, and verification commands.

4. Subagent-Driven Execution (subagent-driven-development)

Dispatches dedicated subagents for each task. Implementers adhere strictly to Test-Driven Development (Red-Green-Refactor). Reviewers independently evaluate spec compliance and code quality.

5. Verified Branch Completion (finishing-a-development-branch)

Runs your full test suite, guides your merge or PR strategy, and cleanly dissolves the worktree without leaving orphaned files.

Tip

Zero Manual Invocation: Augment bootstraps automatically at session start via using-augment. Skills trigger contextually as needed — no magic prompts or custom commands required.

---

Harness Support & Installation

Augment runs natively across 6 major AI coding environments:

🟣 Claude Code

Install from Anthropic's official directory:

/plugin install augment@claude-plugins-official

Or add the community marketplace for early preview builds:

/plugin marketplace add fhmio/augment-marketplace
/plugin install augment@augment-marketplace

🚀 Antigravity CLI (agy)

Install directly from the official repository:

agy plugin install https://github.com/fhmio/augment

Antigravity automatically executes the session-start hook; skills are active from your very first message.

🟩 OpenAI Codex (Desktop & CLI)

Codex Desktop App:

1. Open the Codex App and navigate to Plugins in the sidebar.
2. Search for Augment under the Coding category.
3. Click Install and confirm.

Codex CLI:

/plugins
# Type: augment
# Select: Install Plugin

💻 Cursor

In the Cursor Agent chat interface:

/add-plugin augment

Or search for augment in the Cursor Plugin Directory.

♊ Gemini CLI

Install the official extension:

gemini extensions install https://github.com/fhmio/augment

To update:

gemini extensions update augment

⚡ OpenCode

Add the plugin reference in your workspace opencode.json:

{
  "plugin": ["augment@git+https://github.com/fhmio/augment.git#v0.1.0"]
}

Or ask OpenCode directly:

Fetch and follow instructions from https://raw.githubusercontent.com/fhmio/augment/refs/heads/main/.opencode/INSTALL.md

See docs/README.opencode.md for full configuration details.

---

Skills Catalog

All skills live in skills/ and adhere to vendor-neutral action mappings:

Category	Skill	Purpose	Key Outcome
🎯 Discovery	brainstorming	Socratic requirements extraction & edge-case discovery	Clear, agreed-upon spec before code
	writing-plans	Bite-sized DAG task planning with exact verification steps	Zero hallucination during execution
🏗️ Execution	using-git-worktrees	Workspace isolation using ephemeral git worktrees	Main branch safety & clean baseline
	subagent-driven-development	Dispatching isolated implementers & independent reviewers	Unbiased code quality verification
	executing-plans	Sequential task orchestration with checkpoint gates	Continuous progress with human oversight
	dispatching-parallel-agents	Multi-agent concurrency for non-overlapping tasks	High-throughput parallel execution
	finishing-a-development-branch	Structured branch merging, PR formatting & cleanup	Flawless, regression-free delivery
🔬 Quality	test-driven-development	Enforced Red-Green-Refactor development cycle	High test coverage & bug prevention
	systematic-debugging	4-phase root cause isolation (no guessing allowed)	Deterministic bug resolution
	verification-before-completion	Evidence collection before claiming any task is done	"Show me the logs" accountability
	requesting-code-review	Rigorous pre-merge self-inspection & lint audit	Production-grade code cleanliness
	receiving-code-review	Critical evaluation of review feedback without blind compliance	Principled, thoughtful code fixes
🧩 Meta	using-augment	Session bootstrap & cross-harness tool translation	Universal cross-platform consistency
	writing-skills	Authoring & automated verification of new agent skills	Extensibility and custom workflows

---

Engineering Principles

Augment enforces four non-negotiable software engineering tenets:

╔══════════════════════════════════╦═══════════════════════════════════════════════════════════════╗
║ Principle                        ║ Rule of Law                                                   ║
╠══════════════════════════════════╬═══════════════════════════════════════════════════════════════╣
║ 1. Test-Driven Development       ║ Never write implementation code without a failing test first. ║
║ 2. Systematic over Ad-Hoc        ║ Follow proven engineering protocols; eliminate guesswork.    ║
║ 3. Complexity Reduction          ║ Elegance and simplicity triumph over clever abstractions.     ║
║ 4. Evidence over Assertions      ║ Never claim work is complete without fresh terminal proof.    ║
╚══════════════════════════════════╩═══════════════════════════════════════════════════════════════╝

---

Community & Contributing

Augment is created and maintained by Fahmi Farid.

• 💬 Discussions & Issues: github.com/fhmio/augment/issues
• 🤝 Contributing: Contributions are welcome! Please read the Contributing Guide and open PRs against main.
• 📜 Creating Custom Skills: Refer to skills/writing-skills/SKILL.md for conventions and verification steps.

---

License

Augment is open-source software licensed under the MIT License.