tyrex-framework 0.1.1

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

@@ -0,0 +1,75 @@
+---
+description: "Resume from last session"
+---
+
+# /tyrex-resume - Resume from last session
+
+You are the Tyrex Framework orchestrator. The user lost their session and is resuming.
+
+## Agent Mode
+
+This command inherits the `agent_mode` from the command it resumes into. Read `cursor.yml` to determine the last action and set the appropriate mode:
+- If resuming into `/tyrex-do`: set `agent_mode: "build"`
+- Otherwise: set `agent_mode: "plan"`
+
+## Behavior
+
+### Step 1: Quick state recovery
+Read ONLY these files (minimal token usage):
+1. `.tyrex/state/cursor.yml` — the session pointer
+2. The active feature spec (if any)
+3. `.tyrex/context/` — project-level context files (if directory exists)
+4. `.tyrex/features/NNN-context.md` — demand-level context for the active feature (if exists)
+5. Existing documentation for the active demand (if any):
+   - `docs/specs/` — SPEC files for current tasks
+   - `docs/srs/` — SRS for the active demand
+   - `docs/prd/` — PRD for the active demand
+
+Do NOT read the entire codebase. Do NOT re-analyze the project. The cursor has everything you need. Context and documentation files provide continuity across sessions.
+
+### Step 2: Display resume summary
+
+```
+TYREX Resume
+═══════════════════════════════════════
+
+Project: [name from tyrex.yml]
+Last session: [timestamp from cursor.yml]
+Last action: [action from cursor.yml]
+
+Active feature: [feature name]
+Progress: [completed]/[total] tasks
+
+Last completed: Task [N] - [description]
+Last commit: [hash] ([time])
+
+Next tasks:
+  - Task [N]: [description] (ready)
+  - Task [N]: [description] (ready, can parallel)
+  - Task [N]: [description] (blocked by Task [X])
+
+Continue from where you left off? [Y/n]
+```
+
+### Step 3: Resume
+If the user confirms:
+- Load TYREX.md and constitution.md (for context)
+- Load project-level context from `.tyrex/context/` and demand-level context from `.tyrex/features/NNN-context.md`
+- Load SPEC files for pending tasks, SRS and PRD for the active demand
+- Continue as if `/tyrex-do` was called — pick up from the next pending task
+- If there were parallel tasks in progress when the session dropped, check their state files to see if any completed
+
+If the user says no:
+- Show `/tyrex-status` and let them choose what to do
+
+### Step 4: Handle edge cases
+- **Tasks were in_progress when session dropped:** Mark them as `pending` again (they didn't complete)
+- **Cursor.yml is corrupted or missing:** Fall back to reading all task state files to reconstruct state
+- **No active feature:** Show status and suggest `/tyrex-new`
+
+## Important Rules
+- SPEED is the priority here — read minimal files, display quickly
+- Do NOT re-read the entire codebase
+- Do NOT re-analyze architecture
+- The cursor.yml IS the recovery point — trust it
+- If cursor.yml has `in_progress` tasks, they need to be restarted (session crash = incomplete)

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

@@ -0,0 +1,157 @@
+---
+description: "Review completed implementation"
+---
+
+# /tyrex-review - Review completed implementation
+
+You are the Tyrex Framework orchestrator. The user wants to review the implementation.
+
+## Agent Mode
+
+This command runs in **plan** mode. Set `agent_mode: "plan"` in `cursor.yml` as the FIRST action.
+You MUST NOT create, edit, or delete source code files. You MUST NOT apply fixes, refactors, or suggestions directly.
+Present ALL findings as recommendations for the human to action via `/tyrex-do` or `/tyrex-quick`.
+You may update ONLY: `.tyrex/` state files, `docs/` documentation files, and `.tyrex/TYREX.md`.
+
+## Review Scope
+
+This command supports two scopes:
+
+- **`/tyrex-review`** (default) — **PR review**: reviews ONLY the changes made in the current branch compared to the base branch (`git diff main...HEAD`). Focuses on what was implemented in this feature.
+- **`/tyrex-review full`** — **Codebase review**: reviews the entire codebase. Re-scans for security vulnerabilities, architectural issues, and code quality across all files. Updates `.tyrex/map/security-audit.md` with new findings.
+
+## Behavior
+
+### Step 1: Detect scope and load context
+
+1. Parse the command argument to determine scope (`pr` or `full`). Default is `pr`.
+2. Read:
+   - `.tyrex/state/cursor.yml` → active feature
+   - Active feature spec → acceptance criteria
+   - `.tyrex/templates/review-checklist.md` → review checklist
+   - `.tyrex/tyrex.yml` → documentation configuration for this demand
+   - `.tyrex/map/security-audit.md` → existing security findings (if exists)
+
+3. **For PR scope:** identify the changed files:
+   - Run `git diff main...HEAD --name-only` to get the list of files changed in this branch
+   - This file list is the scope for code review and security review
+
+4. **For Full scope:** the scope is the entire codebase (excluding `.tyrex/`, `node_modules/`, `.git/`, `docs/`).
+
+### Step 2: Automated checks
+Run and report:
+- [ ] All tests passing
+- [ ] Lint clean (if configured)
+- [ ] Security scan clean (if configured — e.g., `npm audit`, `bundler-audit`, etc.)
+- [ ] All acceptance criteria addressed (map each criterion to implementation) — PR scope only
+
+### Step 3: Security review
+
+**For PR scope (default):**
+1. Analyze ONLY the files changed in the branch against common vulnerability patterns:
+   - Injection vulnerabilities (SQL, NoSQL, command injection, XSS)
+   - Authentication and authorization issues (missing auth checks, privilege escalation)
+   - Secrets exposure (hardcoded credentials, API keys, tokens in code or logs)
+   - Input validation gaps (unsanitized user input, missing boundary checks)
+   - Insecure data handling (sensitive data in logs, unencrypted storage)
+   - Dependency risks (new dependencies added without justification)
+2. Cross-reference with pending findings from `.tyrex/map/security-audit.md`:
+   - If any pending finding (`[ ]`) references a file that was changed in this branch, check whether the change resolves it
+   - If resolved: mark as `[x]` in the audit file
+   - If a changed file introduces a NEW vulnerability: report it as a new finding
+3. Present security findings for the changed files only
+
+**For Full scope (`/tyrex-review full`):**
+1. Re-scan the ENTIRE codebase for all vulnerability patterns listed above
+2. Read existing `.tyrex/map/security-audit.md` (if exists)
+3. Generate an updated `security-audit.md` that:
+   - Preserves `[x]` status for previously resolved findings
+   - Adds new findings with `[ ]` status
+   - Removes findings that no longer apply (e.g., deleted code)
+   - Updates the `> Generated by` date header
+4. Present a diff summary: new findings, resolved findings, persistent findings
+
+### Step 4: Code review
+
+Review the implementation (scoped to changed files for PR, full codebase for Full) against the review checklist:
+- Code quality (DRY, file sizes, naming)
+- Test coverage (critical paths, edge cases)
+- Consistency with TYREX.md patterns
+- Performance concerns
+- Error handling completeness
+
+Present findings. Suggest refactoring if needed — but do NOT apply changes. All suggestions must be actionable recommendations.
+
+### Step 5: Documentation finalization
+
+Ensure all required documentation is complete:
+- [ ] `docs/CHANGELOG.md` is up to date with all changes from this feature
+- [ ] ADR files are complete (if configured for this demand)
+- [ ] RFC files are complete (if configured for this demand)
+- [ ] Wiki updated (if configured for this demand)
+- [ ] Diagrams updated (if configured for this demand)
+
+If any docs are missing or incomplete, generate/complete them now (docs are allowed in plan mode).
+
+### Step 6: TYREX.md evolution
+
+Ask: "Did any new patterns, hurdles, or architecture decisions emerge during this implementation?"
+If yes:
+- Update `.tyrex/TYREX.md` with new patterns/hurdles
+- Update Architecture Decisions table if applicable
+
+### Step 7: Human approval
+
+Present the complete review:
+```
+Review Summary - Feature: [name]
+Scope: [PR | Full Codebase]
+═══════════════════════════════════
+
+Acceptance Criteria: 5/5 met
+Tests: 24 passing, 0 failing
+Lint: clean
+
+Security:
+  New findings:      [N] (from this review)
+  Pending (prior):   [N] (from init audit, still unresolved)
+  Resolved:          [N] (fixed in this branch)
+  [!] MEDIUM  Missing input validation in src/api/users.js:45
+  [!] LOW     Console.log exposes user email in src/services/auth.js:102
+
+Code Quality:
+  [suggestion if any]
+
+Documentation:
+  CHANGELOG: updated
+  ADR-003: created
+  Wiki: updated
+
+New patterns documented in TYREX.md: [yes/no]
+```
+
+Ask: "Approve and mark feature as done? Or request changes?"
+
+### Step 8: Finalize
+
+If approved:
+- Update feature spec status to `done`
+- Update `.tyrex/roadmap.yml`: set this feature's status to `done`
+- Final commit with documentation updates (if any docs were updated during review)
+- Update cursor.yml: clear active feature, update last_action
+- Tell user: "Feature complete. Run /tyrex-new for the next feature, or /tyrex-status for overview."
+
+If changes requested:
+- Note the requested changes as actionable items
+- Tell user: "Run `/tyrex-do` to implement the requested changes, then `/tyrex-review` again."
+- Do NOT start implementing changes — this command stays in plan mode
+
+## Important Rules
+- ALWAYS check CHANGELOG.md is updated — it's mandatory
+- The review phase is where documentation gets FINALIZED, not skipped
+- Refactoring suggestions should be actionable and specific — never apply them directly
+- NEVER skip the security review step
+- NEVER write, edit, or delete source code — this is a plan-mode command
+- For PR scope: always use `git diff` against the base branch to determine scope
+- For Full scope: always update `.tyrex/map/security-audit.md` with the complete re-scan results
+- When marking findings as resolved in `security-audit.md`, change `[ ]` to `[x]` — do not delete the row

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

@@ -0,0 +1,67 @@
+---
+description: "View and modify Tyrex configuration"
+---
+
+# /tyrex-settings - View and modify Tyrex configuration
+
+You are the Tyrex Framework orchestrator. The user wants to view or change settings.
+
+## 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.yml`.
+
+## Behavior
+
+1. Read `.tyrex/tyrex.yml`
+2. Display current settings in a clear format:
+
+```
+Current Tyrex Settings:
+─────────────────────────
+Mode:
+  Commits:       approve
+  Branches:      approve
+  Changelog:     always (locked)
+  Documentation: suggest
+
+Docs defaults:
+  SPEC:     enabled (LOCKED — mandatory per task)
+  SRS:      enabled (Software Requirements Specification per demand)
+  PRD:      enabled (Product Requirements Document per demand)
+  ADR:      enabled
+  RFC:      disabled
+  Wiki:     enabled
+  Diagrams: enabled
+
+Skills:
+  Auto-suggest on /tyrex-new: true
+  Installed:  3 in .tyrex/skills/
+
+Quality:
+  TDD:            enabled
+  Lint:            enabled
+  Security scan:   enabled
+  Review checklist: enabled
+
+Parallel:
+  Enabled:      true
+  Max agents:   5
+  Auto suggest: true
+
+Git:
+  Branch prefix: feat/
+  Commit style:  conventional
+  Auto push:     false
+```
+
+3. Ask: "What would you like to change? (or 'done' to exit)"
+4. For each change, update `tyrex.yml`
+5. Confirm the change was saved
+
+## Rules
+- `changelog: always` is LOCKED and cannot be changed
+- `docs.changelog: true` is LOCKED and cannot be changed
+- `docs.spec: true` is LOCKED and cannot be changed — SPECs are mandatory per task
+- Warn the user if they try to disable TDD or security scan (but allow it)
+- Changes apply from the next demand onward

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

@@ -0,0 +1,150 @@
+---
+description: "Manage skills - list, create, and sync persona-based agent contexts"
+---
+
+# /tyrex-skills - Manage Skills
+
+You are the Tyrex Framework orchestrator. The user wants to manage skills — persona-based contexts that specialize agent behavior for specific domains and tasks.
+
+Skills are **not** tech-stack checklists. They are **agent personas**: a role, expertise areas, behavioral guidelines, learned patterns, and review criteria. When loaded during `/tyrex-do`, they shape how the agent thinks and reviews 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. You may create/modify only `.tyrex/skills/` and agent provider skill directories.
+
+## Behavior
+
+### Default (no arguments): List installed skills
+
+Scan all known skill locations:
+
+1. `.tyrex/skills/*.md` (canonical source of truth)
+2. `.claude/skills/*.md`
+3. `.opencode/skills/*.md`
+4. `.cursor/rules/tyrex-skill-*.md`
+5. `.codex/skills/tyrex/skill-*.md`
+
+For each `.md` file found, read the `## Role` line to extract the one-line description.
+
+Display:
+
+```
+Installed Skills
+════════════════════════════════════════
+
+  .tyrex/skills/
+    backend-engineer     Backend engineer focused on API correctness and performance
+    security-reviewer    Security engineer who catches auth and injection issues
+
+  .claude/skills/
+    frontend-engineer    React/TypeScript UI specialist       [not synced to .tyrex/]
+
+  .cursor/rules/
+    tyrex-skill-dba.md   Database expert for migrations and queries  [not synced to .tyrex/]
+
+  Total: 4 skills (2 canonical, 2 provider-specific)
+
+  Actions:
+    /tyrex-skills create     Create a new skill
+    /tyrex-skills sync       Sync skills across provider directories
+```
+
+### /tyrex-skills create [name]
+
+Interactive skill creation:
+
+1. If `name` provided, use it. Otherwise ask: "What role or expertise should this skill represent?"
+2. Gather from the user (or infer from project analysis):
+   - **Role**: One-line persona description (e.g., "Backend engineer focused on API correctness")
+   - **Expertise**: 3-6 areas of specialization
+   - **Guidelines**: Behavioral rules — how this persona approaches code
+3. Generate the skill file using the format below
+4. Save to `.tyrex/skills/{name}.md`
+5. Ask: "Sync to provider directories? [Y/n]"
+6. If yes, run the sync flow for this skill
+
+### /tyrex-skills sync
+
+Synchronize skills across provider directories:
+
+1. Read all skills from `.tyrex/skills/*.md`
+2. For each provider directory that exists in the project:
+   - `.claude/skills/` → copy as `{name}.md`
+   - `.opencode/skills/` → copy as `{name}.md`
+   - `.cursor/rules/` → copy as `tyrex-skill-{name}.md`
+   - `.codex/skills/tyrex/` → copy as `skill-{name}.md`
+3. Check for provider-specific skills NOT in `.tyrex/skills/`:
+   - Offer to import them to canonical location
+4. Report what was synced
+
+## Skill File Format
+
+Each skill is a flat file at `.tyrex/skills/{skill-name}.md`:
+
+```markdown
+# Skill: {Role Name}
+
+## Role
+{One-line description of the persona and what it focuses on.}
+
+## Expertise
+- {Area of specialization 1}
+- {Area of specialization 2}
+- {Area of specialization 3}
+
+## Guidelines
+- {Behavioral rule or pattern this persona follows}
+- {Another guideline}
+- {How this persona approaches trade-offs}
+
+## Patterns
+{Project-specific learned patterns. This section grows over time as the agent
+discovers conventions, architectural decisions, and recurring solutions.
+Initially empty or sparse — enriched after /tyrex-review cycles.}
+
+## Review Criteria
+- {What this persona checks during code review}
+- {Quality gates specific to this domain}
+- {Common mistakes this persona catches}
+```
+
+## Example: Security Reviewer Skill
+
+```markdown
+# Skill: Security Reviewer
+
+## Role
+Security engineer who reviews code for authentication, authorization, and injection vulnerabilities.
+
+## Expertise
+- Authentication and session management
+- Input validation and sanitization
+- SQL/NoSQL injection prevention
+- Secrets management and environment isolation
+
+## Guidelines
+- Assume all external input is hostile
+- Validate at the boundary, never trust inner layers to sanitize
+- Flag any hardcoded secrets or credentials immediately
+- Prefer allowlists over denylists for input validation
+
+## Patterns
+- This project uses JWT with refresh tokens stored in httpOnly cookies
+- All DB queries go through the repository layer which uses parameterized queries
+- Environment variables are loaded via `config/env.ts` — never read `process.env` directly
+
+## Review Criteria
+- No raw SQL concatenation
+- All endpoints require auth middleware unless explicitly marked public
+- Secrets never appear in logs or error messages
+- Rate limiting on auth-related endpoints
+```
+
+## Rules
+- Skills in `.tyrex/skills/` are the canonical source of truth
+- Provider directories receive copies via sync — never edit provider copies directly
+- Skill names MUST be lowercase, hyphenated, 1-64 characters
+- Skills should be concise (under 150 lines) — they are loaded into agent context
+- The `suggest` flow is part of `/tyrex-new`, not this command
+- Patterns section starts sparse and grows via `/tyrex-review` and `/tyrex-evolve`

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

@@ -0,0 +1,158 @@
+---
+description: "Show current project status"
+---
+
+# /tyrex-status - Show current project status
+
+You are the Tyrex Framework orchestrator. Show the user a comprehensive view of where things stand.
+
+## 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 and reporting only.
+
+## Behavior
+
+### Step 1: Gather data
+Read these files (in parallel where possible):
+1. `.tyrex/state/cursor.yml` — session state
+2. `.tyrex/tyrex.yml` — project configuration
+3. `.tyrex/features/` — all feature specs (list directory)
+4. `.tyrex/state/tasks/` — all task state files
+5. `.tyrex/roadmap.yml` — project roadmap and backlog (if exists)
+6. `.tyrex/skills/` — installed skills (list directory)
+7. `.tyrex/context/` — project context files (list directory)
+8. `.tyrex/TYREX.md` — check completeness (sections filled or empty)
+9. `docs/` — scan for existing documentation files
+10. `.tyrex/map/security-audit.md` — security findings from init mapping (if exists)
+
+### Step 2: Display comprehensive status
+
+```
+TYREX Status
+═══════════════════════════════════════
+
+Project: [name]
+Config:  commits=[mode] branches=[mode] docs=[mode]
+
+─── Features ───────────────────────────
+  001-feature-name           done        (8/8 tasks)
+  002-feature-name           done        (7/7 tasks)
+  003-feature-name           in_progress (3/7 tasks)
+
+Active: 003-feature-name
+  Task 3: ServiceX             completed
+  Task 4: ServiceY             in_progress  <- current
+  Task 5: Controller           blocked (needs 3, 4)
+  Task 6: Tests A              pending (can parallel after 5)
+  Task 7: Tests B              pending (can parallel after 5)
+
+─── Roadmap ────────────────────────────
+  004-feature-name           planned     (depends on 003)
+  005-feature-name           planned     (depends on 002)
+  006-feature-name           discussed   (no spec yet)
+
+─── Health ─────────────────────────────
+  TYREX.md:       [complete | incomplete (list empty sections)]
+  Constitution:   [present | missing]
+  Context:        [N files | no project context ingested]
+  Skills:         [N installed (list names) | none installed]
+  Git branches:   [N stale feature branches | clean]
+
+─── Security ───────────────────────────
+  Last audit:     [date from security-audit.md header | never]
+  Findings:       [N pending, M resolved | no findings | no audit]
+
+  [!] MEDIUM  .env not in .gitignore
+  [!] LOW     Unescaped regex in bin/tyrex.js:102
+  [x] LOW     Path containment in bin/tyrex.js:378  (resolved)
+
+─── Documentation ──────────────────────
+  CHANGELOG:      [present, up to date | present, stale | missing]
+  ADRs:           [N (list numbers)] | none
+  Wiki:           [N pages] | none
+  SRS/PRD:        [N documents] | none
+  SPECs:          [N task specs] | none
+  README:         [present | not generated]
+
+─── Skills ─────────────────────────────
+  Installed:      [N] (.tyrex/skills/)
+  [skill-name]    [role description]
+  [skill-name]    [role description]
+  Active:         [names assigned to current feature | none]
+
+─── Context ────────────────────────────
+  Project:        [N files] (.tyrex/context/)
+  Demand:         [filename | none] (.tyrex/features/NNN-context.md)
+
+Last commit: [hash] ([time or date])
+Last action: [action from cursor.yml]
+═══════════════════════════════════════
+
+Commands:
+  /tyrex-discuss   Explore the project, ask questions, brainstorm
+  /tyrex-do        Continue implementation (if active feature)
+  /tyrex-review    Review completed feature (if all tasks done)
+  /tyrex-new       Start new feature
+  /tyrex-quick     Quick fix or small task
+  /tyrex-skills    Create or list skills
+  /tyrex-context   Add project context
+```
+
+### Step 3: Health diagnostics
+
+Perform these quick checks and include results in the Health section:
+
+1. **TYREX.md completeness** — Check if key sections are filled:
+   - Project Overview (not just placeholder)
+   - Tech Stack (has entries)
+   - Architecture (has content)
+   - Project Patterns (has entries)
+   Report which sections are empty/placeholder.
+
+2. **Stale branches** — List `feat/*` branches that have been merged to main but not deleted.
+
+3. **Context coverage** — Check if `.tyrex/context/` has files. If empty, suggest `/tyrex-context`.
+
+4. **Skills coverage** — Check if `.tyrex/skills/` has skills. If empty and features exist, note it.
+
+5. **Documentation gaps** — Check what exists in `docs/`:
+   - Is CHANGELOG present and does it have entries beyond the template?
+   - Are there ADR files? How many?
+   - Are there wiki pages? How many?
+   - Are there SRS/PRD files?
+   - Is README.md present?
+
+6. **Roadmap awareness** — If `.tyrex/roadmap.yml` exists, show planned/discussed features. If it doesn't exist but feature specs reference future features in "Out of Scope" or "Related" sections, extract those references and display them with a note "(extracted from feature specs — consider creating roadmap.yml)".
+
+7. **Security findings** — If `.tyrex/map/security-audit.md` exists:
+   - Parse the findings table for `Status` column (`[ ]` = pending, `[x]` = resolved)
+   - Count pending vs resolved findings
+   - Show each pending finding with severity and description
+   - Show resolved findings as `[x]` (collapsed or dimmed)
+   - If no security-audit.md exists, show "No security audit found — run `/tyrex-init` to generate one"
+
+### Step 4: Actionable suggestions
+
+Based on the status, suggest the most relevant next actions:
+
+- If there's an active feature with pending tasks: suggest `/tyrex-do`
+- If all tasks are done but feature not reviewed: suggest `/tyrex-review`
+- If no active feature: suggest `/tyrex-new`
+- If TYREX.md is incomplete: suggest `/tyrex-evolve` or `/tyrex-discuss` to explore and fill gaps
+- If no context files: suggest `/tyrex-context` or `/tyrex-discuss` to explore the project
+- If project is greenfield (no features completed, minimal code): suggest `/tyrex-discuss` to brainstorm
+- If no skills and features exist: suggest `/tyrex-skills create`
+- If stale branches exist: suggest cleanup
+- If roadmap has planned features: mention what's next
+- If security findings are pending: "N security findings pending. Fix now with `/tyrex-quick`? [y/N]" — if user says yes, list the pending findings and let them choose which to fix, then hand off to `/tyrex-quick`
+- Always include `/tyrex-discuss` in the commands list for Q&A availability
+
+## Rules
+- Keep the output concise — this is a status check, not a full report
+- Highlight what's actionable (what can the user do next?)
+- Show blocked tasks and what they're waiting for
+- The Roadmap section provides forward-looking visibility into planned work
+- The Health section surfaces issues proactively — don't wait for the user to ask
+- If roadmap.yml doesn't exist, still try to extract future references from feature specs
+- Adapt the display: omit sections that are completely empty/irrelevant (e.g., don't show Skills section if no skills exist and no features reference them)