Add complete project scaffolding for ManaMind AI agent

.actrc

@@ -0,0 +1,19 @@
+# Act configuration for local GitHub Actions testing
+# This file optimizes 'act' performance and behavior
+
+# Use smaller, faster images when possible
+-P ubuntu-latest=catthehacker/ubuntu:act-latest
+-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
+-P ubuntu-20.04=catthehacker/ubuntu:act-20.04
+
+# Speed up builds by reusing images
+--reuse
+
+# Show more helpful output
+--verbose
+
+# Don't rebuild containers unnecessarily  
+--use-gitignore
+
+# Platform settings for consistency
+--platform linux/amd64

.github/workflows/test.yml

@@ -0,0 +1,56 @@
+name: Test Suite
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Cache pip dependencies
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Run linting
+      run: |
+        black --check src tests
+        isort --check-only src tests
+        flake8 src tests
+
+    - name: Run type checking
+      run: mypy src
+
+    - name: Run tests
+      run: |
+        pytest --cov=src/manamind --cov-report=xml --cov-report=term-missing -v
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v5
+      if: matrix.python-version == '3.11'
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: ./coverage.xml
+        fail_ci_if_error: true

.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+- repo: https://github.com/psf/black
+  rev: 25.1.0
+  hooks:
+  - id: black
+    args: [--line-length=79]
+
+- repo: https://github.com/PyCQA/isort
+  rev: 5.13.2
+  hooks:
+  - id: isort
+    args: [--profile=black, --line-length=79]
+
+- repo: https://github.com/PyCQA/flake8
+  rev: 7.3.0
+  hooks:
+  - id: flake8
+
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v1.17.1
+  hooks:
+  - id: mypy
+    additional_dependencies: [types-all]
+    args: [--ignore-missing-imports]

CLAUDE.md

@@ -58,9 +58,29 @@ ManaMind is an AI agent designed to play Magic: The Gathering (MTG) at a superhu
 
 ## Development Commands
 
-*Note: This project is in early planning phase. Commands will be added as the codebase develops.*
+### Code Quality & Formatting (CRITICAL)
+Always run these commands before committing to prevent CI failures:
+```bash
+# Format code with black (79 character limit to match CI)
+black --line-length 79 src tests
+
+# Sort imports
+isort src tests
+
+# Check for linting issues 
+flake8 src tests
+
+# Type checking
+mypy src
 
-Expected future commands:
+# Run tests with coverage
+pytest --cov=src/manamind --cov-report=xml --cov-report=term-missing -v
+
+# Run all quality checks at once (recommended before commit)
+black --line-length 79 src tests && isort src tests && flake8 src tests && mypy src
+```
+
+### Training Commands (Future)
 ```bash
 # Training commands (future)
 python train.py --config configs/base.yaml
@@ -84,6 +104,66 @@ python mtga_interface.py --test-mode
 
 ## Development Guidelines
 
+### Code Quality Standards (MANDATORY)
+**CRITICAL: Always follow these practices to prevent CI failures and PR delays:**
+
+1. **Pre-commit Code Quality Checks:**
+   - Run `black --line-length 79 src tests` before every commit
+   - Run `isort src tests` to fix import ordering  
+   - Run `flake8 src tests` and fix ALL violations before committing
+   - Run `mypy src` and address type issues
+   - Use the one-liner: `black --line-length 79 src tests && isort src tests && flake8 src tests && mypy src`
+
+2. **Import Management:**
+   - Remove unused imports immediately when refactoring
+   - Use isort to maintain consistent import ordering
+   - Avoid importing modules that aren't used
+
+3. **Line Length & Formatting:**
+   - Maintain 79-character line limit (matches CI configuration)  
+   - Let black handle most formatting automatically
+   - Break long lines in function arguments, not comments
+   - Use meaningful variable names even if they're longer
+
+4. **Code Writing Best Practices:**
+   - Write code that passes linting from the start
+   - Fix linting issues as you code, not after
+   - Use type hints consistently
+   - Remove debug prints and unused variables immediately
+
+### Automation Recommendations
+To reduce PR iteration cycles, consider setting up:
+
+1. **Pre-commit hooks** (add to `.pre-commit-config.yaml`):
+   ```yaml
+   repos:
+   - repo: https://github.com/psf/black
+     rev: 25.1.0
+     hooks:
+     - id: black
+       args: [--line-length=79]
+   - repo: https://github.com/PyCQA/isort
+     rev: 5.13.2
+     hooks:
+     - id: isort
+   - repo: https://github.com/PyCQA/flake8
+     rev: 7.3.0
+     hooks:
+     - id: flake8
+   ```
+
+2. **IDE/Editor Integration:**
+   - Configure VS Code/PyCharm to run black on save
+   - Enable flake8 linting in your editor
+   - Set up mypy type checking in your IDE
+
+3. **Git Aliases** (add to ~/.gitconfig):
+   ```bash
+   [alias]
+       lint = !black --line-length 79 src tests && isort src tests && flake8 src tests && mypy src
+       commit-clean = !git add . && git lint && git commit
+   ```
+
 ### Code Organization
 - Separate training environment (Forge) from deployment environment (MTGA)
 - Modular design allowing different RL algorithms to be swapped