Engineering Rules

Standard engineering conventions and tooling guidelines for the project-agent-manager (pam) repository.

Language Rules

• Architecture/contract docs under docs/: Must be written in English. Each file must carry YAML frontmatter with an implementation: status key.
• README.md: Bilingual (Korean-first) is acceptable.
• User-facing chat replies: Follow the user’s conversation language.
• Code, code comments, and commit messages: Must be in English.

Toolchain Pinning

• Rust Version Match: The following files/fields MUST all name the SAME Rust version (currently 1.93.1):
  • rust-toolchain.toml
  • .tool-versions
  • The toolchain: input in .github/workflows/ci.yml
• Version Bumping: Any version bump must change all three in ONE commit, never mixed with feature changes. Local gates are meaningless if they run a different compiler than CI.

Docs Rules

• Documentation Index: docs/README.md is the canon index. New docs must be linked from it.
• Frontmatter Requirement: Every architecture/contract/UI/roadmap document carries frontmatter:

  type: architecture | contract | rules | roadmap
  authority: canonical | derived
  implementation: proposed | partial | placeholder | shipped | not-applicable
  verification: <how-to-verify>
  source: <source-file-or-context>
  last_verified: YYYY-MM-DD
  owners:
    - owner-username
  

• Shipped Behavior Source of Truth: Never treat a doc marked proposed (or otherwise not shipped) as describing shipped behavior. Code and tests are the source of truth.

Git Policy

• Single Branch: main.
• Solo-Developer Workflow: All work lands directly on main — no feature branches, no parallel agent-team branches. A branch is created only when the user explicitly names one.
• Remotes: Remote is git.agentthread.dev. Push/remote registration is deferred until configured (planned: September 2026). Until then: no remotes, no pushes.
• Commit Gate: Commit only after all four quality gates (build, test, format, clippy) pass successfully.