# Start and maintain a project

1. Read applicable approved ADRs and specifications. Add the intended system and
   its responsibilities to systems.md; identify affected repositories in its
   specifications. Decide data ownership and deployment boundaries explicitly.
2. Create a Gitea repository under the appropriate owner. Choose visibility
   deliberately. Enable Actions and use the shared host runner labelled `mini-pc`,
   registered at user scope for `wanjakrah`, so new repositories of that owner
   inherit access without a project-specific runner registration. It needs JDK 25,
   Maven, Git, Python 3, Docker/Compose and Node/npm when a frontend is selected.
3. Clone [engineering](http://192.168.2.28:3000/wanjakrah/engineering) and check out
   a released version. Follow its README to run create-project.py with a project
   name, destination, backend/frontend/both selection and release tag. The default
   runner label is `mini-pc`; override it only when using another shared runner.
4. Review generated project-owned files, module paths, Compose project and image
   namespace. Configure deployment targets, readiness and any required dependency
   services. Keep secrets outside Git. Follow engineering's Gitea setup and
   deployment instructions for registry, release and SSH credentials.
5. Verify the engineering lock records both tag and full commit. Commit generated/
   with the local bootstrap and Maven profile. Confirm a fresh checkout builds
   and that the bootstrap can reconstruct an absent generated/ directory.
6. Before the first push, check that `mini-pc` is online and available in the new
   repository's Actions settings. Follow engineering's runner verification command;
   changing a workflow label alone does not change runner scope. Configure the
   project's registry secrets and target platform separately.
   Initialize and push the application repository, run its build workflow, and
   inspect diagnostics. Validate deployment/rollback in an isolated environment
   before a separate manual production deployment.
7. Keep implementation and operational instructions in the application's README.
   Link README and AGENTS to this landscape and pinned local engineering guidance.
   Keep executable tests, fixtures and implementation validation evidence there.
8. Verify that systems.md includes the new repository, responsibilities, data
   ownership and deployment state. Record frontend technology deviations explicitly,
   such as Waterpolo Coaching's Three.js and Vite instead of Angular.

For engineering upgrades, choose a released tag, record its commit, follow that
release's UPGRADING.md, regenerate and review the diff before committing. Only
generated/ is replaced automatically; templates do not overwrite project-owned
files on upgrades. CI checks that generated content matches the chosen release.

Local checkouts conventionally live under `~/Projecten/git/`; consumers do not
depend on those sibling directories. Landscape documentation is consulted at its
current revision. Source attribution and licenses must accompany copied resources.