@litmers/cursorflow-orchestrator 0.1.9 → 0.1.13

package/commands/cursorflow-resume.md

@@ -1,192 +1,84 @@
 # CursorFlow Resume
 
 ## Overview
-Resume lanes that were interrupted or failed. You can restore the previous state or restart from scratch.
+Resume a lane that was interrupted or failed. CursorFlow allows you to continue from where the agent left off or restart the lane from the first task.
 
-## Steps
+## Usage
 
-1. **Check lane status**
-   ```bash
-   cursorflow monitor
-   ```
-
-2. **Resume a lane**
-   ```bash
-   cursorflow resume <lane-name>
-   ```
-
-3. **Clean branches before resuming**
-   ```bash
-   cursorflow resume <lane-name> --clean
-   ```
-
-4. **Restart from the beginning**
-   ```bash
-   cursorflow resume <lane-name> --restart
-   ```
+```bash
+cursorflow resume <lane-name> [options]
+```
 
 ## Options
 
 | Option | Description |
 |------|------|
-| `--run-dir <path>` | Use a specific run directory |
-| `--clean` | Clean branches before restarting |
-| `--restart` | Start over from the beginning |
-| `--force` | Continue without confirmation |
-
-## Examples
-
-### Resume the latest run
+| `<lane-name>` | The name of the lane to resume (e.g., `lane-1`) |
+| `--run-dir <path>` | Use a specific run directory (default: latest) |
+| `--restart` | Restart the lane from the very first task |
+| `--clean` | Clean up the existing worktree before resuming |
+| `--skip-doctor` | Skip pre-resume checks (not recommended) |
+
+## How it works
+1. **Pre-flight Checks**: Runs doctor validation to check for branch conflicts and Git issues.
+2. **State Loading**: Reads the `state.json` for the specified lane to find the last successful task.
+3. **Environment Restore**: Verifies the Git worktree and branch for the lane.
+4. **Execution**: Spawns a new runner that starts either from the current task index or from index 0 if `--restart` is used.
+
+## Pre-resume Validation
+
+Before resuming, CursorFlow automatically runs validation checks:
+- **Branch conflicts**: Ensures no existing branches conflict with the lane's prefix
+- **Git status**: Verifies repository state and remote connectivity
+- **Task configuration**: Validates the task JSON files are still valid
+
+To skip these checks (not recommended):
 ```bash
-# Resume the lane from the latest run
-cursorflow resume 01-dashboard
+cursorflow resume lane-1 --skip-doctor
 ```
 
-### Resume from a specific run
-```bash
-cursorflow resume --run-dir _cursorflow/logs/runs/my-run/ 01-dashboard
-```
+## Examples
 
-### Resolve branch conflicts then resume
+### Resume a failed lane
 ```bash
-# Clean up existing branches before restarting
-cursorflow resume 01-dashboard --clean
+cursorflow resume 01-lane-1
 ```
 
-### Start completely fresh
+### Restart a lane from scratch
 ```bash
-# Reset all state before restarting
-cursorflow resume 01-dashboard --restart
-```
-
-## Resume process
-
-1. **Check state**
-   - Load `state.json`
-   - Locate the last task index
-   - Inspect the worktree state
-
-2. **Restore the environment**
-   - Verify worktree accessibility
-   - Check out the branch
-   - Check for uncommitted changes
-
-3. **Resume execution**
-   - Continue from the interrupted task
-   - Or restart from the beginning (`--restart`)
-
-4. **Complete**
-   - Finish remaining tasks
-   - Commit and push changes
-
-## Sample state file
-
-```json
-{
-  "label": "01-dashboard",
-  "status": "failed",
-  "currentTaskIndex": 1,
-  "totalTasks": 3,
-  "worktreeDir": ".cursorflow/logs/worktrees/01-dashboard-abc123",
-  "pipelineBranch": "feature/dashboard-abc123",
-  "error": "Build failed",
-  "startTime": 1734567890000,
-  "endTime": null
-}
+cursorflow resume 02-lane-2 --restart
 ```
 
-## Checklist
-- [ ] Was the lane actually interrupted?
-- [ ] Does the state file exist?
-- [ ] Are there any branch conflicts?
-- [ ] Does the worktree still exist?
-- [ ] Are there uncommitted changes?
-
-## Troubleshooting
-
-### State file missing
+### Resume from an older run
 ```bash
-# Check the latest run directory
-ls -lt _cursorflow/logs/runs/
-
-# Specify a run explicitly
-cursorflow resume --run-dir _cursorflow/logs/runs/latest/ 01-dashboard
+cursorflow resume 01-lane-1 --run-dir _cursorflow/logs/runs/run-123456789/
 ```
 
-### Branch conflicts
-```bash
-# Inspect existing branches
-git branch | grep dashboard
+## Troubleshooting
 
-# Clean up and resume
-cursorflow resume 01-dashboard --clean
-```
+### State not found
+If the command fails because the state is missing, ensure you are providing the correct lane name. Use `cursorflow monitor` to see the names of the lanes in the latest run.
 
 ### Worktree issues
-```bash
-# List worktrees
-git worktree list
-
-# Remove problematic worktree
-git worktree remove <path> --force
-
-# Resume
-cursorflow resume 01-dashboard --restart
-```
-
-### Dependency blocks
-```bash
-# Verify dependencies are resolved
-cursorflow monitor
-
-# Resume after resolving
-cursorflow resume 01-dashboard
-```
+If the worktree directory was manually deleted, use the `--clean` or `--restart` flag to allow CursorFlow to recreate the environment.
 
-## Resume scenarios
+### Branch conflicts
+If resume fails due to branch conflicts:
 
-### Scenario 1: Interrupted by network errors
 ```bash
-# Simply resume from the same position
-cursorflow resume 01-dashboard
-```
+# Check what branches exist
+git branch --list "feature/*"
 
-### Scenario 2: Failed due to build errors
-```bash
-# After fixing code
-cd .cursorflow/logs/worktrees/01-dashboard-xxx/
-# ... apply fixes ...
-git add -A
-git commit -m "fix: build error"
-
-# Continue from the next task
-cursorflow resume 01-dashboard
-```
+# Clean up old CursorFlow branches
+cursorflow clean branches --dry-run
+cursorflow clean branches
 
-### Scenario 5: Timeout errors
-If the lane failed due to timeout:
-1. Increase the timeout in your task JSON:
-   ```json
-   { "timeout": 600000 }
-   ```
-2. Resume the lane:
-   ```bash
-   cursorflow resume 01-dashboard
-   ```
-
-### Scenario 3: Branch conflicts
-```bash
-# Clean branches then restart
-cursorflow resume 01-dashboard --clean
-```
-
-### Scenario 4: Start over
-```bash
-# Reset all state
-cursorflow resume 01-dashboard --restart
+# Or manually delete specific branches
+git branch -D feature/lane-1-old-branch
 ```
 
-## Next steps
-1. After resuming, monitor with `cursorflow monitor --watch`.
-2. Check the PR when the run finishes.
-3. If failures repeat, review the task configuration.
+### Changed branch prefix
+If the task JSON file's `branchPrefix` was changed after the initial run:
+1. Either restore the original prefix in the JSON
+2. Or use `--restart` to start fresh with the new prefix
+3. Or manually clean up old branches with `cursorflow clean branches`

package/commands/cursorflow-review.md

@@ -1,220 +1,56 @@
-# CursorFlow Review
+# CursorFlow Automatic Review
 
 ## Overview
-Configure the code review flow and inspect review results. Use AI-driven automatic reviews to improve code quality.
+CursorFlow features an integrated AI-powered code review system. It automatically validates task results against your defined acceptance criteria and can provide feedback to the agent for iterative improvements.
 
-## Steps
+## Configuration
 
-1. **Enable reviews**
+### Project-wide Settings
+Enable and configure the review process in your `cursorflow.config.js`:
 
-   Configure `cursorflow.config.js`:
-   ```javascript
-   module.exports = {
-     enableReview: true,
-     reviewModel: 'sonnet-4.5-thinking',
-     maxReviewIterations: 3,
-     // ...
-   };
-   ```
-
-2. **Define acceptance criteria**
-
-   Add validation criteria to the task JSON file:
-   ```json
-   {
-     "tasks": [
-       {
-         "name": "implement",
-         "model": "sonnet-4.5",
-         "acceptanceCriteria": [
-           "No build errors",
-           "No TypeScript type errors",
-           "Key functionality implemented",
-           "Tests passing"
-         ],
-         "prompt": "..."
-       }
-     ]
-   }
-   ```
-
-3. **Run reviews**
-
-   Reviews start automatically after each task completes.
-
-4. **Check review results**
-   ```bash
-   # Inspect the review output
-   cat _cursorflow/logs/runs/<lane>/review-results.json
-   ```
-
-## Review models
-
-| Model | Characteristics | Recommended use |
-|------|------|-----------|
-| `sonnet-4.5-thinking` | Strong reasoning, precise analysis | General code reviews (recommended) |
-| `opus-4.5-thinking` | Highest quality, detailed reviews | Critical code or architecture reviews |
-| `sonnet-4.5` | Faster reviews | Simple changes |
-
-## Review process
-
-1. **Task completion**
-   - Finish implementation
-   - Create a commit
-
-2. **Automatic review**
-   - Run the agent with the selected review model
-   - Verify acceptance criteria
-   - Validate build and types
-
-3. **Review outcome**
-   - `approved`: proceed to the next task
-   - `needs_changes`: send feedback → rework
-
-4. **Feedback loop**
-   - Apply fixes
-   - Re-run the review
-   - Repeat until the maximum iteration count
-
-## Review result format
-
-```json
-{
-  "status": "approved",
-  "buildSuccess": true,
-  "typeCheckSuccess": true,
-  "issues": [
-    {
-      "severity": "warning",
-      "description": "Consider adding error handling",
-      "file": "src/utils/api.js",
-      "line": 42,
-      "suggestion": "Add try-catch block"
-    }
-  ],
-  "suggestions": [
-    "Add unit tests for edge cases",
-    "Improve error messages"
-  ],
-  "summary": "Code quality is good, minor improvements suggested",
-  "reviewedBy": "sonnet-4.5-thinking",
-  "reviewedAt": "2025-12-19T18:30:00Z"
-}
-```
-
-## Examples
-
-### Standard review settings
 ```javascript
-// cursorflow.config.js
-{
-  enableReview: true,
-  reviewModel: 'sonnet-4.5-thinking',
-  maxReviewIterations: 3
-}
+module.exports = {
+  enableReview: true,               // Enable automatic reviews
+  reviewModel: 'sonnet-4.5-thinking', // Model to use for reviewing
+  maxReviewIterations: 3,           // Number of fix/re-review cycles
+  // ...
+};
 ```
 
-### Strict reviews
-```javascript
-{
-  enableReview: true,
-  reviewModel: 'opus-4.5-thinking',
-  maxReviewIterations: 5
-}
-```
-
-### Fast reviews
-```javascript
-{
-  enableReview: true,
-  reviewModel: 'sonnet-4.5',
-  maxReviewIterations: 1
-}
-```
-
-## Acceptance criteria writing guide
-
-### Good examples
-```json
-{
-  "acceptanceCriteria": [
-    "No build errors (pnpm build succeeds)",
-    "No TypeScript type errors (pnpm type-check)",
-    "All existing tests pass",
-    "Three new API endpoints implemented",
-    "Error handling logic included",
-    "Logging added"
-  ]
-}
-```
+### Task-level Criteria
+Add `acceptanceCriteria` to your task JSON to guide the reviewer:
 
-### Poor examples
 ```json
 {
-  "acceptanceCriteria": [
-    "Works well",
-    "Code looks good"
+  "tasks": [
+    {
+      "name": "implement-logic",
+      "acceptanceCriteria": [
+        "No build errors",
+        "Tests in src/tests/ pass",
+        "Code follows project style guide"
+      ],
+      "prompt": "..."
+    }
   ]
 }
 ```
 
-## Analyzing review results
-
-### When approved
-```bash
-# The next task proceeds automatically
-# Confirm in the logs
-cursorflow monitor
-```
-
-### When changes are needed
-```bash
-# Feedback is passed back to the agent
-# After rework, the review re-runs automatically
-# View feedback in the logs
-cat _cursorflow/logs/runs/<lane>/conversation.jsonl | \
-  jq 'select(.role=="reviewer")'
-```
-
-### When the max iterations are hit
-```bash
-# Continue with a warning
-# Manual review is required
-```
-
-## Checklist
-- [ ] Is review enabled?
-- [ ] Is the review model appropriate?
-- [ ] Are the acceptance criteria clear?
-- [ ] Is the max iteration count reasonable?
-- [ ] Have you inspected the review results?
-
-## Troubleshooting
-
-### Reviews are not running
-1. Confirm `enableReview: true`.
-2. Verify the review model name is valid.
-3. Check logs for errors.
-
-### Infinite review loop
-1. Check the `maxReviewIterations` setting.
-2. Ensure the acceptance criteria are achievable.
-3. Improve the task prompts.
-
-### Reviews are too strict
-1. Switch to a more lenient review model.
-2. Adjust the acceptance criteria.
-3. Increase `maxReviewIterations`.
+## The Review Process
 
-## Best practices
+1. **Completion**: When an agent finishes a task, CursorFlow spawns a reviewer agent.
+2. **Analysis**: The reviewer checks the worktree against the `acceptanceCriteria` using the `reviewModel`.
+3. **Verdict**:
+   - **Approved**: The lane proceeds to the next task.
+   - **Needs Changes**: The reviewer's feedback is sent back to the original agent.
+4. **Fix Loop**: The agent attempts to fix the issues based on the feedback. This repeats up to `maxReviewIterations`.
 
-1. **Clear criteria**: Write specific acceptance criteria.
-2. **Right model**: Choose a review model that matches task complexity.
-3. **Iterative improvement**: Don’t aim for perfection on the first pass.
-4. **Use feedback**: Apply review feedback to strengthen future tasks.
+## Monitoring Reviews
+You can track the review process in real-time using `cursorflow monitor`.
+- The lane status will change to **`reviewing`** (`👀`).
+- Reviewer feedback appears in the conversation history as a **`REVIEWER`** message.
 
-## Next steps
-1. Analyze review results.
-2. Identify recurring issue patterns.
-3. Refine task prompts and acceptance criteria.
-4. Tune the review model as needed.
+## Best Practices
+- **Specific Criteria**: Use clear, measurable criteria (e.g., "Build succeeds with `npm run build`").
+- **Thinking Models**: Use reasoning-heavy models like `sonnet-4.5-thinking` for reviews to get better results.
+- **Reasonable Iterations**: Set `maxReviewIterations` to 2 or 3 to prevent infinite loops.