---
name: darkflow
description: >-
  Unattended long-task autonomous progression workflow. Lets AI autonomously
  advance project development while the user sleeps: plan -> execute -> search
  similar -> compare gaps -> continue optimizing, looping without user confirmation.
  Each round runs 2+ hours, 3-8 rounds per night. Supports checkpoint resume,
  periodic review, pre-authorized permissions to avoid interruptions.
  Triggers: darkflow, dark flow, overnight mode, unattended, autonomous, night run.
---

# DarkFlow

> Unattended long-task autonomous progression workflow

## Core Loop (MOST IMPORTANT — must repeat)

```
Phase 1 Execute -> Phase 2 Record -> Phase 3 Search -> Phase 4 Compare -> Phase 5 Plan -> Phase 6 Commit
        ^                                                                                                    |
        └──────────────────────────── back to Phase 1, start next round ←──────────────────────────────────┘
```

**After Phase 6, AI MUST immediately return to Phase 1 for the next round. This is not optional.**

The only reason not to return to Phase 1: any "Stop Conditions" below are met.

## Startup Parameters

User provides three parameters at startup:

1. **Project path** — absolute path to the target project
2. **Final goal** — the overall goal for the entire overnight run, directional, unchanging
3. **Initial goal** — what to do in round 1 specifically, executable and verifiable

Each round, AI autonomously sets the next round's goal, writing it to `state.json`'s `next_plan` field.

## Pre-Authorization Protocol (ask everything upfront, no interruptions all night)

### Why pre-authorization

DarkFlow runs unattended at night. If a permission prompt appears mid-run, the task is stuck.
So all permissions must be asked **before starting**, then never bother the user again.

### Phase 0: What AI must do

AI must NOT start working immediately. First complete the permission checklist:

**Step 1: Confirm project path**
- Project path given in startup parameters
- Mount/grant access to the project directory with full permissions

**Step 2: Ask about additional directories**

Based on project type and task goal, list directories that might be needed:

```
Before starting DarkFlow, I need to confirm permissions.
Project path already authorized: {project_path}

Based on your task ({goal}), I may also need access to:

| # | Directory | Purpose | Needed? |
|---|-----------|---------|---------|
| 1 | {project_path}/_darkflow | DarkFlow workspace (state, reports, backups) | Required |
| 2 | {downloads_dir} | Download dependencies or reference materials | Optional |
| 3 | {sibling_project_dir} | If referencing other project code | Optional |
| 4 | {other_dir_AI_determines} | {purpose} | Optional |

Please tell me:
- Which directories to authorize? Enter numbers like "1,2,4" or "all"
- Any other directories to add?
- Or just say "project dir only" to authorize only the project path
```

**Step 3: Grant access to all authorized directories**

After user confirms:
1. Grant full access (mount/authorize) each selected directory
2. Record all authorized paths in `state.json`'s `authorized_paths` array
3. Set expiry time (default: 07:00 next day or user-specified)

**Step 4: Confirm run time**

```
All permissions ready. Confirming run time:

- Start: now ({current_time})
- End: {default 23:59 today or 07:00 tomorrow}
- Per-round target: 2 hours of uninterrupted work

Confirm? Or tell me to adjust end time.
```

User confirms → write to state.json → enter Phase 1.

### Authorization scope

**Allowed within authorized dirs (no prompts, no asking):**
- Read/write/create/delete/rename files
- Create subdirectories
- git add/commit
- Install dependencies
- Run scripts and programs

**Absolutely forbidden (even if user says "go ahead"):**
- git push
- Modify system files / registry
- Access social software
- Access unauthorized directories

### Authorization expiry

- Each round checks `authorization.expires_at`
- Not expired → continue working
- Expired → write state.json status=stopped, stopped_reason="authorization expired", stop
- **Do NOT re-ask user** (they're sleeping), just stop

## Anti-Prompt Mechanism

> **Principle: Operations that trigger permission prompts must go through safe_ops.py. Non-prompting operations use native tools directly.**

| Operation | Prompts? | How to execute |
|-----------|----------|----------------|
| Read file | No | read tool |
| Create new file | No | write tool |
| Search code | No | grep/glob tool |
| Install deps | No | bash pip install |
| git add/commit | No | bash direct |
| Web search | No | websearch tool |
| Run script | No | bash python xxx.py |
| **Delete file** | **Yes** | **bash python safe_ops.py --project PATH --round N delete --targets "file1,file2"** |
| **Overwrite existing** | **Yes** | **bash python safe_ops.py --project PATH --round N overwrite --target "file" --content-file "new_file"** |
| **Rename/Move** | **Yes** | **bash python safe_ops.py --project PATH --round N rename --src "old" --dst "new"** |
| **Batch operations** | **Yes** | **bash python safe_ops.py --project PATH --round N batch --ops-json "ops.json"** |

**safe_ops.py path**: `{SKILL_DIR}/scripts/safe_ops.py`

**NEVER use bash rm/mv/rename directly for destructive operations. Use safe_ops.py to bypass prompts.**

## Per-Round Duration (Key Improvement)

**Each round targets 2+ hours of continuous work, NOT 30 minutes.**

- Phase 1 (Execute) is the main body, should take most of each round
- Don't jump to Phase 2 (Record) after finishing one small task
- Within Phase 1: read code -> modify -> test -> fix bug -> keep going -> test again
- Only move to Phase 2 when round goal is complete or must change direction

### Per-round time allocation (~2 hours)

| Phase | Duration | Notes |
|-------|----------|-------|
| Phase 1 Execute | 90-100 min | Core development, continuous work |
| Phase 2 Record | 5 min | Update state.json and morning_report |
| Phase 3 Search | 5-10 min | websearch + search similar projects |
| Phase 4 Compare | 3-5 min | Gap analysis |
| Phase 5 Plan | 3-5 min | Set next round's goal |
| Phase 6 Commit | 2-3 min | git commit + periodic review |

### What counts as "round complete"

Any one of:
1. **Round goal achieved**: The specific task in next_plan is done
2. **Over 2 hours worked**: Actual work time exceeded 120 minutes
3. **Hard block**: Must access unauthorized dir, or 10 consecutive fix failures

**NOT a reason to end a round (keep working in Phase 1):**
- ~~Finished one small feature~~ → Start the next one
- ~~Encountered a bug~~ → Fix it and continue
- ~~Not sure how to proceed~~ → Decide best approach and continue
- ~~Searched and want to see what others did~~ → Read results and continue

## 6 Phases

### Phase 0: Initialization (first round only)

1. Confirm project path, grant full access
2. **Ask about additional directories** (see Pre-Authorization Step 2)
3. Grant access to all user-confirmed directories
4. **Confirm run time** (see Pre-Authorization Step 4)
5. Scan project structure (file tree, LOC, main modules)
6. Create `{project_path}/_darkflow/state.json` (with all auth info)
7. Create `{project_path}/_darkflow/morning_report.md`
8. Copy safe_ops.py to project's `_darkflow/` directory
9. Record git start hash (if git repo)
10. **Enter Phase 1**

### Phase 1: Execute (90-100 minutes)

- Read state.json for goal (final) and next_plan (this round)
- Execute core development tasks
- Read → read tool; Create → write tool; Search → grep/glob
- Delete/overwrite/rename → **MUST use safe_ops.py**
- Make autonomous decisions for ambiguous choices, don't pause to ask
- Auto-fix errors, up to 10 attempts, then degrade
- **Keep working until round goal is done or 2+ hours elapsed**

### Phase 2: Record (~5 minutes)

- Update state.json: what was done, completion status
- Append morning_report.md: detailed progress

### Phase 3: Search Similar (~5-10 minutes)

- websearch for similar projects, best practices
- Search GitHub for similar project code
- Record to state.json's search_findings

### Phase 4: Compare Gaps (~3-5 minutes)

- Compare current project vs search findings
- Record to state.json's gap_analysis
- **Key: Large gap is NOT a stop reason, it's motivation to keep optimizing**

### Phase 5: Optimize Plan (~3-5 minutes)

- Based on gap analysis and round results, set next round's goal
- Write to state.json's next_plan
- Round goal must: (1) be specific and executable (2) have acceptance criteria (3) serve final goal
- Record "round goal -> completion -> next round goal" to morning_report.md

### Phase 6: Backup & Commit (~2-3 minutes)

- git add -A && git commit -m "DarkFlow round N: brief description"
- Non-git: copy key files to `_darkflow_backup/round_NN/`
- Every 3 rounds: call review/evaluation to check direction

### After Phase 6

**AI MUST immediately return to Phase 1 for the next round. Check stop conditions, if none met, continue.**

## Stop Conditions (only these stop the loop)

1. **Time's up**: Current time exceeds state.json's end_time
2. **Max rounds**: current_round >= max_rounds (default 8, since each round is 2 hours)
3. **All goals complete and verified**: All planned goals achieved, features work, verified by review
4. **10 consecutive fallback failures**: 10 rounds all went to fallback/degradation
5. **Authorization expired**: authorization.expires_at has passed
6. **Out of authorized scope**: Must operate on unauthorized directory

**These are NOT stop reasons:**
- ~~Large gap~~ → Keep optimizing
- ~~Finished a round~~ → Start next round
- ~~Encountered error~~ → Auto-fix or degrade
- ~~Don't know what to do~~ → Re-plan from gap analysis

When stopping: write state.json status=stopped, record stopped_reason. No prompts, no asking.

## Checkpoint Resume

When session times out and scheduled task triggers restart:

1. Read `_darkflow/state.json`
2. Check all `authorized_paths` validity, re-mount if expired
3. Check end_time, if expired → stop
4. Check if current round is incomplete (state.json's round_in_progress)
   - Incomplete → resume from where it left off
   - Complete → start new round from next_plan
5. **Do NOT ask user, just execute**

## state.json Structure

```json
{
  "project_path": "/path/to/project",
  "goal": "Split game.py into 5 modules and fix AI spawn crash",
  "start_time": "2026-07-24T23:00:00",
  "end_time": "2026-07-25T07:00:00",
  "current_round": 3,
  "max_rounds": 8,
  "round_duration_minutes": 120,
  "round_in_progress": false,
  "round_goals": [
    {"round": 1, "goal": "Extract RenderEngine class", "result": "done", "duration_min": 95},
    {"round": 2, "goal": "Extract CollisionEngine", "result": "partial", "duration_min": 120}
  ],
  "authorized_paths": [
    {"path": "/path/to/project", "mounted": true, "scope": "full"},
    {"path": "/home/user/Downloads", "mounted": true, "scope": "full"}
  ],
  "authorization": {
    "granted_at": "2026-07-24T23:00:00",
    "expires_at": "2026-07-25T07:00:00"
  },
  "git_start_hash": "abc123...",
  "completed_features": [],
  "pending_features": [],
  "search_findings": [],
  "gap_analysis": [],
  "error_log": [],
  "review_log": [],
  "blocked_reason": null,
  "next_plan": "Resolve circular deps, complete CollisionEngine extraction",
  "status": "running"
}
```

## Scheduled Task Integration

1. User triggers DarkFlow manually before sleep (completes Phase 0 pre-auth)
2. Scheduled task triggers every 2 hours for resume
3. Scheduled task message template:
   `DarkFlow resume. Read {project_path}/_darkflow/state.json, check all authorized_paths, continue from next_plan. Do NOT ask user.`
4. Each round targets 2 hours of work; 2-hour trigger interval aligns perfectly.

## Scripts

- `scripts/safe_ops.py` — Safe destructive operations (delete/overwrite/rename/batch) with path validation, operation log, and git backup (424 lines)
- `scripts/check_status.py` — Read state.json and display current progress (85 lines)
- `scripts/generate_report.py` — Generate morning_report.md from state.json (102 lines)