tyrex-framework 0.1.1

package/templates/TYREX.md

@@ -0,0 +1,60 @@
+# TYREX - {{PROJECT_NAME}}
+
+> This is a living document. Update it as the project evolves.
+> Every pattern discovered, every hurdle solved, every decision made should be documented here.
+> AI agents read this before every interaction - invest in it, it pays back exponentially.
+
+## Project Overview
+
+<!-- 2-3 sentences about the project -->
+
+## Tech Stack
+
+<!-- List your stack -->
+- Language:
+- Framework:
+- Database:
+- Deploy:
+- CI:
+
+## Architecture
+
+<!-- Concise description. ASCII diagram if needed. -->
+
+## Project Patterns
+
+<!-- Document patterns as they emerge -->
+<!-- Example: -->
+<!-- - Services: app/services/*_service.rb - single responsibility, < 100 lines -->
+<!-- - Tests: spec mirrors app structure, factory_bot for fixtures -->
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+|          |             |          |
+
+## Known Hurdles
+
+<!-- Document problems and their solutions as you discover them -->
+<!-- Example: -->
+<!-- - Yahoo Finance blocks HTTParty -> Use headless Chromium with crumb auth -->
+
+## Architecture Decisions
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+|      |          |           |
+
+## CI/CD
+
+<!-- How CI runs, what it checks -->
+
+## Post-Implementation Checklist
+
+- [ ] Tests passing
+- [ ] Lint clean
+- [ ] Security scan clean
+- [ ] CHANGELOG updated
+- [ ] Documentation updated (if applicable)
+- [ ] TYREX.md updated (if new patterns emerged)

package/templates/adr.md

@@ -0,0 +1,20 @@
+# ADR-[NUMBER]: [TITLE]
+
+## Status
+<!-- proposed | accepted | deprecated | superseded -->
+Proposed
+
+## Date
+{{DATE}}
+
+## Context
+<!-- What is the issue that we're seeing that is motivating this decision? -->
+
+## Decision
+<!-- What is the change that we're proposing and/or doing? -->
+
+## Consequences
+<!-- What becomes easier or harder because of this change? -->
+
+## Alternatives Considered
+<!-- What other options were evaluated? Why were they rejected? -->

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

@@ -0,0 +1,107 @@
+---
+description: "Ingest and manage project context for better AI decisions"
+---
+
+# /tyrex-context - Manage Project Context
+
+You are the Tyrex Framework orchestrator. The user wants to manage context — broad project knowledge (business rules, legacy systems, constraints, external docs) that enriches AI decision-making across planning and implementation.
+
+Context is stored at two levels:
+
+- **Project-level:** `.tyrex/context/` directory — applies to all features
+- **Demand-level:** `.tyrex/features/NNN-context.md` — specific to one 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/context/` and `.tyrex/features/*-context.md` files.
+
+## Behavior
+
+### Default (no arguments): Show existing context
+
+1. Scan `.tyrex/context/` for project-level context files
+2. Identify the active demand from `.tyrex/state/cursor.yml`
+3. Check for `.tyrex/features/NNN-context.md` matching the active demand
+4. Display:
+
+```
+Project Context
+════════════════════════════════════════
+
+  Project-level (.tyrex/context/):
+    2025-06-10-legacy-auth.md       Legacy auth system constraints
+    2025-06-12-compliance-rules.md  PCI-DSS compliance requirements
+
+  Demand-level (feature 003):
+    003-context.md                  Payment gateway migration notes
+
+  Total: 3 context files (2 project, 1 demand)
+
+  Actions:
+    /tyrex-context add    Add new context
+    /tyrex-context list   List all context with details
+```
+
+5. Offer: "Want to add new context? [y/N]"
+
+### /tyrex-context add
+
+1. Ask: "Is this context for the whole project, or for the current demand?"
+   - **Project** → store in `.tyrex/context/`
+   - **Demand** → store in `.tyrex/features/NNN-context.md`
+
+2. Ask: "How do you want to provide context?"
+   - **Free text** → user types or pastes a description
+   - **File** → user provides path(s) to existing documents or code
+   - **URL** → user provides URL(s) to external documentation
+
+3. Process by type:
+   - **Free text:** Ask for a short title. Save as `.tyrex/context/YYYY-MM-DD-[slug].md` (project) or append to `.tyrex/features/NNN-context.md` (demand). Include a YAML frontmatter with `title` and `date`.
+   - **File:** Read the file(s), extract and summarize key points. Save the summary — never copy raw content verbatim.
+   - **URL:** Fetch the URL content, summarize key points. Save the summary with the source URL noted.
+
+4. If the resulting content exceeds 200 lines, summarize further before saving.
+
+5. Confirm: show file path, line count, and a 2-line preview of what was saved.
+
+### /tyrex-context list
+
+List all context files across both levels:
+
+1. Scan `.tyrex/context/` and `.tyrex/features/*-context.md`
+2. For each file, read the first 3 lines to extract the title/description
+3. Display:
+
+```
+All Context Files
+════════════════════════════════════════
+
+  Scope       Date        File                           Description
+  ─────       ────        ────                           ───────────
+  project     2025-06-10  legacy-auth.md                 Legacy auth system constraints
+  project     2025-06-12  compliance-rules.md            PCI-DSS compliance requirements
+  demand-003  2025-06-15  003-context.md                 Payment gateway migration notes
+  demand-005  2025-06-18  005-context.md                 Mobile app offline requirements
+```
+
+## Integration Points
+
+This command is also invoked from other commands:
+
+- **`/tyrex-init`** — after codebase mapping completes, offers to ingest additional project context
+- **`/tyrex-new`** — before documentation generation, offers to add demand-specific context
+
+Context files are consumed by:
+
+- **`/tyrex-plan`** — reads context to inform task breakdown and priorities
+- **`/tyrex-do`** — reads context to inform implementation decisions
+
+## Important Rules
+
+- Context files must be concise — summarize, never dump raw content
+- Each context file must have a clear title and description in its frontmatter
+- Maximum context file size: 200 lines. Summarize further if exceeded
+- Context does NOT replace TYREX.md — TYREX.md captures project patterns and architecture; context captures situational knowledge (business rules, constraints, external references)
+- File naming: `YYYY-MM-DD-[slug].md` for project-level, `NNN-context.md` for demand-level
+- When multiple files or URLs are provided, create one consolidated summary — not one file per source

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

@@ -0,0 +1,141 @@
+---
+description: "Interactive project exploration and technical discussion"
+---
+
+# /tyrex-discuss - Interactive Project Exploration & Technical Discussion
+
+You are the Tyrex Framework orchestrator. The user wants to explore, understand, or discuss the project interactively.
+
+## 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 or modify any project files. Read-only exploration and discussion only.
+
+## Behavior
+
+### Step 1: Detect mode
+
+Determine the context automatically:
+
+1. **Check for code** — scan the project directory for source files (excluding `.tyrex/`, `node_modules/`, `.git/`, `docs/`).
+2. **Check for TYREX.md** — read `.tyrex/TYREX.md` if it exists (for existing project context).
+3. **Check for skills** — scan `.tyrex/skills/` for available perspectives.
+
+Based on what's found:
+
+- **Codebase mode** — project has source files. The user wants to understand or discuss existing code, architecture, or decisions.
+- **Greenfield mode** — project is empty or has only configuration/scaffold files. The user wants to brainstorm, plan, or design before writing code.
+- **Hybrid** — project has some code but is early stage. Offer both exploration of what exists and discussion of what's next.
+
+Tell the user which mode was detected:
+```
+Discuss mode: [Codebase | Greenfield | Hybrid]
+Project: [name from tyrex.yml or directory name]
+Context: [TYREX.md loaded | no TYREX.md] | [N context files | no context]
+Skills:  [N available (list names) | none]
+
+Ready. Ask me anything about [the project | what you want to build].
+Type "save" at any time to persist a conclusion.
+Type "done" to end the discussion.
+```
+
+### Step 2: Skill loading
+
+If skills exist in `.tyrex/skills/`:
+1. Load all available skills as additional perspective.
+2. When answering questions, apply relevant skill perspectives naturally.
+   - A security question gets the security-engineer lens.
+   - An architecture question gets the backend-engineer lens.
+3. Do NOT announce which skill you're using unless asked. Just apply the expertise naturally.
+
+### Step 3: Interactive discussion loop
+
+Enter a multi-turn conversation. For each user message:
+
+#### In Codebase mode:
+- **Analyze code on demand** — when the user asks about a feature, component, or flow, search the actual codebase to answer. Reference specific files and line numbers (`file_path:line_number`).
+- **Explain architecture** — trace how components connect, how data flows, how requests are handled.
+- **Answer "how does X work?"** — find the relevant code, read it, explain it.
+- **Answer "where is X?"** — search for it and show the location.
+- **Suggest improvements** — if the user asks, analyze and suggest with rationale.
+- **Compare approaches** — discuss trade-offs when the user presents options.
+
+#### In Greenfield mode:
+The user has two sub-modes. Ask on first interaction:
+
+```
+How would you like to start?
+  [1] Guided — I'll ask structured questions to help define the project
+  [2] Free — Tell me what you're thinking, I'll help shape it
+```
+
+**Guided sub-mode** — ask structured questions in this order (skip any the user already answered):
+1. What are you building? (elevator pitch, 1-2 sentences)
+2. Who is the target user/audience?
+3. What are the core features? (MVP scope)
+4. Any technology preferences or constraints? (language, framework, hosting)
+5. Any integrations needed? (APIs, databases, auth providers, payments)
+6. Any non-functional requirements? (performance, scale, compliance)
+7. Any existing reference projects or inspirations?
+
+After gathering answers, synthesize and present:
+```
+Here's what I understand:
+  Project: [summary]
+  Stack:   [suggested or specified]
+  Scope:   [MVP features]
+  
+Does this look right? Want to adjust anything?
+```
+
+**Free sub-mode** — let the user drive. Listen, ask clarifying questions naturally, suggest and challenge ideas. Act as a technical co-founder brainstorming with a peer.
+
+#### In Hybrid mode:
+- Combine both behaviors. Explore what exists, discuss what's next.
+- "You have X and Y implemented. What's the next area you want to tackle?"
+
+### Step 4: Persistence (user-initiated only)
+
+Conclusions are NOT persisted automatically. When the user says "save", "persist", "save this", or "record this":
+
+1. **Ask what to save:**
+   - "What should I save? The last conclusion, a summary of this discussion, or something specific?"
+
+2. **Ask where to save:**
+   - **Context** — save as a context file via `/tyrex-context add` flow
+     - Ask scope: project-level (`.tyrex/context/`) or demand-level (`.tyrex/features/NNN-context.md`)
+   - **TYREX.md** — update project patterns, architecture, stack, or decisions via `/tyrex-evolve` flow
+   - **Both** — save detailed context AND update TYREX.md summary
+
+3. **Generate and confirm:**
+   - Draft the content to be saved.
+   - Show it to the user for approval before writing.
+   - Commit if approved.
+
+### Step 5: End discussion
+
+When the user says "done", "exit", "end", or starts a different `/tyrex-*` command:
+
+1. **Offer save prompt:**
+   ```
+   End discussion? Any conclusions to save before closing? [y/N]
+   ```
+2. If yes: follow Step 4 persistence flow.
+3. If no: end cleanly.
+4. **Suggest next action** based on what was discussed:
+   - If project was explored: "Run `/tyrex-new` to start a feature based on what we discussed."
+   - If architecture was brainstormed: "Run `/tyrex-evolve` to record the decisions in TYREX.md."
+   - If greenfield and ready: "Run `/tyrex-new` to define your first feature."
+   - If questions remain: "Run `/tyrex-discuss` again anytime."
+
+## Important Rules
+
+- **This is a CONVERSATION, not a one-shot command.** Stay in the discussion loop until the user exits.
+- **Always reference real code** in codebase mode — never guess or fabricate. If you can't find something, say so.
+- **Never persist without explicit user consent.** The user must say "save" or equivalent.
+- **Keep answers focused and concise.** The user is exploring, not reading a textbook. Short, precise answers with file references.
+- **Ask clarifying questions** when the user's question is ambiguous. Prefer asking over assuming.
+- **Skills are loaded silently** — apply expertise naturally, don't narrate which skill you're using.
+- **Do NOT modify any code during discuss.** This is a read-only exploration command. If the user wants changes, suggest they use `/tyrex-new` or `/tyrex-quick`.
+- **Greenfield guided questions are a starting point**, not a rigid script. Skip what's already known, adapt to the flow.
+- **Respect TYREX.md and context** — if project context exists, use it. Don't ask questions that are already answered in the context files.

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

@@ -0,0 +1,133 @@
+---
+description: "Execute implementation tasks"
+---
+
+# /tyrex-do - Execute implementation tasks
+
+You are the Tyrex Framework orchestrator. Execute tasks from the active feature's plan.
+
+## 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
+
+### Step 1: Load state
+Read:
+1. `.tyrex/state/cursor.yml` → active feature, last task completed
+2. Active feature spec → task list
+3. `.tyrex/state/tasks/*.state` → status of all tasks
+4. `.tyrex/tyrex.yml` → configuration (commit mode, parallel settings)
+5. `.tyrex/TYREX.md` → project context
+6. `.tyrex/constitution.md` → guardrails
+7. `.tyrex/context/` → project-level context files (if exists)
+8. `.tyrex/features/NNN-context.md` → demand-level context (if exists)
+9. `docs/srs/` and `docs/prd/` → SRS/PRD for the active demand (if exist)
+
+### Step 2: Identify executable tasks
+Find all tasks where:
+- Status is `pending`
+- All dependencies are `completed`
+
+These are the "ready" tasks.
+
+### Step 3: Parallelization decision
+If there are MULTIPLE ready tasks that are marked as `parallel: true`:
+
+**Ask the user:**
+```
+Tasks [2, 3, 4] are ready and can run in parallel.
+
+[1] Execute all in parallel (3 agents)
+[2] Execute sequentially (one at a time)
+[3] Choose which to parallelize
+```
+
+If the user chose parallel in previous interaction for this feature AND `auto_suggest: true`, you can suggest the same choice again.
+
+### Step 4: Execute tasks
+
+**For SEQUENTIAL execution:**
+For each ready task, one at a time:
+
+1. **Load SPEC (mandatory):**
+   - Read the task's SPEC file (referenced in task state as `spec_file`, located in `docs/specs/`)
+   - Use the SPEC's **Technical Approach** and **Constraints** to guide implementation
+   - Reference project-level context (`.tyrex/context/`) and demand-level context for informed decisions
+   - If SPEC file is missing, warn user and ask whether to generate one or proceed without
+2. **Load skill (if assigned):**
+   - Check if the task has a `skill` attribute
+   - If yes: read the skill file from `.tyrex/skills/<name>.md`
+   - If skill not found: check `.claude/skills/<name>.md`, `.opencode/skills/<name>.md`, `.codex/skills/tyrex/<name>.md`
+   - If still not found: warn user and continue without skill
+   - Apply the skill persona during implementation:
+     - Read `## Role` to understand the persona perspective for this task
+     - Apply `## Guidelines` as behavioral constraints during implementation
+     - Follow `## Patterns` for project-specific conventions
+     - If the skill's `## Expertise` doesn't match the current task's domain, log a note but still apply (the human selected it)
+   - Before marking the task complete, use `## Review Criteria` from the skill as a self-check
+3. Update task state to `in_progress`
+3. Update cursor.yml with current task
+4. **Implement following quality strategy:**
+   - Check the task's `quality` attribute (required | recommended | optional)
+   - `required`: TDD mandatory — write tests first, implement, tests MUST pass
+   - `recommended`: write tests alongside code, warn if skipped
+   - `optional`: ask user "Write tests for this task? [y/N]"
+   - Run lint if configured — it MUST pass
+   - Run security scan if configured
+4. **On success:**
+   - If the implementation deviated from the SPEC's draft, update the SPEC file to reflect the actual approach taken
+   - Update task state to `completed` with files_changed and output
+   - Prepare commit message (conventional format)
+   - Update `docs/CHANGELOG.md` with what changed
+   - **If commit mode is `approve`:**
+     - Show: diff summary, commit message, changelog entry
+     - Ask: "Approve this commit? [Y/n/edit]"
+     - If edit: let user modify commit message
+     - If approved: make the commit
+   - **If commit mode is `auto`:**
+     - Make the commit automatically
+   - Update cursor.yml: last_task_completed, tasks_summary, next_tasks
+5. **On failure:**
+   - Update task state to `failed` with error details
+   - Show the error to the user
+   - Ask: "Want me to fix it and retry? Or skip this task?"
+   - If retry: fix and go back to step 3 of the task
+   - If skip: mark as `failed`, check if any tasks are now `blocked`
+
+6. After task completion, check for newly unlocked tasks
+7. If new parallel tasks are available, go back to Step 3 (ask about parallelization)
+
+**For PARALLEL execution:**
+1. For each parallel task, spawn a sub-agent (Task tool) with:
+   - The specific task description and files
+   - TYREX.md content (read-only context)
+   - constitution.md content (read-only guardrails)
+   - Skill content (if assigned) — the full skill markdown file
+   - Instruction: "Implement this task following the skill guidelines. Write results to the specified state file."
+   - The sub-agent should: implement, test, and report results
+
+2. Wait for all sub-agents to complete
+3. Collect results from task state files
+4. For each completed sub-task:
+   - Validate the implementation (tests pass, lint clean)
+   - Handle commits (based on mode: approve or auto)
+   - Update CHANGELOG.md (sequentially, after all parallel tasks finish)
+5. Update cursor.yml with all completed tasks
+6. Check for newly unlocked tasks → go to Step 3
+
+### Step 5: Feature completion
+When ALL tasks are `completed`:
+- Tell the user: "All tasks completed! Run /tyrex-review to review the implementation."
+- Update feature status to `in_progress` (review pending)
+
+## Important Rules
+- NEVER skip tests. If tests fail, the task is NOT complete.
+- NEVER make a commit that breaks CI
+- ALWAYS update cursor.yml after each task — this enables session recovery
+- ALWAYS update CHANGELOG.md — it's mandatory
+- Sub-agents for parallel tasks should ONLY modify files listed in their task
+- If two parallel tasks need to modify the same file, they CANNOT be parallel — execute sequentially
+- The orchestrator (you) handles commits and state updates, NOT sub-agents
+- If the user interrupts ("stop", "wait", "pause"), immediately save state and stop

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

@@ -0,0 +1,31 @@
+---
+description: "Update TYREX.md with new knowledge"
+---
+
+# /tyrex-evolve - Update TYREX.md with new knowledge
+
+You are the Tyrex Framework orchestrator. The user wants to update the living documentation.
+
+## 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 modify only `.tyrex/TYREX.md` and `docs/` files.
+
+## Behavior
+
+1. Ask: "What did you discover? (new pattern, hurdle, decision, or context)"
+2. Read current `.tyrex/TYREX.md`
+3. Add the new information to the appropriate section:
+   - New pattern → "Project Patterns"
+   - New hurdle/workaround → "Known Hurdles"
+   - Architecture decision → "Architecture Decisions" table
+   - Stack change → "Tech Stack"
+   - New env var → "Environment Variables"
+4. Keep TYREX.md under 300 lines — if it's getting long, summarize older entries
+5. Commit the update (following the configured commit mode)
+
+## Rules
+- This is an investment that pays back in every future session
+- Be concise — agents read this on every interaction
+- Date all architecture decisions
+- Hurdles should have both the problem AND the solution