README.md

Documentation Index (openTiger)

This directory organizes openTiger implementation specifications into "navigation paths" and "references."
With source code as the source of truth, information necessary for operations is structured for progressive reading.

Table of Contents

• 0. Purpose-Based Navigation
• 0.1 Recommended Lanes by Reader Type
• 1. First-Time User Path (Shortest)
• 2. Execution Model and Recovery Strategy
• 3. Agent Specifications
• 4. Design Principles and Supplementary Materials
• Recommended Reading Order (Shortest)
• Lookup When Making Changes

0. Purpose-Based Navigation

Purpose	Shortest Page to Read
Want to get it running first	getting-started
Want to grasp the overview	architecture
Want to tune config keys	config
Want API integration	api-reference
Want to build your own plugin	plugins
Need incident response	operations + flow
Quick initial diagnosis of stalled state	state-model
Immediate lookup of retry.reason meanings	state-model
Trace by state vocabulary -> transition -> owner -> implementation	state-model -> flow -> agent/README
Confirm startup condition formulas	startup-patterns
Compare agent role differences	agent/README
Build/run TigerResearch (query -> evidence-backed report)	research

0.1 Recommended Lanes by Reader Type

Lane A: First-Time Users (shortest path to run)

1. getting-started
2. architecture
3. operations

Goals:

• Complete the first run
• Finish the 5-minute post-startup check

Lane B: Operations (stable operation and recovery)

1. operations
2. config
3. state-model
4. flow
5. startup-patterns

Goals:

• Perform rapid triage and restart decisions during incidents
• Avoid mistakes in impact scope of config changes

Shortcut for stalled state:

• state-model -> flow -> operations (8.1 "State vocabulary -> transition -> owner -> implementation lookup") -> agent/README

Lane C: Implementation Tracing (track source diffs)

1. architecture
2. agent/README
3. agent/planner, agent/dispatcher, agent/worker, etc.
4. api-reference
5. config

Goals:

• Understand component responsibilities and implementation boundaries
• Trace related areas without omission when changing API/config
• Reach code quickly via "Implementation reference (source of truth)" in agent specs

Lane D: TigerResearch Design/Operation

1. research
2. architecture
3. flow
4. api-reference
5. operations
6. plugins

Goals:

• Understand planner-first research orchestration
• Tune quality thresholds and runtime behavior
• Troubleshoot research stalls/cancellations quickly

1. First-Time User Path (Shortest)

1. getting-started
   • Setup, first run, execution start via Start page
2. architecture
   • Component responsibilities and data flow
3. config
   • system_config and environment variable reference
4. api-reference
   • Main endpoints for Dashboard/API integration
5. operations
   • Operations, incident recovery, log inspection, runtime hatch

2. Execution Model and Recovery Strategy

• state-model
  • State definitions for task/run/agent/cycle
• flow
  • End-to-end state transitions and recovery loops
• startup-patterns
  • Startup preflight rules and runtime convergence conditions
• mode
  • REPO_MODE / JUDGE_MODE / execution mode operation guidelines
• execution-mode
  • host/sandbox execution differences and sandbox authentication
• policy-recovery
  • Policy violation recovery, allowedPaths self-growth
• verification
  • Planner/Worker verification command resolution strategy
• verify-recovery
  • Verification recovery index (Worker/Cycle Manager split docs)
• verify-recovery-worker
  • Worker-side failure code resolution and skip/retry guard behavior
• verify-recovery-cycle-manager
  • Cycle Manager-side command adjustment and blocked/failed requeue behavior
• research
  • TigerResearch planner-first lifecycle and quality gates

3. Agent Specifications

• agent/README (cross-agent comparison)
• agent/planner
• agent/dispatcher
• agent/worker
• agent/tester
• agent/judge
• agent/docser
• agent/cycle-manager

4. Design Principles and Supplementary Materials

• nonhumanoriented
  • Design principles based on non-stalling assumption
• requirement
  • Requirement template example
• idea
  • Improvement idea notes (future plans)
• research
  • Query-driven research subsystem specification
• plugins
  • Plugin registry and extension implementation guide

Recommended Reading Order (Shortest)

1. getting-started
2. architecture
3. config
4. api-reference
5. operations
6. flow
7. agent/README

Lookup When Making Changes

• When changing startup conditions or replan conditions:
  • startup-patterns
  • flow (related runtime impact)
• When changing task state transitions or blocked recovery:
  • state-model
  • flow
  • operations
• When changing agent implementation responsibilities:
  • agent/README
  • Target agent specs