feat: add CONVENTIONS.md, reviewer references it instead of hardcoding rules
- CONVENTIONS.md covers: language paradigm, naming, error handling, workflow/sense structure, role patterns, meta convention, git rules - Reviewer prompt now: cat CONVENTIONS.md + check diff against it - Single source of truth for all roles
This commit is contained in:
parent
76760c4d29
commit
fbcc1ff30c
152
CONVENTIONS.md
Normal file
152
CONVENTIONS.md
Normal file
@ -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<T, E>` for expected failures
|
||||
- `throw` only for unrecoverable bugs
|
||||
- No try-catch for flow control
|
||||
|
||||
```typescript
|
||||
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 |
|
||||
| Direct `Role<Meta>` | 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/<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
|
||||
|
||||
```bash
|
||||
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
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user