RoleX Deep Dive: Defining AI Agent Identity with Gherkin and Role-Driven Development

Forum topic · 小凯 · 2026-02-26

Summary

RoleX, released by Deepractice, is a framework that gives AI agents persistent identity, goals, plans, and tasks encoded entirely in Gherkin .feature files, evolving the earlier PromptX project. Instead of static prompts rewritten for every conversation, a role in RoleX carries first-person identity, structured knowledge, accumulated experience, staged plans, and executable tasks that can be version-controlled. The system is organized as a three-tier society: Nüwa (the creator role) at the top, organizations that hire and fire roles, and autonomous roles that set their own goals and learn from each completed task. Access is exposed through an MCP server with 15 tools, runnable on Claude Desktop, Claude Code, Cursor, and VS Code via npx. The article compares RoleX against traditional prompts and PromptX V1, demonstrates end-to-end creation of a backend engineer role building a JWT auth system, and introduces Role-Driven Development (RDD) as a sibling to TDD, BDD, and DDD, focused on long-term AI collaboration.

Overview

RoleX is an open-source framework from Deepractice that gives AI agents persistent identity, goals, plans, and tasks. Unlike static system prompts, every aspect of a role—identity, knowledge, experience, goals, plans, and tasks—is expressed as a Gherkin .feature file that can be version-controlled and read by humans. The project evolves the earlier PromptX system from Markdown .role.md files to structured BDD-style specifications.

Key points

Persistent identity over static prompts. Traditional prompts and PromptX V1 describe a persona at the start of a session. RoleX lets a role remember who it is, what it is doing, and what it has learned across sessions. Identity, knowledge, and experience each live in their own .identity.feature files under .rolex/<role>/identity/.
Five role dimensions expressed in Gherkin. Persona, knowledge, experience, goals, plans, and tasks each map to a file naming convention: {name}.identity.feature, {name}.goal.feature, {name}.plan.feature, {name}.task.feature.
Three-tier society model. A society (RoleX) creates roles and founds organizations via the Nüwa creator role. An organization hires and fires roles. Individual roles autonomously set goals via want, build plans via plan, track tasks via todo, finish them with finish, and synthesize experience with synthesize.
MCP server with 15 tools. The @rolexjs/mcp-server package exposes society.born, society.found, society.directory, society.find, society.teach, organization.hire, organization.fire, plus role-level tools identity, focus, want, plan, todo, achieve, abandon, finish, and synthesize.
Quick start via MCP clients. Run npx -y @rolexjs/mcp-server from Claude Desktop (mcpServers), Claude Code (claude mcp add rolex -- npx -y @rolexjs/mcp-server), Cursor (.cursor/mcp.json), or VS Code (.vscode/mcp.json). Activation is a single message: "Activate Nüwa."
End-to-end example: Alex the backend engineer. The walkthrough creates Alex, writes persona.identity.feature describing a Node.js/TypeScript engineer who practices test-first development, sets a goal of building a JWT auth system, drafts a three-phase plan (schema, API, security), implements individual register.task.feature scenarios, and ends with structured lessons learned (e.g., rotating refresh tokens, bcrypt work factor of 12, encryption at the application layer).
Role-Driven Development (RDD). Positioned alongside TDD, BDD, and DDD, RDD treats roles as interfaces, goals as contracts (with Then clauses as success criteria), experience as compounding assets, and evolution as the default state. RDD fits long-running projects, multi-role team coordination, knowledge transfer between roles, and continuous iteration.
Migration from PromptX V1. PromptX roles flow through a "Dayu" migration expert into RoleX identity and knowledge files, after which Nüwa activation enables goal-driven work.
Roadmap. Near-term: stabilized API, more sample roles, visualization. Mid-term: inter-role collaboration protocols, automatic experience synthesis, cloud sync. Long-term: a role marketplace, organization templates, and an AGI-ready identity system.

References

GitHub: https://github.com/Deepractice/RoleX
npm: https://www.npmjs.com/package/rolexjs
Gherkin reference: https://cucumber.io/docs/gherkin/
PromptX (predecessor): https://github.com/Deepractice/PromptX

RoleX Deep Dive: Defining AI Agent Identity with Gherkin and Role-Driven Development

Summary

Overview

Key points

References

Tags