lrnev (lrnev-govern)

What It Does

lrnev is a project governance engine for AI-assisted development, distributed as both an MCP server and a CLI tool. It creates a .lrnev/ directory in your project root that stores requirements, designs, tasks, architectural decisions (ADRs), error records, and project memory as plain Markdown files. AI agents interact with this structure through 39 MCP tools (or matching CLI commands) to create specs, manage task lifecycles, run quality gates, record decisions, and maintain session-to-session continuity. The project is written in TypeScript (10,148 lines across 61 source files), ships on npm as lrnev, and requires Node.js 20 or later. The documentation is primarily in Chinese with some English sections.

The Good

Strong engineering foundation with 564 passing tests. The test suite includes 40 test files covering unit, integration, and e2e layers. Only 1 test failed out of 565, and that failure was caused by a gitignored dev-docs/PUBLISH.md file not shipped with the public repo. The codebase has zero any types (explicitly banned by contributing guidelines) and uses a structured error system (LrnevError with typed ErrorCode values). Every module from TaskManager (946 lines) to URIRouter (448 lines) has corresponding test coverage.

Dual-mode MCP and CLI with complete feature parity. Every MCP tool has a matching CLI subcommand with the same parameters and behavior. This is not an afterthought. The contributing guidelines explicitly state: "MCP and CLI must both support new capabilities, with consistent parameters and behavior." During testing, both lrnev init (CLI) and the MCP server started correctly, and the full spec-to-task-to-gate workflow worked identically in both modes.

The "ai_followup" pattern is well-designed. Every tool response includes an ai_followup object with contextual instructions and suggested next tools. When you create a spec, the followup tells the agent to fill requirements, then run the ready gate. When you complete a task, it suggests running the completion gate. This gives agents a clear decision tree without hard-coding behavior. It is the "guide, do not force" philosophy in action, and it works.

Zero model dependency is a genuine differentiator. lrnev does not call any LLM or embedding API. All operations are deterministic file reads/writes, ID generation, state machine transitions, and structural checks. This means no API costs, no network requirements, and no vendor lock-in. The trade-off is that "understanding" tasks (should this be a spec or just a quick fix?) are delegated back to the agent via ai_followup rather than automated.

Thoughtful token efficiency design. The project_status tool returns bounded snapshots (only active tasks and counts, not full document bodies). The context_search tool uses keyword scoring with L0/L1/L2 abstract levels, so agents can check a one-line summary before deciding whether to read the full document. The README is unusually honest about when lrnev adds token overhead versus when it saves tokens: short one-off tasks cost more, long iterative projects save more.

The Bad

Primary documentation is in Chinese only. The README (320 lines), CONTRIBUTING guide, architecture docs, governance flow docs, and all inline help strings are written in Chinese. There are no English translations. The --help output, error messages, and ai_followup instructions all appear in Chinese. This limits adoption to Chinese-reading developers and agents configured for Chinese-language workflows. For an MCP server that could otherwise serve any developer globally, this is the single biggest barrier.

No tagged releases despite being on npm. The repo has no git tags, no GitHub releases, and a single-commit history (shallow clone returned 1 commit). The npm package is published at v1.3.0, but the repository itself has no release artifacts. This makes it harder to track changes, pin versions in production, or audit what changed between releases. The CHANGELOG.md exists in the repo but is not linked from any release.

Gate checking only validates structure, not content quality. The ready gate checks for FILL sentinels, required sections, and frontmatter fields. It does not evaluate whether the requirements are well-written, whether the design is sound, or whether the acceptance criteria are testable. The README acknowledges this ("Gate is structural checking, it does not judge requirements quality"), but it means the governance promise depends entirely on the AI agent filling in good content, with no mechanical backstop.

Single-author project with 29 stars. All commits are from one contributor (luchangqiu). There are no external PRs, no issue discussions, and no community activity visible in the repo. At 29 stars and growing (doubled from 15 in one scan period), the project has momentum but no evidence of production usage outside the author's own workflow.

Smoke Test Results

Tested on macOS aarch64 (host), Node.js 22.x, cloning the GitHub repo and building from source.

Run A: Fresh clone, build from source

$ git clone --depth 1 https://github.com/LuChangQiu/lrnev-govern.git /tmp/lrnev-govern
Cloning into 'lrnev-govern'...
✅ clone succeeded

$ cd /tmp/lrnev-govern && npm install --cache /tmp/lrnev-npm-cache
added XX packages in Xs
✅ install succeeded (npm cache EACCES workaround required on macOS)

$ npm run build
> tsc
✅ build succeeded, zero errors

$ node bin/lrnev.mjs --version
1.3.0
✅ CLI works

$ node bin/lrnev-mcp.mjs --help
lrnev@1.3.0 MCP 服务已通过 stdio 启动。
✅ MCP server starts in stdio mode

Pass rate: 5 of 5. Full build and startup from source works cleanly.

Run B: npm published package

$ npx --cache /tmp/lrnev-npx-cache lrnev@1.3.0 --version
1.3.0
✅ npx works, version matches repo

Pass rate: 1 of 1. Published npm package works without cloning.

Run C: Functional verification (full governance workflow)

$ mkdir /tmp/lrnev-test && cd /tmp/lrnev-test
$ node /tmp/lrnev-govern/bin/lrnev.mjs init --project-name test-project
✅ ok: true, files_created: 8 files, directories_ensured: 21 directories
 ai_followup with suggested next steps

$ node bin/lrnev.mjs status
✅ ok: true, JSON status with scenes/specs/active_tasks arrays

$ node bin/lrnev.mjs spec create user-login --priority P0
✅ ok: true, spec: "01-00-user-login", status: "draft"
 ai_followup suggesting to fill requirements then run ready gate

$ node bin/lrnev.mjs task create "Implement login API" --scene 00-default \
 --spec 01-00-user-login --validates F-01 --acceptance "POST /login 200" \
 "Wrong password returns 401"
✅ ok: true, id: "T-001", status: "pending", validates: ["F-01"]

$ node bin/lrnev.mjs task update T-001 --scene 00-default \
 --spec 01-00-user-login --status in_progress
✅ ok: true, status: "in_progress", history tracked

$ node bin/lrnev.mjs task update T-001 --scene 00-default \
 --spec 01-00-user-login --status completed
✅ ok: true, status: "completed", ai_followup suggests completion gate

$ node bin/lrnev.mjs gate check --scene 00-default \
 --spec 01-00-user-login --gate ready
✅ gate: "ready", passed: false (expected: FILL sentinels not yet replaced)
 9 checks, 7 passed, 2 failed with specific messages

$ node bin/lrnev.mjs search "login"
✅ ok: true, 4 results with scores, URIs, and snippets

$ node bin/lrnev.mjs doctor
✅ ok: true, 0 errors, 2 warnings (FILL fields in PROJECT.md and ARCHITECTURE.md)

$ npx vitest run (from source dir)
✅ 564 passed, 1 failed (dev-docs/PUBLISH.md not in repo)
 Duration: 3.61s

Functional pass rate: 10 of 10. Every tested workflow returned correct, structured JSON output with meaningful ai_followup guidance. The gate check correctly identified unfilled sentinel values. The search returned relevant, scored results. The doctor found real issues.

What the runs tell you

lrnev installs cleanly from both source and npm, builds without errors, and the full governance workflow (init through gate check) works end-to-end. The single test failure is unrelated to the project's code. The CLI and MCP server both start correctly and produce structured JSON output at every step. This is a functional, tested, published MCP server that does what it claims.

Setup Walkthrough

1. Install Node.js 20 or later.
2. Run npm install -g lrnev (or use npx lrnev@latest without installing).
3. In your project directory, run lrnev init --project-name your-project.
4. For MCP integration, add to your client config: { "mcpServers": { "lrnev": { "command": "lrnev-mcp" } } }.
5. Tell your agent: "This project uses lrnev governance. Call lrnev_guide first."
6. If npm cache EACCES errors appear on macOS, use --cache /tmp/lrnev-npm-cache flag or npx --cache /tmp/lrnev-npx-cache.

Post-install note: The init command creates templates with FILL sentinels that must be replaced with real content before gates will pass. The doctor command identifies incomplete fields. The guide command returns a thorough Chinese-language manual for the agent.

Alternatives

1. obra/superpowers (220,314 stars) -- a broader agent skill framework with subagent-driven development. Superpowers is a methodology pack, while lrnev is a dedicated governance server. Use lrnev when you need persistent file-based governance, superpowers when you need general agent workflow skills.
2. virgiliojr94/book-to-skill (4,574 stars) -- converts books and documents into agent skills. Complementary rather than competing: book-to-skill creates knowledge artifacts, lrnev manages the development process around them.
3. PanisHandsome/ai-rules-sync (113 stars) -- syncs AI rules across agent platforms. A lighter-weight alternative when you need cross-agent configuration but not full spec-driven governance.