Factory Droid CLI Missions · Visual Course

Disk artifacts

Mission state lives in ~/.factory/missions/<uuid>/ — not in chat. Here's the file map and the three contracts that matter.

Read the plain version, or open the technical layer on any section.

The big idea

Every mission gets a folder under ~/.factory/missions/<session-uuid>/. The folder UUID matches the orchestrator session's missionId tag; state.json also carries a public id like mis_e6fd3d67.

Three files form the spine:

validation-contract.md — behavioral assertions (VAL-AUTH-001, etc.). This is the source of truth for "done." Written before features are locked.

features.json — the work queue. Each feature has an id, skillName, milestone, and fulfills array linking to assertion IDs. Invariant: every assertion is claimed by exactly one feature.

handoffs/*.json — structured worker returns with salientSummary, commitId, skillFeedback, and verification notes. Validators read these plus git diffs and transcripts.

Think of it like… a legal case folder. The validation contract is the checklist of what must be proven. features.json is the task list assigning who proves each item. Handoffs are sworn statements from each contractor — not the final verdict.

Full directory map (binary JTT + docs)

Bootstrap minimum: state.json, working_directory.txt, mission.md, features.json, progress_log.jsonl. Also: AGENTS.md, architecture.md, services.yaml, library/, skills/<type>/SKILL.md, validation-state.json, validation/<milestone>/, evidence/<milestone>/, worker-transcripts.jsonl.

Local RE note

Mission 2382c4e6-f93d-4cb1-b94c-c1bfaf86c2c0 was stuck in planning with an almost-empty folder — useful as bootstrap evidence, not a mature example.

In one picture

Mission folder in three bands: planning artifacts upfront, execution outputs as workers run, validation evidence after each milestone gate.

In the code

Representative schemas — consolidated from binary strings, custom droids, and Factory architecture docs.

features.json

{
  "features": [{
    "id": "feat-auth-login",
    "description": "Implement login form and session cookie",
    "skillName": "backend-worker",
    "milestone": "foundation",
    "fulfills": ["VAL-AUTH-001", "VAL-AUTH-002"],
    "status": "pending",
    "workerSessionIds": []
  }]
}

validation-contract.md (excerpt)

### VAL-AUTH-001: Successful login
A user with valid credentials submits the login form
and is redirected to the dashboard.
Tool: agent-browser
Evidence: screenshot, network(POST /api/auth/login -> 200)

handoffs/<session>.json (protocol fields)

{
  "salientSummary": "...",
  "whatWasImplemented": "...",
  "whatWasLeftUndone": "...",
  "verification": "...",
  "commitId": "abc123",
  "skillFeedback": { "followedProcedure": true }
}

Commands

ls -la ~/.factory/missions/
cat ~/.factory/missions/<uuid>/state.json
jq . ~/.factory/missions/<uuid>/features.json

Try it: artifact browser

Select a file in the mission folder. See its role and a sample snippet.

Final lesson: Mission Control and operator moves — pause, redirect, model config, and when to intervene vs let the runner work.