tyrex-framework 0.1.1

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

@@ -0,0 +1,116 @@
+---
+description: "Generate or update project wiki pages in docs/wiki/"
+---
+
+# /tyrex-wiki - Generate/Update Project Wiki
+
+You are the Tyrex Framework orchestrator. Generate or update wiki-style documentation for the project in `docs/wiki/`.
+
+## 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 `docs/wiki/` and `.tyrex/` files.
+
+## Behavior
+
+### Step 1: Project analysis
+
+Read the project to understand what needs documenting:
+
+1. `.tyrex/TYREX.md` — project context, architecture, patterns
+2. `.tyrex/map/` — project mapping (if exists)
+3. Source code structure — identify major modules/areas
+4. Existing wiki pages in `docs/wiki/` — understand what's already documented
+5. ADRs in `docs/adrs/` — architecture decisions that need wiki context
+6. Feature specs in `.tyrex/features/` — completed features that may need documentation
+
+### Step 2: Propose wiki structure
+
+Present a proposed wiki structure based on the project:
+
+```
+docs/wiki/
+├── index.md                    # Wiki home (table of contents)
+├── getting-started.md          # Onboarding guide for new developers
+├── architecture.md             # System architecture overview with diagrams
+├── [area-1].md                 # e.g., authentication.md, payments.md
+├── [area-2].md                 # One page per major feature/domain area
+├── deployment.md               # Deployment guide
+├── troubleshooting.md          # Common issues and solutions
+└── glossary.md                 # Project-specific terminology
+```
+
+For each proposed page, show:
+- Title
+- Brief description of what it would cover
+- Whether it already exists (update) or is new (create)
+
+Ask: "Generate all pages? Or select individually?"
+
+### Step 3: Generate wiki pages
+
+For each selected page, generate content following these rules:
+
+**index.md:**
+- Table of contents with links to all wiki pages
+- Brief project description
+- Quick navigation guide
+
+**getting-started.md:**
+- Prerequisites and setup steps
+- Key concepts a new developer needs to know
+- First tasks / where to start
+- Links to relevant wiki pages
+
+**architecture.md:**
+- System overview with Mermaid diagrams
+- Component descriptions
+- Data flow
+- Key design decisions (link to ADRs)
+
+**[area].md (domain pages):**
+- What this area does
+- Key files and their responsibilities
+- How to modify / extend this area
+- Testing approach for this area
+- Common patterns used
+
+**deployment.md:**
+- Environment setup
+- Deployment steps
+- Rollback procedures
+- Monitoring / health checks
+
+**troubleshooting.md:**
+- Common errors and solutions
+- Debugging tips
+- Known issues and workarounds
+
+**glossary.md:**
+- Project-specific terms and their definitions
+- Abbreviations used in the codebase
+
+### Step 4: Handle existing pages
+
+If wiki pages already exist:
+1. Compare existing content with generated content
+2. For each page, show what would change
+3. Ask: "Update? [Y/n/merge]"
+   - Y: Replace entirely
+   - n: Skip this page
+   - merge: Keep user-written sections, update generated sections
+
+### Step 5: Commit
+
+Update CHANGELOG.md with the wiki change.
+Handle commit based on configured mode (auto/approve).
+
+## Rules
+- Every wiki page MUST include Mermaid diagrams where architecture or flow is described
+- Pages should be self-contained — a developer should be able to read one page and understand that area
+- Cross-reference between pages using relative links
+- Do NOT document implementation details that change frequently — focus on concepts and patterns
+- Keep each page under 200 lines — split into sub-pages if needed
+- Do NOT invent features or capabilities — only document what exists in the code
+- Include code examples from the actual codebase when illustrating patterns
+- Date each page with "Last updated: YYYY-MM-DD" at the bottom

package/templates/constitution.md

@@ -0,0 +1,60 @@
+# Constitution - {{PROJECT_NAME}}
+
+> Inviolable principles. The AI agent MUST follow these at all times.
+> The human can update this document. The AI cannot ignore it.
+
+## Rules
+
+1. **Every commit passes CI** (lint + tests + security scan)
+2. **TDD**: write tests alongside or before code
+3. **No hardcoded secrets** in code or commits
+4. **No unnecessary dependencies** - justify every addition
+5. **Simplicity > Cleverness** - the simplest solution that works wins
+6. **CHANGELOG is mandatory** - every change updates docs/CHANGELOG.md
+7. **Small commits** - one task = one commit, atomic and revertible
+8. **Documentation first** - when configured, generate docs before code
+
+## The Agent MUST
+
+- Ask when in doubt instead of assuming
+- Propose the simplest solution first
+- Warn when something seems over-engineered
+- Follow patterns documented in TYREX.md
+- Update CHANGELOG.md after every change
+- Run tests before considering a task complete
+- Respect task dependencies defined in feature specs
+- Update cursor.yml after completing each task
+
+## The Agent MUST NOT
+
+- Implement without human approval of the plan
+- Add features, libraries, or tools not requested
+- Make commits that break CI
+- Skip tests
+- Generate specs or plans longer than 50 lines per feature
+- Modify constitution.md without explicit human approval
+- Ignore the "Out of Scope" section in feature specs
+- Push to remote without explicit human approval
+
+## On Agent Mode
+
+- The `agent_mode` field in `cursor.yml` controls what the agent can do
+- Each `/tyrex-*` command sets `agent_mode` as its FIRST action before any other work
+- The agent MUST read `agent_mode` from `cursor.yml` before taking any action
+- **`plan` mode**: the agent MUST NOT create, edit, or delete source code files. Only `.tyrex/`, `docs/`, and configuration files may be modified. Analysis, planning, discussion, and documentation only.
+- **`build` mode**: the agent may create, edit, and delete source code files following all other rules (TDD, small commits, CI, etc.)
+- If the agent detects `agent_mode: "plan"` and is asked to write source code, it MUST refuse and suggest running `/tyrex-do` or `/tyrex-quick` instead
+
+## On Parallelization
+
+- Sub-agents receive ONLY their task context + TYREX.md + constitution.md
+- Sub-agents write ONLY to their own task state file
+- Sub-agents do NOT modify cursor.yml (only the orchestrator does)
+- Sub-agents do NOT modify CHANGELOG.md (done after wave completion)
+- Conflicts in file modifications = those tasks CANNOT be parallelized
+
+## On Commits
+
+- Mode "approve": write commit message + changelog entry, present to human, wait for approval
+- Mode "auto": commit automatically with conventional commit message, update changelog
+- Branch naming: agent suggests based on feature, human approves (or auto if configured)

package/templates/cursor.yml

@@ -0,0 +1,29 @@
+# .tyrex/state/cursor.yml - Session pointer for quick recovery
+# This file enables fast session resumption without re-reading the entire codebase.
+# Updated by the orchestrator agent after each task completion.
+
+last_updated: "{{DATE}}T00:00:00Z"
+session_id: null
+
+# Agent mode controls what the agent can do.
+# "plan"  — read, analyze, discuss, plan. MUST NOT write source code.
+# "build" — implement, test, commit. May write source code following TDD and commit rules.
+# Each /tyrex-* command sets this field as its FIRST action.
+agent_mode: "plan"
+
+active_feature: null
+active_feature_file: null
+
+last_task_completed: null
+last_commit: null
+last_action: "tyrex_initialized"
+
+tasks_summary:
+  total: 0
+  completed: 0
+  in_progress: 0
+  pending: 0
+  failed: 0
+  blocked: 0
+
+next_tasks: []

package/templates/feature.md

@@ -0,0 +1,40 @@
+# Feature: [NAME]
+
+## Objective
+<!-- 1-2 sentences: WHAT and WHY -->
+
+## Acceptance Criteria
+- [ ] ...
+- [ ] ...
+
+## Out of Scope
+<!-- What NOT to do. Critical to prevent over-engineering. -->
+- ...
+
+## Technical Notes
+<!-- Added during /tyrex-plan phase -->
+
+## Tasks
+<!-- Added during /tyrex-plan phase. Each task has dependency, parallelism, skill, and quality attributes. -->
+<!--
+### Task 1: [description]
+- **Type:** sequential | parallel
+- **Depends on:** [] (task numbers)
+- **Unlocks:** [] (task numbers)
+- **Estimate:** small | medium | large
+- **Files:** [files to create or modify]
+- **Skill:** none | [skill name from .tyrex/skills/]
+- **Quality:** required | recommended | optional
+- **Status:** pending | in_progress | completed | failed
+-->
+
+## Configuration
+<!-- Set during /tyrex-new -->
+<!--
+- Commits: approve | auto
+- Branch: feat/...
+- Docs: [changelog, spec, srs, prd, adr, rfc, wiki, diagrams]
+-->
+
+## Status: spec
+<!-- spec | planned | in_progress | done -->

package/templates/prd.md

@@ -0,0 +1,30 @@
+# PRD: [PRODUCT/FEATURE TITLE]
+
+## Date
+{{DATE}}
+
+## Project
+{{PROJECT_NAME}}
+
+## Problem Statement
+<!-- What problem are we solving? Who is affected? -->
+
+## Goals & Success Metrics
+<!-- Desired outcomes and how we measure success. -->
+
+## User Personas
+<!-- Who are the target users? Brief descriptions. -->
+
+## Requirements
+
+### Must-Have
+- ...
+
+### Nice-to-Have
+- ...
+
+## Out of Scope
+<!-- What is explicitly NOT part of this effort? -->
+
+## Timeline / Milestones
+<!-- Optional. Key dates or phases if applicable. -->

package/templates/review-checklist.md

@@ -0,0 +1,37 @@
+# Review Checklist
+
+## Functionality
+- [ ] All acceptance criteria met
+- [ ] Edge cases handled
+- [ ] Error handling in place
+
+## Code Quality
+- [ ] No code duplication (DRY)
+- [ ] Functions/methods < 50 lines
+- [ ] Files < 300 lines
+- [ ] Clear naming conventions
+- [ ] Consistent with project patterns (TYREX.md)
+
+## Tests
+- [ ] Tests cover critical paths
+- [ ] Tests cover edge cases
+- [ ] All tests passing
+- [ ] Test-to-code ratio reasonable (aim for > 1.0x)
+
+## Security
+- [ ] No hardcoded secrets
+- [ ] Input validation present
+- [ ] No SQL injection vectors
+- [ ] No path traversal vectors
+- [ ] Dependencies audited
+
+## Documentation
+- [ ] CHANGELOG.md updated
+- [ ] ADR created (if architecture decision was made)
+- [ ] TYREX.md updated (if new patterns emerged)
+- [ ] Code comments where non-obvious
+
+## Git
+- [ ] Atomic commits (one task = one commit)
+- [ ] Conventional commit messages
+- [ ] No broken commits in history

package/templates/rfc.md

@@ -0,0 +1,19 @@
+# RFC-[NUMBER]: [TITLE]
+
+## Summary
+<!-- One paragraph explanation of the proposal -->
+
+## Motivation
+<!-- Why are we doing this? What problem does it solve? -->
+
+## Detailed Design
+<!-- Technical details of the implementation -->
+
+## Drawbacks
+<!-- Why should we NOT do this? -->
+
+## Alternatives
+<!-- What other designs have been considered? -->
+
+## Unresolved Questions
+<!-- What parts of the design are still TBD? -->

package/templates/roadmap.yml

@@ -0,0 +1,16 @@
+# .tyrex/roadmap.yml - Project roadmap and feature backlog
+# Tracks planned, in-progress, and completed features.
+# Updated by /tyrex-new (planned -> in_progress), /tyrex-review (-> done).
+# Read by /tyrex-status for project-wide visibility.
+#
+# Status values: planned | in_progress | done | cancelled
+#
+# To add a planned feature manually:
+#   - id: "NNN"
+#     name: "feature-name"
+#     description: "Short description of the feature"
+#     status: planned
+#     referenced_in: []
+#     depends_on: []
+
+features: []

package/templates/skill.md

@@ -0,0 +1,16 @@
+# Skill: {{SKILL_NAME}}
+
+## Role
+{{ROLE_DESCRIPTION}}
+
+## Expertise
+{{EXPERTISE_AREAS}}
+
+## Guidelines
+{{BEHAVIORAL_GUIDELINES}}
+
+## Patterns
+<!-- Project-specific patterns learned over time. Initially empty, enriched after /tyrex-review. -->
+
+## Review Criteria
+{{REVIEW_CRITERIA}}

package/templates/spec.md

@@ -0,0 +1,33 @@
+# Spec: [TASK TITLE]
+
+## Feature
+<!-- Reference to parent feature, e.g. Feature 001 -->
+
+## Date
+{{DATE}}
+
+## Project
+{{PROJECT_NAME}}
+
+## Objective
+<!-- What does this task achieve technically? One or two sentences. -->
+
+## Technical Approach
+<!-- How will this be implemented? Key steps, algorithms, patterns. -->
+
+## Constraints & Trade-offs
+<!-- Known limitations, performance budgets, compatibility concerns. -->
+
+## Dependencies
+<!-- Libraries, services, or other tasks this depends on. -->
+
+## Files Affected
+<!-- List of files to create or modify. -->
+- ...
+
+## Edge Cases
+<!-- Scenarios that need special handling. -->
+
+## Testing Strategy
+<!-- What tests will be written? Unit, integration, e2e? -->
+- [ ] ...

package/templates/srs.md

@@ -0,0 +1,27 @@
+# SRS: [FEATURE TITLE]
+
+## Feature
+<!-- Reference to parent feature, e.g. Feature 001 -->
+
+## Date
+{{DATE}}
+
+## Project
+{{PROJECT_NAME}}
+
+## Functional Requirements
+<!-- Numbered list of what the system must do. -->
+1. ...
+
+## Non-Functional Requirements
+<!-- Performance, security, scalability, accessibility, etc. -->
+- ...
+
+## User Stories
+<!-- Optional. Format: As a [role], I want [goal], so that [benefit]. -->
+
+## Constraints
+<!-- Technical, regulatory, or business constraints. -->
+
+## Assumptions
+<!-- What are we assuming to be true for this specification? -->

package/templates/tyrex.yml

@@ -0,0 +1,54 @@
+# .tyrex/tyrex.yml - Tyrex Framework Configuration
+# Docs: https://github.com/tyrex-framework/tyrex
+
+project:
+  name: "{{PROJECT_NAME}}"
+  created: "{{DATE}}"
+
+# Operation mode
+mode:
+  commits: "{{COMMIT_MODE}}"         # "auto" | "approve"
+  branches: "{{BRANCH_MODE}}"        # "auto" | "approve"
+  changelog: "always"                # LOCKED - always enabled
+  documentation: "{{DOC_MODE}}"      # "always" | "suggest" | "minimal"
+
+# Documentation defaults for new demands (/tyrex-new)
+docs:
+  spec: true                        # LOCKED - always true (technical specification per task)
+  srs: true                         # Software Requirements Specification per demand
+  prd: true                         # Product Requirements Document per demand
+  adr: true
+  rfc: false
+  wiki: true
+  diagrams: true
+  changelog: true                    # LOCKED - always true
+
+# Quality guardrails
+quality:
+  lint: true
+  security_scan: true
+  review_checklist: true
+  # Adaptive quality strategy per area type
+  # Values: "required" (TDD mandatory) | "recommended" (tests suggested) | "optional" (ask user)
+  strategy:
+    default: "required"            # Fallback for areas not listed below
+    api: "required"                # API endpoints, controllers
+    workers: "required"            # Background jobs, queue processors
+    data: "required"               # Models, migrations, data layer
+    security: "required"           # Auth, encryption, access control
+    frontend: "recommended"        # UI components, views
+    mobile: "recommended"          # Mobile-specific code
+    infra: "optional"             # Docker, CI/CD, config files
+    docs: "optional"              # Documentation generation
+
+# Parallelization
+parallel:
+  enabled: true
+  max_agents: {{MAX_AGENTS}}
+  auto_suggest: true                 # Suggest parallelization when possible
+
+# Git
+git:
+  branch_prefix: "{{BRANCH_PREFIX}}"
+  commit_style: "{{COMMIT_STYLE}}"   # "conventional" | "descriptive"
+  auto_push: false                   # Never auto-push by default