diff --git a/CONVENTIONS.md b/CONVENTIONS.md new file mode 100644 index 0000000..8c78465 --- /dev/null +++ b/CONVENTIONS.md @@ -0,0 +1,152 @@ +# 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`. + +```typescript +// ✅ 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` for expected failures +- `throw` only for unrecoverable bugs +- No try-catch for flow control + +```typescript +type Result = { ok: true; value: T } | { ok: false; error: E }; +``` + +## Workflow Structure + +Each workflow follows the multi-file pattern: + +``` +workflows// + index.ts — WorkflowDefinition default export (thin entry point) + build.ts — factory function with dependency injection + moderator.ts — moderator function + WorkflowMeta type + roles/ + / + 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 | +| Direct `Role` | No LLM needed, scripted logic | committer | + +### Meta Convention + +Meta is a **routing signal only** — one boolean per role: +- `{ ready: boolean }` — planner +- `{ done: boolean }` — coder +- `{ approved: boolean }` — reviewer +- `{ passed: boolean }` — tester +- `{ success: boolean }` — committer + +### 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// + 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 + +```bash +pnpm build # build all packages +pnpm -r build # same, explicit recursive +cd workflows/ && pnpm build # build one workflow +``` + +## Git & Commit Convention + +``` +(): + +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 diff --git a/workflows/gitea-issue-solver/roles/reviewer/prompt.ts b/workflows/gitea-issue-solver/roles/reviewer/prompt.ts index 4428a5b..ed8cdf9 100644 --- a/workflows/gitea-issue-solver/roles/reviewer/prompt.ts +++ b/workflows/gitea-issue-solver/roles/reviewer/prompt.ts @@ -4,6 +4,7 @@ export function reviewerPrompt({ threadId, nerveRoot }: { threadId: string; nerv **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. Always \`cd ${nerveRoot}\` first.** Read the workflow thread for context: \`nerve thread ${threadId}\` +Read project conventions: \`cat ${nerveRoot}/CONVENTIONS.md\` ## Your job — static analysis of the git diff @@ -15,20 +16,16 @@ Run these commands and analyze the output: ## Checklist +Review the diff against CONVENTIONS.md. Key things to catch: + ### 🔴 Reject (approved: false) — tell coder exactly what to fix -- **Garbage files**: node_modules/, .DS_Store, pnpm cache artifacts (e.g. \`false/\` directory), build outputs (dist/) that shouldn't be committed +- **Garbage files**: anything listed under "What NOT to commit" in CONVENTIONS.md - **Secrets/credentials**: API keys, tokens, passwords hardcoded in the diff - **Unrelated changes**: files modified outside the scope of the task -- **Debug code**: console.log, debugger statements, TODO/FIXME without context -- **Hardcoded paths** that should be configurable -- **Wrong patterns**: dynamic import(), interfaces instead of types, broken routing +- **Convention violations**: patterns that contradict CONVENTIONS.md (e.g. \`interface\` instead of \`type\`, \`class\`, dynamic \`import()\`, optional properties with \`?:\`) ### ✅ Approve (approved: true) — no comment needed -If everything looks clean, just approve. Do not add suggestions or warnings — they won't be seen. - -## Output - -Summarize what you found. If garbage files or secrets are present, list them explicitly so the coder knows what to clean up. +- Diff is clean, focused, follows conventions End with: \`\`\`json diff --git a/workflows/sense-generator/roles/reviewer/prompt.ts b/workflows/sense-generator/roles/reviewer/prompt.ts index 4428a5b..ed8cdf9 100644 --- a/workflows/sense-generator/roles/reviewer/prompt.ts +++ b/workflows/sense-generator/roles/reviewer/prompt.ts @@ -4,6 +4,7 @@ export function reviewerPrompt({ threadId, nerveRoot }: { threadId: string; nerv **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. Always \`cd ${nerveRoot}\` first.** Read the workflow thread for context: \`nerve thread ${threadId}\` +Read project conventions: \`cat ${nerveRoot}/CONVENTIONS.md\` ## Your job — static analysis of the git diff @@ -15,20 +16,16 @@ Run these commands and analyze the output: ## Checklist +Review the diff against CONVENTIONS.md. Key things to catch: + ### 🔴 Reject (approved: false) — tell coder exactly what to fix -- **Garbage files**: node_modules/, .DS_Store, pnpm cache artifacts (e.g. \`false/\` directory), build outputs (dist/) that shouldn't be committed +- **Garbage files**: anything listed under "What NOT to commit" in CONVENTIONS.md - **Secrets/credentials**: API keys, tokens, passwords hardcoded in the diff - **Unrelated changes**: files modified outside the scope of the task -- **Debug code**: console.log, debugger statements, TODO/FIXME without context -- **Hardcoded paths** that should be configurable -- **Wrong patterns**: dynamic import(), interfaces instead of types, broken routing +- **Convention violations**: patterns that contradict CONVENTIONS.md (e.g. \`interface\` instead of \`type\`, \`class\`, dynamic \`import()\`, optional properties with \`?:\`) ### ✅ Approve (approved: true) — no comment needed -If everything looks clean, just approve. Do not add suggestions or warnings — they won't be seen. - -## Output - -Summarize what you found. If garbage files or secrets are present, list them explicitly so the coder knows what to clean up. +- Diff is clean, focused, follows conventions End with: \`\`\`json diff --git a/workflows/workflow-generator/roles/reviewer/prompt.ts b/workflows/workflow-generator/roles/reviewer/prompt.ts index 4428a5b..ed8cdf9 100644 --- a/workflows/workflow-generator/roles/reviewer/prompt.ts +++ b/workflows/workflow-generator/roles/reviewer/prompt.ts @@ -4,6 +4,7 @@ export function reviewerPrompt({ threadId, nerveRoot }: { threadId: string; nerv **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. Always \`cd ${nerveRoot}\` first.** Read the workflow thread for context: \`nerve thread ${threadId}\` +Read project conventions: \`cat ${nerveRoot}/CONVENTIONS.md\` ## Your job — static analysis of the git diff @@ -15,20 +16,16 @@ Run these commands and analyze the output: ## Checklist +Review the diff against CONVENTIONS.md. Key things to catch: + ### 🔴 Reject (approved: false) — tell coder exactly what to fix -- **Garbage files**: node_modules/, .DS_Store, pnpm cache artifacts (e.g. \`false/\` directory), build outputs (dist/) that shouldn't be committed +- **Garbage files**: anything listed under "What NOT to commit" in CONVENTIONS.md - **Secrets/credentials**: API keys, tokens, passwords hardcoded in the diff - **Unrelated changes**: files modified outside the scope of the task -- **Debug code**: console.log, debugger statements, TODO/FIXME without context -- **Hardcoded paths** that should be configurable -- **Wrong patterns**: dynamic import(), interfaces instead of types, broken routing +- **Convention violations**: patterns that contradict CONVENTIONS.md (e.g. \`interface\` instead of \`type\`, \`class\`, dynamic \`import()\`, optional properties with \`?:\`) ### ✅ Approve (approved: true) — no comment needed -If everything looks clean, just approve. Do not add suggestions or warnings — they won't be seen. - -## Output - -Summarize what you found. If garbage files or secrets are present, list them explicitly so the coder knows what to clean up. +- Diff is clean, focused, follows conventions End with: \`\`\`json