Skip to main content

​
Microservice Repos from Day One

​
The Challenge

When bootstrapping the IRIS project (rebranding from PERSONA), the initial approach was to create a single iris-dev monorepo containing all packages: SDK, CLI, service, MCP server, and web frontend. This mirrored the persona-dev planning corpus structure.

​
The Insight

When you already know the service boundaries, create separate repos from the start. The refactoring cost of splitting a monorepo always exceeds the initial setup cost of separate repos — especially when contract-driven development (via a specs repo) eliminates the “shared code” justification for monorepos. This was a direct correction during the session. The initial iris-dev monorepo was created, then immediately renamed to iris-specs and repurposed as the contract repo. Five additional service repos were created alongside it.

​
Key Findings

​
1. Prior Art Validates the Pattern

choco-hq runs 31 separate repos successfully. The nestr engine required painful extraction from a monorepo to deploy to Railway (documented in SKILL-monorepo-decoupling.md). Both prove that the “monorepo is simpler” assumption fails at moderate scale.

​
2. The Specs Repo Replaces Shared Code

The primary argument for monorepos is “shared types and utilities.” A dedicated specs/contract repo (iris-specs) solves this:
  • JSON Schema is the single source of truth
  • SDKs and services derive types from the schema
  • OpenAPI contracts define API boundaries
  • No need for shared internal packages

​
3. Contract Repo Must Come First

iris-specs was created and populated before any service repo. This forces:
  • Precise type definitions before implementation
  • API contracts before endpoints
  • Acceptance criteria before code

​
4. Label Propagation Is Infrastructure

Consistent labels across 7 repos required explicit scripting (gh label create --force loop). Without this, each repo would develop its own ad-hoc label scheme.

​
What Worked Well

  • Renaming iris-dev → iris-specs pivoted cleanly without losing the git history
  • gh repo create in parallel created 5 repos in seconds
  • FORGE decomposition produced 58 issues across all repos in a single session
  • Each repo has independent CI/CD from inception

​
What Would Improve It

  • Pre-built org bootstrap script (labels + repos + boards in one command)
  • Template repos for common service patterns (FastAPI, Next.js, MCP server)
  • Automated schema validation in CI from day one (not just in iris-specs)

​
Recommendations

  1. Always ask: “Do I know the service boundaries?” If yes, start with separate repos.
  2. Create specs repo first — it’s the dependency root.
  3. Script label propagation — manual label creation doesn’t scale past 2 repos.
  4. Use FORGE decomposition immediately — don’t create repos without a ticket structure.