Metadata-Version: 2.4
Name: openexec-planner
Version: 0.1.0
Summary: AI Project Planning Engine - From Intent to Executable Task DAGs
Project-URL: Homepage, https://openexec.io
Project-URL: Repository, https://github.com/openexec/openexec-planner
Project-URL: Documentation, https://docs.openexec.io
Project-URL: Issues, https://github.com/openexec/openexec-planner/issues
Author-email: OpenExec Team <hello@openexec.io>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,automation,dag,llm,planner,planning,software-engineering,task-orchestration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: structlog>=23.0
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: google-generativeai>=0.8; extra == 'all'
Requires-Dist: mypy>=1.0; extra == 'all'
Requires-Dist: openai>=1.50; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff>=0.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == 'llm'
Requires-Dist: google-generativeai>=0.8; extra == 'llm'
Requires-Dist: openai>=1.50; extra == 'llm'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">OpenExec Planner</h1>
</p>

<p align="center">
  <strong>AI Project Planning Engine — From Intent to Executable Task DAGs</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.11+-3776AB.svg" alt="Python"/>
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"/>
</p>

---

The **OpenExec Planner** module transforms high-level project intents (PRDs, specs, requirements) into structured, executable task hierarchies using AI-powered decomposition and goal tree analysis.

## Features

- **Guided Intent Interviewer** — Interactive chat to gather constraints and shape
- **Intent Parsing** — Extracts goals and requirements from PRD documents
- **Goal Tree Decomposition** — Breaks down objectives into atomic tasks
- **Story Generation** — Creates user stories with acceptance criteria
- **Dependency Modeling** — Infers and models execution prerequisites for parallel processing
- **Dependency Analysis** — Identifies task relationships and ordering
- **Quality Gate Templates** — Language-aware testing configurations
- **Context Awareness** — Integrates with codebase analysis

## How It Works

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   INTENT    │────▶│    PARSER    │────▶│  GOAL TREE  │
│  (PRD.md)   │     │  (AI Agent)  │     │   (JSON)    │
└─────────────┘     └──────────────┘     └──────┬──────┘
                                                │
                    ┌───────────────────────────┘
                    ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   STORIES   │────▶│    TASKS     │────▶│   SCHEDULE  │
│  (JSON)     │     │   (JSON)     │     │  (ordered)  │
└─────────────┘     └──────────────┘     └─────────────┘
```

## Installation

```bash
git clone https://github.com/openexec/openexec-planner.git
cd openexec-planner
pip install -e .
```

### CLI Dependencies

By default, the orchestration engine uses external CLI tools to call LLMs. Ensure you have the relevant tools installed and authenticated:

- **Claude Code**: `claude` CLI
- **Codex**: `codex` CLI
- **Gemini**: `gemini` CLI
- **OpenCode**: `opencode` (Ollama)

To use direct API calls instead, install the optional dependencies:
```bash
pip install "openexec-planner[llm]"
```

## Usage

The orchestration engine follows a logical project lifecycle:

### 1. Gather Intent (Wizard)

Start a guided interview to define your project shape, platform, and contracts. This is the recommended first step for any new project or refactor.

```bash
openexec-planner wizard --message "I want to build a new mobile app for gym tracking"
```

The wizard will track state and ask follow-up questions until the intent is "Ready", then render an `INTENT.md` file.

### 2. Generate Plan (Generate)

Once you have an `INTENT.md` (either from the wizard or manual), transform it into structured user stories and tasks.

```bash
openexec-planner generate INTENT.md -o .openexec/stories.json
```

### 3. Analyze Architecture (Build Tree)

Decompose the goals into a hierarchical tree to visualize the project structure.

```bash
openexec-planner build-tree INTENT.md -o .openexec/goal_tree.json
```

### 4. Order Execution (Schedule)

Generate an optimized execution schedule based on task dependencies.

```bash
openexec-planner schedule .openexec/stories.json -o .openexec/schedule.json
```

## Configuration

```yaml
# openexec.yaml
orchestration:
  agent: claude                  # AI agent for planning
  model: sonnet                  # Model for decomposition
  max_depth: 4                   # Goal tree max depth
  min_task_granularity: 2h       # Minimum task size
  max_task_granularity: 8h       # Maximum task size

planning:
  include_tests: true            # Generate test tasks
  include_docs: false            # Generate doc tasks
  language_detection: auto       # Detect project language
```

## Output Formats

### stories.json

```json
{
  "stories": [
    {
      "id": "US-001",
      "title": "User Registration",
      "description": "As a user, I want to register...",
      "acceptance_criteria": [
        "User can enter email and password",
        "Email validation is performed",
        "Success message is shown"
      ],
      "tasks": ["T-001", "T-002", "T-003"]
    }
  ]
}
```

### tasks.json

```json
{
  "tasks": [
    {
      "id": "T-001",
      "story_id": "US-001",
      "title": "Create registration form component",
      "description": "...",
      "status": "pending",
      "dependencies": [],
      "estimated_hours": 4
    }
  ]
}
```

### goal-tree.json

```json
{
  "root": {
    "goal": "Build user authentication",
    "children": [
      {
        "goal": "User registration",
        "children": [
          {"task": "T-001"},
          {"task": "T-002"}
        ]
      }
    ]
  }
}
```

## Project Structure

```
openexec-planner/
├── src/
│   └── openexec_planner/
│       ├── __init__.py
│       ├── parser.py           # Intent parsing
│       ├── generator.py        # Story generation
│       ├── goal_tree.py        # Goal tree building
│       ├── scheduler.py        # Task scheduling
│       └── templates/          # Prompt templates
├── tests/
├── pyproject.toml
└── README.md
```

## Language Detection

Automatically detects project language and configures appropriate:
- Quality gates (lint, test, typecheck)
- File patterns
- Build commands

Supported languages:
- Python (ruff, mypy, pytest)
- Go (gofmt, golangci-lint, go test)
- TypeScript/JavaScript (eslint, tsc, jest)
- Rust (cargo fmt, clippy, cargo test)

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

# Type check
mypy src/
```

## Related

- [openexec](../openexec) — Main documentation
- [initial](../initial) — Python CLI (feature-complete)
- [openexec-execution](../openexec-execution) — Execution engine
- [openexec-cli](../openexec-cli) — Go CLI with TUI

## License

MIT License
