6.0 KiB
ZitPlane — contributor and AI-agent instructions
Project boundaries
- Official ZITADEL Go backend is an external, version-pinned image. Do not vendor, fork or modify its core source.
auth/ui/v2/owns login frontend presentation;users/ui/owns the user portal.- Authentication, OAuth/OIDC callbacks, MFA, passkeys, sessions and token/security behavior are protected logic.
- App-specific billing, product permissions, usage and license logic belong in the individual apps, not ZitPlane.
Phase rules
- Inspect Git status and read
docs/PHASES.mdbefore editing. - Require an explicitly approved scope before each new phase; stay within its exact allowed paths.
- Do not add fake runnable scaffolds, dependency versions, secret values or speculative upstream imports.
- On UI-only tasks edit components, styles and approved assets only; preserve auth flows and API contracts.
- Mock previews and test identities must be confined to development/test; never enable auth bypass in production.
- Run one focused verification, inspect exact diff, update relevant docs, and make one local Git commit per approved phase.
- Never push, deploy, create tags, access real user accounts or alter production without explicit approval.
Security and portability
- No credentials, master keys, database data, cert private keys, session tokens or
.envin Git. - Production configuration must fail closed if required secrets, HTTPS or storage configuration are absent.
- Lock external image versions and upstream Login V2 revision; document upgrade procedure.
- Prefer readable React/TypeScript components, accessibility, responsive layouts and small reusable tokens.
- Never modify upstream authentication machinery to accommodate an AI-generated UI without a separate security-approved scope.
Developer experience
- Keep README files accurate for the current phase. Do not claim an app runs before it is integrated.
- Develop on local/test ZITADEL and synthetic users. Verify OIDC, MFA/passkey and redirect flows before release.
Documentation-first rule — mandatory for ALL future changes
Three distinct Git-tracked knowledge areas are required and must stay synchronized:
notes/— development-time scope, planning and phase history. Before ANY code/config/page/feature/fix/add/remove/refactor (including documentation changes), first write or update a scoped Markdown plan there. State baseline, date, goals, exact allowed paths, exclusions, intended changes, prerequisites, risk and acceptance criteria. Keep in-progress decision log, source evidence, blockers and after-action result. Every update/fix/phase needs a dated entry innotes/CHANGELOG.md; do not delete historic outcomes.project/— permanent developer/AI reference. In the same approved phase, update exact developer descriptions of EVERY affected feature/page/module/file/function, logic location and rationale, dependencies and setup, API/data/security flow, tests/evidence and change history. Maintainproject/FILE-MAP.md,project/FUNCTIONS.md,project/FEATURES-AND-PAGES.md,project/SETUP-AND-DEPENDENCIES.md,project/CHANGELOG.md, andproject/SOURCE-INVENTORY.mdwhere relevant. Describe unchanged source only when actually inspected; never fabricate behavior.docs/— permanent end-user/operator guidance. In the same approved phase, document every changed accessible page, button/action, route, feature, permission, setup step, failure case, security or usage limitation in plain, beginner-friendly instructions. Updatedocs/USER-GUIDE.md,docs/SETUP-GUIDE.md,docs/FEATURES-STATUS.md,docs/TROUBLESHOOTING.mdand existing focused guides as applicable. Never advertise incomplete source as tested or deployed.
Mandatory Markdown and manifest policy
- Every new ZitPlane-owned folder, including each knowledge-area folder and newly created subfolder, must include its own
README.mddescribing why it exists, who uses it, when/how to update it, and literalMINIFEST.mdlisting its actual direct files/subfolders, owners/purposes, phase and status. The exact filename isMINIFEST.md(notMANIFEST.md). - When a first-party file/folder is added, moved or removed, update the relevant parent
MINIFEST.md, root navigation and source inventory in the same phase. Do not include ignored/generated data in Git manifests as if tracked. - Do not edit third-party/upstream/vendor-imported source (such as nested
auth/ui/v2/apps/login/,packages/orproto/) just to inject ZitPlane docs. Preserve upstream byte-for-byte identity and document their paths inproject/SOURCE-INVENTORY.md; only modify upstream content with explicit scope and license review. - For preexisting first-party directories not changed in the current phase, add missing per-folder guidance when an approved phase next modifies their structure. Knowledge-area folders
notes/,project/,docs/are mandatory immediately. README.mdis the human-friendly entrypoint;MINIFEST.mdis the exact direct-child inventory; avoid duplicating long feature explanations across both.
Every change must leave a consistent audit trail
Before: audit Git status/current source, create notes/<PHASE>.md scope/plan, and confirm approval.
During: keep a concise change/decision log and identify each touched function/page/file and user-facing consequence.
After: update relevant project/ and docs/ files plus manifests, record exact implementation/test/CI results, commit SHA and residual risk in notes/ and project/CHANGELOG.md. Perform one focused scope/patch audit and commit as approved. Do not say a CI/build/runtime test passed unless it actually ran.
Safety: Never write passwords, personal data, .env contents, secrets, PATs, credentials, private keys or unredacted token-bearing logs into any notes/, project/ or docs/ Markdown file. Do not expand source write scope simply to satisfy documentation; obtain separate approval if necessary. Remote push/deploy still requires explicit approval.