Skills and configuration for AI coding agents. Works with Claude Code, OpenCode, Codex, and Amp.

The guide skill orchestrates a full learning workflow:

┌─────────────────────────────────────────────────────────────────────────┐
│                              guide skill                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│  │ Clarify  │───▶│   Plan   │───▶│  Teach   │───▶│ Archive  │          │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘          │
│       │               │               │               │                 │
│       ▼               ▼               ▼               ▼                 │
│  ask-questions   create-plan     Guide through   history/YYYY-MM-DD-   │
│  skill           workflow        each item       plan-<name>.md        │
│                  ─▶ PLAN.md      with hints                            │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

1. Clarify — Uses ask-questions to gather requirements one at a time (voice-friendly)
2. Plan — Creates PLAN.md with action items, scope, and documentation links
3. Teach — Guides you through each step with hints, not solutions
4. Archive — Moves completed plan to history/YYYY-MM-DD-plan-<name>.md

For standalone planning without teaching, use create-plan directly.

The Ralph Wiggum technique lets you run an AI agent in a loop until work is complete. Based on Geoffrey Huntley's methodology.

Wiggum supports two modes:

Uses a PLAN.md file with checkboxes. Exits when all [ ] become [x].

┌─────────────────────────────────────────────────────────────────────────┐
│                      Plan Mode Loop                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│  │  Plan    │───▶│  Pick    │───▶│ Complete │───▶│  Commit  │──┐       │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘  │       │
│       │               │               │               │        │       │
│       ▼               ▼               ▼               ▼        │       │
│  create-plan     ONE task        Verify via       git commit   │       │
│  ─▶ PLAN.md      from plan       tests/lint       (no push)   │       │
│                                                                 │       │
│                  ◀──────────────────────────────────────────────┘       │
│                       Loop until all tasks [x] complete                 │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Step 1: Create a plan

amp "create a plan for adding user authentication"
# or
claude "create a plan for adding user authentication"

Step 2: Run the loop

wiggum PLAN.md                      # Interactive (confirm each task)
wiggum --auto PLAN.md               # Autonomous (let it run)
wiggum --auto --max 20 PLAN.md      # With iteration limit

Uses a prompt string. Exits when Claude outputs <promise>DONE</promise>.

Best for well-defined, verifiable tasks without a plan file:

# Fix lint errors until clean
wiggum --prompt "Fix all ESLint errors. Run npm run lint to verify."

# Make tests pass
wiggum --auto --prompt "Make all tests in src/auth pass" --promise "TESTS_PASS"

# Refactor with verification
wiggum --prompt "Convert all class components to functional components"

How it works: Each iteration, Claude sees the current codebase state (including changes from previous iterations). The codebase carries the progress, even though each Claude instance is stateless.

• Stateless iterations — Each run re-reads full context, preventing drift
• Plan evolution — Claude updates the plan when reality diverges (splits tasks, adds blockers)
• Operational learning — Discoveries are written to AGENTS.md for future iterations
• Safe commits — Commits after each task, never pushes (you review and push)

"If Ralph falls off the slide, you don't just put him back — you put up a sign that says 'SLIDE DOWN, DON'T JUMP.'"

Each failure teaches what guardrails to add. Tune the plan, tune AGENTS.md, iterate.

For human-in-the-loop execution where you want oversight and learning:

┌─────────────────────────────────────────────────────────────────────────┐
│                    Manual Execution Flow                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐                    │
│  │create-plan │───▶│execute-plan│───▶│execute-plan│───▶ ... ───▶ Done │
│  └────────────┘    └────────────┘    └────────────┘                    │
│        │                 │                 │                 │          │
│        ▼                 ▼                 ▼                 ▼          │
│    PLAN.md          Task 1 done       Task 2 done       Archive spec to│
│    created          + summary         + summary         specs/         │
│                                                                         │
│  Human triggers each step. Reviews. Commits when ready.                 │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Workflow:

1. Create a plan: "create a plan for adding OAuth support"
2. Execute tasks one at a time: "execute the plan" or "continue the plan"
3. Agent asks clarifying questions before acting
4. After each task: marks [x] and adds inline summary
5. Commit when ready: /smart-commit
6. Repeat until done, then archive SPEC.md to specs/YYYY-MM-DD-<title>.md and remove PLAN.md

Key behaviors:

• Questions first — Unlike wiggum, asks before acting (human is present)
• One task at a time — Complete focus, then hand back control
• Learning persistence — Updates AGENTS.md with project conventions discovered
• Documentation updates — Checks docs/ and updates if building user-facing features
• Plan mutations — Splits tasks, adds blockers, restructures as needed

When to use which:

Add the marketplace and install specific skills:

# Add the marketplace (one time)
/plugin marketplace add wunki/amplify

# Install individual skills
/plugin install browse-site@amplify
/plugin install frontend-design@amplify
/plugin install fetch-github-file@amplify

Or install everything at once:

/plugin install wunki/amplify

Clone and run make to install for all detected tools:

git clone https://github.com/wunki/amplify.git
cd amplify
make

This detects which tools you have installed (Claude Code, OpenCode, Codex, Amp) and copies skills, agents, and configuration to each.

To install for a specific tool only:

make claude    # Claude Code only
make opencode  # OpenCode only
make codex     # Codex only
make amp       # Amp only

Use the skill installer:

$skill-installer wunki/amplify/browse-site
$skill-installer wunki/amplify/frontend-design

Amp reads skills from .agents/skills/ in your workspace. Either:

1. Run make amp to install to ~/.config/amp/skills/
2. Or copy skills directly to your project's .agents/skills/ directory

OpenCode reads from ~/.claude/skills/, so this repo uses that shared location instead of installing a separate OpenCode skills directory.

The config/ directory contains tool-specific settings:

config/
├── AGENTS.md           # Shared agent profile (symlinked to all tools)
├── amp/
│   └── settings.json
├── codex/
│   └── config.toml
└── opencode/
    ├── opencode.json
    └── themes/

config/AGENTS.md is the shared agent profile that gets symlinked to each tool's configuration directory. Edit it once, changes propagate everywhere.

1. Create skills/<name>/SKILL.md with frontmatter:

   ---
   name: skill-name
   description: What it does. Include trigger phrases for auto-activation.
   ---

2. Add scripts/ for executable code, references/ for on-demand docs
3. Run make

Config files are symlinked (changes propagate immediately).

Skills and agents are rsynced (run make after changes).

The Makefile auto-discovers skills in skills/ and agents in agents/, then distributes them to each tool's expected location.

All three major tools use the same SKILL.md format with YAML frontmatter. The only difference is directory location. This repo handles that by:

1. Storing skills once in skills/
2. Using make to copy to each tool's directory
3. Providing a Claude Code marketplace for plugin-based installation

There's a slide deck in docs/presentation.md that explains the philosophy behind this repo. Run it with slides:

brew install slides
slides docs/presentation.md

MIT. Individual skills may have their own licenses (see LICENSE.txt in skill directories).