Service catalog · 05 of 05 · The approach

How I'd build a company's service catalog

A proposal, not a record: this is the plan I'd bring to a platform team on day one. The weeks overlap on purpose, and the numbers are starting points, not promises.

How I'd build a company's service catalog Six overlapping phases over a first six months. Weeks 1 to 4, highlighted, discovery: interview 15 to 20 developers, shadow two onboardings, inventory what runs, rank the top journeys. Weeks 4 to 6, name the nouns: draft three to five APIs, review the schemas with the people who asked, and say what won't be built. Weeks 6 to 12, first slice: ship the top journey with one pilot team, with git as the only way in. Weeks 10 to 16, make it readable: outputs and conditions, generated portal pages, drift fails CI. Weeks 14 to 20, open to agents: the contract over MCP, narrow audited access, writes as pull requests. Ongoing, measure and grow: time to first deploy, adoption per API, retire what is unused, and go back to discovery. A loop runs from the last phase back to the first. BUILDING THE CATALOG · A FIRST SIX MONTHSWHAT WE LEARN GOES BACK INTO DISCOVERYWEEKS 1-4Discoverytalk to developersInterview 15 to 20 devsShadow two onboardingsInventory what runsRank the top journeysWEEKS 4-6Name the nounsjobs into resourcesDraft three to five APIsReview schemas withthe people who askedSay what we won't buildWEEKS 6-12First sliceone api, one teamShip the top journeyGit is the only way inPair with a pilot teamWEEKS 10-16Make it readablecontract and statusOutputs and conditionsGenerated portal pagesDrift fails CIWEEKS 14-20Open to agentssame api, boundedThe contract over MCPNarrow, audited accessWrites are pull requestsONGOINGMeasure and growclose the loopTime to first deployAdoption per APIRetire what's unusedBack to discoveryDiscovery comes first and comes back. The first catalog you ship is a draft of the second one.LEGENDStart hereLater phases, overlappingThe loop

Discovery is the product work

Before any YAML: who are our developers, what do they wait on, and what do they copy from the last project? The answers become the first APIs.

Small, then readable, then open

One API that one team loves beats fifteen nobody asked for. Make it explain itself before you let an agent near it.

Measure people, not YAML

Take a baseline during discovery, then count time to first deploy and which APIs teams actually use. An API nobody calls is a cost, and retiring it is part of the job.

Hangar · Airframe · Service catalog