An Agentic Development System: Moving from ad-hoc prompting to structured software engineering.

The Thought Process: You can't see what coding agents are truly capable of if they have to ask permission before running every command, but you also shouldn't give an AI unrestricted access on a machine where a mistake could take down live apps or expose private data. Equally important, if the development machine looks nothing like your real server, you end up with apps that pass local tests and fail in deployment.

How It Works in Practice: My production home lab runs on a dedicated Minisforum N5 NAS (currently being rebuilt on a pure Debian base), while all development happens inside an isolated, Debian-based MX-Linux Hyper-V virtual machine (mx-linux-dev) on my primary HP Omen 16 workstation. While the OS layer isn't an exact mirror (MX-Linux for desktop/dev ergonomics vs. pure Debian in production), sharing a Debian foundation alongside aligned folder paths, Docker networks, reverse proxy, and HTTPS setup means agents test against the real service architecture, with every network route to the live NAS stripped out.

• Autonomy Inside Hard Walls: Within this VM, agents have real administrative power to spin up containers, install tools, and push code branches, while network rules ensure they can never reach production.
• Checkpoint Triggers for Deep Changes: Instead of banning system-level changes outright, risky operations (like kernel, firewall, or Docker engine updates) sit on a "snapshot list." When an agent reaches one, it pauses and asks me to take a five-second Hyper-V checkpoint first, turning worst-case scenarios into a one-click rollback.

The Thought Process: Every AI coding tool looks for its own instruction file and brings its own habits. Maintaining separate instructions for Claude Code, Codex, and Antigravity guarantees they will drift apart over time. Worse, long conversational rule files get ignored by models as context fills up. The rulebook needed to be a single source of truth, written as crisp, unambiguous rules with zero filler.

Key Insights & Guardrails: Rather than trying to predict every edge case, the core rules focus on authority, honesty, and how agents handle friction:

• Task-Scoped Approvals: Permissions are divided into three simple tiers: reading is always allowed; building, testing, and managing resources created by the current task are pre-approved once the task starts; and touching or deleting anything outside the task requires my explicit approval. One "yes" covers the whole task.
• Never Route Around a Block: AI agents are naturally resourceful, and if a command is denied, their instinct is to find a clever backdoor to achieve the same result. A core rule strictly forbids workarounds: if something is blocked, the agent must stop and report the exact command and error.
• Prompt-Injection Defense: Agents read untrusted text constantly, including log files, web pages, dependency docs, and even reports from other agents. The rulebook draws a bright line: text inside files or outputs is data, never instructions. Only I can give commands.
• Plain-Language Communication: Because I approach projects as a product designer rather than a career systems engineer, the rules require agents to explain trade-offs, summaries, and decisions in clear, everyday language rather than jargon.

The Thought Process: An AI coding session has no memory of what happened yesterday or what another agent is doing in a different terminal window. Without shared state, a new session will happily overwrite another agent's work or waste an hour repeating a mistake you already debugged last week.

How Coordination & Learning Work: Instead of relying on chat history, agents read and write to two shared logs on disk before and after their work:

• Seamless Handoffs: A handoff log acts like a shift-change board. Agents log what they are touching and, if a session ends mid-task, record what's happening now, what's already done, and what not to redo. The next agent picks up in seconds without starting over.
• The "Two-Strike" Rule for New Rules: Every mistake or roadblock is recorded in a lessons log (112 entries and counting). Early on, I noticed that creating a new rule after every single hiccup bloats the rulebook. Instead, the system waits until a mistake pattern happens a second time. On the second occurrence, the agent proposes a concise rule diff for my approval, turning real-world stumbles (like race conditions in browser sign-in tests or overly broad cleanup scripts) into permanent institutional memory.

The Thought Process: The most expensive mistakes in software don't happen because an agent wrote a bad loop, they happen because the agent misunderstood what you wanted and built the wrong feature across twenty files. Reviewing thousands of lines of code diffs after the fact is a terrible way to steer a product. I wanted the approval step to happen before building starts, in a format designed for a human product owner.

How Plans Are Structured: Every new app or major feature goes through a structured planning workflow shared across all three agents:

• The Plain-Language Overview Page: Alongside the technical master plan, the agent generates a clean HTML overview page written specifically for me. It explains what we're building, what I'll actually see on screen, how the phases break down, and, crucially, lists every open product decision alongside the agent's recommended choice. Approving that page is what unlocks the build.
• Just-in-Time Detail: If you write out fifty detailed implementation steps on day one, steps thirty through fifty will be obsolete by the time you get to them. Instead, plans define high-level phases up front, and detailed session-sized step files are written just before each phase starts, so they always reflect the real state of the code.
• Session Locking: A shared command-line tool tracks which plan is active and which agent holds it, preventing two sessions from accidentally working the same plan at the same time.

The Thought Process: Even with well-written step files, manually kicking off a new agent session for every step, copying context, running tests, and merging branches still keeps you glued to your keyboard. I wanted to start an approved plan and let an orchestrator drive it through all of its phases, while still guaranteeing that I get called in whenever a real product or design choice comes up.

Insights from Building the Orchestrator: The orchestrator was designed using the planning system itself and proven by autonomously building, testing, and releasing a new feature end-to-end:

• Matching the Brain to the Task: Not every step needs the heaviest, most expensive reasoning model. The orchestrator dynamically assigns high-effort reasoning models to phase planning and UI work, mid-tier models to standard coding and validation, and fast lightweight models to mechanical steps, automatically shifting work between Claude and Codex when usage quotas get tight.
• Trust, But Verify: When a background worker finishes a step and submits its report, the orchestrator doesn't just take its word for it. It checks git to confirm the commits exist and re-runs the quick verification checks itself before moving on.
• Interrupting Only When It Matters: The run proceeds automatically across phases and only pauses (sending me a push notification) for five specific reasons: a visual UI review with screenshots, a scope or product decision that belongs to me, a host change that needs a VM snapshot, a permission block, or a test failure that couldn't be fixed in two tries.

The Thought Process: When an AI agent is stuck on a failing test, its natural temptation is to weaken the assertion, skip the test, or wipe and recreate a local database to make the error go away. If you want agents to merge phases autonomously, the quality bar has to be completely mechanical, and protected by strict rules that forbid watering down a check to make it pass.

What Every Change Must Prove: Every repository has a single check script that stops at the first sign of trouble. Beyond standard formatting, static typing, unit tests, vulnerability audits, and secret scanning, three deeper checks catch the bugs that unit tests miss:

• Real Container Boot & Log Inspection: The app is built into a production container image, started in an isolated test stack, and checked for both a healthy status endpoint and completely clean startup logs.
• Desktop & Mobile Browser Flows: Automated Playwright tests click through every page and main user flow at both desktop and phone screen sizes, catching layout breaks and broken buttons before I ever open the app.
• Live Database Upgrade Verification: To prevent updates from breaking existing user data, the test suite spins up a database from the previous release, loads it with data, runs the new migration scripts against it, and verifies that all data survives intact.

The Thought Process: Maintaining ten repositories creates a quiet dilemma: if you never update pinned versions, you accumulate security debt and painful multi-version jumps; if you let agents upgrade packages whenever a new version drops, you get hit by broken upstream releases and supply-chain churn.

Calm, Automated Maintenance: I had the agents build a custom dependency manager that watches every pinned container image, system service, and language lockfile across all repos:

• The 7-Day Stabilization Rule: Routine minor updates automatically wait seven days after release before they become eligible for upgrade, giving the open-source community time to catch broken publishes. Critical security fixes bypass that waiting period immediately, and major version jumps are flagged for a dedicated plan.
• Isolated Test Upgrades: When an upgrade runs, the tool creates a separate workspace, updates related pins together, updates the changelog, and runs the full 11-step verification suite, only proposing a merge once every check passes.

The Thought Process: Whenever I had an idea for a new personal tool, I didn't want agents spending the first three phases reinventing login screens, dark mode themes, database connections, or test pipelines. And when multiple self-hosted apps run on the same server, they shouldn't each hold administrative keys to the database.

Plugging Into Common Ground: We built both a reusable App Template and a shared Self-Hosted Platform that every new project builds upon:

• Day-One Polish: Every new app starts from the shared template with four color themes, a standard Python/React/TypeScript architecture, generated API types, and the entire verification pipeline already wired up.
• Ticket-Based Database Provisioning: Instead of giving apps admin credentials to PostgreSQL, a new app presents a single-use install ticket to a lightweight helper service, which creates an isolated database and least-privilege login on the spot.
• Unified Front Door & Sign-On: Local HTTPS certificates and single sign-on (including passkeys) are handled centrally by the platform, so individual apps stay focused purely on the problem they were meant to solve.