A fresh session should recover the project from repository state, not from an old conversation.
engineering workflow
How I actually build.
I use agents as bounded engineering collaborators, not as a replacement for owning the system. Git holds the project contract, agents work in reviewable slices, and I keep the gates that can change risk: architecture, evidence, merge and deployment.
If two workers need the same file, I rescope or serialize instead of racing edits.
Completion points to a diff, command output, plan, rendered result, or documented manual check.
Architecture, risky scope changes, merge, apply and deployment remain explicit human gates.
The workflow is a sequence of gates.
Each stage settles a different question, leaves a durable artifact and makes ownership visible. Small work can compress gates; risk makes them explicit.
- 01
Understand
What is true now?
- artifact
- code · behavior · constraints
- owner
- human + agent
- 02
Decide
Which direction survives the tradeoffs?
- artifact
- decision · rationale
- owner
- human
- 03
Specify
What may change, and what proves success?
- artifact
- SPEC · acceptance · boundary
- owner
- agent drafts · human approves
- 04
Slice
What can one worker own cleanly?
- artifact
- tasks · dependencies · owners
- owner
- human approves
- 05
Implement
Can this bounded slice satisfy the contract?
- artifact
- branch · worktree · diff
- owner
- agent works
- 06
Validate
What external evidence supports the claim?
- artifact
- tests · plan · render
- owner
- agent gathers · human judges
- 07
Review
What did the implementer miss?
- artifact
- fresh findings
- owner
- independent reviewer
- 08
Record
What must outlive the session?
- artifact
- Git · docs · durable notes
- owner
- human confirms
Risk changes how much of the loop I make explicit.
Documentation or harmless presentation changes.
- planning
- A short brief can be enough when scope is obvious.
- proof
- Focused command or rendered/manual check.
Features, refactors and ordinary bug fixes.
- planning
- Specify acceptance, slice the work and name the owner.
- proof
- Focused checks plus complete diff review.
Permissions, secrets, networking, data stores, deployment, deletion or cost-bearing resources.
- planning
- Make decisions and safety boundaries explicit before editing.
- proof
- Full relevant gate, independent review and human authorization.
When I am uncertain, I use the higher class. A short diff is not automatically low risk; permissions, credentials, networking, data, deployment, deletion and cost-bearing resources change the review posture.
The agent plane has boundaries, not magic.
The useful part of the setup is not the number of models. Project truth, agent execution, guarded context, evidence and human authority are different layers.
control / write path selected context evidence path human authority
Human operatorintent · tradeoffs · risk acceptance
decides approves direction
Git project contractAGENTS · SPEC · ROADMAP · TASKS
source of truth 
Private knowledgeselected research · cross-project notes
bounded read 
Remote homelab hostlong-running sessions · containers · Tailscale preview
private reachability · separate host scoped agent workspace
Piremote interactive session · inspect / edit / verify
one task parallel only if independent
Herdrworkspaces · ownership · reconciliation state
optional 
Guarded MCPallow-listed context and capabilities
narrow tools 
Codex / Claude routesimplementation · analysis · independent review
routed by risk writes named paths
Branch / worktreephysical ownership · complete diff
exclusive Deterministic checkstests · Terraform plan · headless browser
evidence Fresh reviewercontract · complete diff · evidence
new context recommendation only
Human approvalarchitecture · risk · merge / apply decision
human gate CI / OIDC deliverypublishes reviewed repository state
post-merge 1 human intent→ 2 Git contract→ 3 remote sandbox + Tailscale + Pi / Herdr→ 4 Codex / Claude + MCP→ 5 diff + checks→ 6 fresh review→ 7 human merge / apply
Multiple agents only help when work splits cleanly.
I parallelize independent ownership, not overlapping edits. The coordinator tracks state and dependencies; the reviewer starts fresh on purpose.
Coordinator
state owner- loads the contract
- splits non-overlapping work
- tracks dependency order
- revalidates the combined result
Audit / research
read-only- maps current behavior
- collects evidence
- finds hidden coupling
- returns findings without competing edits
Implementation
exclusive writer- owns named paths/worktree
- writes one bounded slice
- runs focused checks
- hands back diff + evidence
Fresh reviewer
new context- starts with new context
- reads contract + full diff
- challenges skipped evidence
- recommends; does not merge
same file? rescope or serialize not “let both agents try”
Context has a lifecycle too.
Git is project truth. Private knowledge is a separate durable source. Agent sessions are temporary working memory and get only the context the approved task needs.
Git
AGENTS · specs · tasks · source · diagrams · validation instructions
clean clone must make senseAgent session
temporary · scoped · disposable
readedittestreport
only the approved task needs to fit here Obsidian + guarded MCP
research · learning · selected cross-project context
never silent project authority promotion after the task
project decisiondurable→ Git
private learningdurable→ private knowledge
working chattertemporary→ discard
I close work with evidence, not confidence.
The proof changes with the system. What stays constant is that it exists outside the agent’s own explanation and can disagree with it.
fmt · validate · plan · scan machine + human read
I read the actual plan for add/change/destroy/replace behavior before an apply can exist.
✓ lint · build · 375/1280 render machine + rendered
I inspect keyboard flow, no-JS behavior, overflow, accessibility and whether the rendered page still matches the design contract.
✓ tests · fixtures · deterministic output machine evidence
The result must be rerunnable outside the agent session; a narration of what supposedly happened is not enough.
✓ source diff · links · publication review source + publication
I check provenance, private/public boundaries and whether source and rendered output say the same thing.
✓ combined diff · full gate combined-state proof
A clean merge only proves Git found no textual conflict. I re-run evidence after branches or worktrees are reconciled.
✓The useful skills are habits I can rerun.
I keep these as explicit operating patterns instead of vague 'AI best practices'. Each one has a trigger, a behavior and a reason it exists.
Align before editing
- when I reach for it
- The request is underspecified, subjective, or likely to reopen product decisions during implementation.
- what I actually do
- I turn fuzzy intent into questions, acceptance criteria, non-goals and a durable spec before asking an agent to write code.
- why it stays
- The cheapest bug is the one removed before implementation starts.
Explain the system first
- when I reach for it
- A change crosses files, services or an ownership boundary I do not fully understand yet.
- what I actually do
- Read the code and trace the runtime/data flow before critique. Produce a compact mental model, then decide where the change belongs.
- why it stays
- Agents are good at plausible edits; architecture context is what prevents a plausible edit from landing in the wrong layer.
Slice by ownership
- when I reach for it
- A task is large enough to benefit from parallel work.
- what I actually do
- Split by paths, worktrees and dependency boundaries. One writer owns a file at a time; shared integration has a named owner.
- why it stays
- Parallel agents are only useful when coordination cost stays below the work they save.
Diagnose, then change
- when I reach for it
- A bug, failed check or unexpected behavior does not have an obvious single cause.
- what I actually do
- Reproduce, narrow the failure, inspect the relevant boundary and prefer the smallest causal fix over speculative refactoring.
- why it stays
- A faster edit is not useful if it only hides the symptom.
Prove behavior outside the chat
- when I reach for it
- Any implementation claims to be complete.
- what I actually do
- Require command output, tests, plans, rendered behavior or documented manual checks. Re-run the gate after integration.
- why it stays
- An agent report is an assertion. Evidence is something another reviewer can independently inspect.
Edit the prose like code
- when I reach for it
- Documentation, PR text or portfolio copy sounds generic, inflated or model-shaped.
- what I actually do
- Remove filler, name the actual tradeoff, keep claims sourceable and do a final human pass for language I would genuinely use.
- why it stays
- Clear writing exposes unclear thinking; polished vagueness hides it.
Tools have jobs, boundaries and proof.
I keep this list to the tools that actually shape the workflow: what each one does, where it runs, what it may touch, and how I verify the result.
agent interface
Pi
Default bounded coding session
- use it when
- One scoped task needs inspect → edit → verify without a large orchestration layer.
- why
- The terminal surface is small and the repository contract stays visible.
- boundary
- The session can propose and edit; it does not own architecture, merge or release authority.
- proof
- diff · checks · handoff
coordination
Herdr
Independent work coordination
- use it when
- Several tasks are truly independent and each can own an exclusive worktree/path boundary.
- why
- It makes workspace ownership, state, blockers and handoffs visible without turning chat into project state.
- boundary
- I do not start a standing swarm for ordinary work, and Herdr never outranks Git.
- proof
- worktrees · statuses · integration
model routes
Codex + Claude
Replaceable execution and review routes
- use it when
- The task needs a coding/reasoning route or an independent second model family for review.
- why
- Different routes are useful for different kinds of work; the contract and verification stay portable.
- boundary
- I route by risk and reasoning load, not by a permanent model leaderboard.
- proof
- independent evidence · fresh review
project state
Git + GitHub
Durable contract and review surface
- use it when
- Always: requirements, current state, ownership, diffs and review need to survive any individual session.
- why
- Branches and worktrees make ownership physical; the full diff is inspectable by humans and fresh agents.
- boundary
- A pane label, transcript or local memory never outranks repository state.
- proof
- commit · diff · PR/CI
infrastructure
Terraform + AWS
Inspectable infrastructure changes
- use it when
- Public cloud resources or delivery infrastructure change.
- why
- The intended change can be inspected as code and again as a plan before there is an apply.
- boundary
- Agents may author and inspect; human approval separates plan from merge/apply.
- proof
- fmt · validate · plan · CI
knowledge
Obsidian + MCP
Private durable context through narrow contracts
- use it when
- Cross-project research or learning is useful but should not be copied into every repository.
- why
- It separates private durable knowledge from public project truth while still allowing selected retrieval.
- boundary
- Access is allow-listed; private notes are never silent project authority or an implicit publication source.
- proof
- explicit reads/writes · audit
execution host
Remote homelab sandbox
Long-running isolated agent workspace
- use it when
- Agent work needs to keep running independently of my laptop, or I want a private preview I can reach from trusted devices without exposing a dev server publicly.
- why
- The remote homelab keeps longer sessions, containers and parallel worktrees running in a separate environment, and I can review browser-visible work over Tailscale from my laptop or phone.
- boundary
- The host is only an execution surface. Tailscale provides private reachability, not extra authority: scoped credentials, repository contracts, worktree ownership and human merge/apply/deploy gates still apply.
- proof
- worktree · process/logs · container boundary · Tailscale preview · diff + checks
rendered evidence
Headless browser QA
Browser-visible verification outside the agent report
- use it when
- A UI, reference page or browser-facing change needs proof beyond source review and a successful build.
- why
- Rendered checks catch responsive layout, overflow, console, focus and interaction failures that are easy to miss in code review.
- boundary
- Automation gathers evidence; it does not replace human visual judgment for meaningful design changes, and it never turns a preview into release authority.
- proof
- desktop/mobile render · console · keyboard · a11y · screenshots
routing policy
Choose the route for the task's risk and reasoning load, then promote it when evidence reveals hidden coupling or external effects.
Bounded, low-risk workinventory · link checks · mechanical edits · narrow research
command output or cited paths
Implementation + analysisscoped feature · focused bug fix · contract update · test review
focused checks + complete diff
High judgment or high riskarchitecture · security boundary · complex review · incident/conflicting evidence
design rationale + independent review + full relevant gate
The labels describe a portable policy, not a permanent provider ranking. Fresh context matters more to independent review than asking the same model to repeat the same assumptions.
Model names and individual CLIs are intentionally secondary. Routing by task risk and reasoning load matters more than maintaining a permanent model leaderboard.
The failure modes are part of the design.
Most of this workflow is a set of problems I do not want to discover at the end of a change.
context drift
Repository contracts + fresh review; the old chat is not required to continue.
overlapping writers
Exclusive file/worktree ownership; serialize when ownership cannot be split.
agent says “done”
Ask for the current diff and external evidence behind each completion claim.
model overkill
Start with the cheapest route that can answer the question; escalate on risk/evidence.
generic frontend
Write a visual contract, use real content early, then review the rendered page.
self-review
Important changes get a fresh reviewer without the implementer’s conversation history.
unsafe infra authority
Planning and applying remain different capabilities; destructive gates stay human.
private → public leakage
Explicit publication boundary, sanitized diagrams and source/output review.
What one change looks like end to end.
This page redesign is a useful example: the process itself should be visible in the artifact it produces.
- 01
Inspect
Read the existing How I Work page, DESIGN.md, the Homelab Atlas visual grammar and the Agent Workbench contracts before touching UI.
evidence / design contract ↗ - 02
Decide
Treat the page as an operating reference: decisions, ownership, evidence and authority first; tools and models remain supporting detail.
evidence / main flow ↗ - 03
Specify
Record the content hierarchy, responsive diagram rules, public/private boundary and acceptance criteria before implementation.
evidence / reference source ↗ - 04
Slice
Separate page integration, architecture panels, structured data and visual validation so each change has an explicit ownership surface.
evidence / ownership rules ↗ - 05
Implement
Render through the existing content-driven reference route and shared site layout, so the page inherits the real nav, footer, design tokens and Ocean background instead of recreating them.
evidence / reference route ↗ - 06
Validate
Run the repository gate and inspect actual browser output at desktop and phone widths. Check keyboard focus, reduced motion, no-JS readability, links, icon loads, console errors and overflow.
evidence / web tests ↗ - 07
Review
Give a fresh reviewer the contract, complete diff and evidence. The reviewer recommends; the implementer does not grade its own work.
evidence / review model ↗ - 08
Release gate
Human approval is the boundary. Only reviewed repository state may proceed into the existing CI/OIDC path; this workflow deliberately stops before merge/apply/deploy unless I authorize it.
evidence / apply boundary ↗
The workflow has visible influences.
I prefer attribution over pretending these patterns appeared from nowhere. I borrow ideas, test them against my own constraints, and keep the resulting workflow inspectable.
influence ≠ dependency
I did not invent every idea here. I keep the sources visible, then adapt the parts that survive my own constraints: Git-held project state, bounded agent authority, explicit evidence and human release gates.
Matt Pocock — Skills for Real Engineers
idea I borrowed
Small, composable skills that improve how an engineer and agent clarify, diagnose and implement without handing the whole process to a framework.
my adaptation
read the original source ↗ I keep that composability, but make Git-held contracts, evidence gates and human release authority the stable layer around whichever skills/models I use.
pstack — Lauren Tan / poteto
idea I borrowed
Go deep before going fast: understand the system, route work deliberately, verify behavior and clean up model-shaped prose instead of optimizing for raw output.
my adaptation
read the original source ↗ I use those ideas selectively inside my own Workbench: independent ownership for parallel work, explicit verification, fresh review and portable model routing.
Go deeper than the portfolio summary.
The portfolio is the readable entry point. The repositories and upstream influences carry the longer contracts and source material behind it.
workflow source Agent Workbenchgates · ownership/worktrees · worker briefs · model routing · evidence architecture source Homelab Atlasdiagram-first architecture · data flows · original agent-plane icons · sanitized boundaries delivery source Portfolio Infradesign contract · static delivery · Terraform · GitHub Actions/OIDC influence Matt Pocock / skillscomposable engineering skills · clarification · diagnosis · human control influence pstack / potetounderstand first · deliberate routing · verification · technical-writing / unslop