nubecita: Instructions file for Codex

Agent Instructions

Non-Interactive Shell Commands

ALWAYS use non-interactive flags with file operations to avoid hanging on confirmation prompts.

Shell commands like cp, mv, and rm may be aliased to include -i (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.

Use these forms instead:

# Force overwrite without prompting
cp -f source dest           # NOT: cp source dest
mv -f source dest           # NOT: mv source dest
rm -f file                  # NOT: rm file

# For recursive operations
rm -rf directory            # NOT: rm -r directory
cp -rf source dest          # NOT: cp -r source dest

Other commands that may prompt:

• scp - use -o BatchMode=yes for non-interactive
• ssh - use -o BatchMode=yes to fail instead of prompting
• apt-get - use -y flag
• brew - use HOMEBREW_NO_AUTO_UPDATE=1 env var

Branching & Pull Requests (NEVER Push to main)

NEVER push directly to main. ALL code changes destined for main MUST go through a feature branch and a Pull Request.

• Always work on a feature branch: Never commit or push directly on main. Create a descriptive branch before writing code:

  git checkout -b <branch-name> origin/main
  

  Branch naming convention (required by repository beads workflow in CLAUDE.md:122-126): <type>/<bd-id>-<slug>.
  • <type>: Conventional Commit type (feat, fix, chore, refactor, docs, test, etc.) inferred from the bd issue type.
  • <bd-id>: Beads issue ID (e.g. nubecita-aew).
  • <slug>: Kebab-cased title, capped at 50 chars.
  • Example: feat/nubecita-aew-create-mviviewmodel-base-class
• If accidentally on main with changes:
  • Immediately move uncommitted or committed changes to a feature branch:

    git checkout -b <branch-name>
    # If commits were already made on local main, reset local main back to remote:
    git branch -f main origin/main
    

• Push feature branches only:

  git push -u origin <branch-name>
  

• Open a Pull Request:
  • Use GitHub CLI (gh) to open a PR:

    gh pr create --title "<type>(<scope>): <summary>" --body "<details>"
    

• Never bypass branch protections: Even if your credentials or token allow bypassing branch protections or direct pushes to main, NEVER bypass them.
• Do not merge without review / CI: Address review comments, ensure all CI checks pass.
  • Standalone PRs: Merge with squash:

    gh pr merge <pr-number> --squash --delete-branch
    

  • Epic stacked PRs (gh stack): Never merge individual child PRs from the GitHub UI or via gh pr merge. Merge the entire stack atomically:

    gh stack merge --squash --yes