galangal-orchestrate 0.6.3__tar.gz → 0.12.15__tar.gz

{galangal_orchestrate-0.6.3 → galangal_orchestrate-0.12.15}/.gitignore

@@ -69,4 +69,5 @@ galangal-tasks/
 
 # Ideas (local brainstorming)
 ideas/
-.test_venv
+.test_venv
+/GEMINI.md

{galangal_orchestrate-0.6.3 → galangal_orchestrate-0.12.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: galangal-orchestrate
-Version: 0.6.3
+Version: 0.12.15
 Summary: AI-driven development workflow orchestrator
 Project-URL: Homepage, https://github.com/Galangal-Media/galangal-orchestrate
 Project-URL: Repository, https://github.com/Galangal-Media/galangal-orchestrate
@@ -97,7 +97,7 @@ galangal status
 | **PREFLIGHT** | Environment validation | PREFLIGHT_REPORT.md |
 | **DEV** | Implementation | Code changes |
 | **MIGRATION*** | Database migration checks | MIGRATION_REPORT.md |
-| **TEST** | Test implementation | TEST_PLAN.md |
+| **TEST** | Test implementation | TEST_PLAN.md, TEST_SUMMARY.md |
 | **CONTRACT*** | API contract validation | CONTRACT_REPORT.md |
 | **QA** | Quality assurance | QA_REPORT.md |
 | **BENCHMARK*** | Performance validation | BENCHMARK_REPORT.md |
@@ -107,6 +107,15 @@ galangal status
 
 *Conditional stages - skipped automatically if not relevant
 
+### Validation Artifacts
+
+When validation commands run (tests, linters, etc.), Galangal creates debugging artifacts:
+
+- **VALIDATION_REPORT.md** - Full output from all validation commands, useful for debugging failures
+- **TEST_SUMMARY.md** - Concise test results (pass/fail counts, failed test names, coverage) included in downstream stage prompts
+
+These artifacts help you understand what failed without digging through logs, and give downstream stages (QA, REVIEW) context about test results without bloating prompts with verbose output.
+
 ## Task Types
 
 Choose the right workflow for your task:
@@ -114,9 +123,9 @@ Choose the right workflow for your task:
 | Type | Stages | When to Use |
 |------|--------|-------------|
 | **Feature** | All stages | New functionality |
-| **Bug Fix** | PM → DEV → TEST → QA | Fixing bugs |
-| **Refactor** | PM → DESIGN → DEV → TEST | Code restructuring |
-| **Chore** | PM → DEV → TEST | Config, dependencies |
+| **Bug Fix** | PM → PREFLIGHT → DEV → TEST → QA | Fixing bugs |
+| **Refactor** | PM → DESIGN → PREFLIGHT → DEV → TEST | Code restructuring |
+| **Chore** | PM → PREFLIGHT → DEV → TEST | Config, dependencies |
 | **Docs** | PM → DOCS | Documentation only |
 | **Hotfix** | PM → DEV → TEST | Critical fixes |
 
@@ -167,6 +176,32 @@ After analyzing your task, the PM stage outputs a `STAGE_PLAN.md` recommending w
 
 The progress bar updates dynamically to show only relevant stages.
 
+### Workflow Preview
+
+After PM approval, you'll see a preview showing exactly which stages will run and why others are skipped:
+
+```
+Workflow Preview
+
+Stages to run:
+  PM → DESIGN → PREFLIGHT → DEV → TEST → QA → REVIEW → DOCS
+
+Skipping:
+  MIGRATION (no files match: **/migrations/*)
+  CONTRACT (no files match: **/api/*, **/openapi.*)
+  BENCHMARK (task type: bug_fix)
+  SECURITY (PM: simple UI change, no security impact)
+
+Controls during execution:
+  ^N Skip stage  ^B Back  ^E Pause for edit  ^I Interrupt
+```
+
+Skip reasons include:
+- **Task type** - Based on the workflow template (e.g., bug fixes skip DESIGN)
+- **Config** - Stages listed in `stages.skip` configuration
+- **PM recommendation** - From STAGE_PLAN.md analysis
+- **skip_if condition** - No changed files match the glob pattern
+
 ## Commands
 
 | Command | Description |
@@ -403,6 +438,9 @@ validation:
       - name: "Integration tests"
         command: "pytest tests/integration"
         optional: true         # Don't fail if integration tests missing
+      # Use array form for paths with spaces or special characters
+      - name: "Task-specific tests"
+        command: ["pytest", "{task_dir}/tests"]  # {task_dir} is substituted
 
   # Contract stage (API compatibility)
   contract:
@@ -458,21 +496,37 @@ ai:
   # Default backend to use
   default: claude
 
-  # Available backends
+  # Available backends with customizable CLI flags
   backends:
     claude:
-      command: claude
-      args:
-        - "-p"
-        - "{prompt}"
+      command: claude          # CLI command to invoke
+      args:                    # Arguments with {placeholder} substitution
         - "--output-format"
         - "stream-json"
         - "--verbose"
+        - "--max-turns"
+        - "{max_turns}"        # Replaced with max_turns value
+        - "--permission-mode"
+        - "bypassPermissions"
       max_turns: 200           # Maximum conversation turns per stage
+      read_only: false         # If true, backend cannot write files
+
+    codex:
+      command: codex
+      args:
+        - "exec"
+        - "--full-auto"
+        - "--output-schema"
+        - "{schema_file}"      # Replaced with schema file path
+        - "-o"
+        - "{output_file}"      # Replaced with output file path
+      max_turns: 50
+      read_only: true          # Codex runs in read-only sandbox
 
   # Use different backends for specific stages
   stage_backends:
-    # qa: gemini              # Use Gemini for QA stage (when supported)
+    REVIEW: codex              # Use Codex for code review
+    # QA: gemini               # Use Gemini for QA (when supported)
 
 # =============================================================================
 # DOCUMENTATION CONFIGURATION
@@ -569,6 +623,112 @@ stage_context:
     - Secrets must use environment variables
 ```
 
+## AI Backend Customization
+
+Galangal invokes AI backends (like Claude Code CLI) using configurable commands and arguments. This allows you to customize CLI flags without modifying code.
+
+### Default Behavior
+
+By default, Galangal invokes Claude with:
+```bash
+cat prompt.txt | claude --output-format stream-json --verbose --max-turns 200 --permission-mode bypassPermissions
+```
+
+### Customizing CLI Flags
+
+Override any flags in `.galangal/config.yaml`:
+
+```yaml
+ai:
+  backends:
+    claude:
+      command: claude
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--verbose"
+        - "--max-turns"
+        - "{max_turns}"
+        - "--permission-mode"
+        - "bypassPermissions"
+        - "--model"              # Add custom flags
+        - "opus"
+      max_turns: 300             # Increase max turns
+```
+
+### Placeholder Reference
+
+Arguments can include placeholders that are substituted at runtime:
+
+| Placeholder | Backend | Description |
+|-------------|---------|-------------|
+| `{max_turns}` | claude | Maximum conversation turns |
+| `{schema_file}` | codex | Path to JSON schema file |
+| `{output_file}` | codex | Path for structured output |
+
+### Common Customizations
+
+**Use a specific model:**
+```yaml
+ai:
+  backends:
+    claude:
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--model"
+        - "sonnet"           # Use Sonnet instead of default
+        - "--max-turns"
+        - "{max_turns}"
+```
+
+**Increase turn limit for complex tasks:**
+```yaml
+ai:
+  backends:
+    claude:
+      max_turns: 500         # Default is 200
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--max-turns"
+        - "{max_turns}"      # Will use 500
+```
+
+**Use different backends per stage:**
+```yaml
+ai:
+  default: claude
+  stage_backends:
+    REVIEW: codex            # Use Codex for code review
+```
+
+### Adding a Custom Backend
+
+Define any CLI tool as a backend:
+
+```yaml
+ai:
+  backends:
+    my-backend:
+      command: my-ai-tool
+      args:
+        - "--prompt-file"
+        - "-"                # Read from stdin
+        - "--json-output"
+      max_turns: 100
+      read_only: true        # Cannot write files directly
+```
+
+Then use it:
+```yaml
+ai:
+  default: my-backend
+  # Or per-stage:
+  stage_backends:
+    QA: my-backend
+```
+
 ## Customizing Prompts
 
 Galangal uses a layered prompt system:
@@ -712,6 +872,8 @@ If the TEST stage keeps retrying instead of rolling back to DEV:
 2. If tests fail due to implementation bugs, the AI should report FAIL (not try to fix the code)
 3. Check that test commands exit with proper exit codes (0 for success, non-zero for failure)
 
+**Note:** As of v0.12.0, when artifact markers are unclear (missing PASS/FAIL), Galangal prompts you to manually approve or reject instead of retrying indefinitely. You'll see the artifact content and can make the decision yourself.
+
 ### "Galangal has not been initialized" Error
 
 Run `galangal init` in your project root before using other commands.

{galangal_orchestrate-0.6.3 → galangal_orchestrate-0.12.15}/README.md

@@ -61,7 +61,7 @@ galangal status
 | **PREFLIGHT** | Environment validation | PREFLIGHT_REPORT.md |
 | **DEV** | Implementation | Code changes |
 | **MIGRATION*** | Database migration checks | MIGRATION_REPORT.md |
-| **TEST** | Test implementation | TEST_PLAN.md |
+| **TEST** | Test implementation | TEST_PLAN.md, TEST_SUMMARY.md |
 | **CONTRACT*** | API contract validation | CONTRACT_REPORT.md |
 | **QA** | Quality assurance | QA_REPORT.md |
 | **BENCHMARK*** | Performance validation | BENCHMARK_REPORT.md |
@@ -71,6 +71,15 @@ galangal status
 
 *Conditional stages - skipped automatically if not relevant
 
+### Validation Artifacts
+
+When validation commands run (tests, linters, etc.), Galangal creates debugging artifacts:
+
+- **VALIDATION_REPORT.md** - Full output from all validation commands, useful for debugging failures
+- **TEST_SUMMARY.md** - Concise test results (pass/fail counts, failed test names, coverage) included in downstream stage prompts
+
+These artifacts help you understand what failed without digging through logs, and give downstream stages (QA, REVIEW) context about test results without bloating prompts with verbose output.
+
 ## Task Types
 
 Choose the right workflow for your task:
@@ -78,9 +87,9 @@ Choose the right workflow for your task:
 | Type | Stages | When to Use |
 |------|--------|-------------|
 | **Feature** | All stages | New functionality |
-| **Bug Fix** | PM → DEV → TEST → QA | Fixing bugs |
-| **Refactor** | PM → DESIGN → DEV → TEST | Code restructuring |
-| **Chore** | PM → DEV → TEST | Config, dependencies |
+| **Bug Fix** | PM → PREFLIGHT → DEV → TEST → QA | Fixing bugs |
+| **Refactor** | PM → DESIGN → PREFLIGHT → DEV → TEST | Code restructuring |
+| **Chore** | PM → PREFLIGHT → DEV → TEST | Config, dependencies |
 | **Docs** | PM → DOCS | Documentation only |
 | **Hotfix** | PM → DEV → TEST | Critical fixes |
 
@@ -131,6 +140,32 @@ After analyzing your task, the PM stage outputs a `STAGE_PLAN.md` recommending w
 
 The progress bar updates dynamically to show only relevant stages.
 
+### Workflow Preview
+
+After PM approval, you'll see a preview showing exactly which stages will run and why others are skipped:
+
+```
+Workflow Preview
+
+Stages to run:
+  PM → DESIGN → PREFLIGHT → DEV → TEST → QA → REVIEW → DOCS
+
+Skipping:
+  MIGRATION (no files match: **/migrations/*)
+  CONTRACT (no files match: **/api/*, **/openapi.*)
+  BENCHMARK (task type: bug_fix)
+  SECURITY (PM: simple UI change, no security impact)
+
+Controls during execution:
+  ^N Skip stage  ^B Back  ^E Pause for edit  ^I Interrupt
+```
+
+Skip reasons include:
+- **Task type** - Based on the workflow template (e.g., bug fixes skip DESIGN)
+- **Config** - Stages listed in `stages.skip` configuration
+- **PM recommendation** - From STAGE_PLAN.md analysis
+- **skip_if condition** - No changed files match the glob pattern
+
 ## Commands
 
 | Command | Description |
@@ -367,6 +402,9 @@ validation:
       - name: "Integration tests"
         command: "pytest tests/integration"
         optional: true         # Don't fail if integration tests missing
+      # Use array form for paths with spaces or special characters
+      - name: "Task-specific tests"
+        command: ["pytest", "{task_dir}/tests"]  # {task_dir} is substituted
 
   # Contract stage (API compatibility)
   contract:
@@ -422,21 +460,37 @@ ai:
   # Default backend to use
   default: claude
 
-  # Available backends
+  # Available backends with customizable CLI flags
   backends:
     claude:
-      command: claude
-      args:
-        - "-p"
-        - "{prompt}"
+      command: claude          # CLI command to invoke
+      args:                    # Arguments with {placeholder} substitution
         - "--output-format"
         - "stream-json"
         - "--verbose"
+        - "--max-turns"
+        - "{max_turns}"        # Replaced with max_turns value
+        - "--permission-mode"
+        - "bypassPermissions"
       max_turns: 200           # Maximum conversation turns per stage
+      read_only: false         # If true, backend cannot write files
+
+    codex:
+      command: codex
+      args:
+        - "exec"
+        - "--full-auto"
+        - "--output-schema"
+        - "{schema_file}"      # Replaced with schema file path
+        - "-o"
+        - "{output_file}"      # Replaced with output file path
+      max_turns: 50
+      read_only: true          # Codex runs in read-only sandbox
 
   # Use different backends for specific stages
   stage_backends:
-    # qa: gemini              # Use Gemini for QA stage (when supported)
+    REVIEW: codex              # Use Codex for code review
+    # QA: gemini               # Use Gemini for QA (when supported)
 
 # =============================================================================
 # DOCUMENTATION CONFIGURATION
@@ -533,6 +587,112 @@ stage_context:
     - Secrets must use environment variables
 ```
 
+## AI Backend Customization
+
+Galangal invokes AI backends (like Claude Code CLI) using configurable commands and arguments. This allows you to customize CLI flags without modifying code.
+
+### Default Behavior
+
+By default, Galangal invokes Claude with:
+```bash
+cat prompt.txt | claude --output-format stream-json --verbose --max-turns 200 --permission-mode bypassPermissions
+```
+
+### Customizing CLI Flags
+
+Override any flags in `.galangal/config.yaml`:
+
+```yaml
+ai:
+  backends:
+    claude:
+      command: claude
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--verbose"
+        - "--max-turns"
+        - "{max_turns}"
+        - "--permission-mode"
+        - "bypassPermissions"
+        - "--model"              # Add custom flags
+        - "opus"
+      max_turns: 300             # Increase max turns
+```
+
+### Placeholder Reference
+
+Arguments can include placeholders that are substituted at runtime:
+
+| Placeholder | Backend | Description |
+|-------------|---------|-------------|
+| `{max_turns}` | claude | Maximum conversation turns |
+| `{schema_file}` | codex | Path to JSON schema file |
+| `{output_file}` | codex | Path for structured output |
+
+### Common Customizations
+
+**Use a specific model:**
+```yaml
+ai:
+  backends:
+    claude:
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--model"
+        - "sonnet"           # Use Sonnet instead of default
+        - "--max-turns"
+        - "{max_turns}"
+```
+
+**Increase turn limit for complex tasks:**
+```yaml
+ai:
+  backends:
+    claude:
+      max_turns: 500         # Default is 200
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--max-turns"
+        - "{max_turns}"      # Will use 500
+```
+
+**Use different backends per stage:**
+```yaml
+ai:
+  default: claude
+  stage_backends:
+    REVIEW: codex            # Use Codex for code review
+```
+
+### Adding a Custom Backend
+
+Define any CLI tool as a backend:
+
+```yaml
+ai:
+  backends:
+    my-backend:
+      command: my-ai-tool
+      args:
+        - "--prompt-file"
+        - "-"                # Read from stdin
+        - "--json-output"
+      max_turns: 100
+      read_only: true        # Cannot write files directly
+```
+
+Then use it:
+```yaml
+ai:
+  default: my-backend
+  # Or per-stage:
+  stage_backends:
+    QA: my-backend
+```
+
 ## Customizing Prompts
 
 Galangal uses a layered prompt system:
@@ -676,6 +836,8 @@ If the TEST stage keeps retrying instead of rolling back to DEV:
 2. If tests fail due to implementation bugs, the AI should report FAIL (not try to fix the code)
 3. Check that test commands exit with proper exit codes (0 for success, non-zero for failure)
 
+**Note:** As of v0.12.0, when artifact markers are unclear (missing PASS/FAIL), Galangal prompts you to manually approve or reject instead of retrying indefinitely. You'll see the artifact content and can make the decision yourself.
+
 ### "Galangal has not been initialized" Error
 
 Run `galangal init` in your project root before using other commands.

{galangal_orchestrate-0.6.3 → galangal_orchestrate-0.12.15}/docs/local-development/workflow-pipeline.md

@@ -91,7 +91,7 @@ cat '<prompt_file>' | claude \
   --output-format stream-json \
   --verbose \
   --max-turns 200 \
-  --permission-mode acceptEdits
+  --permission-mode bypassPermissions
 ```
 
 The backend:

{galangal_orchestrate-0.6.3 → galangal_orchestrate-0.12.15}/src/galangal/__init__.py

@@ -19,7 +19,7 @@ from galangal.logging import (
     workflow_logger,
 )
 
-__version__ = "0.6.3"
+__version__ = "0.12.15"
 
 __all__ = [
     # Exceptions

galangal_orchestrate-0.12.15/src/galangal/ai/__init__.py

@@ -0,0 +1,167 @@
+"""AI backend abstractions and factory functions."""
+
+from __future__ import annotations
+
+import shutil
+from typing import TYPE_CHECKING
+
+from galangal.ai.base import AIBackend
+from galangal.ai.claude import ClaudeBackend
+from galangal.ai.codex import CodexBackend
+
+if TYPE_CHECKING:
+    from galangal.config.schema import AIBackendConfig, GalangalConfig
+    from galangal.core.state import Stage
+
+# Registry of available backends
+BACKEND_REGISTRY: dict[str, type[AIBackend]] = {
+    "claude": ClaudeBackend,
+    "codex": CodexBackend,
+}
+
+# Default fallback chain: backend -> fallback
+DEFAULT_FALLBACKS: dict[str, str] = {
+    "codex": "claude",
+    "gemini": "claude",
+}
+
+
+def get_backend(
+    name: str,
+    config: GalangalConfig | None = None,
+) -> AIBackend:
+    """
+    Factory function to instantiate backends by name.
+
+    Args:
+        name: Backend name (e.g., "claude", "codex")
+        config: Optional project config to get backend-specific settings
+
+    Returns:
+        Instantiated backend with configuration
+
+    Raises:
+        ValueError: If backend name is unknown
+    """
+    backend_class = BACKEND_REGISTRY.get(name.lower())
+    if not backend_class:
+        available = list(BACKEND_REGISTRY.keys())
+        raise ValueError(f"Unknown backend: {name}. Available: {available}")
+
+    # Get backend-specific config if available
+    backend_config: AIBackendConfig | None = None
+    if config:
+        backend_config = config.ai.backends.get(name.lower())
+
+    return backend_class(backend_config)
+
+
+def is_backend_available(
+    name: str,
+    config: GalangalConfig | None = None,
+) -> bool:
+    """
+    Check if a backend's CLI tool is available on the system.
+
+    Args:
+        name: Backend name (e.g., "claude", "codex")
+        config: Optional project config to get custom command names
+
+    Returns:
+        True if the backend's CLI is installed and accessible
+    """
+    # Check config for custom command name
+    cmd: str | None
+    if config and name.lower() in config.ai.backends:
+        cmd = config.ai.backends[name.lower()].command
+    else:
+        # Fallback to default command names
+        cli_commands = {
+            "claude": "claude",
+            "codex": "codex",
+            "gemini": "gemini",  # Future
+        }
+        cmd = cli_commands.get(name.lower())
+
+    if not cmd:
+        return False
+    return shutil.which(cmd) is not None
+
+
+def get_backend_with_fallback(
+    name: str,
+    fallbacks: dict[str, str] | None = None,
+    config: GalangalConfig | None = None,
+) -> AIBackend:
+    """
+    Get a backend, falling back to alternatives if unavailable.
+
+    Args:
+        name: Primary backend name
+        fallbacks: Optional custom fallback mapping. Defaults to DEFAULT_FALLBACKS.
+        config: Optional project config for backend settings
+
+    Returns:
+        The requested backend if available, otherwise the fallback backend
+
+    Raises:
+        ValueError: If neither primary nor fallback backends are available
+    """
+    fallbacks = fallbacks or DEFAULT_FALLBACKS
+
+    if is_backend_available(name, config):
+        return get_backend(name, config)
+
+    # Try fallback
+    fallback_name = fallbacks.get(name.lower())
+    if fallback_name and is_backend_available(fallback_name, config):
+        return get_backend(fallback_name, config)
+
+    # Last resort: try claude if it exists
+    if name.lower() != "claude" and is_backend_available("claude", config):
+        return get_backend("claude", config)
+
+    raise ValueError(f"Backend '{name}' not available and no fallback found")
+
+
+def get_backend_for_stage(
+    stage: Stage,
+    config: GalangalConfig,
+    use_fallback: bool = True,
+) -> AIBackend:
+    """
+    Get the appropriate backend for a specific stage.
+
+    Checks config.ai.stage_backends for stage-specific overrides,
+    otherwise uses config.ai.default.
+
+    Args:
+        stage: The workflow stage
+        config: Project configuration
+        use_fallback: If True, fall back to alternative backends if primary unavailable
+
+    Returns:
+        The configured backend for the stage
+    """
+    # Check for stage-specific backend override
+    stage_key = stage.value.upper()
+    if stage_key in config.ai.stage_backends:
+        backend_name = config.ai.stage_backends[stage_key]
+    else:
+        backend_name = config.ai.default
+
+    if use_fallback:
+        return get_backend_with_fallback(backend_name, config=config)
+    return get_backend(backend_name, config)
+
+
+__all__ = [
+    "AIBackend",
+    "ClaudeBackend",
+    "CodexBackend",
+    "BACKEND_REGISTRY",
+    "get_backend",
+    "get_backend_for_stage",
+    "get_backend_with_fallback",
+    "is_backend_available",
+]