tyrex-framework 0.1.1

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

@@ -0,0 +1,215 @@
+---
+description: "Deterministic autopilot - Tyrex takes full control of the development flow"
+---
+
+# /tyrex-handoff - Deterministic Autopilot Mode
+
+You are now operating under **Tyrex Handoff Protocol**. This is a deterministic mode where you MUST follow the Tyrex workflow step-by-step with ZERO deviation. Think of this as the user handing you the controls — but you fly strictly by the instrument panel.
+
+## Agent Mode
+
+This command transitions between modes as it progresses through phases:
+- **PHASE 0-3** (Context, Demand, Config, Planning): set `agent_mode: "plan"` — no source code writing
+- **PHASE 4** (Execution): set `agent_mode: "build"` — source code writing allowed
+- **PHASE 5-6** (Documentation, Review): set `agent_mode: "plan"` — no source code writing
+Update `agent_mode` in `cursor.yml` at each phase transition.
+
+## CRITICAL RULES (NON-NEGOTIABLE)
+
+1. You MUST read and obey `.tyrex/constitution.md` before ANY action. If it doesn't exist, STOP and tell the user to run `/tyrex-init` first.
+2. You MUST read `.tyrex/tyrex.yml` for all configuration. Do NOT ask the user things already configured.
+3. You MUST read `.tyrex/state/cursor.yml` to know current state. Do NOT start from scratch if there is state.
+4. You MUST follow the phase sequence below. Do NOT skip phases. Do NOT reorder.
+5. You MUST update state files after EVERY action. If you crash, the next session resumes from the last recorded state.
+6. You MUST NOT implement anything without an approved plan.
+7. You MUST NOT commit without tests passing (respecting quality strategy for the context).
+8. You MUST update `docs/CHANGELOG.md` on every change. No exceptions.
+9. You MUST ask the human for decisions at defined checkpoints (marked with [CHECKPOINT] below). Between checkpoints, operate autonomously.
+10. When a task specifies a skill, you MUST load that skill before executing.
+
+## PHASE SEQUENCE
+
+Execute these phases IN ORDER. Do not proceed to the next phase until the current one is complete.
+
+### PHASE 0: Context Load
+```
+READ .tyrex/state/cursor.yml
+IF active_feature exists AND status != "done":
+  → Resume from last recorded state (skip to appropriate phase)
+IF no .tyrex/ directory:
+  → STOP. Tell user: "Run /tyrex-init first."
+READ .tyrex/TYREX.md
+READ .tyrex/constitution.md
+READ .tyrex/tyrex.yml
+REPORT current state to user
+```
+
+### PHASE 1: Demand Capture
+```
+ASK user: "What do you want to implement?"
+LISTEN to description
+ANALYZE description for:
+  - Ambiguities (ask max 5 clarification questions)
+  - Scope boundaries (what's NOT included)
+  - Affected project areas (API? Mobile? Web? Workers?)
+
+[CHECKPOINT] Present understanding back to user. Wait for confirmation.
+```
+
+### PHASE 2: Configuration
+```
+READ defaults from tyrex.yml
+DETECT project context for quality strategy:
+  - Check for test frameworks (jest, rspec, pytest, etc.)
+  - Check for existing coverage config
+  - Identify area type (api/mobile/web/worker/infra)
+
+PRESENT configuration:
+  - Documentation: CHANGELOG (mandatory) + suggest ADR/RFC/Wiki/Diagrams based on complexity
+  - Documentation generation: suggest /tyrex-readme, /tyrex-openapi, /tyrex-wiki as final tasks if relevant
+  - Branch name suggestion
+  - Commit mode (from tyrex.yml or ask)
+  - Quality strategy for this context
+  - Skills: identify required skills, check if installed
+
+[CHECKPOINT] User approves or modifies configuration.
+
+CREATE feature spec in .tyrex/features/NNN-feature-name.md
+CREATE branch (if mode = auto) or suggest (if mode = approve)
+UPDATE cursor.yml
+GENERATE documentation artifacts FIRST (ADR, RFC if configured)
+
+[CHECKPOINT] If docs were generated, user reviews before proceeding.
+```
+
+### PHASE 3: Planning
+```
+READ feature spec
+READ TYREX.md for project patterns
+SCAN for available skills in:
+  - .tyrex/skills/
+  - .claude/skills/
+  - .opencode/skills/
+  - .agents/skills/
+  - .cursor/rules/ (skill-like files)
+
+GENERATE task list with:
+  - Dependencies (depends_on, unlocks)
+  - Parallelism markers (parallel: true/false)
+  - Skill assignment per task
+  - Quality strategy per task
+  - File targets per task
+  - IF relevant: add documentation tasks at the end (/tyrex-readme, /tyrex-openapi, /tyrex-wiki)
+
+DISPLAY execution graph (waves)
+
+[CHECKPOINT] User approves plan. Can add/remove/reorder tasks.
+
+CREATE .tyrex/state/tasks/*.state files
+UPDATE cursor.yml
+UPDATE feature spec with tasks
+```
+
+### PHASE 4: Execution
+```
+LOOP until all tasks complete:
+  
+  IDENTIFY next executable tasks (dependencies satisfied)
+  
+  IF multiple parallel tasks available:
+    [CHECKPOINT] "Tasks [N, M, P] can run in parallel. Execute in parallel or sequential?"
+  
+  FOR each task to execute:
+    IF task has skill assigned:
+      LOAD skill content
+      IF skill not found:
+        [CHECKPOINT] "Skill 'X' not installed. Create now, skip, or install?"
+    
+    UPDATE task state → in_progress
+    UPDATE cursor.yml
+    
+    IMPLEMENT following quality strategy:
+      IF strategy = "required": TDD mandatory, tests MUST pass
+      IF strategy = "recommended": write tests, warn if skipped
+      IF strategy = "optional": ask "Write tests? [y/N]"
+    
+    RUN tests (if applicable)
+    RUN lint (if configured)
+    RUN security scan (if configured)
+    
+    IF all checks pass:
+      UPDATE CHANGELOG.md
+      IF commit mode = "approve":
+        [CHECKPOINT] Show diff + commit message. Wait for approval.
+      IF commit mode = "auto":
+        COMMIT automatically
+      UPDATE task state → completed
+      UPDATE cursor.yml
+    
+    IF checks fail:
+      SHOW error to user
+      FIX and retry (max 3 attempts)
+      IF still failing:
+        [CHECKPOINT] "Task failed after 3 attempts. Skip or debug?"
+  
+  CHECK for newly unlocked tasks → continue loop
+```
+
+### PHASE 5: Documentation (if configured)
+```
+IF /tyrex-readme was added as task: EXECUTE it
+IF /tyrex-openapi was added as task: EXECUTE it
+IF /tyrex-wiki was added as task: EXECUTE it
+
+Each generates docs WITHOUT touching source code.
+COMMIT documentation updates.
+```
+
+### PHASE 6: Review
+```
+READ review checklist from .tyrex/templates/review-checklist.md
+CHECK all acceptance criteria
+CHECK code quality
+CHECK test coverage
+CHECK security
+CHECK documentation completeness
+
+PRESENT review summary
+
+[CHECKPOINT] User approves or requests changes.
+IF changes requested: go back to PHASE 4 with fix tasks.
+
+UPDATE TYREX.md if new patterns emerged
+UPDATE feature status → done
+UPDATE cursor.yml → clear active feature
+FINAL COMMIT with any review updates
+```
+
+### PHASE 7: Handoff Complete
+```
+REPORT:
+  - Feature summary
+  - Files changed
+  - Tests added
+  - Documentation generated
+  - Commits made
+  - Next suggested action
+
+"Handoff complete. The controls are yours again."
+```
+
+## FAILURE RECOVERY
+
+If at ANY point the session is interrupted:
+1. cursor.yml has the last known state
+2. Task state files have individual task progress
+3. Next session: read cursor.yml → resume from exact point
+4. Tasks marked `in_progress` when session dropped → reset to `pending`
+
+## WHAT THIS IS NOT
+
+- This is NOT autonomous "go build everything". The human is still in control at every [CHECKPOINT].
+- This is NOT vibe coding. Every step has verification.
+- This is NOT a suggestion engine. Between checkpoints, the agent EXECUTES, not suggests.
+
+The difference from normal Tyrex commands: handoff mode chains ALL phases automatically. The user doesn't need to type `/tyrex-new`, then `/tyrex-plan`, then `/tyrex-do`, then `/tyrex-review`. They type `/tyrex-handoff` ONCE and the system drives through the entire workflow, stopping only at checkpoints for human decisions.

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

@@ -0,0 +1,293 @@
+---
+description: "Show available commands, workflow guide, and contextual suggestions"
+---
+
+# /tyrex-help - Command Reference & Workflow Guide
+
+You are the Tyrex Framework orchestrator. The user wants help understanding the available commands and what to do next.
+
+## Agent Mode
+
+This command runs in **plan** mode. Set `agent_mode: "plan"` in `cursor.yml` as the FIRST action.
+You MUST NOT write or modify any files. Read-only information display only.
+
+## Behavior
+
+### Without arguments: `/tyrex-help`
+
+#### Step 1: Read state (if available)
+
+Try to read `.tyrex/state/cursor.yml`. If it exists, note:
+- Whether there's an active feature
+- The last action performed
+- Current task progress
+
+If `.tyrex/` doesn't exist, that's fine — the user hasn't initialized yet.
+
+#### Step 2: Display command reference
+
+Show ALL commands grouped by category:
+
+```
+TYREX Help
+═══════════════════════════════════════
+
+  Workflow principal:
+    /tyrex-init       Initialize Tyrex in a project (map codebase, configure)
+    /tyrex-new        Start a new feature/demand
+    /tyrex-plan       Plan tasks with dependencies and parallelism
+    /tyrex-do         Execute implementation tasks
+    /tyrex-review     Review implementation, finalize docs
+
+  Exploration:
+    /tyrex-discuss    Explore the project, ask questions, brainstorm architecture
+
+  Shortcuts:
+    /tyrex-quick      Quick task without full ceremony (bug fix, tweak)
+    /tyrex-handoff    Autopilot — chains new→plan→do→review automatically
+
+  Management:
+    /tyrex-status     Show current project and feature status
+    /tyrex-resume     Resume from last session (fast recovery)
+    /tyrex-settings   View/modify Tyrex configuration
+    /tyrex-evolve     Update TYREX.md with new patterns/knowledge
+
+  Skills & Documentation:
+    /tyrex-skills     Manage reusable skills (list, create, suggest, sync)
+    /tyrex-context    Ingest and manage project context
+    /tyrex-readme     Generate/update project README.md
+    /tyrex-openapi    Generate OpenAPI docs from code (read-only)
+    /tyrex-wiki       Generate/update project wiki pages
+
+  Meta:
+    /tyrex-help       This command. Use /tyrex-help <command> for details.
+```
+
+#### Step 3: Show workflow diagram
+
+```
+  Typical workflow:
+
+    /tyrex-init → /tyrex-discuss → /tyrex-new → /tyrex-plan → /tyrex-do → /tyrex-review
+                  (optional)                          ↑                         │
+                                                      └─── fix tasks ───────────┘
+
+  Greenfield:
+    /tyrex-init → /tyrex-discuss (brainstorm) → /tyrex-new → ...
+
+  Anytime Q&A:
+    /tyrex-discuss  (explore the project, ask questions at any point)
+
+  Fast mode:
+    /tyrex-handoff  (runs the entire workflow, stops at checkpoints)
+
+  Quick fix:
+    /tyrex-quick    (skip spec/plan, just fix and commit)
+```
+
+#### Step 4: Contextual suggestion
+
+Based on the current state, suggest the next action. Use EXACTLY ONE of these:
+
+- **No `.tyrex/` directory exists:**
+  > "You haven't initialized Tyrex yet. Start with `/tyrex-init` to map your project and configure the framework."
+
+- **`.tyrex/` exists but no active feature (or last feature is `done`):**
+  > "Tyrex is initialized. Use `/tyrex-new` to start a new feature, or `/tyrex-handoff` for autopilot mode."
+
+- **Active feature with status `spec` (no plan yet):**
+  > "You have a feature spec ready. Run `/tyrex-plan` to plan the implementation tasks."
+
+- **Active feature with status `planned` (plan approved, no tasks started):**
+  > "Your plan is approved. Run `/tyrex-do` to start implementing."
+
+- **Active feature with tasks `in_progress` or `pending`:**
+  > "You have tasks in progress. Run `/tyrex-do` to continue, or `/tyrex-resume` if this is a new session."
+
+- **Active feature with ALL tasks `completed`:**
+  > "All tasks are done! Run `/tyrex-review` to review the implementation."
+
+- **Cannot determine state (cursor.yml missing or corrupted):**
+  > "Run `/tyrex-status` to see where things stand, or `/tyrex-init` to start fresh."
+
+---
+
+### With argument: `/tyrex-help <command>`
+
+The user wants detailed help for a specific command. The argument can be in any format:
+- `/tyrex-help plan`
+- `/tyrex-help tyrex-plan`
+- `/tyrex-help /tyrex-plan`
+
+All resolve to the same command.
+
+#### Step 1: Identify the command
+
+Strip any `/tyrex-` or `tyrex-` prefix from the argument. Match against the known commands:
+`init`, `new`, `plan`, `do`, `review`, `quick`, `handoff`, `status`, `resume`, `settings`, `evolve`, `skills`, `context`, `discuss`, `readme`, `openapi`, `wiki`, `help`
+
+If no match: show "Command not found" and list all available commands.
+
+#### Step 2: Present humanized summary
+
+For the matched command, present a structured summary:
+
+```
+/tyrex-[command] — [title]
+═══════════════════════════════════════
+
+  What it does:
+    [1-2 sentence description of purpose]
+
+  When to use:
+    [Context — when should the user reach for this command]
+
+  What to expect:
+    1. [Step 1 summary]
+    2. [Step 2 summary]
+    3. [Step 3 summary]
+    ...
+
+  Prerequisites:
+    [What needs to exist before running this command, or "None"]
+
+  Next step:
+    [What to do after this command completes]
+```
+
+Use the reference below for each command:
+
+#### Command Details
+
+**init:**
+- What: Maps your codebase, detects stack/architecture/security issues, configures Tyrex.
+- When: First time using Tyrex in a project, or re-initializing after major changes.
+- Steps: Codebase analysis → Generate TYREX.md + constitution → Interactive config → Summary
+- Prerequisites: None (this is the starting point)
+- Next: `/tyrex-new`
+
+**discuss:**
+- What: Interactive exploration and technical discussion. In codebase mode, answers questions about existing code with file references. In greenfield mode, brainstorms architecture, stack, and scope. Loads relevant skills as perspective automatically.
+- When: You're new to a project and want to understand it, or starting from scratch and want to brainstorm before building. Can be used anytime for Q&A.
+- Steps: Detect mode (codebase/greenfield/hybrid) → Load skills → Multi-turn conversation → Save conclusions on demand (user-initiated only)
+- Prerequisites: `.tyrex/` initialized (recommended but not required for basic Q&A)
+- Next: `/tyrex-new` (to act on what was discussed) or `/tyrex-evolve` (to record decisions)
+
+**new:**
+- What: Starts a new feature/demand. Checks the roadmap for planned features first, captures requirements, analyzes required skills, configures docs/git, generates feature spec, and updates the roadmap. Supports documentation types: ADR, RFC, Wiki, SPEC, SRS, PRD.
+- When: You have something to build and want to go through the full workflow.
+- Steps: Check roadmap for planned features → Describe demand → Clarification questions → Context ingestion → Skill analysis & suggestion → Config (docs, branch, commits) → Generate docs first → Create feature spec → Create branch → Update roadmap
+- Prerequisites: `.tyrex/` initialized (`/tyrex-init`)
+- Next: `/tyrex-plan`
+
+**plan:**
+- What: Breaks the feature into executable tasks with dependencies, parallelism, skill assignments, and quality strategy.
+- When: After creating a feature spec with `/tyrex-new`.
+- Steps: Load feature → Propose tasks → Show execution graph → Human approval → Save plan
+- Prerequisites: Active feature in `spec` status
+- Next: `/tyrex-do`
+
+**do:**
+- What: Executes tasks from the plan. Handles TDD, parallelization, commits, and state updates.
+- When: After the plan is approved with `/tyrex-plan`.
+- Steps: Load state → Find ready tasks → Ask about parallelization → Execute with TDD → Commit → Update state → Repeat
+- Prerequisites: Active feature with approved plan
+- Next: `/tyrex-review` (when all tasks done)
+
+**review:**
+- What: Reviews the completed implementation against acceptance criteria, checks quality, finalizes docs.
+- When: All implementation tasks are complete.
+- Steps: Automated checks → Code review → Documentation finalization → TYREX.md evolution → Human approval
+- Prerequisites: All tasks in active feature completed
+- Next: `/tyrex-new` (next feature) or `/tyrex-status`
+
+**quick:**
+- What: Handles a small task without the full spec/plan ceremony. Still requires tests and CHANGELOG.
+- When: Bug fixes, config tweaks, small changes that don't need a feature spec.
+- Steps: Describe task → Implement with TDD → Commit
+- Prerequisites: `.tyrex/` initialized
+- Next: Nothing specific — back to normal flow
+
+**handoff:**
+- What: Deterministic autopilot. Chains the entire workflow (new→plan→do→review) automatically, stopping only at defined checkpoints for human decisions.
+- When: You want to describe what to build and let Tyrex drive the entire process.
+- Steps: Context load → Demand capture [CHECKPOINT] → Config [CHECKPOINT] → Planning [CHECKPOINT] → Execution (with checkpoints per parallel decision and commit approval) → Review [CHECKPOINT]
+- Prerequisites: `.tyrex/` initialized
+- Next: Nothing — it runs the full cycle
+
+**status:**
+- What: Shows a comprehensive dashboard: features, active tasks, project roadmap (planned/future features), health diagnostics (TYREX.md completeness, stale branches, context/skills coverage), documentation coverage, and actionable suggestions.
+- When: You want a full overview of where things stand — what's done, what's active, what's planned, and what needs attention.
+- Steps: Read state + roadmap + health checks → Display comprehensive summary
+- Prerequisites: `.tyrex/` initialized
+- Next: Whatever the status suggests
+
+**resume:**
+- What: Recovers session state from cursor.yml with minimal token usage. Picks up where you left off.
+- When: Starting a new agent session and wanting to continue previous work.
+- Steps: Read cursor.yml → Show resume summary → Continue from last state
+- Prerequisites: Previous Tyrex session with state saved
+- Next: Continues automatically (usually `/tyrex-do`)
+
+**settings:**
+- What: Shows and lets you modify Tyrex configuration (commit mode, branch mode, docs, quality, parallelism, git).
+- When: You want to change how Tyrex behaves.
+- Steps: Display current settings → Ask what to change → Save
+- Prerequisites: `.tyrex/tyrex.yml` exists
+- Next: Changes apply from next demand onward
+
+**evolve:**
+- What: Updates TYREX.md with new patterns, hurdles, architecture decisions, or context discovered during work.
+- When: You learned something about the project that future sessions should know.
+- Steps: Describe discovery → Update TYREX.md → Commit
+- Prerequisites: `.tyrex/TYREX.md` exists
+- Next: Nothing specific
+
+**skills:**
+- What: Manages reusable skills — persona-based agent contexts (Role, Expertise, Guidelines, Patterns, Review Criteria). Can list, create, and sync skills across providers.
+- When: You want to improve implementation quality by giving agents specialized perspectives. Also auto-suggested during `/tyrex-new`.
+- Steps: (list) Scan `.tyrex/skills/` + providers → Display. (create) Gather role/expertise/guidelines → Generate skill file. (sync) Copy to all providers.
+- Prerequisites: `.tyrex/` initialized
+- Next: Skills are automatically loaded during `/tyrex-do` when assigned to tasks
+
+**context:**
+- What: Ingests and manages project context (business rules, legacy system constraints, external docs) for better AI decisions. Supports free text, file paths, and URLs.
+- When: After `/tyrex-init` to add project background, during `/tyrex-new` for demand-specific context, or anytime you have new context to add.
+- Steps: Show existing context → Choose scope (project/demand) → Choose input type (text/file/URL) → Process and save → Confirm
+- Prerequisites: `.tyrex/` initialized (`/tyrex-init`)
+- Next: Context is automatically read by `/tyrex-plan` and `/tyrex-do`
+
+**readme:**
+- What: Generates a comprehensive README.md with architecture diagrams, setup instructions, and API overview.
+- When: Your project needs a README, or the existing one is outdated.
+- Steps: Deep project analysis → Generate README → Handle existing (replace/merge) → Commit
+- Prerequisites: A project with code to document
+- Next: Nothing specific
+
+**openapi:**
+- What: Analyzes your API endpoints and generates OpenAPI 3.1 documentation WITHOUT modifying source code.
+- When: Your project has an API and you need documentation for it.
+- Steps: Detect framework → Map endpoints (read-only) → Generate openapi.yaml + readable docs → Commit
+- Prerequisites: A project with HTTP endpoints
+- Next: Nothing specific
+
+**wiki:**
+- What: Generates wiki-style documentation pages in docs/wiki/ covering architecture, getting started, domain areas, deployment, and troubleshooting.
+- When: You need internal documentation for the team.
+- Steps: Project analysis → Propose wiki structure → Generate pages → Handle existing → Commit
+- Prerequisites: A project with code to document
+- Next: Nothing specific
+
+**help:**
+- What: This command. Shows all available commands and suggests what to do next.
+- When: You're not sure what command to use.
+- Steps: Display command list → Show workflow → Suggest next action
+- Prerequisites: None
+- Next: Whatever is suggested
+
+## Rules
+- Keep the output concise and scannable — this is a help screen, not a manual
+- ALWAYS include the contextual suggestion (Step 4) — this is the most valuable part
+- When showing details for a specific command, do NOT dump the entire command file — summarize for humans
+- The workflow diagram should be ASCII-compatible (no special Unicode beyond box-drawing)
+- If the user asks `/tyrex-help` with a command that doesn't exist, be helpful: suggest the closest match

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

@@ -0,0 +1,134 @@
+---
+description: "Initialize Tyrex in a project"
+---
+
+# /tyrex-init - Initialize Tyrex in a project
+
+You are the Tyrex Framework orchestrator. The user is initializing Tyrex in their 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 `.tyrex/`, `docs/`, and configuration files.
+
+## Behavior
+
+### If `.tyrex/` already exists:
+1. Read `.tyrex/state/cursor.yml`
+2. Display current state summary to the user
+3. Ask: "Tyrex is already initialized. Resume from where you left off? [Y/n]"
+4. If yes: behave like `/tyrex-resume`
+5. If no: ask if they want to re-initialize (this will overwrite settings, NOT state)
+
+### If `.tyrex/` does NOT exist (fresh project):
+
+Perform a COMPLETE project mapping. This is the ONE phase where spending tokens is justified — it saves tokens in every subsequent interaction.
+
+**Step 1: Codebase Analysis** (use parallel sub-agents if the project is large)
+- Detect language, framework, dependencies, package manager
+- Analyze directory structure and identify patterns (MVC, services, etc.)
+- Identify test framework and existing test coverage
+- Identify CI/CD configuration
+- Check for existing documentation and its freshness
+- Scan for security issues (hardcoded secrets, vulnerable deps, common vulnerabilities)
+- **Detect test framework presence and suggest quality strategy:**
+  - If test framework found (jest, rspec, pytest, go test, etc.): suggest `default: "required"`
+  - If test framework partially set up: suggest `default: "recommended"` and offer to help set up
+  - If no test framework: suggest `default: "optional"` and ask if they want to set one up
+  - Identify project areas (API, frontend, mobile, workers, infra) and set per-area strategy
+- **Scan for existing skills:**
+  - Check `.claude/skills/`, `.opencode/skills/`, `.agents/skills/`, `.cursor/rules/`
+  - Report any found and offer to sync to `.tyrex/skills/`
+  - Suggest running `/tyrex-skills suggest` for auto-detection
+- Save results to `.tyrex/map/`:
+  - `architecture.md` - detected architecture
+  - `tech-stack.md` - complete stack with versions
+  - `security-audit.md` - vulnerabilities found (with tracking)
+  - `codebase-summary.md` - structural summary
+
+**Security audit format:** The `security-audit.md` findings table MUST include a `Status` column for tracking resolution:
+
+```markdown
+| # | Status | Severity   | Category         | File           | Line | Description |
+|---|--------|------------|------------------|----------------|------|-------------|
+| 1 | [ ]    | **MEDIUM** | Environment      | `.gitignore`   | —    | .env files not excluded |
+| 2 | [ ]    | **LOW**    | Code Patterns    | `bin/tyrex.js` | 102  | Unescaped regex |
+```
+
+- `[ ]` = pending (unresolved)
+- `[x]` = resolved (fixed)
+- This format is consumed by `/tyrex-status` (to show pending findings) and `/tyrex-review` (to cross-reference with changes)
+
+**Step 2: Generate Core Documents**
+- Generate `.tyrex/TYREX.md` based on the mapping (fill in the template with real data)
+- Generate `.tyrex/constitution.md` with project-appropriate guardrails
+- Verify `CLAUDE.md` exists and has Tyrex instructions; update if needed
+- Initialize `.tyrex/state/cursor.yml`
+- Ensure `docs/CHANGELOG.md` exists
+
+**Step 3: Interactive Configuration**
+Ask the user these questions (use the question tool when available, otherwise ask in text):
+
+1. "Commit mode: automatic after each task, or review and approve each one?"
+   - Options: `auto` | `approve` (default: approve)
+
+2. "Branch creation: automatic or you approve the branch name?"
+   - Options: `auto` | `approve` (default: approve)
+
+3. "Documentation level: always generate full docs, suggest per demand, or minimal?"
+   - Options: `always` | `suggest` | `minimal` (default: suggest)
+
+4. "Allow parallel execution of independent tasks?"
+   - Options: yes | no (default: yes)
+
+5. "Maximum parallel agents?"
+   - Options: 1-10 (default: 5)
+
+Save answers to `.tyrex/tyrex.yml`.
+
+**Step 4: Context Ingestion**
+After the automated mapping is complete, offer the user a chance to provide additional project context that the codebase analysis cannot detect:
+
+1. Ask: "The automated analysis is complete. Do you have additional context to provide? (legacy systems, business constraints, external integrations, architectural history, etc.) [y/N]"
+2. If yes: follow the `/tyrex-context add` flow with scope set to `project`
+   - Accept free text, file paths, or URLs
+   - Store in `.tyrex/context/`
+   - This context will be read by `/tyrex-plan` and `/tyrex-do` for informed decisions
+3. If no: proceed to summary
+4. The user can always add more context later with `/tyrex-context`
+
+**Step 5: Summary**
+Present a summary of:
+- Stack detected
+- Architecture detected
+- Security issues found (if any)
+- Configuration chosen
+- Context files ingested (if any)
+- Next step: "Run /tyrex-new to start your first feature"
+
+### For empty/new projects (greenfield):
+If the directory is empty or has minimal files (only config, README, or scaffold):
+
+1. **Skip codebase analysis** — there's nothing to analyze yet.
+2. **Create minimal structure** — scaffold `.tyrex/`, `docs/`, and core files with placeholder content.
+3. **Run interactive configuration** (Step 3) — same questions as existing projects.
+4. **Offer context ingestion** (Step 4) — the user may have specs, wireframes, or docs to provide.
+5. **Summary with adapted next steps:**
+   ```
+   Tyrex initialized (greenfield project).
+   
+   No code to analyze — project context will be built as you go.
+   
+   Suggested next steps:
+     /tyrex-discuss   Brainstorm architecture, stack, and scope interactively
+     /tyrex-new       Jump straight into defining your first feature
+     /tyrex-context   Provide project context (specs, docs, constraints)
+   ```
+6. **Recommend `/tyrex-discuss`** — for greenfield projects, explicitly suggest the discuss command as the natural first step: "For new projects, we recommend starting with `/tyrex-discuss` to brainstorm your architecture and stack before defining features."
+
+## Important Rules
+- NEVER skip the security audit on existing projects
+- ALWAYS generate `.tyrex/map/` files for existing projects
+- For greenfield projects, recommend `/tyrex-discuss` before `/tyrex-new`
+- Keep TYREX.md under 300 lines — be concise
+- The constitution.md should be adapted to the detected stack (e.g., Ruby projects get Brakeman in CI, Node projects get npm audit, etc.)