@ooneex/cli 1.36.3 → 1.36.5

package/dist/index.js

@@ -10362,7 +10362,7 @@ var package_json_default = `{
 `;
 
 // src/templates/app/README.md.txt
-var README_md_default = "# {{NAME}}\n\nA modular, enterprise-grade backend framework built with TypeScript and Bun, powered by the **@ooneex** ecosystem.\n\n## Prerequisites\n\n- [Bun](https://bun.sh) (latest)\n- [Docker](https://www.docker.com/) & Docker Compose\n\n## Getting Started\n\n### Install Dependencies\n\n```bash\nbun install\n```\n\n### Environment Configuration\n\nCopy the environment template and fill in the required values:\n\n```bash\ncp modules/app/.env.example modules/app/.env\n```\n\n| Variable | Description | Required |\n|---|---|---|\n| `APP_ENV` | Application environment (`local`, `development`, `staging`, `testing`, `production`, \u2026) | Yes |\n| `PORT` | Server port number (default: `3000`) | Yes |\n| `HOST_NAME` | Server hostname (default: `0.0.0.0`) | Yes |\n| `LOGS_DATABASE_URL` | Database URL for storing application logs | No |\n| `BETTERSTACK_LOGGER_SOURCE_TOKEN` | Logtail source token for Better Stack logging | No |\n| `BETTERSTACK_EXCEPTION_LOGGER_APPLICATION_TOKEN` | Better Stack token for exception tracking | No |\n| `ANALYTICS_POSTHOG_PROJECT_TOKEN` | PostHog API key for event tracking | No |\n| `CACHE_REDIS_URL` | Redis connection URL for caching | No |\n| `CACHE_UPSTASH_REDIS_REST_URL` | Upstash Redis REST URL for serverless caching | No |\n| `PUBSUB_REDIS_URL` | Redis connection URL for pub/sub messaging | No |\n| `RATE_LIMIT_REDIS_URL` | Redis connection URL for rate limiting | No |\n| `CORS_ORIGINS` | Comma-separated allowed origins or `*` (default: `*`) | No |\n| `CORS_METHODS` | Comma-separated HTTP methods | No |\n| `CORS_HEADERS` | Comma-separated allowed request headers | No |\n| `CORS_CREDENTIALS` | Allow credentials: `true` or `false` | No |\n| `DATABASE_URL` | PostgreSQL connection URL | No |\n| `DATABASE_REDIS_URL` | Redis connection URL for Redis-based database operations | No |\n| `SQLITE_DATABASE_PATH` | SQLite database file path | No |\n| `STORAGE_CLOUDFLARE_ACCESS_KEY` | Cloudflare R2 access key ID | No |\n| `STORAGE_CLOUDFLARE_SECRET_KEY` | Cloudflare R2 secret access key | No |\n| `STORAGE_CLOUDFLARE_ENDPOINT` | Cloudflare R2 endpoint URL | No |\n| `STORAGE_BUNNY_ACCESS_KEY` | BunnyCDN access key | No |\n| `STORAGE_BUNNY_STORAGE_ZONE` | BunnyCDN storage zone name | No |\n| `FILESYSTEM_STORAGE_PATH` | Base directory path for local file storage | No |\n| `MAILER_SENDER_NAME` | Display name for email sender | No |\n| `MAILER_SENDER_ADDRESS` | Email address for sender | No |\n| `RESEND_API_KEY` | Resend email service API key | No |\n| `JWT_SECRET` | Secret key for HS256 JWT signing and verification | No |\n| `OPENROUTER_API_KEY` | OpenRouter API key for accessing 300+ AI models | No |\n| `OPENAI_API_KEY` | OpenAI API key | No |\n| `ANTHROPIC_API_KEY` | Anthropic API key for Claude models | No |\n| `GEMINI_API_KEY` | Google Gemini API key | No |\n| `GROQ_API_KEY` | Groq API key for LLM inference | No |\n| `POLAR_ACCESS_TOKEN` | Polar payment platform access token | No |\n| `CLERK_SECRET_KEY` | Clerk authentication secret key | No |\n| `LINEAR_API_KEY` | Linear API key for issue sync (`issue:pull`, `issue:push`) | No |\n| `LINEAR_TEAM_ID` | Linear team ID \u2014 skips team selection prompt in `issue:push` | No |\n\n### Start the App\n\nStarts Docker services (if a `docker-compose.yml` is present) and launches the application with hot reload:\n\n```bash\noo app:start\n```\n\n### Stop the App\n\nStops all Docker services:\n\n```bash\noo app:stop\n```\n\n### Build the App\n\nCompiles the application for production. Output is written to the `dist` directory:\n\n```bash\noo app:build\n```\n\n---\n\n## Modules\n\nModules are the core organizational unit. Each module lives under `modules/<name>/` and contains its own controllers, services, repositories, entities, migrations, and seeds.\n\n### Why Modules?\n\nA flat codebase quickly becomes hard to navigate and reason about as an application grows. Modules address this by enforcing **vertical slicing**: all code related to a single business domain (e.g. `user`, `order`, `billing`) lives together rather than being scattered across generic `controllers/`, `services/`, and `repositories/` folders.\n\n**Benefits:**\n\n- **Domain isolation** \u2014 changes to one feature cannot accidentally break another; each module is a self-contained unit with explicit boundaries.\n- **Parallel development** \u2014 teams can work on separate modules without stepping on each other's code or creating merge conflicts in shared directories.\n- **Independent deployment** \u2014 a module can be extracted into a standalone service later with minimal refactoring because its code is already co-located.\n- **Simpler onboarding** \u2014 a new developer understands the scope of a feature by exploring a single directory instead of tracing imports across the whole project.\n- **Scoped migrations & seeds** \u2014 database changes stay close to the entities they affect, making rollbacks and reviews straightforward.\n\n**Good practices:**\n\n- Name modules after business domains (`user`, `product`, `payment`), not technical layers (`controllers`, `helpers`).\n- Keep modules small and focused. If a module grows beyond ~10 controllers or services, consider splitting it by sub-domain.\n- Never import from another module's internal files directly \u2014 expose only what is needed through the module's public index.\n- Register all entities in `SharedModule` (done automatically by `oo make:entity`) so the ORM has a single source of truth.\n- Run `oo module:lock` after every migration or seed change to protect file integrity in CI.\n- Prefix route names with the module name (e.g. `api.user.create`) to avoid collisions across modules.\n\n### Create a Module\n\nScaffolds a new module with all required structure, registers it in `AppModule`, adds its entities to `SharedModule`, and updates `tsconfig.json` path aliases and commitlint config:\n\n```bash\noo module:create\noo module:create --name user\n```\n\n### Lock a Module\n\nHashes migration and seed files into a module manifest (`.yml`) for integrity verification. Run this after adding or modifying migrations/seeds:\n\n```bash\noo module:lock --module user\noo module:lock --module user --override   # force update existing hashes\n```\n\n### Delete a Module\n\nRemoves a module and cleans up all references from `AppModule`, `SharedModule`, `tsconfig.json`, and commitlint config. The `app` and `shared` core modules cannot be removed:\n\n```bash\noo module:remove\noo module:remove --name user\noo module:remove --name user --silent    # skip confirmation prompt\n```\n\n---\n\n## Migrations\n\nMigrations are versioned, incremental SQL scripts that evolve your database schema over time. Each migration lives in `modules/<name>/src/migrations/` and is executed in order, making every schema change reproducible, reviewable, and reversible.\n\n### Why Migrations?\n\nManually altering a database in production is error-prone and leaves no audit trail. Migrations solve this by treating schema changes as code: they are committed to git, reviewed in pull requests, and applied the same way in every environment \u2014 local, staging, and production.\n\n**Benefits:**\n\n- **Reproducibility** \u2014 any developer can recreate the exact database state by running `oo migration:up` from scratch.\n- **History & auditability** \u2014 every schema change is tied to a commit, a date, and an author, making it easy to understand when and why a column or table was added.\n- **Safe deployments** \u2014 CI runs migrations before the application boots, catching schema errors before they reach production.\n- **Rollback capability** \u2014 because changes are incremental and versioned, you can reason about what to undo if a deployment goes wrong.\n- **Team coordination** \u2014 concurrent feature branches each generate their own migration file; the timestamp ordering ensures they are applied in the correct sequence when merged.\n\n**Good practices:**\n\n- One migration per logical change (e.g. add a table, add a column, add an index). Avoid bundling unrelated schema changes in a single file.\n- Never edit a migration that has already been applied in any shared environment \u2014 create a new migration to amend it instead.\n- Always write both `up` and `down` logic so migrations can be rolled back cleanly.\n- Keep migrations idempotent where possible (e.g. `CREATE TABLE IF NOT EXISTS`) to prevent failures on re-runs.\n- Run `oo module:lock` after every new migration to hash the file into the module manifest and enable integrity checks in CI.\n- Test migrations against a real database in CI \u2014 schema errors are invisible to TypeScript's type checker.\n- Avoid putting business logic or data transformations in migrations; keep them strictly structural (DDL) or use a dedicated seed for data.\n\n### Create a Migration\n\nGenerates a timestamped migration file in `modules/<name>/src/migrations/` along with a test file and a `bin/migration/up.ts` runner (if not already present):\n\n```bash\noo migration:create --module user\n```\n\n### Run Migrations\n\nExecutes migrations across all modules sequentially:\n\n```bash\noo migration:up\noo migration:up --drop   # drop database before migrating\n```\n\n---\n\n## Seeds\n\nSeeds populate your database with initial or reference data \u2014 default roles, configuration values, demo content, or test fixtures. Each seed lives in `modules/<name>/src/seeds/` as a YAML file and is executed in order via the seed runner.\n\n### Why Seeds?\n\nHardcoding initial data in migration files mixes structural changes with data concerns, making both harder to maintain. Seeds keep data separate from schema, so they can be re-run independently, updated without touching migrations, and disabled in environments where they are not needed.\n\n**Benefits:**\n\n- **Consistent starting state** \u2014 every developer and every environment boots with the same baseline data, eliminating \"works on my machine\" data discrepancies.\n- **Readable data definitions** \u2014 YAML files are easy to read, diff, and review in pull requests without understanding SQL or TypeScript.\n- **Repeatable setup** \u2014 onboarding a new developer or spinning up a fresh staging environment requires only `oo seed:run` instead of manual database operations.\n- **Separation of concerns** \u2014 schema structure (migrations) and data content (seeds) evolve independently, reducing noise in both histories.\n- **Safe resets** \u2014 `oo seed:run --drop` wipes and repopulates data without touching the schema, useful for resetting demo or test environments.\n\n**Good practices:**\n\n- Use seeds for **reference data** (roles, permissions, countries, currencies) and **development fixtures** (demo users, sample products). Avoid using them for production user data.\n- Keep each seed file focused on a single entity or dataset \u2014 one file per table is a reasonable default.\n- Write seeds so they are idempotent: inserting with `ON CONFLICT DO NOTHING` or checking for existence before inserting prevents errors on re-runs.\n- Never depend on data inserted by another module's seed unless you control the execution order explicitly.\n- Run `oo module:lock` after adding or modifying a seed to update the module manifest and protect file integrity in CI.\n- Mirror your migration order: seed data for a table only after the migration that creates it has been applied.\n- Avoid generating seeds with random or time-dependent values \u2014 deterministic data makes debugging and comparison across environments reliable.\n\n### Create a Seed\n\nGenerates a YAML seed file in `modules/<name>/src/seeds/` along with a test file and a `bin/seed/run.ts` runner (if not already present):\n\n```bash\noo seed:create --module user\noo seed:create --name initial-roles --module user\n```\n\n### Run Seeds\n\nExecutes seeds across all modules sequentially:\n\n```bash\noo seed:run\noo seed:run --drop   # drop data before seeding\n```\n\n---\n\n## Issues\n\nIssues bridge your Linear project management board and your local codebase. Each issue is represented as a YAML file under `modules/<name>/issues/` and serves as the single source of truth for what is being built, why, and what \"done\" looks like.\n\n**Requirements:** `LINEAR_API_KEY` must be set in the environment for commands that talk to Linear (`issue:pull`, `issue:push`). Add it to your local `.env`:\n\n```\nLINEAR_API_KEY=lin_api_xxxxxxxxxx\nLINEAR_TEAM_ID=your_team_id       # optional \u2014 skips the team selection prompt in issue:push\n```\n\n### Issue YAML format\n\nEvery issue file follows a consistent schema:\n\n```yaml\nid: \"OON-123\"\ntitle: \"Add password reset flow\"\nstate: \"In Progress\"\npriority: \"High\"\ndescription: |\n  **Context**: Users currently have no way to recover a forgotten password.\n\n  **Goal**: Implement a secure email-based password reset flow.\n\n  **Acceptance Criteria**:\n  - [ ] User can request a reset link via their email address\n  - [ ] Link expires after 1 hour\n  - [ ] Used links are invalidated immediately\n\n  **Technical Notes**: Use JWT with short TTL; store a one-time token hash in the database.\nlabels:\n  - \"authentication\"\n  - \"security\"\ncomments:\n  - author: \"Alice\"\n    message: \"Make sure the token is hashed before storage, not stored in plain text.\"\n```\n\n---\n\n### Create an Issue\n\n`issue:create` scaffolds a new issue YAML locally with a generated `[A-F]{3}-[0-9]{6}` placeholder identifier. No Linear connection is required \u2014 use this when you want to define and refine an issue offline before pushing it to Linear.\n\nBy default all fields are empty; pass `--interactive` to be prompted for each one:\n\n```bash\noo issue:create                                                  # Empty skeleton in shared module\noo issue:create --title \"Add password reset\" --module user       # Pre-fill title, save to user module\noo issue:create --interactive                                    # Prompt for title, state, priority, labels, description\noo issue:create --interactive --module user                      # Interactive + save into modules/user/issues/\n```\n\nAfter writing the file the command optionally **improves the description with Claude** \u2014 rewrites a raw description into the structured *Context / Goal / Acceptance Criteria / Technical Notes* format and suggests labels derived from the description.\n\n---\n\n### Pull an Issue\n\n`issue:pull` fetches an existing Linear issue by its identifier and saves it as `modules/<name>/issues/<identifier>.yml`. Use this to sync a ticket into your local workspace before starting implementation.\n\n```bash\noo issue:pull                               # Prompt for issue ID\noo issue:pull --id OON-123                  # Pull a specific issue\noo issue:pull --id OON-123 --module user    # Save into modules/user/issues/\n```\n\nAfter saving the file the command optionally improves the description with Claude, the same as `issue:create`.\n\n---\n\n### Push an Issue\n\n`issue:push` reads a local YAML file and syncs it back to Linear. It detects whether the issue already exists and either **updates** it (title, description, state, priority, labels, new comments) or **creates** it from scratch in a team you select interactively.\n\n```bash\noo issue:push                               # Prompt for issue ID\noo issue:push --id OON-123                  # Push modules/shared/issues/OON-123.yml\noo issue:push --id OON-123 --module user    # Push modules/user/issues/OON-123.yml\n```\n\nWhen creating a new issue (no matching Linear issue found), the command:\n- Prompts you to select a target team\n- Resolves or creates states and labels as needed\n- Renames the local file to match the real Linear identifier once the issue is created\n\n---\n\n### Spec Plan\n\n`spec:plan` reads an issue YAML file, prompts you to select which resource types to generate (entity, repository, service, controller, and optionals such as cache, mailer, pubsub, etc.), then invokes Claude to produce one `specs/<spec-name>.spec.yml` file per entity/action pair under `modules/<name>/specs/`.\n\n```bash\noo spec:plan                                    # Prompt for issue and resources\noo spec:plan --issue OON-123                    # Plan from shared module issue\noo spec:plan --issue OON-123 --module user      # Plan from user module issue\n```\n\nThe core resources (entity, repository, service, controller) are pre-selected. Deselect any that are not needed, and add optional resources for more complete scaffolding. The generated spec YAMLs describe the entity shape, required operations, and expected behaviour \u2014 inputs and outputs \u2014 ready to be implemented one at a time.\n\n---\n\n### Spec Implement\n\n`spec:implement` reads a single spec YAML file from `modules/<name>/specs/` and invokes Claude to scaffold the full implementation: entity, repository, service, controller or command, and any optional resources declared in the spec.\n\n```bash\noo spec:implement                                        # Prompt for spec\noo spec:implement --spec create-user                     # Implement from shared module\noo spec:implement --spec create-user --module user       # Implement from user module\n```\n\nRun this once per spec entry. When all entries are implemented, the issue's acceptance criteria should be fully satisfied.\n\n---\n\n### Recommended Workflow\n\nThere are two natural entry points depending on whether the ticket originates in Linear or locally.\n\n#### Linear-first (existing ticket)\n\nUse this when a ticket is already created in Linear (e.g. by a product manager) and you are picking it up for implementation:\n\n```\n1. oo issue:pull --id OON-123 --module user\n   \u2192 Downloads the issue YAML into modules/user/issues/OON-123.yml\n   \u2192 Optionally improves the description with Claude\n\n2. oo spec:plan --issue OON-123 --module user\n   \u2192 Prompts for resource types, then generates one spec YAML per entity/action pair\n     in modules/user/specs/\n\n3. oo spec:implement --spec <name> --module user   (repeat per spec entry)\n   \u2192 Invokes Claude to scaffold entity, repository, service, controller, and optional resources\n\n4. oo issue:push --id OON-123 --module user\n   \u2192 Pushes any local edits (description improvements, label changes, comments) back to Linear\n   \u2192 Updates the state to reflect current progress (e.g. \"In Progress\" \u2192 \"In Review\")\n```\n\n#### Offline-first (new idea or local spike)\n\nUse this when you are defining a new feature locally before it exists in Linear:\n\n```\n1. oo issue:create --interactive --module user\n   \u2192 Creates a YAML skeleton with a placeholder ID (e.g. ABD-042381)\n   \u2192 Optionally improves the description with Claude and suggests labels\n\n2. Refine the YAML: adjust title, state, priority, description, labels.\n\n3. oo spec:plan --issue ABD-042381 --module user\n   \u2192 Prompts for resource types, then generates one spec YAML per entity/action pair\n     in modules/user/specs/\n\n4. oo spec:implement --spec <name> --module user   (repeat per spec entry)\n   \u2192 Invokes Claude to scaffold entity, repository, service, controller, and optional resources\n\n5. oo issue:push --id ABD-042381 --module user\n   \u2192 Creates the issue in Linear under the team you select\n   \u2192 Renames the local file to the real Linear identifier (e.g. OON-124.yml)\n```\n\n#### Day-to-day tips\n\n- **Commit issue YAMLs alongside implementation commits** \u2014 the file is the authoritative record of what was planned and why. Future reviewers and `git blame` will thank you.\n- **Use the description improvement step** \u2014 a well-structured description (Context / Goal / Acceptance Criteria) makes the issue easier to implement and review.\n- **Keep state in sync** \u2014 before marking a PR ready for review, run `issue:push` to move the Linear ticket to \"In Review\" so the board reflects reality.\n- **Never commit `LINEAR_API_KEY`** \u2014 add it to `.env` and ensure `.env` is in `.gitignore`.\n\n---\n\n## Generators\n\n### AI\n\nGenerates an AI integration class in `modules/<name>/src/ai/<Name>Ai.ts`. Automatically installs `@ooneex/ai`:\n\n```bash\noo make:ai --name Chat --module user\n```\n\n**Why:** Calling LLM APIs directly from controllers or services mixes infrastructure concerns with business logic and makes it hard to swap providers. A dedicated AI class encapsulates the model, prompt strategy, and configuration in one place.\n\n**Benefits:** Provider-agnostic abstraction, centralised prompt management, easy to mock in tests, swap or upgrade models without touching business logic.\n\n**Good practices:**\n- One class per distinct AI capability (e.g. `ChatAi`, `SummarizeAi`, `ModerationAi`) \u2014 avoid a single god class.\n- Keep system prompts and model configuration inside the class, not scattered across callers.\n- Always handle rate-limit and timeout errors gracefully; never let an AI failure crash the request.\n- Log both the prompt and the response at `debug` level to simplify troubleshooting.\n\n---\n\n### Analytics\n\nGenerates an analytics handler class in `modules/<name>/src/analytics/<Name>Analytics.ts`. Automatically installs `@ooneex/analytics`:\n\n```bash\noo make:analytics --name User --module user\n```\n\n**Why:** Sprinkling raw analytics calls (PostHog, Segment, etc.) throughout controllers couples business logic to a third-party SDK. A dedicated analytics class centralises event definitions and makes it trivial to change or disable the provider.\n\n**Benefits:** Single source of truth for event names and properties, easy to stub in tests, provider can be swapped without touching controllers, events are discoverable by name.\n\n**Good practices:**\n- Name events after business actions, not UI interactions (e.g. `user.subscribed`, not `button.clicked`).\n- Define event property shapes as TypeScript types inside the class.\n- Always fire analytics asynchronously \u2014 never `await` a tracking call on the critical path.\n- Keep one analytics class per domain concept so event ownership is clear.\n\n---\n\n### Cache\n\nGenerates a cache handler class in `modules/<name>/src/cache/<Name>Cache.ts`. Automatically installs `@ooneex/cache`:\n\n```bash\noo make:cache --name User --module user\n```\n\n**Why:** Inline cache calls scattered through services create duplicated TTL values, inconsistent key formats, and make it hard to invalidate related entries. A dedicated cache class owns the key scheme and TTL policy for a given domain object.\n\n**Benefits:** Consistent key naming, single place to update TTLs, easy to add cache warming or invalidation logic, simple to disable caching during tests.\n\n**Good practices:**\n- Prefix keys with the module and entity name to avoid collisions (e.g. `user:profile:{id}`).\n- Define TTLs as named constants, not magic numbers.\n- Always invalidate or update the cache when the underlying data changes \u2014 stale reads are harder to debug than cache misses.\n- Use the cache for reads only; never store the primary copy of data in a cache.\n\n---\n\n### Controller\n\nGenerates an HTTP or WebSocket controller registered in the target module. Prompts for route name, path, and HTTP method if not provided. Automatically installs `@ooneex/controller`:\n\n```bash\noo make:controller --name UserCreate --module user\noo make:controller --name UserCreate --module user --route.name api.user.create --route.path /api/users --route.method POST\noo make:controller --name UserSocket --module user --isSocket\n```\n\n**Why:** Controllers are the entry point for all HTTP and WebSocket interactions. Generating them with a consistent structure ensures route registration, validation, and error handling are set up correctly from the start.\n\n**Benefits:** Automatic route registration in the module, consistent request/response patterns, clear separation between routing and business logic, WebSocket support out of the box.\n\n**Good practices:**\n- One controller per HTTP action (e.g. `UserCreateController`, `UserListController`) \u2014 avoid multi-action controllers.\n- Controllers should be thin: validate input, call a service, return a response. No business logic inside.\n- Prefix route names with the module (e.g. `api.user.create`) to avoid cross-module collisions.\n- Use the generated route name constant everywhere instead of hardcoding URL strings.\n\n---\n\n### Cron\n\nGenerates a cron job class in `modules/<name>/src/crons/<Name>Cron.ts` and registers it in the module. Automatically installs `@ooneex/cron`:\n\n```bash\noo make:cron --name Cleanup --module user\n```\n\n**Why:** Ad-hoc scheduled scripts outside the application are fragile, hard to monitor, and disconnected from the codebase. Cron classes live inside the module that owns the task, are registered with the DI container, and benefit from the same logging and error handling as the rest of the application.\n\n**Benefits:** Centralised schedule management, full access to injected services and repositories, observable via the application logger, easy to disable per environment.\n\n**Good practices:**\n- Name cron classes after the task, not the schedule (e.g. `ExpiredTokenCleanupCron`, not `DailyCron`).\n- Keep the cron class small \u2014 delegate actual work to a service method so the logic is testable independently.\n- Always log the start, end, and outcome of each run.\n- Make cron jobs idempotent: running the same job twice should not corrupt data.\n- Disable background jobs in the `testing` environment to keep tests fast and deterministic.\n\n---\n\n### Database\n\nGenerates a database adapter class in `modules/<name>/src/databases/<Name>Database.ts`. Automatically installs `@ooneex/database`:\n\n```bash\noo make:database --name User --module user\n```\n\n**Why:** Direct use of the ORM or raw query builder in services tightly couples business logic to the database layer. A database adapter wraps the connection and query interface, making it straightforward to configure per-module connections, switch drivers, or mock the database in tests.\n\n**Benefits:** Consistent connection configuration per module, single place to add query logging or instrumentation, easier to test services in isolation by injecting a mock adapter.\n\n**Good practices:**\n- Use the database adapter for raw queries or bulk operations that fall outside the repository pattern.\n- Never expose the raw ORM connection object outside the adapter class.\n- Configure connection pool sizes and timeouts in one place inside the adapter.\n- Prefer the repository pattern for standard CRUD; reach for the database adapter only when you need full query control.\n\n---\n\n### Docker\n\nAdds a Docker service to `modules/app/docker-compose.yml`. Creates the file if it does not exist. Available services: `postgres`, `mysql`, `mongodb`, `redis`, `rabbitmq`, `nats`, `elasticsearch`, `clickhouse`, `minio`, `memcached`, `prometheus`, `grafana`, `jaeger`, `keycloak`, `vault`, `temporal`, `libretranslate`, `maildev`:\n\n```bash\noo make:docker\noo make:docker --name postgres\noo make:docker --name redis\n```\n\n**Why:** Manually writing Docker Compose service definitions is repetitive, error-prone, and inconsistent across projects. The generator adds a pre-configured, production-ready service block so local infrastructure matches what the application expects.\n\n**Benefits:** Consistent port mappings and environment variables across the team, generated health-check and volume definitions, no need to memorise image names or versions.\n\n**Good practices:**\n- Commit `docker-compose.yml` to source control so every developer uses identical service versions.\n- Use named volumes for persistent data (databases) and anonymous volumes for ephemeral services (caches).\n- Never use Docker Compose in production \u2014 it is a local development tool only.\n- Pin image versions (e.g. `postgres:16`) rather than using `latest` to keep environments stable.\n- Add service dependencies (`depends_on`) so the application container only starts after its databases are healthy.\n\n---\n\n### Entity\n\nGenerates a TypeORM entity class in `modules/<name>/src/entities/<Name>Entity.ts` and registers it in `SharedModule`. Automatically installs `@ooneex/entity`:\n\n```bash\noo make:entity --name User --module user\noo make:entity --name User --module user --tableName users\n```\n\n**Why:** Entities are the single source of truth for your database schema. Generating them with consistent decorators and base class inheritance ensures that timestamps, soft deletes, and other cross-cutting concerns are applied uniformly across every table.\n\n**Benefits:** Automatic registration in `SharedModule`, consistent column conventions (snake_case table names, `created_at`/`updated_at` timestamps), TypeScript types aligned with the database schema.\n\n**Good practices:**\n- Always specify the table name explicitly to avoid surprises from TypeORM's pluralisation logic.\n- Keep entities as pure data structures \u2014 no business logic, no service calls inside entity methods.\n- Add database indexes to columns used in frequent `WHERE` or `ORDER BY` clauses.\n- Use enums for columns with a fixed set of values to enforce data integrity at the database level.\n- Create a migration immediately after adding or modifying an entity so schema and code stay in sync.\n\n---\n\n### Logger\n\nGenerates a logger class in `modules/<name>/src/loggers/<Name>Logger.ts`. Automatically installs `@ooneex/logger`:\n\n```bash\noo make:logger --name Audit --module user\n```\n\n**Why:** Using a global logger everywhere produces undifferentiated log output that is hard to filter by feature or severity. A dedicated logger class per domain adds a consistent context (module name, logger name) to every log entry, making logs actionable in production.\n\n**Benefits:** Structured log entries with automatic context tags, easy to route specific loggers to different backends (file, Better Stack, etc.), no need to repeat context strings across every log call.\n\n**Good practices:**\n- Use the `Audit` logger for security-sensitive actions (login, permission changes) and the default app logger for operational events.\n- Always log at the correct level: `debug` for internal state, `info` for significant business events, `warn` for recoverable problems, `error` for failures that need attention.\n- Include relevant IDs (user ID, request ID) in every log entry to enable correlation across services.\n- Never log sensitive data such as passwords, tokens, or payment details.\n\n---\n\n### Mailer\n\nGenerates a mailer class (`<Name>Mailer.ts`) and its JSX template (`<Name>MailerTemplate.tsx`) in `modules/<name>/src/mailers/`. Automatically installs `@ooneex/mailer`:\n\n```bash\noo make:mailer --name Welcome --module user\n```\n\n**Why:** Composing email HTML inline or with raw string templates is brittle and hard to preview. The generator creates a typed mailer class paired with a JSX template, keeping email logic and presentation cleanly separated and type-safe.\n\n**Benefits:** JSX template enables component reuse and design-system consistency across emails, typed mailer class prevents missing required variables, easy to test rendering without sending real emails.\n\n**Good practices:**\n- One mailer per transactional email type (e.g. `WelcomeMailer`, `PasswordResetMailer`).\n- Never send emails synchronously on the request path \u2014 enqueue them via a job or pub/sub event.\n- Always provide a plain-text fallback alongside the HTML template for clients that block images.\n- Test email rendering in multiple clients (Gmail, Outlook, Apple Mail) before deploying \u2014 CSS support varies widely.\n- Use the `testing` environment mailer backend to capture sent emails without delivering them.\n\n---\n\n### Middleware\n\nGenerates an HTTP or WebSocket middleware class registered in the target module. Automatically installs `@ooneex/middleware`:\n\n```bash\noo make:middleware --name Auth --module user\noo make:middleware --name Auth --module user --isSocket\n```\n\n**Why:** Cross-cutting concerns like authentication, CORS, request logging, and input sanitisation should not live inside controllers. Middleware classes intercept requests before they reach a controller, keeping that logic reusable and independently testable.\n\n**Benefits:** Reusable across multiple controllers within the module, auto-registered in the middleware pipeline, full access to injected services via DI, works identically for HTTP and WebSocket routes.\n\n**Good practices:**\n- Keep middleware single-purpose (e.g. `AuthMiddleware` only handles authentication, not rate limiting).\n- Always call `next()` explicitly or return a response \u2014 never leave the pipeline hanging.\n- Order matters: authentication middleware must run before authorisation middleware.\n- Avoid heavy computation in middleware; defer expensive work to the service layer.\n- Write unit tests that verify the middleware passes, blocks, and modifies requests as expected.\n\n---\n\n### Permission\n\nGenerates a permission class in `modules/<name>/src/permissions/<Name>Permission.ts`. Automatically installs `@ooneex/permission`:\n\n```bash\noo make:permission --name User --module user\n```\n\n**Why:** Scattering permission checks across controllers and services leads to inconsistency and makes auditing access control difficult. A dedicated permission class per domain centralises all access rules for that domain in one reviewable place.\n\n**Benefits:** All permissions for a domain are discoverable in a single file, easy to audit who can do what, permissions can be reused across multiple controllers without duplication, changes to access rules require touching only one class.\n\n**Good practices:**\n- Name permissions after the action and resource (e.g. `UserPermission` checks `canCreate`, `canUpdate`, `canDelete`).\n- Always check permissions in middleware or the service layer \u2014 never in the entity or repository.\n- Combine with roles (RBAC) for coarse-grained access and permissions for fine-grained control.\n- Write tests that assert both allowed and denied cases for every permission rule.\n- Never hardcode user IDs or emails inside permission logic; use roles and attributes instead.\n\n---\n\n### PubSub\n\nGenerates a pub/sub event class in `modules/<name>/src/events/<Name>Event.ts` and registers it in the module. Automatically installs `@ooneex/pub-sub`:\n\n```bash\noo make:pubsub --name UserCreated --module user\noo make:pubsub --name UserCreated --module user --channel user-created\n```\n\n**Why:** Direct calls between modules create tight coupling that makes the codebase fragile and hard to extend. Pub/sub events decouple the publisher from the subscriber: the `user` module emits `UserCreated` without knowing or caring which other modules react to it.\n\n**Benefits:** Loose coupling between modules, multiple subscribers can react to the same event independently, easy to add new reactions without modifying the publisher, events are named and typed so their contracts are explicit.\n\n**Good practices:**\n- Name events in the past tense (e.g. `UserCreated`, `OrderShipped`) to make clear they describe something that already happened.\n- Keep event payloads small and serialisable \u2014 include IDs rather than full entity objects where possible.\n- Subscribe in the module that owns the reaction, not in the module that owns the event.\n- Make event handlers idempotent: the same event may be delivered more than once in failure scenarios.\n- Log every event published and consumed to simplify debugging distributed flows.\n\n---\n\n### Repository\n\nGenerates a repository class for data access in `modules/<name>/src/repositories/<Name>Repository.ts`. Automatically installs `@ooneex/repository`:\n\n```bash\noo make:repository --name User --module user\n```\n\n**Why:** Putting database queries directly in services mixes business logic with persistence concerns and makes services impossible to test without a database. The repository pattern isolates all data-access code behind a typed interface that can be mocked in tests.\n\n**Benefits:** Services remain database-agnostic, all queries for an entity are discoverable in one class, easy to swap the underlying ORM or database without touching business logic, clean boundary for unit testing.\n\n**Good practices:**\n- One repository per entity (e.g. `UserRepository` owns all queries against the `users` table).\n- Repositories should only contain query logic \u2014 no business rules, no validation, no event publishing.\n- Use descriptive method names that reflect intent (e.g. `findActiveByEmail`, `findExpiredTokens`) rather than generic `find` with complex filter objects.\n- Return domain objects or plain data \u2014 never expose raw ORM query builders to callers.\n- Add pagination to any method that can return an unbounded number of rows.\n\n---\n\n### Service\n\nGenerates a service class in `modules/<name>/src/services/<Name>Service.ts`. Automatically installs `@ooneex/service`:\n\n```bash\noo make:service --name User --module user\n```\n\n**Why:** Business logic scattered across controllers is impossible to test, reuse, or reason about. Services are the home of all business rules, orchestrating repositories, events, and other services in a single, testable unit.\n\n**Benefits:** Business logic is testable without HTTP, reusable across multiple controllers or cron jobs, dependencies are explicit via constructor injection, easy to mock at the service boundary in integration tests.\n\n**Good practices:**\n- One service per aggregate or major business capability (e.g. `UserService` for user lifecycle, `BillingService` for payment flows).\n- Services should call repositories for data, never query the database directly.\n- Keep services stateless \u2014 all required data should come from method arguments or injected dependencies.\n- Raise typed exceptions (e.g. `UserNotFoundException`) rather than returning `null` or error codes.\n- A service method should do one thing; if a method grows beyond ~20 lines, consider extracting a helper or sub-service.\n\n---\n\n### Storage\n\nGenerates a file storage class in `modules/<name>/src/storage/<Name>Storage.ts`. Automatically installs `@ooneex/storage`:\n\n```bash\noo make:storage --name Avatar --module user\n```\n\n**Why:** Coupling file upload logic directly to a specific provider (S3, Cloudflare R2, local filesystem) makes it painful to change backends and duplicates configuration across the codebase. A storage class abstracts the provider behind a consistent interface scoped to a specific asset type.\n\n**Benefits:** Provider-agnostic uploads and reads, all storage configuration for an asset type in one class, easy to switch between local filesystem (development) and cloud storage (production) via environment variables, consistent file-naming and path conventions.\n\n**Good practices:**\n- Name storage classes after the asset they manage (e.g. `AvatarStorage`, `InvoiceStorage`).\n- Always validate file type and size before passing to the storage class \u2014 never trust client-supplied content types.\n- Generate deterministic, collision-resistant file names (e.g. `{userId}/{uuid}.{ext}`) rather than using the original filename.\n- Never store the full URL in the database \u2014 store only the path or key and derive the URL at read time so it works across environments.\n- Delete orphaned files when the associated entity is deleted to avoid unbounded storage growth.\n\n---\n\n### Vector Database\n\nGenerates a vector database class in `modules/<name>/src/databases/<Name>VectorDatabase.ts`. Automatically installs `@ooneex/rag`:\n\n```bash\noo make:vector-database --name Knowledge --module user\n```\n\n**Why:** Semantic search and Retrieval-Augmented Generation (RAG) require storing and querying high-dimensional embeddings, which relational databases are not designed for. A dedicated vector database class encapsulates the embedding model, index configuration, and similarity-search logic in one place.\n\n**Benefits:** Centralised embedding and retrieval strategy per knowledge domain, easy to swap vector backends (pgvector, Qdrant, etc.), consistent chunking and metadata conventions, decoupled from the LLM layer so both can evolve independently.\n\n**Good practices:**\n- One vector database class per knowledge domain (e.g. `KnowledgeVectorDatabase`, `ProductCatalogVectorDatabase`).\n- Always store the source document ID alongside each embedding so retrieved chunks can be traced back to their origin.\n- Use a consistent chunking strategy (fixed-size or sentence-boundary) within a class \u2014 mixing strategies pollutes the index.\n- Re-index when the embedding model changes; embeddings from different models are not comparable.\n- Cache frequently retrieved embeddings to avoid redundant model calls on hot queries.\n\n---\n\n## Claude\n\nThis project ships with a set of **Claude Code skills** \u2014 pre-built instruction sets that tell Claude exactly how to scaffold, implement, and test each type of artefact in this codebase. Skills eliminate the gap between \"generate the files\" and \"ship working code\": each skill runs the CLI generator, reads the output, completes the implementation, writes tests, and lints \u2014 all in one `/command`.\n\n### Why Skills?\n\nRunning `oo make:service` creates a skeleton. A Claude skill does that *and* completes the business logic, writes a meaningful test suite, applies coding conventions, and formats the result \u2014 turning a 10-step workflow into a single prompt.\n\n**Benefits:**\n- Consistent code quality across every artefact, regardless of who wrote it\n- Conventions (visibility modifiers, naming suffixes, DI patterns) are enforced automatically\n- Tests are generated alongside implementation, not as an afterthought\n- Skills chain together \u2014 `make:controller` automatically triggers `make:service` and `make:pubsub`\n\n### Setup\n\nBefore using skills, generate the `.claude/` directory with all skill files and the project `CLAUDE.md`:\n\n```bash\noo claude:skill:create\n```\n\nThis writes `.claude/CLAUDE.md` and one `SKILL.md` per skill under `.claude/skills/<skill-name>/`. Re-run any time you upgrade the CLI to pick up new or updated skills. Commit the generated files so every team member gets the same skill definitions without running the command themselves.\n\n### How to Use\n\nOpen Claude Code in the project root and type `/skill-name`. Claude will execute the full workflow described in the skill. You can pass arguments inline:\n\n```\n/make:service --name=UserCreate --module=user\n/make:controller --name=UserCreate --module=user --route.path=/users --route.method=POST\n/commit\n```\n\nIf you omit arguments, Claude will prompt you for the required values.\n\n> **Important:** Always run skills from the project root, not from inside a module directory.\n\n### Available Skills\n\n#### Code Quality\n\n| Skill | Description |\n|---|---|\n| `/optimize` | Enforce naming conventions, remove duplication, improve performance, and restructure tests across a module |\n| `/commit` | Analyze staged changes, group them by module, and create properly scoped conventional commits |\n\n#### Generators\n\n| Skill | Description |\n|---|---|\n| `/make:ai` | Generate an AI integration class with `run` and `runStream` methods, wired to `@ooneex/ai` |\n| `/make:analytics` | Generate an analytics handler class for tracking domain events via `@ooneex/analytics` |\n| `/make:cache` | Generate a cache handler class with key and TTL management via `@ooneex/cache` |\n| `/make:command` | Generate a CLI command class implementing `ICommand` via `@ooneex/cli` |\n| `/make:controller` | Generate an HTTP or WebSocket controller with route type, validation, roles, service, and pub/sub event |\n| `/make:cron` | Generate a cron job class registered in its module via `@ooneex/cron` |\n| `/make:database` | Generate a database adapter class for raw queries via `@ooneex/database` |\n| `/make:entity` | Generate a TypeORM entity class registered in `SharedModule` via `@ooneex/entity` |\n| `/make:logger` | Generate a structured logger class with domain context via `@ooneex/logger` |\n| `/make:mailer` | Generate a mailer class and its JSX email template via `@ooneex/mailer` |\n| `/make:middleware` | Generate an HTTP or WebSocket middleware class registered in the module via `@ooneex/middleware` |\n| `/make:permission` | Generate a permission class centralising access rules for a domain via `@ooneex/permission` |\n| `/make:pubsub` | Generate a pub/sub event class registered in the module via `@ooneex/pub-sub` |\n| `/make:repository` | Generate a repository class for typed data access via `@ooneex/repository` |\n| `/make:service` | Generate a service class implementing `IService` with business logic and tests |\n| `/make:storage` | Generate a file storage class for asset management via `@ooneex/storage` |\n| `/make:vector-database` | Generate a vector database class for semantic search and RAG via `@ooneex/rag` |\n\n#### Database\n\n| Skill | Description |\n|---|---|\n| `/migration:create` | Generate a migration file with `up`/`down` methods, index guidance, and structural tests |\n| `/seed:create` | Generate a seed class and its YAML data file with idempotent insertion logic |\n\n#### Spec\n\n| Skill | Description |\n|---|---|\n| `/spec:plan` | Parse user-provided content and produce one `specs/<spec-name>.spec.yml` file per entity/action pair |\n| `/spec:implement` | Read a single spec YML entry and implement entity, repository, service, controller/command, and optional resources |\n\n### Coding Conventions Enforced by Skills\n\nAll generator skills automatically apply the conventions defined in `/optimize`:\n\n- **Visibility modifiers** \u2014 every class method and property has explicit `public`, `private`, or `protected`\n- **Naming suffixes** \u2014 types end with `Type`, interfaces start with `I`\n- **Arrow functions** \u2014 used everywhere except class methods\n- **No non-null assertions** \u2014 use default values or optional types instead\n- **Dependency injection** \u2014 constructor injection via `@inject()` from `@ooneex/container`\n- **Code hygiene** \u2014 no unused imports, no dead code, no bare `TODO` comments\n\n---\n\n## Release\n\n```bash\noo make:release\n```\n\nScans every `packages/` and `modules/` directory for unreleased conventional commits and, for each one that has them, performs a full release cycle automatically:\n\n1. **Detects unreleased work** \u2014 finds the last git tag matching `<package-name>@*` and lists all conventional commits that have landed since then in that directory. Packages with no new commits are skipped.\n2. **Bumps the version** in `package.json`:\n   - `minor` (e.g. `1.2.0 \u2192 1.3.0`) when any commit is of type `feat`\n   - `patch` (e.g. `1.2.0 \u2192 1.2.1`) for all other types (`fix`, `refactor`, `perf`, `docs`, `chore`, \u2026)\n3. **Updates `CHANGELOG.md`** with a dated version section. Commits are grouped into standard Keep-a-Changelog categories and linked to their SHA on the remote:\n\n   | Commit type | Changelog category |\n   |---|---|\n   | `feat` | Added |\n   | `fix` | Fixed |\n   | `refactor`, `perf`, `style`, `docs`, `build`, `ci`, `chore` | Changed |\n   | `revert` | Removed |\n\n4. **Creates a release commit** \u2014 stages `package.json` and `CHANGELOG.md` then commits with the message `chore(release): <name>@<version>`.\n5. **Creates an annotated git tag** \u2014 `<name>@<version>` (e.g. `@acme/user@1.3.0`).\n6. **Prompts to push** \u2014 after all packages are processed, asks whether to push commits and tags to the remote. If confirmed, it also runs `bun install`, commits the updated `bun.lock`, and pushes everything.\n\n> **Note:** This command requires conventional commits (`type(scope): Subject`). Non-conventional commits are silently ignored when building the changelog.\n\n---\n\n## Scripts\n\n| Command | Description |\n|---|---|\n| `bun run fmt` | Format all source files with Biome |\n| `bun run lint` | Lint all modules with Biome and TypeScript |\n| `bun run test` | Run tests across all modules |\n| `bun run commit` | Interactive conventional commit prompt |\n";
+var README_md_default = "# {{NAME}}\n\nA modular, enterprise-grade backend framework built with TypeScript and Bun, powered by the **@ooneex** ecosystem.\n\n## Prerequisites\n\n- [Bun](https://bun.sh) (latest)\n- [Docker](https://www.docker.com/) & Docker Compose\n\n## Getting Started\n\n### Install Dependencies\n\n```bash\nbun install\n```\n\n### Environment Configuration\n\nThe environment file is created automatically at `modules/app/.env.yml`. Edit it to fill in the required values:\n\n| Variable | Description | Required |\n|---|---|---|\n| `app.env` | Application environment (`local`, `development`, `staging`, `testing`, `production`, \u2026) | Yes |\n| `app.port` | Server port number (default: `3000`) | Yes |\n| `app.host` | Server hostname (default: `0.0.0.0`) | Yes |\n| `logs.database_url` | Database URL for storing application logs | No |\n| `logs.betterstack.source_token` | Logtail source token for Better Stack logging | No |\n| `logs.betterstack.ingesting_host` | Better Stack log ingestion host URL | No |\n| `exception.betterstack.application_token` | Better Stack token for exception tracking | No |\n| `exception.betterstack.ingesting_host` | Better Stack exception ingestion host URL | No |\n| `analytics.posthog.project_token` | PostHog project token for event tracking | No |\n| `analytics.posthog.host` | PostHog ingest host (default: `https://eu.i.posthog.com`) | No |\n| `cache.redis.url` | Redis connection URL for caching | No |\n| `cache.upstash.rest_url` | Upstash Redis REST URL for serverless caching | No |\n| `cache.upstash.rest_token` | Upstash Redis REST token for serverless caching | No |\n| `pubsub.redis.url` | Redis connection URL for pub/sub messaging | No |\n| `rate_limit.redis.url` | Redis connection URL for rate limiting | No |\n| `rate_limit.upstash.url` | Upstash Redis URL for serverless rate limiting | No |\n| `rate_limit.upstash.token` | Upstash Redis token for serverless rate limiting | No |\n| `cors.origins` | Comma-separated allowed origins or `*` (default: `*`) | No |\n| `cors.methods` | Comma-separated HTTP methods | No |\n| `cors.headers` | Comma-separated allowed request headers | No |\n| `cors.exposed_headers` | Comma-separated headers exposed to the browser | No |\n| `cors.credentials` | Allow credentials: `true` or `false` | No |\n| `cors.max_age` | Preflight response cache duration in seconds | No |\n| `database.url` | PostgreSQL connection URL | No |\n| `database.redis.url` | Redis connection URL for Redis-based database operations | No |\n| `database.sqlite.path` | SQLite database file path | No |\n| `storage.cloudflare.access_key` | Cloudflare R2 access key ID | No |\n| `storage.cloudflare.secret_key` | Cloudflare R2 secret access key | No |\n| `storage.cloudflare.endpoint` | Cloudflare R2 endpoint URL | No |\n| `storage.cloudflare.region` | Cloudflare R2 region (default: `EEUR`) | No |\n| `storage.bunny.access_key` | BunnyCDN access key | No |\n| `storage.bunny.storage_zone` | BunnyCDN storage zone name | No |\n| `storage.bunny.region` | BunnyCDN region (default: `de`) | No |\n| `storage.filesystem.path` | Base directory path for local file storage | No |\n| `mailer.sender.name` | Display name for email sender | No |\n| `mailer.sender.address` | Email address for sender | No |\n| `mailer.resend.api_key` | Resend email service API key | No |\n| `jwt.secret` | Secret key for HS256 JWT signing and verification | No |\n| `ai.openrouter.api_key` | OpenRouter API key for accessing 300+ AI models | No |\n| `ai.openai.api_key` | OpenAI API key | No |\n| `ai.anthropic.api_key` | Anthropic API key for Claude models | No |\n| `ai.gemini.api_key` | Google Gemini API key | No |\n| `ai.groq.api_key` | Groq API key for LLM inference | No |\n| `ai.ollama.host` | Ollama host URL for local LLM inference | No |\n| `payment.polar.access_token` | Polar payment platform access token | No |\n| `payment.polar.environment` | Polar environment (`sandbox` or `production`) | No |\n| `authentication.auth_token` | Shared secret token for service-to-service authentication | No |\n| `authentication.clerk.secret_key` | Clerk authentication secret key | No |\n| `linear.api_key` | Linear API key for issue sync (`issue:pull`, `issue:push`) | No |\n| `linear.team_id` | Linear team ID \u2014 skips team selection prompt in `issue:push` | No |\n| `allowed_users.development` | Comma-separated emails allowed in the `development` environment | No |\n| `allowed_users.staging` | Comma-separated emails allowed in the `staging` environment | No |\n| `allowed_users.testing` | Comma-separated emails allowed in the `testing` environment | No |\n| `allowed_users.test` | Comma-separated emails allowed in the `test` environment | No |\n| `allowed_users.qa` | Comma-separated emails allowed in the `qa` environment | No |\n| `allowed_users.uat` | Comma-separated emails allowed in the `uat` environment | No |\n| `allowed_users.integration` | Comma-separated emails allowed in the `integration` environment | No |\n| `allowed_users.preview` | Comma-separated emails allowed in the `preview` environment | No |\n| `allowed_users.demo` | Comma-separated emails allowed in the `demo` environment | No |\n| `allowed_users.sandbox` | Comma-separated emails allowed in the `sandbox` environment | No |\n| `allowed_users.beta` | Comma-separated emails allowed in the `beta` environment | No |\n| `allowed_users.canary` | Comma-separated emails allowed in the `canary` environment | No |\n| `allowed_users.hotfix` | Comma-separated emails allowed in the `hotfix` environment | No |\n| `allowed_users.system` | Comma-separated system user emails | No |\n| `allowed_users.super_admin` | Comma-separated super-admin user emails | No |\n| `allowed_users.admin` | Comma-separated admin user emails | No |\n\n### Start the App\n\nStarts Docker services (if a `docker-compose.yml` is present) and launches the application with hot reload:\n\n```bash\noo app:start\n```\n\n### Stop the App\n\nStops all Docker services:\n\n```bash\noo app:stop\n```\n\n### Build the App\n\nCompiles the application for production. Output is written to the `dist` directory:\n\n```bash\noo app:build\n```\n\n---\n\n## Modules\n\nModules are the core organizational unit. Each module lives under `modules/<name>/` and contains its own controllers, services, repositories, entities, migrations, and seeds.\n\n### Why Modules?\n\nA flat codebase quickly becomes hard to navigate and reason about as an application grows. Modules address this by enforcing **vertical slicing**: all code related to a single business domain (e.g. `user`, `order`, `billing`) lives together rather than being scattered across generic `controllers/`, `services/`, and `repositories/` folders.\n\n**Benefits:**\n\n- **Domain isolation** \u2014 changes to one feature cannot accidentally break another; each module is a self-contained unit with explicit boundaries.\n- **Parallel development** \u2014 teams can work on separate modules without stepping on each other's code or creating merge conflicts in shared directories.\n- **Independent deployment** \u2014 a module can be extracted into a standalone service later with minimal refactoring because its code is already co-located.\n- **Simpler onboarding** \u2014 a new developer understands the scope of a feature by exploring a single directory instead of tracing imports across the whole project.\n- **Scoped migrations & seeds** \u2014 database changes stay close to the entities they affect, making rollbacks and reviews straightforward.\n\n**Good practices:**\n\n- Name modules after business domains (`user`, `product`, `payment`), not technical layers (`controllers`, `helpers`).\n- Keep modules small and focused. If a module grows beyond ~10 controllers or services, consider splitting it by sub-domain.\n- Never import from another module's internal files directly \u2014 expose only what is needed through the module's public index.\n- Register all entities in `SharedModule` (done automatically by `oo make:entity`) so the ORM has a single source of truth.\n- Run `oo module:lock` after every migration or seed change to protect file integrity in CI.\n- Prefix route names with the module name (e.g. `api.user.create`) to avoid collisions across modules.\n\n### Create a Module\n\nScaffolds a new module with all required structure, registers it in `AppModule`, adds its entities to `SharedModule`, and updates `tsconfig.json` path aliases and commitlint config:\n\n```bash\noo module:create\noo module:create --name user\n```\n\n### Lock a Module\n\nHashes migration and seed files into a module manifest (`.yml`) for integrity verification. Run this after adding or modifying migrations/seeds:\n\n```bash\noo module:lock --module user\noo module:lock --module user --override   # force update existing hashes\n```\n\n### Delete a Module\n\nRemoves a module and cleans up all references from `AppModule`, `SharedModule`, `tsconfig.json`, and commitlint config. The `app` and `shared` core modules cannot be removed:\n\n```bash\noo module:remove\noo module:remove --name user\noo module:remove --name user --silent    # skip confirmation prompt\n```\n\n---\n\n## Migrations\n\nMigrations are versioned, incremental SQL scripts that evolve your database schema over time. Each migration lives in `modules/<name>/src/migrations/` and is executed in order, making every schema change reproducible, reviewable, and reversible.\n\n### Why Migrations?\n\nManually altering a database in production is error-prone and leaves no audit trail. Migrations solve this by treating schema changes as code: they are committed to git, reviewed in pull requests, and applied the same way in every environment \u2014 local, staging, and production.\n\n**Benefits:**\n\n- **Reproducibility** \u2014 any developer can recreate the exact database state by running `oo migration:up` from scratch.\n- **History & auditability** \u2014 every schema change is tied to a commit, a date, and an author, making it easy to understand when and why a column or table was added.\n- **Safe deployments** \u2014 CI runs migrations before the application boots, catching schema errors before they reach production.\n- **Rollback capability** \u2014 because changes are incremental and versioned, you can reason about what to undo if a deployment goes wrong.\n- **Team coordination** \u2014 concurrent feature branches each generate their own migration file; the timestamp ordering ensures they are applied in the correct sequence when merged.\n\n**Good practices:**\n\n- One migration per logical change (e.g. add a table, add a column, add an index). Avoid bundling unrelated schema changes in a single file.\n- Never edit a migration that has already been applied in any shared environment \u2014 create a new migration to amend it instead.\n- Always write both `up` and `down` logic so migrations can be rolled back cleanly.\n- Keep migrations idempotent where possible (e.g. `CREATE TABLE IF NOT EXISTS`) to prevent failures on re-runs.\n- Run `oo module:lock` after every new migration to hash the file into the module manifest and enable integrity checks in CI.\n- Test migrations against a real database in CI \u2014 schema errors are invisible to TypeScript's type checker.\n- Avoid putting business logic or data transformations in migrations; keep them strictly structural (DDL) or use a dedicated seed for data.\n\n### Create a Migration\n\nGenerates a timestamped migration file in `modules/<name>/src/migrations/` along with a test file and a `bin/migration/up.ts` runner (if not already present):\n\n```bash\noo migration:create --module user\n```\n\n### Run Migrations\n\nExecutes migrations across all modules sequentially:\n\n```bash\noo migration:up\noo migration:up --drop   # drop database before migrating\n```\n\n---\n\n## Seeds\n\nSeeds populate your database with initial or reference data \u2014 default roles, configuration values, demo content, or test fixtures. Each seed lives in `modules/<name>/src/seeds/` as a YAML file and is executed in order via the seed runner.\n\n### Why Seeds?\n\nHardcoding initial data in migration files mixes structural changes with data concerns, making both harder to maintain. Seeds keep data separate from schema, so they can be re-run independently, updated without touching migrations, and disabled in environments where they are not needed.\n\n**Benefits:**\n\n- **Consistent starting state** \u2014 every developer and every environment boots with the same baseline data, eliminating \"works on my machine\" data discrepancies.\n- **Readable data definitions** \u2014 YAML files are easy to read, diff, and review in pull requests without understanding SQL or TypeScript.\n- **Repeatable setup** \u2014 onboarding a new developer or spinning up a fresh staging environment requires only `oo seed:run` instead of manual database operations.\n- **Separation of concerns** \u2014 schema structure (migrations) and data content (seeds) evolve independently, reducing noise in both histories.\n- **Safe resets** \u2014 `oo seed:run --drop` wipes and repopulates data without touching the schema, useful for resetting demo or test environments.\n\n**Good practices:**\n\n- Use seeds for **reference data** (roles, permissions, countries, currencies) and **development fixtures** (demo users, sample products). Avoid using them for production user data.\n- Keep each seed file focused on a single entity or dataset \u2014 one file per table is a reasonable default.\n- Write seeds so they are idempotent: inserting with `ON CONFLICT DO NOTHING` or checking for existence before inserting prevents errors on re-runs.\n- Never depend on data inserted by another module's seed unless you control the execution order explicitly.\n- Run `oo module:lock` after adding or modifying a seed to update the module manifest and protect file integrity in CI.\n- Mirror your migration order: seed data for a table only after the migration that creates it has been applied.\n- Avoid generating seeds with random or time-dependent values \u2014 deterministic data makes debugging and comparison across environments reliable.\n\n### Create a Seed\n\nGenerates a YAML seed file in `modules/<name>/src/seeds/` along with a test file and a `bin/seed/run.ts` runner (if not already present):\n\n```bash\noo seed:create --module user\noo seed:create --name initial-roles --module user\n```\n\n### Run Seeds\n\nExecutes seeds across all modules sequentially:\n\n```bash\noo seed:run\noo seed:run --drop   # drop data before seeding\n```\n\n---\n\n## Issues\n\nIssues bridge your Linear project management board and your local codebase. Each issue is represented as a YAML file under `modules/<name>/issues/` and serves as the single source of truth for what is being built, why, and what \"done\" looks like.\n\n**Requirements:** `linear.api_key` must be set in the environment for commands that talk to Linear (`issue:pull`, `issue:push`). Add it to `modules/app/.env.yml`:\n\n```yaml\nlinear:\n  api_key: lin_api_xxxxxxxxxx\n  team_id: your_team_id       # optional \u2014 skips the team selection prompt in issue:push\n```\n\n### Issue YAML format\n\nEvery issue file follows a consistent schema:\n\n```yaml\nid: \"OON-123\"\ntitle: \"Add password reset flow\"\nstate: \"In Progress\"\npriority: \"High\"\ndescription: |\n  **Context**: Users currently have no way to recover a forgotten password.\n\n  **Goal**: Implement a secure email-based password reset flow.\n\n  **Acceptance Criteria**:\n  - [ ] User can request a reset link via their email address\n  - [ ] Link expires after 1 hour\n  - [ ] Used links are invalidated immediately\n\n  **Technical Notes**: Use JWT with short TTL; store a one-time token hash in the database.\nlabels:\n  - \"authentication\"\n  - \"security\"\ncomments:\n  - author: \"Alice\"\n    message: \"Make sure the token is hashed before storage, not stored in plain text.\"\n```\n\n---\n\n### Create an Issue\n\n`issue:create` scaffolds a new issue YAML locally with a generated `[A-F]{3}-[0-9]{6}` placeholder identifier. No Linear connection is required \u2014 use this when you want to define and refine an issue offline before pushing it to Linear.\n\nBy default all fields are empty; pass `--interactive` to be prompted for each one:\n\n```bash\noo issue:create                                                  # Empty skeleton in shared module\noo issue:create --title \"Add password reset\" --module user       # Pre-fill title, save to user module\noo issue:create --interactive                                    # Prompt for title, state, priority, labels, description\noo issue:create --interactive --module user                      # Interactive + save into modules/user/issues/\n```\n\nAfter writing the file the command optionally **improves the description with Claude** \u2014 rewrites a raw description into the structured *Context / Goal / Acceptance Criteria / Technical Notes* format and suggests labels derived from the description.\n\n---\n\n### Pull an Issue\n\n`issue:pull` fetches an existing Linear issue by its identifier and saves it as `modules/<name>/issues/<identifier>.yml`. Use this to sync a ticket into your local workspace before starting implementation.\n\n```bash\noo issue:pull                               # Prompt for issue ID\noo issue:pull --id OON-123                  # Pull a specific issue\noo issue:pull --id OON-123 --module user    # Save into modules/user/issues/\n```\n\nAfter saving the file the command optionally improves the description with Claude, the same as `issue:create`.\n\n---\n\n### Improve an Issue\n\n`/issue:improve` rewrites the description of an existing issue YAML into the structured *Context / Goal / Acceptance Criteria / Technical Notes* format, suggests labels, and optionally splits the issue into smaller focused sub-issues.\n\n```\n/issue:improve --id OON-123 --module user\n```\n\n---\n\n### Push an Issue\n\n`issue:push` reads a local YAML file and syncs it back to Linear. It detects whether the issue already exists and either **updates** it (title, description, state, priority, labels, new comments) or **creates** it from scratch in a team you select interactively.\n\n```bash\noo issue:push                               # Prompt for issue ID\noo issue:push --id OON-123                  # Push modules/shared/issues/OON-123.yml\noo issue:push --id OON-123 --module user    # Push modules/user/issues/OON-123.yml\n```\n\nWhen creating a new issue (no matching Linear issue found), the command:\n- Prompts you to select a target team\n- Resolves or creates states and labels as needed\n- Renames the local file to match the real Linear identifier once the issue is created\n\n---\n\n### Recommended Workflow\n\nThere are two natural entry points depending on whether the ticket originates in Linear or locally.\n\n#### Linear-first (existing ticket)\n\nUse this when a ticket is already created in Linear (e.g. by a product manager) and you are picking it up for implementation:\n\n```\n1. oo issue:pull --id OON-123 --module user\n   \u2192 Downloads the issue YAML into modules/user/issues/OON-123.yml\n   \u2192 Optionally improves the description with Claude\n\n2. oo issue:push --id OON-123 --module user\n   \u2192 Pushes any local edits (description improvements, label changes, comments) back to Linear\n   \u2192 Updates the state to reflect current progress (e.g. \"In Progress\" \u2192 \"In Review\")\n```\n\n#### Offline-first (new idea or local spike)\n\nUse this when you are defining a new feature locally before it exists in Linear:\n\n```\n1. oo issue:create --interactive --module user\n   \u2192 Creates a YAML skeleton with a placeholder ID (e.g. ABD-042381)\n   \u2192 Optionally improves the description with Claude and suggests labels\n\n2. Refine the YAML: adjust title, state, priority, description, labels.\n\n3. oo issue:push --id ABD-042381 --module user\n   \u2192 Creates the issue in Linear under the team you select\n   \u2192 Renames the local file to the real Linear identifier (e.g. OON-124.yml)\n```\n\n#### Day-to-day tips\n\n- **Commit issue YAMLs alongside implementation commits** \u2014 the file is the authoritative record of what was planned and why. Future reviewers and `git blame` will thank you.\n- **Use the description improvement step** \u2014 a well-structured description (Context / Goal / Acceptance Criteria) makes the issue easier to implement and review.\n- **Keep state in sync** \u2014 before marking a PR ready for review, run `issue:push` to move the Linear ticket to \"In Review\" so the board reflects reality.\n- **Never commit `linear.api_key`** \u2014 keep it in `modules/app/.env.yml` and ensure `.env.yml` is in `.gitignore`.\n\n---\n\n## Generators\n\n### AI\n\nGenerates an AI integration class in `modules/<name>/src/ai/<Name>Ai.ts`. Automatically installs `@ooneex/ai`:\n\n```bash\noo make:ai --name Chat --module user\n```\n\n**Why:** Calling LLM APIs directly from controllers or services mixes infrastructure concerns with business logic and makes it hard to swap providers. A dedicated AI class encapsulates the model, prompt strategy, and configuration in one place.\n\n**Benefits:** Provider-agnostic abstraction, centralised prompt management, easy to mock in tests, swap or upgrade models without touching business logic.\n\n**Good practices:**\n- One class per distinct AI capability (e.g. `ChatAi`, `SummarizeAi`, `ModerationAi`) \u2014 avoid a single god class.\n- Keep system prompts and model configuration inside the class, not scattered across callers.\n- Always handle rate-limit and timeout errors gracefully; never let an AI failure crash the request.\n- Log both the prompt and the response at `debug` level to simplify troubleshooting.\n\n---\n\n### Analytics\n\nGenerates an analytics handler class in `modules/<name>/src/analytics/<Name>Analytics.ts`. Automatically installs `@ooneex/analytics`:\n\n```bash\noo make:analytics --name User --module user\n```\n\n**Why:** Sprinkling raw analytics calls (PostHog, Segment, etc.) throughout controllers couples business logic to a third-party SDK. A dedicated analytics class centralises event definitions and makes it trivial to change or disable the provider.\n\n**Benefits:** Single source of truth for event names and properties, easy to stub in tests, provider can be swapped without touching controllers, events are discoverable by name.\n\n**Good practices:**\n- Name events after business actions, not UI interactions (e.g. `user.subscribed`, not `button.clicked`).\n- Define event property shapes as TypeScript types inside the class.\n- Always fire analytics asynchronously \u2014 never `await` a tracking call on the critical path.\n- Keep one analytics class per domain concept so event ownership is clear.\n\n---\n\n### Cache\n\nGenerates a cache handler class in `modules/<name>/src/cache/<Name>Cache.ts`. Automatically installs `@ooneex/cache`:\n\n```bash\noo make:cache --name User --module user\n```\n\n**Why:** Inline cache calls scattered through services create duplicated TTL values, inconsistent key formats, and make it hard to invalidate related entries. A dedicated cache class owns the key scheme and TTL policy for a given domain object.\n\n**Benefits:** Consistent key naming, single place to update TTLs, easy to add cache warming or invalidation logic, simple to disable caching during tests.\n\n**Good practices:**\n- Prefix keys with the module and entity name to avoid collisions (e.g. `user:profile:{id}`).\n- Define TTLs as named constants, not magic numbers.\n- Always invalidate or update the cache when the underlying data changes \u2014 stale reads are harder to debug than cache misses.\n- Use the cache for reads only; never store the primary copy of data in a cache.\n\n---\n\n### Controller\n\nGenerates an HTTP or WebSocket controller registered in the target module. Prompts for route name, path, and HTTP method if not provided. Automatically installs `@ooneex/controller`:\n\n```bash\noo make:controller --name UserCreate --module user\noo make:controller --name UserCreate --module user --route.name api.user.create --route.path /api/users --route.method POST\noo make:controller --name UserSocket --module user --isSocket\n```\n\n**Why:** Controllers are the entry point for all HTTP and WebSocket interactions. Generating them with a consistent structure ensures route registration, validation, and error handling are set up correctly from the start.\n\n**Benefits:** Automatic route registration in the module, consistent request/response patterns, clear separation between routing and business logic, WebSocket support out of the box.\n\n**Good practices:**\n- One controller per HTTP action (e.g. `UserCreateController`, `UserListController`) \u2014 avoid multi-action controllers.\n- Controllers should be thin: validate input, call a service, return a response. No business logic inside.\n- Prefix route names with the module (e.g. `api.user.create`) to avoid cross-module collisions.\n- Use the generated route name constant everywhere instead of hardcoding URL strings.\n\n---\n\n### Cron\n\nGenerates a cron job class in `modules/<name>/src/crons/<Name>Cron.ts` and registers it in the module. Automatically installs `@ooneex/cron`:\n\n```bash\noo make:cron --name Cleanup --module user\n```\n\n**Why:** Ad-hoc scheduled scripts outside the application are fragile, hard to monitor, and disconnected from the codebase. Cron classes live inside the module that owns the task, are registered with the DI container, and benefit from the same logging and error handling as the rest of the application.\n\n**Benefits:** Centralised schedule management, full access to injected services and repositories, observable via the application logger, easy to disable per environment.\n\n**Good practices:**\n- Name cron classes after the task, not the schedule (e.g. `ExpiredTokenCleanupCron`, not `DailyCron`).\n- Keep the cron class small \u2014 delegate actual work to a service method so the logic is testable independently.\n- Always log the start, end, and outcome of each run.\n- Make cron jobs idempotent: running the same job twice should not corrupt data.\n- Disable background jobs in the `testing` environment to keep tests fast and deterministic.\n\n---\n\n### Database\n\nGenerates a database adapter class in `modules/<name>/src/databases/<Name>Database.ts`. Automatically installs `@ooneex/database`:\n\n```bash\noo make:database --name User --module user\n```\n\n**Why:** Direct use of the ORM or raw query builder in services tightly couples business logic to the database layer. A database adapter wraps the connection and query interface, making it straightforward to configure per-module connections, switch drivers, or mock the database in tests.\n\n**Benefits:** Consistent connection configuration per module, single place to add query logging or instrumentation, easier to test services in isolation by injecting a mock adapter.\n\n**Good practices:**\n- Use the database adapter for raw queries or bulk operations that fall outside the repository pattern.\n- Never expose the raw ORM connection object outside the adapter class.\n- Configure connection pool sizes and timeouts in one place inside the adapter.\n- Prefer the repository pattern for standard CRUD; reach for the database adapter only when you need full query control.\n\n---\n\n### Docker\n\nAdds a Docker service to `modules/app/docker-compose.yml`. Creates the file if it does not exist. Available services: `postgres`, `mysql`, `mongodb`, `redis`, `rabbitmq`, `nats`, `elasticsearch`, `clickhouse`, `minio`, `memcached`, `prometheus`, `grafana`, `jaeger`, `keycloak`, `vault`, `temporal`, `libretranslate`, `maildev`:\n\n```bash\noo make:docker\noo make:docker --name postgres\noo make:docker --name redis\n```\n\n**Why:** Manually writing Docker Compose service definitions is repetitive, error-prone, and inconsistent across projects. The generator adds a pre-configured, production-ready service block so local infrastructure matches what the application expects.\n\n**Benefits:** Consistent port mappings and environment variables across the team, generated health-check and volume definitions, no need to memorise image names or versions.\n\n**Good practices:**\n- Commit `docker-compose.yml` to source control so every developer uses identical service versions.\n- Use named volumes for persistent data (databases) and anonymous volumes for ephemeral services (caches).\n- Never use Docker Compose in production \u2014 it is a local development tool only.\n- Pin image versions (e.g. `postgres:16`) rather than using `latest` to keep environments stable.\n- Add service dependencies (`depends_on`) so the application container only starts after its databases are healthy.\n\n---\n\n### Entity\n\nGenerates a TypeORM entity class in `modules/<name>/src/entities/<Name>Entity.ts` and registers it in `SharedModule`. Automatically installs `@ooneex/entity`:\n\n```bash\noo make:entity --name User --module user\noo make:entity --name User --module user --tableName users\n```\n\n**Why:** Entities are the single source of truth for your database schema. Generating them with consistent decorators and base class inheritance ensures that timestamps, soft deletes, and other cross-cutting concerns are applied uniformly across every table.\n\n**Benefits:** Automatic registration in `SharedModule`, consistent column conventions (snake_case table names, `created_at`/`updated_at` timestamps), TypeScript types aligned with the database schema.\n\n**Good practices:**\n- Always specify the table name explicitly to avoid surprises from TypeORM's pluralisation logic.\n- Keep entities as pure data structures \u2014 no business logic, no service calls inside entity methods.\n- Add database indexes to columns used in frequent `WHERE` or `ORDER BY` clauses.\n- Use enums for columns with a fixed set of values to enforce data integrity at the database level.\n- Create a migration immediately after adding or modifying an entity so schema and code stay in sync.\n\n---\n\n### Logger\n\nGenerates a logger class in `modules/<name>/src/loggers/<Name>Logger.ts`. Automatically installs `@ooneex/logger`:\n\n```bash\noo make:logger --name Audit --module user\n```\n\n**Why:** Using a global logger everywhere produces undifferentiated log output that is hard to filter by feature or severity. A dedicated logger class per domain adds a consistent context (module name, logger name) to every log entry, making logs actionable in production.\n\n**Benefits:** Structured log entries with automatic context tags, easy to route specific loggers to different backends (file, Better Stack, etc.), no need to repeat context strings across every log call.\n\n**Good practices:**\n- Use the `Audit` logger for security-sensitive actions (login, permission changes) and the default app logger for operational events.\n- Always log at the correct level: `debug` for internal state, `info` for significant business events, `warn` for recoverable problems, `error` for failures that need attention.\n- Include relevant IDs (user ID, request ID) in every log entry to enable correlation across services.\n- Never log sensitive data such as passwords, tokens, or payment details.\n\n---\n\n### Mailer\n\nGenerates a mailer class (`<Name>Mailer.ts`) and its JSX template (`<Name>MailerTemplate.tsx`) in `modules/<name>/src/mailers/`. Automatically installs `@ooneex/mailer`:\n\n```bash\noo make:mailer --name Welcome --module user\n```\n\n**Why:** Composing email HTML inline or with raw string templates is brittle and hard to preview. The generator creates a typed mailer class paired with a JSX template, keeping email logic and presentation cleanly separated and type-safe.\n\n**Benefits:** JSX template enables component reuse and design-system consistency across emails, typed mailer class prevents missing required variables, easy to test rendering without sending real emails.\n\n**Good practices:**\n- One mailer per transactional email type (e.g. `WelcomeMailer`, `PasswordResetMailer`).\n- Never send emails synchronously on the request path \u2014 enqueue them via a job or pub/sub event.\n- Always provide a plain-text fallback alongside the HTML template for clients that block images.\n- Test email rendering in multiple clients (Gmail, Outlook, Apple Mail) before deploying \u2014 CSS support varies widely.\n- Use the `testing` environment mailer backend to capture sent emails without delivering them.\n\n---\n\n### Middleware\n\nGenerates an HTTP or WebSocket middleware class registered in the target module. Automatically installs `@ooneex/middleware`:\n\n```bash\noo make:middleware --name Auth --module user\noo make:middleware --name Auth --module user --isSocket\n```\n\n**Why:** Cross-cutting concerns like authentication, CORS, request logging, and input sanitisation should not live inside controllers. Middleware classes intercept requests before they reach a controller, keeping that logic reusable and independently testable.\n\n**Benefits:** Reusable across multiple controllers within the module, auto-registered in the middleware pipeline, full access to injected services via DI, works identically for HTTP and WebSocket routes.\n\n**Good practices:**\n- Keep middleware single-purpose (e.g. `AuthMiddleware` only handles authentication, not rate limiting).\n- Always call `next()` explicitly or return a response \u2014 never leave the pipeline hanging.\n- Order matters: authentication middleware must run before authorisation middleware.\n- Avoid heavy computation in middleware; defer expensive work to the service layer.\n- Write unit tests that verify the middleware passes, blocks, and modifies requests as expected.\n\n---\n\n### Permission\n\nGenerates a permission class in `modules/<name>/src/permissions/<Name>Permission.ts`. Automatically installs `@ooneex/permission`:\n\n```bash\noo make:permission --name User --module user\n```\n\n**Why:** Scattering permission checks across controllers and services leads to inconsistency and makes auditing access control difficult. A dedicated permission class per domain centralises all access rules for that domain in one reviewable place.\n\n**Benefits:** All permissions for a domain are discoverable in a single file, easy to audit who can do what, permissions can be reused across multiple controllers without duplication, changes to access rules require touching only one class.\n\n**Good practices:**\n- Name permissions after the action and resource (e.g. `UserPermission` checks `canCreate`, `canUpdate`, `canDelete`).\n- Always check permissions in middleware or the service layer \u2014 never in the entity or repository.\n- Combine with roles (RBAC) for coarse-grained access and permissions for fine-grained control.\n- Write tests that assert both allowed and denied cases for every permission rule.\n- Never hardcode user IDs or emails inside permission logic; use roles and attributes instead.\n\n---\n\n### PubSub\n\nGenerates a pub/sub event class in `modules/<name>/src/events/<Name>Event.ts` and registers it in the module. Automatically installs `@ooneex/pub-sub`:\n\n```bash\noo make:pubsub --name UserCreated --module user\noo make:pubsub --name UserCreated --module user --channel user-created\n```\n\n**Why:** Direct calls between modules create tight coupling that makes the codebase fragile and hard to extend. Pub/sub events decouple the publisher from the subscriber: the `user` module emits `UserCreated` without knowing or caring which other modules react to it.\n\n**Benefits:** Loose coupling between modules, multiple subscribers can react to the same event independently, easy to add new reactions without modifying the publisher, events are named and typed so their contracts are explicit.\n\n**Good practices:**\n- Name events in the past tense (e.g. `UserCreated`, `OrderShipped`) to make clear they describe something that already happened.\n- Keep event payloads small and serialisable \u2014 include IDs rather than full entity objects where possible.\n- Subscribe in the module that owns the reaction, not in the module that owns the event.\n- Make event handlers idempotent: the same event may be delivered more than once in failure scenarios.\n- Log every event published and consumed to simplify debugging distributed flows.\n\n---\n\n### Repository\n\nGenerates a repository class for data access in `modules/<name>/src/repositories/<Name>Repository.ts`. Automatically installs `@ooneex/repository`:\n\n```bash\noo make:repository --name User --module user\n```\n\n**Why:** Putting database queries directly in services mixes business logic with persistence concerns and makes services impossible to test without a database. The repository pattern isolates all data-access code behind a typed interface that can be mocked in tests.\n\n**Benefits:** Services remain database-agnostic, all queries for an entity are discoverable in one class, easy to swap the underlying ORM or database without touching business logic, clean boundary for unit testing.\n\n**Good practices:**\n- One repository per entity (e.g. `UserRepository` owns all queries against the `users` table).\n- Repositories should only contain query logic \u2014 no business rules, no validation, no event publishing.\n- Use descriptive method names that reflect intent (e.g. `findActiveByEmail`, `findExpiredTokens`) rather than generic `find` with complex filter objects.\n- Return domain objects or plain data \u2014 never expose raw ORM query builders to callers.\n- Add pagination to any method that can return an unbounded number of rows.\n\n---\n\n### Service\n\nGenerates a service class in `modules/<name>/src/services/<Name>Service.ts`. Automatically installs `@ooneex/service`:\n\n```bash\noo make:service --name User --module user\n```\n\n**Why:** Business logic scattered across controllers is impossible to test, reuse, or reason about. Services are the home of all business rules, orchestrating repositories, events, and other services in a single, testable unit.\n\n**Benefits:** Business logic is testable without HTTP, reusable across multiple controllers or cron jobs, dependencies are explicit via constructor injection, easy to mock at the service boundary in integration tests.\n\n**Good practices:**\n- One service per aggregate or major business capability (e.g. `UserService` for user lifecycle, `BillingService` for payment flows).\n- Services should call repositories for data, never query the database directly.\n- Keep services stateless \u2014 all required data should come from method arguments or injected dependencies.\n- Raise typed exceptions (e.g. `UserNotFoundException`) rather than returning `null` or error codes.\n- A service method should do one thing; if a method grows beyond ~20 lines, consider extracting a helper or sub-service.\n\n---\n\n### Storage\n\nGenerates a file storage class in `modules/<name>/src/storage/<Name>Storage.ts`. Automatically installs `@ooneex/storage`:\n\n```bash\noo make:storage --name Avatar --module user\n```\n\n**Why:** Coupling file upload logic directly to a specific provider (S3, Cloudflare R2, local filesystem) makes it painful to change backends and duplicates configuration across the codebase. A storage class abstracts the provider behind a consistent interface scoped to a specific asset type.\n\n**Benefits:** Provider-agnostic uploads and reads, all storage configuration for an asset type in one class, easy to switch between local filesystem (development) and cloud storage (production) via environment variables, consistent file-naming and path conventions.\n\n**Good practices:**\n- Name storage classes after the asset they manage (e.g. `AvatarStorage`, `InvoiceStorage`).\n- Always validate file type and size before passing to the storage class \u2014 never trust client-supplied content types.\n- Generate deterministic, collision-resistant file names (e.g. `{userId}/{uuid}.{ext}`) rather than using the original filename.\n- Never store the full URL in the database \u2014 store only the path or key and derive the URL at read time so it works across environments.\n- Delete orphaned files when the associated entity is deleted to avoid unbounded storage growth.\n\n---\n\n### Vector Database\n\nGenerates a vector database class in `modules/<name>/src/databases/<Name>VectorDatabase.ts`. Automatically installs `@ooneex/rag`:\n\n```bash\noo make:vector-database --name Knowledge --module user\n```\n\n**Why:** Semantic search and Retrieval-Augmented Generation (RAG) require storing and querying high-dimensional embeddings, which relational databases are not designed for. A dedicated vector database class encapsulates the embedding model, index configuration, and similarity-search logic in one place.\n\n**Benefits:** Centralised embedding and retrieval strategy per knowledge domain, easy to swap vector backends (pgvector, Qdrant, etc.), consistent chunking and metadata conventions, decoupled from the LLM layer so both can evolve independently.\n\n**Good practices:**\n- One vector database class per knowledge domain (e.g. `KnowledgeVectorDatabase`, `ProductCatalogVectorDatabase`).\n- Always store the source document ID alongside each embedding so retrieved chunks can be traced back to their origin.\n- Use a consistent chunking strategy (fixed-size or sentence-boundary) within a class \u2014 mixing strategies pollutes the index.\n- Re-index when the embedding model changes; embeddings from different models are not comparable.\n- Cache frequently retrieved embeddings to avoid redundant model calls on hot queries.\n\n---\n\n## Claude\n\nThis project ships with a set of **Claude Code skills** \u2014 pre-built instruction sets that tell Claude exactly how to scaffold, implement, and test each type of artefact in this codebase. Skills eliminate the gap between \"generate the files\" and \"ship working code\": each skill runs the CLI generator, reads the output, completes the implementation, writes tests, and lints \u2014 all in one `/command`.\n\n### Why Skills?\n\nRunning `oo make:service` creates a skeleton. A Claude skill does that *and* completes the business logic, writes a meaningful test suite, applies coding conventions, and formats the result \u2014 turning a 10-step workflow into a single prompt.\n\n**Benefits:**\n- Consistent code quality across every artefact, regardless of who wrote it\n- Conventions (visibility modifiers, naming suffixes, DI patterns) are enforced automatically\n- Tests are generated alongside implementation, not as an afterthought\n- Skills chain together \u2014 `make:controller` automatically triggers `make:service` and `make:pubsub`\n\n### Setup\n\nBefore using skills, generate the `.claude/` directory with all skill files and the project `CLAUDE.md`:\n\n```bash\noo claude:skill:create\n```\n\nThis writes `.claude/CLAUDE.md` and one `SKILL.md` per skill under `.claude/skills/<skill-name>/`. Re-run any time you upgrade the CLI to pick up new or updated skills. Commit the generated files so every team member gets the same skill definitions without running the command themselves.\n\n### How to Use\n\nOpen Claude Code in the project root and type `/skill-name`. Claude will execute the full workflow described in the skill. You can pass arguments inline:\n\n```\n/make:service --name=UserCreate --module=user\n/make:controller --name=UserCreate --module=user --route.path=/users --route.method=POST\n/commit\n```\n\nIf you omit arguments, Claude will prompt you for the required values.\n\n> **Important:** Always run skills from the project root, not from inside a module directory.\n\n### Available Skills\n\n#### Code Quality\n\n| Skill | Description |\n|---|---|\n| `/optimize` | Enforce naming conventions, remove duplication, improve performance, and restructure tests across a module |\n| `/commit` | Analyze staged changes, group them by module, and create properly scoped conventional commits |\n\n#### Generators\n\n| Skill | Description |\n|---|---|\n| `/make:ai` | Generate an AI integration class with `run` and `runStream` methods, wired to `@ooneex/ai` |\n| `/make:analytics` | Generate an analytics handler class for tracking domain events via `@ooneex/analytics` |\n| `/make:cache` | Generate a cache handler class with key and TTL management via `@ooneex/cache` |\n| `/make:command` | Generate a CLI command class implementing `ICommand` via `@ooneex/cli` |\n| `/make:controller` | Generate an HTTP or WebSocket controller with route type, validation, roles, service, and pub/sub event |\n| `/make:cron` | Generate a cron job class registered in its module via `@ooneex/cron` |\n| `/make:database` | Generate a database adapter class for raw queries via `@ooneex/database` |\n| `/make:entity` | Generate a TypeORM entity class registered in `SharedModule` via `@ooneex/entity` |\n| `/make:logger` | Generate a structured logger class with domain context via `@ooneex/logger` |\n| `/make:mailer` | Generate a mailer class and its JSX email template via `@ooneex/mailer` |\n| `/make:middleware` | Generate an HTTP or WebSocket middleware class registered in the module via `@ooneex/middleware` |\n| `/make:permission` | Generate a permission class centralising access rules for a domain via `@ooneex/permission` |\n| `/make:pubsub` | Generate a pub/sub event class registered in the module via `@ooneex/pub-sub` |\n| `/make:repository` | Generate a repository class for typed data access via `@ooneex/repository` |\n| `/make:service` | Generate a service class implementing `IService` with business logic and tests |\n| `/make:storage` | Generate a file storage class for asset management via `@ooneex/storage` |\n| `/make:vector-database` | Generate a vector database class for semantic search and RAG via `@ooneex/rag` |\n\n#### Database\n\n| Skill | Description |\n|---|---|\n| `/migration:create` | Generate a migration file with `up`/`down` methods, index guidance, and structural tests |\n| `/seed:create` | Generate a seed class and its YAML data file with idempotent insertion logic |\n\n### Coding Conventions Enforced by Skills\n\nAll generator skills automatically apply the conventions defined in `/optimize`:\n\n- **Visibility modifiers** \u2014 every class method and property has explicit `public`, `private`, or `protected`\n- **Naming suffixes** \u2014 types end with `Type`, interfaces start with `I`\n- **Arrow functions** \u2014 used everywhere except class methods\n- **No non-null assertions** \u2014 use default values or optional types instead\n- **Dependency injection** \u2014 constructor injection via `@inject()` from `@ooneex/container`\n- **Code hygiene** \u2014 no unused imports, no dead code, no bare `TODO` comments\n\n---\n\n## Release\n\n```bash\noo make:release\n```\n\nScans every `packages/` and `modules/` directory for unreleased conventional commits and, for each one that has them, performs a full release cycle automatically:\n\n1. **Detects unreleased work** \u2014 finds the last git tag matching `<package-name>@*` and lists all conventional commits that have landed since then in that directory. Packages with no new commits are skipped.\n2. **Bumps the version** in `package.json`:\n   - `minor` (e.g. `1.2.0 \u2192 1.3.0`) when any commit is of type `feat`\n   - `patch` (e.g. `1.2.0 \u2192 1.2.1`) for all other types (`fix`, `refactor`, `perf`, `docs`, `chore`, \u2026)\n3. **Updates `CHANGELOG.md`** with a dated version section. Commits are grouped into standard Keep-a-Changelog categories and linked to their SHA on the remote:\n\n   | Commit type | Changelog category |\n   |---|---|\n   | `feat` | Added |\n   | `fix` | Fixed |\n   | `refactor`, `perf`, `style`, `docs`, `build`, `ci`, `chore` | Changed |\n   | `revert` | Removed |\n\n4. **Creates a release commit** \u2014 stages `package.json` and `CHANGELOG.md` then commits with the message `chore(release): <name>@<version>`.\n5. **Creates an annotated git tag** \u2014 `<name>@<version>` (e.g. `@acme/user@1.3.0`).\n6. **Prompts to push** \u2014 after all packages are processed, asks whether to push commits and tags to the remote. If confirmed, it also runs `bun install`, commits the updated `bun.lock`, and pushes everything.\n\n> **Note:** This command requires conventional commits (`type(scope): Subject`). Non-conventional commits are silently ignored when building the changelog.\n\n---\n\n## Scripts\n\n| Command | Description |\n|---|---|\n| `bun run fmt` | Format all source files with Biome |\n| `bun run lint` | Lint all modules with Biome and TypeScript |\n| `bun run test` | Run tests across all modules |\n| `bun run commit` | Interactive conventional commit prompt |\n";
 
 // src/templates/app/tsconfig.json.txt
 var tsconfig_json_default = `{
@@ -10713,13 +10713,6 @@ This project ships with Claude Code skills that scaffold, implement, and test ar
 | \`/migration:create\` | Generate a migration file with \`up\`/\`down\` methods and structural tests |
 | \`/seed:create\` | Generate a seed class and its YAML data file with idempotent insertion logic |
 
-#### Spec
-
-| Skill | Description |
-|---|---|
-| \`/spec:plan\` | Parse user-provided content and produce one \`specs/<spec-name>.spec.yml\` file per entity/action pair |
-| \`/spec:implement\` | Read a single spec YML entry and implement entity, repository, service, controller/command, and optional resources |
-
 ### Coding Conventions Enforced by Skills
 
 - **Visibility modifiers** \u2014 every class method and property has explicit \`public\`, \`private\`, or \`protected\`
@@ -10883,6 +10876,126 @@ git commit -m "chore(common): Update dependencies and cache package"
 Apply all coding conventions from the \`optimize\` skill.
 `;
 
+// src/templates/claude/skills/issue.improve.md.txt
+var issue_improve_md_default = `---
+name: issue:improve
+description: Improve a YAML issue file by rewriting the description into a structured format, extracting labels, and optionally splitting into smaller focused issues. Reads from modules/<module>/issues/<ID>.yml.
+---
+
+# Issue Improve
+
+Improve an existing YAML issue file: rewrite the description, suggest labels, and optionally split into smaller issues.
+
+## Workflow
+
+### 1. Locate the Issue File
+
+Ask the user for the issue identifier or file path if not already provided.
+Look for the file in \`modules/<module>/issues/<ID>.yml\` (default module: \`shared\`).
+Read the YAML file with the Read tool.
+
+### 2. Improve the Description
+
+Rewrite the \`description\` field into this structured format:
+
+\`\`\`markdown
+## Context
+<Background information explaining why this issue exists>
+
+## Goal
+<What needs to be achieved>
+
+## Acceptance Criteria
+- [ ] <Condition 1 that must be met>
+- [ ] <Condition 2 that must be met>
+- [ ] <\u2026>
+
+## Technical Notes
+<Optional: technical constraints or implementation hints \u2014 omit section if not applicable>
+\`\`\`
+
+Rules:
+- Preserve all factual information from the original description
+- Keep each section concise and actionable
+- Acceptance Criteria must be checkboxes (\`- [ ]\`), not prose
+- Omit \`## Technical Notes\` if there is nothing relevant to add
+
+### 3. Extract Labels
+
+Based on the improved description, suggest relevant labels:
+- Short (1\u20133 words), lowercase, hyphenated (e.g. \`bug\`, \`enhancement\`, \`performance\`, \`breaking-change\`)
+- Deduplicate against labels already present in the YAML
+- Present suggestions to the user and ask which ones to add
+
+Common label vocabulary:
+\`bug\`, \`enhancement\`, \`performance\`, \`refactor\`, \`security\`, \`breaking-change\`,
+\`documentation\`, \`testing\`, \`database\`, \`api\`, \`ui\`, \`infrastructure\`, \`cleanup\`
+
+### 4. Check Whether Splitting Is Needed
+
+Evaluate whether the issue is large or complex enough to split. An issue needs splitting when it:
+- Spans multiple unrelated concerns or implementation areas
+- Cannot be completed in one focused developer session
+- Contains several independent acceptance criteria that could ship separately
+
+Skip splitting if the issue is already small and focused.
+
+### 5. Split Into Sub-Issues (if needed)
+
+Break the issue into 3\u20137 small, self-contained, independently implementable issues.
+
+For each sub-issue:
+- Generate a new identifier using the format \`XXX-000000\` (3 uppercase letters + 6 digits)
+- Write a new YAML file to the same \`modules/<module>/issues/\` directory
+- Inherit \`state\`, \`priority\`, and \`labels\` from the parent issue
+
+Sub-issue YAML structure:
+\`\`\`yaml
+id: "<generated-id>"
+title: "<action-oriented title: verb + noun>"
+state: "<parent state>"
+priority: "<parent priority>"
+description: |
+  <2\u20135 sentences: context, goal, and acceptance criteria>
+labels:
+  - "<label>"
+\`\`\`
+
+### 6. Save Changes
+
+Update the original YAML file with the improved description and new labels using the Edit or Write tool.
+Confirm each file written with a success message showing the relative path.
+
+## YAML Structure Reference
+
+\`\`\`yaml
+id: "OON-123456"
+title: "Add user validation"
+state: "In Progress"
+priority: "High"
+description: |
+  ## Context
+  \u2026
+  ## Goal
+  \u2026
+  ## Acceptance Criteria
+  - [ ] \u2026
+labels:
+  - "enhancement"
+  - "api"
+comments:
+  - author: "Alice"
+    message: "Some comment"
+\`\`\`
+
+## Notes
+
+- Never invent facts \u2014 only restructure and clarify what is already in the description
+- If the description is missing or empty, tell the user and stop
+- Always show the user the improved description before writing, and ask for confirmation
+- When splitting, inform the user of each sub-issue file created
+`;
+
 // src/templates/claude/skills/make.ai.md.txt
 var make_ai_md_default = `---
 name: make:ai
@@ -14013,286 +14126,6 @@ bun run lint
 Apply all coding conventions from the \`optimize\` skill.
 `;
 
-// src/templates/claude/skills/spec.implement.md.txt
-var spec_implement_md_default = `---
-name: spec:implement
-description: Implement a single spec from a YML entry. Use when executing a planned spec, creating or updating an entity, repository, service, controller/command, and optional resources.
----
-
-# Spec Implement
-
-Use the single spec YML entry provided by the user and implement it.
-
-## Important
-
-Always run all commands from the **root of the project** (the monorepo root), not from inside individual packages.
-
-## Steps
-
-### 1. Read the spec YML
-
-Use the YML content provided by the user. Do not search for or locate a file on your own.
-
-If no YML content was provided, stop and ask the user to supply the spec YML or run \`/spec:plan\` first.
-
-A spec YML looks like:
-
-\`\`\`yaml
-name: "organization.create"
-entity: "organization"
-description: "Admin creates a new organization"
-roles:
-  - super_admin
-  - admin
-permissions:
-  - name: "organization:create"
-    description: "Grants the ability to create a new organization"
-resources:
-  entity: OrganizationEntity
-  repository: OrganizationRepository
-  service: OrganizationCreateService
-  controller: OrganizationCreateController
-  permission: OrganizationCreatePermission
-\`\`\`
-
-### 2. Analyse the spec
-
-Extract:
-
-- \`name\` \u2014 dot-notation identifier (e.g. \`"user.create"\`)
-- \`entity\` \u2014 the resource being acted on (e.g. \`"user"\`)
-- \`description\` \u2014 what the spec does
-- \`roles\` \u2014 list of roles with access; check \`modules/shared/src/roles.yml\` to map role slugs to their canonical values
-- \`permissions\` \u2014 list of objects with \`name\` (\`"entity:action"\` format) and optional \`description\`
-- \`resources\` \u2014 map of resource keys to PascalCase class names; this is the authoritative list of what to create
-
-Derive the HTTP method from the action part of \`name\`:
-- \`.create\` \u2192 \`post\`
-- \`.read\` / \`.list\` / \`.search\` \u2192 \`get\`
-- \`.update\` \u2192 \`put\` or \`patch\`
-- \`.delete\` \u2192 \`delete\`
-
-### 3. Create or update the entity
-
-Only if \`resources.entity\` is present.
-
-\`\`\`
-/make:entity --name=<resources.entity> --module=<module>
-\`\`\`
-
-### 4. Create or update the repository
-
-Only if \`resources.repository\` is present.
-
-\`\`\`
-/make:repository --name=<resources.repository> --module=<module>
-\`\`\`
-
-Retain only the CRUD methods that are needed by this spec (e.g. \`.create\` spec needs \`save\`; \`.read\` needs \`findById\`; \`.list\` needs \`find\`; \`.delete\` needs \`delete\`).
-
-### 5. Create or update the service
-
-Only if \`resources.service\` is present.
-
-\`\`\`
-/make:service --name=<resources.service> --module=<module>
-\`\`\`
-
-Inject the repository into the service via the constructor and implement \`execute()\` with the business logic described by the spec.
-
-### 6. Create or update the controller or command
-
-**Controller** \u2014 only if \`resources.controller\` is present:
-
-\`\`\`
-/make:controller --name=<resources.controller> --module=<module> --route-name=<spec.name> --route-path=<derived-path> --route-method=<derived-method>
-\`\`\`
-
-Derive the route path from the entity and action (e.g. \`"user.create"\` \u2192 \`/users\`, \`"user.read"\` \u2192 \`/users/:id\`).
-
-Inject the service into the controller. Set \`roles\` in the \`@Route\` decorator from \`spec.roles\` as uppercase string literals (e.g., \`"ROLE_USER"\`, \`"ROLE_ADMIN"\`). Apply each permission \`name\` from \`spec.permissions\` to the route decorator when a \`permissions\` field is available on \`@Route\`.
-
-**Command** \u2014 only if \`resources.command\` is present:
-
-\`\`\`
-/make:command --name=<resources.command> --module=<module>
-\`\`\`
-
-Inject the service into the command. Set \`getName()\` to \`"<entity>:<action>"\` format.
-
-### 7. Create or update optional resources
-
-Create each resource that is present in \`resources\` beyond the core four. Use the class name from the \`resources\` map as the \`--name\` value. Do not create resources that are absent from the map.
-
-| \`resources\` key  | Skill                                                                       |
-|------------------|-----------------------------------------------------------------------------|
-| \`permission\`     | \`/make:permission --name=<resources.permission> --module=<module>\`          |
-| \`middleware\`     | \`/make:middleware --name=<resources.middleware> --module=<module>\`          |
-| \`cache\`          | \`/make:cache --name=<resources.cache> --module=<module>\`                    |
-| \`pubsub\`         | \`/make:pubsub --name=<resources.pubsub> --module=<module>\`                  |
-| \`mailer\`         | \`/make:mailer --name=<resources.mailer> --module=<module>\`                  |
-| \`logger\`         | \`/make:logger --name=<resources.logger> --module=<module>\`                  |
-| \`analytics\`      | \`/make:analytics --name=<resources.analytics> --module=<module>\`            |
-| \`storage\`        | \`/make:storage --name=<resources.storage> --module=<module>\`                |
-| \`cron\`           | \`/make:cron --name=<resources.cron> --module=<module>\`                      |
-| \`ai\`             | \`/make:ai --name=<resources.ai> --module=<module>\`                          |
-| \`database\`       | \`/make:database --name=<resources.database> --module=<module>\`              |
-| \`vectorDatabase\` | \`/make:vector-database --name=<resources.vectorDatabase> --module=<module>\` |
-
-### 8. Lint and format
-
-\`\`\`bash
-bun run fmt
-bun run lint
-\`\`\`
-
-### 9. Confirm
-
-Report:
-
-- Spec \`name\` implemented
-- Resources created or updated (list each key and class name from \`resources\`)
-- Any step that was skipped and why
-
-## Notes
-
-- The \`resources\` map is the single source of truth for what to create \u2014 do not infer additional resources beyond what is listed.
-- If a resource already exists, update it rather than overwrite it \u2014 add new methods, columns, or routes without removing existing ones unless they conflict.
-- Derive all names, paths, and methods from the spec; never ask the user for values that can be inferred.
-- Apply all coding conventions from the \`optimize\` skill to every generated file.
-`;
-
-// src/templates/claude/skills/spec.plan.md.txt
-var spec_plan_md_default = `---
-name: spec:plan
-description: Analyse user-provided content and produce one spec YML file per operation under specs/. Use before /spec:implement to plan entities, CRUD actions, roles, and permissions.
----
-
-# Spec Plan
-
-Read the user-provided content (feature description, requirements, user stories, or raw notes) and produce one \`specs/<spec-name>.spec.yml\` file per operation.
-
-## Important
-
-Always run all commands from the **root of the project** (the monorepo root), not from inside individual packages.
-
-## Steps
-
-### 1. Read the user content
-
-Use only the content provided by the user in the current message. Do not search files or infer context from the repository.
-
-If no content was provided, stop and ask the user to describe the feature, entity, or workflow they want to plan.
-
-### 2. Identify entities and operations
-
-Extract every distinct entity mentioned or implied. For each entity determine which CRUD operations are required:
-
-| Action keyword in content             | Spec action suffix |
-|---------------------------------------|--------------------|
-| create, add, register, submit, invite | \`.create\`          |
-| get, fetch, view, read, show, detail  | \`.read\`            |
-| list, search, browse, filter, query   | \`.list\`            |
-| update, edit, modify, change, patch   | \`.update\`          |
-| delete, remove, archive, deactivate   | \`.delete\`          |
-
-Produce one spec per \`<entity>.<action>\` pair.
-
-### 3. Build each spec
-
-For each spec, populate the following fields:
-
-**\`name\`** \u2014 dot-notation identifier: \`"<entity>.<action>"\` (snake_case entity, e.g. \`"blog_post.create"\`).
-
-**\`entity\`** \u2014 the resource name in snake_case (e.g. \`"blog_post"\`).
-
-**\`description\`** \u2014 describes what the operation does, the data it acts on, and any key business rules or constraints an implementer must know. Derived from the user content.
-
-**\`roles\`** \u2014 list of role identifiers that may perform this operation. Derive from the user content; default to \`["user"]\` when not specified. Look inside \`modules/shared/src/roles.yml\` for the list of available roles in the project.
-
-**\`permissions\`** \u2014 list of fine-grained access-control entries that guard this operation. Each object has:
-- \`name\`: \`"<entity>:<action>"\` format (e.g. \`"blog_post:create"\`) \u2014 uniquely identifies the permission across the system
-- \`description\`: one sentence explaining what this permission grants, who it protects, and any conditions or limits (e.g. ownership, tenant scope). Required \u2014 never leave empty.
-
-**\`resources\`** \u2014 map of PascalCase class names to create for this spec. Use only the keys listed under **Resources to generate** in the user message; omit any key not in that list.
-
-**Core (always include):**
-- \`entity\`: the data model class (e.g. \`"BlogPostEntity"\`)
-- \`repository\`: the data-access class (e.g. \`"BlogPostRepository"\`)
-- \`service\`: the business-logic class (e.g. \`"BlogPostService"\`)
-- \`controller\`: the HTTP handler class (e.g. \`"BlogPostCreateController"\`); use \`command\` instead when the spec implies a CLI operation (e.g. \`"BlogPostCreateCommand"\`)
-
-**Optional (include only when the trigger condition applies \u2014 names use \`<PascalSpec>\` derived from \`name\`, e.g. \`"blog_post.create"\` \u2192 \`"BlogPostCreate"\`):**
-
-| Key              | Trigger condition                                               | Example value                    |
-|------------------|-----------------------------------------------------------------|----------------------------------|
-| \`permission\`     | Spec has \`roles\` or \`permissions\` defined                       | \`"BlogPostCreatePermission"\`     |
-| \`middleware\`     | Spec implies auth, rate-limiting, or request transformation     | \`"BlogPostCreateMiddleware"\`     |
-| \`cache\`          | Spec implies read-heavy or list endpoints                       | \`"BlogPostCreateCache"\`          |
-| \`pubsub\`         | Spec mutates state (post, put, patch, delete)                   | \`"BlogPostCreatePubSub"\`         |
-| \`mailer\`         | Spec mentions email, notification, or invitation                | \`"BlogPostCreateMailer"\`         |
-| \`logger\`         | Spec mentions audit, log, or traceability                       | \`"BlogPostCreateLogger"\`         |
-| \`analytics\`      | Spec mentions tracking, metrics, or reporting                   | \`"BlogPostCreateAnalytics"\`      |
-| \`storage\`        | Spec mentions file, upload, or attachment                       | \`"BlogPostCreateStorage"\`        |
-| \`cron\`           | Spec mentions scheduled, periodic, or background task          | \`"BlogPostCreateCron"\`           |
-| \`ai\`             | Spec mentions AI, embedding, or generation                      | \`"BlogPostCreateAi"\`             |
-| \`database\`       | Spec implies a new database connection or datasource            | \`"BlogPostCreateDatabase"\`       |
-| \`vectorDatabase\` | Spec mentions vector search or similarity                       | \`"BlogPostCreateVectorDatabase"\` |
-
-### 4. Write spec files
-
-For each spec, create the file \`specs/<spec-name>.spec.yml\` where \`<spec-name>\` equals the \`name\` field with dots replaced by hyphens (e.g. \`specs/blog-post-create.spec.yml\`).
-
-Write one YAML block per file using the structure below. Do **not** combine multiple specs into a single file.
-
-\`\`\`yaml
-name: "<entity>.<action>"
-entity: "<entity>"
-description: "<description of what the operation does, the data it acts on, and any key business rules or constraints an implementer must know>"
-roles:
-  - <role>
-permissions:
-  - name: "<entity>:<action>"
-    description: "<what this permission grants, who it protects, and any conditions or limits>"
-resources:
-  # Core \u2014 always present
-  entity: <EntityName>
-  repository: <EntityRepositoryName>
-  service: <PascalSpecServiceName>
-  controller: <PascalSpecControllerName>  # or command: <PascalSpecCommandName> for CLI ops
-  # Optional \u2014 include only when triggered
-  # permission: <PascalSpecPermissionName>
-  # middleware: <PascalSpecMiddlewareName>
-  # cache: <PascalSpecCacheName>
-  # pubsub: <PascalSpecPubSubName>
-  # mailer: <PascalSpecMailerName>
-  # logger: <PascalSpecLoggerName>
-  # analytics: <PascalSpecAnalyticsName>
-  # storage: <PascalSpecStorageName>
-  # cron: <PascalSpecCronName>
-  # ai: <PascalSpecAiName>
-  # database: <PascalSpecDatabaseName>
-  # vectorDatabase: <PascalSpecVectorDatabaseName>
-\`\`\`
-
-Create the \`specs/\` directory if it does not exist.
-
-### 5. Confirm
-
-After all files are written, report:
-
-- Total number of specs created
-- List of file paths written (one per line)
-- Any entity or action that was ambiguous and how it was resolved
-
-## Notes
-
-- One file per spec \u2014 never merge multiple specs into one file.
-- Derive everything from the user content; never ask for values that can be inferred.
-- If the user content implies a CLI operation rather than an HTTP endpoint, add \`kind: command\` at the top level of the spec.
-- Specs are consumed by \`/spec:implement\` \u2014 keep field names and values precise so that skill can infer types without ambiguity.
-`;
-
 // src/commands/ClaudeSkillCreateCommand.ts
 var skills = {
   "make.ai": make_ai_md_default,
@@ -14314,8 +14147,7 @@ var skills = {
   "make.service": make_service_md_default,
   "make.storage": make_storage_md_default,
   "make.vector-database": make_vector_database_md_default,
-  "spec.implement": spec_implement_md_default,
-  "spec.plan": spec_plan_md_default,
+  "issue.improve": issue_improve_md_default,
   commit: commit_md_default,
   optimize: optimize_md_default
 };
@@ -14841,46 +14673,6 @@ _oo_modules() {
   fi
 }
 
-_oo_issues() {
-  local module="shared"
-  local i
-  for (( i = 1; i < $#words; i++ )); do
-    if [[ "\${words[i]}" == "--module" ]]; then
-      module="\${words[i+1]}"
-      break
-    elif [[ "\${words[i]}" == --module=* ]]; then
-      module="\${words[i]#--module=}"
-      break
-    fi
-  done
-  local -a issues
-  local issues_dir="modules/\${module}/issues"
-  if [[ -d "$issues_dir" ]]; then
-    issues=(\${(@f)"$(command ls -1 "\${issues_dir}" 2>/dev/null | sed 's/\\.yml$//')"})
-    compadd -a issues
-  fi
-}
-
-_oo_specs() {
-  local module="shared"
-  local i
-  for (( i = 1; i < $#words; i++ )); do
-    if [[ "\${words[i]}" == "--module" ]]; then
-      module="\${words[i+1]}"
-      break
-    elif [[ "\${words[i]}" == --module=* ]]; then
-      module="\${words[i]#--module=}"
-      break
-    fi
-  done
-  local -a specs
-  local specs_dir="modules/\${module}/specs"
-  if [[ -d "$specs_dir" ]]; then
-    specs=(\${(@f)"$(command ls -1 "\${specs_dir}" 2>/dev/null | sed 's/\\.spec\\.yml$//')"})
-    compadd -a specs
-  fi
-}
-
 _oo_custom_commands() {
   local -a cmds
   if [[ -d modules ]]; then
@@ -14925,8 +14717,6 @@ _oo() {
     'make\\:resource\\:book:Generate book resource (entity, migration, repository)'
     'issue\\:create:Create a YAML skeleton file for a new issue'
     'issue\\:pull:Pull an issue from Linear and save it as a YAML file'
-    'spec\\:implement:Implement a spec using Claude'
-    'spec\\:plan:Generate a spec plan for an issue using Claude'
     'seed\\:create:Generate a new seed file'
     'seed\\:run:Run seeds for all modules'
     'make\\:service:Generate a new service class'
@@ -15033,16 +14823,6 @@ _oo() {
             '--id=[Linear issue ID or identifier]:id' \\
             '--module=[Module name]:module:_oo_modules'
           ;;
-        spec:implement)
-          _arguments -s \\
-            '--spec=[Spec identifier]:spec:_oo_specs' \\
-            '--module=[Module name]:module:_oo_modules'
-          ;;
-        spec:plan)
-          _arguments -s \\
-            '--issue=[Issue identifier]:issue:_oo_issues' \\
-            '--module=[Module name]:module:_oo_modules'
-          ;;
         migration:up|seed:run)
           _arguments -s \\
             '--drop[Drop the database before running]'
@@ -15068,46 +14848,6 @@ _ooneex_modules() {
   fi
 }
 
-_ooneex_issues() {
-  local module="shared"
-  local i
-  for (( i = 1; i < $#words; i++ )); do
-    if [[ "\${words[i]}" == "--module" ]]; then
-      module="\${words[i+1]}"
-      break
-    elif [[ "\${words[i]}" == --module=* ]]; then
-      module="\${words[i]#--module=}"
-      break
-    fi
-  done
-  local -a issues
-  local issues_dir="modules/\${module}/issues"
-  if [[ -d "$issues_dir" ]]; then
-    issues=(\${(@f)"$(command ls -1 "\${issues_dir}" 2>/dev/null | sed 's/\\.yml$//')"})
-    compadd -a issues
-  fi
-}
-
-_ooneex_specs() {
-  local module="shared"
-  local i
-  for (( i = 1; i < $#words; i++ )); do
-    if [[ "\${words[i]}" == "--module" ]]; then
-      module="\${words[i+1]}"
-      break
-    elif [[ "\${words[i]}" == --module=* ]]; then
-      module="\${words[i]#--module=}"
-      break
-    fi
-  done
-  local -a specs
-  local specs_dir="modules/\${module}/specs"
-  if [[ -d "$specs_dir" ]]; then
-    specs=(\${(@f)"$(command ls -1 "\${specs_dir}" 2>/dev/null | sed 's/\\.spec\\.yml$//')"})
-    compadd -a specs
-  fi
-}
-
 _ooneex_custom_commands() {
   local -a cmds
   if [[ -d modules ]]; then
@@ -15152,8 +14892,6 @@ _ooneex() {
     'make\\:resource\\:book:Generate book resource (entity, migration, repository)'
     'issue\\:create:Create a YAML skeleton file for a new issue'
     'issue\\:pull:Pull an issue from Linear and save it as a YAML file'
-    'spec\\:implement:Implement a spec using Claude'
-    'spec\\:plan:Generate a spec plan for an issue using Claude'
     'seed\\:create:Generate a new seed file'
     'seed\\:run:Run seeds for all modules'
     'make\\:service:Generate a new service class'
@@ -15260,16 +14998,6 @@ _ooneex() {
             '--id=[Linear issue ID or identifier]:id' \\
             '--module=[Module name]:module:_ooneex_modules'
           ;;
-        spec:implement)
-          _arguments -s \\
-            '--spec=[Spec identifier]:spec:_ooneex_specs' \\
-            '--module=[Module name]:module:_ooneex_modules'
-          ;;
-        spec:plan)
-          _arguments -s \\
-            '--issue=[Issue identifier]:issue:_ooneex_issues' \\
-            '--module=[Module name]:module:_ooneex_modules'
-          ;;
         migration:up|seed:run)
           _arguments -s \\
             '--drop[Drop the database before running]'
@@ -15431,168 +15159,6 @@ class IssueCreateCommand {
       showArrow: false,
       useSymbol: true
     });
-    const { improveDescription } = description ? await import_enquirer5.prompt({
-      type: "confirm",
-      name: "improveDescription",
-      message: "Improve description with Claude?",
-      initial: true
-    }) : { improveDescription: false };
-    if (improveDescription && description) {
-      const improvePrompt = [
-        "Rewrite the following issue description into a well-structured format with these sections:",
-        "- **Context**: Background information explaining why this issue exists",
-        "- **Goal**: What needs to be achieved",
-        "- **Acceptance Criteria**: A checklist of conditions that must be met (Definition of Done)",
-        "- **Technical Notes**: (optional) Any technical constraints or implementation hints",
-        "",
-        "Output ONLY the reformatted description. No preamble, no explanation.",
-        "",
-        "Original description:",
-        description
-      ].join(`
-`);
-      const improveSpinner = createSpinner("Improving description...");
-      const proc = Bun.spawn(["claude", "-p", improvePrompt], {
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      await proc.exited;
-      improveSpinner.stop();
-      description = await new Response(proc.stdout).text();
-      const labelPrompt = [
-        "Based on the following issue description, suggest relevant labels as a comma-separated list.",
-        "Labels should be short (1-3 words), lowercase, hyphenated (e.g. bug, enhancement, performance, breaking-change).",
-        "Output ONLY the comma-separated labels. No preamble, no explanation.",
-        "",
-        "Description:",
-        description
-      ].join(`
-`);
-      const labelSpinner = createSpinner("Extracting labels...");
-      const labelProc = Bun.spawn(["claude", "-p", labelPrompt], {
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      await labelProc.exited;
-      labelSpinner.stop();
-      const suggestedLabels = (await new Response(labelProc.stdout).text()).trim().split(",").map((l2) => l2.trim()).filter((l2) => l2.length > 0 && !labels.includes(l2));
-      if (suggestedLabels.length > 0) {
-        const { selectedLabels = [] } = await import_enquirer5.prompt({
-          type: "multiselect",
-          name: "selectedLabels",
-          message: "Suggested labels from description (space to toggle)",
-          choices: suggestedLabels
-        });
-        labels = [...new Set([...labels, ...selectedLabels])];
-      }
-      const updatedYaml = issueToYaml(resolvedId, title?.trim() ?? null, state?.trim() ?? null, priority?.trim() ?? null, description.trim(), labels);
-      await Bun.write(filePath, updatedYaml);
-      logger.success(`${join11(issuesLocalDir, fileName)} updated with improved description`, undefined, {
-        showTimestamp: false,
-        showArrow: false,
-        useSymbol: true
-      });
-    }
-    const currentDescription = description ?? null;
-    const { splitIssue } = currentDescription ? await import_enquirer5.prompt({
-      type: "confirm",
-      name: "splitIssue",
-      message: "Split into small executable issues with Claude?",
-      initial: false
-    }) : { splitIssue: false };
-    if (splitIssue && currentDescription) {
-      const checkPrompt = [
-        "You are a technical project manager. Evaluate whether the following issue is large or complex enough to benefit from being split into smaller issues.",
-        "",
-        'Output ONLY a JSON object: { "needed": boolean, "reason": string }',
-        '- "needed": true if the issue spans multiple concerns, steps, or implementation areas; false if it is already small and focused',
-        '- "reason": one sentence explaining your decision',
-        "No preamble, no explanation, no markdown fences \u2014 raw JSON only",
-        "",
-        `Issue title: ${title ?? ""}`,
-        "",
-        "Issue description:",
-        currentDescription
-      ].join(`
-`);
-      const checkSpinner = createSpinner("Checking if split is needed...");
-      const checkProc = Bun.spawn(["claude", "-p", checkPrompt], {
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      await checkProc.exited;
-      checkSpinner.stop();
-      const checkRaw = (await new Response(checkProc.stdout).text()).trim();
-      let splitNeeded = true;
-      try {
-        const checkResult = JSON.parse(checkRaw);
-        splitNeeded = checkResult.needed;
-        logger.info(`Claude: ${checkResult.reason}`, undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-      } catch {}
-      if (!splitNeeded) {
-        logger.info("Issue does not need splitting", undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-        return;
-      }
-    }
-    if (splitIssue && currentDescription) {
-      const splitPrompt = [
-        "You are a technical project manager. Break the following issue into small, self-contained, executable issues.",
-        "Each issue must be independently implementable by a developer in one focused session.",
-        "",
-        "Output ONLY a JSON array of objects with these fields:",
-        '  { "title": string, "description": string }',
-        "",
-        "Rules:",
-        '- title: concise action-oriented title (verb + noun, e.g. "Add user validation")',
-        "- description: 2-5 sentences covering context, goal, and acceptance criteria",
-        "- Aim for 3-7 issues; never output more than 10",
-        "- No preamble, no explanation, no markdown fences \u2014 raw JSON array only",
-        "",
-        `Issue title: ${title ?? ""}`,
-        "",
-        "Issue description:",
-        currentDescription
-      ].join(`
-`);
-      const splitSpinner = createSpinner("Splitting issue...");
-      const splitProc = Bun.spawn(["claude", "-p", splitPrompt], {
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      await splitProc.exited;
-      splitSpinner.stop();
-      const rawJson = (await new Response(splitProc.stdout).text()).trim();
-      let splitItems = [];
-      try {
-        splitItems = JSON.parse(rawJson);
-      } catch {
-        logger.error("Claude returned invalid JSON for split issues", undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-      }
-      for (const item of splitItems) {
-        const splitId = generateId();
-        const splitFileName = `${splitId}.yml`;
-        const splitFilePath = join11(issuesDir, splitFileName);
-        const splitYaml = issueToYaml(splitId, item.title, state?.trim() ?? null, priority?.trim() ?? null, item.description, labels);
-        await Bun.write(splitFilePath, splitYaml);
-        logger.success(`${join11(issuesLocalDir, splitFileName)} created`, undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-      }
-    }
   }
 }
 IssueCreateCommand = __legacyDecorateClassTS([
@@ -95552,182 +95118,6 @@ class IssuePullCommand {
       showArrow: false,
       useSymbol: true
     });
-    let description = issue.description ?? null;
-    const { improveDescription } = description ? await import_enquirer6.prompt({
-      type: "confirm",
-      name: "improveDescription",
-      message: "Improve description with Claude?",
-      initial: true
-    }) : { improveDescription: false };
-    if (improveDescription && description) {
-      const improvePrompt = [
-        "Rewrite the following issue description into a well-structured format with these sections:",
-        "- **Context**: Background information explaining why this issue exists",
-        "- **Goal**: What needs to be achieved",
-        "- **Acceptance Criteria**: A checklist of conditions that must be met (Definition of Done)",
-        "- **Technical Notes**: (optional) Any technical constraints or implementation hints",
-        "",
-        "Output ONLY the reformatted description. No preamble, no explanation.",
-        "",
-        "Original description:",
-        description
-      ].join(`
-`);
-      const improveSpinner = createSpinner("Improving description...");
-      const proc = Bun.spawn(["claude", "-p", improvePrompt], {
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      await proc.exited;
-      improveSpinner.stop();
-      description = await new Response(proc.stdout).text();
-      const labelPrompt = [
-        "Based on the following issue description, suggest relevant labels as a comma-separated list.",
-        "Labels should be short (1-3 words), lowercase, hyphenated (e.g. bug, enhancement, performance, breaking-change).",
-        "Output ONLY the comma-separated labels. No preamble, no explanation.",
-        "",
-        "Description:",
-        description
-      ].join(`
-`);
-      const labelSpinner = createSpinner("Extracting labels...");
-      const labelProc = Bun.spawn(["claude", "-p", labelPrompt], {
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      await labelProc.exited;
-      labelSpinner.stop();
-      const existingLabelNames = issue.labels?.map((l2) => l2.name).filter((n2) => n2 != null) ?? [];
-      const suggestedLabels = (await new Response(labelProc.stdout).text()).trim().split(",").map((l2) => l2.trim()).filter((l2) => l2.length > 0 && !existingLabelNames.includes(l2));
-      let extraLabels = [];
-      if (suggestedLabels.length > 0) {
-        const { selectedLabels = [] } = await import_enquirer6.prompt({
-          type: "multiselect",
-          name: "selectedLabels",
-          message: "Suggested labels from description (space to toggle)",
-          choices: suggestedLabels
-        });
-        extraLabels = selectedLabels.map((name) => ({ name }));
-      }
-      const updatedIssue = {
-        ...issue,
-        description,
-        labels: [...issue.labels ?? [], ...extraLabels]
-      };
-      await Bun.write(filePath, issueToYaml2(updatedIssue));
-      logger.success(`${join12(issuesLocalDir, fileName)} updated with improved description`, undefined, {
-        showTimestamp: false,
-        showArrow: false,
-        useSymbol: true
-      });
-    }
-    const currentDescription = description ?? issue.description;
-    const { splitIssue } = currentDescription ? await import_enquirer6.prompt({
-      type: "confirm",
-      name: "splitIssue",
-      message: "Split into small executable issues with Claude?",
-      initial: false
-    }) : { splitIssue: false };
-    if (splitIssue && currentDescription) {
-      const checkPrompt = [
-        "You are a technical project manager. Evaluate whether the following issue is large or complex enough to benefit from being split into smaller issues.",
-        "",
-        'Output ONLY a JSON object: { "needed": boolean, "reason": string }',
-        '- "needed": true if the issue spans multiple concerns, steps, or implementation areas; false if it is already small and focused',
-        '- "reason": one sentence explaining your decision',
-        "No preamble, no explanation, no markdown fences \u2014 raw JSON only",
-        "",
-        `Issue title: ${issue.title ?? ""}`,
-        "",
-        "Issue description:",
-        currentDescription
-      ].join(`
-`);
-      const checkSpinner = createSpinner("Checking if split is needed...");
-      const checkProc = Bun.spawn(["claude", "-p", checkPrompt], {
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      await checkProc.exited;
-      checkSpinner.stop();
-      const checkRaw = (await new Response(checkProc.stdout).text()).trim();
-      let splitNeeded = true;
-      try {
-        const checkResult = JSON.parse(checkRaw);
-        splitNeeded = checkResult.needed;
-        logger.info(`Claude: ${checkResult.reason}`, undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-      } catch {}
-      if (!splitNeeded) {
-        logger.info("Issue does not need splitting", undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-        return;
-      }
-    }
-    if (splitIssue && currentDescription) {
-      const splitPrompt = [
-        "You are a technical project manager. Break the following issue into small, self-contained, executable issues.",
-        "Each issue must be independently implementable by a developer in one focused session.",
-        "",
-        "Output ONLY a JSON array of objects with these fields:",
-        '  { "title": string, "description": string }',
-        "",
-        "Rules:",
-        '- title: concise action-oriented title (verb + noun, e.g. "Add user validation")',
-        "- description: 2-5 sentences covering context, goal, and acceptance criteria",
-        "- Aim for 3-7 issues; never output more than 10",
-        "- No preamble, no explanation, no markdown fences \u2014 raw JSON array only",
-        "",
-        `Issue title: ${issue.title ?? ""}`,
-        "",
-        "Issue description:",
-        currentDescription
-      ].join(`
-`);
-      const splitSpinner = createSpinner("Splitting issue...");
-      const splitProc = Bun.spawn(["claude", "-p", splitPrompt], {
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      await splitProc.exited;
-      splitSpinner.stop();
-      const rawJson = (await new Response(splitProc.stdout).text()).trim();
-      let splitItems = [];
-      try {
-        splitItems = JSON.parse(rawJson);
-      } catch {
-        logger.error("Claude returned invalid JSON for split issues", undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-      }
-      for (const item of splitItems) {
-        const splitId = generateId2();
-        const splitFileName = `${splitId}.yml`;
-        const splitFilePath = join12(issuesDir, splitFileName);
-        const splitYaml = issueToYaml2({
-          identifier: splitId,
-          title: item.title,
-          description: item.description,
-          ...issue.state !== undefined ? { state: issue.state } : {},
-          ...issue.priority !== undefined ? { priority: issue.priority } : {},
-          ...issue.labels !== undefined ? { labels: issue.labels } : {}
-        });
-        await Bun.write(splitFilePath, splitYaml);
-        logger.success(`${join12(issuesLocalDir, splitFileName)} created`, undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-      }
-    }
   }
 }
 IssuePullCommand = __legacyDecorateClassTS([
@@ -100855,224 +100245,7 @@ class SeedRunCommand {
 SeedRunCommand = __legacyDecorateClassTS([
   decorator39.command()
 ], SeedRunCommand);
-// src/commands/SpecImplementCommand.ts
-var import_enquirer12 = __toESM(require_enquirer(), 1);
-import { join as join40 } from "path";
-import { decorator as decorator40 } from "@ooneex/command";
-import { TerminalLogger as TerminalLogger38 } from "@ooneex/logger";
-class SpecImplementCommand {
-  getName() {
-    return "spec:implement";
-  }
-  getDescription() {
-    return "Implement a spec using Claude";
-  }
-  async run(options) {
-    let { spec, module = "shared" } = options;
-    await ensureModule(module);
-    const specsDir = join40(process.cwd(), "modules", module, "specs");
-    if (!spec) {
-      const files = [];
-      try {
-        for await (const file2 of new Bun.Glob("*.spec.yml").scan(specsDir)) {
-          files.push(file2.replace(/\.spec\.yml$/, ""));
-        }
-      } catch {}
-      if (files.length === 0) {
-        const logger2 = new TerminalLogger38;
-        logger2.error(`No specs found in modules/${module}/specs/`, undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-        return;
-      }
-      const response = await import_enquirer12.prompt({
-        type: "select",
-        name: "spec",
-        message: "Select spec",
-        choices: files
-      });
-      spec = response.spec;
-    }
-    const filePath = join40(specsDir, `${spec}.spec.yml`);
-    const file = Bun.file(filePath);
-    if (!await file.exists()) {
-      const logger2 = new TerminalLogger38;
-      logger2.error(`Spec file not found: modules/${module}/specs/${spec}.spec.yml`, undefined, {
-        showTimestamp: false,
-        showArrow: false,
-        useSymbol: true
-      });
-      return;
-    }
-    const content = await file.text();
-    const implementPrompt = [spec_implement_md_default, "", `**Module:** ${module}`, "", "## Spec", "", content].join(`
-`).trim();
-    const logger = new TerminalLogger38;
-    logger.info(`Running /spec:implement for ${spec}.spec.yml...`, undefined, {
-      showTimestamp: false,
-      showArrow: false,
-      useSymbol: true
-    });
-    const implProc = Bun.spawn(["claude", "-p", implementPrompt], {
-      stdout: "inherit",
-      stderr: "inherit"
-    });
-    await implProc.exited;
-  }
-}
-SpecImplementCommand = __legacyDecorateClassTS([
-  decorator40.command()
-], SpecImplementCommand);
-// src/commands/SpecPlanCommand.ts
-var import_enquirer13 = __toESM(require_enquirer(), 1);
-import { join as join41 } from "path";
-import { decorator as decorator41 } from "@ooneex/command";
-import { TerminalLogger as TerminalLogger39 } from "@ooneex/logger";
-var ALL_RESOURCES = [
-  { name: "entity", hint: "Data model class" },
-  { name: "repository", hint: "Data-access class" },
-  { name: "service", hint: "Business-logic class" },
-  { name: "controller", hint: "HTTP handler / CLI command" },
-  { name: "permission", hint: "Access-control class" },
-  { name: "middleware", hint: "Auth / rate-limit / transform" },
-  { name: "cache", hint: "Read-heavy / list endpoints" },
-  { name: "pubsub", hint: "State-mutating operations" },
-  { name: "mailer", hint: "Email / notification / invitation" },
-  { name: "logger", hint: "Audit / log / traceability" },
-  { name: "analytics", hint: "Tracking / metrics / reporting" },
-  { name: "storage", hint: "File / upload / attachment" },
-  { name: "cron", hint: "Scheduled / periodic / background" },
-  { name: "ai", hint: "AI / embedding / generation" },
-  { name: "database", hint: "New database connection" },
-  { name: "vectorDatabase", hint: "Vector search / similarity" }
-];
-var CORE_RESOURCES = new Set(["entity", "repository", "service", "controller"]);
-var VALID_RESOURCE_NAMES = new Set(ALL_RESOURCES.map((r2) => r2.name));
-async function suggestResources(issueContent) {
-  const suggestionPrompt = [
-    "You are a backend architecture assistant.",
-    "Given the following issue, reply with ONLY a JSON array of resource names that should be generated.",
-    `Choose from: ${ALL_RESOURCES.map((r2) => r2.name).join(", ")}.`,
-    "No explanation, no markdown, no code block \u2014 just a raw JSON array.",
-    "",
-    "Issue:",
-    issueContent
-  ].join(`
-`);
-  try {
-    const suggestionSpinner = createSpinner("Suggesting resources...");
-    const proc = Bun.spawn(["claude", "-p", suggestionPrompt], {
-      stdout: "pipe",
-      stderr: "pipe"
-    });
-    await proc.exited;
-    suggestionSpinner.stop();
-    const raw = await new Response(proc.stdout).text();
-    const parsed = JSON.parse(raw.trim());
-    if (Array.isArray(parsed)) {
-      const valid = parsed.filter((v2) => typeof v2 === "string" && VALID_RESOURCE_NAMES.has(v2));
-      if (valid.length > 0)
-        return new Set(valid);
-    }
-  } catch {}
-  return new Set(CORE_RESOURCES);
-}
-
-class SpecPlanCommand {
-  getName() {
-    return "spec:plan";
-  }
-  getDescription() {
-    return "Generate a spec plan for an issue using Claude";
-  }
-  async run(options) {
-    let { issue, module = "shared" } = options;
-    await ensureModule(module);
-    const issuesDir = join41(process.cwd(), "modules", module, "issues");
-    if (!issue) {
-      const files = [];
-      try {
-        for await (const file2 of new Bun.Glob("*.yml").scan(issuesDir)) {
-          files.push(file2.replace(/\.yml$/, ""));
-        }
-      } catch {}
-      if (files.length === 0) {
-        const logger2 = new TerminalLogger39;
-        logger2.error(`No issues found in modules/${module}/issues/`, undefined, {
-          showTimestamp: false,
-          showArrow: false,
-          useSymbol: true
-        });
-        return;
-      }
-      const response = await import_enquirer13.prompt({
-        type: "select",
-        name: "issue",
-        message: "Select issue",
-        choices: files
-      });
-      issue = response.issue;
-    }
-    const filePath = join41(issuesDir, `${issue}.yml`);
-    const file = Bun.file(filePath);
-    if (!await file.exists()) {
-      const logger2 = new TerminalLogger39;
-      logger2.error(`Issue file not found: modules/${module}/issues/${issue}.yml`, undefined, {
-        showTimestamp: false,
-        showArrow: false,
-        useSymbol: true
-      });
-      return;
-    }
-    const content = await file.text();
-    const suggestedResources = await suggestResources(content);
-    const { resources } = await import_enquirer13.prompt({
-      type: "multiselect",
-      name: "resources",
-      message: "Select resources to generate",
-      choices: ALL_RESOURCES.map((r2) => ({
-        name: r2.name,
-        hint: r2.hint,
-        enabled: suggestedResources.has(r2.name)
-      }))
-    });
-    const specsDir = join41(process.cwd(), "modules", module, "specs");
-    const planPrompt = [
-      spec_plan_md_default,
-      "",
-      `**Module:** ${module}`,
-      `**Spec output directory:** ${specsDir}`,
-      "",
-      "## Resources to generate",
-      "",
-      resources.map((r2) => `- ${r2}`).join(`
-`),
-      "",
-      "## Issue",
-      "",
-      content
-    ].join(`
-`).trim();
-    const logger = new TerminalLogger39;
-    logger.info("Running /spec:plan...", undefined, {
-      showTimestamp: false,
-      showArrow: false,
-      useSymbol: true
-    });
-    const planProc = Bun.spawn(["claude", "-p"], {
-      stdin: Buffer.from(planPrompt),
-      stdout: "inherit",
-      stderr: "inherit"
-    });
-    await planProc.exited;
-  }
-}
-SpecPlanCommand = __legacyDecorateClassTS([
-  decorator41.command()
-], SpecPlanCommand);
 // src/index.ts
 await run();
 
-//# debugId=4D85614A43F301F864756E2164756E21
+//# debugId=C0A94E3D0B33D65A64756E2164756E21