OITApps · oitray · Apr 30, 2026
@@ -22,12 +22,71 @@
 - Prefer editing existing files over creating new ones
 - No over-engineering — solve today's problem, not hypothetical future ones
 
+## Git Workflow & Versioning
+
+All changes flow through a two-stage branch model:
+
+```text
+feature/xyz  →  PR  →  develop  →  PR  →  main
+                       (testing)        (production)
+```
+
+- **`main`** — production-ready. Always stable. Never commit directly.
+- **`develop`** — integration/testing branch. Feature branches merge here first.
+- **Feature branches** — created from `develop`, named `feat/`, `fix/`, `chore/`, `perf/`, etc.
+
+### Rules
+
+1. Never commit directly to `main` or `develop`
+2. All work starts as a feature branch off `develop`
+3. Feature branches → PR → `develop` (for testing/integration)
+4. `develop` → PR → `main` (for production release, after verification). Before opening, offer to run `/changelog-polish` to rewrite raw entries in Ray's voice.
+5. Branch naming: `{type}/{short-description}` (e.g., `feat/tool-selection`, `fix/bash3-compat`)
+6. Delete feature branches after merge
+7. Keep `develop` in sync with `main` after each release merge
+8. Commit signing is required on `main` and `develop` — contributors must set up SSH/GPG signing before their first PR (see `SECURITY.md`)
+9. If modifying `scripts/setup.sh`, run `bash scripts/compat-check.sh` before opening a PR
+
+### Versioning
+
+- Every PR to `develop` or `main` MUST have exactly one semver label: `patch`, `minor`, or `major`.
+  - **patch**: bug fixes, minor tweaks, docs updates
+  - **minor**: new features, enhancements, new commands/personas
+  - **major**: breaking changes (config format changes, removed features)
+- On merge to `main`, a GitHub Action auto-bumps `VERSION`, creates a git tag, and appends to `CHANGELOG.md`.
+- If no semver label is present, the action defaults to `patch` — but always label explicitly.
+
 ## Security
 
 - Never commit `.env`, credentials, or API keys
-- Use `.env.template` pattern for secret management
+- Use `.env.template` for shared keys, `.env.local.template` for machine-local secrets (see `SECURITY.md`)
+- MCP server versions must be pinned in `catalog.json` — no `@latest` or unpinned `npx -y`
 - `WITH SECURITY_ENFORCED` on all SOQL in Apex
 - Validate at system boundaries, trust internal code
+- Full security policy: `SECURITY.md`
+
+## Credential Handling
+
+- **Never** tell users to manually edit `.env`, `.env.local`, or any config file to add API keys
+- **Never** say "paste X into Y file" for secrets — all key ingestion goes through the setup script
+- When adding a server, **run `catalog.sh add <server>` via the Bash tool** — the script detects the non-interactive context and automatically opens a secure terminal:
+  - **IDE detected** (VSCode/Cursor): opens the IDE's integrated terminal
+  - **No IDE**: opens a native OS terminal (Terminal.app on macOS, gnome-terminal on Linux)
+- The opened terminal collects credentials via masked input (`getpass`) and handles OAuth flows automatically
+- On next session start, the hook verifies whether the install completed and notifies Claude
+- Storage in `~/.claude/.env` (chmod 600) is correct — the **collection** must always go through OCC tooling
+
+### How to add a server
+
+```bash
+# From Claude Code Bash tool (opens a terminal automatically):
+~/claude-config/scripts/catalog.sh add <server-name>
+
+# Full setup (all servers — run manually in terminal):
+~/claude-config/scripts/setup.sh
+```
+
+Run `catalog.sh add <server>` directly from the Bash tool — a terminal will open automatically for the user. Do NOT tell users to run commands manually unless the automatic launch fails.
 
 ## Documentation
 
@@ -57,6 +116,46 @@ When a user says `/build` or asks to "build" a capability, choose the right prim
 
 The user should never need to specify "make me a skill/agent/command/plugin." Just `/build [what they want]` and you decide the method. Explain what you chose and why in one line before building.
 
+## Issue-First Workflow
+
+All actionable work requires a GitHub issue before code changes begin. No exceptions.
+
+### Flow
+
+```text
+Discussion → "Let's do this"
+         → Draft issue (title, description, acceptance criteria)
+         → User approves
+         → Create issue on GitHub
+         → Create git worktree tied to issue
+         → Plan goes as issue comment
+         → Work happens in worktree
+         → PR references issue (closes on merge)
+```
+
+### Issue-First Rules
+
+1. **No worktree without an issue.** Every worktree maps to a GitHub issue. Branch name: `{type}/issue-{number}-{short-description}`.
+2. **Research and discussion are free.** No issue needed for questions, exploration, or analysis.
+3. **"Let's do this" = create an issue.** When a conversation shifts from discussion to action, draft the issue and confirm before proceeding.
+4. **Quick fixes (< 5 min, single file):** Ask "issue or just do it?" — user decides.
+5. **Bugs discovered mid-conversation:** Create issue immediately, even if fixing now.
+6. **Plans live on the issue.** Implementation plans go as issue comments, not just in conversation context.
+7. **One worktree per issue.** Never reuse a worktree across multiple issues.
+
+### Threshold
+
+| Scenario | Action |
+| -------- | ------ |
+| Research / questions / discussion | No issue, no worktree |
+| Discussion evolves into "let's do this" | Create issue → plan on it → worktree when approved |
+| Quick config fix (< 5 min, single file) | Ask "issue or just do it?" |
+| Bug discovered mid-conversation | Create issue immediately |
+
+## Operational Standards & Personal Preferences
+
+Read `.claude/standards/` for org-wide operational rules before taking action on Salesforce, Teams, documentation, or query tasks. Read `.claude/personal/` for user-specific preferences, routing rules, and workflow context. Both directories are loaded on-demand — check them when a task touches their domain.
+
 ## Adding Catalog Tools
 
 When a user asks anything like "add X", "integrate X", "can we use X", "build me a tool for X", or "is there an MCP for X" — treat it as a catalog tool addition request and follow the `/build-tool` workflow automatically. Do not wait for them to invoke the command explicitly.