Files

T

YeonGyu-Kim 1e7a7600a2 docs(agents-md): regenerate hierarchical AGENTS.md knowledge base for v4.1.1

Refresh all AGENTS.md files to reflect codebase state at 5ffbe0e24 (was cd31d2a1a, 197 commits behind).

Key drift corrections across 45 modified + 1 new file:

Root AGENTS.md:
- TS file counts: 1967 -> 2034 in src/ (1337 source + 697 test)
- LOC: 278k -> 292k
- Barrel index.ts: 120 -> 122
- Hook tier composition: 52/59 -> 54/61 (base/with team-mode)
- Tool Guard hooks: 14 -> 16 (add fsync-skip-warning, bash-file-read-guard)
- Add boulder feature, agent-ordering schema, .agents/ directory, v4.1.1 release tag
- Add generated/ directory entry

src/AGENTS.md:
- Subsystem inventory: agents 96->102, hooks 570->581, tools 306->314,
  features 389->400, shared 258->278, cli 150->158, plugin 55->56
- LOC totals refreshed for every subsystem
- Schema files: 32 -> 30

src/hooks/AGENTS.md:
- Tier 2 (Tool Guard): 14 -> 16 hooks, add fsyncSkipWarning row
- Total: 52 base / 59 team-mode -> 54 base / 61 team-mode
- zauc-mocks count: 7 -> 5

src/features/AGENTS.md:
- background-agent: 47 -> 57 files, mention archive fallback
- opencode-skill-loader: 33 -> 30
- tmux-subagent: 34 -> 32

src/plugin/AGENTS.md:
- Tool Guard composer count: 14 -> 16
- Aggregator total: 43 -> 45

src/cli/AGENTS.md:
- Add new boulder subcommand (BoulderState inspector)
- Command count: 6 -> 7

NEW: src/features/boulder-state/AGENTS.md
- Document the new Boulder work tracking feature
- Schema v2 with BoulderState/BoulderWorkState/TaskSessionState
- Lifecycle, storage, integration points with atlas/ralph-loop hooks

All other AGENTS.md files: Generated date 2026-05-08 -> 2026-05-14.

2026-05-14 12:57:46 +09:00

2.3 KiB

Raw Blame History

src/hooks/ralph-loop/ — Self-Referential Dev Loop

Generated: 2026-05-14

OVERVIEW

14 files (~1687 LOC). The ralphLoop Session Tier hook — powers the /ralph-loop command. Iterates a development loop until the agent emits <promise>DONE</promise> or max iterations reached.

LOOP LIFECYCLE

/ralph-loop → startLoop(sessionID, prompt, options)
  → loopState.startLoop() → persists state to .sisyphus/ralph-loop.local.md
  → session.idle events → createRalphLoopEventHandler()
    → completionPromiseDetector: scan output for <promise>DONE</promise>
    → if not done: inject continuation prompt → loop
    → if done or maxIterations: cancelLoop()

KEY FILES

File	Purpose
`ralph-loop-hook.ts`	`createRalphLoopHook()` — composes controller + recovery + event handler
`ralph-loop-event-handler.ts`	`createRalphLoopEventHandler()` — handles session.idle, drives loop
`loop-state-controller.ts`	State CRUD: startLoop, cancelLoop, getState, persist to disk
`loop-session-recovery.ts`	Recover from crashed/interrupted loop sessions
`completion-promise-detector.ts`	Scan session transcript for `<promise>DONE</promise>`
`continuation-prompt-builder.ts`	Build continuation message for next iteration
`continuation-prompt-injector.ts`	Inject built prompt into active session
`storage.ts`	Read/write `.sisyphus/ralph-loop.local.md` state file
`message-storage-directory.ts`	Temp dir for prompt injection
`with-timeout.ts`	API call wrapper with timeout (default 5000ms)
`types.ts`	`RalphLoopState`, `RalphLoopOptions`, loop iteration types

STATE FILE

.sisyphus/ralph-loop.local.md  (gitignored)
  → sessionID, prompt, iteration count, maxIterations, completionPromise, ultrawork flag

OPTIONS

startLoop(sessionID, prompt, {
  maxIterations?: number  // Default from config (default: 100)
  completionPromise?: string  // Custom "done" signal (default: "<promise>DONE</promise>")
  ultrawork?: boolean  // Enable ultrawork mode for iterations
})

EXPORTED INTERFACE

interface RalphLoopHook {
  event: (input) => Promise<void>  // session.idle handler
  startLoop: (sessionID, prompt, options?) => boolean
  cancelLoop: (sessionID) => boolean
  getState: () => RalphLoopState | null
}

2.3 KiB Raw Blame History