A universal framework for AI-assisted development that works across Claude Code, Cursor, GitHub Copilot, and Gemini CLI. Includes a comprehensive skills library inspired by Superpowers.
- Planning Skills - Brainstorming, writing plans, executing plans
- Testing Skills - TDD, verification before completion
- Debugging Skills - Systematic debugging, root cause tracing, defense in depth
- Development Skills - Git worktrees, finishing branches, subagent workflows
- Meta Skills - Creating skills, writing skills
Plus:
- Slash Commands -
/dev:brainstorm,/dev:write-plan,/dev:execute-plan - Automatic Integration - Skills activate automatically when relevant
- Multi-Tool Support - Works with Claude Code, Cursor, Copilot, Gemini
# In your project directory
git clone https://github.com/walcon/ai-framework.git .ai
.ai/setup.shThis will:
- Add
.ai/to your.gitignore - Create
.ai-local/context.mdfor project-specific settings - Generate all tool-specific files
- Test-Driven Development - Write tests first, always
- Systematic over ad-hoc - Process over guessing
- Complexity reduction - Simplicity as primary goal
- Evidence over claims - Verify before declaring success
- Brainstorm before coding - Design before implementation
ai-framework/
├── context.md # Your default working style
├── rules.md # Your universal coding standards
├── build.sh # Generates tool files
├── setup.sh # Project initialization
├── hooks/ # Session start hooks
│
├── agents/
│ ├── code-reviewer.md # Code quality review
│ ├── test-writer.md # Test generation
│ ├── prd-writer.md # Product requirements
│ ├── story-creator.md # User stories from PRDs
│ └── security-auditor.md # Security review
│
├── commands/
│ ├── ai.md # Load framework context for editing
│ ├── dev/
│ │ ├── brainstorm.md # Interactive design refinement
│ │ ├── write-plan.md # Create implementation plan
│ │ ├── execute-plan.md # Execute plan in batches
│ │ ├── new-feature.md # Scaffold new feature
│ │ ├── fix-issue.md # Fix from issue ID
│ │ ├── pr-create.md # Create PR with description
│ │ └── code-review.md # Review current changes
│ ├── po/
│ │ ├── write-prd.md # Draft PRD
│ │ ├── create-stories.md # Stories from PRD
│ │ └── release-notes.md # Generate release notes
│ └── meta/
│ ├── create-agent.md # Create new agent
│ ├── create-command.md # Create new command
│ ├── create-skill.md # Create new skill
│ ├── improve-prompt.md # Refine existing prompt
│ └── sync.md # Update framework
│
└── skills/
├── using-framework/ # Introduction to using skills
├── brainstorming/ # Socratic design refinement
├── writing-plans/ # Detailed implementation plans
├── executing-plans/ # Batch execution with checkpoints
├── test-driven-development/ # RED-GREEN-REFACTOR cycle
├── systematic-debugging/ # 4-phase root cause process
├── verification-before-completion/ # Evidence before claims
├── root-cause-tracing/ # Find the real problem
├── defense-in-depth/ # Multiple validation layers
├── dispatching-parallel-agents/ # Concurrent subagent workflows
├── using-git-worktrees/ # Parallel development branches
├── finishing-a-development-branch/ # Merge/PR decision workflow
├── subagent-driven-development/ # Fast iteration with quality gates
├── code-review/ # Systematic code review
└── writing-skills/ # Create new skills
Skills activate automatically when relevant. For example:
test-driven-developmentactivates when implementing featuressystematic-debuggingactivates when debugging issuesverification-before-completionactivates before claiming work is donebrainstormingactivates before writing code
1. Brainstorm a design:
/dev:brainstorm
Refines rough ideas into fully-formed designs through collaborative questioning.
2. Create an implementation plan:
/dev:write-plan
Creates detailed implementation plans with exact file paths and complete code.
3. Execute the plan:
/dev:execute-plan docs/plans/2024-01-15-feature.md
Executes in controlled batches with review checkpoints.
After running setup.sh or build.sh, your project will have:
your-project/
├── .ai/ # This framework (gitignored)
├── .ai-local/ # Project overrides (committed)
│ └── context.md # Project-specific details
│
├── CLAUDE.md # Generated - Claude Code instructions
├── AGENTS.md # Generated - Multi-tool instructions
├── GEMINI.md # Generated - Gemini CLI instructions
│
├── .claude/
│ ├── agents/ # Symlinks to agents
│ └── commands/ # Symlinks to commands
│
├── .cursor/
│ ├── rules/index.mdc # Generated rules
│ └── commands/ # Symlinks to commands
│
├── .github/
│ ├── copilot-instructions.md # Generated instructions (with skill refs)
│ ├── prompts/ # Commands as .prompt.md
│ └── agents/ # Symlinks to agents
│
└── .agent/
└── skills/ # Symlinks to skills
**Note:** AGENTS.md, GEMINI.md, and .github/copilot-instructions.md automatically include skill references so non-Claude tools can discover and use skills.
| Tool | Syntax | Example |
|---|---|---|
| Claude Code | /namespace:command |
/dev:new-feature auth |
| Cursor | /command |
/new-feature auth |
| GitHub Copilot | /command |
/dev-new-feature auth |
In Claude Code, invoke agents by name:
- "Use the code-reviewer agent to review my changes"
- "Ask the security-auditor to check this PR"
- Edit
.ai-local/context.mdwith your project details - Optionally add
.ai-local/rules.mdfor project-specific rules - Add project-specific agents in
.ai-local/agents/ - Run
.ai/build.shto regenerate files
cd .ai
git pull
cd ..
.ai/build.shOr use the sync command: /meta:sync
Always loaded at session start. Contains project context and coding standards.
On-demand prompts invoked with /command-name. Only loaded when called.
Specialized AI instances with their own context window. Useful for isolated tasks.
Procedural knowledge loaded on-demand by the AI. Contains step-by-step instructions for specialized tasks. Skills activate automatically when relevant:
| Skill | Use When |
|---|---|
brainstorming |
Before writing code, refining ideas |
writing-plans |
Design complete, need implementation tasks |
executing-plans |
Given a plan to implement |
test-driven-development |
Implementing any feature or bugfix |
systematic-debugging |
Encountering bugs or test failures |
verification-before-completion |
About to claim work is done |
root-cause-tracing |
Errors deep in execution |
defense-in-depth |
Invalid data causes deep failures |
using-git-worktrees |
Need isolated workspace |
finishing-a-development-branch |
Implementation complete |
Session start hooks that inject skill awareness into every conversation.
Use /ai to load full framework context, then describe what you want:
- "Add a command that generates API docs"
- "Create an agent for database migrations"
- "Add a skill for performance optimization"
# agents/my-agent.md
---
name: my-agent
description: What it does. When to use it.
tools: Read, Grep, Glob
model: sonnet
---
## Role
Your role description.
## Task
What to do.
## Output Format
How to format output.# commands/category/my-command.md
---
description: What it does
argument-hint: <arg-name>
---
# Command Title: $ARGUMENTS
## Steps
1. First step
2. Second step
## Output
What to produce.# skills/my-skill/SKILL.md
---
name: my-skill
description: Use when [triggering conditions] - [what it does]
---
# My Skill
## Overview
Core principle in 1-2 sentences.
## When to Use
- Specific symptoms and situations
- When NOT to use
## The Process
Step-by-step instructions.
## Common Mistakes
What goes wrong + fixes.| Component | Location | Purpose |
|---|---|---|
| context.md | Root | Your working style (all projects) |
| rules.md | Root | Coding standards (all projects) |
| agents/ | Root | Reusable AI agents |
| commands/ | Root | Reusable commands |
| skills/ | Root | Procedural knowledge |
| hooks/ | Root | Session start hooks |
| .ai-local/context.md | Per-project | Project-specific context |
| .ai-local/rules.md | Per-project | Project-specific rules |
Skills library inspired by Superpowers by Jesse Vincent.
MIT