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 | 5 | Phase-based workflow with enforced tool restrictions and handoff buttons |
| Skills | 6 | 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
↓ ↑ ↓
Handoff (fix) Done
| Agent | Purpose | Tool Access | Handoff To |
|---|---|---|---|
| Explore | Research + create plans | Read-only | → Implement, → Handoff |
| Implement | Execute planned changes | Full access | → Review |
| Review | Verify implementation quality | Read + Test | → Commit / → Explore (re-plan) |
| Commit | Create semantic commits | Git + Read | ✅ Done |
| Handoff | Persist context for next session | Write | → Implement |
Why agents? Each phase has enforced tool restrictions (Explore can't accidentally edit code) and handoff buttons to guide you to the next step.
Skills activate automatically based on what you say:
| You Say | Skill Activated |
|---|---|
| "This test is failing" | debug |
| "Find code smells" | tech-debt |
| "Document the architecture" | architecture |
| "Teach me how this works" | mentor |
| "Clean up dead code" | janitor |
| "Challenge my approach" | critic |
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 | ~/.github/skills/ (with ~/.claude/skills symlink) |
| Instructions | ~/Library/Application Support/Code/User/prompts/ |
| Handoffs gitignore | Added to global gitignore |
Agents are available as slash commands in Claude Code:
| Command | Purpose |
|---|---|
/project:explore <task> |
Research and plan |
/project:implement |
Execute the plan |
/project:review |
Verify changes |
/project:commit |
Create semantic commits |
Example workflow:
$ claude
> /project:explore add user authentication
[Claude researches, produces plan]
> /project:implement
[Claude implements based on conversation context]
> /project:review
[Claude reviews changes]
> /project: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.
| 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, Handoff)
└── 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.