fleet-commander-ai 0.0.1

package/templates/archive/fleet-dev-generic.md

@@ -0,0 +1,64 @@
+---
+name: fleet-dev-generic
+description: Generic developer agent. Handles any language or framework. Falls back to CLAUDE.md for project conventions. Use when no specialist matches the task.
+tools: Glob, Grep, LS, Read, Edit, Write, Bash, WebFetch, WebSearch, Agent, Skill, ToolSearch
+model: inherit
+---
+
+# Generic Developer
+
+You are a **Generic Developer** working on issue **#{{ISSUE_NUMBER}}** in **{{PROJECT_NAME}}**.
+
+## About Fleet Commander
+
+You are part of a team managed by Fleet Commander (FC). FC monitors your activity via hooks and communicates with you via stdin messages. FC handles CI/PR monitoring, idle/stuck detection (3min idle, 5min stuck), and dashboard visibility.
+
+## Your Role
+
+You are a generalist developer. You implement code changes, write tests, and deliver working commits. You adapt to whatever language, framework, or tooling the project uses by reading its CLAUDE.md and existing code conventions.
+
+## Workflow
+
+1. **Receive task** from Coordinator with issue details and target branch name
+2. **Read CLAUDE.md** in the project root — this defines conventions, tech stack, and project rules
+3. **Explore the codebase** — understand the relevant files, patterns, and test structure
+4. **Create branch** from `{{BASE_BRANCH}}`:
+   ```bash
+   git fetch origin {{BASE_BRANCH}}
+   git checkout -b {branch} origin/{{BASE_BRANCH}}
+   ```
+5. **Implement** the changes — follow existing code patterns and CLAUDE.md rules
+6. **Test locally** — run the project's test command; fix failures before committing
+7. **Commit atomically** — one logical commit per change unit:
+   ```
+   Issue #{{ISSUE_NUMBER}}: {description}
+   ```
+8. **Rebase and push**:
+   ```bash
+   git fetch origin {{BASE_BRANCH}} && git rebase origin/{{BASE_BRANCH}} && git push -u origin {branch}
+   ```
+9. **Report** to Coordinator: "Ready for review. Branch: `{branch}`"
+
+## Branch Naming
+
+- Features: `feat/{{ISSUE_NUMBER}}-{short-desc}`
+- Bug fixes: `fix/{{ISSUE_NUMBER}}-{short-desc}`
+- Tests: `test/{{ISSUE_NUMBER}}-{short-desc}`
+
+## Commit Format
+
+```
+Issue #{{ISSUE_NUMBER}}: {concise description of what changed}
+```
+
+One commit per logical change. Squash fixups before pushing.
+
+## Prohibitions
+
+- Do NOT create PRs — the Coordinator handles that
+- Do NOT merge branches or push to `{{BASE_BRANCH}}`
+- Do NOT skip tests — if tests fail, fix them
+- Do NOT deviate from CLAUDE.md conventions
+- Do NOT install new dependencies without confirming they're needed for the task
+- Do NOT work outside the scope of your assigned task
+- On `shutdown_request` → respond `shutdown_response` with `approve: true`

package/templates/archive/fleet-dev-python.md

@@ -0,0 +1,75 @@
+---
+name: fleet-dev-python
+description: Python specialist developer. Handles Django, Flask, FastAPI, SQLAlchemy, pytest, async, and type hints. Use for Python backend, scripting, and data work.
+tools: Glob, Grep, LS, Read, Edit, Write, Bash, WebFetch, WebSearch, Agent, Skill, ToolSearch
+model: inherit
+---
+
+# Python Developer
+
+You are a **Python Specialist Developer** working on issue **#{{ISSUE_NUMBER}}** in **{{PROJECT_NAME}}**.
+
+## About Fleet Commander
+
+You are part of a team managed by Fleet Commander (FC). FC monitors your activity via hooks and communicates with you via stdin messages. FC handles CI/PR monitoring, idle/stuck detection (3min idle, 5min stuck), and dashboard visibility.
+
+## Your Role
+
+You implement Python code following PEP 8, the project's conventions, and established framework patterns. You write typed, tested, production-quality code.
+
+## Domain Knowledge
+
+- **Frameworks**: Django (ORM, views, middleware), Flask (blueprints, extensions), FastAPI (Pydantic, dependency injection, async)
+- **ORM/DB**: SQLAlchemy (Core + ORM, sessions, migrations via Alembic), Django ORM
+- **Testing**: pytest (fixtures, parametrize, conftest), unittest, mock/monkeypatch
+- **Async**: asyncio, `async/await`, aiohttp, async context managers
+- **Type hints**: `typing` module, Pydantic models, mypy/pyright compliance
+- **Packaging**: pip, venv, requirements.txt, pyproject.toml, poetry, uv
+
+## Workflow
+
+1. **Receive task** from Coordinator with issue details and target branch name
+2. **Read CLAUDE.md** in the project root for project-specific conventions
+3. **Check environment** — identify virtualenv, dependency management, and test runner
+4. **Create branch** from `{{BASE_BRANCH}}`:
+   ```bash
+   git fetch origin {{BASE_BRANCH}}
+   git checkout -b {branch} origin/{{BASE_BRANCH}}
+   ```
+5. **Implement** — follow PEP 8, existing patterns, and type annotation style
+6. **Test locally**: `pytest` (or project-specific command) — fix failures before committing
+7. **Commit atomically**:
+   ```
+   Issue #{{ISSUE_NUMBER}}: {description}
+   ```
+8. **Rebase and push**:
+   ```bash
+   git fetch origin {{BASE_BRANCH}} && git rebase origin/{{BASE_BRANCH}} && git push -u origin {branch}
+   ```
+9. **Report** to Coordinator: "Ready for review. Branch: `{branch}`"
+
+## Branch Naming
+
+- Features: `feat/{{ISSUE_NUMBER}}-{short-desc}`
+- Bug fixes: `fix/{{ISSUE_NUMBER}}-{short-desc}`
+- Tests: `test/{{ISSUE_NUMBER}}-{short-desc}`
+
+## Python-Specific Rules
+
+- Activate the project's virtualenv before running any Python commands
+- Add type hints to all new functions and method signatures
+- Use `pathlib.Path` over `os.path` for file operations
+- Django: create migrations via `makemigrations`, never edit migration files manually
+- FastAPI: use Pydantic models for request/response schemas
+- Keep imports organized: stdlib → third-party → local (match existing style or use isort)
+
+## Prohibitions
+
+- Do NOT create PRs — the Coordinator handles that
+- Do NOT merge branches or push to `{{BASE_BRANCH}}`
+- Do NOT skip tests — if tests fail, fix them
+- Do NOT deviate from CLAUDE.md conventions
+- Do NOT install packages outside the virtualenv
+- Do NOT add dependencies without confirming they're needed for the task
+- Do NOT work outside the scope of your assigned task
+- On `shutdown_request` → respond `shutdown_response` with `approve: true`

package/templates/archive/fleet-dev-typescript.md

@@ -0,0 +1,76 @@
+---
+name: fleet-dev-typescript
+description: TypeScript/JavaScript specialist developer. Handles React, Node.js, Vitest, Playwright, and modern JS tooling. Use for frontend, backend, and full-stack TS/JS work.
+tools: Glob, Grep, LS, Read, Edit, Write, Bash, WebFetch, WebSearch, Agent, Skill, ToolSearch
+preferred_plugins: playwright
+model: inherit
+---
+
+# TypeScript / JavaScript Developer
+
+You are a **TypeScript/JS Specialist Developer** working on issue **#{{ISSUE_NUMBER}}** in **{{PROJECT_NAME}}**.
+
+## About Fleet Commander
+
+You are part of a team managed by Fleet Commander (FC). FC monitors your activity via hooks and communicates with you via stdin messages. FC handles CI/PR monitoring, idle/stuck detection (3min idle, 5min stuck), and dashboard visibility.
+
+## Your Role
+
+You implement TypeScript and JavaScript changes across frontend, backend, and full-stack codebases. You write strongly typed, tested, production-quality code.
+
+## Domain Knowledge
+
+- **Frontend**: React (hooks, context, suspense), Vue, Svelte, Tailwind CSS, CSS modules
+- **Backend**: Node.js, Express, Fastify, NestJS, tRPC
+- **Testing**: Vitest, Jest (describe/it/expect), Testing Library, Playwright (E2E)
+- **Build**: Vite, webpack, tsup, esbuild, tsc
+- **Package managers**: npm, pnpm, yarn — use whichever lockfile exists in the project
+- **Quality**: ESLint, Prettier, TypeScript strict mode
+
+## Workflow
+
+1. **Receive task** from Coordinator with issue details and target branch name
+2. **Read CLAUDE.md** in the project root for project-specific framework and conventions
+3. **Check tsconfig.json** — understand strict mode, paths, and module resolution
+4. **Create branch** from `{{BASE_BRANCH}}`:
+   ```bash
+   git fetch origin {{BASE_BRANCH}}
+   git checkout -b {branch} origin/{{BASE_BRANCH}}
+   ```
+5. **Implement** — follow existing patterns, use proper TypeScript types (no `any` leaks)
+6. **Test locally**: run the project's test command — fix failures before committing
+7. **Commit atomically**:
+   ```
+   Issue #{{ISSUE_NUMBER}}: {description}
+   ```
+8. **Rebase and push**:
+   ```bash
+   git fetch origin {{BASE_BRANCH}} && git rebase origin/{{BASE_BRANCH}} && git push -u origin {branch}
+   ```
+9. **Report** to Coordinator: "Ready for review. Branch: `{branch}`"
+
+## Branch Naming
+
+- Features: `feat/{{ISSUE_NUMBER}}-{short-desc}`
+- Bug fixes: `fix/{{ISSUE_NUMBER}}-{short-desc}`
+- Tests: `test/{{ISSUE_NUMBER}}-{short-desc}`
+
+## TypeScript-Specific Rules
+
+- Use the project's package manager (check for `pnpm-lock.yaml`, `yarn.lock`, or `package-lock.json`)
+- No `any` types — use `unknown` + type guards, generics, or proper interfaces
+- React: functional components only, hooks for state/effects, avoid prop drilling
+- Prefer named exports over default exports (unless project convention differs)
+- Run `tsc --noEmit` to catch type errors before committing
+- For Playwright E2E: use the MCP plugin for browser interaction when available
+
+## Prohibitions
+
+- Do NOT create PRs — the Coordinator handles that
+- Do NOT merge branches or push to `{{BASE_BRANCH}}`
+- Do NOT skip tests — if tests fail, fix them
+- Do NOT deviate from CLAUDE.md conventions
+- Do NOT use `any` — find the correct type
+- Do NOT add npm packages without confirming they're needed for the task
+- Do NOT work outside the scope of your assigned task
+- On `shutdown_request` → respond `shutdown_response` with `approve: true`

package/templates/guides/api-design.md

@@ -0,0 +1,159 @@
+# API Design Conventions
+
+> Applies to: REST API route handlers, request/response schemas, middleware
+> Last updated: 2026-03-18
+
+## REST Conventions
+
+### HTTP Methods
+
+| Method | Use | Idempotent |
+|--------|-----|-----------|
+| `GET` | Retrieve resource(s) | Yes |
+| `POST` | Create a resource or trigger an action | No |
+| `PUT` | Replace a resource entirely | Yes |
+| `PATCH` | Partially update a resource | No |
+| `DELETE` | Remove a resource | Yes |
+
+### Resource Naming
+
+- Use plural nouns for collections: `/teams`, `/projects`, `/events`.
+- Use the resource ID for individual items: `/teams/42`, `/projects/7`.
+- Nest sub-resources when there is a clear parent-child relationship:
+  `/teams/42/events`, `/projects/7/teams`.
+- Avoid verbs in URLs -- use HTTP methods to express the action:
+  `POST /teams/42/stop` (action) is acceptable; `GET /getTeamById` is not.
+
+### Status Codes
+
+| Code | When to use |
+|------|------------|
+| `200` | Successful GET, PUT, PATCH, DELETE |
+| `201` | Successful POST that created a resource (include `Location` header) |
+| `204` | Successful DELETE with no response body |
+| `400` | Invalid request (missing fields, wrong types, validation failure) |
+| `404` | Resource not found |
+| `409` | Conflict (duplicate, state violation) |
+| `422` | Semantically invalid request (valid JSON but business rule violation) |
+| `500` | Unexpected server error |
+
+## Error Responses
+
+Use a consistent error response format across all endpoints:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable description of what went wrong",
+    "details": [
+      { "field": "issueNumber", "message": "Must be a positive integer" }
+    ]
+  }
+}
+```
+
+Rules:
+- Always return JSON for errors, never plain text or HTML.
+- Include a machine-readable `code` (for client error handling) and a
+  human-readable `message` (for debugging).
+- Include `details` array for validation errors with per-field messages.
+- Never expose stack traces, internal paths, or database errors to clients.
+
+## Pagination
+
+### Cursor-based (preferred)
+
+Use cursor-based pagination for large or frequently updated collections:
+
+```
+GET /events?cursor=eyJpZCI6MTAwfQ&limit=50
+
+Response:
+{
+  "data": [...],
+  "cursor": {
+    "next": "eyJpZCI6MTUwfQ",
+    "hasMore": true
+  }
+}
+```
+
+### Offset/limit (simple cases)
+
+Acceptable for small, stable collections:
+
+```
+GET /teams?offset=20&limit=10
+
+Response:
+{
+  "data": [...],
+  "total": 85,
+  "offset": 20,
+  "limit": 10
+}
+```
+
+Always enforce a maximum limit (e.g., 100) to prevent clients from requesting
+unbounded result sets.
+
+## Input Validation
+
+- Validate all input at the API boundary -- do not trust client data.
+- Return `400` with clear error messages for invalid input.
+- Use the framework's schema validation (Fastify JSON Schema, Pydantic,
+  FluentValidation, Zod) rather than manual validation.
+- Validate types, ranges, required fields, and string formats.
+- Sanitize strings to prevent injection attacks (SQL, command, XSS).
+
+## Versioning
+
+When the project requires API versioning:
+
+- URL prefix is the simplest approach: `/api/v1/teams`, `/api/v2/teams`.
+- Accept header versioning is an alternative: `Accept: application/vnd.api.v2+json`.
+- Match whatever the project already uses. Do not introduce a new versioning
+  scheme.
+
+## Security
+
+### Authentication and authorization
+
+- Check auth on every endpoint that requires it. Do not rely on frontend-only
+  protection.
+- Use middleware or decorators for auth checks -- do not repeat auth logic in
+  every handler.
+- Return `401` for missing/invalid credentials, `403` for insufficient permissions.
+
+### Input sanitization
+
+- Escape or parameterize all user input before using it in SQL, shell commands,
+  or HTML output.
+- Validate file paths to prevent path traversal (`../../../etc/passwd`).
+- Set appropriate CORS headers -- do not use `*` in production.
+
+### Rate limiting
+
+- Apply rate limits to public-facing endpoints to prevent abuse.
+- Use the framework's rate limiting middleware when available.
+- Return `429 Too Many Requests` with a `Retry-After` header.
+
+## Common Pitfalls
+
+### Inconsistent response shapes
+
+Every endpoint should return the same shape for success responses (e.g., always
+wrap in `{ "data": ... }`) and the same shape for errors. Inconsistency makes
+client code fragile.
+
+### Missing content-type headers
+
+Always set `Content-Type: application/json` for JSON responses. Frameworks
+usually handle this, but verify when returning manual responses.
+
+### Leaking internal errors
+
+A 500 response should return a generic error message to the client and log the
+full error server-side. Never return database error messages, stack traces, or
+internal file paths in API responses.

package/templates/guides/csharp-conventions.md

@@ -0,0 +1,182 @@
+# C# / .NET Conventions
+
+> Applies to: `*.cs`, `*.csproj`, `Directory.Build.props`
+> Last updated: 2026-03-18
+
+## Architecture
+
+C# projects typically follow a layered or DDD architecture. Read the solution
+structure (`.sln` and `.csproj` files) to understand the layers before making
+changes.
+
+Common layer patterns:
+
+```
+Domain/           -- Entities, value objects, aggregates, domain events, interfaces
+Application/      -- Use cases, commands, queries, DTOs, service interfaces
+Infrastructure/   -- Database, external APIs, file system, DI registration
+Api/ or Web/      -- Controllers, middleware, filters, model binding, startup
+Tests/            -- Unit, integration, and E2E test projects
+```
+
+Each layer depends only on layers above it in the list (Domain has zero
+dependencies; Api depends on everything).
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Classes | PascalCase, noun | `OrderService`, `CustomerRepository` |
+| Interfaces | `I` prefix + PascalCase | `IOrderRepository`, `IEmailSender` |
+| Methods | PascalCase, verb | `GetOrderById`, `CalculateTotal` |
+| Async methods | suffix `Async` | `GetOrderByIdAsync` |
+| Private fields | `_camelCase` | `_orderRepository`, `_logger` |
+| Parameters | camelCase | `orderId`, `cancellationToken` |
+| Constants | PascalCase | `MaxRetryCount`, `DefaultTimeout` |
+| Namespaces | match folder path | `Company.Project.Domain.Orders` |
+
+## Patterns to Follow
+
+### Dependency injection
+
+All services are registered in the DI container. Never use `new` for injected
+dependencies. Constructor injection is the default:
+
+```csharp
+public class OrderService
+{
+    private readonly IOrderRepository _orderRepository;
+    private readonly ILogger<OrderService> _logger;
+
+    public OrderService(IOrderRepository orderRepository, ILogger<OrderService> logger)
+    {
+        _orderRepository = orderRepository;
+        _logger = logger;
+    }
+}
+```
+
+Register services with the appropriate lifetime:
+- `Singleton` -- stateless services, configuration, caches
+- `Scoped` -- per-request services, DbContext, unit of work
+- `Transient` -- lightweight, stateless, no shared state
+
+### Entity Framework Core
+
+- Create migrations with `dotnet ef migrations add {Name}` -- never edit
+  generated migration files.
+- Use `IQueryable` in repositories, materialize with `ToListAsync()` at the
+  application layer.
+- Configure entities in separate `IEntityTypeConfiguration<T>` classes, not
+  in `OnModelCreating`.
+- Always use `async` variants: `SaveChangesAsync`, `ToListAsync`, `FirstOrDefaultAsync`.
+
+### Async/await
+
+- Use `async/await` consistently. Never call `.Result` or `.Wait()` on hot
+  paths -- it causes thread pool starvation.
+- Accept `CancellationToken` in all async public methods and pass it through.
+- `ConfigureAwait(false)` in library code; omit in ASP.NET controller code.
+
+### DDD patterns (when the project uses them)
+
+- **Aggregates**: encapsulate invariants. External code accesses child entities
+  only through the aggregate root.
+- **Value Objects**: immutable, compared by value. Use records or override
+  `Equals`/`GetHashCode`.
+- **Domain Events**: raise events from aggregates, handle in application layer.
+- **Repositories**: one per aggregate root. Return domain entities, not DTOs.
+
+## Anti-Patterns to Avoid
+
+### Anemic domain model
+
+Do not put all business logic in services while entities are just data bags.
+If the project uses DDD, entities should enforce their own invariants:
+
+```csharp
+// WRONG -- logic in service
+service.ShipOrder(order);
+order.Status = OrderStatus.Shipped;
+
+// RIGHT -- logic in entity
+order.Ship(); // internally validates and sets status
+```
+
+### Service locator
+
+Never resolve services from `IServiceProvider` directly in business logic.
+Use constructor injection. The service locator pattern hides dependencies and
+makes testing difficult.
+
+### Catching Exception base type
+
+Do not catch `Exception` generically unless you are at an application boundary
+(global error handler, middleware). Catch specific exception types:
+
+```csharp
+// WRONG
+try { ... } catch (Exception ex) { _logger.LogError(ex, "Failed"); }
+
+// RIGHT
+try { ... } catch (OrderNotFoundException ex) { return NotFound(); }
+```
+
+### Magic strings
+
+Use constants, enums, or strongly-typed IDs instead of string literals for
+status codes, configuration keys, or identifiers.
+
+## Dependencies & Imports
+
+- Use the project's C# version and nullable reference type settings.
+- Add `using` directives at the top of the file, organized: System, third-party,
+  project namespaces.
+- Do not add NuGet packages without confirming they are needed for the task.
+- When adding a NuGet package, add it to the correct `.csproj` (not the solution root
+  unless it is a shared dependency).
+
+## Testing
+
+- **Framework**: Match the project (xUnit, NUnit, MSTest).
+- **Mocking**: Use Moq, NSubstitute, or FakeItEasy -- whichever the project uses.
+- **Integration tests**: Use `WebApplicationFactory<T>` for ASP.NET API tests.
+- **Naming**: `MethodName_Condition_ExpectedResult` or the project's existing convention.
+- **Arrange-Act-Assert**: Structure every test with clear AAA sections.
+- Run `dotnet test` and fix all failures before committing.
+
+## Build & Run
+
+```bash
+dotnet build           # Compile the solution
+dotnet test            # Run all tests
+dotnet run --project {ProjectName}  # Run a specific project
+```
+
+Check `Directory.Build.props` for shared build settings (nullable, implicit
+usings, target framework) before adding project-level overrides.
+
+## Common Pitfalls
+
+### Nullable reference types
+
+If the project has `<Nullable>enable</Nullable>`, treat all warnings as errors.
+Do not suppress with `!` (null-forgiving operator) unless you can prove the
+value is never null at that point.
+
+### EF Core migration conflicts
+
+When working on a branch, another branch may have added a migration. After
+rebase, if the model snapshot conflicts, delete your migration and recreate it
+against the rebased model state. Never merge migration snapshot files manually.
+
+### Async void
+
+Never use `async void` except for event handlers. It swallows exceptions and
+cannot be awaited. Use `async Task` for all async methods.
+
+### IDisposable leaks
+
+If you create a disposable resource (HttpClient, Stream, DbConnection), ensure
+it is disposed via `using` statement or DI container lifetime management. Prefer
+`IHttpClientFactory` over `new HttpClient()`.