---
Date: 2026-08-17
Author: Adolfo Reyna + Hermes
Status: superseded for day-to-day operation by `paseo_software_factory_working_model_2026-08-17.md`; retained as verified discovery/history
Tags: [paseo, software-factory, continuous-development, orchestration, home-infra]
Supersedes: the implementation approach (not history) in `paseo_centralized_agents_2026.md`
---

# Paseo Software Factory — Continuous Development Blueprint

## Executive decision

Use **Paseo as the agent/workspace control plane**, not as a new custom FastAPI task server. The prior design proposed building a separate service at `.110`; Paseo already has the essential primitives: durable workspaces, agents, isolated worktrees, provider routing, terminal/script supervision, iterative verifier loops, recurring schedules, and a Desktop control surface.

The factory should be **Git-first and project-scoped**:

```text
Intake → triage/plan → isolated implementation → automated verification
      → independent review → human approval → merge/deploy → monitored follow-up
```

Paseo coordinates the agents in that flow. Git/Gitea remains the source of truth for code, pull requests, and release history. Hermes is the human-facing dispatcher and policy layer.

## What is actually available today

Discovery on 2026-08-17 found:

| Host | Intended role | Paseo state | Factory use now |
|---|---|---|---|
| Mac mini M4 `.102` | control plane, coding, image work, native Paseo browser | **Paseo 0.2.5 daemon healthy**; relay connected; Codex, OpenCode, Pi, Hermes available; browser tools enabled | **Ready** |
| iMac `.124` | persistent Chrome / browser fallback | Paseo 0.2.3 CLI exists, but daemon is **stale/unreachable** | Re-enrol before use |
| FamReynaServer `.110` | Docker, Compose, Ollama, build/deploy; shared Paseo control host | **Paseo 0.4.0 daemon healthy on loopback**, relay connected, and an external Paseo Desktop/laptop client is attached; Codex, OpenCode, and Pi are available | **Ready for a local pilot**; add project/workspace policy before production work |
| EMI server `.119` | EMI APIs | reachable by SSH; Paseo CLI absent | Install/enrol before use |
| AeroPi5 `.126` | light checks and low-impact cron | reachable by SSH; Paseo CLI absent | Install/enrol before use |

### Important correction to the initial assumption

The Mac mini CLI can target a daemon with `--host`, but it does **not** automatically gain execution access to every LAN server. Each worker must run a reachable, paired Paseo daemon (or be deliberately reached through a secured SSH tunnel). Today, only the Mac mini is an operational Paseo execution node.

All observed daemons use loopback `127.0.0.1:6767`; that is the right security default. Do **not** expose this port to the LAN. Remote CLI access should use an SSH local-forward, e.g. a local endpoint forwarding to the target's `127.0.0.1:6767`, rather than binding a Paseo daemon publicly.

## Operating model

### 1. Stable roles

| Factory role | Responsibility | Paseo primitive | Default placement |
|---|---|---|---|
| **Dispatcher** | converts an approved request into a bounded task and picks a project/worker | Hermes + `paseo run` | Mac mini `.102` |
| **Planner** | reads the repo, states acceptance criteria, risks, and test plan; makes no edits | analysis agent | Mac mini initially |
| **Implementer** | changes code only in an isolated branch/worktree | `workspace create --isolation worktree`, agent | capability-matched node |
| **Verifier** | executes deterministic tests/builds and checks acceptance criteria | `paseo loop --verify-check` | distinct provider/node where practical |
| **Reviewer** | independently reviews diff, tests, migrations, and deployment risk; makes no edits | audit agent | different model family/provider |
| **Release steward** | prepares deployment evidence and awaits explicit human approval | agent + project scripts | target deploy node |
| **Monitor** | runs bounded post-merge/build checks and reports regressions | `schedule` or `heartbeat` | lightweight node after enrolment |

No agent receives authority to merge, deploy, restart a production service, publish, or send external communication merely because it completed implementation. Those are explicit approval gates.

### 1a. Agent, session, and workspace model

The factory treats these as distinct operational objects:

| Object | Factory meaning |
|---|---|
| **Our project** | The complete cross-server system, such as EMI. It owns server placements, repositories, services, dependencies, and approval state. |
| **Paseo project** | One repository/directory on one daemon host. |
| **Workspace** | One task place within that server-local Paseo project: a main checkout or isolated worktree. |
| **Agent** | A durable Paseo worker identity with a provider/model, workspace placement, timeline, parentage, labels, lifecycle, and archive record. |
| **Session** | The active provider conversation/runtime used by that agent. Paseo can close/release it while retaining the durable agent record for later resume. |
| **Tab** | A per-client UI view. Closing a tab is not a reliable project-lifecycle signal. |

Example:

```text
Our project: EMI
  └── Paseo project: EMI client repository on Mac mini
       └── Workspace: feature/prayer-reminders (isolated worktree)
            ├── Agent: Planner      → active provider session: plan/context
            ├── Agent: Implementer  → active provider session: code/test context
            └── Agent: Reviewer     → active provider session: diff/risk context
```

Use separate durable agents for the planner, implementer, verifier/reviewer, and release steward when their responsibilities or provider constraints differ. Preserve their final evidence in the project record, then archive completed temporary agents deliberately. Do not confuse an `idle` agent with a completed project change, or a closed provider session with a deleted agent.

### 2. Project contract

Each factory-enabled repository should add these versioned files:

```text
AGENTS.md                    # project safety boundaries and local conventions
paseo.json                   # named scripts: test, lint, typecheck, build, dev, health
.docs/factory.md             # architecture, release and verification contract
.github/ or forge CI config  # independent server-side checks when applicable
```

`paseo.json` should provide stable, non-interactive commands. Example policy, not a pasted configuration:

| Script | Required behavior |
|---|---|
| `lint` | exits non-zero for style/static failures |
| `typecheck` | exits non-zero for type failures |
| `test` | deterministic automated test suite |
| `build` | production build without publishing/deploying |
| `health` | read-only service health check, when applicable |

The factory uses those names rather than improvising commands in every task.

### 3. Per-change lifecycle

1. **Intake / classify** — Hermes records goal, project, constraints, acceptance tests, and side-effect boundaries. Small changes may skip a separate planner; ambiguous/high-risk work gets a planner or two-agent committee.
2. **Plan** — planner produces a concise implementation and verification plan. No edits.
3. **Isolate** — create a Paseo worktree from the confirmed base branch. One worktree/branch per change.
4. **Implement** — implementation agent changes only its worktree, runs project scripts, and reports exact files/tests/results.
5. **Verify** — a bounded Paseo loop runs objective checks plus an independent verifier. It is capped by both iterations and wall-clock time; failures create a clear handoff, never an endless loop.
6. **Review** — a different provider/model family checks the diff against the original acceptance criteria and flags security, migration, regression, and scope drift.
7. **Approval gate** — Hermes presents the evidence: diff/PR, commands and results, review verdict, rollout/rollback notes. The human decides whether to merge/deploy.
8. **Release / monitor** — after explicit approval, the target-specific release agent performs the requested action. A bounded post-release monitor verifies health and reports only changes/failures.

## Routing policy

Start with explicit routing rather than autonomous hardware selection. The dispatcher must name the workspace and worker node in every task.

| Work type | Primary node after enrolment | Fallback | Notes |
|---|---|---|---|
| ordinary code, planning, review | Mac mini `.102` | local Mac mini second provider | current ready path |
| UI/visual design | Mac mini `.102` | provider selected for design | browser/image support available locally |
| browser tasks | Paseo Desktop native browser on `.102` | iMac `.124` after daemon recovery | workspace-scoped browser; iMac only when persistent Chrome profile is required |
| Docker/Compose/image builds | FamReynaServer `.110` | Mac mini when safe | segregate from production deployment |
| EMI API changes | EMI server `.119` | Mac mini test clone | deploy only with explicit approval |
| light scheduled checks | AeroPi5 `.126` | Mac mini | keep workload/memory caps low |
| heavy local models | FamReynaServer `.110` | Mac mini provider | isolate model workloads from control plane |

Provider choices must be read from `~/.paseo/orchestration-preferences.json` at dispatch time, then validated against `paseo provider ls` on the actual target. Current preferences name OpenCode for implementation/audit and Claude models for planning/UI, but Claude is not currently available on the Mac mini daemon; routing must fall back to an actually available provider or surface the gap.

## Continuous-development lanes

Do not start with a single open-ended agent. Operate three deliberately bounded lanes:

### A. Change lane — event driven

Used for a user-approved feature, bug, or maintenance item.

- Creates a plan + isolated implementation worktree.
- Verifies with project scripts and an independent review.
- Ends at an approval gate.

### B. Quality lane — scheduled, read-only by default

Runs on a sensible cadence per repository (for example, nightly or on weekdays), with a fixed prompt:

- fetch/read current main branch only;
- run `lint`, `typecheck`, `test`, and `build` where supported;
- summarize deltas and failures;
- create **no edits, PRs, releases, or restarts**.

A failing quality run creates a proposed remediation task for review; it does not self-deploy a fix.

### C. Dependency/security lane — scheduled, review-first

Checks dependencies, CI failures, stale branches, and service-health evidence. It may prepare a worktree and a proposed patch, but it does not merge or deploy. Use a shorter cadence only for projects with low-cost, reliable checks.

## Paseo primitives to standardize

| Need | Standard primitive | Guardrail |
|---|---|---|
| isolated change | `paseo workspace create --isolation worktree --mode branch-off` | confirm base branch and project first |
| implementation/review task | `paseo run --workspace …` | prompt includes acceptance criteria, scripts, and side-effect limits |
| follow-up to same agent | `paseo send <agent> …` | retain continuity only for the same change |
| test-fix iteration | `paseo loop run` | include `--verify-check`, cross-provider verifier, `--max-iterations`, `--max-time`, and `--archive` |
| fresh periodic quality run | `paseo schedule create` | bounded prompt; explicit `--cwd`, provider, timezone, expiry/max runs |
| status nudge for a current agent | `paseo heartbeat create` | not a replacement for a schedule; finite lifetime |
| project servers/tests | `paseo script` backed by `paseo.json` | scripts must be safe to start/stop and observable |

## Remote-node enrolment order

This is a proposed rollout, not yet executed.

1. **Prove the factory locally on Mac mini.** Select one low-risk repository; establish its scripts and complete one change lane manually.
2. **Recover iMac `.124`.** Inspect why its existing Paseo PID is stale; only then start/upgrade its daemon and pair it to Paseo Desktop. Verify browser-specific work in a new workspace.
3. **Enrol FamReynaServer `.110`.** Install a compatible Paseo CLI/daemon, run as its service user, pair to Desktop, and verify a harmless Docker/build task.
4. **Enrol EMI `.119`.** First define application-specific deployment/restart permissions and a read-only health script. Then install/pair Paseo and prove a test-only task.
5. **Enrol AeroPi5 `.126`.** Add only low-memory monitoring/cron tasks after resource limits and cleanup behavior are defined.

For each node, require this evidence before it joins a production lane:

```text
paseo status --json              # daemon reachable and relay healthy
paseo provider ls --json         # actual provider availability
paseo workspace create …         # isolated workspace works
one read-only/build task         # result and logs verified
one policy test                  # agent refuses/halts at forbidden side effect
```

## Security and reliability policy

- Keep all daemons on loopback. Pair through the relay/Desktop or use authenticated SSH forwards; never open `6767` on the LAN.
- Keep credentials in the node's approved credential store; prompts, logs, PRs, and task summaries must never contain secrets.
- A task prompt always declares allowed directories, allowed commands, forbidden side effects, expected output, and verification commands.
- Production has separate **test**, **prepare**, and **execute** tasks. The execute task is created only after the user approves the prepared evidence.
- Use worktrees, short-lived branches, server-side CI, and rollback notes. Do not let a scheduled agent modify `main` directly.
- Prefer a different provider/model family for review or verification when available. A same-provider verifier is a temporary fallback, not the target architecture.
- Never blindly restart a Desktop-managed Paseo daemon; restart interrupts active work. Diagnose first and get approval.
- Each remote execution role has a resource budget: max concurrent agents, max runtime, and permitted script list.

## First pilot: definition of done

Pilot one repository on the Mac mini before enabling continuous schedules:

- [ ] Project `AGENTS.md`, `paseo.json`, and factory verification contract are committed.
- [ ] A planning agent produces a testable plan without edits.
- [ ] An implementation agent completes one isolated-worktree change.
- [ ] `lint`, `typecheck`, `test`, and `build` run with recorded exit status.
- [ ] A separate review agent evaluates the diff.
- [ ] Human reviews/approves the merge or deliberately rejects it.
- [ ] A finite, read-only quality schedule is created, run once, and its output is useful.
- [ ] The schedule has a documented owner, cadence, stop condition, and cost/resource cap.

Only after that pilot should the factory add remote worker nodes or an autonomous remediation loop.

## Decisions requested before implementation

1. Choose the pilot repository (recommended: a low-risk, testable project on the Mac mini rather than an active production service).
2. Choose the human approval point: PR merge only, or merge plus deployment.
3. Confirm whether remote nodes should be paired directly in Paseo Desktop, managed through secure SSH forwards, or both.
4. Approve the enrolment order and the maximum autonomy tier for each node.

## Immediate next action once approved

Create the pilot project's factory contract and run one complete **plan → worktree → implement → verify → review → approval** change lane. Do not create a recurring schedule until that lane has produced trustworthy evidence.