Skip to main content
In Ooneex, you don’t hand an AI agent a vague prompt and hope for the best. You give it a spec: a small, structured YAML file that says exactly what the work is, why it exists, and how you’ll know it’s done. The agent reads that spec, implements it against your real module conventions, and checks its own work against the acceptance criteria you wrote. That spec is an issue — a modules/<module>/issues/<ID>.yml file. The whole workflow is three steps over that file:
1

Find — discover work

Audit a module’s source and surface concrete findings, each one a future issue.
2

Plan — turn requests into specs

Scaffold an issue and restructure it into context / goal / dod / dependencies, splitting big work into ordered sub-issues.
3

Fix — implement the spec

Hand each planned issue to the fixer for its module type; it writes the code, lints, satisfies the Definition of Done, and marks the issue Done.
Each step is an AI skill — /issue:found, /issue:plan, /issue:fix — that you invoke from your agent (Claude or Codex). They share one artifact, the issue file, so the spec flows from discovery to a finished, verified change.

​
The issue is the spec

Everything centers on one file per unit of work: 
modules/<module>/issues/<ID>.yml
The <ID> is generated for you — three uppercase letters and six digits, e.g. ABC-012345. A brand-new issue starts as a thin skeleton (see issue:create): 
id: "ABC-012345"
title: "Add authorization check to user delete route"
state: "Todo"
priority: "High"
description: |
  The DELETE /users/:id route never verifies the caller owns the account.
labels: []
Planning transforms that free-form skeleton into a real spec — four fields that read as an unambiguous brief: 
id: "ABC-012345"
title: "Add authorization check to user delete route"
state: "Planned"
priority: "High"
labels:
  - "Security"
context: |
  The DELETE /users/:id route deletes any account by id without checking
  the authenticated caller. Any logged-in user can delete any other user.
goal: |
  Add an ownership/authorization guard to the delete route so a user can
  only delete their own account (admins excepted).

  ## Technical Notes
  Reuse the existing permission service; do not hand-roll the check.

  ### Data Model
  - No schema change — authorization only.
dod: |
  - [ ] Non-owner, non-admin caller receives 403 on DELETE /users/:id
  - [ ] Owner can still delete their own account
  - [ ] Admin can delete any account
  - [ ] A test covers each of the three cases
dependencies: []
The four planning fields are the contract between you and the agent:
FieldWhat it holds
contextBackground and why the issue exists.
goalThe concrete work to do — plus optional Technical Notes and a module-type-specific structure block.
dodThe Definition of Done: acceptance criteria as - [ ] checkboxes. The fixer ticks these and only marks the issue Done when all pass.
dependenciesIDs of issues that must be completed first — how the loop sequences work.

​
Issue lifecycle

Every issue carries a state and a priority. State moves left to right as the spec travels through the workflow: 
Backlog → Todo → Planned → In Progress → In Review → Done
                                                  ↘ Cancelled
StateMeaning
Backlog / TodoCaptured but not yet a real spec — just a title and a description.
PlannedRestructured into context/goal/dod/dependencies — ready to implement. /issue:fix takes over here.
In Progress / In ReviewBeing implemented or reviewed.
DoneEvery dod checkbox is satisfied.
CancelledDropped.
Priority is one of Low, Medium, High, Urgent, inferred from severity (an exploitable vulnerability is Urgent; a missing test is Medium).

​
The workflow

​
1. Find — audit a module for issues

/issue:found infers which modules you mean from plain language (“audit the user and billing modules”, or just user), then runs a read-only audit of each module’s source. It never writes anything itself — it dispatches each module to the founder sub-agent that matches the module’s type and collects findings.
Module typeFounderWhat it audits
module (or none)module-issue-founderBackend domain module — security, performance, architecture, missing tests, code quality, database
apiapi-issue-founderThe above plus the HTTP/REST contract (status codes, DTOs, validation, versioning, pagination, rate limiting)
microservicemicroservice-issue-founderThe above plus boundaries, event contracts, idempotency, resilience, observability
spaspa-issue-founder + design-issue-founderClient-side SPA issues and UI/UX design issues
designdesign-issue-founderUI/UX design issues for the design system
Every finding cites concrete files and lines, gets a priority and a category label, and is handed straight to /issue:plan.
Prompt
Audit the user and billing modules for security and architecture issues.

​
2. Plan — turn a request into a spec

/issue:plan is the heart of spec-driven development. It takes either an existing issue (by ID) or a free-form description and produces a planned spec:
  1. Scaffold (for new work) — runs issue:create, inferring the target module from the domain nouns in your request (“user profile” → user, “checkout” → order).
  2. Restructure — replaces the free-form description with context / goal / dod / dependencies.
  3. Label and prioritize — extracts labels and sets state: "Planned" with an inferred priority.
  4. Split when needed — if the work spans multiple unrelated concerns, it breaks the parent into 3–7 ordered, self-contained sub-issues (each with the same four fields, wired together through dependencies) and deletes the parent.
Prompt
Plan an org create API and a billing settings page.
This single request becomes two specs in two different modules, sequenced if one depends on the other.

​
Specs are module-type aware

The goal’s technical block follows the module’s conventions, so the fixer gets the right vocabulary:
### Data Model — TypeORM relations with the exact field, decorator, and inverse side:
- `Organization.packs` → `@OneToMany(() => Pack, (p) => p.organization)` — one org has many packs
- `Pack.organization` → `@ManyToOne(() => Organization, (o) => o.packs)` — many packs belong to one org

​
3. Fix — implement the spec

/issue:fix resolves which issues to implement (by ID, by module, or by description), sequences them in dependency order, and dispatches each to the fixer sub-agent for its module type:
Module typeFixer
module (or none)module-issue-fixer
apiapi-issue-fixer
microservicemicroservice-issue-fixer
spaspa-issue-fixer
designdesign-issue-fixer
Each fixer reads the spec, implements the artifacts the goal calls for following Clean Architecture and the module’s conventions, runs bun run fmt and bun run lint from the monorepo root, checks off every satisfied dod box, and sets state: "Done" only when all of them pass.
Prompt
Implement ABC-012345.
All commands — including the ones the fixers run — execute from the monorepo root, never inside an individual module. See Monorepo.
When a goal describes a multi-step business process — conditional, reversible steps that should roll back together on failure — the fixer reaches for the @ooneex/workflow package instead of hand-rolling the orchestration.

​
The loop end to end

The three skills compose into a single thread from “something’s wrong” to “it’s fixed and verified”:
Prompt
Audit the user module, then plan and fix everything you find.
1

Find

/issue:found audits modules/user/ and surfaces a missing authorization check, citing the exact route file.
2

Plan

The finding flows into /issue:plan, which scaffolds ABC-012345, restructures it into a spec, labels it Security, sets it High / Planned.
3

Fix

/issue:fix hands ABC-012345 to module-issue-fixer, which adds the guard and the tests, lints, ticks every dod box, and marks the issue Done.
You stay in plain language the whole way — the structure lives in the issue file, and each agent reads it as a precise instruction rather than a guess.

​
Why specs

  • The agent never guesses the goal — goal and dod are explicit, so the work and the finish line are unambiguous.
  • Self-verifying — the fixer can only mark Done when every acceptance criterion is checked, so “done” means verified against the spec you wrote.
  • Sequenced automatically — dependencies let the loop implement issues in the right order, even across modules.
  • Convention-aware — specs carry the right structure for backend, SPA, or design modules, so generated code fits your codebase.
  • Reviewable before any code is written — planning happens read-only; you approve the spec, then execution writes the change.

​
Use with Claude and Codex

The skills ship with the CLI. Initialize them, then drive the whole workflow in natural language. 
ooneex claude:init
Prompt
Audit the billing module, plan the findings, and implement the
highest-priority one.

​
Next steps

issue:create

The command that scaffolds an issue’s YAML skeleton.

Monorepo

Where modules and their issues/ directories live.

Module overview

What a module is and how its type selects the founder and fixer.

Workflow component

Orchestrate reversible multi-step processes that a fix may call for.