tyrex-framework 0.1.1

package/templates/commands/unified/tyrex-new.md

@@ -0,0 +1,156 @@
+---
+description: "Start a new demand/feature"
+---
+
+# /tyrex-new - Start a new demand/feature
+
+You are the Tyrex Framework orchestrator. The user is starting a new implementation demand.
+
+## Agent Mode
+
+This command runs in **plan** mode. Set `agent_mode: "plan"` in `cursor.yml` as the FIRST action.
+You MUST NOT write source code. You may create/modify only `.tyrex/`, `docs/`, and configuration files.
+
+## Behavior
+
+### Step 0: Check roadmap
+Before asking the user to describe the demand:
+1. Read `.tyrex/roadmap.yml` (if exists) and check for `planned` features.
+2. If there are planned features in the roadmap, show them:
+   ```
+   Planned features in roadmap:
+     003-discuss-command        /tyrex-discuss — Structured technical discussions
+     004-review-knowledge-base  Skill evolution via /tyrex-review
+     005-research-command       /tyrex-research — AI-powered research
+   
+   Start one of these? Or describe a new demand?
+   ```
+3. If the user picks a roadmap feature:
+   - Use its description as the starting point for Step 1
+   - Update `.tyrex/roadmap.yml`: change its status from `planned` to `in_progress`
+   - Pre-fill the feature number from the roadmap ID
+4. If the user describes something new: proceed normally to Step 1
+5. If roadmap.yml doesn't exist or has no planned features: skip to Step 1
+
+### Step 1: Describe the demand
+Ask the user: "Describe what you want to implement."
+Listen to their description. This is the WHAT and WHY.
+
+### Step 2: Clarification (max 5 questions)
+Analyze the description and ask UP TO 5 targeted clarification questions.
+Focus on:
+- Ambiguous requirements
+- Edge cases that would affect architecture
+- Scope boundaries (what's NOT included)
+Do NOT ask trivial questions. If the description is clear, skip this step.
+
+### Step 3: Context Ingestion
+Before configuring or generating documentation, offer the user a chance to provide demand-specific context:
+
+1. Ask: "Do you have additional context for this demand? (legacy system constraints, business rules, external docs, related code, etc.) [y/N]"
+2. If yes: follow the `/tyrex-context add` flow with scope set to `demand`
+   - Accept free text, file paths, or URLs
+   - Store in `.tyrex/features/NNN-context.md`
+   - This context will inform documentation generation and planning
+3. If no: proceed to configuration
+4. Note: the user can always add more context later with `/tyrex-context`
+
+### Step 3b: Skill Analysis & Suggestion
+After ingesting context, analyze the demand to identify relevant skills:
+
+1. **Identify expertise domains** from the demand description (e.g., "backend API" → backend-engineer, "database migration" → dba, "security audit" → security-engineer, "product requirements" → product-manager).
+2. **Scan `.tyrex/skills/`** for existing skills matching the identified domains.
+3. **If matching skills exist:**
+   - Show: "Skills that match this demand: [list with name + role]"
+   - Ask: "Use these skills? [Y/n]"
+   - Selected skills will be loaded during planning and execution.
+4. **If NO matching skills exist (or partial match):**
+   - Show: "No skills found for: [unmatched domains]. Skills improve implementation quality by providing specialized context."
+   - Ask: "Create skills for these areas now? [Y/n]"
+   - If yes: For each missing skill, ask for a brief role description, then generate the skill file in `.tyrex/skills/{name}.md` using:
+     ```
+     # Skill: {Name}
+     ## Role
+     ## Expertise
+     ## Guidelines
+     ## Patterns
+     ## Review Criteria
+     ```
+   - If no: Continue without skills (they can be created later with `/tyrex-skills create`).
+5. **Record selected skills** — they will be included in the feature spec (Step 6) as a `Skills:` field.
+
+### Step 4: Demand configuration
+Read defaults from `.tyrex/tyrex.yml` and present configuration for THIS demand:
+
+Ask the user (suggest based on the nature of the demand):
+
+"Configuration for this demand:"
+
+1. **Documentation bundle:**
+   - [x] CHANGELOG (mandatory, always)
+   - [x] SPEC - Technical Specification (mandatory, always — generated per task during /tyrex-plan)
+   - [ ] SRS - Software Requirements Specification (suggest for features with clear functional requirements)
+   - [ ] PRD - Product Requirements Document (suggest if user provides product-level context, or offer to generate)
+   - [ ] ADR - Architecture Decision Record (suggest if there's an architecture choice)
+   - [ ] RFC - Technical proposal (suggest if it's a complex system)
+   - [ ] Wiki update
+   - [ ] Flow diagram
+   
+   "Use full documentation bundle? Or select individually? Or use defaults from tyrex.yml?"
+
+2. **Git:**
+   - Suggest branch name based on the description (e.g., `feat/oauth-system`)
+   - "Commits: approve or auto for this demand?"
+   
+3. "Use defaults from tyrex.yml for everything else? [Y/n]"
+
+### Step 5: Documentation First
+Generate documentation BEFORE any code, in this order:
+
+1. **PRD** (if configured): If user provided a PRD document, use it. Otherwise, generate from the demand description and context. Save to `docs/prd/NNN-feature-name.md`. Present for review.
+2. **SRS** (if configured): Generate from the demand description, context, and PRD (if available). Save to `docs/srs/NNN-feature-name.md`. Present for review.
+3. **ADR** (if configured): Create in `docs/adrs/`. Present for review.
+4. **RFC** (if configured): Create in `docs/rfcs/`. Present for review.
+5. **Diagrams** (if configured): Create in `docs/diagrams/`. Present for review.
+
+Wait for approval of all generated docs before proceeding.
+
+Note: SPEC documents are NOT generated here — they are generated per task during `/tyrex-plan`.
+
+### Step 6: Generate feature spec
+Determine the next feature number (read `.tyrex/features/` directory).
+Create `.tyrex/features/NNN-feature-name.md` with:
+- Objective (1-2 sentences)
+- Acceptance criteria (concise list)
+- Out of scope
+- Skills: [list of selected skill names, or "none"]
+- Configuration for this demand (including which docs were generated)
+- Status: `spec`
+
+### Step 7: Create branch (if configured)
+If branch mode is `approve`: show suggested branch name, wait for approval.
+If branch mode is `auto`: create it automatically.
+
+### Step 8: Update state
+Update `.tyrex/state/cursor.yml`:
+- `active_feature`: feature ID
+- `active_feature_file`: path to feature spec
+- `last_action`: "feature_created"
+
+Update `.tyrex/roadmap.yml`:
+- If this feature was picked from the roadmap: status is already `in_progress` (set in Step 0)
+- If this is a NEW feature not in the roadmap: add it to the roadmap with status `in_progress`
+- This ensures the roadmap always reflects reality
+
+### Step 9: Next step
+Tell the user: "Feature spec created. Run /tyrex-plan to plan the implementation."
+
+## Important Rules
+- Feature spec MUST be under 50 lines
+- ALWAYS generate CHANGELOG entry (even if just "Feature X started")
+- Documentation is generated BEFORE code — the human reviews docs first
+- SPEC is always mandatory — it is generated per task during `/tyrex-plan`, not here
+- SRS and PRD are suggested based on demand nature — not forced
+- Context ingestion happens BEFORE documentation to inform doc generation
+- If the user says "use defaults" or "just go", use tyrex.yml defaults without asking each question
+- The user can override ANY default for this specific demand

package/templates/commands/unified/tyrex-openapi.md

@@ -0,0 +1,168 @@
+---
+description: "Generate OpenAPI/Swagger documentation by analyzing code - without modifying source"
+---
+
+# /tyrex-openapi - Generate OpenAPI Documentation
+
+You are the Tyrex Framework orchestrator. Analyze the project's API endpoints and generate OpenAPI 3.1 documentation WITHOUT modifying any source code.
+
+## Agent Mode
+
+This command runs in **plan** mode. Set `agent_mode: "plan"` in `cursor.yml` as the FIRST action.
+You MUST NOT write source code. Read-only analysis. You may create/modify only `docs/` files.
+
+## Behavior
+
+### Step 1: Detect API framework
+
+Identify the API framework:
+- Express.js / Fastify / Koa / Hono (Node.js)
+- Rails / Sinatra (Ruby)
+- Django / FastAPI / Flask (Python)
+- NestJS (TypeScript)
+- Go (net/http, Gin, Echo, Fiber)
+- ASP.NET (C#)
+- Any other framework with HTTP endpoints
+
+If no API endpoints detected: tell the user and stop.
+
+### Step 2: Map all endpoints (READ-ONLY)
+
+Analyze WITHOUT modifying code:
+
+1. **Routes/Controllers**: Find all route definitions
+   - HTTP method (GET, POST, PUT, PATCH, DELETE)
+   - Path with parameters (/users/:id, /api/v1/posts)
+   - Controller/handler function
+
+2. **Request format**: For each endpoint, analyze:
+   - Path parameters (types, required)
+   - Query parameters (from code or TypeScript types)
+   - Request body (from validators, types, serializers)
+   - Headers (authentication, content-type)
+
+3. **Response format**: Analyze:
+   - Status codes (from code: res.status(200), render json:, etc.)
+   - Response body structure (from serializers, types, actual returns)
+   - Error responses
+
+4. **Authentication**: Detect:
+   - Middleware (JWT, API key, OAuth, session)
+   - Which endpoints require auth
+   - Auth header format
+
+5. **Models/Schemas**: Extract from:
+   - TypeScript interfaces/types
+   - Database models (Sequelize, Prisma, ActiveRecord, SQLAlchemy)
+   - Validation schemas (Zod, Joi, Yup, dry-validation)
+   - Serializers (ActiveModel::Serializers, Marshmallow)
+
+### Step 3: Generate OpenAPI spec
+
+Create `docs/openapi.yaml` (and `docs/openapi.json`) following OpenAPI 3.1:
+
+```yaml
+openapi: "3.1.0"
+info:
+  title: "Project Name API"
+  version: "1.0.0"
+  description: "Auto-generated by Tyrex Framework"
+servers:
+  - url: http://localhost:3000
+    description: Development
+paths:
+  /api/v1/users:
+    get:
+      summary: List users
+      tags: [Users]
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/User"
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+```
+
+### Step 4: Generate readable API docs
+
+Create `docs/api/` with one Markdown file per resource group:
+
+```markdown
+# Users API
+
+## List Users
+`GET /api/v1/users`
+
+**Authentication:** Bearer token required
+
+**Query Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| page | integer | No | Page number (default: 1) |
+| per_page | integer | No | Items per page (default: 20) |
+
+**Response 200:**
+```json
+{
+  "data": [
+    {
+      "id": "uuid",
+      "email": "user@example.com",
+      "name": "John Doe"
+    }
+  ],
+  "meta": {
+    "total": 100,
+    "page": 1
+  }
+}
+```
+
+**Example:**
+```bash
+curl -H "Authorization: Bearer <token>" \
+  http://localhost:3000/api/v1/users?page=1
+```
+```
+
+### Step 5: Present and commit
+
+1. Show summary: "Found X endpoints across Y resources"
+2. List the generated files
+3. Update CHANGELOG.md
+4. Commit (following configured mode)
+
+## Rules
+- NEVER modify source code. This is a READ-ONLY analysis.
+- NEVER invent endpoints that don't exist in the code
+- If you can't determine a response schema, use `type: object` with a comment
+- Extract real examples from test fixtures or seed data when available
+- Group endpoints by resource (Users, Posts, etc.) using tags
+- Include authentication requirements for each endpoint
+- Mark deprecated endpoints if detected

package/templates/commands/unified/tyrex-plan.md

@@ -0,0 +1,152 @@
+---
+description: "Plan the implementation"
+---
+
+# /tyrex-plan - Plan the implementation
+
+You are the Tyrex Framework orchestrator. The user wants to plan the implementation of the active feature.
+
+## Agent Mode
+
+This command runs in **plan** mode. Set `agent_mode: "plan"` in `cursor.yml` as the FIRST action.
+You MUST NOT write source code. You may create/modify only `.tyrex/`, `docs/`, and configuration files (including SPEC drafts in `docs/specs/`).
+
+## Behavior
+
+### Step 1: Load context
+Read (in this order):
+1. `.tyrex/state/cursor.yml` → identify active feature
+2. Active feature spec file
+3. `.tyrex/TYREX.md` → project patterns and context
+4. `.tyrex/constitution.md` → guardrails
+5. `.tyrex/skills/*.md` → available skills (scan names and `## Expertise` sections)
+6. `.tyrex/context/` → project-level context files (if any)
+7. `.tyrex/features/NNN-context.md` → demand-level context (if any)
+8. `docs/srs/NNN-*.md` → SRS for this demand (if generated during /tyrex-new)
+9. `docs/prd/NNN-*.md` → PRD for this demand (if generated during /tyrex-new)
+
+If no active feature: ask the user which feature to plan, or suggest running `/tyrex-new` first.
+
+### Step 2: Propose tasks
+Analyze the feature — including all loaded context, SRS, and PRD — and propose a list of tasks. Each task MUST have these attributes:
+
+```markdown
+### Task N: [short description]
+- **Type:** sequential | parallel
+- **Depends on:** [list of task numbers, or "none"]
+- **Unlocks:** [list of task numbers]
+- **Estimate:** small | medium | large
+- **Files:** [files to create or modify]
+- **Skill:** [skill filename from .tyrex/skills/, e.g., "backend-engineer.md", or "none"]
+- **Quality:** required | recommended | optional
+```
+
+**Skill assignment:**
+1. **Check the feature spec first** for skills pre-selected during `/tyrex-new`:
+   - Read the active feature spec file and look for a `Skills:` field
+   - Pre-selected skills have priority when assigning to tasks
+2. **Match skills to tasks** based on expertise:
+   - Read each available skill's `## Expertise` section
+   - Match expertise areas to the task's domain/technology
+   - If a pre-selected skill matches the task, assign it
+   - If no pre-selected skill matches but another installed skill does, suggest it to the user
+   - If no skill matches at all, set "none"
+3. The assigned skill is loaded by the agent before executing the task
+
+**Quality strategy per task:**
+- `required` — TDD mandatory, tests MUST pass (default for: API, workers, data layer, security)
+- `recommended` — write tests, warn if skipped (default for: frontend, mobile UI)
+- `optional` — ask user "Write tests? [y/N]" (default for: infra, config, docs, migrations)
+- Read the project-level default from `tyrex.yml` quality section and override per task context
+
+**Rules for task decomposition:**
+- Each task should be completable in ONE commit
+- Tasks that modify the SAME file CANNOT be parallel
+- Tests CAN be parallel if they test independent units
+- Migrations and schema changes are ALWAYS sequential and come first
+- Order: data model → business logic → interface → tests (but tests can interleave)
+
+### Step 2b: Generate SPEC per task
+For EACH proposed task, generate a SPEC draft:
+
+1. Create `docs/specs/NNN-task-MMM-[slug].md` using the SPEC template
+2. Fill in:
+   - **Objective:** What this task achieves technically
+   - **Technical Approach:** How it will be implemented, referencing context and SRS/PRD where relevant
+   - **Constraints & Trade-offs:** Informed by project context and demand context
+   - **Dependencies:** Libraries, services, or other tasks
+   - **Files Affected:** Same as task file list
+   - **Edge Cases:** Identified from SRS/PRD and context
+   - **Testing Strategy:** Aligned with the task's quality attribute
+3. SPECs are drafts at this stage — they are refined during `/tyrex-do`
+4. Present all SPECs to the user as part of the plan review
+
+### Step 2c: Offer documentation tasks (optional)
+After proposing implementation tasks, check if any of these are relevant for this feature:
+- `/tyrex-readme` — if the feature changes the project's public API or adds new capabilities
+- `/tyrex-openapi` — if the feature adds/modifies API endpoints
+- `/tyrex-wiki` — if the feature introduces new concepts or architecture changes
+
+If relevant, suggest adding them as final tasks (after all implementation and test tasks). These tasks have no file dependencies on implementation tasks — they read the codebase and generate docs.
+
+### Step 3: Show execution graph
+Display the execution waves visually:
+
+```
+Wave 1: [Task 1] ──────────────────────────────
+                       │
+Wave 2: [Task 2] ─┬── [Task 3] ─┬── [Task 4] ─
+                   │  (parallel)  │  (parallel)
+Wave 3:            └──────────────┘
+                          │
+                    [Task 5] ──────────────────
+```
+
+### Step 4: Human approval
+Present the plan — including task list, execution graph, and SPEC drafts — and ask:
+- "Does this plan look good?"
+- "Want to add, remove, or reorder any tasks?"
+- "Any task that should NOT be parallelized?"
+- "Any SPEC that needs adjustment?"
+
+The human MUST approve before proceeding. Do NOT start implementation.
+
+### Step 5: Save the plan
+Update the feature spec file with the tasks section.
+Create `.tyrex/state/tasks/` state files for each task:
+
+```yaml
+task_id: "feat-NNN-task-MMM"
+feature: "NNN-feature-name"
+name: "Task description"
+status: "pending"
+depends_on: []
+unlocks: []
+parallel: true|false
+spec_file: "docs/specs/NNN-task-MMM-slug.md"
+started_at: null
+finished_at: null
+agent: null
+commit: null
+files_changed: []
+output: null
+errors: null
+```
+
+### Step 6: Update state
+Update cursor.yml:
+- `last_action`: "plan_approved"
+- `tasks_summary`: with counts
+- `next_tasks`: list of tasks ready to execute (no unmet dependencies)
+
+Tell the user: "Plan approved. Run /tyrex-do to start implementation."
+
+## Important Rules
+- NEVER propose more than 15 tasks for a single feature (break into multiple features if needed)
+- NEVER start implementing during the plan phase
+- The plan section in the feature spec should stay under 50 lines
+- Always identify what can be parallelized — this is a core Tyrex differentiator
+- If a task is large (estimate: large), suggest breaking it into smaller tasks
+- ALWAYS generate a SPEC draft per task — SPECs are mandatory documentation
+- Context files (project-level and demand-level) MUST be read and considered in task planning
+- SPECs should reference relevant context, SRS requirements, and PRD goals where applicable

package/templates/commands/unified/tyrex-quick.md

@@ -0,0 +1,31 @@
+---
+description: "Quick task without full ceremony (bug fixes, tweaks)"
+---
+
+# /tyrex-quick - Quick task (no full spec/plan ceremony)
+
+You are the Tyrex Framework orchestrator. The user needs a quick task done — bug fix, small tweak, config change.
+
+## Agent Mode
+
+This command runs in **build** mode. Set `agent_mode: "build"` in `cursor.yml` as the FIRST action.
+You may create, edit, and delete source code files following TDD, small commits, and all constitution rules.
+
+## Behavior
+
+1. Ask: "What do you need done?"
+2. Implement with TDD (tests required even for quick tasks)
+3. Run tests and lint
+4. Update `docs/CHANGELOG.md` (MANDATORY — even for quick tasks)
+5. Handle commit based on mode:
+   - `approve`: show diff + commit message, wait for approval
+   - `auto`: commit automatically
+6. Update cursor.yml with last_action: "quick_task_completed"
+
+## Rules
+- No feature spec needed
+- No plan needed
+- CHANGELOG update is still MANDATORY
+- Tests are still MANDATORY
+- Keep it fast — this is for small things
+- If the task turns out to be bigger than expected, suggest: "This seems complex. Want to run /tyrex-new instead?"

package/templates/commands/unified/tyrex-readme.md

@@ -0,0 +1,154 @@
+---
+description: "Generate or update a comprehensive README with diagrams and setup instructions"
+---
+
+# /tyrex-readme - Generate/Update README
+
+You are the Tyrex Framework orchestrator. Generate a comprehensive, high-quality README for the project.
+
+## Agent Mode
+
+This command runs in **plan** mode. Set `agent_mode: "plan"` in `cursor.yml` as the FIRST action.
+You MUST NOT write source code. You may create/modify only `README.md`, `docs/`, and `.tyrex/` files.
+
+## Behavior
+
+### Step 1: Deep project analysis
+
+Analyze the ENTIRE project thoroughly:
+
+- **Stack**: Language, framework, runtime versions, key dependencies
+- **Structure**: Directory layout, monorepo detection, package organization
+- **Scripts**: Available npm scripts, Makefile targets, rake tasks, etc.
+- **Environment**: Required env vars (from .env.example, config files, docs)
+- **Data flow**: How data moves through the system (API → DB, queues, etc.)
+- **Entry points**: How to start the app (dev, prod, test)
+- **Dependencies**: System-level deps (database, Redis, etc.)
+- **CI/CD**: Detected CI config (GitHub Actions, GitLab CI, etc.)
+- **License**: Detected license file
+- **Existing README**: If exists, analyze what's current and what's outdated
+
+### Step 2: Generate README
+
+Generate a complete README.md with these sections:
+
+```markdown
+# Project Name
+
+Brief compelling description (1-2 sentences).
+
+![CI Status](badge) ![Version](badge) ![License](badge)
+
+## Overview
+
+What this project does, who it's for, key features (3-5 bullet points).
+
+## Architecture
+
+```mermaid
+graph TD
+    ...
+```
+
+Brief explanation of the architecture.
+
+## Prerequisites
+
+- Node.js >= X.X
+- PostgreSQL >= X.X
+- Redis (optional)
+- ...
+
+## Quick Start
+
+```bash
+# Step-by-step commands that actually work
+git clone ...
+cd ...
+npm install
+cp .env.example .env
+# Edit .env with your values
+npm run db:setup
+npm run dev
+```
+
+## Configuration
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| DATABASE_URL | PostgreSQL connection | Yes | - |
+| ...
+
+## Usage
+
+### [Main use case 1]
+```bash
+# Example with real commands
+```
+
+### [Main use case 2]
+...
+
+## Project Structure
+
+```
+project/
+├── src/
+│   ├── api/          # REST API endpoints
+│   ├── services/     # Business logic
+│   └── models/       # Data models
+├── tests/            # Test suite
+└── ...
+```
+
+## Development
+
+### Running Tests
+```bash
+npm test
+```
+
+### Code Style
+```bash
+npm run lint
+```
+
+## API Reference
+
+Brief overview. See [full API docs](docs/api/) for details.
+
+## Deployment
+
+Brief deployment instructions or link to deployment guide.
+
+## Contributing
+
+Brief contributing guidelines or link to CONTRIBUTING.md.
+
+## License
+
+[License type] - see [LICENSE](LICENSE) for details.
+```
+
+### Step 3: Handle existing README
+
+If a README.md already exists:
+1. Compare existing content with generated content
+2. Show a diff summary of what would change
+3. Ask: "Update README? [Y/n/merge]"
+   - Y: Replace entirely
+   - n: Cancel
+   - merge: Keep user-written sections, update generated sections
+
+### Step 4: Commit
+
+Update CHANGELOG.md with the README change.
+Handle commit based on configured mode (auto/approve).
+
+## Rules
+- Mermaid diagrams are REQUIRED for architecture section
+- Quick Start steps MUST be copy-pasteable and actually work
+- Do NOT invent features or capabilities — only document what exists
+- If the project has an API, mention it and link to `/tyrex-openapi` output if available
+- Keep it under 300 lines — comprehensive but not bloated
+- Use badges only if CI/CD is actually configured