Local Repo Improvement with NFLTR Workers

Use this workflow when you want NFLTR workers to make a bounded change in this repository without giving those workers direct write access to your main checkout. Workers operate on isolated clones, return git-backed patches, and leave the coordinator clone in charge of the final keep-or-reject decision.

What This Workflow Gives You

Piece	Why it matters
Isolated worker clones	Workers change their own clone instead of your primary checkout.
Planner-owned task session	One planner session can dispatch, poll, answer follow-up questions, and export task history.
Repo archive over `artifact_files`	The worker gets a read-only snapshot of the repo state you want it to use as context.
Git-backed patch result	You apply a concrete patch in the coordinator clone and rerun verification locally before keeping it.

Why this is safer than direct write access

The worker can still use local tools and a full checkout, but the only thing that crosses back into your coordinator clone is the returned patch artifact. That keeps repo mutation reviewable and makes retrying a bounded task much easier.

Safety Model

Coordinator checkout - the clone where you inspect returned patches, apply them, and rerun final verification.
Worker clones - one clone per worker, used only by nfltr worker --mcp-command "nfltr copilot-mcp ... --git-code-result".
Planner session - one nfltr mcp process driven through cmd/tools/mcp-stdio-call so the same session owns dispatch and follow-up polling.

On every task, keep constraints.allowed_paths, constraints.verification_commands, and require_changed_paths=true explicit. That is the simplest way to keep the task bounded and avoid a worker completing with prose instead of a usable patch.

Prerequisites

NFLTR_API_KEY with access to the workers you will launch
A current CLI build from this checkout
One coordinator clone and at least one worker clone
A repo archive workers can treat as a read-only reference snapshot

go build -mod vendor -o bin/nfltr ./cmd/nfltr
git archive --format=tar.gz -o /tmp/current-repo.tar.gz HEAD

Quick Validation Path

If you want the fastest end-to-end proof first, run the checked-in smoke for this exact pattern:

scripts/smoke-test-mcp-isolated-workers.sh

That script creates a temporary fixture repo, launches two isolated workers on separate clones, dispatches two tasks through one planner session, applies the returned patches to a coordinator clone, and reruns go test ./... on the merged result.

Manual Workflow

1. Start isolated workers

Run one worker per isolated clone. Keep labels simple and planner-friendly so you can target the worker deterministically.

AGENT_ID=repo-ux-worker-a \
./bin/nfltr worker \
  --name repo-ux-worker-a \
  --server grpc.nfltr.xyz:443 \
  --api-key "$NFLTR_API_KEY" \
  --labels "pool=repo-ux,track=docs,role=implementer,non_mock=true" \
  --max-tasks 1 \
  --mcp-command "./bin/nfltr copilot-mcp --cwd /path/to/worker-a --git-code-result --timeout 20m --copilot-arg=--stream=off"

For parallel fan-out, start a second worker with a different track label and a different clone path.

2. Drive one planner session from NDJSON

Use the checked-in template at cmd/tools/mcp-stdio-call/examples/local-repo-improvement.ndjson. It covers the stable tool order for this flow:

list_worker_peers
ensure_worker_capacity
probe_worker
orchestrate_task
wait_for_task
get_task_events
export_task_coordination_bundle

Before running it, replace these placeholders in the example file: REPLACE_WITH_WORKER_ID, REPLACE_WITH_ALLOWED_PATH, REPLACE_WITH_VERIFY_COMMAND, REPLACE_WITH_REPO_ARCHIVE, and REPLACE_WITH_OBJECTIVE.

go run ./cmd/tools/mcp-stdio-call \
  --command "./bin/nfltr mcp --proxy-url https://nfltr.xyz" \
  --stderr-file /tmp/local-repo-improvement.stderr \
  < cmd/tools/mcp-stdio-call/examples/local-repo-improvement.ndjson \
  > /tmp/local-repo-improvement.results.ndjson

3. Inspect the returned patch result

For git-backed worker runs, the patch usually appears in result.artifacts[0].path or result.result.patch_path. If the task is completed but neither path is present, treat it as a failed implementation run and retry with a narrower objective or stricter allowed_paths.

4. Apply the patch in the coordinator clone

git -C /path/to/coordinator apply /path/to/returned.patch

Then rerun the exact verification command from the task contract in the coordinator clone. The worker should already have run it in its own clone; the coordinator rerun is the final local confirmation before you keep or refine the change.

5. Capture task history and bundle output

Keep both planner outputs:

get_task_events for the append-only lifecycle replay
export_task_coordination_bundle for a portable status-plus-events bundle

If your rebuilt bin/nfltr exposes get_orchestration_timeline, add that call after wait_for_task when you want one compact status-plus-context view instead of stitching together separate reads.

Why This Pattern Works

It keeps planner ownership explicit: one stdio session dispatches the task and waits for completion.
It keeps worker mutations isolated: workers change only their own clone and return a patch.
It keeps validation local: the coordinator clone is the only place where you decide whether the patch is good enough to keep.
It scales to parallel work: add more isolated workers and route tasks by labels such as track=docs or track=orchestrator.

Troubleshooting

Symptom	Action
No workers in `list_worker_peers`	Confirm the workers are already started and that the same API key scope can see them.
`get_orchestration_timeline` is unknown	Rebuild `bin/nfltr` from the current checkout, then rerun `{"list_tools":true}` through `cmd/tools/mcp-stdio-call` to confirm the tool is present.
Worker returned prose but no patch	Tighten `allowed_paths`, keep `require_changed_paths=true`, and ask for a git-backed patch result explicitly.
Worker asks a question or requests another artifact	Reply with `respond_to_worker` in the same planner session so the task keeps its full history.