Skip to main content

AI Agent Onboarding

This is the developer and AI-agent handoff for OneProtect. It applies to Codex, Claude, and any other coding assistant used by Medham, Akash, or Sharath.

Canonical source: docs/engineering/ai-agent-onboarding.md.

Required Reading​

  • AGENTS.md
  • docs/task-board.md
  • docs/engineering/feature-delivery-workflow.md
  • docs/engineering/contribution-rules.md
  • docs/engineering/documentation-standards.md
  • Relevant ADRs under docs/adr/
  • Relevant architecture notes under docs/architecture/
  • Relevant docs-site feature notes
  • Relevant .codex/skills/

Core Rules​

  • Start from latest develop.
  • Work on one scoped feature/, fix/, or docs/ branch.
  • Do not edit or push directly to main, develop, demo, or master.
  • Do not push repeatedly while iterating; GitLab runners are paid compute and every remote push can burn CI minutes.
  • Push once only after local validation passes and the branch is ready for review.
  • Do not deploy unless explicitly instructed.
  • Preserve untracked PDFs, reports, local configs, and secrets.
  • Keep Phase 1 bounded to RMM core, SIEM lite, and Compliance foundation.

Required Updates​

Every completed feature branch updates the relevant set:

  • docs/
  • docs-site/docs/
  • docs-site/docs/feature-notes/
  • docs/task-board.md
  • docs/architecture/next-milestone-readiness.md
  • ADRs when architecture decisions change
  • OpenAPI, AsyncAPI, and event schemas when contracts change
  • README, env examples, Helm, Terraform/OpenTofu docs, and runbooks when those surfaces change
  • .codex/skills/ when future agents need a durable guardrail

Taskboard updates are mandatory. Each branch must move the relevant docs/task-board.md item, update acceptance/evidence, or explicitly say why no taskboard change applied.

Skill Update Rule​

Update .codex/skills/ only for durable rules: accepted ADRs, implemented runtime boundaries, security/compliance guardrails, deployment rules, or repeated mistakes future agents must avoid. Do not store secrets or transient notes in skills.

Deployment Rule​

Feature branches validate only. They must not publish images, run Terraform or OpenTofu plan/apply, deploy Helm, deploy docs, or run AWS smoke jobs. Use local commits freely, but keep remote pushes to one final reviewed push.

Deployment-capable branches are develop, demo, and main, and deployment still requires protected variables, manual approval, and explicit GitLab dropdowns such as:

  • PUBLISH_AWS_DEV_IMAGES=true
  • PLAN_AWS_DEV_INFRA=true
  • HELM_DEPLOY_AWS_DEV=true
  • DOCS_SITE_DEPLOY_ENABLED=true
  • INSTALL_AWS_LB_CONTROLLER=true

AWS dev Helm deploys through the GitLab Agent context medhamsh/oneconnect:oneprotect-dev.

Terraform/OpenTofu owns AWS infrastructure. Helm owns application releases. Do not blur that boundary.

Validation​

For cross-boundary runtime features, run:

make validate-contracts
make typecheck-python
make lint
make test-sqlite
npm --prefix frontend test -- --run
make docs-build
git diff --cached --check

For docs-only changes, run:

make docs-build
git diff --cached --check

If a check cannot run, the branch handoff must say why.

Final Handoff Must Include​

  • branch name,
  • commit hash,
  • docs/contracts changed,
  • taskboard update,
  • API/event/schema changes,
  • migration/RLS impact,
  • validation commands run,
  • explicit non-scope preserved,
  • deployment status,
  • known follow-ups,
  • confirmation that untracked reference files were not touched.