@litmers/cursorflow-orchestrator 0.1.8 → 0.1.12

package/commands/cursorflow-run.md

@@ -1,129 +1,251 @@
 # CursorFlow Run
 
 ## Overview
-Execute prepared tasks with single-lane or multi-lane orchestration.
 
-## Steps
+Execute AI agent orchestration using task configurations generated by `prepare`. CursorFlow uses a DAG (Directed Acyclic Graph) scheduler to handle lane dependencies and automatic branch merging.
 
-1. **Check the task directory**
-   ```bash
-   ls _cursorflow/tasks/
-   ```
+## Workflow
 
-2. **Run multiple lanes**
-   ```bash
-   cursorflow run _cursorflow/tasks/MyFeature/
-   ```
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│ 1. Create Lanes │ ──▶ │ 2. Add Tasks    │ ──▶ │ 3. Validate     │ ──▶ │ 4. Run          │
+│ (prepare)       │     │ (prepare)       │     │ (doctor)        │     │ (run)           │
+└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+## Usage
+
+```bash
+cursorflow run <tasks-dir> [options]
+```
 
-3. **Run a single lane**
-   ```bash
-   cursorflow lane _cursorflow/tasks/MyFeature/01-task.json
-   ```
+### Quick Start
 
-4. **Dry run (preview the plan)**
-   ```bash
-   cursorflow run _cursorflow/tasks/MyFeature/ --dry-run
-   ```
+```bash
+# Step 1: Create lanes
+cursorflow prepare AddAPI --prompt "Create REST API for users" --criteria "CRUD works,Tests pass"
+
+# Step 2: (Optional) Add more lanes or tasks
+cursorflow prepare --add-lane _cursorflow/tasks/2412211530_AddAPI \
+  --prompt "Add authentication" --depends-on "01-lane-1"
+
+# Step 3: Validate configuration
+cursorflow doctor --tasks-dir _cursorflow/tasks/2412211530_AddAPI
+
+# Step 4: Run
+cursorflow run _cursorflow/tasks/2412211530_AddAPI
+
+# Or run the latest prepared task
+cursorflow run latest
+```
 
-5. **Monitor execution**
+## How It Works
 
-   Watch progress from another terminal while the run is in progress:
-   ```bash
-   cursorflow monitor --watch
-   ```
+1. **Load**: Read all JSON files from the tasks directory
+2. **Validate**: Check `tasks` array, required fields (`name`, `prompt`)
+3. **Resolve**: Build execution order from `dependsOn` dependencies
+4. **Execute**:
+   - Start lanes with no dependencies in parallel
+   - When a lane completes, unlock dependent lanes
+   - **Dependent lanes auto-merge predecessor branches before starting**
+5. **Monitor**: Heartbeat logs every 30 seconds
 
 ## Options
 
 | Option | Description |
-|------|------|
-| `--dry-run` | Preview the plan without executing |
-| `--executor <type>` | Execution mode (`cursor-agent` \| `cloud`) |
-| `--no-review` | Disable code review |
-| `--config <path>` | Use a custom config file |
+|--------|-------------|
+| `<tasks-dir>` | Directory containing JSON task files |
+| `--max-concurrent <num>` | Limit concurrent lane execution |
+| `--executor <type>` | `cursor-agent` (default) or `cloud` |
+| `--skip-doctor` | Skip environment checks (not recommended) |
+| `--dry-run` | Show execution plan without running |
 
-## Examples
+## Execution Flow
+
+### Single Lane
 
-### Standard run
 ```bash
-cursorflow run _cursorflow/tasks/2512191700_MyFeature/
+cursorflow prepare SimpleFix --prompt "Fix the bug"
+cursorflow run _cursorflow/tasks/2412211530_SimpleFix
 ```
 
-### Cloud run (requires API key)
-```bash
-export CURSOR_API_KEY=your_key
-cursorflow run _cursorflow/tasks/MyFeature/ --executor cloud
+```
+┌─────────────────────────────────────────────────────────┐
+│  01-lane-1                                              │
+│  ┌─────────┐                                            │
+│  │implement│ → AI executes → Review → Complete          │
+│  └─────────┘                                            │
+└─────────────────────────────────────────────────────────┘
 ```
 
-### Fast run without review
+### Multiple Tasks in Lane
+
 ```bash
-cursorflow run _cursorflow/tasks/MyFeature/ --no-review
+cursorflow prepare Feature \
+  --task "plan|sonnet-4.5-thinking|Create plan|Plan ready" \
+  --task "implement|sonnet-4.5|Build feature|Code done"
 ```
 
-## Execution process
+```
+┌─────────────────────────────────────────────────────────┐
+│  01-lane-1                                              │
+│  ┌────┐     ┌─────────┐                                 │
+│  │plan│ ──▶ │implement│ → Review → Complete             │
+│  └────┘     └─────────┘                                 │
+└─────────────────────────────────────────────────────────┘
+```
 
-1. **Initialization**
-   - Load configuration
-   - Verify the `cursor-agent` CLI
-   - Confirm Git repository status
+### Sequential Lanes (with `--sequential`)
 
-2. **Prepare lanes**
-   - Create worktrees
-   - Check out branches
-   - Configure the environment
+```bash
+cursorflow prepare FullStack --lanes 3 --sequential \
+  --prompt "Implement your layer"
+```
 
-3. **Run tasks**
-   - Execute tasks sequentially
-   - Commit after each task
-   - Trigger automatic review when enabled
+```
+┌───────────┐     ┌───────────┐     ┌───────────┐
+│ 01-lane-1 │ ──▶ │ 02-lane-2 │ ──▶ │ 03-lane-3 │
+│ (DB)      │     │ (API)     │     │ (UI)      │
+└───────────┘     └───────────┘     └───────────┘
+                        │                 │
+                    merges 01         merges 01,02
+```
 
-4. **Complete**
-   - Push changes
-   - Create a PR (depending on settings)
-   - Store logs
+### Parallel Lanes
 
-## Log location
+```bash
+cursorflow prepare FrontBack --lanes 2 \
+  --prompt "Implement your layer"
+```
 
-Run logs are stored in `_cursorflow/logs/runs/`:
+```
+┌───────────┐
+│ 01-lane-1 │  (Frontend)
+└───────────┘
+              ─── both run in parallel
+┌───────────┐
+│ 02-lane-2 │  (Backend)
+└───────────┘
+```
 
+## JSON Schema (RunnerConfig)
+
+Each JSON file in the tasks directory follows this schema:
+
+```json
+{
+  "baseBranch": "main",
+  "branchPrefix": "feature/lane-1-",
+  "timeout": 300000,
+  "enableIntervention": false,
+  "dependsOn": ["01-lane-1"],
+  "dependencyPolicy": {
+    "allowDependencyChange": false,
+    "lockfileReadOnly": true
+  },
+  "enableReview": true,
+  "reviewModel": "sonnet-4.5-thinking",
+  "maxReviewIterations": 3,
+  "tasks": [
+    {
+      "name": "implement",
+      "prompt": "Create a reusable button component...",
+      "model": "sonnet-4.5",
+      "acceptanceCriteria": ["Build passes", "Tests pass"]
+    }
+  ]
+}
 ```
-_cursorflow/logs/runs/<lane>-<timestamp>/
-├── state.json              # Lane status
-├── results.json            # Task results
-├── conversation.jsonl      # Agent conversation
-├── git-operations.jsonl    # Git activity log
-└── events.jsonl            # Event log
+
+### Configuration Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `baseBranch` | string | Yes | Branch to create worktree from |
+| `branchPrefix` | string | Yes | Prefix for feature branch naming |
+| `tasks` | Task[] | Yes | Array of task objects to execute |
+| `dependsOn` | string[] | No | Lane names to wait for and merge |
+| `timeout` | number | No | Task timeout in ms (default: 300000) |
+| `enableIntervention` | boolean | No | Allow stdin injection during execution |
+| `dependencyPolicy.allowDependencyChange` | boolean | No | Allow package.json modifications |
+| `dependencyPolicy.lockfileReadOnly` | boolean | No | Keep lockfile read-only |
+| `enableReview` | boolean | No | Enable AI code review (default: true) |
+| `reviewModel` | string | No | Model for code review |
+| `maxReviewIterations` | number | No | Max review cycles (default: 3) |
+
+### Task Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Task identifier (alphanumeric, `-`, `_`) |
+| `prompt` | string | Yes | Instructions for the AI agent |
+| `model` | string | No | Model override for this task |
+| `acceptanceCriteria` | string[] | No | Criteria for AI reviewer validation |
+
+## Monitoring During Execution
+
+```bash
+# In another terminal
+cursorflow monitor latest
+
+# Or specify the task directory
+cursorflow monitor _cursorflow/tasks/2412211530_AddAPI
 ```
 
-## Checklist
-- [ ] Is the `cursor-agent` CLI installed?
-- [ ] Are Git worktrees available?
-- [ ] Are the task files valid?
-- [ ] Do branch names avoid collisions?
-- [ ] Are required environment variables set? (for cloud runs)
+The monitor shows:
+- Lane status (pending, running, completed, failed)
+- Current task within each lane
+- Dependency graph and progress
+- Real-time log streaming
 
 ## Troubleshooting
 
-### Branch conflicts
-```bash
-# Clean up existing branches
-cursorflow clean branches --pattern "feature/my-*"
+### Validation Errors
+
+```
+Task N missing required "name" field
 ```
+→ Ensure every task has both `name` and `prompt` fields
 
-### Worktree conflicts
-```bash
-# Clean up existing worktrees
-cursorflow clean worktrees --all
 ```
+Invalid task name: "my task"
+```
+→ Task names can only contain alphanumeric characters, `-`, and `_`
 
-### Run failures
-```bash
-# Inspect logs
-cursorflow monitor
-# or
-cat _cursorflow/logs/runs/latest/*/state.json
+### Dependency Issues
+
+```
+Circular dependency detected
+```
+→ Check your `dependsOn` fields for cycles (A→B, B→A)
+
+```
+Unknown dependency: 01-lane-99
 ```
+→ Verify the lane name in `dependsOn` matches an actual JSON filename
+
+### Merge Conflicts
+
+When a dependent lane's auto-merge fails:
+
+1. Find the worktree path in `cursorflow monitor`
+2. Navigate to the worktree directory
+3. Resolve conflicts manually and commit
+4. Resume with `cursorflow resume <lane-name>`
+
+### Lane Stuck
+
+If a lane stops responding:
+
+1. Check the agent window in Cursor IDE
+2. Use `cursorflow signal <lane-name> --message "continue"` to nudge
+3. Or terminate and restart with `cursorflow run --resume`
+
+## Best Practices
 
-## Next steps
-1. Monitor progress with `cursorflow monitor --watch`.
-2. Review the PR when the run completes.
-3. If a run fails, resume with `cursorflow resume <lane>`.
+1. **Always Validate First**: Run `cursorflow doctor --tasks-dir <dir>` before `run`
+2. **Start Small**: Test with a single lane before scaling up
+3. **Use `--dry-run`**: Preview execution plan before committing
+4. **Monitor Actively**: Keep `cursorflow monitor` running in a separate terminal
+5. **Plan Dependencies**: Draw out the DAG before running complex workflows
+6. **Include Verification**: Add verify tasks to catch edge cases

package/commands/cursorflow-signal.md

@@ -1,19 +1,45 @@
-# /cursorflow-signal
+# CursorFlow Signal
 
-## Goal
-Directly intervene in a running lane to provide guidance, corrections, or emergency stops.
+## Overview
+Directly intervene in a running lane by sending a message to the agent. This is useful for providing immediate feedback or corrections during long-running tasks.
 
 ## Usage
-1. Type `/cursorflow-signal <lane-name> <your-message>` in the chat.
-2. The message will be injected into the lane's conversation as a high-priority system instruction.
 
-## Context
-Use this command when:
-- You see an agent making a repeated mistake in the monitor.
-- You want to provide specific implementation guidance mid-task.
-- You need to tell the agent to stop or change direction without killing the process.
+```bash
+cursorflow signal <lane-name> "<message>" [options]
+```
+
+## Options
+
+| Option | Description |
+|------|------|
+| `<lane-name>` | The name of the lane to signal |
+| `"<message>"` | The text message to send to the agent |
+| `--run-dir <path>` | Use a specific run directory (default: latest) |
+
+## How it works
+1. **Logging**: The message is recorded in the lane's conversation history as a system/commander message.
+2. **Injection**: If the lane's task configuration has `enableIntervention: true`, the message is injected into the agent's input stream.
 
 ## Example
-"Send a signal to lane-1: 'Stop using library X, use library Y instead.'"
-"Intervene in backend-lane: 'The database schema changed, please pull the latest main branch.'"
 
+```bash
+# Provide a hint to a running agent
+cursorflow signal 01-lane-1 "Make sure to export the new function from index.ts"
+```
+
+## Dashboard Alternative
+You can also use the interactive monitor to send signals:
+1. Run `cursorflow monitor latest`.
+2. Select a lane and enter details (`→`).
+3. Press `I` to type and send an intervention message.
+
+## Note on Intervention
+For the agent to receive the signal immediately, the task must be configured with:
+```json
+{
+  "enableIntervention": true,
+  "tasks": [...]
+}
+```
+If disabled, the signal will be logged but the agent will not be interrupted.

package/dist/cli/clean.d.ts

@@ -1,5 +1,7 @@
 /**
- * CursorFlow clean command (stub)
+ * CursorFlow clean command
+ *
+ * Clean up worktrees, branches, and logs created by CursorFlow
  */
 declare function clean(args: string[]): Promise<void>;
 export = clean;

package/dist/cli/clean.js

@@ -1,6 +1,8 @@
 "use strict";
 /**
- * CursorFlow clean command (stub)
+ * CursorFlow clean command
+ *
+ * Clean up worktrees, branches, and logs created by CursorFlow
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -35,23 +37,158 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const logger = __importStar(require("../utils/logger"));
+const git = __importStar(require("../utils/git"));
+const config_1 = require("../utils/config");
+function printHelp() {
+    console.log(`
+Usage: cursorflow clean <type> [options]
+
+Clean up resources created by CursorFlow.
+
+Types:
+  branches               Remove local feature branches
+  worktrees              Remove temporary Git worktrees
+  logs                   Clear log directories
+  all                    Remove all of the above (default)
+
+Options:
+  --dry-run              Show what would be removed without deleting
+  --force                Force removal (ignore uncommitted changes)
+  --help, -h             Show help
+  `);
+}
 function parseArgs(args) {
     return {
-        type: args[0], // branches | worktrees | logs | all
+        type: args.find(a => ['branches', 'worktrees', 'logs', 'all'].includes(a)),
         pattern: null,
         dryRun: args.includes('--dry-run'),
         force: args.includes('--force'),
+        all: args.includes('--all'),
+        help: args.includes('--help') || args.includes('-h'),
     };
 }
 async function clean(args) {
-    logger.section('🧹 Cleaning CursorFlow Resources');
     const options = parseArgs(args);
-    logger.info('This command will be fully implemented in the next phase');
-    logger.info(`Clean type: ${options.type}`);
-    logger.info(`Dry run: ${options.dryRun}`);
-    logger.warn('\n⚠️  Implementation pending');
-    logger.info('This will clean branches, worktrees, and logs');
+    if (options.help) {
+        printHelp();
+        return;
+    }
+    const config = (0, config_1.loadConfig)();
+    const repoRoot = git.getRepoRoot();
+    logger.section('🧹 Cleaning CursorFlow Resources');
+    const type = options.type || 'all';
+    if (type === 'all') {
+        await cleanWorktrees(config, repoRoot, options);
+        await cleanBranches(config, repoRoot, options);
+        await cleanLogs(config, options);
+    }
+    else if (type === 'worktrees') {
+        await cleanWorktrees(config, repoRoot, options);
+    }
+    else if (type === 'branches') {
+        await cleanBranches(config, repoRoot, options);
+    }
+    else if (type === 'logs') {
+        await cleanLogs(config, options);
+    }
+    logger.success('\n✨ Cleaning complete!');
+}
+async function cleanWorktrees(config, repoRoot, options) {
+    logger.info('\nChecking worktrees...');
+    const worktrees = git.listWorktrees(repoRoot);
+    const worktreeRoot = path.join(repoRoot, config.worktreeRoot || '_cursorflow/worktrees');
+    const toRemove = worktrees.filter(wt => {
+        // Skip main worktree
+        if (wt.path === repoRoot)
+            return false;
+        const isInsideRoot = wt.path.startsWith(worktreeRoot);
+        const hasPrefix = path.basename(wt.path).startsWith(config.worktreePrefix || 'cursorflow-');
+        return isInsideRoot || hasPrefix;
+    });
+    if (toRemove.length === 0) {
+        logger.info('  No worktrees found to clean.');
+        return;
+    }
+    for (const wt of toRemove) {
+        if (options.dryRun) {
+            logger.info(`  [DRY RUN] Would remove worktree: ${wt.path} (${wt.branch || 'no branch'})`);
+        }
+        else {
+            try {
+                logger.info(`  Removing worktree: ${wt.path}...`);
+                git.removeWorktree(wt.path, { cwd: repoRoot, force: options.force });
+                // Git worktree remove might leave the directory if it has untracked files
+                if (fs.existsSync(wt.path)) {
+                    if (options.force) {
+                        fs.rmSync(wt.path, { recursive: true, force: true });
+                        logger.info(`  (Forced removal of directory)`);
+                    }
+                    else {
+                        logger.warn(`  Directory still exists: ${wt.path} (contains untracked files). Use --force to delete anyway.`);
+                    }
+                }
+            }
+            catch (e) {
+                logger.error(`  Failed to remove worktree ${wt.path}: ${e.message}`);
+            }
+        }
+    }
+}
+async function cleanBranches(config, repoRoot, options) {
+    logger.info('\nChecking branches...');
+    // List all local branches
+    const result = git.runGitResult(['branch', '--list'], { cwd: repoRoot });
+    if (!result.success)
+        return;
+    const branches = result.stdout
+        .split('\n')
+        .map(b => b.replace('*', '').trim())
+        .filter(b => b && b !== 'main' && b !== 'master');
+    const prefix = config.branchPrefix || 'feature/';
+    const toDelete = branches.filter(b => b.startsWith(prefix));
+    if (toDelete.length === 0) {
+        logger.info('  No branches found to clean.');
+        return;
+    }
+    for (const branch of toDelete) {
+        if (options.dryRun) {
+            logger.info(`  [DRY RUN] Would delete branch: ${branch}`);
+        }
+        else {
+            try {
+                logger.info(`  Deleting branch: ${branch}...`);
+                git.deleteBranch(branch, { cwd: repoRoot, force: options.force || options.all });
+            }
+            catch (e) {
+                logger.warn(`  Could not delete branch ${branch}: ${e.message}. Use --force if it's not merged.`);
+            }
+        }
+    }
+}
+async function cleanLogs(config, options) {
+    const logsDir = (0, config_1.getLogsDir)(config);
+    logger.info(`\nChecking logs in ${logsDir}...`);
+    if (!fs.existsSync(logsDir)) {
+        logger.info('  Logs directory does not exist.');
+        return;
+    }
+    if (options.dryRun) {
+        logger.info(`  [DRY RUN] Would remove logs directory: ${logsDir}`);
+    }
+    else {
+        try {
+            logger.info(`  Removing logs...`);
+            fs.rmSync(logsDir, { recursive: true, force: true });
+            fs.mkdirSync(logsDir, { recursive: true });
+            logger.info(`  Logs cleared.`);
+        }
+        catch (e) {
+            logger.error(`  Failed to clean logs: ${e.message}`);
+        }
+    }
 }
 module.exports = clean;
 //# sourceMappingURL=clean.js.map

package/dist/cli/clean.js.map

@@ -1 +1 @@
-{"version":3,"file":"clean.js","sourceRoot":"","sources":["../../src/cli/clean.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,wDAA0C;AAS1C,SAAS,SAAS,CAAC,IAAc;IAC/B,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,oCAAoC;QACnD,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;QAClC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;KAChC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,KAAK,CAAC,IAAc;IACjC,MAAM,CAAC,OAAO,CAAC,kCAAkC,CAAC,CAAC;IAEnD,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAEhC,MAAM,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;IACxE,MAAM,CAAC,IAAI,CAAC,eAAe,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,CAAC,IAAI,CAAC,YAAY,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE1C,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAC5C,MAAM,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;AAC/D,CAAC;AAED,iBAAS,KAAK,CAAC"}
+{"version":3,"file":"clean.js","sourceRoot":"","sources":["../../src/cli/clean.ts"],"names":[],"mappings":"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"}

package/dist/cli/doctor.js

@@ -47,6 +47,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 const logger = __importStar(require("../utils/logger"));
 const doctor_1 = require("../utils/doctor");
+const cursor_agent_1 = require("../utils/cursor-agent");
 function printHelp() {
     console.log(`
 Usage: cursorflow doctor [options]
@@ -58,12 +59,13 @@ Options:
   --tasks-dir <path>     Also validate lane files (run preflight)
   --executor <type>      cursor-agent | cloud
   --no-cursor            Skip Cursor Agent install/auth checks
+  --test-agent           Run interactive agent test (to approve MCP/permissions)
   --help, -h             Show help
 
 Examples:
   cursorflow doctor
+  cursorflow doctor --test-agent
   cursorflow doctor --tasks-dir _cursorflow/tasks/demo-test/
-  cursorflow doctor --json
   `);
 }
 function parseArgs(args) {
@@ -74,6 +76,7 @@ function parseArgs(args) {
         tasksDir: tasksDirIdx >= 0 ? (args[tasksDirIdx + 1] || null) : null,
         executor: executorIdx >= 0 ? (args[executorIdx + 1] || null) : null,
         includeCursorAgentChecks: !args.includes('--no-cursor'),
+        testAgent: args.includes('--test-agent'),
     };
     if (args.includes('--help') || args.includes('-h')) {
         printHelp();
@@ -90,6 +93,8 @@ function printHumanReport(report) {
         logger.info(`tasks: ${report.context.tasksDir}`);
     if (report.issues.length === 0) {
         logger.success('All checks passed');
+        console.log('\n💡 Tip: If this is your first run, we recommend running:');
+        console.log('   cursorflow doctor --test-agent\n');
         return;
     }
     for (const issue of report.issues) {
@@ -121,6 +126,10 @@ function printHumanReport(report) {
 }
 async function doctor(args) {
     const options = parseArgs(args);
+    if (options.testAgent) {
+        const success = (0, cursor_agent_1.runInteractiveAgentTest)();
+        process.exit(success ? 0 : 1);
+    }
     const report = (0, doctor_1.runDoctor)({
         cwd: process.cwd(),
         tasksDir: options.tasksDir || undefined,
@@ -133,6 +142,10 @@ async function doctor(args) {
     else {
         printHumanReport(report);
     }
+    // Save successful doctor run status
+    if (report.ok && report.context.repoRoot) {
+        (0, doctor_1.saveDoctorStatus)(report.context.repoRoot, report);
+    }
     process.exit(report.ok ? 0 : 1);
 }
 module.exports = doctor;