Concepts

Overview

Understanding the eight core concepts gives you a complete picture of how Romyq works. These concepts map directly to the eight lifecycle stages.

Mission

A mission is a concise statement of what a project is supposed to accomplish. It is defined during romyq init (or by editing the file directly) and stored in mission.md at the project root.

Build a REST API for internal analytics with authentication and PostgreSQL.

Every planning decision is evaluated against the mission. If a proposed phase or task does not serve the mission, the planning provider is expected to reject it.

Lifecycle

The lifecycle is the top-level structure that organizes a project's work. It has eight stages:

A lifecycle runs until the operator issues romyq stop or the recommendation engine emits Stop and the operator confirms.

Phases

Phases are the ordered segments of work within a lifecycle. Each phase has:

• A name and description
• A set of tasks
• Done criteria (what must be true to consider the phase complete)
• Dependencies on predecessor phases

Phases do not overlap. Phase 3 cannot start until Phase 2 is complete. Done criteria are checked before advancing, not when tasks finish.

Example phases for an Intermediate complexity project:

01 Setup        → install dependencies, configure environment
02 Database     → schema, migrations, ORM
03 Auth         → JWT, middleware, protected routes
04 Testing      → unit, integration, coverage
05 Deployment   → CI, containerization, production config

Tasks

A task is the unit of work within a phase. Each task has:

• A title and description
• A capability tag (what the project gains when this task is complete)
• A list of tasks it unblocks
• A reference to which phase it belongs to

Tasks are generated by the planning provider during stage 04. They are re-plannable. If a task violates the project rules, it is replanned before execution begins.

Governance

Governance is the system that enforces project rules before execution. Rules are stored in .romyq/rules.json as plain text and managed via the CLI:

romyq rules add "Always use PostgreSQL for relational data."
romyq rules add "Tests are required for every source file."
romyq rules add "No SQLite anywhere in the codebase."
romyq rules list

Every proposed task is evaluated against the rules before it enters the execution queue. Evaluation is synchronous — tasks that fail are replanned, not skipped.

See the Governance page for full details.

Memory

Romyq maintains several state files across sessions in .romyq/:

All files are stored locally, in plain text or JSON. They are readable, diffable, and can be version-controlled. The mission itself is stored in mission.md at the project root.

See the Knowledge page for more on how the knowledge layer works.

Readiness

Readiness is a score from 0 to 100 computed after every task. It is not a percentage of tasks complete. It is a weighted aggregate across four categories:

A score of 100 means all done criteria are satisfied, all required capabilities are present, and there are no active governance violations.

See the Readiness page for the scoring details.

Recommendations

After every task (and after every operator command), Romyq evaluates the project state and emits one of four recommendations:

The recommendation is advisory. The operator decides what to do with it. Romyq does not stop execution automatically.