Architecture

Overview

Romyq is a single Python process that coordinates between a planning provider, an execution provider, and a set of local state managers. Everything runs on your machine. The only outbound network traffic goes to whichever LLM providers you configure.

romyq
├── lifecycle/       core state machine
├── planning/        phase & task generation
├── execution/       task runner & provider bridge
├── governance/      rules evaluation
├── memory/          state file managers
├── readiness/       scoring aggregation
├── recommendation/  Continue / Pause / Review / Stop engine
├── ui/              Textual TUI (optional, pip install 'romyq[ui]')
└── commands/        operator steering interface

Core Components

Lifecycle Engine

The lifecycle engine is a state machine with eight stages. It transitions through stages in order, never skipping, never going backward. Stage transitions are recorded in .romyq/history.json.

Each project has exactly one active lifecycle at a time.

Planning

Planning is handled by the configured planning provider (DeepSeek R1 by default). Romyq sends a structured prompt containing the mission (mission.md), the current rules (.romyq/rules.json), the knowledge base (.romyq/knowledge.json), and current lifecycle stage. The provider responds with a phase or task plan in structured JSON format.

Romyq validates every plan against the rules before accepting it. Invalid plans are rejected and the provider is re-prompted with the rejection reason.

Governance

The governance system evaluates every proposed task against the rules in .romyq/rules.json before it enters the execution queue. Evaluation is synchronous — no task can bypass it.

A task fails governance when:

• It uses a technology explicitly excluded by a rule.
• It performs an action prohibited by a rule.
• It violates an ordering constraint (e.g., deploying before testing).

Failed tasks are replanned, not skipped. Every decision (accept or reject) is written to .romyq/decisions.json.

State Files

Key state files in .romyq/:

All files are human-readable. They can be inspected, edited, and version-controlled. The mission is stored in mission.md at the project root.

Readiness Scoring

The readiness score is a float between 0 and 100, recomputed after every task. Inputs:

Recommendation Engine

The recommendation engine reads the readiness score, lifecycle state, and done criteria to produce one of four outputs: Continue, Pause, Review, or Stop.

It is re-evaluated after every task completion and after every operator command.

Monitoring

romyq dashboard prints a text-based overview that answers the eight key lifecycle questions. Run it on demand in any terminal.

romyq ui launches a live Textual TUI that updates in real time alongside romyq run. Requires pip install 'romyq[ui]'.

Data Flow

operator command (romyq steer / romyq shell)
       ↓
  planning provider (DeepSeek) → phase / task plan
       ↓
  governance evaluation → rejected → replan
       ↓ approved
  execution provider (Claude Code) → task result
       ↓
  state update (history.json, knowledge.json)
       ↓
  readiness recompute
       ↓
  recommendation update (Continue / Pause / Review / Stop)
       ↓
  dashboard / ui refresh

Local-First Guarantees

• All state in .romyq/ is written atomically using temp-file swap.
• The lifecycle can be interrupted at any point and resumed from the last checkpoint.
• No data leaves the machine except LLM API calls, which go to your configured provider.