droboticflow/AGENTS.md
Codex 0040988fe9
Some checks are pending
web-ci / checks (push) Waiting to run
web-ci / pool-search-mongo (push) Waiting to run
🧭 Enforce dev mainline and release identity
2026-11-10 01:35:25 -08:00

10 KiB

Project Instructions

Working Root

  • The repository root is /Users/d-robotics/Desktop/fanyu/droboticflow. The unified development checkout is local-data/worktrees/recent-integration on dev. The main checkout and existing unmerged worktrees retain protected work; do not reset, switch or discard them as part of routine development.
  • Cluster kubeconfig (fanyu.conf), BOS credential CSV, downloaded captures, and the local workspace mount live under this repo's untracked local-data/ directory; ~/Desktop/fanyu still holds legacy copies (fanyu.conf, 泛宇-aksk.csv) and is being retired (see docs/HANDOFF.md § 0).
  • Before reading code to explain production behavior or starting changes, run bash scripts/local/branch-freshness.sh (read-only). If it reports the checkout is behind origin/dev, missing a live build commit, or only locally compared without remote/live confirmation, tell the user and work in a worktree that contains the live commit instead of a stale checkout.

Engineering Principles

These principles guide implementation choices. Specific business contracts and this document's release, authorization, and data safety rules take precedence.

  1. Check contracts and implementation first. Read CONTEXT.md, relevant ADRs, business docs, code, and tests (docs/agents/domain.md). Distinguish current behavior, approved unimplemented designs, and superseded rules. Use the controlled Chinese terms from CONTEXT.md in customer-facing copy, specs, issues, and domain discussions; ask the user when a request conflicts with existing agreements and affects business outcomes.

  2. Define the compatibility scope before making changes. For APIs, Mongo records, workflow definitions, operator inputs/outputs, delivery formats, or task states, check callers, existing data, and in-flight tasks. Preserve active migration and recovery paths; before removing an old path, verify migration completion and explain rollback impact. Internal implementations may be refactored directly when contracts remain unchanged.

  3. Keep solutions simple, incremental, and verifiable. Abstractions and indirection must serve a concrete requirement; authentication, permission isolation, data consistency, retries, and recovery are part of requirements. For multi-layer changes, connect the smallest complete flow first and validate replacement paths before removing old ones. State the scope, limitations, and replacement conditions of any temporary solution.

  4. Follow responsibility boundaries and reuse existing capabilities. Place changes in the module responsible for that behavior. Enforce permissions and business constraints on the server; use frontend validation for interaction feedback and keep generated files updated from authoritative sources. Inspect existing code, standard libraries, and installed dependencies before adding new ones, and consult primary sources for unfamiliar or hard-to-reverse choices.

  5. Complete delivery with verification evidence. Run the scoped checks (docs/agents/verification.md) and verify relevant behavior in the appropriate local environment. Cover failure, restart recovery, and legacy data scenarios for async, persistence, or compatibility changes. Compare existing failures against the baseline by specific test case and cause (npm run test:frontend:gate / npm run test:go:gate), update contracts when behavior changes, and clearly report what passed, failed, or remains unverified.

Deployment Environment

  • The dev branch uses Fanyu. Leave DEPLOY_ENV unset or set it to fanyu; the loader rejects other targets, including poc and wjzh.
  • POC-like branches resolve to poc and require that target. Feature branches outside these routing rules may select a target explicitly with DEPLOY_ENV.
  • Supply Fanyu secrets and environment-specific settings through the loader's existing local override files; the tracked preset contains only non-secret defaults.
  • Verify the target cluster and namespace before every release, including when the environment is inferred from the branch.

Git Workflow

  • Before assuming a remote target, inspect the remote URL with credentials redacted (git remote -v | sed -E 's#//[^@/[[:space:]]+@#//<redacted>@#g'). Never print raw credential-bearing .git/config URLs into logs or reports; prefer migrating Git credentials to the system Keychain.
  • After making code or documentation changes for the user, stage only the files changed for that task. Do not stage or commit unrelated user changes already present in the working tree.
  • Commit with an English, emoji-prefixed commit message.
  • dev is the single integration and release mainline. Reuse the unified dev checkout for normal authorized work. Create a branch or worktree only when the user explicitly requests it; record its purpose and merge-back plan first. Read-only diagnosis creates neither.
  • Existing unmerged branches and uncommitted work remain untouched until the user requests their integration or disposal. Completed branches are cleaned only after their commits are in origin/dev, their work is preserved, and no service uses the worktree. Follow docs/agents/branch-workflow.md for synchronization and cleanup.
  • Push and PR each require explicit user authorization. An explicit request to synchronize remote dev authorizes that bounded fast-forward push; it does not authorize a deployment or unrelated pending changes. Never force-push or rewrite dev history. Otherwise commit locally and report the state.
  • When a task ends, run python3 scripts/agent_status.py --no-fetch (or with fetch if network/remote checks are needed) and report the branch's local state to the user.

Release Workflow

  • For release preparation, deployment, rollback, or resuming release work, read docs/release/README.md first and run python3 scripts/release.py status <release-id> when a record exists. Follow the recorded state and evidence; a successful rollout alone is not business acceptance.
  • Every new release must use exactly the synchronized local dev and remote origin/dev tip at release time. Integrate and verify fixes on dev before preparing a release; unmerged-branch releases have no exception. scripts/release.py checks both refs during prepare and refreshes origin/dev again before deployment. Existing release records and unchanged components retain their historical identities; later development may advance dev beyond the deployed version.
  • Fanyu image releases use scripts/release.py (scripts/deploy-k8s.sh blocks Fanyu). Configuration changes or migrations outside its supported scope require a separately reviewed plan and the corresponding user authorization.

Credentials

  • Never hardcode credentials (BOS AK/SK, Mongo, Gitea token, cluster kubeconfig) in any tracked file, and never echo raw credentials from untracked files (.git/config, local-data/*) into conversation output, .scratch/ notes, or test logs.
  • Read secrets from untracked local files, environment variables, or the system Keychain; see scripts/local/ for the established pattern.

Release Approval and Customer Data Safety

  • Pushing branches, creating/submitting a pull request, and deploying to any company cluster require explicit user approval (either individually or via an explicit combined instruction such as "push and open PR"); approving one action never implicitly authorizes another. Local review and commits remain unsubmitted until approved.
  • Cluster verification is read-only against customer data: use isolated synthetic fixtures or existing records without mutation, and never delete, overwrite, or add customer data. If a test requires a write or destructive operation, stop and obtain explicit approval for that exact operation.

Development verification

  • Before choosing checks for a change, read docs/agents/verification.md. Start with npm run verify:plan -- --base <task-base>; use quick checks while editing and affected task checks once before delivery. Expand only for changed dependencies, failures or uncovered risk.
  • Reuse unchanged evidence within a task using the recorded source, dependency, configuration and environment identities. Report skipped, timed-out and unmapped coverage as pending; quick checks never replace release evidence.
  • Keep local implementation and verification moving within the authorized scope. The existing push, PR, production-data and deployment approval rules still apply.

Local Environment

  • Local Mongo environments serve distinct purposes (docs/HANDOFF.md § 0, docs/local-dev-guide.zh-CN.md § 0):
    • Snapshot Mongo (127.0.0.1:27018, env-local-snapshot.sh): realistic replica of production data structure for workbench/API verification before a PR. Keep shared snapshot task claim states clean before running Go baseline gates (npm run test:go:gate).
    • Empty/isolated Mongo (127.0.0.1:27017, env-local.sh, or per-test isolated databases on 27018): synthetic fixtures, unit/integration tests, and clean-slate workflow CRUD debugging.
  • Verification commands and known pitfalls (upstream test debt, session auth flag, workspace mount) are documented in docs/HANDOFF.md.
  • Comparing test failures against the known-failure baseline ALWAYS goes through npm run test:frontend:gate / npm run test:go:gate (they diff against tests/known-failures.json; only NEW failures fail). Never hand-diff failure lists with stash/scratch files. Quick edits check changed-file formatting; the full formatting gate remains npm run format:check at integration/release scope.
  • The company cluster and BOS bucket are read-only by default; any write requires explicit user approval.

Agent skills

Issue tracker

Issues and specs use local Markdown under .scratch/. Before reading or publishing tickets, read docs/agents/issue-tracker.md.

Triage labels

Use the five default triage roles. Before triaging issues, read docs/agents/triage-labels.md.

Domain docs

Use a single-context layout: root CONTEXT.md and docs/adr/. Before exploring domain concepts or decisions, read docs/agents/domain.md.

Coding standards

Before writing or reviewing pool/list eligibility logic (claim buttons, canClaim, task-pool gating), read docs/CODING_STANDARDS.md — eligibility flags are server-shipped; the UI renders them, it never rebuilds them.

UI copy and presentation

Before adding or changing any customer-facing page, component, or copy, read docs/ui/copy-guidelines.md. Its minimal-copy rules and applicable visual checks are required acceptance criteria for implementation and review, including bug fixes and generated UI. Apply them to new work as well as existing pages.