AI-Guided Engineering — Navigate → Think → Ship
A minimal framework for AI-assisted coding with phase-based workflows, auto-activating skills, and enforced tool safety. Works with VS Code Copilot and Claude Code.
| Component | Count | What It Does |
|---|---|---|
| Agents | 4 | Phase-based workflow with enforced tool restrictions and handoff buttons |
| Skills | 9 | Auto-activate based on your prompts (debug, mentor, architecture, etc.) |
| Instructions | 5 | File-type coding standards that load automatically |
git clone https://github.com/mcouthon/agents.git
cd agents
./install.shThat's it. Use /agent or the Chat menu to select agents, or just talk naturally and let skills auto-activate.
"The highest leverage point is at the end of research and the beginning of the plan. A human can skim 30 seconds and provide feedback that saves hours of incorrect implementation."
This framework is built around that insight. The Explore agent is read-only—it can't accidentally edit your code. You review its research and plan, then hand off to Implement when you're ready.
Explore ──→ Implement ──→ Review ──→ Commit
│ │
│ └──→ Fix Issues ──→ (back to Implement)
│
└──→ Commit (skip review for small changes)
| Agent | Purpose | Tool Access | Key Handoffs |
|---|---|---|---|
| Explore | Research + create plans | Read + Task Write | Implement |
| Implement | Execute planned changes | Full access | Review, Commit |
| Review | Verify implementation quality | Read + Test | Commit Changes, Fix Issues |
| Commit | Create semantic commits | Git + Read | Push |
Task Write: Explore can only write to .tasks/ directory—not your codebase.
Automatic state persistence: Explore saves research to .tasks/[NNN]-[task-name]/ so you can resume across sessions. Tasks are numbered sequentially (001, 002, etc.) for chronological ordering.
In-context actions: Each agent has handoff buttons for common next steps that keep your chat history and context intact. To switch agents, just @ mention them (e.g., @Implement when ready to start coding).
Each agent has buttons that trigger common next steps without leaving your current chat context:
| Agent | Button | Purpose |
|---|---|---|
| Explore | Implement | Hand off to Implement agent |
| Plan Next Phase | Detailed plan for next unplanned phase | |
| Re-explore | Investigate further | |
| Show Plan | Display phase status from task.md | |
| Save | Persist research to .tasks/ |
|
| Implement | Review | Hand off to Review agent |
| Commit | Hand off to Commit agent | |
| Check for Errors | Run linting and type checks | |
| Run Tests | Execute the test suite | |
| Review | Commit Changes | Hand off to Commit agent |
| Fix Issues | Hand off to Implement to address problems | |
| Re-review | Check again after fixes are applied | |
| Check Tests | Run tests and verify they pass | |
| Commit | Review Commits | Show commits with git log |
| Amend Last Commit | Amend the last commit with staged changes | |
| Push | Push commits to remote |
Key benefit: These buttons keep your context and chat history. No reset, no re-explaining.
Skills activate automatically based on what you say:
| You Say | Skill Activated |
|---|---|
| "This test is failing" | debug |
| "Find code smells" | tech-debt |
| "Clean up dead code" | tech-debt |
| "Document the architecture" | architecture |
| "Teach me how this works" | mentor |
| "Challenge my approach" | critic |
| "Create a Makefile" | makefile |
| "Build a dashboard UI" | design |
| "Security review this PR" | security-review |
No manual switching required—just ask naturally.
| AGENTS Is | AGENTS Isn't |
|---|---|
| Advisory guidance | Mandatory enforcement |
| Phase-based workflow | Magic one-shot agent |
| Minimal and composable | Batteries-included framework |
| IDE-agnostic patterns | Cursor/Claude-specific |
| Human-in-the-loop at key points | Fully autonomous |
After ./install.sh:
| Component | Installed To |
|---|---|
| Agents (VS Code) | ~/Library/Application Support/Code/User/prompts/ |
| Commands (Claude Code) | ~/.claude/commands/ |
| Skills | ~/.copilot/skills/ (with ~/.claude/skills symlink) |
| Instructions | ~/Library/Application Support/Code/User/prompts/ |
| Task state gitignore | Added to global gitignore (.tasks/) |
Agents are available using @agent-<Name> syntax in Claude Code:
| Command | Purpose |
|---|---|
@agent-Explore <task> |
Research and plan |
@agent-Implement |
Execute the plan |
@agent-Review |
Verify changes |
@agent-Commit |
Create semantic commits |
Example workflow:
$ claude
> @agent-Explore add user authentication
[Claude researches, produces plan]
> @agent-Implement
[Claude implements based on conversation context]
> @agent-Review
[Claude reviews changes]
> @agent-Commit
[Claude creates commits]
Note: VS Code agent features like tool restrictions, model selection, and handoff buttons are not available in Claude Code. Skills work identically on both platforms.
Create .github/agents/my-agent.agent.md:
---
name: My Agent
description: What this agent does and when to use it.
tools: ["codebase", "search", "editFiles"]
model: Claude Sonnet 4 # Optional
handoffs:
- label: Next Step
agent: other-agent
prompt: Continue with the next phase.
---
# My Agent Instructions
Your detailed instructions here.Create .github/skills/my-skill/SKILL.md:
---
name: my-skill
description: >
Trigger keywords for auto-activation: "keyword1", "keyword2".
Focus on WHEN to use (symptoms), not WHAT it does.
---
# My Skill Instructions
Your instructions here (< 500 lines recommended).- RED - Run task WITHOUT the skill, note failures
- GREEN - Add skill, verify improvement
- REFACTOR - If agent rationalizes around it, strengthen guidance
If you didn't see it fail without the skill, you don't know if the skill helps.
Run ./install.sh after adding agents or skills.
Explore persists state to .tasks/[NNN]-[task-name]/:
.tasks/001-add-auth/
task.md # Research + phases + main plan
plan/
phase-1-config.md # Detailed plan for phase 1 (optional)
phase-2-user-model.md # Detailed plan for phase 2 (optional)
- Initial research →
task.mdwith research findings + phase table - Plan Next Phase (optional) → detailed plan for complex phases →
plan/phase-N-[name].md - Implement → picks smallest planned unit (phase plan if exists, else task.md)
- Mark phase ✅ Done, repeat
| Agent | Reads | Updates |
|---|---|---|
| Explore | task.md, plan/*.md |
task.md, plan/*.md, phase status |
| Implement | Phase plan or task.md |
Phase status (⬜→📋→🔄→✅) |
| Review | All plan + implement | — |
To continue a task: Just say "Continue working on [task-name]"
| Use Case | Use |
|---|---|
| Need enforced tool restrictions | Agent |
| Need handoffs between phases | Agent |
| Want auto-activation from prompts | Skill |
| Role-based workflow phases | Agent |
| Specialized methodologies | Skill |
.github/
├── agents/ # Workflow phases (Explore, Implement, Review, Commit)
└── skills/ # Auto-activating capabilities (debug, mentor, etc.)
instructions/ # File-type coding standards
├── global.instructions.md
├── python.instructions.md
├── typescript.instructions.md
├── testing.instructions.md
└── terminal.instructions.md
docs/
├── synthesis/ # Core principles and framework analysis
└── research/ # Research Decision Records (RDRs)
Skills not auto-activating?
- Run
./install.shto ensure symlinks exist - Check
~/.github/skills/for your skills - Be more explicit: "Use debug mode to investigate..."
Need to uninstall?
./install.sh uninstallWe welcome contributions! See CONTRIBUTING.md for guidelines.
Quick ways to contribute:
| Topic | Document |
|---|---|
| Core principles | prevailing-wisdom.md |
| Framework analysis | framework-comparison.md |
| Memory & session continuity | memory-and-continuity.md |
| Research decisions | docs/research/ |
| 12-Factor Agents | docs/sources/12-factor-agents/ |
Synthesized from multiple frameworks into something minimal and useful:
- 12 Factor Agents — Control flow ownership
- HumanLayer ACE — Context engineering, human leverage points
- CursorRIPER — Permission boundaries
- Superpowers — Skill quality, TDD for documentation
- Awesome Copilot — Agent and instruction patterns
Model recommendation: Claude Opus 4.5 for heavy lifting. When Sonnet struggles, Opus delivers.