Agent Stuff

This repo is a temporary dumping ground for useful artifacts & resources I've put together so far while ramping up on AI tooling.

The Ralph trend is perhapse a little overblown, but the pattern seems useful nonetheless.

The original Ralph method by Geoffrey Huntley. It's essentially just a while loop within which claude is invoked to select the next task for it to complete.

Claude code's ralph loop has been decried as being "not a real ralph loop" by several folks. Worth being aware of if its workflow meets your needs. Truethfully, I have not looked into this at all yet.

An interesting resource I found while writing this readme is https://ralph-tui.com/. It hits on an observability problem I have with the ralph script in this repo. I'll be investigating ralph-tui in the coming days.

The script is extremely make-do. It has a few args for selecting how you want to the script to run: until no more github issues, for N github issues, or for T time.

It has a two-step loop:

1. Invoke claude to select the next issue using a ralph-issue-selector agent.
2. Implement the selected issue using the ticket-orchestrator-planned-sdlc agent. Currently this is done with no security isolation and with dangerous permissions. Isolation is still on my todo list to learn.

My main project has two types of work items: planned-tickets and tactical-tickets (essentially unplanned work).

Currently the ralph-issue-selector is tasked with picking the next task from only the planned work, really it should include both planned and unplanned to some degree. This agent is written specifically for my dudewheresmyjob project (private repo), but can very easily be generalized/adapted for your own projects.

Noteworthy details:

• filters github issues by labels audience:claude and stage:ready-for-development
• sticks to planned issues (which contain an ERD reference in their description like: ## ERD)
• rudimentary dependency evaluation (githubs "relationship" feature not available via gh, so manually managed links in the issue description is required)
• "Deep analysis" is done for candidate issues to further "understand" the goal. Should improve prioritization decisions when multiple issues are ready at once. This is very dependent on my ERD/PRD setup (not documented here).
• output formatting directives for parsing in the ralph loop

This agent orchestrates the implementation of a github issue and is very tightly coupled to my project documentation.

Details:

• only acts on planned work
• delegates all work to subagents for context preservation
• workflow:
  • implementation
  • opens PR once initial changes, tests, and lints are resolved
  • "tract" reviewers review the diff & request changes to the orchestrator.
  • acceptance testing this step is supposed to actually test the feature, but my local environment has been a mess so this stage hasn't actually been happening effectively. I need to create a dedicated agent for this

The "tracts" are essentially like domains covering various parts of the stack. These are areas you might typically form an engineering team around, like frontend, api, xyz feature backend, auth(n/z), db, k8s, helm charts, etc.

The concepts of a Tract results in a context boundary useful for LLMs. As documents and requirements build up over time, there will be lots of nuanced requiremnts across the stack that will get lost in a single LLMs context. Tracts are a mechanism for grouping like concerns so that an agent can "review on behalf" of a tract. A single github issue may span a couple tracts (like UI, backend, and search), an agent for each tract is created to review the changes in the context of that tract.