fleet-commander-ai 0.0.1

package/templates/guides/devops-conventions.md

@@ -0,0 +1,192 @@
+# DevOps / Infrastructure Conventions
+
+> Applies to: `.github/workflows/*.yml`, `Dockerfile`, `docker-compose.yml`, `*.sh`, `*.ps1`, `Makefile`
+> Last updated: 2026-03-18
+
+## Architecture
+
+Infrastructure code typically lives in these locations:
+
+```
+.github/workflows/   -- GitHub Actions CI/CD pipelines
+docker/              -- Dockerfiles and compose files (or project root)
+scripts/             -- Build, deploy, and utility scripts
+k8s/ or deploy/      -- Kubernetes manifests, Helm charts
+infra/               -- Terraform, Pulumi, or other IaC
+```
+
+Read `CLAUDE.md` and existing CI config before making changes. Match the project's
+existing patterns for pipeline structure, script conventions, and deployment approach.
+
+## CI/CD — GitHub Actions
+
+### Pinned versions
+
+Always use pinned action versions, not `@main` or floating tags:
+
+```yaml
+# RIGHT
+uses: actions/checkout@v4
+uses: actions/setup-node@v4
+
+# WRONG
+uses: actions/checkout@main
+```
+
+### Permissions block
+
+Set explicit `permissions` on every workflow. Use least-privilege:
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+```
+
+### Matrix strategies
+
+Use matrices for multi-version testing. Include `fail-fast: false` when you want
+all combinations to run:
+
+```yaml
+strategy:
+  fail-fast: false
+  matrix:
+    node-version: [18, 20, 22]
+    os: [ubuntu-latest, windows-latest]
+```
+
+### Secrets
+
+- Never hardcode secrets in workflows -- use `${{ secrets.NAME }}`.
+- Never echo or log secret values.
+- Use environment-level secrets for deployment-specific values.
+
+## Docker
+
+### Multi-stage builds
+
+Use multi-stage builds to minimize image size:
+
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+CMD ["node", "dist/index.js"]
+```
+
+### Layer caching
+
+Order Dockerfile instructions from least-changing to most-changing. Copy
+dependency files before source code so dependency installation is cached.
+
+### .dockerignore
+
+Always maintain a `.dockerignore` file. Include at minimum:
+`node_modules`, `.git`, `*.md`, `tests/`, `.env*`.
+
+## Scripts
+
+### Cross-platform compatibility
+
+When the project supports both Windows and Linux:
+
+- Provide both `.sh` and `.ps1` versions, or use a tool that runs on both (Node.js, Python).
+- Use forward slashes in paths within scripts -- bash on Windows handles them.
+- Avoid platform-specific commands without alternatives (`sed` on Windows needs Git Bash).
+- Ensure shell scripts use LF line endings -- CRLF breaks shebang lines on Linux.
+
+### Idempotency
+
+Scripts must be safe to run multiple times. Check for existing state before
+creating resources:
+
+```bash
+# RIGHT -- idempotent
+mkdir -p "$TARGET_DIR"
+[ -f "$CONFIG" ] || cp template.conf "$CONFIG"
+
+# WRONG -- fails on second run
+mkdir "$TARGET_DIR"
+cp template.conf "$CONFIG"
+```
+
+### Error handling
+
+Use `set -euo pipefail` in bash scripts. Check exit codes for critical operations.
+
+## Anti-Patterns to Avoid
+
+### Hardcoded paths and URLs
+
+Never hardcode environment-specific values. Use environment variables or
+configuration files:
+
+```bash
+# WRONG
+curl https://api.prod.example.com/deploy
+
+# RIGHT
+curl "${DEPLOY_URL}/deploy"
+```
+
+### Skipping YAML validation
+
+Always validate YAML syntax before committing pipeline changes. A typo in a
+workflow file can break CI for the entire team.
+
+### Database migrations without rollback
+
+Database migrations must be reversible. Always provide a down/rollback migration.
+Test migrations against a fresh database to catch ordering issues.
+
+## Testing Infrastructure Changes
+
+- **GitHub Actions**: Use `act` for local testing when possible, or create a
+  draft PR to trigger the workflow.
+- **Docker**: Build and run locally before pushing. Test with `docker build --no-cache`.
+- **Scripts**: Run scripts in a clean environment to verify they work without
+  pre-existing state.
+
+## Build & Run
+
+```bash
+# GitHub Actions
+act -j build                    # Run locally with act
+gh workflow run ci.yml          # Trigger manually
+
+# Docker
+docker build -t app:test .      # Build image
+docker compose up -d            # Start services
+
+# Scripts
+bash scripts/install.sh         # Run install script
+shellcheck scripts/*.sh         # Lint shell scripts
+```
+
+## Common Pitfalls
+
+### GitHub Actions caching
+
+Cache keys must include the lockfile hash. Stale caches cause mysterious build
+failures. Use `hashFiles('**/package-lock.json')` or equivalent.
+
+### Docker build context size
+
+A missing `.dockerignore` sends the entire repo (including `node_modules` and
+`.git`) as build context, making builds slow. Check context size if builds are
+unexpectedly slow.
+
+### Script encoding on Windows
+
+Git on Windows may convert LF to CRLF. Bash scripts with CRLF line endings fail
+with cryptic errors (`$'\r': command not found`). Use `.gitattributes` to force
+LF for shell scripts: `*.sh text eol=lf`.

package/templates/guides/fsharp-conventions.md

@@ -0,0 +1,201 @@
+# F# Conventions
+
+> Applies to: `*.fs`, `*.fsi`, `*.fsx`, `*.fsproj`
+> Last updated: 2026-03-18
+
+## Architecture
+
+F# projects use a layered module structure. Files compile top-to-bottom in the
+order listed in the `.fsproj` file. This is enforced by the compiler -- there is
+no way around it.
+
+Typical layer ordering (top of .fsproj = compiled first):
+
+```
+Domain.Types.fs         -- Discriminated unions, value objects, domain types
+Domain.Events.fs        -- Domain events
+Domain.Services.fs      -- Pure domain logic, no IO
+Application.Commands.fs -- Use-case orchestration
+Application.Queries.fs  -- Read-side projections
+Infrastructure.Db.fs    -- Database access (side effects live here)
+Api.Handlers.fs         -- HTTP handlers (thin, delegate to Application)
+Program.fs              -- Composition root, DI wiring, app startup (always last)
+```
+
+Each file can only reference types and functions defined in files listed above it.
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Modules | PascalCase, noun | `module OrderProcessing` |
+| Functions | camelCase, verb | `let calculateTotal items = ...` |
+| Types (DUs, records) | PascalCase | `type OrderStatus = Pending \| Shipped` |
+| DU cases | PascalCase | `Pending`, `Shipped`, `Cancelled` |
+| Parameters | camelCase | `orderId`, `customerName` |
+| Private helpers | prefix with underscore or nest in local scope | `let _validate x = ...` |
+| Test functions | backtick names describing behavior | `` let `calculateTotal returns zero for empty list` () = `` |
+
+## Patterns to Follow
+
+### Discriminated unions for domain modeling
+
+Prefer DUs over class hierarchies. Encode business rules in the type system so
+invalid states are unrepresentable:
+
+```fsharp
+type Email = private Email of string
+module Email =
+    let create (s: string) =
+        if s.Contains("@") then Ok (Email s)
+        else Error "Invalid email"
+    let value (Email s) = s
+```
+
+### Railway-oriented programming
+
+Use `Result<'T, 'E>` for operations that can fail. Chain with `Result.bind`
+or a `result {}` computation expression:
+
+```fsharp
+let processOrder orderId =
+    validateOrder orderId
+    |> Result.bind checkInventory
+    |> Result.bind chargePayment
+    |> Result.bind shipOrder
+```
+
+### Pipeline style
+
+Prefer pipelines over nested function calls:
+
+```fsharp
+// Good
+orders
+|> List.filter (fun o -> o.Status = Active)
+|> List.sortBy (fun o -> o.CreatedAt)
+|> List.take 10
+
+// Avoid
+List.take 10 (List.sortBy (fun o -> o.CreatedAt) (List.filter (fun o -> o.Status = Active) orders))
+```
+
+### Computation expressions
+
+Use `async {}` for legacy async, `task {}` for .NET Task interop. Match whichever
+the project already uses -- do not mix styles within a module.
+
+```fsharp
+let fetchOrder (id: OrderId) = task {
+    let! result = db.QueryAsync<Order>(id)
+    return result |> Option.ofObj
+}
+```
+
+## Anti-Patterns to Avoid
+
+### Mutable state in domain logic
+
+Never use `mutable` in domain types or domain service functions. Mutation is
+acceptable only in infrastructure code (e.g., filling a buffer) and must be
+isolated behind a pure interface.
+
+### Classes for domain models
+
+Do not create classes with inheritance hierarchies for domain concepts. Use
+discriminated unions and records. Classes are acceptable for infrastructure
+(e.g., a repository implementation) but not for domain types.
+
+### Ignoring Result errors
+
+Never discard a `Result` value or convert it to an exception unless you are at
+an application boundary (e.g., an HTTP handler returning 400/500):
+
+```fsharp
+// WRONG -- silently ignores failure
+let _ = processOrder orderId
+
+// RIGHT -- handle both cases
+match processOrder orderId with
+| Ok order -> handleSuccess order
+| Error e -> handleFailure e
+```
+
+### Float/double for financial values
+
+Never use `float` or `double` for money, prices, quantities, or financial
+calculations. Use `decimal` exclusively. Floating-point rounding errors
+compound silently in financial contexts.
+
+```fsharp
+// WRONG
+let total: float = price * quantity
+
+// RIGHT
+let total: decimal = price * quantity
+```
+
+## Dependencies & Imports
+
+- Open modules explicitly -- avoid `[<AutoOpen>]` on new modules unless the
+  project already uses it extensively.
+- Prefer `open` at the top of the file, not inside functions.
+- Group opens: FSharp.Core / System first, then third-party, then project modules.
+- Do not add NuGet packages without confirming they are needed for the task.
+
+## Testing
+
+- **Framework**: Match whatever the project uses (Expecto, xUnit+FsUnit, NUnit).
+- **Property-based tests**: Use FsCheck for functions with well-defined input/output
+  contracts (e.g., `serialize >> deserialize = id`).
+- **Assertions**: Prefer Unquote (`test <@ expr @>`) or FsUnit matchers over
+  raw `Assert.Equal` when the project supports them.
+- **Test file placement**: Mirror the source file in a parallel test project.
+  If source is `Domain.Orders.fs`, test is `Domain.OrdersTests.fs`.
+- Run `dotnet test` and fix all failures before committing.
+
+## Build & Run
+
+```bash
+dotnet build           # Compile -- catches type errors and .fsproj ordering issues
+dotnet test            # Run all tests
+dotnet run             # Run the application (if applicable)
+```
+
+Always run `dotnet build` immediately after adding a new `.fs` file to catch
+compilation order errors early. If you get "not defined" or "not recognized"
+errors, the problem is almost certainly file ordering in `.fsproj`.
+
+## Common Pitfalls
+
+### .fsproj file ordering (CRITICAL)
+
+F# compiles files strictly top-to-bottom as listed in the `.fsproj` `<Compile>`
+items. When adding a new file:
+
+1. **Read the `.fsproj` first** -- understand the current order.
+2. **Insert the new `<Compile Include="..." />` at the correct position** --
+   after its dependencies, before its dependents.
+3. **Run `dotnet build` immediately** -- do not write more code until the build passes.
+
+If build fails with "The type 'X' is not defined" or "The namespace 'Y' is not
+defined", check `.fsproj` order FIRST. This is the most common F# build failure.
+
+### Module vs namespace
+
+- `namespace Foo` -- groups types, cannot contain `let` bindings at top level.
+- `module Foo` -- can contain `let` bindings, types, and nested modules.
+
+Match whatever the project uses. Do not switch conventions within a project.
+
+### Partial application surprises
+
+Be explicit with parameter counts. A function `let add x y = x + y` partially
+applied as `add 1` returns a function, not a value. This is correct behavior
+but can surprise when passing to higher-order functions that expect a value.
+
+### Equality semantics
+
+F# records and DUs have structural equality by default. Classes do not. If you
+wrap a class in a record, the record's equality will use reference equality for
+that field. Use `[<CustomEquality; CustomComparison>]` if needed.

package/templates/guides/python-conventions.md

@@ -0,0 +1,146 @@
+# Python Conventions
+
+> Applies to: `*.py`, `pyproject.toml`, `requirements.txt`, `setup.cfg`
+> Last updated: 2026-03-18
+
+## Architecture
+
+Python projects vary widely. Read `CLAUDE.md` and the project's entry point to
+understand the framework and structure before making changes.
+
+Common patterns:
+
+```
+src/
+  app/            -- Application code
+    models/       -- Database models / domain entities
+    services/     -- Business logic
+    api/          -- Route handlers / views
+    schemas/      -- Pydantic models / serializers
+  tests/          -- Test files (mirror src structure)
+  migrations/     -- Database migrations (Alembic / Django)
+```
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Modules | snake_case | `order_service.py`, `user_repository.py` |
+| Classes | PascalCase | `OrderService`, `UserRepository` |
+| Functions | snake_case | `get_order_by_id`, `calculate_total` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES`, `DEFAULT_TIMEOUT` |
+| Private | underscore prefix | `_validate_input`, `_cache` |
+| Type variables | single uppercase or descriptive | `T`, `ReturnType` |
+
+## Patterns to Follow
+
+### Type hints
+
+Add type hints to all new function signatures. Use `typing` module types for
+complex signatures:
+
+```python
+from typing import Optional, Sequence
+
+def get_orders(user_id: int, limit: Optional[int] = None) -> Sequence[Order]:
+    ...
+```
+
+### Framework patterns
+
+- **Django**: Use class-based views when they fit, function-based for simple endpoints.
+  Create migrations with `makemigrations` -- never edit migration files manually.
+- **Flask**: Use blueprints for route organization. Register extensions in the
+  application factory.
+- **FastAPI**: Use Pydantic models for request/response schemas. Use dependency
+  injection for services and database sessions.
+
+### Async patterns
+
+- Use `async/await` with asyncio when the framework supports it (FastAPI, aiohttp).
+- Use `async with` for context managers that manage connections or sessions.
+- Do not mix sync and async code without explicit bridges (`asyncio.to_thread`
+  for sync-in-async, `asyncio.run` for async-in-sync at boundaries only).
+
+## Anti-Patterns to Avoid
+
+### Mutable default arguments
+
+```python
+# WRONG -- shared mutable default
+def add_item(item: str, items: list[str] = []) -> list[str]:
+    items.append(item)
+    return items
+
+# RIGHT -- use None sentinel
+def add_item(item: str, items: list[str] | None = None) -> list[str]:
+    if items is None:
+        items = []
+    items.append(item)
+    return items
+```
+
+### Bare except clauses
+
+Never catch `Exception` or use bare `except:` unless you are at an application
+boundary (middleware, CLI entry point). Catch specific exception types.
+
+### os.path for file operations
+
+Prefer `pathlib.Path` over `os.path` for all file operations:
+
+```python
+# Prefer
+from pathlib import Path
+config_path = Path("config") / "settings.json"
+
+# Avoid
+import os
+config_path = os.path.join("config", "settings.json")
+```
+
+## Dependencies & Imports
+
+- Activate the project's virtualenv before running any Python commands.
+- Import order: stdlib, third-party, local (match existing style or use isort).
+- Do not add packages without confirming they are needed for the task.
+- Check for the project's dependency tool: `requirements.txt`, `pyproject.toml`,
+  `poetry`, or `uv`.
+
+## Testing
+
+- **Framework**: pytest (fixtures, parametrize, conftest) or unittest -- match the project.
+- **Naming**: `test_function_name_condition_expected_result` or the project's convention.
+- **Fixtures**: Use `conftest.py` for shared fixtures. Prefer fixture factories
+  over complex fixture chains.
+- **Parametrize**: Use `@pytest.mark.parametrize` for testing multiple inputs.
+- **Mocking**: Use `unittest.mock.patch` or `monkeypatch` -- mock at boundaries only.
+- Run `pytest` (or project-specific command) and fix all failures before committing.
+
+## Build & Run
+
+```bash
+python -m pytest          # Run tests
+python -m mypy .          # Type check (if project uses mypy)
+python -m black --check . # Format check (if project uses black)
+pip install -e .          # Install in development mode
+```
+
+## Common Pitfalls
+
+### Import errors from circular dependencies
+
+Python resolves imports at module load time. Circular imports cause
+`ImportError` or `AttributeError`. Fix by moving shared types to a separate
+module or using `TYPE_CHECKING` guards for type-only imports.
+
+### Django migration conflicts after rebase
+
+If another branch added a migration, yours may conflict. Delete your migration
+and recreate with `python manage.py makemigrations`. Never manually merge
+migration files.
+
+### Forgetting to close resources
+
+Use context managers (`with` statements) for files, database connections, and
+HTTP sessions. Do not rely on garbage collection to close resources.

package/templates/guides/sql-database.md

@@ -0,0 +1,125 @@
+# SQL & Database Conventions
+
+> Applies to: `*.sql`, migration files, ORM model definitions, database access code
+> Last updated: 2026-03-18
+
+## Migration Discipline
+
+- Always use the project's migration framework (Alembic, Django migrations,
+  EF Core migrations, Flyway, Knex, Prisma). Never run raw DDL against production.
+- Migrations must be reversible -- provide both up and down operations.
+- Never edit a migration that has already been applied to any environment.
+- Test migrations against a fresh database to catch ordering issues.
+- After rebase, if migration files conflict, delete yours and regenerate against
+  the rebased model state. Never manually merge migration files.
+
+## Schema Conventions
+
+### Naming
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Tables | snake_case, plural | `orders`, `pull_requests`, `usage_snapshots` |
+| Columns | snake_case | `created_at`, `issue_number`, `ci_status` |
+| Primary keys | `id` (integer auto-increment or UUID) | `id INTEGER PRIMARY KEY` |
+| Foreign keys | `{referenced_table_singular}_id` | `team_id`, `project_id` |
+| Indexes | `idx_{table}_{columns}` | `idx_events_team_id_created_at` |
+| Boolean columns | `is_` or `has_` prefix | `is_active`, `has_hooks` |
+| Timestamp columns | `_at` suffix | `created_at`, `merged_at`, `stopped_at` |
+
+### Required columns
+
+Every table should have:
+- A primary key (`id`)
+- `created_at` timestamp (set on insert, never updated)
+- `updated_at` timestamp (set on insert, updated on every modification) -- optional
+  for append-only tables like events or logs
+
+## Query Optimization
+
+### Avoid N+1 queries
+
+Never fetch a list of items and then query related data in a loop. Use JOINs,
+subqueries, or the ORM's eager loading:
+
+```sql
+-- WRONG: N+1
+SELECT * FROM teams;
+-- then for each team:
+SELECT * FROM events WHERE team_id = ?;
+
+-- RIGHT: single query
+SELECT t.*, e.* FROM teams t
+LEFT JOIN events e ON e.team_id = t.id;
+```
+
+### Index frequently filtered columns
+
+Add indexes for columns that appear in WHERE, JOIN, ORDER BY, or GROUP BY clauses.
+Foreign key columns should always be indexed.
+
+### Use EXPLAIN
+
+Before committing complex queries, run `EXPLAIN` (or `EXPLAIN ANALYZE`) to verify
+the query plan uses indexes and does not perform full table scans on large tables.
+
+## Transaction Safety
+
+- Use explicit transactions for multi-step operations. Do not rely on auto-commit
+  for operations that must be atomic.
+- Keep transactions short -- do not hold locks while performing external API calls
+  or expensive computations.
+- Handle deadlocks gracefully -- retry with backoff when appropriate.
+
+## ORM Patterns
+
+### Lazy vs eager loading
+
+- Use eager loading (JOINs / includes) for data you know you will need.
+- Use lazy loading only when you rarely need the related data.
+- Never traverse lazy relationships inside a loop -- this causes N+1.
+
+### Connection pooling
+
+- Use the ORM's built-in connection pool. Never open connections manually unless
+  the framework requires it.
+- Set pool size appropriate for the workload. For SQLite, a pool size of 1 is
+  typical (single-writer constraint).
+
+## SQLite-Specific
+
+When working with SQLite (better-sqlite3 or similar):
+
+- Enable WAL mode for concurrent reads: `PRAGMA journal_mode=WAL;`
+- Use synchronous API -- better-sqlite3 is synchronous by design. Do not wrap
+  calls in async wrappers unnecessarily.
+- SQLite has no native DATETIME type -- store timestamps as ISO 8601 strings
+  or Unix epoch integers. Be consistent within the project.
+- Use `INSERT OR REPLACE` or `ON CONFLICT` for upserts.
+- Foreign keys are off by default -- ensure `PRAGMA foreign_keys = ON` is set
+  at connection time.
+
+## Common Pitfalls
+
+### String interpolation in queries
+
+Never interpolate user input into SQL strings. Always use parameterized queries:
+
+```sql
+-- WRONG (SQL injection risk)
+SELECT * FROM users WHERE name = '${userName}';
+
+-- RIGHT (parameterized)
+SELECT * FROM users WHERE name = ?;
+```
+
+### Missing NOT NULL constraints
+
+Default to `NOT NULL` for all columns unless NULL has a meaningful semantic
+(e.g., `stopped_at` is NULL while a team is still running). Nullable columns
+require NULL checks everywhere they are used.
+
+### Large transactions in SQLite
+
+SQLite uses a single-writer model. Long-running write transactions block all
+other writers. Keep write transactions as short as possible.