uncaged/nerve
Archived
10
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: align develop-workflow prompts and .knowledge with flat workspace structure #287

New Issue
Closed
opened 2026-04-30 13:15:47 +00:00 by xiaoju · 0 comments
xiaoju commented 2026-04-30 13:15:47 +00:00
Owner
Copy Link
Copy Source

⚠️ Revised direction — AGENT.md instead of nerve-skills

Conventions belong to the workspace, not to an npm package. Different workspaces may have different conventions.

Plan

1. CLI nerve init generates AGENT.md

Update packages/cli/src/commands/init.ts to generate an AGENT.md file in the workspace root. Content should include:

# Nerve Workspace Conventions

## File Structure

workflows//
index.ts — default export (wires adapters + config)
build.ts — factory: createXxxWorkflow({adapters, extract})
moderator.ts — moderator function + WorkflowMeta type
roles/.ts — schema + prompt + createXxxRole (one file per role)

senses//
src/index.ts — compute() function + drizzle table
migrations/ — SQL migration files


## Naming

- Workflow names: **verb-first** kebab-case (e.g. `solve-issue`, `extract-knowledge`)
- Sense names: descriptive kebab-case (e.g. `cpu-usage`, `github-pr`)

## Role Pattern

Every role follows the four-tuple pattern:

```ts
import { createRole } from "@uncaged/nerve-workflow-utils";

export function createXxxRole(adapter: AgentFn, extract: LlmExtractorConfig): Role<XxxMeta> {
  return createRole(adapter, xxxPrompt, xxxMetaSchema, extract);
}
  • adapter: AgentFn — cursor/hermes/llm adapter
  • prompt: string | (ctx) => Promise<string> — role instructions
  • schema: z.ZodType<M> — Zod meta schema for structured extraction
  • extract: LlmExtractorConfig — LLM provider for meta extraction

Pure-LLM roles (no tool use): use createLlmAdapter(provider) from @uncaged/nerve-workflow-utils.

Build

Single root build: npm run build (via scripts/build.mjs)
No per-workflow or per-sense package.json.
Output: dist/workflows/<name>/index.js, dist/senses/<name>/index.js

Coding Style

  • TypeScript, functional-first (function + type, not class + interface)
  • type over interface
  • No optional properties (?:), use T | null
  • Always async/await, never .then() chains
  • Named exports only

### 2. Update develop-workflow and develop-sense prompts

All 6 prompt files should replace `cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md` with `cat AGENT.md`:
- `packages/workflow-meta/src/develop-workflow/roles/planner.ts`
- `packages/workflow-meta/src/develop-workflow/roles/coder.ts`
- `packages/workflow-meta/src/develop-workflow/roles/tester.ts`
- `packages/workflow-meta/src/develop-sense/roles/planner.ts`
- `packages/workflow-meta/src/develop-sense/roles/coder.ts`
- `packages/workflow-meta/src/develop-sense/roles/tester.ts`

Also keep the flat workspace corrections (no per-workflow package.json, root build, single-file roles) from the current branch.

### 3. Update .knowledge docs

Keep the `.knowledge/workflow.md` and `.knowledge/adapter.md` additions from the current branch.

### 4. Tests

- Update `e2e-validate-init.test.ts` to check that `AGENT.md` is generated
- `pnpm -r run test` — all must pass

## Constraints

- Branch: `refactor/287-align-prompts-knowledge` (amend existing)
- Commit as: 小橘 <xiaoju@shazhou.work>
- Reference: Fixes #287
## ⚠️ Revised direction — AGENT.md instead of nerve-skills Conventions belong to the **workspace**, not to an npm package. Different workspaces may have different conventions. ## Plan ### 1. CLI `nerve init` generates `AGENT.md` Update `packages/cli/src/commands/init.ts` to generate an `AGENT.md` file in the workspace root. Content should include: ```markdown # Nerve Workspace Conventions ## File Structure ``` workflows/<name>/ index.ts — default export (wires adapters + config) build.ts — factory: createXxxWorkflow({adapters, extract}) moderator.ts — moderator function + WorkflowMeta type roles/<role>.ts — schema + prompt + createXxxRole (one file per role) senses/<name>/ src/index.ts — compute() function + drizzle table migrations/ — SQL migration files ``` ## Naming - Workflow names: **verb-first** kebab-case (e.g. `solve-issue`, `extract-knowledge`) - Sense names: descriptive kebab-case (e.g. `cpu-usage`, `github-pr`) ## Role Pattern Every role follows the four-tuple pattern: ```ts import { createRole } from "@uncaged/nerve-workflow-utils"; export function createXxxRole(adapter: AgentFn, extract: LlmExtractorConfig): Role<XxxMeta> { return createRole(adapter, xxxPrompt, xxxMetaSchema, extract); } ``` - `adapter: AgentFn` — cursor/hermes/llm adapter - `prompt: string | (ctx) => Promise<string>` — role instructions - `schema: z.ZodType<M>` — Zod meta schema for structured extraction - `extract: LlmExtractorConfig` — LLM provider for meta extraction Pure-LLM roles (no tool use): use `createLlmAdapter(provider)` from `@uncaged/nerve-workflow-utils`. ## Build Single root build: `npm run build` (via `scripts/build.mjs`) No per-workflow or per-sense `package.json`. Output: `dist/workflows/<name>/index.js`, `dist/senses/<name>/index.js` ## Coding Style - TypeScript, functional-first (`function` + `type`, not `class` + `interface`) - `type` over `interface` - No optional properties (`?:`), use `T | null` - Always `async/await`, never `.then()` chains - Named exports only ``` ### 2. Update develop-workflow and develop-sense prompts All 6 prompt files should replace `cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md` with `cat AGENT.md`: - `packages/workflow-meta/src/develop-workflow/roles/planner.ts` - `packages/workflow-meta/src/develop-workflow/roles/coder.ts` - `packages/workflow-meta/src/develop-workflow/roles/tester.ts` - `packages/workflow-meta/src/develop-sense/roles/planner.ts` - `packages/workflow-meta/src/develop-sense/roles/coder.ts` - `packages/workflow-meta/src/develop-sense/roles/tester.ts` Also keep the flat workspace corrections (no per-workflow package.json, root build, single-file roles) from the current branch. ### 3. Update .knowledge docs Keep the `.knowledge/workflow.md` and `.knowledge/adapter.md` additions from the current branch. ### 4. Tests - Update `e2e-validate-init.test.ts` to check that `AGENT.md` is generated - `pnpm -r run test` — all must pass ## Constraints - Branch: `refactor/287-align-prompts-knowledge` (amend existing) - Commit as: 小橘 <xiaoju@shazhou.work> - Reference: Fixes #287
This repo is archived. You cannot comment on issues.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
1 Participants
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/nerve#287
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?