One stack, five repos: my setup and workflow with coding agents
Vite+, pnpm, a shared quality gate and a canary-to-main release flow: the setup behind my five repositories, and the workflow I follow with coding agents.
In part 1 I described the layers of checks that give an agent feedback in under a second. Those layers only work if every project runs them the same way. Below: the setup that makes that possible, and the workflow I follow with agents on top of it.
There are five repositories: three published TypeScript libraries (overrepo, create-adr, stable-error), this site (Astro on Vercel), and quality-gate, which holds everything they share.
Start from defaults, add only what you need
My first attempt rebuilt the toolchain I use at work. It depends on a private registry and can’t leave the company network, so I dropped it for my own projects.
So I started over with one rule: start from Vite+ defaults, and add a dedicated config for a tool only when it’s needed.
Vite+ gives you one CLI, vp, for the whole loop:
vp check: formatting (Oxfmt), type-aware linting (Oxlint) and type checking.vp test: Vitest.vp pack: library builds.vp stagedandvp config: git hooks from a.vite-hooks/folder.
All tool configuration lives in one vite.config.ts. An agent that opens any of my repositories finds the same commands and the same file.
bun or pnpm?
I looked for adoption data to settle it. There’s nothing reliable: State of JS doesn’t ask the question. So I decided on context. Published npm libraries, Changesets and npm provenance all point to pnpm, and it’s the Vite+ default. One stack everywhere meant this site had to leave bun too.
The migration found a real bug. After the switch, the build failed with Cannot find module 'shiki'. The site imported a package it had never declared, and bun’s hoisting had made it work by accident. pnpm’s strict node_modules exposed it.
Before merging, I compared the two lockfiles: 682 resolved packages, 3 transitive patch differences. I also checked the switch on a Vercel preview, which caught one more problem: my “safe” install command, npx pnpm@12 install, failed with EBADDEVENGINES, because npx goes through npm and npm refuses a project that declares pnpm. Vercel already reads the pnpm version from devEngines, so the right fix was to remove my workaround.
quality-gate: one base config for every project
Every project installs quality-gate as a dev dependency and spreads its base config (this site uses defineQualityGate({ ignore: [...] }) to skip generated folders):
import { qualityGate } from "quality-gate/vite";
import { defineConfig } from "vite-plus";
export default defineConfig({
...qualityGate,
test: { ...qualityGate.test, include: ["tests/**/*.test.ts"] },
});
The gates are the same everywhere: format, lint and types, tests with coverage, dead code and unused dependencies (Knip), duplication (jscpd, fails above 5 %), secrets (secretlint), SAST (Semgrep, in CI only) and the build. quality-gate also ships the CLI the hooks call, commitlint’s config, and the reusable GitHub Actions workflows for the report and the releases.
One rule keeps it from drifting: fix the project, not the base. The base config changes only when a rule is wrong for every project. When the gate fails, the project gets patched: unexported internals, deleted dead code, an explicit entry for what Knip can’t find on its own. A project may only add what its structure needs, such as build entries, test paths and generated folders to ignore.
The rule works in both directions. When a stricter rule was right for everyone (prefer Vite+ imports over direct vitest or vite imports), it moved into the base.
Supply chain
- A 14-day cooldown on dependencies (
minimumReleaseAgeinpnpm-workspace.yaml). A version younger than two weeks doesn’t install, and compromised packages are often caught and pulled within days. Two documented exceptions, each listed with its reason and the date it ages out: an important security fix, and a version already shipped to production, which I never downgrade. The package manager itself is not under the cooldown. - No install scripts unless
allowBuildsapproves the package by name. - Dependabot with the same cooldown, targeting
canary.
Branches and releases
Every repository follows the same flow:
canaryis the default branch. Every pull request targets it. On this site,canarydeploys to a protected preview.mainis production. It only receives the release pull request,canary→main.- Merge commits only. Squash and rebase merging are disabled, in the repository settings and in the rulesets. Part 3 of this series explains why the hard way.
- Changesets. Every user-facing pull request adds one, written for the user. Internal ones (
ci,build,test,docs,chore) are exempt, exceptchore(deps): a runtime dependency update reaches users. - A bot opens the release. On every push to
canary, a shared workflow opens or updates the release pull request with the full notes. When I merge it, the release onmainversions the package, updates the changelog, tags it, creates the GitHub release, publishes to npm where needed, and bringsmainback intocanary.
Public and private repositories get the same protection. I moved to GitHub Pro so private repositories get rulesets too.
The workflow with agents
The setup covers the tools. The workflow covers how work reaches the agents and comes back.
Instructions live in the repository. Each project has an AGENTS.md, tool-neutral: Claude Code reads it through a one-line CLAUDE.md, other agents read it directly. It lists the stack, the commands, the conventions, what not to touch, and the rules for branches, merging and proof. Project skills cover repeated tasks: verify runs the full check, content writes posts with valid frontmatter.
Tickets are written for an agent to run end to end. The migration tickets for this site list what depends on bun and its pnpm equivalent, the steps, what to check before merging and the acceptance criteria. Context goes in the ticket, so a fresh agent doesn’t have to guess.
Plans come first, with break points. The agent proposes a plan, I review it, and it stops at agreed points: “we wait until 1, 2 and 3 are validated.” It also stops before anything outward-facing or irreversible.
Every pull request carries its proof: the commands that ran and their real output, what wasn’t tested, and a criticality score from 1 (content) to 5 (deploy pipeline, security). Agents may merge into canary when the score is 3 or lower, the checks are green and I asked for it. They never merge into main. Releasing stays my decision.
One skill carries the conventions to the next project. At the end of the evening, everything above went into an okq-stack agent skill: the conventions, a migration playbook, the gotchas from this series, an audit script and a script that applies the repository settings. I tested it on every repository I own that follows the stack.
When a task crosses repositories, overrepo gives the agent a map of what exists, so it clones only what the task needs.
Takeaways
- Start from tool defaults. Add a config file only when a tool needs one.
- Choose the package manager on context, not on popularity you can’t measure.
- Share one base config and fix projects, not the base.
- Put a cooldown on dependencies, with a documented exception for security fixes.
- Same branches, same release flow, same protection in every repository, public or private.
- Write instructions and tickets for an agent: in the repo, with context, steps and acceptance criteria.
In part 3, the release flow breaks: a squash merge brings back a release that had already shipped.
Share this post