ouroboros-ai 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

ouroboros/bigbang/ambiguity.py

@@ -9,6 +9,8 @@ The scoring algorithm evaluates three key components:
 - Success Criteria Clarity (30%): How measurable the success criteria are
 """
 
+import json
+import re
 from dataclasses import dataclass
 from typing import Any
 
@@ -139,6 +141,7 @@ class AmbiguityScorer:
     temperature: float = SCORING_TEMPERATURE
     initial_max_tokens: int = 2048
     max_retries: int | None = None  # None = unlimited retries
+    max_format_error_retries: int = 5  # Stop after N format errors (non-truncation)
 
     async def score(
         self, state: InterviewState
@@ -303,38 +306,19 @@ class AmbiguityScorer:
         Returns:
             System prompt string.
         """
-        return """You are an expert requirements analyst evaluating the clarity of software requirements.
-
-Your task is to assess how clear and unambiguous the requirements are based on an interview conversation.
+        return """You are an expert requirements analyst. Evaluate the clarity of software requirements.
 
 Evaluate three components:
-1. Goal Clarity (40% weight): Is the goal statement specific and well-defined?
-   - Clear: "Build a CLI tool for task management with project grouping"
-   - Unclear: "Build something useful for productivity"
-
-2. Constraint Clarity (30% weight): Are constraints and limitations specified?
-   - Clear: "Must use Python 3.14+, no external database dependencies"
-   - Unclear: No mention of technical constraints or limitations
-
-3. Success Criteria Clarity (30% weight): Are success criteria measurable?
-   - Clear: "Tasks can be created, edited, deleted; supports filtering by status"
-   - Unclear: "The tool should be easy to use"
-
-For each component, provide:
-- A clarity score between 0.0 (completely unclear) and 1.0 (perfectly clear)
-- A brief justification (1-2 sentences max) explaining the score
+1. Goal Clarity (40%): Is the goal specific and well-defined?
+2. Constraint Clarity (30%): Are constraints and limitations specified?
+3. Success Criteria Clarity (30%): Are success criteria measurable?
 
-IMPORTANT: You MUST provide ALL six fields below. Keep justifications concise.
+Score each from 0.0 (unclear) to 1.0 (perfectly clear). Scores above 0.8 require very specific requirements.
 
-Respond in this exact format:
-GOAL_CLARITY_SCORE: <score>
-GOAL_CLARITY_JUSTIFICATION: <justification in 1-2 sentences>
-CONSTRAINT_CLARITY_SCORE: <score>
-CONSTRAINT_CLARITY_JUSTIFICATION: <justification in 1-2 sentences>
-SUCCESS_CRITERIA_CLARITY_SCORE: <score>
-SUCCESS_CRITERIA_CLARITY_JUSTIFICATION: <justification in 1-2 sentences>
+RESPOND ONLY WITH VALID JSON. No other text before or after.
 
-Be strict in your evaluation. Scores above 0.8 require very specific, measurable requirements."""
+Required JSON format:
+{"goal_clarity_score": 0.0, "goal_clarity_justification": "string", "constraint_clarity_score": 0.0, "constraint_clarity_justification": "string", "success_criteria_clarity_score": 0.0, "success_criteria_clarity_justification": "string"}"""
 
     def _build_scoring_user_prompt(self, context: str) -> str:
         """Build user prompt with interview context.
@@ -365,27 +349,23 @@ Analyze each component and provide scores with justifications."""
         Raises:
             ValueError: If response cannot be parsed.
         """
-        lines = response.strip().split("\n")
-        scores: dict[str, Any] = {}
-
-        for line in lines:
-            line = line.strip()
-            if not line:
-                continue
-
-            for prefix in [
-                "GOAL_CLARITY_SCORE:",
-                "GOAL_CLARITY_JUSTIFICATION:",
-                "CONSTRAINT_CLARITY_SCORE:",
-                "CONSTRAINT_CLARITY_JUSTIFICATION:",
-                "SUCCESS_CRITERIA_CLARITY_SCORE:",
-                "SUCCESS_CRITERIA_CLARITY_JUSTIFICATION:",
-            ]:
-                if line.startswith(prefix):
-                    key = prefix[:-1].lower()  # Remove colon and lowercase
-                    value = line[len(prefix) :].strip()
-                    scores[key] = value
-                    break
+        # Extract JSON from response (handle markdown code blocks)
+        text = response.strip()
+
+        # Try to find JSON in markdown code block
+        json_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+        if json_match:
+            text = json_match.group(1)
+        else:
+            # Try to find raw JSON object
+            json_match = re.search(r"\{.*\}", text, re.DOTALL)
+            if json_match:
+                text = json_match.group(0)
+
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON response: {e}") from e
 
         # Validate all required fields are present
         required_fields = [
@@ -398,35 +378,32 @@ Analyze each component and provide scores with justifications."""
         ]
 
         for field_name in required_fields:
-            if field_name not in scores:
+            if field_name not in data:
                 raise ValueError(f"Missing required field: {field_name}")
 
-        # Parse scores to float
-        def parse_score(value: str) -> float:
-            try:
-                score = float(value)
-                return max(0.0, min(1.0, score))  # Clamp to [0, 1]
-            except ValueError as e:
-                raise ValueError(f"Invalid score value: {value}") from e
+        # Parse and clamp scores
+        def clamp_score(value: Any) -> float:
+            score = float(value)
+            return max(0.0, min(1.0, score))
 
         return ScoreBreakdown(
             goal_clarity=ComponentScore(
                 name="Goal Clarity",
-                clarity_score=parse_score(scores["goal_clarity_score"]),
+                clarity_score=clamp_score(data["goal_clarity_score"]),
                 weight=GOAL_CLARITY_WEIGHT,
-                justification=scores["goal_clarity_justification"],
+                justification=str(data["goal_clarity_justification"]),
             ),
             constraint_clarity=ComponentScore(
                 name="Constraint Clarity",
-                clarity_score=parse_score(scores["constraint_clarity_score"]),
+                clarity_score=clamp_score(data["constraint_clarity_score"]),
                 weight=CONSTRAINT_CLARITY_WEIGHT,
-                justification=scores["constraint_clarity_justification"],
+                justification=str(data["constraint_clarity_justification"]),
             ),
             success_criteria_clarity=ComponentScore(
                 name="Success Criteria Clarity",
-                clarity_score=parse_score(scores["success_criteria_clarity_score"]),
+                clarity_score=clamp_score(data["success_criteria_clarity_score"]),
                 weight=SUCCESS_CRITERIA_CLARITY_WEIGHT,
-                justification=scores["success_criteria_clarity_justification"],
+                justification=str(data["success_criteria_clarity_justification"]),
             ),
         )
 

ouroboros/bigbang/interview.py

@@ -1,7 +1,7 @@
 """Interactive interview engine for requirement clarification.
 
 This module implements the interview protocol that refines vague ideas into
-clear requirements through iterative questioning (max 10 rounds).
+clear requirements through iterative questioning. Users control when to stop.
 """
 
 from collections.abc import Iterator
@@ -52,10 +52,17 @@ def _file_lock(file_path: Path, exclusive: bool = True) -> Iterator[None]:
 
 log = structlog.get_logger()
 
-MAX_INTERVIEW_ROUNDS = 10
+# Interview round constants
+MIN_ROUNDS_BEFORE_EARLY_EXIT = 3  # Must complete at least 3 rounds
+SOFT_LIMIT_WARNING_THRESHOLD = 15  # Warn about diminishing returns after this
+DEFAULT_INTERVIEW_ROUNDS = 10  # Reference value for prompts (not enforced)
+
 # Default model moved to config.models.ClarificationConfig.default_model
 _FALLBACK_MODEL = "openrouter/google/gemini-2.0-flash-001"
 
+# Legacy alias for backward compatibility
+MAX_INTERVIEW_ROUNDS = DEFAULT_INTERVIEW_ROUNDS
+
 
 class InterviewStatus(StrEnum):
     """Status of the interview process."""
@@ -69,13 +76,13 @@ class InterviewRound(BaseModel):
     """A single round of interview questions and responses.
 
     Attributes:
-        round_number: 1-based round number (1 to MAX_INTERVIEW_ROUNDS).
+        round_number: 1-based round number (no upper limit - user controls).
         question: The question asked by the system.
         user_response: The user's response (None if not yet answered).
         timestamp: When this round was created.
     """
 
-    round_number: int = Field(ge=1, le=MAX_INTERVIEW_ROUNDS)
+    round_number: int = Field(ge=1)  # No upper limit - user decides when to stop
     question: str
     user_response: str | None = None
     timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
@@ -107,11 +114,8 @@ class InterviewState(BaseModel):
 
     @property
     def is_complete(self) -> bool:
-        """Check if interview has reached max rounds or is marked complete."""
-        return (
-            self.status == InterviewStatus.COMPLETED
-            or len(self.rounds) >= MAX_INTERVIEW_ROUNDS
-        )
+        """Check if interview is marked complete (user-controlled)."""
+        return self.status == InterviewStatus.COMPLETED
 
     def mark_updated(self) -> None:
         """Update the updated_at timestamp."""
@@ -321,14 +325,8 @@ class InterviewEngine:
             response_length=len(user_response),
         )
 
-        # Check if we've reached max rounds
-        if len(state.rounds) >= MAX_INTERVIEW_ROUNDS:
-            state.status = InterviewStatus.COMPLETED
-            log.info(
-                "interview.max_rounds_reached",
-                interview_id=state.interview_id,
-                total_rounds=len(state.rounds),
-            )
+        # Note: No auto-complete on round limit. User controls when to stop.
+        # CLI handles prompting user to continue after each round.
 
         return Result.ok(state)
 
@@ -437,7 +435,7 @@ class InterviewEngine:
         Returns:
             The system prompt.
         """
-        round_info = f"Round {state.current_round_number} of {MAX_INTERVIEW_ROUNDS}"
+        round_info = f"Round {state.current_round_number}"
 
         return f"""You are an expert requirements engineer conducting an interview to refine vague ideas into clear, executable requirements.
 

ouroboros/cli/commands/init.py

@@ -5,6 +5,7 @@ Supports both LiteLLM (external API) and Claude Code (Max Plan) modes.
 """
 
 import asyncio
+from enum import Enum, auto
 from pathlib import Path
 from typing import Annotated
 
@@ -12,13 +13,28 @@ from rich.prompt import Confirm, Prompt
 import typer
 
 from ouroboros.bigbang.ambiguity import AmbiguityScorer
-from ouroboros.bigbang.interview import MAX_INTERVIEW_ROUNDS, InterviewEngine, InterviewState
+from ouroboros.bigbang.interview import (
+    MIN_ROUNDS_BEFORE_EARLY_EXIT,
+    SOFT_LIMIT_WARNING_THRESHOLD,
+    InterviewEngine,
+    InterviewState,
+    InterviewStatus,
+)
 from ouroboros.bigbang.seed_generator import SeedGenerator
 from ouroboros.cli.formatters import console
 from ouroboros.cli.formatters.panels import print_error, print_info, print_success, print_warning
 from ouroboros.providers.base import LLMAdapter
 from ouroboros.providers.litellm_adapter import LiteLLMAdapter
 
+
+class SeedGenerationResult(Enum):
+    """Result of seed generation attempt."""
+
+    SUCCESS = auto()
+    CANCELLED = auto()
+    CONTINUE_INTERVIEW = auto()
+
+
 app = typer.Typer(
     name="init",
     help="Start interactive interview to refine requirements.",
@@ -43,62 +59,30 @@ def _get_adapter(use_orchestrator: bool) -> LLMAdapter:
         return LiteLLMAdapter()
 
 
-async def _run_interview(
-    initial_context: str,
-    resume_id: str | None = None,
-    state_dir: Path | None = None,
-    use_orchestrator: bool = False,
-) -> None:
-    """Run the interview process.
+async def _run_interview_loop(
+    engine: InterviewEngine,
+    state: InterviewState,
+) -> InterviewState:
+    """Run the interview question loop until completion or user exit.
 
-    Args:
-        initial_context: Initial context or idea for the interview.
-        resume_id: Optional interview ID to resume.
-        state_dir: Optional custom state directory.
-        use_orchestrator: If True, use Claude Code (Max Plan) instead of LiteLLM.
-    """
-    # Initialize components
-    llm_adapter = _get_adapter(use_orchestrator)
-    engine = InterviewEngine(
-        llm_adapter=llm_adapter,
-        state_dir=state_dir or Path.home() / ".ouroboros" / "data",
-    )
+    Implements tiered confirmation:
+    - Rounds 1-3: Auto-continue (minimum context)
+    - Rounds 4-15: Ask "Continue?" after each round
+    - Rounds 16+: Ask "Continue?" with diminishing returns warning
 
-    # Load or start interview
-    if resume_id:
-        print_info(f"Resuming interview: {resume_id}")
-        state_result = await engine.load_state(resume_id)
-        if state_result.is_err:
-            print_error(f"Failed to load interview: {state_result.error.message}")
-            raise typer.Exit(code=1)
-        state = state_result.value
-    else:
-        print_info("Starting new interview session...")
-        state_result = await engine.start_interview(initial_context)
-        if state_result.is_err:
-            print_error(f"Failed to start interview: {state_result.error.message}")
-            raise typer.Exit(code=1)
-        state = state_result.value
-
-    console.print()
-    console.print(
-        f"[bold cyan]Interview Session: {state.interview_id}[/]",
-    )
-    console.print(f"[muted]Max rounds: {MAX_INTERVIEW_ROUNDS}[/]")
-    console.print()
+    Args:
+        engine: Interview engine instance.
+        state: Current interview state.
 
-    # Interview loop
+    Returns:
+        Updated interview state.
+    """
     while not state.is_complete:
         current_round = state.current_round_number
-        console.print(
-            f"[bold]Round {current_round}/{MAX_INTERVIEW_ROUNDS}[/]",
-        )
+        console.print(f"[bold]Round {current_round}[/]")
 
         # Generate question
-        with console.status(
-            "[cyan]Generating question...[/]",
-            spinner="dots",
-        ):
+        with console.status("[cyan]Generating question...[/]", spinner="dots"):
             question_result = await engine.ask_next_question(state)
 
         if question_result.is_err:
@@ -130,15 +114,22 @@ async def _run_interview(
 
         state = record_result.value
 
-        # Save state
+        # Save state immediately after recording
         save_result = await engine.save_state(state)
         if save_result.is_err:
             print_error(f"Warning: Failed to save state: {save_result.error.message}")
 
         console.print()
 
-        # Check if user wants to continue or finish early
-        if not state.is_complete and current_round >= 3:
+        # Tiered confirmation logic
+        if current_round >= MIN_ROUNDS_BEFORE_EARLY_EXIT:
+            # Show warning for rounds beyond soft limit
+            if current_round >= SOFT_LIMIT_WARNING_THRESHOLD:
+                print_warning(
+                    f"Round {current_round}: Diminishing returns expected. "
+                    "Consider generating Seed to check ambiguity score."
+                )
+
             should_continue = Confirm.ask(
                 "Continue with more questions?",
                 default=True,
@@ -147,40 +138,104 @@ async def _run_interview(
                 complete_result = await engine.complete_interview(state)
                 if complete_result.is_ok:
                     state = complete_result.value
-                    await engine.save_state(state)
+                await engine.save_state(state)
                 break
 
-    # Interview complete
-    console.print()
-    print_success("Interview completed!")
-    console.print(f"[muted]Total rounds: {len(state.rounds)}[/]")
-    console.print(f"[muted]Interview ID: {state.interview_id}[/]")
+    return state
 
-    # Save final state
-    save_result = await engine.save_state(state)
-    if save_result.is_ok:
-        console.print(f"[muted]State saved to: {save_result.value}[/]")
 
-    console.print()
+async def _run_interview(
+    initial_context: str,
+    resume_id: str | None = None,
+    state_dir: Path | None = None,
+    use_orchestrator: bool = False,
+) -> None:
+    """Run the interview process.
 
-    # Ask if user wants to proceed to Seed generation
-    should_generate_seed = Confirm.ask(
-        "[bold cyan]Proceed to generate Seed specification?[/]",
-        default=True,
+    Args:
+        initial_context: Initial context or idea for the interview.
+        resume_id: Optional interview ID to resume.
+        state_dir: Optional custom state directory.
+        use_orchestrator: If True, use Claude Code (Max Plan) instead of LiteLLM.
+    """
+    # Initialize components
+    llm_adapter = _get_adapter(use_orchestrator)
+    engine = InterviewEngine(
+        llm_adapter=llm_adapter,
+        state_dir=state_dir or Path.home() / ".ouroboros" / "data",
     )
 
-    if not should_generate_seed:
-        console.print(
-            "[muted]You can resume later with:[/] "
-            f"[bold]ouroboros init start --resume {state.interview_id}[/]"
+    # Load or start interview
+    if resume_id:
+        print_info(f"Resuming interview: {resume_id}")
+        state_result = await engine.load_state(resume_id)
+        if state_result.is_err:
+            print_error(f"Failed to load interview: {state_result.error.message}")
+            raise typer.Exit(code=1)
+        state = state_result.value
+    else:
+        print_info("Starting new interview session...")
+        state_result = await engine.start_interview(initial_context)
+        if state_result.is_err:
+            print_error(f"Failed to start interview: {state_result.error.message}")
+            raise typer.Exit(code=1)
+        state = state_result.value
+
+    console.print()
+    console.print(f"[bold cyan]Interview Session: {state.interview_id}[/]")
+    console.print("[muted]No round limit - you decide when to stop[/]")
+    console.print()
+
+    # Run initial interview loop
+    state = await _run_interview_loop(engine, state)
+
+    # Outer loop for retry on high ambiguity
+    while True:
+        # Interview complete
+        console.print()
+        print_success("Interview completed!")
+        console.print(f"[muted]Total rounds: {len(state.rounds)}[/]")
+        console.print(f"[muted]Interview ID: {state.interview_id}[/]")
+
+        # Save final state
+        save_result = await engine.save_state(state)
+        if save_result.is_ok:
+            console.print(f"[muted]State saved to: {save_result.value}[/]")
+
+        console.print()
+
+        # Ask if user wants to proceed to Seed generation
+        should_generate_seed = Confirm.ask(
+            "[bold cyan]Proceed to generate Seed specification?[/]",
+            default=True,
         )
-        return
 
-    # Generate Seed
-    seed_path = await _generate_seed_from_interview(state, llm_adapter)
+        if not should_generate_seed:
+            console.print(
+                "[muted]You can resume later with:[/] "
+                f"[bold]ouroboros init start --resume {state.interview_id}[/]"
+            )
+            return
 
-    if seed_path is None:
-        return
+        # Generate Seed
+        seed_path, result = await _generate_seed_from_interview(state, llm_adapter)
+
+        if result == SeedGenerationResult.CONTINUE_INTERVIEW:
+            # Re-open interview for more questions
+            console.print()
+            print_info("Continuing interview to reduce ambiguity...")
+            state.status = InterviewStatus.IN_PROGRESS
+            await engine.save_state(state)  # Save status change immediately
+
+            # Continue interview loop (reusing the same helper)
+            state = await _run_interview_loop(engine, state)
+            continue
+
+        if result == SeedGenerationResult.CANCELLED:
+            return
+
+        # Success - proceed to workflow
+        break
 
     # Ask if user wants to start workflow
     console.print()
@@ -196,7 +251,7 @@ async def _run_interview(
 async def _generate_seed_from_interview(
     state: InterviewState,
     llm_adapter: LLMAdapter,
-) -> Path | None:
+) -> tuple[Path | None, SeedGenerationResult]:
     """Generate Seed from completed interview.
 
     Args:
@@ -204,7 +259,7 @@ async def _generate_seed_from_interview(
         llm_adapter: LLM adapter for scoring and generation.
 
     Returns:
-        Path to generated seed file, or None if failed.
+        Tuple of (path to generated seed file or None, result status).
     """
     console.print()
     console.print("[bold cyan]Generating Seed specification...[/]")
@@ -216,7 +271,7 @@ async def _generate_seed_from_interview(
 
     if score_result.is_err:
         print_error(f"Failed to calculate ambiguity: {score_result.error.message}")
-        return None
+        return None, SeedGenerationResult.CANCELLED
 
     ambiguity_score = score_result.value
     console.print(f"[muted]Ambiguity score: {ambiguity_score.overall_score:.2f}[/]")
@@ -226,12 +281,24 @@ async def _generate_seed_from_interview(
             f"Ambiguity score ({ambiguity_score.overall_score:.2f}) is too high. "
             "Consider more interview rounds to clarify requirements."
         )
-        should_force = Confirm.ask(
-            "[yellow]Generate Seed anyway?[/]",
-            default=False,
+        console.print()
+        console.print("[bold]What would you like to do?[/]")
+        console.print("  [cyan]1[/] - Continue interview with more questions")
+        console.print("  [cyan]2[/] - Generate Seed anyway (force)")
+        console.print("  [cyan]3[/] - Cancel")
+        console.print()
+
+        choice = Prompt.ask(
+            "[yellow]Select option[/]",
+            choices=["1", "2", "3"],
+            default="1",
         )
-        if not should_force:
-            return None
+
+        if choice == "1":
+            return None, SeedGenerationResult.CONTINUE_INTERVIEW
+        elif choice == "3":
+            return None, SeedGenerationResult.CANCELLED
+        # choice == "2" falls through to generate anyway
 
     # Step 2: Generate Seed
     with console.status("[cyan]Generating Seed from interview...[/]", spinner="dots"):
@@ -240,18 +307,20 @@ async def _generate_seed_from_interview(
         if ambiguity_score.is_ready_for_seed:
             seed_result = await generator.generate(state, ambiguity_score)
         else:
-            # Create a modified score that passes threshold for forced generation
+            # TODO: Add force=True parameter to SeedGenerator.generate() instead of this hack
+            # Creating a modified score to bypass threshold check
             from ouroboros.bigbang.ambiguity import AmbiguityScore as AmbScore
 
+            FORCED_SCORE_VALUE = 0.19  # Just under threshold (0.2)
             forced_score = AmbScore(
-                overall_score=0.19,  # Just under threshold
+                overall_score=FORCED_SCORE_VALUE,
                 breakdown=ambiguity_score.breakdown,
             )
             seed_result = await generator.generate(state, forced_score)
 
     if seed_result.is_err:
         print_error(f"Failed to generate Seed: {seed_result.error.message}")
-        return None
+        return None, SeedGenerationResult.CANCELLED
 
     seed = seed_result.value
 
@@ -261,10 +330,10 @@ async def _generate_seed_from_interview(
 
     if save_result.is_err:
         print_error(f"Failed to save Seed: {save_result.error.message}")
-        return None
+        return None, SeedGenerationResult.CANCELLED
 
     print_success(f"Seed generated: {seed_path}")
-    return seed_path
+    return seed_path, SeedGenerationResult.SUCCESS
 
 
 async def _start_workflow(seed_path: Path, use_orchestrator: bool = False) -> None:
@@ -344,21 +413,17 @@ def start(
     """
     # Get initial context if not provided
     if not resume and not context:
-        console.print(
-            "[bold cyan]Welcome to Ouroboros Interview![/]",
-        )
+        console.print("[bold cyan]Welcome to Ouroboros Interview![/]")
         console.print()
         console.print(
             "This interactive process will help refine your ideas into clear requirements.",
         )
         console.print(
-            f"You'll be asked up to {MAX_INTERVIEW_ROUNDS} questions to reduce ambiguity.",
+            "You control when to stop - no arbitrary round limit.",
         )
         console.print()
 
-        context = Prompt.ask(
-            "[bold]What would you like to build?[/]",
-        )
+        context = Prompt.ask("[bold]What would you like to build?[/]")
 
     if not resume and not context:
         print_error("Initial context is required when not resuming.")

{ouroboros_ai-0.2.2.dist-info → ouroboros_ai-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.2.2
+Version: 0.3.0
 Summary: Self-Improving AI Workflow System
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE
@@ -41,18 +41,26 @@ Description-Content-Type: text/markdown
   <em>The serpent that devours itself to be reborn anew.</em>
 </p>
 
+<p align="center">
+  <a href="https://pypi.org/project/ouroboros-ai/"><img src="https://img.shields.io/pypi/v/ouroboros-ai?color=blue" alt="PyPI"></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.14+-blue" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+</p>
+
 <p align="center">
   <a href="#-philosophy">Philosophy</a> •
   <a href="#-the-six-phases">Phases</a> •
   <a href="#-architecture">Architecture</a> •
+  <a href="#-prerequisites">Prerequisites</a> •
   <a href="#-quick-start">Start</a> •
-  <a href="#-the-personas-lateral-thinking-agents">Personas</a>
+  <a href="#-roadmap">Roadmap</a> •
+  <a href="#-contributing">Contributing</a>
 </p>
 
 <br/>
 
 <p align="center">
-  <code>74 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
+  <code>75 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code> · <code>v0.2.x</code>
 </p>
 
 <br/>
@@ -352,7 +360,7 @@ src/ouroboros/
 
 <br/>
 
-**작동 방식**: Stagnation Detection (4 patterns) → Persona Rotation → 새로운 관점으로 재시도
+**How it works**: Stagnation Detection (4 patterns) → Persona Rotation → Retry with fresh perspective
 
 <br/>
 
@@ -415,6 +423,22 @@ not to restart, but to **re-crystallize** with new understanding.
 
 <br/>
 
+## ◈ Prerequisites
+
+<br/>
+
+| Requirement | Description |
+|-------------|-------------|
+| **Python 3.14+** | Required (uses latest language features) |
+| **Claude Code Max Plan** | For orchestrator mode (no API key needed) |
+| **OR API Key** | OpenRouter, Anthropic, or OpenAI for LiteLLM mode |
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Installation
 
 <br/>
@@ -476,7 +500,7 @@ uv run ouroboros init start "I want to build a task management CLI"
 uv run ouroboros status health
 ```
 
-> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)**
+> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)** | **[CLI Reference](docs/cli-reference.md)**
 
 <br/>
 
@@ -563,22 +587,49 @@ uv run ruff format src/
 
 <br/>
 
+## ◈ Contributing
+
+<br/>
+
+Contributions are welcome! Please see:
+
+- **Issues**: [GitHub Issues](https://github.com/Q00/ouroboros/issues) for bugs and feature requests
+- **Discussions**: [GitHub Discussions](https://github.com/Q00/ouroboros/discussions) for questions and ideas
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Roadmap
 
 <br/>
 
+### Completed
+
 ```
-[■■■■■■■■■■] Epic 0  Foundation
-[■■■■■■■■■■] Epic 1  Big Bang
-[■■■■■■■■■■] Epic 2  PAL Router
-[■■■■■■■■■■] Epic 3  Double Diamond
-[■■■■■■■■■■] Epic 4  Resilience
-[■■■■■■■■■■] Epic 5  Evaluation
-[■■■■■■■■■■] Epic 6  Drift Control
-[■■■■■■■■■■] Epic 7  Secondary Loop
-[■■■■■■■■■■] Epic 8  Orchestrator      ✓ Complete
+[■■■■■■■■■■] Epic 0  Foundation          ✓
+[■■■■■■■■■■] Epic 1  Big Bang            ✓
+[■■■■■■■■■■] Epic 2  PAL Router          ✓
+[■■■■■■■■■■] Epic 3  Double Diamond      ✓
+[■■■■■■■■■■] Epic 4  Resilience          ✓
+[■■■■■■■■■■] Epic 5  Evaluation          ✓
+[■■■■■■■■■■] Epic 6  Drift Control       ✓
+[■■■■■■■■■■] Epic 7  Secondary Loop      ✓
+[■■■■■■■■■■] Epic 8  Orchestrator        ✓
 ```
 
+### Upcoming
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Worker MCP** | MCP server for distributed task execution | Planned |
+| **TUI Enhancement** | Rich terminal UI with real-time progress | Planned |
+| **AC Tree Visualization** | Interactive acceptance criteria graph | Planned |
+| **Plugin System** | Custom evaluators and personas | Planned |
+| **Web Dashboard** | Execution monitoring and analytics | Planned |
+
 <br/>
 
 ---

{ouroboros_ai-0.2.2.dist-info → ouroboros_ai-0.3.0.dist-info}/RECORD

@@ -2,14 +2,14 @@ ouroboros/__init__.py,sha256=lmQgHmNOWxGlmwayNvp1ckCuJycL8WzX5Y-7IzrFaVM,701
 ouroboros/__main__.py,sha256=f_qnL0zPJwh9kfQqynX5adpqzj8ilj94zW5Q2loqGxE,168
 ouroboros/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ouroboros/bigbang/__init__.py,sha256=9xGqOYwMKBifb7QVwonc_wndNLMZb7ZH7xgMHaz_70A,951
-ouroboros/bigbang/ambiguity.py,sha256=pmvahQP41OVL8o6N7DkNHM8zqsLYYhem_CfM2X5xuGE,18911
-ouroboros/bigbang/interview.py,sha256=zm1VrDNqE8ouGG62h8qnNkIpnUf3HHv4NjzMKDIaWcY,17147
+ouroboros/bigbang/ambiguity.py,sha256=5KM8xjATknjLZguVa90Yii6o3pzXE4PU4BJIP6Ii938,17955
+ouroboros/bigbang/interview.py,sha256=ku1MVppSmIS9OZeiqC208el4ZqoYYQwT78ycLenwID4,17200
 ouroboros/bigbang/seed_generator.py,sha256=7MY9a7Eua_zVGDWIVDlzOZJjeAwz0DRatXJg0PvMgiY,20082
 ouroboros/cli/__init__.py,sha256=CRpxsqJadZL7bCS-yrULWC51tqPKfPsxQLgt0JiwP4g,225
 ouroboros/cli/main.py,sha256=ldvqtVpw2xZwE8G7M34qY_7qg0RuNiydjdmmU-hdJvM,1485
 ouroboros/cli/commands/__init__.py,sha256=LZpEvU80R4Cq0LwgkwOluEGNsmmJ9K7roeDQ6bsbbDc,193
 ouroboros/cli/commands/config.py,sha256=kcqi0Wo09oo1MMyZIX4k2IDICV1SAX6HzAXZaIJGdKY,2100
-ouroboros/cli/commands/init.py,sha256=HmXwTLyso6p8Df5aAguxh-XTIYZGkzGltGXqJvDxI78,13536
+ouroboros/cli/commands/init.py,sha256=y2hlHnqFkc9-44_mJUs3GmQvX4Tg6yTIyb0e0KCPl30,16130
 ouroboros/cli/commands/run.py,sha256=DnxfbSdATDIaNYJXLcwAcR9NqNVGkVlHgYJImaSVn4I,6328
 ouroboros/cli/commands/status.py,sha256=Bnqpj1UkqhpBPYA11DV-Z63Bz8pjrebhlzeMKwz3_Ps,2217
 ouroboros/cli/formatters/__init__.py,sha256=-Ik7KXajaIExBxSAp5iYp8gO9SfXudGjyDe2nm2_msw,691
@@ -75,8 +75,8 @@ ouroboros/routing/tiers.py,sha256=QhBQUOo2-h5Z3dEtC0lcOzkRnqTi2W7Jl46750AVNig,73
 ouroboros/secondary/__init__.py,sha256=kYQ7C4bnBzwDlPrU8qZrOPr2ZuTBaftGktOXl5WZl5Q,1123
 ouroboros/secondary/scheduler.py,sha256=sPVVWJ1q0yewRAM-Rm1j_HMerSe4cavIvP9z4xlUuL4,13737
 ouroboros/secondary/todo_registry.py,sha256=4W3C9Uro29VrVLCPKUlpH_BYpzQSbRNW1oMnDYyEhEw,13880
-ouroboros_ai-0.2.2.dist-info/METADATA,sha256=v_WwLBVh1qLB3vaFS2PwNCiODepMmq-zitj82ty4jPs,19661
-ouroboros_ai-0.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-ouroboros_ai-0.2.2.dist-info/entry_points.txt,sha256=MoETHup6rVkR6AsyjoRzAgIuvVtYYm3Jw40itV3_VyI,53
-ouroboros_ai-0.2.2.dist-info/licenses/LICENSE,sha256=n2X-q26TqpXnoBo0t_WouhFxWw663_q5FmbYDZayoHo,1060
-ouroboros_ai-0.2.2.dist-info/RECORD,,
+ouroboros_ai-0.3.0.dist-info/METADATA,sha256=J5my7Xvr9PRNCn081N7t6ER3cvRP7AFwWilWjcf5fUo,21321
+ouroboros_ai-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ouroboros_ai-0.3.0.dist-info/entry_points.txt,sha256=MoETHup6rVkR6AsyjoRzAgIuvVtYYm3Jw40itV3_VyI,53
+ouroboros_ai-0.3.0.dist-info/licenses/LICENSE,sha256=n2X-q26TqpXnoBo0t_WouhFxWw663_q5FmbYDZayoHo,1060
+ouroboros_ai-0.3.0.dist-info/RECORD,,