I'm tired of guessing how long I worked on this feature and having to round down (to be as honest as possible) and just leaving cash on the table.

BillMyCommits fixes that. Version 1.0.0 is live today, free during beta (probably forever).

What BillMyCommits does

BMC connects to your GitHub repos, groups them by client, and turns commit history into the bones of an invoice.

Pick a client and a date range. BMC pulls commits from every repo tied to that client, sorts each one into a category (feature, bugfix, refactor, docs, test, chore), and lets you turn the ones you want to bill into line items in one pass. Set hours and rates globally or per line, add a tax rate if you need one, export to PDF or email it to the client.

No timer to start. No timer to forget. You write code, you commit code, and the raw material for the invoice is already sitting there at the end of the month.

The privacy promise

I want to be specific here, because I'm a freelance dev too and most repos I touch are covered by NDAs that say your code doesn't leave your machine without permission.

BMC never fetches your code.

The integration calls two GitHub endpoints. One lets you pick which repos belong to a client. The other reads commit metadata: message, timestamp, author, SHA. It never calls the contents API, never pulls diffs, never reads file bodies, never touches branch contents or PR descriptions. Commit messages and metadata are what an invoice needs. Nothing else gets read.

One caveat about OAuth. GitHub's permission model is coarse. To list commits on private repos, BMC has to request the repo scope, which on paper grants full read and write access to your private repositories. GitHub offers no "commits only" scope. BMC's code never asks GitHub for your files. The privacy page spells out exactly what gets read and what doesn't.

If your commit messages contain sensitive information, that's a commit hygiene decision you already make every time you push to a code host or a CI provider. BMC treats commit messages with the same trust boundary they already cross.

Why I built this

I'm a freelance Elixir dev in Vienna. I bill in dollars and euros, I'm bad at time tracking despite knowing better, and I've watched years of revenue leak out of invoices built on "I forgot what I did that week."

What's in 1.0.0

• GitHub integration. OAuth login, repo selection, commit fetching with date filtering. GitHub only at launch.

• Multi-repo aggregation per client. Attach any number of repos to a client. Cross-repo work comes back as one list of line items.

• Automatic commit categorization. Every commit lands in one of seven buckets (feature, bugfix, refactor, docs, test, style, chore) via conventional-commit keyword matching. The commit message becomes the line item description, and you edit anything too technical before sending.

• Hour estimation. BMC suggests hours per commit. Override per line, or change the hourly rate for the whole invoice.

• Multi-currency. USD, EUR, GBP, AUD, CAD, JPY, CHF, set per client.

• PDF export and email send. Send from BMC with the PDF attached, or download it and send through your own pipeline.

• Public share links. Every invoice gets a UUID-based public URL. Send the link, no client login needed.

• Invoice status tracking. Draft, sent, paid, cancelled.

• Draft-first workflow. Nothing leaves your account without an explicit send.

What's deliberately not in 1.0.0

Things people will ask about:

• Real-time time tracking. BMC works after the fact by design. If you want a timer, run one alongside it.

• LLM-written commit summaries. Commit messages become descriptions verbatim today. Rewriting them into client-friendly prose is on the roadmap.

• Recurring or scheduled invoice generation. You start each invoice from a date range. Per-client cadences (weekly, biweekly, monthly auto-draft) are on the roadmap.

• GitLab and Bitbucket. GitHub only at launch. Other providers are on the roadmap.

• Editing an invoice after send. Status still moves through sent, paid and cancelled, but line items lock on send. Re-issue if the billed work needs to change.

• Client portals. No client login. Clients get PDFs and share links.

• Variable retainer modeling. Retainers work as fixed amounts today. Variable work against a retainer is on the roadmap.

• Multi-jurisdiction tax. One tax rate per invoice. Real multi-jurisdiction tax is its own product and I'm not going to pretend otherwise.

• Multi-user teams. BMC is for solo freelancers. Agencies aren't the audience right now.

Every one of these is a decision, not an oversight.

Pricing

BillMyCommits is free during beta (and probably forever).

Start using BMC

Sign up at billmycommits.com. Connect a repo, tell BMC which client it belongs to, and let it draft the first invoice.

If something breaks, the Discord is the fastest way to reach me. I'm in there and I answer.

Join the Discord

There's a BMC Discord.

Roadmap updates land there, bug reports get triaged fastest there, and freelance devs compare their own invoicing workflows. The early cohort is the useful place to be, because their feedback shapes the next year of the product.

I'm in there daily. If something is broken, I'd rather hear it from you in #bugs than discover it in a billing mess three months later.

Release notes

Starting with this post, every BillMyCommits release gets a blog post with a changelog.

Release post or it didn't happen.

Changelog: 1.0.0

Added

• Initial public release

• GitHub OAuth login and repo selection

• Commit fetching with date filtering and per-repo caching

• Automatic commit categorization (feature, bugfix, refactor,

• Hour estimation per commit with per-line and global overrides

• Multi-repo aggregation per client

• Multi-currency support: USD, EUR, GBP, AUD, CAD, JPY, CHF

• PDF export via ChromicPDF

• Email send with PDF attachment

• Public invoice share links (UUID-based, no auth required)

• Invoice status tracking (draft / sent / paid / cancelled)

• Client management (CRUD) with per-client hourly rate, defaul

• Account dashboard

• Draft-first send workflow

Closing

If you're a freelance dev who has ever guessed at last month's hours, try BillMyCommits.

Free during beta. No card on file. The Discord is open. And if something's wrong, I want to know.

Sign up. · Join the Discord.

By the end of part 2, the agent crew was running. The CEO summary lands on my Discord at 06:00 Vienna. The product PMs work morning and evening shifts. Twelve agents share Linear as their workplace, and one label, agent, is the trust boundary that keeps me in control of the parts I should still own.

What part 2 left out was the rest of the loop. Where does the engineer's code go? How do I review it without burning my whole day on it? Where do the marketer's landing-page drafts end up? And how do I keep all of it reachable from my phone in a café without giving the agents internet access to anything dangerous?

This is the article for the devs in the audience. It's the most concrete and most copyable of the three. The previous two were "here's how to think about it." This one is "here's the wiring."

The whole loop comes down to two daily touch points, Linear and GitHub. Everything else is automated. I'll walk through each piece in roughly the order a feature flows through the system.

The deliverables repo trick

Before I get to code, the most useful piece of plumbing in the whole setup is one I almost didn't bother to write up because it sounds too simple. It's not.

There's a single shared GitHub repo, mraaroncruz/paperclip-deliverables, where every non-code artifact from every agent lands.

The repo is organized by sub-company:

paperclip-deliverables/
├── encroach/        # Encroach marketing & assets
├── billmycommits/   # BMC marketing & assets
├── happyclients/    # HappyClients marketing & assets
├── content/         # Content Strategist drafts (cross-company)
└── talks/           # Talk Researcher proposals & outlines

Every agent that produces a non-code deliverable (landing-page copy, social posts, weekly analytics digests, talk proposals, blog drafts, screenshots, hero images, style guides) saves it into the right subdirectory and commits. The agents have write access to this repo and only this repo.

When an agent finishes a draft, it follows the same pattern across all twelve roles. The exact instruction in the Encroach Marketing agent's AGENTS.md:

All content deliverables (marketing drafts, images, social posts, etc.) MUST be saved to the shared deliverables repo at /home/aaron/Projects/deliverables/encroach/. This repo is published at https://github.com/mraaroncruz/paperclip-deliverables.

• Save files using descriptive filenames

• Commit and push your deliverables to the repo

• In your Paperclip task comments, Linear issues, and GitHub PRs, link to the file on GitHub

So the agents don't email me drafts. They don't generate files into a local folder I'd never see. They commit, push, and link. The link is what I get in Discord and Linear.

Why this matters more than it sounds:

1. I don't need access to the Mac mini to see what the agents made. I'm in a café in Vienna with a laptop. The marketer just produced three blog post drafts. They're in GitHub, and I can read them on my phone. No Tailscale into my home network, no asking the agent to send me the file. They're already in the place I'd look anyway.

2. The agents on the Mac mini don't need outbound access to my hosting. The marketer has no credentials for Cloudflare Pages, Plausible, or Kit.com. It pushes to a GitHub repo. From there, downstream automation (which I control, with its own credentials) deploys. If the agent goes haywire, the worst it can do is commit nonsense to a repo I review before any of it goes live.

3. The whole studio gets versioned. Every landing page change, blog post, and analytics digest is a commit. I can roll back a marketing change as easily as a code change. I can find out why the homepage hero changed last Tuesday and what the agent's reasoning was, because the commit message and the linked Linear issue are right there.

4. It works when I'm offline. The agents keep running on the Mac mini whether I'm online or not. When I come back, GitHub has the diffs waiting for me.

The deliverables repo is the most novel piece of plumbing in this setup, and it's a five-minute change. If you take one thing from this article, take this.

Code: the engineer agents' PR loop

The engineer agents work against the product repos themselves. For Encroach: encroach. For BillMyCommits: billmycommits_ex. For HappyClients: happyclients_ex.

The flow is what you'd expect:

1. The PM picks up an issue labeled agent from Linear and either does the work itself or delegates a Paperclip subtask to the engineer.

2. The engineer checks out a feature branch, writes the code, runs mix test and mix format (enforced in every engineer's AGENTS.md), commits.

3. Before opening the PR, the engineer captures Playwright screenshots of any changed UI (more on this below).

4. It opens the PR via the gh CLI with a description that closes the Linear issue (Closes ELB-1234), explains what changed, and embeds the screenshots.

5. It posts a Discord notification with the PR link.

6. I review. Screenshots first, then the Coolify preview if I need it, then the diff if I still need it.

7. I merge or comment back. The engineer reads the merge in the next batch and moves the Linear issue to Done.

The Linear-to-PR link is the one rule I won't bend on. Every PR description ends with Closes ELB-XXXX. Every commit message references the issue. Six months from now, when I'm asking "why does this code exist?", I can go from git blame to commit, commit to issue, issue to milestone, milestone to the original product hypothesis. Full traceability for the cost of one line per PR.

Playwright screenshots in the PR

This is the piece that surprised me most once the workflow was running.

I have a playwright-cli skill that any engineer agent can call. Before opening a PR for any UI change, the engineer:

1. Starts the Phoenix dev server.

2. Navigates to each affected route.

3. Captures screenshots at two viewports: desktop (1280x720) and mobile (375x812).

4. Embeds the screenshots in the PR body using markdown.

The skill, in summary:

# Desktop screenshot
playwright screenshot --viewport-size "1280,720" \
  http://localhost:4000/dashboard \
  dashboard-desktop.png

# Mobile screenshot
playwright screenshot --viewport-size "375,812" \
  http://localhost:4000/dashboard \
  dashboard-mobile.png

A typical PR ends up looking like:

## What changed

Added CSV export to the billing history page (Closes ELB-1234).

## Screenshots

### Desktop
![Desktop](dashboard-desktop.png)

### Mobile
![Mobile](dashboard-mobile.png)

Most of my UI review now happens in the PR itself, on my phone, before I click through to anything else. I scan the screenshots. If the change looks right at both viewports, I merge. If something looks off, a button in the wrong place or a layout glitch on mobile, I catch it without spinning anything up.

The Playwright pattern handles maybe 70% of my visual review. Coolify previews handle the other 30%, the cases where I need to click on the thing, fill in a form, or watch state change. I need both.

I didn't expect this part. Capturing mobile screenshots by default has caught more bugs than any other single change to the workflow. Left alone, the agents optimize for what they can see in the dev server, which is desktop. Forcing a mobile screenshot into every PR forces mobile awareness onto every change. Most of the layout regressions I've caught in agent PRs were mobile-only and would have been invisible without it.

Coolify previews: review the running app, not the diff

For the 30% where screenshots aren't enough, anything stateful or interactive, I rely on Coolify PR previews.

Each product has a Coolify application connected to its GitHub repo with PR preview deployments enabled. When the engineer opens a PR, Coolify builds the branch and deploys it to a unique URL like pr-142.encroach.example.com. That takes a couple of minutes, and a post-deploy webhook posts the preview URL as a comment on the PR. You could also set up something similar using AWS Cloudformation or GCS Cloud Run if you don't want to host it yourself.

I never pull the branch, install dependencies, or run anything locally to review a feature. I click the link, use the running thing, and decide.

Reviewing a 600-line PR from an agent by reading the diff is hard. The diff doesn't tell you the new validation message is too quiet, or that the export button sits below the fold on small screens. Screenshots catch the visual stuff. The running app catches everything else. The diff lies about what code does in ways that running code can't.

I now read the diff only when something in the running app or a screenshot feels off and I want to know why. The diff is a diagnosis tool, not an approval gate.

Coolify preview setup, the abridged version

This assumes you've got Coolify running on a server. Mine is on a Hetzner box. A $5 VPS works for small projects.

1. Wildcard DNS. Add a wildcard CNAME for the preview pattern:

*.encroach.example.com  →  CNAME  →  <your-coolify-server>

This single record covers all preview subdomains forever. No per-PR DNS work.

2. Enable preview deployments on the application. Settings → Preview Deployments → Enable. Coolify registers the GitHub webhook for you if you've connected your GitHub account.

3. Set the preview URL pattern. Default is pr-{number}.{domain}. Fine for most cases.

4. Enable automatic SSL. Let's Encrypt for the preview domains. This matters if your app uses cookies, service workers, or anything secure-context-only. Without it, previews behave differently from production in confusing ways.

5. Set per-application resource limits. If three products each have two previews running at once, that's six containers eating your server. Cap CPU and memory per preview container so a busy week doesn't starve your main applications.

6. Wire the post-deploy notification. Coolify can call a webhook when a deploy completes. I have a small Cloudflare Worker that listens for those events and posts the preview URL as a comment on the PR. Without this piece, the loop technically works but doesn't feel automated, and you stop using it. With it, the URL is one tap away from wherever I'm reading the morning summary.

The whole setup is an evening of work, including waiting on wildcard DNS propagation. The post-deploy worker is the part most people skip and shouldn't.

The two touch points

I said at the top that the loop comes down to two daily touch points. Here's what that looks like.

Linear is where I:

• Refine issues the PM flagged as needing my input

• Apply the agent label to issues I'm willing to hand to an agent

• Create new issues from product ideas that didn't go through the planning pipeline

• Read clarifying questions from agents and answer them as comments

• Sync with the PMs at noon Vienna

GitHub is where I:

• Review PRs (screenshots first, then the Coolify preview if needed, then the diff if anything still feels off)

• Review marketing deliverables in paperclip-deliverables

• Merge or close PRs

• Occasionally edit an AGENTS.md file when an agent drifts in some new way

Everything else is push notifications. Discord at 06:00 with the CEO summary, more Discord pings as PRs and drafts land through the day, and the noon sync with the PMs. I don't open Coolify daily. I don't open Cloudflare daily. I don't open the Mac mini's terminal. I don't tail logs.

When the system is working, which is most days, I spend something like 45 to 75 minutes on it, in a couple of focused chunks. Not zero, but a lot less than these three products would eat if I were the only one moving them forward.

When it's not working (usually an agent has drifted, an issue was scoped badly, or a milestone was wrong from step 1), I find out through blocker pings or by noticing the morning summary has too many "waiting on you" items. The fix is almost always upstream. Tighten an issue, add a line to an AGENTS.md, sharpen the milestone exit criterion. The loop itself rarely needs fixing. The inputs do.

What I'd do differently if I were starting over

A few things I learned the slow way.

Set up the deliverables repo on day one, not month two. I started without it and had agents emailing me drafts. It was bad. The repo solves a problem I didn't know I had until I'd lived with it.

Set up Playwright screenshots in PRs before Coolify previews. I had Coolify first and added screenshots later. I'd flip that order. Screenshots are cheaper to set up, faster to consume, and cover most cases.

Set up Coolify previews before you trust the engineer agent. Reviewing the engineer's first PRs from the diff was painful and made me distrust the agent more than I should have. Once previews were live, the trust came back, because I was reviewing the feature instead of the code.

Wire the post-deploy notification first, not last. The difference between automated-but-clunky and automated-and-frictionless is the URL landing where I'm already looking.

Keep it to two touch points. Every extra tool that demands daily attention is a tax. Things I tried and rejected: a separate Slack workspace for agent-to-me communication (Discord won), a dashboard pulling Linear + GitHub + Plausible into one view (felt useful, went unused), a daily standup video the agents would record (please don't).

What's not in this series

A few things I skipped, in case you're wondering.

The prompts for each agent role. They drift, they're long, and the framework matters more than the prompt. Give a model the role definition (the AGENTS.md) and the boundary agent label semantics) and it'll do most of the work. The full company is a publishable Paperclip export and I may share an anonymized version as a follow-up.

Model selection per role. The engineer uses something stronger than the marketer, the PM is in between. Specifics change with every model release, so anything I write today is wrong in three months.

Closing

Three products, three Linear projects in the ELB team, twelve agents, one Mac mini, one Hetzner box, one shared deliverables repo, two daily touch points. Three side projects that are moving forward instead of rotting on Github with the last changes 7 years ago.

The trick wasn't the agents. It was the planning that happens before them (part 1), the boundaries they work within (part 2), and the loop that keeps me out of the day-to-day except where it matters (this one). The agents are the engine. The system is what makes the engine useful.

If you build a version of this and it works for you, I'd love to hear what you changed and why. If you build it and it doesn't work, I'd love to hear that more.

Square Bracket eU is a one-person product studio in Vienna. Find me at squarebracket.io.

The first article in this series ended where most agent content starts: with a Linear project full of well-scoped milestones and issues, ready for someone to pick up.

This is the part where the agents come in. What works for me is something like a tiny org chart: a small company of narrow agents, each pinned to one job, sharing Linear as their workplace.

Currently there are twelve agents. They report up to a CEO agent who reports to me. The CEO produces a daily summary that lands on my Discord (super easy to set up a webhook for messages) at 06:00 Vienna so I have it before I sit down to work at 08:00. The product agents work in two shifts (06:30 morning batch and 21:00 evening batch), and I sync with them around noon to clear blockers and adjust priorities.

The most important piece of the whole setup isn't the agents themselves. It's a single Linear label that defines the trust boundary between work that's safe to delegate and work that isn't. I'll come back to that, but first the org chart.

The org chart

Twelve agents, organized in roughly the shape a real small company would take:

The CEO runs once daily at 06:00 Vienna, before I'm up. It reviews state across the three product PMs, surfaces ideas that bubbled up overnight, sets priorities for the day, and writes a single concise summary that lands on my Discord. The system prompt for this agent literally says: "Lead with what needs founder attention (decisions, approvals, blockers). Follow with progress updates and metrics. End with recommended next actions." That's the message format I read at 08:00.

The product PMs (BillMyCommits, Encroach, HappyClients) are the workhorses. Each one runs twice daily (06:30 and 21:00 Vienna) and owns the backlog for its product. They pick up issues, delegate to their engineer and marketing agents, update Linear state, and post status back to Paperclip and Discord. Each PM reports to the CEO. They never report directly to me, which is by design. The CEO consolidates.

The engineers and marketers (one of each per product) report to their respective PM. The engineers do the code; the marketers do the content. Both push deliverables to a shared GitHub repo (covered in part 3) so I can review from anywhere without touching the machine the agents run on.

Two cross-company agents report to the CEO directly: a Content Strategist whose job is mining git history and PRs for stories worth writing about, and a Talk Researcher that drafts conference proposals and outlines. These exist outside the per-product structure because their work cuts across all three products. (The Content Strategist has an explicit "Building with AI" series mandate, which means this article series you're reading is, in a way, an attempt by me to do a job one of my agents was supposed to do. I notice the irony.)

The whole structure lives in version-controlled markdown. Each agent has its own AGENTS.md file with its role, its skills, its boundaries, and its reporting lines. Twelve files. Adding, removing, or modifying an agent is a commit. The whole company is a git repo.

A real AGENTS.md, abridged

Here's the actual top of the Encroach PM's role definition, cleaned up slightly for the article:

---
name: "Encroach PM"
title: "Product Manager: Encroach"
reportsTo: "ceo"
skills:
  - "linear-integration"
  - "discord-notification"
  - "gh-cli-skill"
---

You are the Product Manager for Encroach, a running game app where 
runners sync data from Strava and compete to capture squares on a 
map of their city. You report to the CEO.

## Linear Integration

- Project ID: `1234` (team: SQBR)
- Use the `linear` CLI to read milestones and issues
- Pick highest-priority issues from the current milestone
- Only pick up issues labeled `paperclip-ai`. The rest require 
  founder/human attention or are not ready for you and must not 
  be picked up by agents
- State transitions:
  - Pick up issue: `Ready for Progress` → `Started`
  - Work complete: keep `Started`, link PR or draft in comment
  - Founder approves: move to `Done`

## Decision Authority

- You CAN: pick up paperclip-ai issues, delegate to your team, 
  draft specs, update Linear state, write code if needed
- You CANNOT: merge PRs, publish marketing content, or change 
  strategic direction
- Escalate interesting ideas to the CEO, not directly to the founder

The pattern is the same across all twelve agents. Frontmatter for the structural details (name, title, who they report to, what skills they can call), then a free-form description of responsibilities, boundaries, and how they work. The agent reads this on every task.

The trust boundary: the paperclip-ai label

This is the most important section in this article.

In the Linear backlog there are issues the agents can pick up and issues they can't. The mechanism that distinguishes them is one label: paperclip-ai.

Agents are told, in their system prompts, to only pick up issues with this label. Anything in the backlog without it must not be touched. Two different kinds of issues end up unlabeled and the agents can't tell them apart, which turns out to be the right property: issues that are mine (decisions, sensitive client comms, things I want to handle for skill reasons), and issues that are not yet ready for anyone (under-specified, missing context, waiting on an upstream call). From the agent's perspective those are the same (no label, don't touch), and that's exactly the rule I want.

This sounds like a small distinction. It's not. The point is that the default is "this is my work or it's not ready," and the label is an explicit act of delegation. Every time I add paperclip-ai to an issue, I'm making a deliberate decision that the work is well-scoped enough, low-blast-radius enough, and obvious enough in intent that I'm willing to let an agent do it without further review of the task itself. The PR or the draft still gets reviewed. The decision to delegate gets made once, by me, when I apply the label.

The label is gated to me. The PMs can suggest that an issue is ready for the label (in a comment), but they cannot apply it themselves. Only I can. This protects the boundary from drifting toward whatever the PM finds easiest to delegate.

In practice the label goes on issues like:

• "Add a CSV export button to the billing history page"

• "Draft a LinkedIn post about the new BMC pricing tier" (drafted by marketer, reviewed by me)

• "Fix flash notification colors for dark theme on HappyClients"

• "Write the weekly Plausible analytics digest for Encroach"

And stays off issues like:

• "Decide on the Encroach pricing tier structure"

• "Review the new Strava OAuth scopes before we ask for them"

• "Migrate the H3 grid resolution: DB rewrite required"

• "First conversation with the freelance designer about the BMC homepage"

The mix is fluid. Some weeks I'm tightening the boundary because an agent surprised me. Other weeks I'm loosening it because I'm trusting them more. The label is the dial.

Linear as the workplace

The agents don't share a chat room. They don't have a group thread. They don't ping each other on Slack.

They share Linear, and Linear is their workplace.

Concretely:

• The PM picks up an issue labeled paperclip-ai from unstarted, transitions it to started, and either does the work itself or delegates a Paperclip subtask to its engineer or marketer.

• The engineer's PR link goes in the issue as a comment.

• The marketer's drafts go in the deliverables repo (covered in part 3) with a link in the issue.

• All status flows through Linear states: triage → backlog → unstarted → started → completed. Plus canceled for things that go away.

Without a shared workplace, multi-agent setups end up passing context through summaries and ad-hoc handoffs, and every handoff loses information. The Linear ticket is the single source of truth. Every agent appends to it instead of recreating context elsewhere.

The Linear team for all three products is ELB (ElixirBytes, my pre-Square-Bracket umbrella). One team, three projects, twelve agents. The CEO sees all three projects. Each PM sees one.

What the agents are allowed to break

Each agent's AGENTS.md carries explicit "you can / you cannot" lists. The shape is consistent across the company:

• PMs can update issue state, delegate, draft specs, write code if needed. They cannot merge PRs, publish marketing content, or change strategic direction.

• Engineers can write code, run mix test and mix format, create PRs via the gh CLI, link to PRs in Paperclip and Linear. They cannot merge their own PRs, modify production environment variables, run migrations against production, or touch deploy configuration.

• Marketers can draft and commit content to the deliverables repo, draft analytics digests, propose nurture-sequence updates. They cannot publish anything externally. Drafts are surfaced for me to review, and I publish.

• CEO can reprioritize tasks, delegate to PMs, propose new initiatives. Cannot ship code, publish content, spend budget, or hire new agents without my approval.

Some of these are enforced by the agent's tools (no production credentials), some by me being the only person with merge rights, some by the system prompt and crossed fingers. The defence is layered, not airtight, and I'm honest with myself about which is which.

A consistent line in the engineer agents' prompts that does more work than it looks like:

Keep the work moving until it's done. If you need QA to review it, ask them. If you need your boss to review it, ask them. If someone needs to unblock you, assign them the ticket with a comment asking for what you need. Don't let work just sit here. You must always update your task with a comment.

Three subtle effects of that one paragraph: agents delegate up and across instead of stopping silently, blocked tickets get visibly tagged so I can see them in summaries, and there's no "I tried for a while and gave up" state. The agent always either makes progress or asks for help in writing.

The routines that surface only what needs my attention

The crew runs continuously on a Mac mini in a closet. The schedule is the part that keeps it manageable:

Discord is the only push-notification channel for the system. The webhook lives in a Paperclip secret called DISCORD_WEBHOOK_URL, and any agent can post to it via the discord-notification skill. The skill defines exactly four message formats: PR ready for review, marketing draft ready, CEO daily summary, and agent blocked. That's it. The constraint matters. Without it the channel becomes noisy, and I stop reading.

The Discord notification call, in full:

curl -H "Content-Type: application/json" \
  -d '{"content": "🔀 **PR Ready for Review**\n\n**Issue:** ELB-XXXX: Issue title\n**PR:** https://github.com/owner/repo/pull/XX\n\nScreenshots attached to the PR."}' \
  "$DISCORD_WEBHOOK_URL"

Five lines of bash. Not glamorous. Doing the actual work of keeping me in the loop.

I deliberately did not build an agent that asks me clarifying questions in real time. That sounds nice but in practice would mean my phone interrupts me throughout the day, which is exactly what I'm trying to avoid. Clarifying questions go into the issue as comments. I see them at noon when I sync, or in the next CEO summary. The system batches my involvement instead of fragmenting it.

What's next

The CEO summary lands at 06:00 Vienna, the PM morning batches run at 06:30, and by the time I'm at my desk I have a Discord message telling me what to look at first.

What's not yet covered: how the actual deliverables move from agent to me to production. The engineer opens PRs. Where do they go? How do I review them without spending all day reading diffs? How does the marketer push landing-page changes if its machine isn't on the public internet?

That's part 3: the execution loop. A shared deliverables repo on GitHub, Coolify previews for the engineering PRs, and the Playwright screenshot pattern that means I can review most UI changes without even clicking through to the staging URL.

The single biggest predictor of whether a side project of mine ships or dies is how much work I do before any code gets written.

Not the brainstorming. Brainstorming is fun and cheap and produces nothing. I mean the unglamorous middle step between "I have an idea" and "I'm building it" - turning a vague intuition into a sharp product hypothesis, then turning that hypothesis into an MVP plan with milestones concrete enough that someone other than me could execute against them.

That last clause matters more than it sounds, because in my current setup, "someone other than me" is a small team of agents. But honestly it mattered before that too. The Linear projects I scoped well got finished. The ones I scoped poorly turned into a graveyard of half-built features and a domain I'm still paying renewal on.

This is the part of my workflow that runs entirely between me and a model. No agents yet. No tickets yet. Just me and Claude in a long conversation, going from idea to plan.

Step 1. The product conversation

I open a long-form chat with a strong reasoning model and we chat out the idea.

The point of this conversation is not to get an answer. It's to expose the parts of the idea I haven't actually thought about yet. A good model will push back on weak parts of the pitch the way a good co-founder would, if I'm prompting it to do that, and I am explicitly prompting it to do that. It will ask me tough questions and I just had to scrap an idea I've been wanting to build for years from the feedback it gave me. I was pretty bummed out afterward.

A few things I've learned to insist on:

Direct pushback. Not validation. I tell the model up front that I want it to argue against the weakest parts of the idea, not encourage me. "What's wrong with this?" gets better answers than "what do you think of this?"

Comparable products, named. I make the model name three to five existing products in the space and explain how my idea would beat each one. If the answer is hand-wavy, the idea is hand-wavy. The exercise of naming concrete competitors and writing a one-sentence differentiator against each is the cheapest reality check in the world.

The "why now" question. Why hasn't someone built this already, or if they have, why does it deserve another entrant? Sometimes the answer is honest ("everyone who could build this is busy at a big company"). Sometimes the answer is "they have, and they're doing fine, and you should not build this." I'd rather find out in a Tuesday-afternoon chat than after I've burned a bunch of time (or tokens) on it.

One sharp differentiator, stated as a sentence. Not three differentiators. One. If I can't compress the reason this product is better than the alternatives into a sentence, the product isn't ready to plan yet.

I want to talk through a side project idea. Your job is to argue 
against the weakest parts of it, not encourage me. Push back when 
my reasoning is thin. Name three to five existing products in 
the space and force me to articulate, in one sentence each, why 
mine would beat them. Don't let me get away with hand-waving on 
"why now." Ready when you are.

For Encroach, the differentiator went through about four versions before it landed at "a territory-claiming game where the territory is the route you actually ran, not a generic GPS grid." That sentence is now the load-bearing test for every feature decision: does it sharpen this differentiator, or does it dilute it?

This conversation usually takes a couple of hours over a few sittings. I don't rush it. The cost of skipping it is enormous, the cost of doing it is one afternoon.

Step 2. The MVP plan

Once the product hypothesis is sharp, I move to the same model but in a different mode: planning.

The output I want from this step is a list of milestones, ordered, each one shippable on its own. Not a Gantt chart. Not a feature list. Milestones that each represent a usable thing, even if the usable thing is small.

For a typical side product the shape ends up roughly:

1. Foundation milestone (account creation, the smallest possible end-to-end flow that proves the idea works at all).

2. The differentiator milestone (the one feature that makes this product distinctive, built early, even if rough).

3. Polish-the-differentiator milestone.

4. The first real-user milestone (whatever you need to put it in front of three friends who'll actually use it).

5. Operational readiness milestone (this is the one most people skip; more on this in a moment).

6. Launch milestone (landing page live, signup flow real, first external traffic).

The exact list varies. The discipline of milestones-as-shippable-things doesn't.

A couple of patterns I've come to insist on:

The differentiator gets built early, not last. The strongest temptation in MVP planning is to ship the boring stuff first because it's well-understood, and save the "hard" differentiator feature for later. This is exactly backwards. If the differentiator turns out to be harder or duller than expected, you want to find out on day fifteen, not day sixty after you've built a beautiful house around it.
Also, with the use of agents, it's much quicker to work through the hard stuff early.

Operational readiness is its own milestone. Observability, error tracking, basic deploy automation, the smallest possible monitoring you'd want before letting strangers near the thing. Most plans I see treat these as something to tack on at the end. They are not. They are a milestone, and they go before the launch milestone, not after. I have a Paperclip skill specifically for spinning up the observability stack: Prometheus, Grafana, Sentry, OpenObserve, structured logging, because every single project needs the same thing and there's no reason to design it from scratch each time. Same for a few other recurring milestones (the Coolify staging setup, the Cloudflare Pages landing page, the Plausible analytics wiring). Skills, not bespoke planning.

Each milestone has an exit criterion stated as a behavior. "Foundation milestone is done when a user can sign up, log in, perform the core action once, and see it persisted across a logout." Not "auth complete and basic CRUD done." The behavior phrasing is what makes the milestone shippable rather than aspirational.

Step 3. Loading the plan into Linear

This is where the planning leaves the model conversation and becomes a real artifact in a real tool.

The plan goes into a new Linear project. One project per side product. The structure I use:

• Linear project = the side product (Encroach, BillMyCommits, HappyClients).

• Milestones in Linear = the milestones from the plan. Each one has the behavior-based exit criterion in its description.

• Issues = the work to get a milestone to its exit criterion. Each issue is sized to roughly a day of work or less.

• Labels = lightweight tags. The most important one, which I'll cover in detail in part two, is paperclip-ready, a flag that says "this issue is fully specified and an agent can pick it up." Issues without that label are mine, or aren't ready yet.

The skills I use here are workflow shortcuts I've built up over time: a milestone-creation skill that takes the plan output from step 2 and produces Linear milestones with proper descriptions and exit criteria; an observability-setup skill that produces the standard observability milestone with all the issues underneath it pre-filled; similar skills for Coolify staging setup and the launch-readiness checklist. A skill to use the linear terminal client instead of the MCP server (I find it faster and it seems to consume less context). These aren't fancy, they're glorified templates, but they save me an hour each time and, more importantly, they keep my projects structurally consistent. Every project has the same shape, which means every project is legible the same way.

Once the plan is loaded, the Linear project is the source of truth. Not the chat with the model. Not a Notion doc. Linear. Everything that happens from here on out: agent work, my own work, status updates, demo recordings, references Linear issues and milestones.

Why this part matters more than the agents

The strong temptation, especially if you're excited about agents, is to skip ahead and let the agents do the planning too. I've tried this. It doesn't work, for a specific reason.

The planning conversation is where my judgment is highest-leverage. It's where I'm deciding what to build and why, and those are decisions that depend on context I have and the agent doesn't, about my time, my market, my appetite for maintenance, my honest assessment of which competitors I can actually beat. I want the model in that conversation as a sparring partner. I don't want the agent system doing it for me, because the system would optimize for plausible plans rather than plans I'll actually finish.

The work done by the agents later is routine. The upstream planning is judgment. Putting an hour of careful judgment in at the top is the difference between an agent crew building the right thing well and an agent crew building the wrong thing very efficiently.

What's next

Once the Linear project exists with milestones, exit criteria, and a backlog of issues, the agents can come in. That's part two: spinning up a Paperclip subteam: a PM, a marketer, an engineer, with the routines that keep them honest and the boundaries that keep me in control of the parts I should still own.

Part three covers the execution loop itself: how the engineer agent's PRs get reviewed via Coolify previews, how a separate marketing repo lets the agents ship landing-page changes without needing access to my local machine, and how I keep my actual touch points down to two tools: Linear and GitHub, while the rest runs itself.

If you're new here: I'm Aaron, I run Square Bracket, a one-person product and dev consulting studio in Vienna, and I'm building BillMyCommits, Encroach, and HappyClients on the side while doing client work full time. The whole reason I built this workflow is that I don't have time to do it any other way.