pub struct PhaseOrchestrator { /* private fields */ }Expand description
Orchestrates the execution of spec generation phases.
This is the main entry point for running phases. It manages:
- Phase execution with dependency validation
- Artifact storage and receipt generation
- Lock management for concurrent access
- Error handling and partial artifact preservation
§API Stability and Usage Guidance
Production code: Use OrchestratorHandle for all production scenarios. It provides
a stable, higher-level API designed for CLI commands and external integrations.
Test code: PhaseOrchestrator exposes internal helper methods (marked with #[doc(hidden)])
for white-box testing of phase orchestration logic. These methods are public to enable testing
but are not part of the stable API and may change without notice.
Stability notice: Methods marked with #[doc(hidden)] are internal implementation details
and may be narrowed to pub(crate) visibility in future versions. Do not rely on them in
production code.
§Examples
Production usage (preferred):
let handle = OrchestratorHandle::new("my-spec")?;
handle.execute_requirements_phase(&config).await?;Test usage (white-box testing):
let orchestrator = PhaseOrchestrator::new("test-spec")?;
orchestrator.validate_transition(PhaseId::Design)?; // Test internal logic
let config = OrchestratorConfig::default();
orchestrator.execute_requirements_phase(&config).await?;Implementations§
Source§impl PhaseOrchestrator
impl PhaseOrchestrator
Sourcepub async fn execute_requirements_phase(
&self,
config: &OrchestratorConfig,
) -> Result<ExecutionResult>
pub async fn execute_requirements_phase( &self, config: &OrchestratorConfig, ) -> Result<ExecutionResult>
Execute the Requirements phase end-to-end with timeout.
This is the primary entry point for generating requirements from a spec. Validates the phase transition, builds a packet, invokes the LLM, and stores the resulting artifacts and receipt.
Used by CLI and Kiro flows; respects dry_run and LLM configuration.
Note: Public for tests and advanced integrations; prefer OrchestratorHandle
for general use. May be narrowed to pub(crate) in a future version.
Reserved for future orchestration API; not currently used by CLI.
§Errors
Returns error if transition is invalid or execution fails.
Sourcepub async fn execute_design_phase(
&self,
config: &OrchestratorConfig,
) -> Result<ExecutionResult>
pub async fn execute_design_phase( &self, config: &OrchestratorConfig, ) -> Result<ExecutionResult>
Execute the Design phase end-to-end with timeout.
Generates architecture and design documents based on requirements. Validates the phase transition and dependencies before execution.
Used by CLI and Kiro flows; respects dry_run and LLM configuration.
Note: Public for tests and advanced integrations; prefer OrchestratorHandle
for general use. May be narrowed to pub(crate) in a future version.
§Errors
Returns error if transition is invalid or execution fails.
Sourcepub async fn execute_tasks_phase(
&self,
config: &OrchestratorConfig,
) -> Result<ExecutionResult>
pub async fn execute_tasks_phase( &self, config: &OrchestratorConfig, ) -> Result<ExecutionResult>
Execute the Tasks phase end-to-end with timeout.
Generates implementation tasks and milestones based on design. Validates the phase transition and dependencies before execution.
Used by CLI and Kiro flows; respects dry_run and LLM configuration.
Note: Public for tests and advanced integrations; prefer OrchestratorHandle
for general use. May be narrowed to pub(crate) in a future version.
§Errors
Returns error if transition is invalid or execution fails.
Sourcepub async fn resume_from_phase(
&self,
phase_id: PhaseId,
config: &OrchestratorConfig,
) -> Result<ExecutionResult>
pub async fn resume_from_phase( &self, phase_id: PhaseId, config: &OrchestratorConfig, ) -> Result<ExecutionResult>
Resume execution from a specific phase.
Validates that all dependencies are satisfied before executing. Use this to continue a workflow from any valid phase.
§Arguments
phase_id- The phase to resume fromconfig- Execution configuration
§Errors
Returns error if dependencies are not satisfied or execution fails.
Source§impl PhaseOrchestrator
impl PhaseOrchestrator
Sourcepub fn new(spec_id: &str) -> Result<Self>
pub fn new(spec_id: &str) -> Result<Self>
Create a new orchestrator for the given spec ID.
Acquires an exclusive lock on the spec directory to prevent concurrent modifications.
§Errors
Returns error if lock cannot be acquired or artifact manager creation fails.
Sourcepub fn new_with_force(spec_id: &str, force: bool) -> Result<Self>
pub fn new_with_force(spec_id: &str, force: bool) -> Result<Self>
Create a new orchestrator with optional force flag for lock override.
Use with caution: forcing lock override can lead to race conditions if another process is actively working on the spec.
§Arguments
spec_id- The spec identifierforce- Whether to override existing locks
§Errors
Returns error if artifact manager creation fails.
Sourcepub fn new_readonly(spec_id: &str) -> Result<Self>
pub fn new_readonly(spec_id: &str) -> Result<Self>
Create a read-only orchestrator that doesn’t acquire locks.
Use this for status queries and inspection operations that don’t modify state. This allows reading spec data while another process holds the write lock.
§Errors
Returns error if artifact manager creation fails.
Sourcepub fn artifact_manager(&self) -> &ArtifactManager
pub fn artifact_manager(&self) -> &ArtifactManager
Returns a reference to the artifact manager. Used by status generation and tests.
Sourcepub fn receipt_manager(&self) -> &ReceiptManager
pub fn receipt_manager(&self) -> &ReceiptManager
Returns a reference to the receipt manager. Used by status generation and tests.