Development process¶
An orientation guide for anyone working in the mcc-systems codebase — how the repo is structured, how development work flows, and where to find detailed references.
Repository structure¶
The mcc-systems monorepo contains two apps and shared infrastructure:
| What | Location |
|---|---|
| BMS app | apps/bms/ |
| Client Portal app | apps/client-portal/ |
| Supabase Edge Functions | supabase/functions/ |
| CC standing instructions | CLAUDE.md (repo root) |
| BMS project state | apps/bms/_project-state.md |
| Portal project state | apps/client-portal/_project-state.md |
| BMS page templates | apps/bms/_page-templates.md |
| Portal page templates | apps/client-portal/_page-templates.md |
| Health check script | scripts/health-check.mjs |
| Weekly AI review script | scripts/weekly-ai-review.mjs |
| GitHub Actions workflows | .github/workflows/ |
| Production deploy scripts | scripts/deploy-prod.ps1, scripts/deploy-edge-prod.ps1 |
| Documentation | docs/ |
Both apps deploy to Vercel. The BMS is internal-facing; the Client Portal is at portal2.matthewscleaningco.com.au.
Development environment setup¶
A setup guide covers everything needed to get the monorepo running from scratch: Node.js, Supabase CLI, VS Code, cloning and installing dependencies, environment variables, running dev servers, deploying Edge Functions, configuring Git identity, Vercel projects, and production deployment.
Written primarily for onboarding a second developer, but also useful as a reference when setting up a new machine.
Full detail: docs/admin/dev-environment-setup.md
The development workflow¶
All substantive development work follows the plan-before-execute model described in the governance overview. In practice this means:
- Plan in Claude.ai — describe the feature or fix, supply relevant source files, and work with Claude.ai to produce a step-by-step instruction file. Claude.ai handles regression checking, dependency tracing, and reference document verification at this stage.
- Review the instructions — read the downloaded instruction file before pasting it into Claude Code. This is the human review point between planning and execution.
- Execute in Claude Code — paste the instructions and work through them one step at a time, relaying each report-back to Claude.ai for confirmation before proceeding.
- Test on dev — build steps and dev Edge Function deployments happen automatically as part of the instructions. All testing happens against the dev environment. The automated test suite also runs in CI — unit tests on every push, integration tests on every push to master and nightly. If any test fails, the workflow flags it before deployment.
- Deploy to production — when the work is confirmed good, run
deploy-prod.ps1for database migrations anddeploy-edge-prod.ps1for Edge Functions. The nightly health check will then verify production is in sync.
Production deployment is always a deliberate, manual sequence. Claude Code never commits, pushes, or deploys to production autonomously.
Specs and plans¶
Specs¶
A spec is a document written before building a feature. It describes what to build, the data model, the UI behaviour, edge cases, and any constraints. Specs live in docs/specs/ and are the input to the plan-before-execute workflow — Claude.ai reads the spec when producing Claude Code instructions.
Writing a spec before building forces ambiguities to be resolved before any code is written, and gives Claude.ai the context it needs to produce accurate instructions.
Plans¶
A plan is a living document for a body of work that spans multiple sessions. Unlike a spec, a plan describes what work remains and in what order — it's updated as work progresses, with completed items checked off and new findings added. Plans live in docs/plans/. Claude Code is responsible for ticking off completed items as it finishes them — it has the most accurate picture of what has actually been completed, and keeping the plan current is part of its session responsibilities alongside updating _project-state.md.
Plans are useful when a piece of work is too large to complete in a single session and needs to be picked up later without losing context. Thread continuation documents serve a similar purpose for individual conversation threads; plans cover work that may span many threads over days or weeks.
Full detail on both: docs/admin/spec-and-plan-guide.md
Dashboard development (Jordan)¶
Jordan has access to a dedicated dashboards section in the BMS at src/resources/dashboards/. This area operates under its own isolation rules — described fully in the governance overview — which allow Jordan to build dashboards with full autonomy without any risk of affecting the core BMS or Client Portal.
Full detail: docs/admin/dashboard-development-guide.md