@rolexjs/core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,190 +1,197 @@
-import { RXR, Registry } from "resourcexjs";
-/**
-* RoleX Core Types
-* @rolexjs/core
-*/
-/**
-* Rendered Role object
-*/
-interface RenderedRole {
-	/** Final rendered complete prompt */
-	readonly prompt: string;
-	/** Personality section */
-	readonly personality: string;
-	/** Principle section */
-	readonly principle: string;
-	/** Knowledge section */
-	readonly knowledge: string;
+import { Scenario as Scenario$1, Feature as Feature$1 } from '@cucumber/messages';
+
+/**
+ * Scenario — A unit of behavior within a Feature.
+ *
+ * Extends Gherkin's Scenario with verifiability marking.
+ * Verifiable scenarios become persistent test cases.
+ * Non-verifiable scenarios are one-time acceptance criteria.
+ */
+
+/**
+ * A Gherkin Scenario enriched with verification metadata.
+ */
+interface Scenario extends Scenario$1 {
+    readonly verifiable: boolean;
 }
-/**
-* Thought sub-tag types
-*/
-type ThoughtSubTag = "exploration" | "reasoning" | "challenge" | "plan";
-/**
-* Execution sub-tag types
-*/
-type ExecutionSubTag = "process" | "constraint" | "rule" | "guideline" | "criteria";
-/**
-* Parsed Thought content
-*/
-interface ParsedThought {
-	readonly exploration?: string;
-	readonly reasoning?: string;
-	readonly challenge?: string;
-	readonly plan?: string;
+
+/**
+ * Feature — The atomic unit in the RDD model.
+ *
+ * Extends Gherkin's Feature with RDD dimension classification
+ * and explicit Scenario relationship.
+ */
+
+/**
+ * A Gherkin Feature enriched with RDD semantics.
+ */
+interface Feature extends Feature$1 {
+    readonly type: "persona" | "knowledge" | "experience" | "voice" | "goal" | "plan" | "task";
+    readonly scenarios: Scenario[];
 }
-/**
-* Parsed Execution content
-*/
-interface ParsedExecution {
-	readonly process?: string;
-	readonly constraint?: string;
-	readonly rule?: string;
-	readonly guideline?: string;
-	readonly criteria?: string;
+
+/**
+ * Identity — The role's complete self.
+ *
+ * NOT a Feature itself — it is a container that wraps
+ * multiple Features (*.identity.feature files).
+ * Always loaded, independent of any goal.
+ */
+
+/**
+ * The identity foundation of a role. Wraps many Features.
+ */
+interface Identity {
+    readonly features: Feature[];
 }
-/**
-* Resource resolver function type
-*/
-type ResourceResolver = (src: string) => Promise<string>;
-/**
-* Load and render a Role from RXR
-*
-* @param rxr - Role resource (RXL + RXM + RXC)
-* @param registry - Registry instance (for resolving ARP rxr:// references)
-* @returns Rendered Role object
-*
-* @example
-* ```typescript
-* const registry = createRegistry();
-* const rxr = await registry.get('localhost/my.role@1.0.0');
-* const role = await loadRole(rxr, registry);
-* console.log(role.prompt);
-* ```
-*/
-declare function loadRole(rxr: RXR, registry: Registry): Promise<RenderedRole>;
-import { ResourceType } from "resourcexjs";
-/**
-* Role resource type for ResourceX integration
-*
-* @example
-* ```typescript
-* import { createRegistry } from 'resourcexjs';
-* import { roleType } from '@rolexjs/core';
-*
-* const registry = createRegistry();
-* registry.supportType(roleType);
-*
-* const resource = await registry.resolve('deepractice.dev/nuwa.role@1.0.0');
-* const role = await resource.execute();
-* console.log(role.prompt);
-* ```
-*/
-declare const roleType: ResourceType<void, RenderedRole>;
-/**
-* RoleX Error Classes
-* @rolexjs/core
-*/
-/**
-* Base error class for all RoleX errors
-*/
-declare class RoleXError extends Error {
-	constructor(message: string, options?: ErrorOptions);
+
+/**
+ * Goal — The driver of action.
+ *
+ * A Goal IS-A Feature with type='goal'.
+ * Dynamic and phase-specific. What the role wants to achieve.
+ * Expressed as *.goal.feature files.
+ */
+
+/**
+ * A goal that a role wants to achieve in a given phase.
+ */
+interface Goal extends Feature {
+    readonly type: "goal";
 }
-/**
-* Error thrown when role loading fails
-*/
-declare class RoleLoadError extends RoleXError {
-	readonly locator?: string;
-	constructor(message: string, locator?: string);
+
+/**
+ * Role — The primary organizing unit in RDD.
+ *
+ * Every role operates through dimensions:
+ * Identity → Goal → Plan → Task/Skill
+ *
+ * Identity is static (always present).
+ * Goals are dynamic (change per phase).
+ */
+
+/**
+ * A role in the RDD (Role-Driven Development) model.
+ */
+interface Role {
+    readonly name: string;
+    readonly identity: Identity;
+    readonly goals: Goal[];
 }
-/**
-* Error thrown when resource resolution fails
-*/
-declare class ResourceResolveError extends RoleXError {
-	readonly src?: string;
-	constructor(message: string, src?: string);
+
+/**
+ * Plan — The bridge between goal and execution.
+ *
+ * A Plan IS-A Feature with type='plan'.
+ * Expressed as *.plan.feature files.
+ */
+
+/**
+ * A plan that decomposes a goal into executable tasks.
+ */
+interface Plan extends Feature {
+    readonly type: "plan";
 }
-/**
-* Error thrown when DPML parsing fails
-*/
-declare class DPMLParseError extends RoleXError {
-	constructor(message: string);
+
+/**
+ * Task — Concrete unit of work within a plan.
+ *
+ * A Task IS-A Feature with type='task'.
+ * Expressed as *.task.feature files.
+ */
+
+/**
+ * A concrete unit of work.
+ */
+interface Task extends Feature {
+    readonly type: "task";
+}
+
+/**
+ * Skill — Execution capability for a task.
+ *
+ * Compatible with existing skill systems:
+ * Claude Code skills, ResourceX resources, MCP tools, etc.
+ */
+/**
+ * A capability that a role uses to execute a task.
+ */
+interface Skill {
+    /** Skill identifier, e.g. "commit", "bdd", "dev-flow" */
+    readonly name: string;
+    /** Reference to the concrete implementation: skill path, resource locator, tool URI */
+    readonly reference: string;
 }
-import { Schema } from "dpml";
-/**
-* RoleX schema collection
-*/
-interface RoleSchemas {
-	readonly role: Schema;
-	readonly thought: Schema;
-	readonly execution: Schema;
-	readonly knowledge: Schema;
+
+/**
+ * Platform — The abstraction layer for role storage.
+ *
+ * Defines how roles are loaded and persisted.
+ * LocalPlatform uses the filesystem (.rolex/ directories).
+ * Future platforms could use databases, cloud storage, etc.
+ *
+ * All methods are stateless — role name is passed per call.
+ */
+
+/**
+ * Role entry in the organization.
+ */
+interface RoleEntry {
+    readonly name: string;
+    readonly team: string;
 }
-import { Schema as Schema2 } from "dpml";
-/**
-* Create all RoleX schemas
-*
-* Role structure:
-* <role>
-*   <personality>...</personality>
-*   <principle>...</principle>
-*   <knowledge>...</knowledge>
-* </role>
-*/
-declare function defineRoleSchemas(): RoleSchemas;
-declare const roleSchema: Schema2;
-declare const thoughtSchema: Schema2;
-declare const executionSchema: Schema2;
-declare const knowledgeSchema: Schema2;
-/**
-* Transformer input interface (compatible with dpml 0.3.0)
-*/
-interface TransformInput {
-	document: {
-		rootNode: unknown
-		nodesById?: Map<string, unknown>
-		metadata?: Record<string, unknown>
-	};
-	isValid?: boolean;
-	validation?: {
-		isValid: boolean
-		errors: unknown[]
-		warnings: unknown[]
-	};
-	resources?: unknown[];
+/**
+ * Organization structure.
+ */
+interface Organization {
+    readonly name: string;
+    readonly roles: RoleEntry[];
+}
+/**
+ * Society directory — all known roles and organizations.
+ */
+interface Directory {
+    readonly roles: readonly RoleEntry[];
+    readonly organizations: readonly {
+        readonly name: string;
+    }[];
 }
 /**
-* Role transformer type
-*/
-interface RoleTransformer {
-	name: string;
-	description?: string;
-	transform(input: TransformInput): RenderedRole;
+ * Platform interface — abstracts role storage and retrieval.
+ * All methods are stateless — role name identifies the target role.
+ */
+interface Platform {
+    /** Found an organization */
+    found(name: string): void;
+    /** Get the organization structure (teams + roles) */
+    organization(): Organization;
+    /** Create a new role with its persona */
+    born(name: string, source: string): Feature;
+    /** Hire a role into the organization — establish CAS link */
+    hire(name: string): void;
+    /** Fire a role from the organization — remove CAS link */
+    fire(name: string): void;
+    /** Load all identity features for a role */
+    identity(roleId: string): Feature[];
+    /** Add a growth dimension to a role's identity */
+    growup(roleId: string, type: "knowledge" | "experience" | "voice", name: string, source: string): Feature;
+    /** Find the current active goal for a role (with plan + tasks context) */
+    activeGoal(roleId: string): (Goal & {
+        plan: Plan | null;
+        tasks: Task[];
+    }) | null;
+    /** Create a new goal from Gherkin source */
+    createGoal(roleId: string, name: string, source: string, testable?: boolean): Goal;
+    /** Create a plan for the current active goal */
+    createPlan(roleId: string, source: string): Plan;
+    /** Create a task for the current active goal */
+    createTask(roleId: string, name: string, source: string, testable?: boolean): Task;
+    /** Mark the current active goal as done, optionally with experience reflection */
+    completeGoal(roleId: string, experience?: string): void;
+    /** Abandon the current active goal, optionally with experience reflection */
+    abandonGoal(roleId: string, experience?: string): void;
+    /** Mark a task as done */
+    completeTask(roleId: string, name: string): void;
 }
-import { Transformer } from "dpml";
-/**
-* Role Transformer
-* Transforms DPML role document into RenderedRole
-*/
-declare const roleTransformer: Transformer<{
-	document: {
-		rootNode: unknown
-	}
-}, RenderedRole>;
-import { Registry as Registry2 } from "resourcexjs";
-/**
-* Create a resource resolver function
-*
-* @param registry - Registry instance (required for RxrTransport)
-* @returns Resource resolver function that accepts ARP URLs
-*
-* @example
-* ```typescript
-* const resolver = createResourceResolver(registry);
-* const content = await resolver('arp:text:rxr://localhost/my.role@1.0.0/thought/first.thought.md');
-* ```
-*/
-declare function createResourceResolver(registry: Registry2): ResourceResolver;
-declare const VERSION: string;
-export { thoughtSchema, roleType, roleTransformer, roleSchema, loadRole, knowledgeSchema, executionSchema, defineRoleSchemas, createResourceResolver, VERSION, ThoughtSubTag, RoleXError, RoleTransformer, RoleSchemas, RoleLoadError, ResourceResolver, ResourceResolveError, RenderedRole, ParsedThought, ParsedExecution, ExecutionSubTag, DPMLParseError };
+
+export type { Directory, Feature, Goal, Identity, Organization, Plan, Platform, Role, RoleEntry, Scenario, Skill, Task };