Agentic Workflow

Introduction

Copy-paste recipes: what to type, in what order, for each common job. Each step says what you type and what happens. Your only manual work is answering questions and approving gates.

Agent quickstart is the manual per-module walkthrough if you would rather drive every step yourself.

One-time setup, once per clone:

pnpm setup:agent      # docker + db + mcp + deps

First time on the platform? Let it onboard you. It interviews you for requirements, then delegates the build to the right agents:

/start                        # or: /start I want a tournaments feature

Implement a feature end to end

/add-feature <ticket, work-order path, or a plain description>

The flow stops for you twice:

1. Answer the grill questions. The agent asks about scope edges, module ownership, and data-model choices.
2. Approve the plan. You get the exact surface - packages, tables, contracts, events - plus a task breakdown. Say "approved", or correct it first. Nothing is edited before this.
3. Implementation, tests, parallel review (contract-reviewer, security-reviewer, quality-reviewer) and a QA end-to-end run happen agent-side, with fixes looped in automatically.
4. When it reports green, run /create-pr, then confirm the push when asked.

Have a fuzzy idea rather than a ticket? Start with the domain expert, then feed its output into step 1:

ask the expert agent: turn "<your idea>" into requirements with acceptance criteria
/add-feature <the resulting spec>

Review code

Everyday review of your branch, cheap enough for capped plans:

/review                       # current branch vs dev
/review 123                   # a pull request by number
/review --base stage          # a different base branch

Output is paste-ready line comments, an acceptance-criteria check, and a one-sentence go/no-go. Nothing is posted or edited - you paste the comments you agree with.

Deep sweep of a large or risky change set, token-heavy:

/oss-review                   # one reviewer per applicable dimension
/oss-review --agents 6        # force the fan-out width
/oss-review --fix             # also apply the fixes in the working tree

Scaffold by hand

When you want to drive implementation yourself instead of /add-feature:

/scaffold-module tournaments                     # new add-on, registered + working list route
/scaffold-route tournaments POST /tournaments    # add a route stub
/scaffold-plugin my-overlay                      # overlay extension under extensions/

Fill in the // AGENT: implement here regions, then after any schema or contract edit:

/regen                           # migrations + openapi + catalog
/verify                          # typecheck + lint + unit tests, same as CI
/verify --filter @openora/core   # scoped to one package, faster

/verify does not just run the checks - it fixes what fails, or explains why a test needs updating, and never reports done on red.

Ship it

/pre-pr                       # full local gate, including the drift check CI runs
/create-pr                    # commit, push (asks first), open the PR

Ask before you build

Read-only inspection through the oss-dev MCP tools. Any agent can answer these directly:

what modules exist?                       # list-modules
does a route for X already exist?         # list-routes / query-openapi
what does the wallet schema look like?    # get-drizzle-schema module=wallet
would table "tournament_entry" collide?   # propose-table-change

Change the agents themselves

1. Edit the source under .rulesync/ - rules/, subagents/, skills/. Never the generated mirrors (AGENTS.md, CLAUDE.md, .claude/, .github/).
2. Run pnpm sync:agents.
3. New or changed subagents load in a fresh session, not the current one.

Ground rules

• Agents are read-only until you approve a plan. They never commit unless asked, and never push without a per-action "yes".
• Every state-changing action must leave an audit entry. No audit entry, not done.
• pnpm verify green before any PR. CI also rejects generated-artifact drift, which /pre-pr catches locally.