Repository Management Best Practices

Branching Strategy (MANDATORY)

• Protected Main: NEVER commit code directly to main unless it is a documentation-only change (e.g., updating README.md or specs/).
• Feature Branches: Before writing ANY code for a feature or fix, you must create a branch.
  • Naming Convention: type/issue-id-short-description
  • Examples:
    • feat/35-account-deletion
    • fix/login-crash
    • chore/update-deps
• Workflow Integration: The /execute workflow MUST trigger this branch creation immediately after analyzing the request.

Shipping Discipline (One Feature = One Ship)

• Granulairy: A "Ship" (Merge) happens as soon as a single unit of value is complete.
  • Do: Merge "Login Page" immediately upon completion.
  • Don't: Wait to build "Login" AND "Home" AND "Profile" on one branch.
• Risk Mitigation: Shipping frequently prevents "Merge Hell" and allows for easy reverts if something breaks.
• WIP Management: If you didn't finish the featin a session, just /save (which pushes to the feature branch). Only /ship when it is production-ready.

Security & Hygiene

• CRITICAL: Never commit .env files or any file containing secrets/API keys.
• Environment Safety (Onboarding):
  • Sync: Whenever you add a new variable to .env, you MUST immediately add it to .env.example (with a placeholder value).
  • Check: New developers (or agents) rely on .env.example to know how to configure the app. Missing this is unprofessional.
• Agent Sharing: You SHOULD commit the .agent/ folder (workflows, skills, rules) so that the team shares the same capabilities.
• Rule Sharing: PROJECT_RULES.md is now the shared source of truth and SHOULD be committed.
• Gitignore Audit: Verify that .env and .claude/ (personal config) are in .gitignore.
• Shell Syntax: Use && to chain commands in Bash.
• Pre-Commit Scan: Never run git add . without first running git status to check for untracked sensitive files.
  • Explicit Block: If you see files named mcp.json (especially in .agent/), credentials.json, service_account.json, or anything containing token or secret, STOP. Do not commit them. Add them to .gitignore immediately.
  • Secret Scrubbing: If you accidentally catch a secret in a commit history, you MUST rewrite the history (e.g., git filter-branch or git rebase -i) to remove it before pushing. Pushing a secret will block the push and require manual intervention.
• Repository Sweep (Sub-Agent): You can spawn a sub-agent to perform a thorough security sweep:
  • claude -p "Perform a deep security audit of the repository. Check all files (even ignored ones) for potential secrets and report findings." --agent "qa-bot"

Git Lock File Handling

• Symptom: fatal: Unable to create '.git/...lock': File exists.
• Cause: Another git process (IDE plugin, background git pull, or a crashed process) is holding a lock.
• Solution:

  1. First, check if a legitimate process is running (git status).

  2. If safe, remove all lock files:

     find .git -name "*.lock" -delete
     

  3. Retry the command.

• Prevention: Avoid very long-running background git commands. Do NOT leave git pull running indefinitely.

Git Sync After PR Merge

• Problem: After gh pr merge, local main may diverge if it has local-only commits.

• Safe Sync Pattern:

  git checkout main
  git fetch origin
  git reset --hard origin/main
  git remote prune origin
  

• NEVER chain git pull after gh pr merge if you suspect local divergence. Use reset --hard to guarantee sync.

Command Execution Discipline

• Avoid Long Chains: Do NOT chain more than 2-3 commands with &&. If one fails mid-chain, recovery is difficult.
• Prefer Sequential Steps: For high-risk operations (merge, reset, prune), run commands individually and check status between each.

Tool Hygiene

• No Hammering: If a tool call (like mcp_list_resources or run_command) fails, DO NOT retry the exact same call within the same step. Analyze the error message first. If a resource or command is not found, assume it is unavailable and ask the user or try an alternative approach.
• Agent Folder Location: The claude CLI strictly requires agents to be in .claude/agents/. NEVER try to place them in .agent/agents/ or create new directories for them. Use the existing location.

GitHub Operations

• CLI Usage: For PRs, Issues, and Releases, prefer using the GitHub CLI.
• Skill Check: Read view_file .agent/skills/github-cli/SKILL.md for specific commands and shortcuts.

Public Documentation (README)

• Mirroring Standards: If PROJECT_RULES.md is ignored, ensure all development standards (styling, hooks, state management) are summarized in the public README.md.
• Setup Clarity: Always provide a "Getting Started" section that includes environment variable requirements.
• Tech Stack Transparency: Clearly list the technologies used (Expo, Supabase, NativeWind) to assist other developers or for your own future reference.

Conventional Commits

• Use the format: type(scope): description.
• Common types: feat, fix, chore, docs, refactor, style, test.

System Evolution & Reflection

• Continuous Learning: Before starting any task (especially those involving /save, /ship, or /teach), the agent MUST reflect on the current chat history to identify procedural or technical mistakes.
• Skill Updates: If a mistake is recurring (e.g., CRLF warnings, missing haptics, RLS leakage), the agent MUST update the corresponding SKILL.md file using the /teach workflow.
• Self-Correction First: The agent is responsible for identifying its own errors through active reflection, rather than waiting for the user to point them out.
• Rule Synchronization: If a new technical standard is established during a session (e.g., a new unit conversion rule), it must be added to PROJECT_RULES.md and the relevant SKILL.md.