OpenSpec & Experimental Workflows
Relevant source files
The following files were used as context for generating this wiki page:
- openspec/changes/archive/spec-kit-old/README_OLD.md
- openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
- openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md
- openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/plan.md
- openspec/changes/archive/spec-kit-old/002-replace-rng-currently/002-replace-rng-currently.md
- openspec/changes/archive/spec-kit-old/007-name-parallelize-mrmr/plan.md
- openspec/changes/archive/spec-kit-old/005-right-now-there/plan.md
- openspec/changes/archive/spec-kit-old/001-mrmr-feature-selector/plan.md
OpenSpec is the spec-driven development framework adopted by the DeepCausality project to streamline the implementation of complex features through AI-assisted orchestration. It utilizes a structured lifecycle—from feature story to implementation—ensuring that every change is grounded in technical specifications, architectural plans, and a project-specific constitution.
Sources: openspec/changes/archive/spec-kit-old/README_OLD.md:1-25
The OpenSpec Development Lifecycle
The OpenSpec workflow consists of a multi-phase execution flow managed via CLI commands. This process ensures that architectural decisions are made before code is written, reducing technical debt and alignment issues.
Workflow Phases
The workflow is categorized into distinct phases, each producing specific artifacts:
| Phase | Command | Output Artifacts | Description |
|---|---|---|---|
| Phase 0 | /plan | research.md | Research into technical unknowns and best practices. |
| Phase 1 | /plan | data-model.md, quickstart.md, contracts/ | Design of data structures and API contracts. |
| Phase 2 | /tasks | tasks.md | Generation of granular, ordered implementation tasks. |
| Phase 3 | /implement | Source Code | Test-driven implementation of the planned tasks. |
| Phase 4 | N/A | Validated Feature | Final testing and validation against the project constitution. |
Sources: openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md:10-30, openspec/changes/archive/spec-kit-old/README_OLD.md:40-55
Execution Flow Diagram
The following diagram illustrates the standard transition of a feature from a user story to a built task list within the OpenSpec environment.
Project Constitution and Principles
Every OpenSpec plan must pass a "Constitution Check" to ensure it adheres to project standards. This check is performed twice: once before Phase 0 research and again after Phase 1 design.
Key Constitutional Principles
- Simplicity: Maximum of 3 projects per feature; avoid wrapper classes and unnecessary patterns like Repository/UoW.
- Architecture: Every feature must be implemented as a library; CLIs must support specific flags (
--help,--version,--format). - Testing (Non-Negotiable): Strict Red-Green-Refactor cycle. Tests must be written before implementation. Integration tests are required for new libraries and shared schemas.
- Coding Conventions: Public types must have private fields with explicit accessors. Static dispatch is preferred over
dynor trait objects. - Safety: No
unsafecode is allowed in library crates.
Sources: openspec/changes/archive/spec-kit-old/005-right-now-there/plan.md:45-95, openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md:120-135
Planning and Risk Assessment
OpenSpec emphasizes proactive risk mitigation during the /plan stage. For advanced features, the agent is required to conduct a risk assessment and update the plan with mitigation strategies.
Risk Management Structure
Common risk categories identified in experimental workflows include:
- Technical Risks: Numerical instability in algorithms (e.g., mRMR), performance overhead of abstractions (e.g., HKT), and data races in parallel execution.
- Schedule Risks: Underestimation of effort for massive refactors.
- Quality Risks: Incomplete test coverage or code quality degradation.
Sources: openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md:195-235, openspec/changes/archive/spec-kit-old/001-mrmr-feature-selector/plan.md:35-45
Risk Mitigation Flow
Causal Discovery DSL (Experimental Workflow)
A primary application of the OpenSpec process is the Causal Discovery Language (DSL), which uses monadic composition to streamline causal analysis.
DSL Pipeline Stages
The DSL pipeline follows a strict typestate transition to prevent semantic errors at compile time.
| State | Transition Command | Resulting State |
|---|---|---|
CQD<NoData> | .start(loader, config) | CQD<WithData> |
CQD<WithData> | .feat_select(selector, config) | CQD<WithFeatures> |
CQD<WithFeatures> | .causal_discovery(discovery, config) | CQD<WithCausalResults> |
CQD<WithCausalResults> | .analyze(analyzer) | CQD<WithAnalysis> |
CQD<WithAnalysis> | .finalize(formatter) | CQD<Finalized> |
Sources: openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:145-165
Data Flow in Causal Discovery
The following diagram illustrates how data transforms from raw files into actionable causal insights using the DSL components.
Summary
OpenSpec and experimental workflows in DeepCausality provide a rigorous framework for evolving the project. By enforcing a project constitution, requiring up-front research, and leveraging monadic DSL patterns for complex data flows, the system ensures that high-level causal reasoning remains both technically sound and easy to compose for developers.
Sources: openspec/changes/archive/spec-kit-old/README_OLD.md:100-115, openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:180-195