building-company-tool

Building a company tool

Use this as the top-level orchestration skill for a full end-to-end company service launch.

The house defaults are:

• Next.js Pages Router, used as SPA plus API routes
• No SSR, no SSG, no Server Components, no Server Actions (one App Router file is permitted, only for the Auth.js v5 route handler)
• TypeScript with strict settings
• ESLint flat config plus Prettier
• Vitest for core logic
• zod-validated env at boot
• /api/health aggregating one health-check function per dependency
• Prisma plus PostgreSQL
• Auth.js v5 ([email protected] + @auth/prisma-adapter) with the shared Okta OIDC setup.
• tRPC v11 + TanStack Query as the only sanctioned client/server layer for app-internal endpoints
• GitHub repo under the shared company GitHub org, always private (never --public)
• Railway deployment is always GitHub-connected — never railway up
• Railway workspace and production URL/domain are resolved through docs/RAILWAY_WORKSPACES.md before deployment

Check package version before starting

Fetch the latest package version and compare it to what is installed in the current agent tool:

gh api repos/unicore-railway/unicore-skills/contents/package.json \
  --jq '.content' | base64 -d | jq -r '"Latest: " + .version'

Check the installed version through the platform's plugin, skill, or marketplace UI/command.

If the installed version is behind, update unicore-skills with that platform's normal update flow, then reload or restart the tool if needed.

Stale package versions may contain outdated conventions, wrong domain names, or missing steps.

Access prerequisites

Both GitHub and Railway are invite-only. Before doing anything else, the engineer (or agent acting on their behalf) needs the right access.

Before Railway work, resolve the company context:

• Unicore uses Railway workspace Universe Unicore.
• GuruApps uses Railway workspace GuruApps.

Use docs/RAILWAY_WORKSPACES.md. If the context is not obvious, ask: "Unicore or GuruApps?"

Both contexts use the GitHub org unicore-railway and the same Okta setup. The Railway workspace and production URL/domain policy are the context-specific parts.

For access, ask Roman Shevchuk (or Oleksii Yurchenko as an alternative contact) to add you to the shared Okta group. Once in the group:

• Railway workspace: check your email and accept the Railway invite.
• GitHub org: go to okta-automations.unicore-tools.io/github, sign in with Okta, and set your GitHub username — you'll receive a GitHub org invite by email, accept it.

Don't try to scaffold a service before both invites are accepted — gh repo create and Railway project creation will both fail.

When to run zero-to-running-tool first

If the user is non-technical (PM, finance, legal, ops) or is starting from a fresh laptop, run zero-to-running-tool before the skill sequence below. It installs Node 24, Docker Desktop, gh, and the Railway CLI, and verifies GitHub org and Railway workspace access. If any of those checks fail, this orchestrator will fail later in the flow.

Skip zero-to-running-tool only when you have already verified that node -v, docker ps, gh api user/orgs includes unicore-railway, railway whoami succeeds, and railway list --json includes the target workspace. For Unicore, the target Railway workspace is Universe Unicore. For GuruApps, it is GuruApps.

Companion tools

Run skills/setting-up-agent-stack/SKILL.md after install to check companion tools.

Core companions include:

• Superpowers
• Context7 or current official docs
• Serena or another semantic navigation tool
• Browser or Playwright
• Railway CLI or Railway agent tools
• GitHub CLI

The setup skill checks each tool and asks for approval before install or config changes.

Skill sequence

1. Use bootstrapping-nextjs-service to scaffold the app, env validation, the /api/health aggregator, and the front-end, TypeScript, lint, and test defaults.
2. Use setting-up-prisma-postgres to add local PostgreSQL, Prisma, the initial schema, the database health check, and database scripts.
3. Use setting-up-nextauth-okta to add shared Okta SSO via Auth.js v5, the auth health check, local env files, and onboarding steps.
4. Use setting-up-trpc to add the tRPC server, typed client, auth-protected procedures, and the [trpc].ts catch-all handler. Every app-internal endpoint goes through here.
5. Use managing-service-env whenever a sub-skill adds or changes environment variables. Before deploy, use it to audit .env.example, .env.local, src/lib/env.ts, and Railway Variables.
6. Use creating-github-repo to publish the repository to GitHub (always private) and apply the commit message convention. No GitHub Actions CI — Railway is the only deploy gate.
7. Use deploying-to-railway to connect the repo to Railway, configure production variables, resolve the production URL/domain, and set the Railway healthcheck path to /api/health.

When to stay with this orchestrator

Use this skill when the request is broad, such as:

• "Create a new internal company tool"
• "Set up a new service for Railway"
• "New project on Railway"
• "Take this app from zero to production"

If the request is narrower, load only the matching sub-skill instead of the whole workflow.

Which sub-skills to skip:

Skip	When
setting-up-prisma-postgres	No persistent data (no database needed)
setting-up-nextauth-okta	No login or access control needed
setting-up-trpc	No app-internal API calls between client and server
managing-service-env	Never skip when any env key is added, changed, or audited

Ready-to-ship checklist

• .env.example documents every required variable
• .env.local is gitignored
• src/lib/env.ts validates every required variable with zod
• src/pages/api/health.ts registers a check function for every dependency (app, database, auth, …)
• tRPC is wired (src/server/trpc.ts, src/server/router.ts, src/pages/api/trpc/[trpc].ts, src/lib/trpc.ts); no app-internal pages/api/* handlers exist outside health.ts and auth/[...nextauth].ts
• docker compose up -d plus npm run dev works on a fresh clone
• npm run typecheck, npm run lint, npm run test, and npm run build pass locally
• curl http://localhost:3000/api/health returns 200 with every check ok
• Prisma migrations are committed and applied in production
• The shared Okta app has the correct callback URL for the resolved production URL.
• Railway has all required variables set (AUTH_SECRET, AUTH_URL, AUTH_TRUST_HOST, DATABASE_URL, and the resolved auth variables)
• Railway high-sensitivity variables are sealed according to managing-service-env
• The agent printed Required Railway Seal actions for the actual service variables
• The user confirmed required variables were sealed, or the remaining manual seal actions are listed as pending
• Railway healthcheck path is set to /api/health
• The Railway project has a one-sentence description set (Settings → Description)
• The resolved production URL serves the app
• Sign-in works end to end in production for the resolved auth provider
• The repo README.md includes local onboarding steps

After launch

Once the launch checklist is green, the team's recurring loop is edit → preview → commit → push → auto-deploy. The full step-by-step is documented in creating-github-repo under "Day-to-day workflow" — point engineers there, especially non-engineers who haven't yet internalized that git push is the deploy.