Dotai

<p align="center"> <h1 align="center">dotai</h1> <p align="center"> Opinionated AI coding standards for Claude Code.<br/> Security guardrails · Workflow rules · Specialized agents · One-command setup. </p> </p> <p align="center"> <img src="https://img.shields.io/badge/python-3.8+-blue?logo=python&logoColor=white" alt="Python 3.8+"/> <img src="https://img.shields.io/badge/platform-macOS%20·%20Linux%20·%20Windows-lightgrey" alt="Platforms"/> <img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License"/> <img src="https://img.shields.io/badge/AI%20Tool-Claude%20Code-blueviolet?logo=anthropic" alt="Claude Code"/> </p>

---

What Is This?

When engineers use AI coding assistants like Claude Code, the assistant follows instructions from special CLAUDE.md files. These files tell the AI how to behave, what to avoid, and how to work on your code.

Without shared standards, every engineer gets a different AI experience — and critical security rules might be missing entirely.

This repo provides a shared set of rules and specialized agents that any engineer can install with one command. Think of it as a "team policy" for your AI assistant.

flowchart LR
    A[Clone + ./setup.sh] --> B{How to run?}
    B -->|No flags| C[Interactive TUI]
    B -->|--global / --project / --both| D[Non-interactive CLI]
    C --> E["~/.claude/\nRules + Agents"]
    C --> F["Your repo\ntasks/ + settings"]
    D --> E & F

Quick Start

Setup (one time)

git clone https://github.com/Muadiv/dotai.git
cd dotai
./setup.sh                    # creates venv + installs the command

Windows? Use setup.bat instead, or skip straight to the PowerShell installer which needs no Python at all.

Run (from any directory)

dotai                    # interactive TUI
dotai --global           # install everything globally
dotai --project          # install project template here
dotai --both             # global + project
dotai --update           # pull latest, then install
dotai --update --global  # pull latest + install globally
dotai --no-tasks         # skip creating tasks/ directories
dotai --restore          # restore from latest backup
dotai --restore 20260223-120000  # restore specific backup
dotai --auto-read        # auto-approve read ops (with --project/--both)
dotai --model opus       # set Opus as default model (sonnet|opus|haiku|none)
dotai --uninstall        # remove managed files from ~/.claude/ (with backup)

No flags = interactive TUI. Any flag = non-interactive (scriptable, CI-friendly).

PowerShell (no Python required)

git clone https://github.com/Muadiv/dotai.git
cd dotai
.\install.ps1                          # interactive
.\install.ps1 -Global                  # install everything globally
.\install.ps1 -Both                    # global + project
.\install.ps1 -Update                  # pull latest, then install
.\install.ps1 -Update -Global          # pull latest + install globally
.\install.ps1 -NoTasks -Global         # skip tasks/ creation
.\install.ps1 -Restore                 # restore from latest backup
.\install.ps1 -Restore -RestoreTimestamp "20260223-120000"  # restore specific backup
.\install.ps1 -AutoRead -Project       # auto-approve read ops
.\install.ps1 -Model opus -Global     # set Opus as default model
.\install.ps1 -Uninstall              # remove managed files from ~/.claude/ (with backup)

Alternative setup methods

<details> <summary>Manual pip install (if you prefer managing your own venv)</summary>

cd dotai
python3 -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e .              # creates the `dotai` command

</details> <details> <summary>Standalone (no pip install, no venv)</summary>

cd dotai
pip install -r requirements.txt        # one-time (needs textual for TUI)
python3 install.py                     # launches TUI
python3 install.py --global            # non-interactive (works without textual)

</details>

The TUI installer is a full-screen app — navigate with arrow keys, toggle with Space, confirm with Enter, go back with Escape:

╔══════════════════════════════════════════════════════════╗
║                  AI Coding Standards                      ║
║   Standardized Claude Code configuration                  ║
╚══════════════════════════════════════════════════════════╝

  ◉ Global — CLAUDE.md + rules + agents to ~/.claude/
  ○ Project — tasks + settings in current repo
  ○ Both — global + project

          [ Next ]    [ Quit ]

╭── Select Rules ──────────────────────────────────────────╮
│  [X] Coding Standards (coding.md)                         │
│  [X] Safety Rules (safety.md)                             │
│  [X] Security Standards (security.md) [MANDATORY]         │
│  [X] Workflow Orchestration (workflow.md)                  │
╰──────────────────────────────────────────────────────────╯

---

What Gets Installed

Global (your machine)

Installed to ~/.claude/ — applies to every Claude Code session.

Rules

Rules are auto-loaded by Claude Code. They define what the AI must always do (or never do).

| File | What it does | Required? | |:-----|:-------------|:---------:| | rules/security.md | Blocks secrets in code, flags OWASP risks, data privacy | Mandatory | | rules/safety.md | Prevents accidental file deletion, destructive git ops | Optional | | rules/workflow.md | Enforces plan-first approach, verification before done | Optional | | rules/coding.md | Prevents over-engineering, keeps changes minimal | Optional |

Agents

Agents are specialized AI personas invoked via /agent-name in Claude Code. They provide deep expertise for specific tasks.

| Agent | Trigger | Model | What it does | |:------|:--------|:------|:-------------| | security-auditor | /security-auditor | opus | Scans for secrets, OWASP vulnerabilities, insecure dependencies | | compliance-reviewer | /compliance-reviewer | opus | Quality compliance, audit trails, data integrity | | code-reviewer | /code-reviewer | sonnet | Pre-PR review: bugs, style, tests, over-engineering | | architect | /architect | opus | System design, ADRs, trade-off analysis | | test-engineer | /test-engineer | sonnet | Generates tests, identifies missing coverage, edge cases | | devops | /devops | sonnet | CI/CD, Terraform/CDK, Docker, cloud infrastructure | | data-engineer | /data-engineer | sonnet | ETL pipelines, data quality, data lineage | | api-designer | /api-designer | sonnet | API contracts, OpenAPI specs, versioning, auth patterns | | doc-writer | /doc-writer | sonnet | READMEs, architecture docs, runbooks | | incident-responder | /incident-responder | opus | Production incident investigation, root cause analysis | | performance-analyst | /performance-analyst | sonnet | Profiling, bottleneck analysis, optimization recommendations | | migration-planner | /migration-planner | opus | Migration strategies, rollback plans, data integrity verification |

security-auditor and compliance-reviewer are mandatory — they cannot be deselected during installation.

Project (your repo)

Project install sets up tasks/ and auto-read settings in your repository. It does not install a CLAUDE.md template — use /init inside Claude Code to auto-generate one tailored to your actual codebase.

Task Tracking

Optional tasks/ directory for AI self-improvement:

• lessons.md — The AI logs mistakes here so it doesn't repeat them
• todo.md — Tracks multi-step work across sessions

---

How It Behaves

This repo isn't just security rules. It also shapes how the AI talks to you and how it works — making interactions feel more natural and less robotic. These behavior and workflow rules are entirely optional; security standards are the only mandatory part.

Interaction style

The CLAUDE.md file sets the AI's personality:

• No filler — no "Great question!", no fake enthusiasm, no fluff
• Strong opinions — gives direct recommendations instead of "it depends"
• Brevity — says it once, clearly, and moves on
• Humor OK — humor and informal language are welcome when natural, never forced

If you prefer a more formal tone, edit ~/.claude/CLAUDE.md after install.

Plan mode behavior

By default, Claude Code rushes to produce a formal plan and exit plan mode. The workflow.md rule changes this:

• Plan mode is a conversation — the AI asks questions, challenges assumptions, and suggests alternatives before writing anything formal
• No premature formalization — the AI won't call ExitPlanMode until you explicitly say "write the plan" or "let's do it"
• Whiteboard talk — short, back-and-forth responses instead of essays

This is the biggest behavioral change from vanilla Claude Code. If you don't want it, deselect workflow.md during installation or delete ~/.claude/rules/workflow.md.

Workflow approach

The workflow.md rule also defines how the AI works on tasks:

1. Plan first — enters plan mode for any non-trivial task
2. Subagents — offloads research and parallel work to keep context clean
3. Self-improvement — logs mistakes in tasks/lessons.md and reviews them each session
4. Verification — never marks work done without proving it works
5. Elegance check — pauses on non-trivial changes to ask "is there a better way?"
6. Autonomous bug fixing — investigates and fixes bugs without hand-holding

---

What goes into ~/.claude/settings.json

The installer creates (or merges into) your global settings.json:

| Category | Keys | Purpose | |:---------|:-----|:--------| | Default model | model | Set during install — Sonnet (default), Opus, Haiku, or none | | Permissions | `al