FamReynaBrain/projects/paseo_software_factory_blueprint_2026-08-17.md

Date, Author, Status, Tags, Supersedes

Date	Author	Status	Tags	Supersedes
2026-08-17	Adolfo Reyna + Hermes	superseded for day-to-day operation by `paseo_software_factory_working_model_2026-08-17.md`; retained as verified discovery/history	paseo software-factory continuous-development orchestration home-infra	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:

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:

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:

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:

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.