forager

Check codebase for architectural violations (factory bypass, raw assign, scope compliance, service layer). TRIGGER when the user discusses creating Core Data objects in production code, adding new entity creation sites, or before PR creation on milestones that touch the service/model layer.

Create a git commit following project conventions. Enforces PREFIX-#.# prefix, imperative mood, no Co-Authored-By. TRIGGER when the user says "commit this", "commit the changes", "let's commit", "make a commit", "save this progress", "check in the code", "snapshot this", "git commit", or any request to create a git commit.

Update all core documentation files after completing a milestone. Use when marking any M#.#.# as COMPLETE. Ensures documentation stays synchronized. TRIGGER when the user says "milestone done", "mark milestone complete", "finish milestone", "this is done", "wrap up this milestone", "close out milestone", "mark it complete", or any indication that a milestone has been completed.

Set up a new milestone for development. Creates feature branch, updates current-story.md, and creates branch-specific next-prompt file with implementation guidance. TRIGGER when the user says "new milestone", "start a new milestone", "create milestone", "begin feature", "next milestone", "set up milestone", or any request to start a new development milestone.

Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.

Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.

Run the mandatory session startup checklist. Reads context docs, checks git status, checks active OpenSpec changes, reports current milestone and branch. TRIGGER when the user says "start session", "begin session", "let's get started", "starting work", "resume session", "pick up where I left off", "what should I work on", or at the start of every Claude Code session.

Create a pull request following project conventions. PREFIX-#.# title, structured body with summary/changes/testing/time, squash merge target. TRIGGER when the user says "create a PR", "make a pull request", "open a PR", "let's PR this", "submit a PR", "ready for review", "push and PR", or any request to create or submit a pull request.

Review current branch changes for convention compliance, manifest adherence, and code quality. Two modes: /review (pre-PR, local branch) and /review <PR#> (open PR via gh). TRIGGER when the user says "review this", "review my changes", "check before PR", "run review", "pre-PR check", "review code", "audit changes", or any request to review changes before or after creating a pull request.

Wrap up work on a milestone or session. Chains review → journal → commit → PR → milestone-complete. Interactive — each step asks before proceeding. TRIGGER when the user says "done", "I'm done", "wrap up", "finish up", "all done", "ship it", "let's wrap", "ready to merge", or any request to complete and finalize work.

Build forager with the correct Xcode configuration. Uses iPhone 17 Pro simulator. Filters output for errors and warnings. TRIGGER when the user says "build it", "build the app", "run a build", "compile", "does it build", "rebuild", "try building", "does it compile", or any request to build or compile the project.

Open a new tmux pane in the current session. Optionally launch claude with an initial command. TRIGGER when the user says "new pane", "open a pane", "split pane", "another terminal", "new window", "side by side", or any request to open a parallel terminal or claude session.

Archive and distribute forager to TestFlight. Auto-increments build number, archives for Release, uploads to App Store Connect, waits for processing, sets export compliance, and adds to beta test group. TRIGGER when the user says "archive", "deploy to TestFlight", "upload to TestFlight", "release a build", "ship a build", or any request to distribute the app.

Run Core Data impact analysis before schema changes. Required by ADR 007. Searches all usage of affected entities, documents relationships, codegen, and migration impact. TRIGGER when the user discusses changing the Core Data schema, adding/removing entity attributes, modifying relationships, creating a new entity, or any database model changes.

Write or update the narrative session entry in docs/development-journal.md. Captures decisions, learning, and AI tooling observations. MANDATORY before every commit. TRIGGER when the user says "update the journal", "write a journal entry", "log the session", or when preparing to commit (should auto-check if journal is current).

Log a technical insight to docs/insights-log.md immediately. Do not defer — sessions can clear. TRIGGER when the user says "log this insight", "that's worth noting", "remember this", "note this gotcha", "TIL", "important discovery", "capture this learning", or any request to record a technical observation.

Audit a PRD against the current codebase before implementation. Verifies entity names, property names, and API signatures are still accurate. TRIGGER when the user says "audit the PRD", "check the PRD", "is the PRD still accurate", or when starting implementation of a PRD that is more than 2 weeks old.

Full release pipeline from feature branch to TestFlight. Pushes branch, creates PR, squash merges to main, then runs archive + TestFlight distribution. TRIGGER when the user says "release this", "ship it", "release prep", "merge and archive", "get this to TestFlight", or any request to take a feature branch through to TestFlight distribution.

Search for existing services before creating new infrastructure. Prevents duplicate services. TRIGGER when the user says "create a service", "new service", "add a service class", "build a service for", or discusses creating any new service, manager, or helper class in the Services/ directory.