Project Context and Existing-Project Onboarding¶
1. When to Use¶
Run Project Onboarding first when:
- entering an unfamiliar repository;
- maintaining several similar projects;
- work spans sessions or is long-running;
- preparing to commit, push, deploy, restart, or write data;
- historical documents may disagree with current source.
A simple one-time read-only question may omit a Project Profile, but still identify the current repository and branch.
2. Onboarding Commands¶
python3 scripts/cp-runtime.py project-onboard \
--repo-path /path/to/repo \
--project-id logistics-system \
--project-name "AI Logistics Management System"
Use a custom directory outside the repository:
python3 scripts/cp-runtime.py project-onboard \
--repo-path /path/to/repo \
--context-dir /secure/external/context/logistics-system
3. Automatic Detection Scope¶
The tool reads only:
- Git root, branch, HEAD, remote, and workspace state;
- root-level build markers;
- first-level module markers;
- bounded framework or script declarations in files such as
pom.xmlandpackage.json.
It does not:
- scan all source deeply;
- build, test, or start the application;
- access networks, databases, or production;
- read
.envand store credentials; - label heuristic inference as confirmed.
4. Review the Profile¶
After first generation, check:
identity.repo_pathandremote_origin.- Missing primary technology under
technology. confidencefor eachentrypointsitem.- Environment, data sensitivity, and ownership under
boundaries. - Whether actual evidence resolved any
unknowns. - Whether
prohibited_pathscovers dependencies, artifacts, and sensitive directories.
5. Refresh and Validate¶
python3 scripts/cp-runtime.py project-refresh \
--profile /path/to/project-profile.json
python3 scripts/cp-runtime.py project-validate \
--profile /path/to/project-profile.json \
--repo-path /path/to/repo
Refresh primarily updates the Git baseline in Project State. The stable Project Profile binding hash changes only when project identity or governance boundaries change.
6. Project Isolation¶
Every project needs its own project ID and directory. Do not:
- copy Project A's Profile to Project B;
- reuse another project's Approval;
- put another project's APIs, schemas, credentials, or conclusions into current Project Memory;
- switch repository roots within one task state;
- rely on identical project names while ignoring remote and path validation.