Adopt in your project
The day-one sequence for a new Platform project: theme, harness, workflows, and registering in Health, each with the reason it is there. Written for our engineers.
This page is the practical door into everything the rest of this section describes. It is written for a Plain Concepts engineer setting up a Platform project. Every package it installs is public on npm, so the theme and the harness work anywhere; the workflows assume the Platform GitHub App, the Forge gateway and the runner fleet, and Health reads repositories in the PlainConceptsPlatform organisation.
The order below is not alphabetical. Each step is a prerequisite for the one after it, and together they are phase 2 in miniature: make the app look like a Platform app, give agents something to act on, put the agents on repository events, and measure all of it from the first day.
A new app
Install the theme
pnpm add @plainconceptsplatform/ui-theme @plainconceptsplatform/ui-components tailwindcssnpm install @plainconceptsplatform/ui-theme @plainconceptsplatform/ui-components tailwindcssyarn add @plainconceptsplatform/ui-theme @plainconceptsplatform/ui-components tailwindcssbun add @plainconceptsplatform/ui-theme @plainconceptsplatform/ui-components tailwindcssThen initialize it:
npx @plainconceptsplatform/ui-theme@latest initThis copies components.json, adds the theme import to your global stylesheet, and shows you how
to wire the Outfit font in your root layout. Both packages are public npm packages; there is no
registry configuration and no access token.
Why this is first. The tokens are the only shared artifact between Platform apps. Everything
else on this page produces code that has to look right, and it can only look right if the semantic
tokens exist before the first screen is built. From here on,
npx shadcn@latest add button card dialog gives you components that already look like a Platform
app, unmodified. The stack and the patterns are on Frontend; the .NET side is on
Backend.
Install the harness
npx @plainconceptsplatform/agent-harness@latestThen open OpenCode in the repository and run /repo-initialize.
The wizard wires the agent team, the pc-* skills, the slash commands, and an OpenSpec workspace,
and the bootstrap generates ARCHITECTURE.md and DESIGN.md. For a greenfield repository it
leaves those as placeholders to fill in as the architecture appears.
Why before the workflows. Unattended agents are only as good as what they find in the repository. The harness is what turns our conventions from pages on this site into files an agent reads on every run, so installing it first means the very first automated change already follows the rules. Details and the full command set are on AI x SDLC.
Install the workflows
npx @plainconceptsplatform/workflowsThe CLI installs the router, the workers for the routes you pick, the compile script, and the OpenCode CI config. Then:
- Add the secrets:
FORGE_API_KEYfor the Forge gateway, andBOT_APP_IDandBOT_PRIVATE_KEYfor the Platform App, which every write that has to start another workflow is made with. - Set
VERIFY_COMMANDSin each worker'senv:to the repository's own verification command. For a pnpm or full-stack repository that ispnpm verify, and it should run what CI blocks on. - Make the CI's last job hand its verdict to the merge train (
dispatch-merge-train; the CI templates in the package include it), and setCI_WORKFLOW_NAMEin the router if your CI is not calledApp: CI. - Pick a free day for the weekly audit in the router's
AUDIT_CRON, so it does not run at the same minute as every other repository on the shared fleet. - Compile with
node scripts/compile-agent-workflows.mjs, commit the generated locks, and watch one real event go through before you trust it.
The labels are created the first time a workflow applies them. workflows update later refreshes every managed file and keeps your env: values.
Why this shape. From this point the repository maintains itself on events: a label added to an issue triggers refinement or implementation, changes arrive as pull requests, a merge train takes them one at a time, and the merge gate merges what is safe and parks only what is dangerous to merge unseen. The full contract, including the label state machine and the merge gate, is on Agentic workflows.
Register in Health
The list of measured repositories lives in projects.json in the private Project-Health-Platform repository. Ask the repository for its entry rather than writing it by hand:
gh workflow run discover.yml --repo PlainConceptsPlatform/Project-Health-Platform -f repo=PlainConceptsPlatform/<repo>It reads the repository and prints a suggested entry, writing nothing. Paste it into projects.json in a pull request, and check what it cannot know:
type, such asback-front,libraryorstatic-site, which decides which engineering practices apply to the project.statusandenvironments: whether it is in production yet, and which deployment environments count as production and staging.- The opt-ins:
"engineeringExcellence": { "enabled": true }once CI publishes its facets, and"roadmap": { "enabled": true }for the Roadmap tab. - Permissions: the Platform App needs read access to Metadata, Deployments, Contents, Issues and Actions on the repository, plus Pull requests for the roadmap. The collector names anything missing rather than writing empty metrics.
Why bother on day one. Health is not only delivery numbers. From the first collection it shows whether the engineering gates are in place, whether the harness and workflows are installed and current, and where each issue's time goes, and the trends are only comparable if collection starts before the interesting period, not after. What each area measures, and what it refuses to fake, is in Measuring with Health.
An app that already exists
Nothing above requires a rewrite. Adopt in the order that gives the most value for the least risk: theme first, since importing the tokens is the single change that makes an app look like the rest of the Platform; then shadcn components as you next touch each piece of UI; then the frontend architecture as you split or add features, with new code following the convention while old code migrates gradually; and the harness and workflows once the repository is somewhere an agent can be trusted to work.
For a brownfield application that needs the full stack rather than incremental adoption, use the
platform-onboard skill.
It runs a binary preflight across six domains, then migrates one domain at a time as separate
OpenSpec changes, and it requires Playwright characterization tests before touching the frontend so
behaviour is pinned before anything moves.
What not to do
- Do not wrap the shadcn components in your own abstractions. That is how proprietary component libraries start, and principle 2 exists to prevent them.
- Do not fork the theme. Bump the package version to pick up changes.
- Do not move app-specific components into the foundation. The bar is the same need in more than one app; Contributing covers it.
- Do not point agents at the repository before the guardrails exist. Phase 2 explains why that order cannot be skipped.
Where to go next
Frontend
Architecture, theming, dependency injection, i18n, and the everyday patterns.
AI x SDLC
The harness, the workflows, and the whole agent contract on one page.
Measuring with Health
What Health measures for every project, and how to read it.
Principles
What belongs in the foundation, and what deliberately does not.
Roadmap
The Roadmap area reads every issue's labels over time to show who had it at each moment: an agent, a person, a pull request waiting to merge, or nobody. And where the human attention in an agent pipeline actually goes.
Frontend
The frontend stack, the reasoning behind it, and the patterns for everyday work.