fix: rewrite agent instructions from agent perspective

[koriyoshi2041]

Summary

Fixes #47

Agent instructions contained abstraction leaks—they were written from the orchestrator's perspective, assuming the agent understands the Ralph loop. But each agent session starts fresh with no memory of previous invocations.

Changes

1. Terminology: iteration → session

The word "iteration" implies knowledge of an outer loop. Changed to "session" which makes sense from the agent's POV.

2. Explicit Memory Statement

Added at the top of CLAUDE.md and prompt.md:

Important: Each session starts fresh with no memory of previous sessions. Your only knowledge comes from reading files.

3. Completion Criteria Section

Added explicit criteria referencing specific step numbers (5, 6, 8, 9, 10) so the agent knows exactly when its work is done.

4. Improved Stop Condition

Before (vague):

"end your response normally (another iteration will pick up the next story)"

After (explicit):

"End your session after completing steps 1-10. Your work is done for this session."

5. Contextualized File Writing

Explained why writing to files matters—future sessions have no memory, only files.

Files Modified

• AGENTS.md (12 lines)
• CLAUDE.md (29 lines)
• prompt.md (31 lines)

Testing

The agent no longer needs to understand orchestration concepts—it only needs to follow the numbered steps and check the explicit completion criteria.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR successfully refactors agent instruction files to eliminate abstraction leaks by rewriting them from the agent's perspective rather than the orchestrator's perspective.

Key improvements:

• Replaced "iteration" terminology with "session" throughout all files, removing assumptions about outer loop knowledge
• Added explicit memory statement at the top of instruction files clarifying that each session starts fresh
• Created dedicated "Completion Criteria" section listing specific step numbers (5, 6, 8, 9, 10) for clear completion signals
• Improved stop condition from vague "end your response normally" to explicit "End your session after completing steps 1-10"
• Added context about why file writing matters (future sessions have no memory)

Note on file naming:
The PR introduces a divergence where CLAUDE.md instructs Claude Code agents to document in CLAUDE.md files, while prompt.md instructs Amp agents to document in AGENTS.md files. This appears intentional for tool-specific documentation conventions, but verify this doesn't fragment knowledge sharing if projects switch between tools.

Confidence Score: 4/5

• Safe to merge with minor consideration about documentation file naming conventions
• All changes are documentation-only with clear improvements to agent instructions. The terminology updates are consistent and well-reasoned. One minor concern about CLAUDE.md vs AGENTS.md naming divergence that may need clarification but doesn't block merging.
• All files are documentation changes only; no critical issues found

Important Files Changed

Filename	Overview
AGENTS.md	Terminology updated from "iteration" to "session" throughout, emphasizing that sessions don't share memory
CLAUDE.md	Added memory statement, updated terminology, added completion criteria section - but references wrong file name (CLAUDE.md instead of AGENTS.md)
prompt.md	Added memory statement, updated terminology to "session", added explicit completion criteria section

Sequence Diagram

sequenceDiagram
    participant Orchestrator as Ralph Orchestrator
    participant Agent as Fresh Agent Session
    participant Files as File System
    
    Note over Orchestrator: Loop until all stories complete
    
    Orchestrator->>Files: Read prd.json
    Orchestrator->>Agent: Spawn fresh session with instructions
    
    Note over Agent: Session starts with NO memory
    
    Agent->>Files: Read prd.json
    Agent->>Files: Read progress.txt (check Codebase Patterns)
    Agent->>Files: Read AGENTS.md/CLAUDE.md for context
    
    Agent->>Agent: Pick highest priority story (passes: false)
    Agent->>Files: Implement story (edit code files)
    Agent->>Files: Run quality checks
    
    alt Quality checks pass
        Agent->>Files: Commit changes
        Agent->>Files: Update prd.json (set passes: true)
        Agent->>Files: Append to progress.txt with learnings
        Agent->>Files: Update AGENTS.md/CLAUDE.md if patterns found
        Agent->>Orchestrator: End session normally
    else Quality checks fail
        Agent->>Files: Fix issues
        Note over Agent: Retry until checks pass
    end
    
    alt All stories complete
        Agent->>Orchestrator: Return COMPLETE signal
        Note over Orchestrator: Exit loop
    else Stories remain
        Note over Orchestrator: Spawn new session
        Orchestrator->>Agent: Create new agent (clean context)
    end

Loading

[greptile-apps]

_{3 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

File name inconsistency: CLAUDE.md should reference AGENTS.md instead for consistency with prompt.md (which references AGENTS.md on the equivalent line)

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: CLAUDE.md
Line: 5:5

Comment:
File name inconsistency: `CLAUDE.md` should reference `AGENTS.md` instead for consistency with `prompt.md` (which references `AGENTS.md` on the equivalent line)

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Consider whether Claude Code agents should document learnings in AGENTS.md (to match prompt.md:5) instead of CLAUDE.md for cross-tool consistency

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: CLAUDE.md
Line: 5:5

Comment:
Consider whether Claude Code agents should document learnings in `AGENTS.md` (to match `prompt.md:5`) instead of `CLAUDE.md` for cross-tool consistency

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

[koriyoshi2041]

Intentional design: CLAUDE.md is for Claude Code users (uses CLAUDE.md convention), prompt.md is for Amp users (uses AGENTS.md convention). The original files already follow this pattern (see lines 49-73 vs 52-76). Happy to unify if maintainers prefer, but that's a broader design decision.

[schaveyt]

Does this have any meaningful change in the results or is being overly pedantic? What evals do you have that show improvement a to what degree? Or is this all a hunch?