Add Claude commands/remove Ralph logic#740
Merged
forstmeier merged 8 commits intomasterfrom Feb 4, 2026
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughThis PR removes the Ralph autonomous development workflow from maskfile.md, CLAUDE.md, and tooling scripts, then introduces new command-based workflows for managing issues, pull requests, and notes. The issue template is renamed and restructured, and guidance in CLAUDE.md is generalized to reflect the new workflow approach. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR deprecates the Ralph autonomous development workflow in favor of Claude commands for on-demand task management. The changes refactor the workflow model from automated loops to explicit command-driven interactions.
Changes:
- Removed Ralph-related scripts, maskfile tasks, and configuration
- Introduced Claude commands for GitHub issue and PR management
- Updated CLAUDE.md with new workflow orchestration guidelines
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/ralph_preflight.sh | Deleted Ralph preflight validation script |
| maskfile.md | Removed Ralph workflow tasks and cleaned up echo statements |
| CLAUDE.md | Replaced Ralph workflow documentation with new workflow orchestration principles |
| .github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md | Simplified issue template from Ralph spec format to standard issue format |
| .claude/commands/update-pull-request.md | Added new command for processing PR feedback |
| .claude/commands/update-notes.md | Added new command for consolidating lessons into CLAUDE.md |
| .claude/commands/fix-pull-request-feedback.md | Deleted old PR feedback command |
| .claude/commands/create-or-update-issue.md | Added new command for issue creation/updates |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
Greptile OverviewGreptile SummaryThis PR successfully transitions from Ralph's autonomous workflow system to on-demand Claude commands. The changes remove Ralph-specific infrastructure (bash scripts, mask commands, workflow documentation) and replace it with three focused Claude commands for issue management, PR updates, and notes consolidation. All previously identified issues from the feedback thread have been addressed, including fixing placeholder syntax, removing hardcoded organization references, and properly handling file operations. Key improvements:
Confidence Score: 5/5
|
| Filename | Overview |
|---|---|
| .claude/commands/create-or-update-issue.md | New command for managing GitHub issues; all previous feedback addressed |
| .claude/commands/update-notes.md | New command for consolidating lessons; clear workflow with approval gates |
| .claude/commands/update-pull-request.md | New comprehensive PR management command; addresses all previous feedback |
| .gitignore | Added .claude/tasks/ to prevent committing session-specific files |
| CLAUDE.md | Removed Ralph workflow section, added workflow best practices |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Fix all issues with AI agents
In @.claude/commands/create-or-update-issue.md:
- Line 22: Clarify how to retrieve the project node ID by adding the explicit
GraphQL query used to fetch it (querying the organization by login and then
projectV2(number: N) to read the id) and show that this id is the value passed
to the addProjectV2ItemById mutation; reference the projectV2 and
organization(login:) selection and the addProjectV2ItemById mutation so readers
know which fields to request and which id to supply.
In @.claude/commands/update-notes.md:
- Line 18: The instruction text "After approval, append the consolidated bullet
points to the `CLAUDE.md` \"## Notes\" section maintaining alphabetical or
logical grouping with existing notes." is ambiguous because the existing Notes
section isn't alphabetized; either remove the "alphabetical" reference or make
alphabetization a prerequisite. Update .claude/commands/update-notes.md to (a)
remove the word "alphabetical" and leave "logical grouping" only, or (b) add a
prerequisite step that reorders the `CLAUDE.md` "## Notes" section
alphabetically before appending; ensure the updated sentence replaces the
original exact phrase containing "maintaining alphabetical or logical grouping"
so reviewers can find it easily.
In @.claude/commands/update-pull-request.md:
- Around line 77-79: The docs mention using the GraphQL mutation
resolveReviewThread(input:{threadId:"..."}) but do not explain how to obtain
that threadId; update the workflow to instruct extracting thread IDs from
comment metadata (look for .in_reply_to_id on review comment objects) or by
querying the review threads via the GitHub REST/GraphQL API (e.g., list review
threads for a PR and map comments to their thread IDs), and show that
.pull_request_review_id is not the same as the threadId so consumers should use
.in_reply_to_id or the threads query to retrieve the correct id before calling
resolveReviewThread.
- Around line 15-20: Clarify that the commit SHA used for the check-runs API
should be taken from the PR metadata's head.sha field: when calling `gh api
repos/:owner/:repo/commits/{commit_sha}/check-runs`, extract commit_sha from the
PR metadata response's `head.sha` property (i.e., PRResponse.head.sha) so
readers know exactly which field to use.
- Around line 22-26: Update the "Analyze Check Failures" step to clarify that
check-runs and workflow runs are distinct GitHub entities and that logs require
a workflow run ID: instruct to obtain the workflow run ID from the check-run
(use the check-run's .check_suite.id or match the check-run to its parent
workflow run) before calling gh api
repos/:owner/:repo/actions/runs/{run_id}/logs, and add a short note in the
"Analyze Check Failures" section explaining this two-step mapping so readers
know to translate check-run data to a workflow run ID first.
In `@CLAUDE.md`:
- Line 64: Typo fix: the word "specfications" should be corrected to
"specifications" in the sentence "Write detailed specfications upfront to reduce
ambiguity"; update that exact token so the line reads "Write detailed
specifications upfront to reduce ambiguity" (look for the misspelled word
"specfications" in CLAUDE.md).
- Line 24: Fix the typo in CLAUDE.md by changing the word "serivces" to
"services" in the sentence that reads "Folder names under the `applications/`
directory should have a `*model` suffix for machine learning serivces"; update
that exact phrase so it reads "...machine learning services" (edit the string in
CLAUDE.md where "machine learning serivces" appears).
- Line 62: Remove the trailing space at the end of the sentence "If something
goes wrong, stop and re-plan immediately - don't continue working " in CLAUDE.md
so the line ends with the apostrophe and no extra whitespace; update the content
for consistency by trimming the trailing whitespace in that line.
- Line 75: Fix the typographical error in the README text: change the incorrect
filename "lessons.m`d" to "lessons.md" in the CLAUDE.md content where the
sentence refers to updating `.claude/tasks/lessons.m`d`; ensure the backtick is
removed and the correct extension ".md" is used so the path reads
`.claude/tasks/lessons.md`.
- Around line 59-93: The ordered list numbering in the CLAUDE.md sections ("1.
Plan Mode Default", "2. Subagent Strategy", "3. Self-Improvement Loop", "4.
Verification Before Done", "5. Demand Elegance") should use consistent plain
`1.` for each top-level item to satisfy markdownlint; edit those list prefixes
so every top-level list line begins with `1.` (leave sublists and content
unchanged) so reordering is easier and the file passes linting.
Fixed 14 review comments from automated bot feedback across documentation files. CLAUDE.md typos (9 comments): - Line 24: serivces → services - Line 62: Removed trailing space after "working" - Line 64: specfications → specifications - Line 75: lessons.m`d → lessons.md Command documentation clarifications (5 comments): - update-pull-request.md: Clarified commit_sha comes from head.sha field - update-pull-request.md: Added note about check-runs vs workflow runs distinction - update-pull-request.md: Added guidance on extracting thread IDs for comment resolution - update-notes.md: Removed "alphabetical or" to keep only logical grouping - create-or-update-issue.md: Added specific GraphQL query for project node ID retrieval Rejected 1 style suggestion (markdown list numbering) as explicit numbering matches project conventions and improves readability. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
forstmeier
commented
Feb 2, 2026
Collaborator
Author
forstmeier
left a comment
forstmeier
left a comment
There was a problem hiding this comment.
Review Feedback Responses
Thank you @copilot, @greptile-apps, and @coderabbitai for the thorough review! I've addressed 14 of the 15 comments in commit 9ba3f80.
Fixed (14 comments):
CLAUDE.md typos:
- ✅ Line 24: 'serivces' → 'services' (@copilot, @greptile-apps, @coderabbitai)
- ✅ Line 62: Removed trailing space (@coderabbitai)
- ✅ Line 64: 'specfications' → 'specifications' (@copilot, @coderabbitai)
- ✅ Line 75: 'lessons.m`d' → 'lessons.md' (@copilot, @greptile-apps, @coderabbitai)
Command documentation clarifications:
- ✅ update-pull-request.md L20: Added clarification that commit_sha comes from
head.shafield (@coderabbitai) - ✅ update-pull-request.md L24-26: Added note about check-runs vs workflow runs distinction (@coderabbitai)
- ✅ update-pull-request.md L77-79: Added guidance on extracting thread IDs from
pull_request_review_idfield (@coderabbitai) - ✅ update-notes.md L18: Removed "alphabetical or" to keep only logical grouping (@coderabbitai)
- ✅ create-or-update-issue.md L22: Added specific GraphQL query for project node ID retrieval (@coderabbitai)
Not Implemented (1 comment):
CLAUDE.md L93 - Markdown list numbering (@coderabbitai):
Keeping the explicit numbering (1, 2, 3, 4, 5) as it's more readable and matches the project's documentation style throughout CLAUDE.md. While markdownlint prefers consistent 1. numbering, the explicit style is intentional for clarity when reading the raw markdown.
Contributor
|
@forstmeier I've opened a new pull request, #741, to work on those changes. Once the pull request is ready, I'll request review from you. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @.claude/commands/update-pull-request.md:
- Around line 57-69: Add a new step after the verification instructions in
section "7. Verify Changes" that instructs developers to commit and push
verified fixes to update the PR branch: after running the relevant verification
commands (e.g., mask development python all / mask development rust all) stage
changes, create a clear commit (mentioning the feedback group or ticket), and
push the branch so the PR reflects the fixes; ensure the step also notes to
re-run CI on the remote PR and proceed only after the remote checks pass.
- Line 24: The guidance is ambiguous about which field holds the workflow run
ID; change the text to specify that the check-run's check_suite.id is the check
suite ID (not the workflow run ID) and instruct to either (A) query workflow
runs by head SHA using check_run.check_suite.head_sha (GET
/repos/:owner/:repo/actions/runs?head_sha={sha}) and pick the matching run, or
(B) list workflow runs and filter where workflow_run.check_suite_id ==
check_run.check_suite.id to locate the workflow run before fetching logs with gh
api repos/:owner/:repo/actions/runs/{run_id}/logs.
- Line 78: The doc incorrectly instructs extracting thread IDs from
pull_request_review_id; instead query the PR's reviewThreads GraphQL field to
get PullRequestReviewThread.id values and pass those to the resolveReviewThread
mutation (e.g. use gh api graphql to fetch pullRequest -> reviewThreads -> nodes
{ id } and then call mutation resolveReviewThread with that id); update the
guidance to mention that pull_request_review_id identifies a review submission,
not a thread, and that the REST API cannot supply the PullRequestReviewThread.id
so GraphQL must be used.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In @.claude/commands/update-pull-request.md:
- Around line 219-241: The documentation currently resolves review threads
immediately after posting responses (the resolveReviewThread GraphQL mutation
block) while the workflow still says "Do not create any git commits yet",
causing threads to be marked resolved before fixes are pushed; update the docs
by inserting a short explicit note right after the review-thread resolution
section (after the block that describes resolveReviewThread and before the
commit/push step) explaining that threads are resolved based on local
verification, fixes remain in the local working directory until the Section 10
commit/push, and remote CI/reviewers will not see or validate changes until the
branch is updated.
- Around line 16-263: Update the markdown in
.claude/commands/update-pull-request.md to satisfy MD031 and wording
suggestions: add a blank line before and after every fenced code block (the
triple-backtick blocks shown in the file) to comply with MD031, replace the
phrase "not accessible" with "inaccessible" and replace "fix" with "resolve"
where suggested (search for those literal strings in the document), and run a
markdown linter to confirm no remaining MD031 violations before committing.
- Around line 244-265: The guidance under "10. Commit Changes (After User
Confirmation)" currently presents the prompt "Would you like me to push these
changes to the remote branch?" as optional; update this to state that pushing is
the required next step to update the PR and trigger remote CI while still
allowing the user to defer timing—e.g., replace that question with a clear
statement that "Pushing is required to update the PR and trigger CI; shall I
push now or wait for you to confirm a specific time?" and ensure the flow in
this section (commit example and subsequent prompt) makes pushing the expected
follow-up action to complete the workflow.
- Around line 168-181: Clarify that the "Verify Changes" steps using `mask
development python all` and `mask development rust all` are local-only checks:
add a short note in Section 7 (and echo in Section 9 and the final summary in
Section 11) stating that local verification confirms fixes in the developer's
environment but remote CI for the PR will not re-run or reflect those results
until changes are pushed in Section 10, and that final PR/remote CI status
should be checked after pushing changes; mention `mask development python all`,
`mask development rust all`, Section 9, Section 10, and Section 11 so readers
know where to update the text.
In @.claude/tasks/lessons.md:
- Around line 5-9: Clarify the 7‑day cutoff timezone by updating the "Rules"
header and the template comment; change the sentence "Rules older than 7 days
are periodically consolidated into `CLAUDE.md`." to explicitly state "using UTC"
(or similar), and modify the template comment line "<!-- Add new lessons here
with format: - [YYYY-MM-DD] Rule description -->" to include "use UTC dates"
(e.g., "<!-- Add new lessons here with format: - [YYYY-MM-DD] Rule description —
use UTC dates -->") so contributors know which clock to use for the 7‑day rule.
…on clarity This commit addresses all 8 review threads from PR #740, focusing on making the update-pull-request command more portable and improving documentation clarity around the workflow timing. Key changes: 1. Dynamic repository detection - The command now extracts owner/repo from git remote instead of hardcoding "oscmcompany/fund", following the pattern from create-or-update-issue.md 2. Consistent variable syntax - Updated all API examples to use $OWNER and $REPO variables 3. Naming convention clarity - Changed wildcard notation (*model, *manager) to explicit "should end with" phrasing in CLAUDE.md 4. Markdown formatting - Added blank lines around fenced code blocks (MD031 compliance) and improved word choices ("inaccessible" vs "not accessible", "resolve" vs "fix") 5. Workflow timing clarity - Added notes throughout the documentation explaining that local verification doesn't update remote CI, threads are resolved before fixes are pushed, and pushing is necessary to complete the PR update workflow 6. Timezone specification - Added UTC references to lessons.md for the 7-day consolidation rule All review threads have been responded to and resolved. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit addresses four issues discovered during command execution: 1. Removed todos.md clearing step that caused write errors (Write tool requires reading file first if it exists). Plan mode already handles organizing work, making separate todo file redundant. 2. Added explicit scratchpad directory instruction to use session-specific path from system reminders instead of /tmp/. Ensures session isolation and automatic cleanup. 3. Updated all temporary file paths to use $SCRATCHPAD variable instead of /tmp/ (pr_data.json references in Sections 1, 3, and 3a). 4. Added critical warning to never read PR data file directly with Read tool since it will be too large. Explicitly instructs to always use jq for parsing. These changes improve command reliability and follow best practices for temporary file storage. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit clarifies the todos.md workflow and removes obsolete temporary files: 1. Updated Task Management section in CLAUDE.md to clarify that todos.md is for general task tracking, not command-specific workflows. Commands like /update-pull-request use plan mode instead. Added note about reading file before writing to avoid errors. 2. Removed 7 temporary files from /tmp/: - 5 JSON files from PR #740 execution (pr_data.json, pr_metadata.json, review_threads.json, thread_responses.txt, pr740.json) - 2 obsolete shell scripts from PR #739 (reply_to_comments.sh, resolve_comments.sh) that used old REST API approach All PR work is committed and future commands will use scratchpad directory instead of /tmp/. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.claude/commands/update-pull-request.md:
- Around line 15-16: The doc omits exporting the parsed OWNER and REPO
environment variables before they are used in the GraphQL call; update the step
after parsing the git remote URL to explicitly set and export the variables
(e.g., assign to $OWNER and $REPO and run export) so the subsequent GraphQL
fetch step that references $OWNER/$REPO will work reliably; ensure the
instruction mentions the variable names ($OWNER and $REPO) and that this export
happens immediately before the "Fetch comprehensive PR data using a single
GraphQL query" step.
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 10 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.claude/commands/update-pull-request.md:
- Line 96: Change the unbraced shell variable usage `$ARGUMENTS` in the curl/gh
command to the safer braced form `${ARGUMENTS}` to avoid parsing ambiguities;
update the command that builds pr_data.json (the invocation using -f
owner="$OWNER" -f repo="$REPO" -F number=$ARGUMENTS > $SCRATCHPAD/pr_data.json)
so it uses -F number=${ARGUMENTS} (and consider bracing other variables like
${OWNER}, ${REPO}, ${SCRATCHPAD} for consistency).
Collaborator
Author
This stack of pull requests is managed by Graphite. Learn more about stacking. |
This was referenced Feb 4, 2026
chrisaddy
approved these changes
Feb 4, 2026
This was referenced Feb 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Changes
CLAUDE.md"Notes" section updater Claude commandCLAUDE.mdsectionContext
Our rollout of Ralph was not comprehensively evaluated and we should present cohesive/singular workflows to contributors if we they're going to be shared on
master. This is a switch over to an on-demand model with Claude commands. We can reintroduce Ralph or an equivalent workflow process later.Summary by CodeRabbit
Documentation
Chores