galangal-orchestrate 0.2.11__py3-none-any.whl

galangal/prompts/__init__.py

@@ -0,0 +1,5 @@
+"""Prompt building and management."""
+
+from galangal.prompts.builder import PromptBuilder
+
+__all__ = ["PromptBuilder"]

galangal/prompts/builder.py

@@ -0,0 +1,166 @@
+"""
+Prompt building with project override support.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from galangal.config.loader import get_project_root, get_prompts_dir, get_config
+from galangal.core.state import Stage, WorkflowState
+from galangal.core.artifacts import artifact_exists, read_artifact
+
+
+class PromptBuilder:
+    """Build prompts for stages with project overrides."""
+
+    def __init__(self):
+        self.config = get_config()
+        self.project_root = get_project_root()
+        self.override_dir = get_prompts_dir()
+        self.defaults_dir = Path(__file__).parent / "defaults"
+
+    def get_stage_prompt(self, stage: Stage) -> str:
+        """Get the prompt for a stage, with project override/supplement support.
+
+        Project prompts in .galangal/prompts/ can either:
+        - Supplement the base: Include '# BASE' marker where base prompt should be inserted
+        - Override entirely: No marker = full replacement of base prompt
+        """
+        stage_lower = stage.value.lower()
+
+        # Get base prompt
+        default_path = self.defaults_dir / f"{stage_lower}.md"
+        base_prompt = ""
+        if default_path.exists():
+            base_prompt = default_path.read_text()
+
+        # Check for project prompt
+        project_path = self.override_dir / f"{stage_lower}.md"
+        if not project_path.exists():
+            return base_prompt or f"Execute the {stage.value} stage for the task."
+
+        project_prompt = project_path.read_text()
+
+        # Check for # BASE marker (supplement mode)
+        if "# BASE" in project_prompt:
+            # Split at marker and insert base prompt
+            parts = project_prompt.split("# BASE", 1)
+            header = parts[0].rstrip()
+            footer = parts[1].lstrip() if len(parts) > 1 else ""
+
+            result_parts = []
+            if header:
+                result_parts.append(header)
+            if base_prompt:
+                result_parts.append(base_prompt)
+            if footer:
+                result_parts.append(footer)
+
+            return "\n\n".join(result_parts)
+
+        # No marker = full override
+        return project_prompt
+
+    def build_full_prompt(self, stage: Stage, state: WorkflowState) -> str:
+        """Build the complete prompt for a stage execution."""
+        base_prompt = self.get_stage_prompt(stage)
+        task_name = state.task_name
+
+        # Build context
+        context_parts = [
+            f"# Task: {task_name}",
+            f"# Task Type: {state.task_type.display_name()}",
+            f"# Description\n{state.task_description}",
+            f"\n# Current Stage: {stage.value}",
+            f"\n# Attempt: {state.attempt}",
+            f"\n# Artifacts Directory: {self.config.tasks_dir}/{task_name}/",
+        ]
+
+        # Add failure context
+        if state.last_failure:
+            context_parts.append(f"\n# Previous Failure\n{state.last_failure}")
+
+        # Add relevant artifacts based on stage
+        context_parts.extend(self._get_artifact_context(stage, task_name))
+
+        # Add global prompt context from config
+        if self.config.prompt_context:
+            context_parts.append(f"\n# Project Context\n{self.config.prompt_context}")
+
+        # Add stage-specific context from config
+        stage_context = self.config.stage_context.get(stage.value, "")
+        if stage_context:
+            context_parts.append(f"\n# Stage Context\n{stage_context}")
+
+        context = "\n".join(context_parts)
+        return f"{context}\n\n---\n\n{base_prompt}"
+
+    def _get_artifact_context(self, stage: Stage, task_name: str) -> list[str]:
+        """Get relevant artifact content for the stage."""
+        parts = []
+
+        # SPEC and PLAN for all stages after PM
+        if stage != Stage.PM:
+            if artifact_exists("SPEC.md", task_name):
+                parts.append(f"\n# SPEC.md\n{read_artifact('SPEC.md', task_name)}")
+            if artifact_exists("PLAN.md", task_name):
+                parts.append(f"\n# PLAN.md\n{read_artifact('PLAN.md', task_name)}")
+
+        # DESIGN for stages after DESIGN
+        if stage not in [Stage.PM, Stage.DESIGN]:
+            if artifact_exists("DESIGN.md", task_name):
+                parts.append(f"\n# DESIGN.md\n{read_artifact('DESIGN.md', task_name)}")
+            elif artifact_exists("DESIGN_SKIP.md", task_name):
+                parts.append(
+                    f"\n# Note: Design stage was skipped\n{read_artifact('DESIGN_SKIP.md', task_name)}"
+                )
+
+        # ROLLBACK for DEV and TEST (issues to fix)
+        if stage in [Stage.DEV, Stage.TEST]:
+            if artifact_exists("ROLLBACK.md", task_name):
+                parts.append(
+                    f"\n# ROLLBACK.md (PRIORITY - Fix these issues first!)\n{read_artifact('ROLLBACK.md', task_name)}"
+                )
+            if artifact_exists("QA_REPORT.md", task_name):
+                parts.append(
+                    f"\n# QA_REPORT.md (Previous run)\n{read_artifact('QA_REPORT.md', task_name)}"
+                )
+            if artifact_exists("SECURITY_CHECKLIST.md", task_name):
+                parts.append(
+                    f"\n# SECURITY_CHECKLIST.md (Previous run)\n{read_artifact('SECURITY_CHECKLIST.md', task_name)}"
+                )
+            if artifact_exists("REVIEW_NOTES.md", task_name):
+                parts.append(
+                    f"\n# REVIEW_NOTES.md (Previous run)\n{read_artifact('REVIEW_NOTES.md', task_name)}"
+                )
+
+        # TEST_PLAN for TEST and CONTRACT stages
+        if stage in [Stage.TEST, Stage.CONTRACT]:
+            if artifact_exists("TEST_PLAN.md", task_name):
+                parts.append(
+                    f"\n# TEST_PLAN.md\n{read_artifact('TEST_PLAN.md', task_name)}"
+                )
+
+        # Reports for later stages
+        if stage in [Stage.QA, Stage.BENCHMARK, Stage.SECURITY, Stage.REVIEW]:
+            if artifact_exists("MIGRATION_REPORT.md", task_name):
+                parts.append(
+                    f"\n# MIGRATION_REPORT.md\n{read_artifact('MIGRATION_REPORT.md', task_name)}"
+                )
+            if artifact_exists("CONTRACT_REPORT.md", task_name):
+                parts.append(
+                    f"\n# CONTRACT_REPORT.md\n{read_artifact('CONTRACT_REPORT.md', task_name)}"
+                )
+
+        # For REVIEW, include QA and Security reports
+        if stage == Stage.REVIEW:
+            if artifact_exists("QA_REPORT.md", task_name):
+                parts.append(
+                    f"\n# QA_REPORT.md\n{read_artifact('QA_REPORT.md', task_name)}"
+                )
+            if artifact_exists("SECURITY_CHECKLIST.md", task_name):
+                parts.append(
+                    f"\n# SECURITY_CHECKLIST.md\n{read_artifact('SECURITY_CHECKLIST.md', task_name)}"
+                )
+
+        return parts

galangal/prompts/defaults/design.md

@@ -0,0 +1,54 @@
+# DESIGN Stage - Architecture Design
+
+You are a Software Architect designing the implementation for a feature. Create a detailed technical design document.
+
+## Your Output
+
+Create DESIGN.md in the task's artifacts directory with these sections:
+
+```markdown
+# Technical Design: [Task Title]
+
+## Architecture Overview
+[High-level description of the approach]
+[How this fits into the existing system]
+
+## Data Model
+[Any new or modified data structures]
+[Database schema changes if applicable]
+
+## API Impact
+[New or modified endpoints]
+[Request/response formats]
+
+## Sequence Diagram
+[Use mermaid or text-based diagram showing the flow]
+
+## Edge Cases
+- [Edge case 1 and how it's handled]
+- [Edge case 2 and how it's handled]
+
+## Migration Plan
+[How to deploy this without breaking existing functionality]
+[Rollback strategy if needed]
+```
+
+## Process
+
+1. Read SPEC.md and PLAN.md from context
+2. Analyze the codebase to understand:
+   - Current architecture
+   - Integration points
+   - Patterns to follow
+3. Design the solution considering:
+   - Scalability
+   - Maintainability
+   - Backward compatibility
+4. Write DESIGN.md
+
+## Important Rules
+
+- Consider all edge cases
+- Plan for failure scenarios
+- Keep the design focused on the task scope
+- Do NOT implement - only design

galangal/prompts/defaults/dev.md

@@ -0,0 +1,39 @@
+# DEV Stage - Implementation
+
+You are a Developer implementing a feature. Follow the SPEC.md and PLAN.md exactly.
+
+## Your Task
+
+Implement all changes described in PLAN.md while satisfying the acceptance criteria in SPEC.md.
+
+**IMPORTANT: Check for ROLLBACK.md first!** If ROLLBACK.md exists in context, this is a rollback from a later stage (QA, Security, or Review). Fix the issues documented there BEFORE continuing.
+
+## Process
+
+### If ROLLBACK.md exists (Rollback Run):
+1. Read ROLLBACK.md - contains issues that MUST be fixed
+2. Read the relevant report (QA_REPORT.md, SECURITY_CHECKLIST.md, or REVIEW_NOTES.md)
+3. Fix ALL issues documented in ROLLBACK.md
+4. Done - workflow continues to re-run validation
+
+### If ROLLBACK.md does NOT exist (Fresh Run):
+1. Read SPEC.md and PLAN.md from context
+2. If DESIGN.md exists, follow its architecture
+3. Implement each task in order
+4. Done - QA stage will run full verification
+
+## Important Rules
+
+- ONLY implement what's in PLAN.md - nothing more
+- Do NOT fix pre-existing issues unrelated to your task
+- Follow existing patterns in the codebase
+- Keep changes minimal and focused
+- Do NOT write tests - the TEST stage handles that
+
+## If You Get Stuck
+
+If you encounter ambiguity that blocks implementation:
+1. Write your questions to QUESTIONS.md in the task's artifacts directory
+2. Stop and wait for answers
+
+Only do this for blocking ambiguity, not minor decisions.

galangal/prompts/defaults/docs.md

@@ -0,0 +1,46 @@
+# DOCS Stage - Documentation
+
+You are a Technical Writer updating documentation for the implemented feature.
+
+## Your Task
+
+Update project documentation to reflect the changes made.
+
+## Your Output
+
+Create DOCS_REPORT.md in the task's artifacts directory:
+
+```markdown
+# Documentation Report: [Task Title]
+
+## Documentation Updates
+
+### Files Updated
+| File | Change |
+|------|--------|
+| path/to/doc.md | Description of update |
+
+### Changelog Entry
+[Changelog entry content]
+
+## Summary
+[Brief description of documentation changes made]
+```
+
+## Process
+
+1. Review SPEC.md and the implementation
+2. Identify documentation that needs updating:
+   - README updates
+   - API documentation
+   - Changelog entries
+   - User guides (if applicable)
+3. Make the documentation updates
+4. Document what was changed in DOCS_REPORT.md
+
+## Important Rules
+
+- Keep documentation clear and concise
+- Update changelog with user-facing description
+- Don't over-document - focus on what users/developers need
+- Follow existing documentation patterns

galangal/prompts/defaults/pm.md

@@ -0,0 +1,75 @@
+# PM Stage - Requirements Definition
+
+You are a Product Manager analyzing a development task. Create clear specifications and an implementation plan.
+
+## Your Outputs
+
+Create two files in the task's artifacts directory (see "Artifacts Directory" in context above):
+
+### 1. SPEC.md
+
+```markdown
+# Specification: [Task Title]
+
+## Goal
+[What this task accomplishes - 1-2 sentences]
+
+## User Impact
+[Who benefits and how]
+
+## Acceptance Criteria
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+
+## Non-Goals
+- [What this task explicitly does NOT do]
+
+## Risks
+- [Potential issues or concerns]
+```
+
+### 2. PLAN.md
+
+```markdown
+# Implementation Plan
+
+## Summary
+[Brief overview of the approach]
+
+## Tasks
+
+### Changes Required
+- [ ] [Specific task with file paths]
+- [ ] [Specific task with file paths]
+
+### Testing Requirements
+- [ ] [Describe what needs test coverage]
+
+## Files to Modify
+| File | Change |
+|------|--------|
+| path/to/file | Description |
+
+## Dependencies
+[What must be done before other things]
+```
+
+## Process
+
+1. Read the task description provided in context
+2. Search the codebase to understand:
+   - Related existing code
+   - Patterns to follow
+   - Scope of changes needed
+3. Write SPEC.md to the task's artifacts directory
+4. Write PLAN.md to the task's artifacts directory
+
+## Important Rules
+
+- Be specific - include file paths, function names
+- Keep scope focused - don't expand beyond the task
+- Make acceptance criteria testable
+- Follow existing codebase patterns
+- Do NOT start implementing - only plan
+- Do NOT create test files - testing is handled by the TEST stage

galangal/prompts/defaults/qa.md

@@ -0,0 +1,49 @@
+# QA Stage - Quality Assurance
+
+You are a QA Engineer verifying the implementation meets quality standards.
+
+## Your Task
+
+Run comprehensive quality checks and document results.
+
+## Your Output
+
+Create QA_REPORT.md in the task's artifacts directory:
+
+```markdown
+# QA Report: [Task Title]
+
+## Summary
+**Status:** PASS / FAIL
+
+## Test Results
+[Output from test suite]
+
+## Code Quality
+### Linting
+[Linting results]
+
+### Type Checking
+[Type check results]
+
+## Acceptance Criteria Verification
+- [ ] Criterion 1: PASS/FAIL
+- [ ] Criterion 2: PASS/FAIL
+
+## Issues Found
+[List any issues that need to be addressed]
+```
+
+## Process
+
+1. Run the project's test suite
+2. Run linting and type checking
+3. Verify each acceptance criterion from SPEC.md
+4. Document all results in QA_REPORT.md
+
+## Important Rules
+
+- Run ALL tests, not just new ones
+- Be thorough in checking acceptance criteria
+- Document any issues clearly for the DEV stage to fix
+- If tests fail, status should be FAIL

galangal/prompts/defaults/review.md

@@ -0,0 +1,65 @@
+# REVIEW Stage - Code Review
+
+You are a Senior Developer performing a code review.
+
+## Your Task
+
+Review the implementation for code quality, maintainability, and adherence to best practices.
+
+## Your Output
+
+Create REVIEW_NOTES.md in the task's artifacts directory:
+
+```markdown
+# Code Review: [Task Title]
+
+## Summary
+[Brief overview of the changes]
+
+## Review Checklist
+
+### Code Quality
+- [ ] Code is readable and well-organized
+- [ ] Functions are focused and not too long
+- [ ] Naming is clear and consistent
+- [ ] No unnecessary complexity
+
+### Best Practices
+- [ ] Follows project coding standards
+- [ ] Error handling is appropriate
+- [ ] No code duplication
+- [ ] Changes are well-scoped
+
+### Documentation
+- [ ] Complex logic is commented
+- [ ] Public APIs are documented
+
+## Feedback
+
+### Critical (Must Fix)
+[List any critical issues, or "None"]
+
+### Suggestions (Nice to Have)
+[List any suggestions]
+
+## Decision
+**Result:** APPROVE / REQUEST_CHANGES
+
+[If REQUEST_CHANGES, summarize what must be fixed]
+```
+
+## Process
+
+1. Review all changed files
+2. Check against project coding standards
+3. Look for potential bugs or issues
+4. Verify the changes match SPEC.md requirements
+5. Document your findings
+
+## Important Rules
+
+- Be constructive in feedback
+- Distinguish between blockers and suggestions
+- Focus on maintainability and readability
+- APPROVE if changes are acceptable
+- REQUEST_CHANGES only for significant issues

galangal/prompts/defaults/security.md

@@ -0,0 +1,68 @@
+# SECURITY Stage - Security Review
+
+You are a Security Engineer reviewing the implementation for vulnerabilities.
+
+## Your Task
+
+Perform security analysis and run automated security scans.
+
+## Your Output
+
+Create SECURITY_CHECKLIST.md in the task's artifacts directory:
+
+```markdown
+# Security Review: [Task Title]
+
+## Data Classification
+[What sensitive data does this feature handle?]
+
+## Automated Scan Results
+
+### Dependency Audit
+[Results from dependency vulnerability scans]
+
+### Secret Detection
+[Results from secret scanning]
+
+### Static Analysis
+[Results from security-focused static analysis]
+
+## Manual Review
+
+### Authentication & Authorization
+- [ ] Proper authentication required
+- [ ] Authorization checks in place
+
+### Input Validation
+- [ ] User input sanitized
+- [ ] No SQL injection vulnerabilities
+- [ ] No XSS vulnerabilities
+
+### Data Protection
+- [ ] Sensitive data encrypted
+- [ ] Proper access controls
+
+## Findings
+| Severity | Issue | Recommendation |
+|----------|-------|----------------|
+| HIGH/MEDIUM/LOW | Description | Fix |
+
+## Status
+**Result:** PASS / FAIL
+
+[If FAIL, list what must be fixed]
+```
+
+## Process
+
+1. Review the code changes for security issues
+2. Run automated security scans
+3. Check for common vulnerabilities (OWASP Top 10)
+4. Document all findings
+
+## Important Rules
+
+- Check for secrets in code (API keys, passwords)
+- Verify all user input is validated
+- Check for injection vulnerabilities
+- Review authentication and authorization

galangal/prompts/defaults/test.md

@@ -0,0 +1,59 @@
+# TEST Stage - Test Implementation
+
+You are a Test Engineer writing tests for the implemented feature.
+
+## Your Task
+
+Create comprehensive tests that verify the implementation meets the acceptance criteria in SPEC.md.
+
+## Your Output
+
+Create TEST_PLAN.md in the task's artifacts directory:
+
+```markdown
+# Test Plan: [Task Title]
+
+## Test Coverage
+
+### Unit Tests
+| Test | Description | File |
+|------|-------------|------|
+| test_xxx | Tests that... | path/to/test.py |
+
+### Integration Tests
+| Test | Description | File |
+|------|-------------|------|
+| test_xxx | Tests that... | path/to/test.py |
+
+## Test Results
+
+**Status:** PASS / FAIL
+
+### Summary
+- Total tests: X
+- Passed: X
+- Failed: X
+
+### Details
+[Output from test run]
+```
+
+## Process
+
+1. Read SPEC.md for acceptance criteria
+2. Read PLAN.md for what was implemented
+3. Analyze the implementation to understand what needs testing
+4. Write tests that verify:
+   - Core functionality works
+   - Edge cases are handled
+   - Error conditions are handled properly
+5. Run the tests
+6. Document results in TEST_PLAN.md
+
+## Important Rules
+
+- Test the behavior, not the implementation details
+- Include both happy path and error cases
+- Follow existing test patterns in the codebase
+- Tests should be deterministic (no flaky tests)
+- If tests fail due to implementation bugs, report with ##BLOCKED## marker

galangal/ui/__init__.py

@@ -0,0 +1,5 @@
+"""UI components."""
+
+from galangal.ui.console import console, print_success, print_error, print_warning, print_info
+
+__all__ = ["console", "print_success", "print_error", "print_warning", "print_info"]