galangal-orchestrate 0.13.0__py3-none-any.whl

galangal_orchestrate-0.13.0.dist-info/METADATA

@@ -0,0 +1,985 @@
+Metadata-Version: 2.4
+Name: galangal-orchestrate
+Version: 0.13.0
+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
+Project-URL: Issues, https://github.com/Galangal-Media/galangal-orchestrate/issues
+Author: Galangal Media
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,development,orchestrator,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: structlog>=24.0.0
+Requires-Dist: textual>=0.40.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Galangal Orchestrate
+
+**Turn AI coding assistants into structured development workflows.**
+
+Galangal Orchestrate wraps [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI to execute a deterministic, multi-stage development pipeline. Instead of open-ended AI coding sessions, you get a structured workflow with approval gates, validation, and automatic rollback.
+
+## Why Use This?
+
+When you ask an AI to "add user authentication", you get whatever the AI decides to build. With Galangal:
+
+1. **PM Stage** - AI writes requirements, you approve before any code is written
+2. **Design Stage** - AI proposes architecture, you approve the approach
+3. **Dev Stage** - AI implements according to approved specs
+4. **Test Stage** - AI writes tests, validation ensures they pass
+5. **QA Stage** - AI verifies requirements are met
+6. **Review Stage** - AI reviews its own code for issues
+7. **Docs Stage** - AI updates documentation
+
+If anything fails, the workflow automatically rolls back to the appropriate fix point with context about what went wrong.
+
+## Requirements
+
+- Python 3.10+
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed (`claude` command available)
+- Claude Pro or Max subscription
+- Git
+
+## Installation
+
+```bash
+# With pip
+pip install galangal-orchestrate
+
+# With pipx (recommended for CLI tools)
+pipx install galangal-orchestrate
+```
+
+## Quick Start
+
+```bash
+# Initialize in your project
+cd your-project
+galangal init
+
+# Start a task
+galangal start "Add user authentication with JWT tokens"
+
+# Resume after a break
+galangal resume
+
+# Check current status
+galangal status
+```
+
+## Workflow Stages
+
+| Stage | Purpose | Output |
+|-------|---------|--------|
+| **PM** | Requirements & planning | SPEC.md, PLAN.md, STAGE_PLAN.md |
+| **DESIGN** | Architecture design | DESIGN.md |
+| **PREFLIGHT** | Environment validation | PREFLIGHT_REPORT.md |
+| **DEV** | Implementation | Code changes |
+| **MIGRATION*** | Database migration checks | MIGRATION_REPORT.md |
+| **TEST** | Test implementation | TEST_PLAN.md, TEST_SUMMARY.md |
+| **TEST_GATE*** | Verify configured test suites pass | TEST_GATE_RESULTS.md |
+| **CONTRACT*** | API contract validation | CONTRACT_REPORT.md |
+| **QA** | Quality assurance | QA_REPORT.md |
+| **BENCHMARK*** | Performance validation | BENCHMARK_REPORT.md |
+| **SECURITY** | Security review | SECURITY_CHECKLIST.md |
+| **REVIEW** | Code review | REVIEW_NOTES.md |
+| **DOCS** | Documentation | DOCS_REPORT.md |
+
+*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.
+
+### Test Gate
+
+The **TEST_GATE** stage is an optional quality gate that runs configured test suites mechanically (no AI). It runs after the TEST stage and before QA. All configured tests must pass for the workflow to proceed.
+
+**Why use Test Gate?**
+- Ensures specific test suites always pass before QA
+- Separates "writing tests" (TEST stage) from "verifying tests pass" (TEST_GATE)
+- QA can skip running automated tests and focus on exploratory testing
+- Provides a clear, repeatable verification step
+
+**Configuration:**
+
+```yaml
+# .galangal/config.yaml
+test_gate:
+  enabled: true
+  fail_fast: true  # Stop on first failure (default: true)
+  tests:
+    - name: "unit tests"
+      command: "npm test"
+      timeout: 300  # Optional, defaults to 5 minutes
+    - name: "integration tests"
+      command: "pytest tests/integration -v"
+    - name: "e2e tests"
+      command: "cd frontend && npm run e2e"
+      timeout: 600  # 10 minutes for slower tests
+```
+
+**Behavior:**
+- Runs each test command in sequence
+- Creates `TEST_GATE_RESULTS.md` with detailed output
+- On success: proceeds to CONTRACT/QA stages
+- On failure: rolls back to DEV with context about which tests failed
+- QA prompt is automatically updated to skip re-running these tests
+
+**Skip conditions:**
+- `test_gate.enabled: false` (default)
+- No tests configured in `test_gate.tests`
+- DOCS task type (no code changes)
+- Manual skip artifact (`TEST_GATE_SKIP.md`)
+
+## Task Types
+
+Choose the right workflow for your task:
+
+| Type | Stages | When to Use |
+|------|--------|-------------|
+| **Feature** | All stages | New functionality |
+| **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 |
+
+The PM stage can further customize which stages run based on task analysis.
+
+## Interactive Controls
+
+During workflow execution:
+
+| Key | Action | Description |
+|-----|--------|-------------|
+| `^Q` | Quit | Pause and exit (resume later with `galangal resume`) |
+| `^I` | Interrupt | Stop current stage, give feedback, rollback to DEV |
+| `^N` | Skip | Skip current stage, advance to next |
+| `^B` | Back | Go back to previous stage |
+| `^E` | Edit | Pause for manual editing, press Enter to resume |
+
+### Interrupt with Feedback (^I)
+
+When you see the AI doing something wrong mid-stage:
+1. Press `^I` to interrupt immediately
+2. Enter feedback describing what needs to be fixed
+3. Workflow rolls back to DEV with your feedback as context
+4. A `ROLLBACK.md` artifact is created for the AI to reference
+
+### Manual Edit Pause (^E)
+
+Need to make a quick fix yourself?
+1. Press `^E` to pause
+2. Make edits in your editor
+3. Press Enter to resume the current stage
+
+## PM-driven Stage Planning
+
+After analyzing your task, the PM stage outputs a `STAGE_PLAN.md` recommending which optional stages to run or skip:
+
+```markdown
+# Stage Plan
+
+## Recommendations
+| Stage | Action | Reason |
+|-------|--------|--------|
+| MIGRATION | skip | No database changes detected |
+| CONTRACT | skip | Internal refactor, no API changes |
+| SECURITY | run | Handling user authentication input |
+| BENCHMARK | skip | UI-only changes, no performance impact |
+```
+
+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 |
+|---------|-------------|
+| `galangal init` | Initialize in current project |
+| `galangal start "desc"` | Start new task |
+| `galangal list` | List all tasks |
+| `galangal switch <name>` | Switch active task |
+| `galangal status` | Show task status |
+| `galangal resume` | Continue active task |
+| `galangal pause` | Pause for break |
+| `galangal approve` | Approve plan |
+| `galangal approve-design` | Approve design |
+| `galangal skip-design` | Skip design stage |
+| `galangal skip-to <stage>` | Jump to stage |
+| `galangal complete` | Finalize & create PR |
+| `galangal reset` | Delete active task |
+| `galangal github setup` | Set up GitHub integration |
+| `galangal github issues` | List galangal-labeled issues |
+| `galangal github run` | Process issues automatically |
+
+## GitHub Integration
+
+Galangal can create tasks directly from GitHub issues, automatically downloading screenshots and inferring task types from labels.
+
+### Quick Setup
+
+```bash
+# 1. Install GitHub CLI (if not already installed)
+# macOS:
+brew install gh
+
+# Windows:
+winget install GitHub.cli
+
+# Linux: See https://cli.github.com
+
+# 2. Authenticate
+gh auth login
+
+# 3. Set up GitHub integration (creates labels)
+galangal github setup
+```
+
+### How It Works
+
+1. Add the `galangal` label to any GitHub issue you want to work on
+2. Run `galangal start` and select "GitHub issue" as the task source
+3. Galangal will:
+   - Download any screenshots from the issue body
+   - Infer the task type from issue labels
+   - Create a task linked to the issue
+   - Mark the issue as "in-progress"
+
+When you complete the task with `galangal complete`, a PR is created that automatically closes the linked issue.
+
+### Batch Processing
+
+Process all galangal-labeled issues automatically:
+
+```bash
+# List issues that would be processed
+galangal github run --dry-run
+
+# Process all issues headlessly
+galangal github run
+```
+
+### Issue Screenshots
+
+Screenshots embedded in GitHub issues (using `![](url)` syntax) are automatically:
+- Downloaded to `galangal-tasks/<task>/screenshots/`
+- Passed to the AI during PM, Design, and Dev stages
+- Available for the AI to view using Claude's Read tool
+
+This is especially useful for bug reports with screenshots or design mockups.
+
+### Label Configuration
+
+Galangal maps GitHub labels to task types. The defaults are:
+
+| Task Type | Labels |
+|-----------|--------|
+| bug_fix | `bug`, `bugfix` |
+| feature | `enhancement`, `feature` |
+| docs | `documentation`, `docs` |
+| refactor | `refactor` |
+| chore | `chore`, `maintenance` |
+| hotfix | `hotfix`, `critical` |
+
+Customize in `.galangal/config.yaml`:
+
+```yaml
+github:
+  # Label that triggers galangal to pick up issues
+  pickup_label: galangal
+
+  # Label added when work starts
+  in_progress_label: in-progress
+
+  # Custom label colors (hex without #)
+  label_colors:
+    galangal: "7C3AED"
+    in-progress: "FCD34D"
+
+  # Map your labels to task types
+  label_mapping:
+    bug:
+      - bug
+      - bugfix
+      - defect           # Add your custom labels
+    feature:
+      - enhancement
+      - feature
+      - new-feature
+    docs:
+      - documentation
+      - docs
+    refactor:
+      - refactor
+      - tech-debt
+    chore:
+      - chore
+      - maintenance
+      - dependencies
+    hotfix:
+      - hotfix
+      - critical
+      - urgent
+```
+
+### GitHub Commands
+
+| Command | Description |
+|---------|-------------|
+| `galangal github setup` | Create required labels, show setup instructions |
+| `galangal github setup --help-install` | Show detailed gh CLI installation instructions |
+| `galangal github check` | Verify gh CLI installation and authentication |
+| `galangal github issues` | List issues with galangal label |
+| `galangal github issues --label <name>` | List issues with custom label |
+| `galangal github run` | Process all labeled issues headlessly |
+| `galangal github run --dry-run` | Preview without processing |
+
+## Configuration
+
+After `galangal init`, customize `.galangal/config.yaml`. Here's a complete reference:
+
+```yaml
+# =============================================================================
+# PROJECT CONFIGURATION
+# =============================================================================
+project:
+  # Project name (displayed in logs and prompts)
+  name: "My Project"
+
+  # Default approver name for plan/design approvals (auto-fills signoff prompts)
+  approver_name: "Jane Smith"
+
+  # Technology stacks in your project
+  # Helps AI understand your codebase structure
+  stacks:
+    - language: python
+      framework: fastapi       # Optional: framework name
+      root: backend/           # Optional: subdirectory for this stack
+    - language: typescript
+      framework: vite
+      root: frontend/
+
+# =============================================================================
+# TASK STORAGE
+# =============================================================================
+# Directory where task state and artifacts are stored
+tasks_dir: galangal-tasks
+
+# Git branch naming pattern ({task_name} is replaced with sanitized task name)
+branch_pattern: "task/{task_name}"
+
+# =============================================================================
+# STAGE CONFIGURATION
+# =============================================================================
+stages:
+  # Stages to always skip (regardless of task type or PM recommendations)
+  skip:
+    - BENCHMARK
+    - CONTRACT
+
+  # Default timeout for each stage in seconds (4 hours default)
+  timeout: 14400
+
+  # Maximum retries per stage before rollback (default: 5)
+  max_retries: 5
+
+# =============================================================================
+# TEST GATE CONFIGURATION
+# Mechanical test verification stage (no AI) - runs after TEST, before QA
+# =============================================================================
+test_gate:
+  # Enable the test gate stage (default: false)
+  enabled: true
+
+  # Stop on first test failure instead of running all tests (default: true)
+  fail_fast: true
+
+  # Test suites to run - all must pass for the stage to succeed
+  tests:
+    - name: "unit tests"
+      command: "npm test"
+      timeout: 300           # Timeout in seconds (default: 300)
+    - name: "integration tests"
+      command: "pytest tests/integration -v"
+    - name: "e2e tests"
+      command: "cd frontend && npm run e2e"
+      timeout: 600           # Longer timeout for e2e tests
+
+# =============================================================================
+# VALIDATION CONFIGURATION
+# Each stage can have validation commands, checks, and skip conditions
+# =============================================================================
+validation:
+  # Preflight checks run before DEV stage
+  preflight:
+    timeout: 300  # Timeout for each check in seconds
+    checks:
+      - name: "Git status clean"
+        command: "git status --porcelain"
+        expect_empty: true      # Pass if output is empty
+        warn_only: false        # If true, warn but don't fail
+      - name: "Node modules exist"
+        path_exists: "node_modules"  # Check if path exists
+      - name: "Dependencies installed"
+        command: "npm ls --depth=0"
+        warn_only: true
+
+  # Migration stage validation
+  migration:
+    # Skip if no migration files changed
+    skip_if:
+      no_files_match:
+        - "migrations/**"
+        - "**/migrations/**"
+        - "alembic/**"
+    timeout: 600
+    commands:
+      - name: "Run migrations"
+        command: "python manage.py migrate --check"
+        timeout: 300           # Override timeout for this command
+        optional: false        # If true, don't fail if command fails
+        allow_failure: false   # If true, report but don't block
+
+  # Test stage validation
+  test:
+    timeout: 600
+    commands:
+      - name: "Unit tests"
+        command: "pytest tests/unit"
+      - 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:
+    skip_if:
+      no_files_match: "openapi.yaml"
+    timeout: 300
+    commands:
+      - name: "Validate OpenAPI spec"
+        command: "openapi-spec-validator openapi.yaml"
+
+  # QA stage validation
+  qa:
+    timeout: 3600
+    commands:
+      - name: "Lint"
+        command: "./scripts/lint.sh"
+        timeout: 600
+      - name: "Type check"
+        command: "mypy src/"
+        timeout: 600
+    # Marker-based validation (for AI output verification)
+    artifact: "QA_REPORT.md"
+    pass_marker: "## PASS"
+    fail_marker: "## FAIL"
+
+  # Security stage validation
+  security:
+    timeout: 1800
+    commands:
+      - name: "Security scan"
+        command: "bandit -r src/"
+        allow_failure: true    # Report issues but don't block
+    artifacts_required:
+      - "SECURITY_CHECKLIST.md"
+
+  # Review stage validation
+  review:
+    timeout: 1800
+    artifact: "REVIEW_NOTES.md"
+    pass_marker: "APPROVED"
+    fail_marker: "REJECTED"
+
+  # Docs stage validation
+  docs:
+    timeout: 900
+    artifacts_required:
+      - "DOCS_REPORT.md"
+
+# =============================================================================
+# AI BACKEND CONFIGURATION
+# =============================================================================
+ai:
+  # Default backend to use
+  default: claude
+
+  # Available backends with customizable CLI flags
+  backends:
+    claude:
+      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:
+    REVIEW: codex              # Use Codex for code review
+    # QA: gemini               # Use Gemini for QA (when supported)
+
+# =============================================================================
+# DOCUMENTATION CONFIGURATION
+# =============================================================================
+docs:
+  # Directory for changelog entries
+  changelog_dir: docs/changelog
+
+  # Directory for security audit reports
+  security_audit: docs/security
+
+  # Directory for general documentation
+  general: docs
+
+  # Toggle documentation updates
+  update_changelog: true       # Update changelog in DOCS stage
+  update_security_audit: true  # Create security reports in SECURITY stage
+  update_general_docs: true    # Update general docs in DOCS stage
+
+# =============================================================================
+# PULL REQUEST CONFIGURATION
+# =============================================================================
+pr:
+  # Base branch for PRs (e.g., main, develop)
+  base_branch: main
+
+  # Add @codex review to PR body for automated review
+  codex_review: false
+
+# =============================================================================
+# STRUCTURED LOGGING
+# =============================================================================
+logging:
+  # Enable structured logging to file
+  enabled: true
+
+  # Log level: debug, info, warning, error
+  level: info
+
+  # Log file path (JSON Lines format for easy parsing)
+  file: logs/galangal.jsonl
+
+  # Output format: true for JSON, false for pretty console format
+  json_format: true
+
+  # Also output to console (stderr)
+  console: false
+
+# =============================================================================
+# TASK TYPE SETTINGS
+# Per-task-type overrides
+# =============================================================================
+task_type_settings:
+  bugfix:
+    skip_discovery: true       # Skip the PM discovery Q&A for bugfixes
+  hotfix:
+    skip_discovery: true
+
+# =============================================================================
+# PROMPT CONTEXT
+# Additional context injected into AI prompts
+# =============================================================================
+
+# Global context added to ALL stage prompts
+prompt_context: |
+  ## Project Conventions
+  - Use repository pattern for data access
+  - API responses use api_success() / api_error() helpers
+  - All errors should be logged with context
+
+  ## Testing Standards
+  - Unit tests go in tests/unit/
+  - Integration tests go in tests/integration/
+  - Use pytest fixtures for test data
+
+# Per-stage context (merged with global context)
+stage_context:
+  dev: |
+    ## Development Environment
+    - Run `npm run dev` for hot reload
+    - Database: PostgreSQL on localhost:5432
+    - Redis: localhost:6379
+
+  test: |
+    ## Test Setup
+    - Use vitest for frontend unit tests
+    - Use pytest for backend tests
+    - Mock external APIs in tests
+
+  security: |
+    ## Security Requirements
+    - All user input must be validated
+    - Use parameterized queries (no raw SQL)
+    - 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:
+
+1. **Base prompts** - Built-in, language-agnostic prompts
+2. **Project prompts** - Your customizations in `.galangal/prompts/`
+
+### Supplement Mode (Recommended)
+
+Add project-specific content that gets prepended to the base prompt:
+
+```markdown
+<!-- .galangal/prompts/dev.md -->
+
+## Project CLI Scripts
+
+- `./scripts/test.sh` - Run all tests
+- `./scripts/lint.sh` - Run linter
+
+## Patterns to Follow
+
+- Always use `api_success()` for responses
+- Never use raw SQL queries
+
+# BASE
+```
+
+The `# BASE` marker inserts the default prompt at that location.
+
+### Override Mode
+
+To completely replace a base prompt, omit the `# BASE` marker:
+
+```markdown
+<!-- .galangal/prompts/preflight.md -->
+
+# Custom Preflight
+
+This completely replaces the default preflight prompt.
+
+[Your custom instructions...]
+```
+
+### Available Prompt Files
+
+Create any of these in `.galangal/prompts/`:
+
+| File | Stage |
+|------|-------|
+| `pm.md` | Requirements & planning |
+| `design.md` | Architecture design |
+| `preflight.md` | Environment checks |
+| `dev.md` | Implementation |
+| `test.md` | Test writing |
+| `qa.md` | Quality assurance |
+| `security.md` | Security review |
+| `review.md` | Code review |
+| `docs.md` | Documentation |
+
+## Troubleshooting
+
+### Debug Mode
+
+When something goes wrong and you need to see what happened:
+
+```bash
+# Enable debug logging (writes to logs/galangal_debug.log)
+galangal --debug start "task description"
+galangal --debug resume
+
+# Alternative: set environment variable
+GALANGAL_DEBUG=1 galangal start "task description"
+```
+
+Debug mode creates two log files:
+- `logs/galangal_debug.log` - Human-readable debug trace with timestamps
+- `logs/galangal.jsonl` - Structured JSON logs for programmatic analysis
+
+**Example debug log:**
+```
+[14:32:15.123] GitHub integration failed: HTTPError: 401 Unauthorized
+[14:32:15.124] Traceback:
+  File "/path/to/start.py", line 138, in task_creation_thread
+    check = ensure_github_ready()
+  ...
+```
+
+### Structured Logging Configuration
+
+Enable structured logging in `.galangal/config.yaml`:
+
+```yaml
+logging:
+  enabled: true        # Enable logging
+  level: debug         # debug, info, warning, error
+  file: logs/galangal.jsonl
+  json_format: true    # JSON for parsing, false for console format
+  console: false       # Also output to stderr
+```
+
+### Tests Hang at TEST Stage
+
+Test frameworks must run non-interactively. Common issues:
+
+**Playwright** - HTML reporter blocks by default:
+```bash
+# Use non-blocking reporter
+npx playwright test --reporter=list
+
+# Or set environment variable
+PLAYWRIGHT_HTML_OPEN=never npx playwright test
+
+# Or in playwright.config.ts:
+# reporter: [['html', { open: 'never' }]]
+```
+
+**Jest/Vitest** - Watch mode blocks:
+```bash
+# Wrong (blocks):
+npm test -- --watch
+
+# Correct:
+npm test
+```
+
+**Cypress** - Interactive mode blocks:
+```bash
+# Wrong (blocks):
+cypress open
+
+# Correct:
+cypress run
+```
+
+**General rule**: Use CI-friendly commands that exit automatically. Avoid watch mode, interactive mode, or any GUI that waits for user input.
+
+### TEST Stage Loops Indefinitely
+
+If the TEST stage keeps retrying instead of rolling back to DEV:
+1. Ensure your TEST_PLAN.md has a clear `**Status:** PASS` or `**Status:** FAIL` line
+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.
+
+### Task Exits Without Error Message
+
+If a task quits unexpectedly with no visible error:
+
+1. **Enable debug mode** and re-run:
+   ```bash
+   galangal --debug start "your task"
+   ```
+
+2. **Check the debug log** for the actual error:
+   ```bash
+   tail -50 logs/galangal_debug.log
+   ```
+
+3. **Common causes**:
+   - GitHub authentication failed (run `gh auth status`)
+   - Network timeout fetching issues
+   - Missing permissions for the repository
+   - Invalid issue number or no issues with `galangal` label
+
+### GitHub Integration Fails Silently
+
+If `galangal start` from a GitHub issue exits without creating a task:
+
+```bash
+# Check GitHub CLI is working
+gh auth status
+gh repo view
+
+# Try with debug mode
+galangal --debug start --issue 123
+```
+
+Check `logs/galangal_debug.log` for specific errors like:
+- `401 Unauthorized` - Re-authenticate with `gh auth login`
+- `404 Not Found` - Issue doesn't exist or wrong repo
+- `No issues with 'galangal' label` - Add the label to an issue first
+
+## License
+
+MIT License - see LICENSE file.