diff --git a/README.md b/README.md
new file mode 100644
index 0000000..59c4939
--- /dev/null
+++ b/README.md
@@ -0,0 +1,177 @@
+# Claude Code AI Workflow
+
+A composable toolkit for enhancing [Claude Code](https://claude.ai/claude-code) with structured workflows, issue management, and AI-assisted development practices.
+
+## Why This Project?
+
+Claude Code is powerful, but its effectiveness depends on how you use it. This project provides:
+
+- **Structured workflows** for common development tasks (issue tracking, PR reviews, planning)
+- **Composable components** that build on each other (skills, agents, commands)
+- **Forgejo integration** for seamless issue and PR management
+- **Consistent patterns** that make AI assistance more predictable and effective
+
+## Core Concepts
+
+The project is built around three composable component types:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      COMMANDS                           │
+│         User-facing entry points (/work-issue)          │
+│                         │                               │
+│                         ▼                               │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │                    AGENTS                        │   │
+│  │    Subprocesses with isolated context            │   │
+│  │    (parallel processing, complex workflows)      │   │
+│  │                      │                           │   │
+│  │                      ▼                           │   │
+│  │  ┌───────────────────────────────────────────┐  │   │
+│  │  │                 SKILLS                     │  │   │
+│  │  │   Reusable knowledge modules               │  │   │
+│  │  │   (forgejo, issue-writing, planning)       │  │   │
+│  │  └───────────────────────────────────────────┘  │   │
+│  └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+| Component | Purpose | Example |
+|-----------|---------|---------|
+| **Commands** | Entry points users invoke directly | `/work-issue 42` starts implementation workflow |
+| **Skills** | Domain knowledge modules | `issue-writing` knows how to structure good issues |
+| **Agents** | Autonomous subprocesses | `product-manager` combines skills for complex planning |
+
+## Quick Start
+
+### Prerequisites
+
+- [Claude Code CLI](https://claude.ai/claude-code) installed
+- [Forgejo CLI](https://code.forgejo.org/forgejo/forgejo-cli) (`fj`) for issue/PR management
+
+### Installation
+
+```bash
+# Clone the repository
+git clone ssh://git@code.flowmade.one/flowmade-one/ai.git
+cd ai
+
+# Install symlinks to ~/.claude/
+make install
+```
+
+### Forgejo Setup
+
+```bash
+# Install forgejo-cli
+brew install forgejo-cli
+
+# Authenticate (one-time)
+echo "YOUR_TOKEN" | fj -H code.flowmade.one auth add-key username
+
+# Required token scopes: read:user, read:repository, write:issue, write:repository
+```
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/dashboard` | Show open issues and PRs for the current repo |
+| `/work-issue <n>` | Fetch issue, create branch, implement, and create PR |
+| `/review-pr <n>` | Review a PR with diff analysis and feedback |
+| `/create-issue` | Create single or batch issues interactively |
+| `/plan-issues <desc>` | Break down a feature into discrete issues |
+| `/groom [n]` | Improve issue quality (single or batch) |
+| `/roadmap` | Visualize issues by status and dependencies |
+
+## Project Structure
+
+```
+ai/
+├── commands/           # Slash commands invoked by users
+│   ├── work-issue.md
+│   ├── dashboard.md
+│   ├── review-pr.md
+│   ├── create-issue.md
+│   ├── plan-issues.md
+│   ├── groom.md
+│   └── roadmap.md
+├── skills/             # Reusable knowledge modules
+│   ├── forgejo/        # Forgejo CLI integration
+│   ├── issue-writing/  # Issue structure best practices
+│   ├── backlog-grooming/  # Backlog maintenance
+│   └── roadmap-planning/  # Feature breakdown
+├── agents/             # Specialized subagents
+│   └── product-manager/  # Combines skills for PM tasks
+├── scripts/            # Git hooks and utilities
+│   └── pre-commit-checks.sh
+├── settings.json       # Claude Code configuration
+├── Makefile            # Symlink management
+└── CLAUDE.md           # Instructions for Claude Code
+```
+
+## Example Workflows
+
+### Working on an Issue
+
+```
+> /work-issue 42
+
+Fetching issue #42: "Add user authentication"
+Creating branch: feature/42-add-user-authentication
+Planning implementation...
+[Claude implements the feature]
+Creating PR with reference to issue...
+```
+
+### Planning a Feature
+
+```
+> /plan-issues Add dark mode support
+
+Proposed Issues:
+1. Create theme context and provider
+2. Add theme toggle component
+3. Update components to use theme variables
+4. Add system preference detection
+
+Create these issues? [y/n]
+```
+
+### Daily Standup
+
+```
+> /dashboard
+
+Open Issues (3):
+| #  | Title                    | Labels      |
+|----|--------------------------|-------------|
+| 42 | Add user authentication  | feature     |
+| 38 | Fix login redirect       | bug         |
+| 35 | Update dependencies      | maintenance |
+
+Open PRs (1):
+| #  | Title                    | Status      |
+|----|--------------------------|-------------|
+| 41 | Add password reset flow  | review      |
+```
+
+## Configuration
+
+The `settings.json` configures Claude Code behavior:
+
+- **Model selection**: Uses Opus for complex tasks
+- **Status line**: Shows git branch and status
+- **Hooks**: Pre-commit validation for secrets and YAML
+
+## Uninstall
+
+```bash
+make uninstall
+```
+
+This removes symlinks from `~/.claude/` and restores any backed-up files.
+
+## License
+
+MIT