nerve-workspace/CONVENTIONS.md

Nerve Workspace Conventions

This document defines coding and workflow conventions for the nerve-workspace (~/.uncaged-nerve). All roles (planner, coder, reviewer, tester) should reference this file.

Language & Paradigm

Functional-first

Use function + type, not class + interface.

// ✅ Good
type Signal = { senseId: string; value: unknown; ts: number };
function createSignal(senseId: string, value: unknown): Signal { ... }

// ❌ Bad
class Signal implements ISignal { ... }

Rules

Rule	Description
type over interface	All type definitions use type
function over class	Pure functions + closures, no class
No this	Functions must not depend on this context
No inheritance	No extends, implements, abstract
Composition over inheritance	Use function composition
No optional properties	Use T | null instead of ?:
No dynamic import()	Always static top-level import
async/await only	Never .then() chains

Exceptions

Classes allowed when required by a library (e.g. Drizzle sqliteTable) or Error subclasses.

Naming

Type	Style	Example
Files	kebab-case	signal-bus.ts
Types	PascalCase	SignalBus
Functions/variables	camelCase	createSignalBus
Constants	UPPER_SNAKE	MAX_RETRY_COUNT

Error Handling

• Use Result<T, E> for expected failures
• throw only for unrecoverable bugs
• No try-catch for flow control

type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

Workflow Structure

Each workflow follows the multi-file pattern:

workflows/<name>/
  index.ts          — WorkflowDefinition default export (thin entry point)
  build.ts          — factory function with dependency injection
  moderator.ts      — moderator function + WorkflowMeta type
  roles/
    <role>/
      index.ts      — build function + meta schema
      prompt.ts     — prompt pure function (string template)
  package.json      — with esbuild build script
  tsconfig.json

Role Implementation Patterns

Pattern	When to use	Example
createCursorRole	Needs file system access (code generation, planning)	planner, coder
createHermesRole	Needs shell + tools (testing, reviewing)	tester, reviewer
createLlmRole	Pure LLM reasoning, no tools	analysis roles
createRole(hermesAdapter, …)	Agent role with LLM + shell (branch/commit/push from thread context)	solve-issue committer, publish
Direct Role<Meta>	No LLM needed, scripted logic	thin wrappers only

Meta Convention

Meta is a routing signal only — one boolean per role:

• { ready: boolean } — planner
• { done: boolean } — coder
• { approved: boolean } — reviewer
• { passed: boolean } — tester
• { committed: boolean } — committer (solve-issue: branch created, pushed)
• { success: boolean } — publish (PR opened)

Standard Flow

planner → coder → reviewer → tester → committer → END

• Reviewer rejection → back to coder (within MAX_CODER_ITERATIONS)
• Tester failure → back to coder (within MAX_CODER_ITERATIONS)
• Committer failure → back to coder (within MAX_CODER_ITERATIONS)

Sense Structure

senses/<name>/
  src/
    index.ts        — compute() function + schema
    schema.ts       — Drizzle table definition
  migrations/       — SQLite migrations
  package.json      — with esbuild build script

Toolchain

Tool	Purpose
pnpm	Package manager (workspace mode)
TypeScript	Type checking
esbuild	Bundling (each workflow/sense bundles independently)

Commands

pnpm build          # build all packages
pnpm -r build       # same, explicit recursive
cd workflows/<name> && pnpm build   # build one workflow

Git & Commit Convention

<type>(<scope>): <description>

type: feat | fix | refactor | docs | chore | test
scope: workflow | sense | core | ...

What NOT to commit

• node_modules/
• dist/ (build outputs, generated by esbuild)
• .DS_Store
• pnpm cache artifacts (e.g. false/ directories from --no-cache misuse)
• Secrets, API keys, tokens
• Unrelated file changes outside the task scope

Dependencies

Shared packages from the nerve monorepo:

• @uncaged/nerve-core — types, END constant, WorkflowDefinition
• @uncaged/nerve-workflow-utils — role factories, spawnSafe, llmExtract, cursorAgent
• zod — schema definitions for meta extraction