Lavish Editor

Lavish Editor helps agents turn rich HTML artifacts into collaborative human review surfaces. Whenever you are about to give user a complex response that will be easier to understand via a rich / interactive page, consider using Lavish Editor. First generate an interactive HTML artifact according to user request, then run npx -y lavish-axi <html-file> so the user can visually review it, annotate elements or selected text, queue prompts, and send feedback back through npx -y lavish-axi poll.

You do not need lavish-axi installed globally - invoke it with npx -y lavish-axi <html-file>. If lavish-axi output shows a follow-up command starting with lavish-axi, run it as npx -y lavish-axi ... instead.

Request

$ARGUMENTS

If the request above is non-empty, the user invoked /lavish explicitly - build an HTML artifact for that request now, following the workflow below. If it is empty, infer what to visualize from the conversation.

When to use

Use lavish-axi when the user asks for a visual artifact, HTML explainer, interactive prototype, review surface, product or technical plan, comparison, report, or browser-based feedback loop

Workflow

1. Create the HTML artifact (default location .lavish/<name>.html in the working directory).
2. Run npx -y lavish-axi <html-file> to open or resume a review session in the browser.
3. Run npx -y lavish-axi poll <html-file> to long-poll for the user's annotations, queued prompts, and browser-reported layout_warnings. The poll stays silent until the user acts or the real browser reports fresh layout warnings - leave it running, never kill it. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost.
4. If poll returns layout_warnings, fix overflow, clipped text, or overlapping unreadable content and re-check before involving the human.
5. Apply human feedback, then poll again with --agent-reply "<message>" to reply in the browser and keep the loop going.
6. Run npx -y lavish-axi end <html-file> when the review is finished.

Visual guidance

• Use visual hierarchy to make the most important decisions, risks, tradeoffs, and next actions obvious at a glance
• Use visual structure such as sections, cards, tables, diagrams, annotated snippets, and side-by-side comparisons instead of long prose
• Choose typography, spacing, color, and layout deliberately so the artifact has a clear point of view
• Prevent horizontal overflow at every nesting level: nested grid/flex children also need minmax(0, 1fr) tracks and min-width: 0, especially when badges, labels, or status text use wide pixel or monospace fonts; wrap, truncate, or contain long unbreakable text deliberately

Playbooks

Run npx -y lavish-axi playbook <id> for focused, detailed guidance on any of these. One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so read every playbook relevant to your artifact, not just one, for the best quality:

• diagram - Map relationships, flows, state, and architecture
• table - Turn dense records into scan-friendly review surfaces
• comparison - Show options, tradeoffs, and current vs target behavior
• plan - Explain a product or technical plan before implementation
• code - Render source code, code files, patches, PR diffs, and before/after code inside Lavish artifacts
• input - Must be used when the agent needs to collect user input on decisions, choices, preferences, triage, scope, or other structured feedback from within the artifact
• slides - Create a deliberate presentation when slides are requested

Commands & rules

• Run npx -y lavish-axi <html-file> to open or resume a Lavish Editor session
• Unless the user specifies another location, create HTML artifacts in the current working directory under .lavish/
• Lavish serves the html file through a local express.js server. If your html needs to reference other filesystem assets such as images, CSS, fonts, and local scripts, copy them into the same directory as the HTML file, then reference them with relative paths from that directory. Never prepend / to those asset paths - root paths won't work
• Run npx -y lavish-axi poll <html-file> to wait for user feedback or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix layout_warnings before involving the human. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost
• Run npx -y lavish-axi end <html-file> to end a session
• Run npx -y lavish-axi stop to shut down the background server (it also self-stops when idle or after the last session ends with nothing connected)
• Run npx -y lavish-axi playbook <playbook_id> for focused artifact guidance. One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so read every playbook relevant to the artifact, not just one, for the best quality
• Lavish does not auto-inject any design system - artifacts stay portable so they render identically when opened directly without lavish-axi running. Before writing any HTML, decide the design direction in this strict priority order, and only move to the next step when the current one truly yields nothing: (1) if the user asked for a specific look or named design system, use that; (2) otherwise you must first inspect the project the artifact is about - the subject or product whose content or UI it represents, which may differ from your current working directory - and match that project's design system: Tailwind or theme config, shared CSS variables or design tokens, component library, brand assets, or existing styled pages. If the artifact previews, proposes, or mocks a specific app's UI, render it in that app's own design system so it faithfully shows the product, even when you are running in a different repo; (3) only when both steps come up empty, use the Lavish-recommended Tailwind CSS browser runtime v4 + DaisyUI v5, available via CDN - run npx -y lavish-axi design for a copy-pasteable CDN snippet plus component reference, and prefer that CDN snippet over hand-writing styles unless explicitly instructed otherwise by the user. When you deliver the artifact, state which of the three design sources you used and why.
• Use lavish-axi when the user asks for a visual artifact, HTML explainer, interactive prototype, review surface, product or technical plan, comparison, report, or browser-based feedback loop

Code Review and Quality

Overview

Multi-dimensional code review with quality gates. Every change gets reviewed before merge — no exceptions. Review covers five axes: correctness, readability, architecture, security, and performance.

The approval standard: Approve a change when it definitely improves overall code health, even if it isn't perfect. Perfect code doesn't exist — the goal is continuous improvement. Don't block a change because it isn't exactly how you would have written it. If it improves the codebase and follows the project's conventions, approve it.

When to Use

• Before merging any PR or change
• After completing a feature implementation
• When another agent or model produced code you need to evaluate
• When refactoring existing code
• After any bug fix (review both the fix and the regression test)

The Five-Axis Review

Every review evaluates code across these dimensions:

1. Correctness

Does the code do what it claims to do?

• Does it match the spec or task requirements?
• Are edge cases handled (null, empty, boundary values)?
• Are error paths handled (not just the happy path)?
• Does it pass all tests? Are the tests actually testing the right things?
• Are there off-by-one errors, race conditions, or state inconsistencies?

2. Readability & Simplicity

Can another engineer (or agent) understand this code without the author explaining it?

• Are names descriptive and consistent with project conventions? (No temp, data, result without context)
• Is the control flow straightforward (avoid nested ternaries, deep callbacks)?
• Is the code organized logically (related code grouped, clear module boundaries)?
• Are there any "clever" tricks that should be simplified?
• Could this be done in fewer lines? (1000 lines where 100 suffice is a failure)
• Are abstractions earning their complexity? (Don't generalize until the third use case)
• Would comments help clarify non-obvious intent? (But don't comment obvious code.)
• Are there dead code artifacts: no-op variables (_unused), backwards-compat shims, or // removed comments?

3. Architecture

Does the change fit the system's design?

• Does it follow existing patterns or introduce a new one? If new, is it justified?
• Does it maintain clean module boundaries?
• Is there code duplication that should be shared?
• Are dependencies flowing in the right direction (no circular dependencies)?
• Is the abstraction level appropriate (not over-engineered, not too coupled)?

4. Security

For detailed security guidance, see security-and-hardening. Does the change introduce vulnerabilities?

• Is user input validated and sanitized?
• Are secrets kept out of code, logs, and version control?
• Is authentication/authorization checked where needed?
• Are SQL queries parameterized (no string concatenation)?
• Are outputs encoded to prevent XSS?
• Are dependencies from trusted sources with no known vulnerabilities?
• Is data from external sources (APIs, logs, user content, config files) treated as untrusted?
• Are external data flows validated at system boundaries before use in logic or rendering?

5. Performance

For detailed profiling and optimization, see performance-optimization. Does the change introduce performance problems?

• Any N+1 query patterns?
• Any unbounded loops or unconstrained data fetching?
• Any synchronous operations that should be async?
• Any unnecessary re-renders in UI components?
• Any missing pagination on list endpoints?
• Any large objects created in hot paths?

Change Sizing

Small, focused changes are easier to review, faster to merge, and safer to deploy. Target these sizes:

~100 lines changed   → Good. Reviewable in one sitting.
~300 lines changed   → Acceptable if it's a single logical change.
~1000 lines changed  → Too large. Split it.

What counts as "one change": A single self-contained modification that addresses one thing, includes related tests, and keeps the system functional after submission. One part of a feature — not the whole feature.

Splitting strategies when a change is too large:

When large changes are acceptable: Complete file deletions and automated refactoring where the reviewer only needs to verify intent, not every line.

Separate refactoring from feature work. A change that refactors existing code and adds new behavior is two changes — submit them separately. Small cleanups (variable renaming) can be included at reviewer discretion.

Change Descriptions

Every change needs a description that stands alone in version control history.

First line: Short, imperative, standalone. "Delete the FizzBuzz RPC" not "Deleting the FizzBuzz RPC." Must be informative enough that someone searching history can understand the change without reading the diff.

Body: What is changing and why. Include context, decisions, and reasoning not visible in the code itself. Link to bug numbers, benchmark results, or design docs where relevant. Acknowledge approach shortcomings when they exist.

Anti-patterns: "Fix bug," "Fix build," "Add patch," "Moving code from A to B," "Phase 1," "Add convenience functions."

Review Process

Step 1: Understand the Context

Before looking at code, understand the intent:

- What is this change trying to accomplish?
- What spec or task does it implement?
- What is the expected behavior change?

Step 2: Review the Tests First

This step is optional. If there is no test coverage, skip to the implementation review. But if tests exist, they are the best place to understand the intended behavior and edge cases. Tests reveal intent and coverage:

- Do tests exist for the change?
- Do they test behavior (not implementation details)?
- Are edge cases covered?
- Do tests have descriptive names?
- Would the tests catch a regression if the code changed?

Step 3: Review the Implementation

Walk through the code with the five axes in mind:

For each file changed:
1. Correctness: Does this code do what the test says it should?
2. Readability: Can I understand this without help?
3. Architecture: Does this fit the system?
4. Security: Any vulnerabilities?
5. Performance: Any bottlenecks?

Step 4: Categorize Findings

Label every comment with its severity so the author knows what's required vs optional:

This prevents authors from treating all feedback as mandatory and wasting time on optional suggestions.

Step 5: Verify the Verification

Check the author's verification story:

- What tests were run?
- Did the build pass?
- Was the change tested manually?
- Are there screenshots for UI changes?
- Is there a before/after comparison?

Dead Code Hygiene

After any refactoring or implementation change, check for orphaned code:

1. Identify code that is now unreachable or unused
2. List it explicitly
3. Ask before deleting: "Should I remove these now-unused elements: [list]?"

Don't leave dead code lying around — it confuses future readers and agents. But don't silently delete things you're not sure about. When in doubt, ask.

DEAD CODE IDENTIFIED:
- formatLegacyDate() in src/utils/date.ts — replaced by formatDate()
- OldTaskCard component in src/components/ — replaced by TaskCard
- LEGACY_API_URL constant in src/config.ts — no remaining references
→ Safe to remove these?

Review Speed

Slow reviews block entire teams. The cost of context-switching to review is less than the waiting cost imposed on others.

• Ideal cadence: Respond shortly after a review request arrives, unless deep in focused coding. A typical change should complete multiple review rounds in a single day
• Prioritize fast individual responses over quick final approval. Quick feedback reduces frustration even if multiple rounds are needed
• Large changes: Ask the author to split them rather than reviewing one massive changeset

Handling Disagreements

When resolving review disputes, apply this hierarchy:

1. Technical facts and data override opinions and preferences
2. Style guides are the absolute authority on style matters
3. Software design must be evaluated on engineering principles, not personal preference
4. Codebase consistency is acceptable if it doesn't degrade overall health

Don't accept "I'll clean it up later." Experience shows deferred cleanup rarely happens. Require cleanup before submission unless it's a genuine emergency. If surrounding issues can't be addressed in this change, require filing a bug with self-assignment.

Honesty in Review

When reviewing code — whether written by you, another agent, or a human:

• Don't rubber-stamp. "LGTM" without evidence of review helps no one.
• Don't soften real issues. "This might be a minor concern" when it's a bug that will hit production is dishonest.
• Quantify problems when possible. "This N+1 query will add ~50ms per item in the list" is better than "this could be slow."
• Push back on approaches with clear problems. Sycophancy is a failure mode in reviews. If the implementation has issues, say so directly and propose alternatives.
• Accept override gracefully. If the author has full context and disagrees, defer to their judgment. Comment on code, not people — reframe personal critiques to focus on the code itself.

Dependency Discipline

Part of code review is dependency review:

Before adding any dependency:

1. Does the existing stack solve this? (Often it does.)
2. How large is the dependency? (Check bundle impact.)
3. Is it actively maintained? (Check last commit, open issues.)
4. Does it have known vulnerabilities? (npm audit)
5. What's the license? (Must be compatible with the project.)

Rule: Prefer standard library and existing utilities over new dependencies. Every dependency is a liability.

The Review Checklist

## Review: [PR/Change title]

### Context
- [ ] I understand what this change does and why

### Correctness
- [ ] Change matches spec/task requirements
- [ ] Edge cases handled
- [ ] Error paths handled
- [ ] Tests cover the change adequately

### Readability
- [ ] Names are clear and consistent
- [ ] Logic is straightforward
- [ ] No unnecessary complexity

### Architecture
- [ ] Follows existing patterns
- [ ] No unnecessary coupling or dependencies
- [ ] Appropriate abstraction level

### Security
- [ ] No secrets in code
- [ ] Input validated at boundaries
- [ ] No injection vulnerabilities
- [ ] Auth checks in place
- [ ] External data sources treated as untrusted

### Performance
- [ ] No N+1 patterns
- [ ] No unbounded operations
- [ ] Pagination on list endpoints

### Verification
- [ ] Tests pass
- [ ] Build succeeds
- [ ] Manual verification done (if applicable)

### Verdict
- [ ] **Approve** — Ready to merge
- [ ] **Request changes** — Issues must be addressed

Common Rationalizations

Red Flags

• PRs merged without any review
• Review that only checks if tests pass (ignoring other axes)
• "LGTM" without evidence of actual review
• Security-sensitive changes without security-focused review
• Large PRs that are "too big to review properly" (split them)
• No regression tests with bug fix PRs
• Review comments without severity labels — makes it unclear what's required vs optional
• Accepting "I'll fix it later" — it never happens

Verification

After review is complete:

• All Critical issues are resolved
• All Important issues are resolved or explicitly deferred with justification
• Tests pass
• Build succeeds
• The verification story is documented (what changed, how it was verified)

Code Simplification

Overview

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"

When to Use

• After a feature is working and tests pass, but the implementation feels heavier than it needs to be
• During code review when readability or complexity issues are flagged
• When you encounter deeply nested logic, long functions, or unclear names
• When refactoring code written under time pressure
• When consolidating related logic scattered across files
• After merging changes that introduced duplication or inconsistency

When NOT to use:

• Code is already clean and readable — don't simplify for the sake of it
• You don't understand what the code does yet — comprehend before you simplify
• The code is performance-critical and the "simpler" version would be measurably slower
• You're about to rewrite the module entirely — simplifying throwaway code wastes effort

The Five Principles

1. Preserve Behavior Exactly

Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.

ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior?
→ Does this preserve the same side effects and ordering?
→ Do all existing tests still pass without modification?

2. Follow Project Conventions

Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:

1. Read CLAUDE.md / project conventions
2. Study how neighboring code handles similar patterns
3. Match the project's style for:
   - Import ordering and module system
   - Function declaration style
   - Naming conventions
   - Error handling patterns
   - Type annotation depth

Simplification that breaks project consistency is not simplification — it's churn.

3. Prefer Clarity Over Cleverness

Explicit code is better than compact code when the compact version requires a mental pause to parse.

// UNCLEAR: Dense ternary chain
const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';

// CLEAR: Readable mapping
function getStatusLabel(item: Item): string {
  if (item.isNew) return 'New';
  if (item.isUpdated) return 'Updated';
  if (item.isArchived) return 'Archived';
  return 'Active';
}

// UNCLEAR: Chained reduces with inline logic
const result = items.reduce((acc, item) => ({
  ...acc,
  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
}), {});

// CLEAR: Named intermediate step
const countById = new Map<string, number>();
for (const item of items) {
  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
}

4. Maintain Balance

Simplification has a failure mode: over-simplification. Watch for these traps:

• Inlining too aggressively — removing a helper that gave a concept a name makes the call site harder to read
• Combining unrelated logic — two simple functions merged into one complex function is not simpler
• Removing "unnecessary" abstraction — some abstractions exist for extensibility or testability, not complexity
• Optimizing for line count — fewer lines is not the goal; easier comprehension is

5. Scope to What Changed

Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.

The Simplification Process

Step 1: Understand Before Touching (Chesterton's Fence)

Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.

BEFORE SIMPLIFYING, ANSWER:
- What is this code's responsibility?
- What calls it? What does it call?
- What are the edge cases and error paths?
- Are there tests that define the expected behavior?
- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
- Check git blame: what was the original context for this code?

If you can't answer these, you're not ready to simplify. Read more context first.

Step 2: Identify Simplification Opportunities

Scan for these patterns — each one is a concrete signal, not a vague smell:

Structural complexity:

Naming and readability:

Redundancy:

Step 3: Apply Changes Incrementally

Make one simplification at a time. Run tests after each change. Submit refactoring changes separately from feature or bug fix changes. A PR that refactors and adds a feature is two PRs — split them.

FOR EACH SIMPLIFICATION:
1. Make the change
2. Run the test suite
3. If tests pass → commit (or continue to next simplification)
4. If tests fail → revert and reconsider

Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.

The Rule of 500: If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.

Step 4: Verify the Result

After all simplifications, step back and evaluate the whole:

COMPARE BEFORE AND AFTER:
- Is the simplified version genuinely easier to understand?
- Did you introduce any new patterns inconsistent with the codebase?
- Is the diff clean and reviewable?
- Would a teammate approve this change?

If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.

Language-Specific Guidance

TypeScript / JavaScript

// SIMPLIFY: Unnecessary async wrapper
// Before
async function getUser(id: string): Promise<User> {
  return await userService.findById(id);
}
// After
function getUser(id: string): Promise<User> {
  return userService.findById(id);
}

// SIMPLIFY: Verbose conditional assignment
// Before
let displayName: string;
if (user.nickname) {
  displayName = user.nickname;
} else {
  displayName = user.fullName;
}
// After
const displayName = user.nickname || user.fullName;

// SIMPLIFY: Manual array building
// Before
const activeUsers: User[] = [];
for (const user of users) {
  if (user.isActive) {
    activeUsers.push(user);
  }
}
// After
const activeUsers = users.filter((user) => user.isActive);

// SIMPLIFY: Redundant boolean return
// Before
function isValid(input: string): boolean {
  if (input.length > 0 && input.length < 100) {
    return true;
  }
  return false;
}
// After
function isValid(input: string): boolean {
  return input.length > 0 && input.length < 100;
}

React / JSX

// SIMPLIFY: Verbose conditional rendering
// Before
function UserBadge({ user }: Props) {
  if (user.isAdmin) {
    return <Badge variant="admin">Admin</Badge>;
  } else {
    return <Badge variant="default">User</Badge>;
  }
}
// After
function UserBadge({ user }: Props) {
  const variant = user.isAdmin ? 'admin' : 'default';
  const label = user.isAdmin ? 'Admin' : 'User';
  return <Badge variant={variant}>{label}</Badge>;
}

// SIMPLIFY: Prop drilling through intermediate components
// Before — consider whether context or composition solves this better.
// This is a judgment call — flag it, don't auto-refactor.

Common Rationalizations

Red Flags

• Simplification that requires modifying tests to pass (you likely changed behavior)
• "Simplified" code that is longer and harder to follow than the original
• Renaming things to match your preferences rather than project conventions
• Removing error handling because "it makes the code cleaner"
• Simplifying code you don't fully understand
• Batching many simplifications into one large, hard-to-review commit
• Refactoring code outside the scope of the current task without being asked

Verification

After completing a simplification pass:

• All existing tests pass without modification
• Build succeeds with no new warnings
• Linter/formatter passes (no style regressions)
• Each simplification is a reviewable, incremental change
• The diff is clean — no unrelated changes mixed in
• Simplified code follows project conventions (checked against CLAUDE.md or equivalent)
• No error handling was removed or weakened
• No dead code was left behind (unused imports, unreachable branches)
• A teammate or review agent would approve the change as a net improvement

Documentation and ADRs

Overview

Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.

When to Use

• Making a significant architectural decision
• Choosing between competing approaches
• Adding or changing a public API
• Shipping a feature that changes user-facing behavior
• Onboarding new team members (or agents) to the project
• When you find yourself explaining the same thing repeatedly

When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.

Architecture Decision Records (ADRs)

ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.

When to Write an ADR

• Choosing a framework, library, or major dependency
• Designing a data model or database schema
• Selecting an authentication strategy
• Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
• Choosing between build tools, hosting platforms, or infrastructure
• Any decision that would be expensive to reverse

ADR Template

Store ADRs in docs/decisions/ with sequential numbering:

# ADR-001: Use PostgreSQL for primary database

## Status
Accepted | Superseded by ADR-XXX | Deprecated

## Date
2025-01-15

## Context
We need a primary database for the task management application. Key requirements:
- Relational data model (users, tasks, teams with relationships)
- ACID transactions for task state changes
- Support for full-text search on task content
- Managed hosting available (for small team, limited ops capacity)

## Decision
Use PostgreSQL with Prisma ORM.

## Alternatives Considered

### MongoDB
- Pros: Flexible schema, easy to start with
- Cons: Our data is inherently relational; would need to manage relationships manually
- Rejected: Relational data in a document store leads to complex joins or data duplication

### SQLite
- Pros: Zero configuration, embedded, fast for reads
- Cons: Limited concurrent write support, no managed hosting for production
- Rejected: Not suitable for multi-user web application in production

### MySQL
- Pros: Mature, widely supported
- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
- Rejected: PostgreSQL is the better fit for our feature requirements

## Consequences
- Prisma provides type-safe database access and migration management
- We can use PostgreSQL's full-text search instead of adding Elasticsearch
- Team needs PostgreSQL knowledge (standard skill, low risk)
- Hosting on managed service (Supabase, Neon, or RDS)

ADR Lifecycle

PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)

• Don't delete old ADRs. They capture historical context.
• When a decision changes, write a new ADR that references and supersedes the old one.

Inline Documentation

When to Comment

Comment the why, not the what:

// BAD: Restates the code
// Increment counter by 1
counter += 1;

// GOOD: Explains non-obvious intent
// Rate limit uses a sliding window — reset counter at window boundary,
// not on a fixed schedule, to prevent burst attacks at window edges
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

When NOT to Comment

// Don't comment self-explanatory code
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// Don't leave TODO comments for things you should just do now
// TODO: add error handling  ← Just add it

// Don't leave commented-out code
// const oldImplementation = () => { ... }  ← Delete it, git has history

Document Known Gotchas

/**
 * IMPORTANT: This function must be called before the first render.
 * If called after hydration, it causes a flash of unstyled content
 * because the theme context isn't available during SSR.
 *
 * See ADR-003 for the full design rationale.
 */
export function initializeTheme(theme: Theme): void {
  // ...
}

README Structure

Every project should have a README that covers:

# Project Name

One-paragraph description of what this project does.

## Quick Start
1. Clone the repo
2. Install dependencies: `npm install`
3. Set up environment: `cp .env.example .env`
4. Run the dev server: `npm run dev`

## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Production build |
| `npm run lint` | Run linter |

## Architecture
Brief overview of the project structure and key design decisions.
Link to ADRs for details.

## Contributing
How to contribute, coding standards, PR process.

Changelog Maintenance

For shipped features:

# Changelog

## [1.2.0] - 2025-01-20
### Added
- Task sharing: users can share tasks with team members (#123)
- Email notifications for task assignments (#124)

### Fixed
- Duplicate tasks appearing when rapidly clicking create button (#125)

### Changed
- Task list now loads 50 items per page (was 20) for better UX (#126)

Documentation for Agents

Special consideration for AI agent context:

• AGENT.md / rules files — Document project conventions so agents follow them
• Spec files — Keep specs updated so agents build the right thing
• ADRs — Help agents understand why past decisions were made (prevents re-deciding)
• Inline gotchas — Prevent agents from falling into known traps

Common Rationalizations

Red Flags

• Architectural decisions with no written rationale
• Public APIs with no documentation or types
• README that doesn't explain how to run the project
• Commented-out code instead of deletion
• TODO comments that have been there for weeks
• No ADRs in a project with significant architectural choices
• Documentation that restates the code instead of explaining intent

Verification

After documenting:

• ADRs exist for all significant architectural decisions
• README covers quick start, commands, and architecture overview
• API functions have parameter and return type documentation
• Known gotchas are documented inline where they matter
• No commented-out code remains
• Rules files (AGENT.md etc.) are current and accurate

Electron Secure Boundary

Objective

Keep Ordinus secure by preserving the separation between privileged desktop code and UI code.

Rules

• Keep privileged work in Electron main process: filesystem, SQLite, child processes, provider runtimes, secrets, native dialogs, and OS integration.
• Keep renderer as UI-only React code. Do not import or use Node APIs, Electron APIs, SQLite clients, filesystem modules, or child process modules in renderer.
• Keep preload small and typed. Expose only purpose-built window.ordinus.* methods.
• Never expose raw ipcRenderer, electron, filesystem, process, database, or generic command execution APIs to renderer.
• Preserve nodeIntegration: false, contextIsolation: true, and sandbox: true unless the user explicitly asks for a security model redesign.
• Avoid third-party runtime imports in preload. In sandboxed preload, prefer type-only imports plus ipcRenderer.invoke.

Workflow

1. Identify which side of the boundary the change touches: main, preload, renderer, or shared contracts.
2. Move privileged behavior to main process services or IPC handlers.
3. Add the narrowest preload method needed for renderer.
4. Keep validation and trust decisions in main/shared, not renderer.
5. Run npm run typecheck, npm run lint, and npm run build.
6. For boundary changes, smoke test npm run dev or the packaged app.

Red Flags

• Renderer imports from electron, node:*, fs, path, child_process, better-sqlite3, or main-process modules.
• Preload exposes general-purpose methods such as invoke(channel, payload) or runCommand(command).
• IPC handlers trust renderer payloads without validation.
• A UI feature requires relaxing sandbox settings before simpler IPC design has been tried.

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time.

If a question can be answered by exploring the codebase, explore the codebase instead.

Idea Discovery

Act as a critical thinking partner, not an approval machine. Help the user understand whether an idea is worth pursuing, how it fits the existing product and architecture, and what decision they actually need to make.

Do not create an implementation plan or ADR unless the user explicitly asks for one.

Discovery Loop

Start by restating the idea at a high level and identifying the likely decision being explored.

Then explore the idea step by step using focused questions. Ask one question at a time.

For each question:

• Explain why the question matters.
• Provide your recommended answer or direction.
• Mention meaningful alternatives when relevant.
• Highlight risks, trade-offs, and hidden assumptions.
• Inspect existing code, docs, designs, issues, or ADRs when they can answer the question better than the user can.

Keep the conversation moving toward a clear decision. When the idea is vague, help shape it. When the idea is weak, say so clearly and explain why. When several valid paths exist, compare them directly.

Areas To Explore

Use the areas below when relevant. Do not force every area into every conversation.

Problem Clarity

• Identify the problem being solved.
• Test whether the problem is real or only interesting.
• Name who feels the pain and how often.
• Separate user pain from implementation curiosity.

Fit With Existing Work

• Check alignment with the current product direction.
• Look for existing features, docs, workflows, or architecture that already cover the need.
• Identify whether the idea adds useful structure or unnecessary complexity.
• Consider whether it fits the current runtime, UI, persistence, IPC, and workflow boundaries.

Alternative Solutions

• Compare simpler or manual options.
• Identify what can be postponed.
• Find the smallest useful version.
• Prefer reversible, observable changes when the problem is not yet proven.

User And Business Value

• Name who benefits and what changes for them after the idea exists.
• Test whether the value is obvious enough to justify product and maintenance cost.
• Classify the idea as core feature, supporting feature, infrastructure, or distraction.

Technical Direction

• Identify affected system areas such as data model, IPC contract, UI, runtime, provider adapter, database, or docs.
• Surface risky technical decisions and integration points.
• Validate assumptions against existing repository files before asking the user.
• Separate decisions that must be made now from details that can wait.

Decision Shaping

• State the actual decision being made.
• Compare the viable options.
• Recommend one option and explain why.
• Capture assumptions and trade-offs that would belong in an ADR if the user later asks for one.

Closing Summary

After enough exploration, summarize concisely:

• Refined idea
• Main options considered
• Recommended direction
• Key trade-offs
• Open questions
• ADR-worthy decisions

IPC Contract Design

Objective

Keep Ordinus IPC small, typed, explicit, and stable enough for the renderer to act as a safe UI over main-process capabilities.

Contract Shape

• Define channel names in src/shared/ipc.ts.
• Define shared request/response schemas and types in src/shared/contracts.ts.
• Register handlers in main process modules, not renderer.
• Expose renderer-facing methods through window.ordinus in preload.
• Use feature-shaped methods such as workspace.selectFolder() instead of generic transport methods.

Workflow

1. Name the user-facing capability before creating an IPC method.
2. Add or update shared types and Zod schemas.
3. Add the IPC channel constant.
4. Implement the main handler and validate untrusted input.
5. Add the narrow preload method that invokes that channel.
6. Consume the method in renderer through window.ordinus.
7. Run typecheck, lint, and build.

Guidelines

• Keep method names domain-oriented: app.getInfo, db.getStatus, workspace.selectFolder.
• Prefer one explicit method over a generic catch-all channel.
• Keep renderer errors user-readable and main errors diagnostic enough to debug.
• When IPC responses drive renderer status, empty states, or error copy, align user-visible naming with DESIGN.md.
• Do not add IPC for future features until there is an immediate caller.
• Do not return secrets, raw environment details, or unrestricted local paths unless the UI truly needs them.

Anti-Patterns

• window.ordinus.invoke(channel, payload).
• Passing raw command strings from renderer to main.
• Duplicating response shapes separately in main and renderer.
• Letting renderer decide privileged policy such as workspace boundaries or executable paths.

Ordinus UI System

Objective

Make Ordinus feel like a calm, practical command center for AI-assisted work.

Design System Source

Read DESIGN.md before changing renderer UI, layout, Tailwind styling, shadcn-style components, status surfaces, empty states, forms, task views, provider views, or user-facing product copy.

Treat DESIGN.md as the canonical source for visual tokens, component vocabulary, status language, density, and copy guidance. If it conflicts with AGENTS.md, the secure Electron boundary and product principles in AGENTS.md win.

Product Feel

• Work-focused, not marketing-focused.
• Clear status over decorative flourish.
• Dense enough for repeated use, but not crowded.
• User-facing text should describe product state and next actions, not internal implementation.
• Avoid turning the app into a generic chat page.
• Distinctive but calm. Ordinus should feel intentionally designed without becoming loud or theatrical.

Avoid Generic AI UI

• Do not default to generic assistant layouts, oversized prompt boxes, purple gradients, vague glowing panels, or decorative AI-themed backgrounds.
• Choose a clear product direction before styling: desktop command center, operational workspace, project cockpit, or agent control surface.
• Let the product context drive visual choices. Agent status, work progress, outputs, and attention states matter more than visual novelty.
• Use typography, spacing, color, and motion deliberately. The interface should feel polished because details are consistent, not because effects are abundant.
• Prefer subtle useful motion for state transitions, loading, reveal, and feedback. Avoid animations that distract from work.
• Make empty states, status labels, and action hierarchy feel designed, not placeholder-like.

UI Rules

• Align colors, typography, spacing, radius, status labels, and component naming with DESIGN.md.
• Use shadcn-style components and local reusable primitives.
• Prefer restrained cards for individual panels, not nested card-heavy layouts.
• Use lucide icons for recognizable actions.
• Keep typography readable and proportional to the UI surface.
• Avoid decorative gradients, orbs, bokeh, and oversized hero sections.
• Make status visible: planned, running, blocked, completed, needs attention.
• Avoid one-note palettes. Use a restrained base with purposeful accent colors for state and hierarchy.
• Match component density to the workflow: dashboards and work boards should be scan-friendly, not spacious landing pages.

Workflow

1. Read DESIGN.md and identify the workflow the UI supports.
2. Choose the smallest design-system component vocabulary that fits that workflow.
3. Put the primary state and next action above secondary details.
4. Use existing components before creating new primitives.
5. Keep labels concise and user-centered.
6. Check mobile/narrow and desktop layouts for overflow.
7. Run typecheck, lint, and build.

Copy Guidelines

• Say what the user can understand now.
• Avoid references to browser/session/localStorage/Electron internals unless the screen is explicitly diagnostic.
• Prefer "Workspace ready" over "IPC bridge initialized".
• Prefer "No work items yet" over "No database rows".

Provider Runtime Adapter

Objective

Keep local AI CLI integrations provider-neutral, observable, and owned by Electron main process.

Adapter Boundary

Provider adapters should hide provider-specific CLI details behind a shared runtime shape. Start with only the methods needed by current product behavior.

Preferred concepts:

• detect: determine whether the CLI is available.
• getAuthStatus: report whether the provider appears ready.
• startRun: launch one user-approved run.
• cancelRun: stop an active run.
• parseEvents: normalize stdout/stderr into observable run events when needed.

Do not implement all concepts until the product flow needs them.

Runtime Rules

• Run provider processes from Electron main process or a main-owned worker.
• Do not allow renderer to pass arbitrary shell commands.
• Store run state and events durably only after the run model is intentionally designed.
• Normalize provider behavior without erasing useful provider-specific diagnostics.
• Treat Codex and Claude as peers. Do not let the first provider shape the whole architecture.
• When provider state or events are shown in renderer UI, align user-visible statuses and event labels with the status vocabulary in DESIGN.md.

Workflow

1. Define the user action that needs provider runtime support.
2. Add the smallest provider-neutral interface needed for that action.
3. Implement detection or process behavior in main process.
4. Validate executable paths, workspace boundaries, and allowed arguments in main.
5. Stream or record events in a way the UI can explain clearly, using DESIGN.md status language for user-visible states.
6. Support cancellation before adding more automation.
7. Run typecheck, lint, build, and a runtime smoke test.

Red Flags

• Renderer sends raw command strings or CLI args.
• Provider-specific flags leak into UI state too early.
• Long-running process state exists only in memory when the UI needs to recover it.
• A provider integration assumes a single operating system.

shadcn Project Workflow

Objective

Use shadcn/ui as the standard path for reusable UI primitives while preserving Ordinus product direction.

Use this with ordinus-ui-system: this skill governs shadcn mechanics; ordinus-ui-system governs product feel. Use DESIGN.md as the canonical source for theme tokens, component vocabulary, status language, and UI density when changing shadcn-style components or renderer styling.

Required Workflow

1. Run or inspect project context before making component decisions: npm run ui:info
2. Read DESIGN.md before changing theme tokens, variants, component styling, status surfaces, or user-facing UI copy.
3. Check existing installed components before adding new ones.
4. Prefer shadcn CLI for registry components: npm run ui:add -- <component>
5. For unfamiliar components, get docs first: npx shadcn@latest docs <component>
6. For updates, preview before changing: npm run ui:add -- <component> --dry-run npm run ui:add -- <component> --diff <file>
7. Read files added by the CLI and fix imports, aliases, composition, and lint issues.
8. Run npm run ui:check, npm run typecheck, npm run lint, and npm run build.

Ordinus Defaults

• Package manager: npm.
• Electron app directory: app.
• Renderer alias: @renderer/*.
• Run shadcn and npm commands from app unless the user explicitly changes the project layout.
• UI components path: app/src/renderer/src/components/ui.
• Utility path: app/src/renderer/src/lib/utils.ts.
• Tailwind version: v3.
• Icon library: lucide-react.
• Product style: calm, operational, work-focused.

Critical Rules

• Align reusable variants and semantic CSS variables with DESIGN.md before adding one-off styling.
• Compose existing components before writing custom styled markup.
• Use built-in variants before custom class overrides.
• Use semantic tokens such as bg-background, text-muted-foreground, border, and bg-primary.
• Avoid raw Tailwind colors for product UI unless adding an intentional semantic token or variant.
• Use gap-* for spacing, not space-x-* or space-y-*.
• Use size-* for equal width and height.
• Use cn() for conditional class composition.
• Do not apply presets, overwrite components, or change global theme without explicit user approval.

Detailed References

Read only the relevant reference when needed:

• rules/styling.md for Tailwind and token rules.
• rules/composition.md for component composition and accessibility.
• rules/forms.md for forms and validation layouts.
• rules/icons.md for lucide icon usage.
• rules/base-vs-radix.md for primitive API differences.
• references/cli.md for shadcn CLI commands.
• references/customization.md for theming and CSS variables.

Notes

The official shadcn skill includes broader registry, MCP, asset, and eval infrastructure. Ordinus keeps a smaller adapted version focused on this Electron/Vite app.

SQLite Minimal Persistence

Objective

Use SQLite as durable local app state without designing product tables before the workflow model is clear.

Current Policy

• The minimum database starts with app_meta.
• Add new tables only when the product behavior needs durable state now.
• Avoid adding agent, task, provider, schedule, inbox, or run schemas speculatively.
• Keep secrets out of ordinary product tables unless a secure storage decision has been made.
• Treat SQLite as main-process owned. Renderer must access state only through typed IPC.

Workflow

1. Confirm the requested behavior truly needs persistence.
2. Check whether existing app_meta or settings-level storage is sufficient.
3. If a table is necessary, define the smallest schema that supports the current behavior.
4. Add Drizzle schema and bootstrap/migration logic together.
5. Keep data access behind main-process services.
6. Update db.getStatus only if the status surface needs to show new bootstrap information.
7. Run typecheck, lint, build, and a runtime smoke test that opens the app.

Design Guidance

• Prefer durable state for user-visible history, resumable work, and app configuration.
• Prefer filesystem storage for large artifacts and generated files, with database metadata later when needed.
• Prefer explicit timestamps and schema versioning for local migrations.
• Keep schema names product-oriented and stable.

Red Flags

• A table is added because a future module might need it.
• Renderer imports database code.
• Database writes are mixed into UI event handlers.
• Migration behavior is not exercised by opening the app.

Code Review and Quality

Overview

Multi-dimensional code review with quality gates. Every change gets reviewed before merge — no exceptions. Review covers five axes: correctness, readability, architecture, security, and performance.

The approval standard: Approve a change when it definitely improves overall code health, even if it isn't perfect. Perfect code doesn't exist — the goal is continuous improvement. Don't block a change because it isn't exactly how you would have written it. If it improves the codebase and follows the project's conventions, approve it.

When to Use

• Before merging any PR or change
• After completing a feature implementation
• When another agent or model produced code you need to evaluate
• When refactoring existing code
• After any bug fix (review both the fix and the regression test)

The Five-Axis Review

Every review evaluates code across these dimensions:

1. Correctness

Does the code do what it claims to do?

• Does it match the spec or task requirements?
• Are edge cases handled (null, empty, boundary values)?
• Are error paths handled (not just the happy path)?
• Does it pass all tests? Are the tests actually testing the right things?
• Are there off-by-one errors, race conditions, or state inconsistencies?

2. Readability & Simplicity

Can another engineer (or agent) understand this code without the author explaining it?

• Are names descriptive and consistent with project conventions? (No temp, data, result without context)
• Is the control flow straightforward (avoid nested ternaries, deep callbacks)?
• Is the code organized logically (related code grouped, clear module boundaries)?
• Are there any "clever" tricks that should be simplified?
• Could this be done in fewer lines? (1000 lines where 100 suffice is a failure)
• Are abstractions earning their complexity? (Don't generalize until the third use case)
• Would comments help clarify non-obvious intent? (But don't comment obvious code.)
• Are there dead code artifacts: no-op variables (_unused), backwards-compat shims, or // removed comments?

3. Architecture

Does the change fit the system's design?

• Does it follow existing patterns or introduce a new one? If new, is it justified?
• Does it maintain clean module boundaries?
• Is there code duplication that should be shared?
• Are dependencies flowing in the right direction (no circular dependencies)?
• Is the abstraction level appropriate (not over-engineered, not too coupled)?

4. Security

For detailed security guidance, see security-and-hardening. Does the change introduce vulnerabilities?

• Is user input validated and sanitized?
• Are secrets kept out of code, logs, and version control?
• Is authentication/authorization checked where needed?
• Are SQL queries parameterized (no string concatenation)?
• Are outputs encoded to prevent XSS?
• Are dependencies from trusted sources with no known vulnerabilities?
• Is data from external sources (APIs, logs, user content, config files) treated as untrusted?
• Are external data flows validated at system boundaries before use in logic or rendering?

5. Performance

For detailed profiling and optimization, see performance-optimization. Does the change introduce performance problems?

• Any N+1 query patterns?
• Any unbounded loops or unconstrained data fetching?
• Any synchronous operations that should be async?
• Any unnecessary re-renders in UI components?
• Any missing pagination on list endpoints?
• Any large objects created in hot paths?

Change Sizing

Small, focused changes are easier to review, faster to merge, and safer to deploy. Target these sizes:

~100 lines changed   → Good. Reviewable in one sitting.
~300 lines changed   → Acceptable if it's a single logical change.
~1000 lines changed  → Too large. Split it.

What counts as "one change": A single self-contained modification that addresses one thing, includes related tests, and keeps the system functional after submission. One part of a feature — not the whole feature.

Splitting strategies when a change is too large:

When large changes are acceptable: Complete file deletions and automated refactoring where the reviewer only needs to verify intent, not every line.

Separate refactoring from feature work. A change that refactors existing code and adds new behavior is two changes — submit them separately. Small cleanups (variable renaming) can be included at reviewer discretion.

Change Descriptions

Every change needs a description that stands alone in version control history.

First line: Short, imperative, standalone. "Delete the FizzBuzz RPC" not "Deleting the FizzBuzz RPC." Must be informative enough that someone searching history can understand the change without reading the diff.

Body: What is changing and why. Include context, decisions, and reasoning not visible in the code itself. Link to bug numbers, benchmark results, or design docs where relevant. Acknowledge approach shortcomings when they exist.

Anti-patterns: "Fix bug," "Fix build," "Add patch," "Moving code from A to B," "Phase 1," "Add convenience functions."

Review Process

Step 1: Understand the Context

Before looking at code, understand the intent:

- What is this change trying to accomplish?
- What spec or task does it implement?
- What is the expected behavior change?

Step 2: Review the Tests First

This step is optional. If there is no test coverage, skip to the implementation review. But if tests exist, they are the best place to understand the intended behavior and edge cases. Tests reveal intent and coverage:

- Do tests exist for the change?
- Do they test behavior (not implementation details)?
- Are edge cases covered?
- Do tests have descriptive names?
- Would the tests catch a regression if the code changed?

Step 3: Review the Implementation

Walk through the code with the five axes in mind:

For each file changed:
1. Correctness: Does this code do what the test says it should?
2. Readability: Can I understand this without help?
3. Architecture: Does this fit the system?
4. Security: Any vulnerabilities?
5. Performance: Any bottlenecks?

Step 4: Categorize Findings

Label every comment with its severity so the author knows what's required vs optional:

This prevents authors from treating all feedback as mandatory and wasting time on optional suggestions.

Step 5: Verify the Verification

Check the author's verification story:

- What tests were run?
- Did the build pass?
- Was the change tested manually?
- Are there screenshots for UI changes?
- Is there a before/after comparison?

Dead Code Hygiene

After any refactoring or implementation change, check for orphaned code:

1. Identify code that is now unreachable or unused
2. List it explicitly
3. Ask before deleting: "Should I remove these now-unused elements: [list]?"

Don't leave dead code lying around — it confuses future readers and agents. But don't silently delete things you're not sure about. When in doubt, ask.

DEAD CODE IDENTIFIED:
- formatLegacyDate() in src/utils/date.ts — replaced by formatDate()
- OldTaskCard component in src/components/ — replaced by TaskCard
- LEGACY_API_URL constant in src/config.ts — no remaining references
→ Safe to remove these?

Review Speed

Slow reviews block entire teams. The cost of context-switching to review is less than the waiting cost imposed on others.

• Ideal cadence: Respond shortly after a review request arrives, unless deep in focused coding. A typical change should complete multiple review rounds in a single day
• Prioritize fast individual responses over quick final approval. Quick feedback reduces frustration even if multiple rounds are needed
• Large changes: Ask the author to split them rather than reviewing one massive changeset

Handling Disagreements

When resolving review disputes, apply this hierarchy:

1. Technical facts and data override opinions and preferences
2. Style guides are the absolute authority on style matters
3. Software design must be evaluated on engineering principles, not personal preference
4. Codebase consistency is acceptable if it doesn't degrade overall health

Don't accept "I'll clean it up later." Experience shows deferred cleanup rarely happens. Require cleanup before submission unless it's a genuine emergency. If surrounding issues can't be addressed in this change, require filing a bug with self-assignment.

Honesty in Review

When reviewing code — whether written by you, another agent, or a human:

• Don't rubber-stamp. "LGTM" without evidence of review helps no one.
• Don't soften real issues. "This might be a minor concern" when it's a bug that will hit production is dishonest.
• Quantify problems when possible. "This N+1 query will add ~50ms per item in the list" is better than "this could be slow."
• Push back on approaches with clear problems. Sycophancy is a failure mode in reviews. If the implementation has issues, say so directly and propose alternatives.
• Accept override gracefully. If the author has full context and disagrees, defer to their judgment. Comment on code, not people — reframe personal critiques to focus on the code itself.

Dependency Discipline

Part of code review is dependency review:

Before adding any dependency:

1. Does the existing stack solve this? (Often it does.)
2. How large is the dependency? (Check bundle impact.)
3. Is it actively maintained? (Check last commit, open issues.)
4. Does it have known vulnerabilities? (npm audit)
5. What's the license? (Must be compatible with the project.)

Rule: Prefer standard library and existing utilities over new dependencies. Every dependency is a liability.

The Review Checklist

## Review: [PR/Change title]

### Context
- [ ] I understand what this change does and why

### Correctness
- [ ] Change matches spec/task requirements
- [ ] Edge cases handled
- [ ] Error paths handled
- [ ] Tests cover the change adequately

### Readability
- [ ] Names are clear and consistent
- [ ] Logic is straightforward
- [ ] No unnecessary complexity

### Architecture
- [ ] Follows existing patterns
- [ ] No unnecessary coupling or dependencies
- [ ] Appropriate abstraction level

### Security
- [ ] No secrets in code
- [ ] Input validated at boundaries
- [ ] No injection vulnerabilities
- [ ] Auth checks in place
- [ ] External data sources treated as untrusted

### Performance
- [ ] No N+1 patterns
- [ ] No unbounded operations
- [ ] Pagination on list endpoints

### Verification
- [ ] Tests pass
- [ ] Build succeeds
- [ ] Manual verification done (if applicable)

### Verdict
- [ ] **Approve** — Ready to merge
- [ ] **Request changes** — Issues must be addressed

Common Rationalizations

Red Flags

• PRs merged without any review
• Review that only checks if tests pass (ignoring other axes)
• "LGTM" without evidence of actual review
• Security-sensitive changes without security-focused review
• Large PRs that are "too big to review properly" (split them)
• No regression tests with bug fix PRs
• Review comments without severity labels — makes it unclear what's required vs optional
• Accepting "I'll fix it later" — it never happens

Verification

After review is complete:

• All Critical issues are resolved
• All Important issues are resolved or explicitly deferred with justification
• Tests pass
• Build succeeds
• The verification story is documented (what changed, how it was verified)

Code Simplification

Overview

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"

When to Use

• After a feature is working and tests pass, but the implementation feels heavier than it needs to be
• During code review when readability or complexity issues are flagged
• When you encounter deeply nested logic, long functions, or unclear names
• When refactoring code written under time pressure
• When consolidating related logic scattered across files
• After merging changes that introduced duplication or inconsistency

When NOT to use:

• Code is already clean and readable — don't simplify for the sake of it
• You don't understand what the code does yet — comprehend before you simplify
• The code is performance-critical and the "simpler" version would be measurably slower
• You're about to rewrite the module entirely — simplifying throwaway code wastes effort

The Five Principles

1. Preserve Behavior Exactly

Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.

ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior?
→ Does this preserve the same side effects and ordering?
→ Do all existing tests still pass without modification?

2. Follow Project Conventions

Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:

1. Read CLAUDE.md / project conventions
2. Study how neighboring code handles similar patterns
3. Match the project's style for:
   - Import ordering and module system
   - Function declaration style
   - Naming conventions
   - Error handling patterns
   - Type annotation depth

Simplification that breaks project consistency is not simplification — it's churn.

3. Prefer Clarity Over Cleverness

Explicit code is better than compact code when the compact version requires a mental pause to parse.

// UNCLEAR: Dense ternary chain
const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';

// CLEAR: Readable mapping
function getStatusLabel(item: Item): string {
  if (item.isNew) return 'New';
  if (item.isUpdated) return 'Updated';
  if (item.isArchived) return 'Archived';
  return 'Active';
}

// UNCLEAR: Chained reduces with inline logic
const result = items.reduce((acc, item) => ({
  ...acc,
  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
}), {});

// CLEAR: Named intermediate step
const countById = new Map<string, number>();
for (const item of items) {
  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
}

4. Maintain Balance

Simplification has a failure mode: over-simplification. Watch for these traps:

• Inlining too aggressively — removing a helper that gave a concept a name makes the call site harder to read
• Combining unrelated logic — two simple functions merged into one complex function is not simpler
• Removing "unnecessary" abstraction — some abstractions exist for extensibility or testability, not complexity
• Optimizing for line count — fewer lines is not the goal; easier comprehension is

5. Scope to What Changed

Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.

The Simplification Process

Step 1: Understand Before Touching (Chesterton's Fence)

Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.

BEFORE SIMPLIFYING, ANSWER:
- What is this code's responsibility?
- What calls it? What does it call?
- What are the edge cases and error paths?
- Are there tests that define the expected behavior?
- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
- Check git blame: what was the original context for this code?

If you can't answer these, you're not ready to simplify. Read more context first.

Step 2: Identify Simplification Opportunities

Scan for these patterns — each one is a concrete signal, not a vague smell:

Structural complexity:

Naming and readability:

Redundancy:

Step 3: Apply Changes Incrementally

Make one simplification at a time. Run tests after each change. Submit refactoring changes separately from feature or bug fix changes. A PR that refactors and adds a feature is two PRs — split them.

FOR EACH SIMPLIFICATION:
1. Make the change
2. Run the test suite
3. If tests pass → commit (or continue to next simplification)
4. If tests fail → revert and reconsider

Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.

The Rule of 500: If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.

Step 4: Verify the Result

After all simplifications, step back and evaluate the whole:

COMPARE BEFORE AND AFTER:
- Is the simplified version genuinely easier to understand?
- Did you introduce any new patterns inconsistent with the codebase?
- Is the diff clean and reviewable?
- Would a teammate approve this change?

If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.

Language-Specific Guidance

TypeScript / JavaScript

// SIMPLIFY: Unnecessary async wrapper
// Before
async function getUser(id: string): Promise<User> {
  return await userService.findById(id);
}
// After
function getUser(id: string): Promise<User> {
  return userService.findById(id);
}

// SIMPLIFY: Verbose conditional assignment
// Before
let displayName: string;
if (user.nickname) {
  displayName = user.nickname;
} else {
  displayName = user.fullName;
}
// After
const displayName = user.nickname || user.fullName;

// SIMPLIFY: Manual array building
// Before
const activeUsers: User[] = [];
for (const user of users) {
  if (user.isActive) {
    activeUsers.push(user);
  }
}
// After
const activeUsers = users.filter((user) => user.isActive);

// SIMPLIFY: Redundant boolean return
// Before
function isValid(input: string): boolean {
  if (input.length > 0 && input.length < 100) {
    return true;
  }
  return false;
}
// After
function isValid(input: string): boolean {
  return input.length > 0 && input.length < 100;
}

React / JSX

// SIMPLIFY: Verbose conditional rendering
// Before
function UserBadge({ user }: Props) {
  if (user.isAdmin) {
    return <Badge variant="admin">Admin</Badge>;
  } else {
    return <Badge variant="default">User</Badge>;
  }
}
// After
function UserBadge({ user }: Props) {
  const variant = user.isAdmin ? 'admin' : 'default';
  const label = user.isAdmin ? 'Admin' : 'User';
  return <Badge variant={variant}>{label}</Badge>;
}

// SIMPLIFY: Prop drilling through intermediate components
// Before — consider whether context or composition solves this better.
// This is a judgment call — flag it, don't auto-refactor.

Common Rationalizations

Red Flags

• Simplification that requires modifying tests to pass (you likely changed behavior)
• "Simplified" code that is longer and harder to follow than the original
• Renaming things to match your preferences rather than project conventions
• Removing error handling because "it makes the code cleaner"
• Simplifying code you don't fully understand
• Batching many simplifications into one large, hard-to-review commit
• Refactoring code outside the scope of the current task without being asked

Verification

After completing a simplification pass:

• All existing tests pass without modification
• Build succeeds with no new warnings
• Linter/formatter passes (no style regressions)
• Each simplification is a reviewable, incremental change
• The diff is clean — no unrelated changes mixed in
• Simplified code follows project conventions (checked against CLAUDE.md or equivalent)
• No error handling was removed or weakened
• No dead code was left behind (unused imports, unreachable branches)
• A teammate or review agent would approve the change as a net improvement

Documentation and ADRs

Overview

Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.

When to Use

• Making a significant architectural decision
• Choosing between competing approaches
• Adding or changing a public API
• Shipping a feature that changes user-facing behavior
• Onboarding new team members (or agents) to the project
• When you find yourself explaining the same thing repeatedly

When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.

Architecture Decision Records (ADRs)

ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.

When to Write an ADR

• Choosing a framework, library, or major dependency
• Designing a data model or database schema
• Selecting an authentication strategy
• Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
• Choosing between build tools, hosting platforms, or infrastructure
• Any decision that would be expensive to reverse

ADR Template

Store ADRs in docs/decisions/ with sequential numbering:

# ADR-001: Use PostgreSQL for primary database

## Status
Accepted | Superseded by ADR-XXX | Deprecated

## Date
2025-01-15

## Context
We need a primary database for the task management application. Key requirements:
- Relational data model (users, tasks, teams with relationships)
- ACID transactions for task state changes
- Support for full-text search on task content
- Managed hosting available (for small team, limited ops capacity)

## Decision
Use PostgreSQL with Prisma ORM.

## Alternatives Considered

### MongoDB
- Pros: Flexible schema, easy to start with
- Cons: Our data is inherently relational; would need to manage relationships manually
- Rejected: Relational data in a document store leads to complex joins or data duplication

### SQLite
- Pros: Zero configuration, embedded, fast for reads
- Cons: Limited concurrent write support, no managed hosting for production
- Rejected: Not suitable for multi-user web application in production

### MySQL
- Pros: Mature, widely supported
- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
- Rejected: PostgreSQL is the better fit for our feature requirements

## Consequences
- Prisma provides type-safe database access and migration management
- We can use PostgreSQL's full-text search instead of adding Elasticsearch
- Team needs PostgreSQL knowledge (standard skill, low risk)
- Hosting on managed service (Supabase, Neon, or RDS)

ADR Lifecycle

PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)

• Don't delete old ADRs. They capture historical context.
• When a decision changes, write a new ADR that references and supersedes the old one.

Inline Documentation

When to Comment

Comment the why, not the what:

// BAD: Restates the code
// Increment counter by 1
counter += 1;

// GOOD: Explains non-obvious intent
// Rate limit uses a sliding window — reset counter at window boundary,
// not on a fixed schedule, to prevent burst attacks at window edges
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

When NOT to Comment

// Don't comment self-explanatory code
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// Don't leave TODO comments for things you should just do now
// TODO: add error handling  ← Just add it

// Don't leave commented-out code
// const oldImplementation = () => { ... }  ← Delete it, git has history

Document Known Gotchas

/**
 * IMPORTANT: This function must be called before the first render.
 * If called after hydration, it causes a flash of unstyled content
 * because the theme context isn't available during SSR.
 *
 * See ADR-003 for the full design rationale.
 */
export function initializeTheme(theme: Theme): void {
  // ...
}

README Structure

Every project should have a README that covers:

# Project Name

One-paragraph description of what this project does.

## Quick Start
1. Clone the repo
2. Install dependencies: `npm install`
3. Set up environment: `cp .env.example .env`
4. Run the dev server: `npm run dev`

## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Production build |
| `npm run lint` | Run linter |

## Architecture
Brief overview of the project structure and key design decisions.
Link to ADRs for details.

## Contributing
How to contribute, coding standards, PR process.

Changelog Maintenance

For shipped features:

# Changelog

## [1.2.0] - 2025-01-20
### Added
- Task sharing: users can share tasks with team members (#123)
- Email notifications for task assignments (#124)

### Fixed
- Duplicate tasks appearing when rapidly clicking create button (#125)

### Changed
- Task list now loads 50 items per page (was 20) for better UX (#126)

Documentation for Agents

Special consideration for AI agent context:

• AGENT.md / rules files — Document project conventions so agents follow them
• Spec files — Keep specs updated so agents build the right thing
• ADRs — Help agents understand why past decisions were made (prevents re-deciding)
• Inline gotchas — Prevent agents from falling into known traps

Common Rationalizations

Red Flags

• Architectural decisions with no written rationale
• Public APIs with no documentation or types
• README that doesn't explain how to run the project
• Commented-out code instead of deletion
• TODO comments that have been there for weeks
• No ADRs in a project with significant architectural choices
• Documentation that restates the code instead of explaining intent

Verification

After documenting:

• ADRs exist for all significant architectural decisions
• README covers quick start, commands, and architecture overview
• API functions have parameter and return type documentation
• Known gotchas are documented inline where they matter
• No commented-out code remains
• Rules files (AGENT.md etc.) are current and accurate

Electron Secure Boundary

Objective

Keep Ordinus secure by preserving the separation between privileged desktop code and UI code.

Rules

• Keep privileged work in Electron main process: filesystem, SQLite, child processes, provider runtimes, secrets, native dialogs, and OS integration.
• Keep renderer as UI-only React code. Do not import or use Node APIs, Electron APIs, SQLite clients, filesystem modules, or child process modules in renderer.
• Keep preload small and typed. Expose only purpose-built window.ordinus.* methods.
• Never expose raw ipcRenderer, electron, filesystem, process, database, or generic command execution APIs to renderer.
• Preserve nodeIntegration: false, contextIsolation: true, and sandbox: true unless the user explicitly asks for a security model redesign.
• Avoid third-party runtime imports in preload. In sandboxed preload, prefer type-only imports plus ipcRenderer.invoke.

Workflow

1. Identify which side of the boundary the change touches: main, preload, renderer, or shared contracts.
2. Move privileged behavior to main process services or IPC handlers.
3. Add the narrowest preload method needed for renderer.
4. Keep validation and trust decisions in main/shared, not renderer.
5. Run npm run typecheck, npm run lint, and npm run build.
6. For boundary changes, smoke test npm run dev or the packaged app.

Red Flags

• Renderer imports from electron, node:*, fs, path, child_process, better-sqlite3, or main-process modules.
• Preload exposes general-purpose methods such as invoke(channel, payload) or runCommand(command).
• IPC handlers trust renderer payloads without validation.
• A UI feature requires relaxing sandbox settings before simpler IPC design has been tried.

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time.

If a question can be answered by exploring the codebase, explore the codebase instead.

Idea Discovery

Act as a critical thinking partner, not an approval machine. Help the user understand whether an idea is worth pursuing, how it fits the existing product and architecture, and what decision they actually need to make.

Do not create an implementation plan or ADR unless the user explicitly asks for one.

Discovery Loop

Start by restating the idea at a high level and identifying the likely decision being explored.

Then explore the idea step by step using focused questions. Ask one question at a time.

For each question:

• Explain why the question matters.
• Provide your recommended answer or direction.
• Mention meaningful alternatives when relevant.
• Highlight risks, trade-offs, and hidden assumptions.
• Inspect existing code, docs, designs, issues, or ADRs when they can answer the question better than the user can.

Keep the conversation moving toward a clear decision. When the idea is vague, help shape it. When the idea is weak, say so clearly and explain why. When several valid paths exist, compare them directly.

Areas To Explore

Use the areas below when relevant. Do not force every area into every conversation.

Problem Clarity

• Identify the problem being solved.
• Test whether the problem is real or only interesting.
• Name who feels the pain and how often.
• Separate user pain from implementation curiosity.

Fit With Existing Work

• Check alignment with the current product direction.
• Look for existing features, docs, workflows, or architecture that already cover the need.
• Identify whether the idea adds useful structure or unnecessary complexity.
• Consider whether it fits the current runtime, UI, persistence, IPC, and workflow boundaries.

Alternative Solutions

• Compare simpler or manual options.
• Identify what can be postponed.
• Find the smallest useful version.
• Prefer reversible, observable changes when the problem is not yet proven.

User And Business Value

• Name who benefits and what changes for them after the idea exists.
• Test whether the value is obvious enough to justify product and maintenance cost.
• Classify the idea as core feature, supporting feature, infrastructure, or distraction.

Technical Direction

• Identify affected system areas such as data model, IPC contract, UI, runtime, provider adapter, database, or docs.
• Surface risky technical decisions and integration points.
• Validate assumptions against existing repository files before asking the user.
• Separate decisions that must be made now from details that can wait.

Decision Shaping

• State the actual decision being made.
• Compare the viable options.
• Recommend one option and explain why.
• Capture assumptions and trade-offs that would belong in an ADR if the user later asks for one.

Closing Summary

After enough exploration, summarize concisely:

• Refined idea
• Main options considered
• Recommended direction
• Key trade-offs
• Open questions
• ADR-worthy decisions

IPC Contract Design

Objective

Keep Ordinus IPC small, typed, explicit, and stable enough for the renderer to act as a safe UI over main-process capabilities.

Contract Shape

• Define channel names in src/shared/ipc.ts.
• Define shared request/response schemas and types in src/shared/contracts.ts.
• Register handlers in main process modules, not renderer.
• Expose renderer-facing methods through window.ordinus in preload.
• Use feature-shaped methods such as workspace.selectFolder() instead of generic transport methods.

Workflow

1. Name the user-facing capability before creating an IPC method.
2. Add or update shared types and Zod schemas.
3. Add the IPC channel constant.
4. Implement the main handler and validate untrusted input.
5. Add the narrow preload method that invokes that channel.
6. Consume the method in renderer through window.ordinus.
7. Run typecheck, lint, and build.

Guidelines

• Keep method names domain-oriented: app.getInfo, db.getStatus, workspace.selectFolder.
• Prefer one explicit method over a generic catch-all channel.
• Keep renderer errors user-readable and main errors diagnostic enough to debug.
• When IPC responses drive renderer status, empty states, or error copy, align user-visible naming with DESIGN.md.
• Do not add IPC for future features until there is an immediate caller.
• Do not return secrets, raw environment details, or unrestricted local paths unless the UI truly needs them.

Anti-Patterns

• window.ordinus.invoke(channel, payload).
• Passing raw command strings from renderer to main.
• Duplicating response shapes separately in main and renderer.
• Letting renderer decide privileged policy such as workspace boundaries or executable paths.

Ordinus UI System

Objective

Make Ordinus feel like a calm, practical command center for AI-assisted work.

Design System Source

Read DESIGN.md before changing renderer UI, layout, Tailwind styling, shadcn-style components, status surfaces, empty states, forms, task views, provider views, or user-facing product copy.

Treat DESIGN.md as the canonical source for visual tokens, component vocabulary, status language, density, and copy guidance. If it conflicts with AGENTS.md, the secure Electron boundary and product principles in AGENTS.md win.

Product Feel

• Work-focused, not marketing-focused.
• Clear status over decorative flourish.
• Dense enough for repeated use, but not crowded.
• User-facing text should describe product state and next actions, not internal implementation.
• Avoid turning the app into a generic chat page.
• Distinctive but calm. Ordinus should feel intentionally designed without becoming loud or theatrical.

Avoid Generic AI UI

• Do not default to generic assistant layouts, oversized prompt boxes, purple gradients, vague glowing panels, or decorative AI-themed backgrounds.
• Choose a clear product direction before styling: desktop command center, operational workspace, project cockpit, or agent control surface.
• Let the product context drive visual choices. Agent status, work progress, outputs, and attention states matter more than visual novelty.
• Use typography, spacing, color, and motion deliberately. The interface should feel polished because details are consistent, not because effects are abundant.
• Prefer subtle useful motion for state transitions, loading, reveal, and feedback. Avoid animations that distract from work.
• Make empty states, status labels, and action hierarchy feel designed, not placeholder-like.

UI Rules

• Align colors, typography, spacing, radius, status labels, and component naming with DESIGN.md.
• Use shadcn-style components and local reusable primitives.
• Prefer restrained cards for individual panels, not nested card-heavy layouts.
• Use lucide icons for recognizable actions.
• Keep typography readable and proportional to the UI surface.
• Avoid decorative gradients, orbs, bokeh, and oversized hero sections.
• Make status visible: planned, running, blocked, completed, needs attention.
• Avoid one-note palettes. Use a restrained base with purposeful accent colors for state and hierarchy.
• Match component density to the workflow: dashboards and work boards should be scan-friendly, not spacious landing pages.

Workflow

1. Read DESIGN.md and identify the workflow the UI supports.
2. Choose the smallest design-system component vocabulary that fits that workflow.
3. Put the primary state and next action above secondary details.
4. Use existing components before creating new primitives.
5. Keep labels concise and user-centered.
6. Check mobile/narrow and desktop layouts for overflow.
7. Run typecheck, lint, and build.

Copy Guidelines

• Say what the user can understand now.
• Avoid references to browser/session/localStorage/Electron internals unless the screen is explicitly diagnostic.
• Prefer "Workspace ready" over "IPC bridge initialized".
• Prefer "No work items yet" over "No database rows".

Provider Runtime Adapter

Objective

Keep local AI CLI integrations provider-neutral, observable, and owned by Electron main process.

Adapter Boundary

Provider adapters should hide provider-specific CLI details behind a shared runtime shape. Start with only the methods needed by current product behavior.

Preferred concepts:

• detect: determine whether the CLI is available.
• getAuthStatus: report whether the provider appears ready.
• startRun: launch one user-approved run.
• cancelRun: stop an active run.
• parseEvents: normalize stdout/stderr into observable run events when needed.

Do not implement all concepts until the product flow needs them.

Runtime Rules

• Run provider processes from Electron main process or a main-owned worker.
• Do not allow renderer to pass arbitrary shell commands.
• Store run state and events durably only after the run model is intentionally designed.
• Normalize provider behavior without erasing useful provider-specific diagnostics.
• Treat Codex and Claude as peers. Do not let the first provider shape the whole architecture.
• When provider state or events are shown in renderer UI, align user-visible statuses and event labels with the status vocabulary in DESIGN.md.

Workflow

1. Define the user action that needs provider runtime support.
2. Add the smallest provider-neutral interface needed for that action.
3. Implement detection or process behavior in main process.
4. Validate executable paths, workspace boundaries, and allowed arguments in main.
5. Stream or record events in a way the UI can explain clearly, using DESIGN.md status language for user-visible states.
6. Support cancellation before adding more automation.
7. Run typecheck, lint, build, and a runtime smoke test.

Red Flags

• Renderer sends raw command strings or CLI args.
• Provider-specific flags leak into UI state too early.
• Long-running process state exists only in memory when the UI needs to recover it.
• A provider integration assumes a single operating system.

shadcn Project Workflow

Objective

Use shadcn/ui as the standard path for reusable UI primitives while preserving Ordinus product direction.

Use this with ordinus-ui-system: this skill governs shadcn mechanics; ordinus-ui-system governs product feel. Use DESIGN.md as the canonical source for theme tokens, component vocabulary, status language, and UI density when changing shadcn-style components or renderer styling.

Required Workflow

1. Run or inspect project context before making component decisions: npm run ui:info
2. Read DESIGN.md before changing theme tokens, variants, component styling, status surfaces, or user-facing UI copy.
3. Check existing installed components before adding new ones.
4. Prefer shadcn CLI for registry components: npm run ui:add -- <component>
5. For unfamiliar components, get docs first: npx shadcn@latest docs <component>
6. For updates, preview before changing: npm run ui:add -- <component> --dry-run npm run ui:add -- <component> --diff <file>
7. Read files added by the CLI and fix imports, aliases, composition, and lint issues.
8. Run npm run ui:check, npm run typecheck, npm run lint, and npm run build.

Ordinus Defaults

• Package manager: npm.
• Electron app directory: app.
• Renderer alias: @renderer/*.
• Run shadcn and npm commands from app unless the user explicitly changes the project layout.
• UI components path: app/src/renderer/src/components/ui.
• Utility path: app/src/renderer/src/lib/utils.ts.
• Tailwind version: v3.
• Icon library: lucide-react.
• Product style: calm, operational, work-focused.

Critical Rules

• Align reusable variants and semantic CSS variables with DESIGN.md before adding one-off styling.
• Compose existing components before writing custom styled markup.
• Use built-in variants before custom class overrides.
• Use semantic tokens such as bg-background, text-muted-foreground, border, and bg-primary.
• Avoid raw Tailwind colors for product UI unless adding an intentional semantic token or variant.
• Use gap-* for spacing, not space-x-* or space-y-*.
• Use size-* for equal width and height.
• Use cn() for conditional class composition.
• Do not apply presets, overwrite components, or change global theme without explicit user approval.

Detailed References

Read only the relevant reference when needed:

• rules/styling.md for Tailwind and token rules.
• rules/composition.md for component composition and accessibility.
• rules/forms.md for forms and validation layouts.
• rules/icons.md for lucide icon usage.
• rules/base-vs-radix.md for primitive API differences.
• references/cli.md for shadcn CLI commands.
• references/customization.md for theming and CSS variables.

Notes

The official shadcn skill includes broader registry, MCP, asset, and eval infrastructure. Ordinus keeps a smaller adapted version focused on this Electron/Vite app.

SQLite Minimal Persistence

Objective

Use SQLite as durable local app state without designing product tables before the workflow model is clear.

Current Policy

• The minimum database starts with app_meta.
• Add new tables only when the product behavior needs durable state now.
• Avoid adding agent, task, provider, schedule, inbox, or run schemas speculatively.
• Keep secrets out of ordinary product tables unless a secure storage decision has been made.
• Treat SQLite as main-process owned. Renderer must access state only through typed IPC.

Workflow

1. Confirm the requested behavior truly needs persistence.
2. Check whether existing app_meta or settings-level storage is sufficient.
3. If a table is necessary, define the smallest schema that supports the current behavior.
4. Add Drizzle schema and bootstrap/migration logic together.
5. Keep data access behind main-process services.
6. Update db.getStatus only if the status surface needs to show new bootstrap information.
7. Run typecheck, lint, build, and a runtime smoke test that opens the app.

Design Guidance

• Prefer durable state for user-visible history, resumable work, and app configuration.
• Prefer filesystem storage for large artifacts and generated files, with database metadata later when needed.
• Prefer explicit timestamps and schema versioning for local migrations.
• Keep schema names product-oriented and stable.

Red Flags

• A table is added because a future module might need it.
• Renderer imports database code.
• Database writes are mixed into UI event handlers.
• Migration behavior is not exercised by opening the app.