vibeblocks_code is a multi-agent orchestrator built on top of VibeBlocks to run an AI-assisted development loop:

Problem → Hypothesis → Plan → Implementation → Test → Evaluation

The project defines specialized blocks, connects YAML prompt templates, and executes a configurable CLI command (default: echo) to simulate or integrate external LLM agents.

This packaged Python module lets you:

• Define a workflow with sequential blocks.
• Render prompts from YAML templates.
• Execute AI tools through the terminal with timeout and error capture.
• Persist execution metadata in the workflow context.
• Evaluate outputs using structured JSON to decide next actions.

It is designed to be minimal, extensible, and easy to adapt to different model CLIs (codex, gemini, claude, etc.).

For domain-specific documentation, see:

• Installation Guide
• Setup and Configuration
• Glossary

vibeblocks-code/
├── pyproject.toml
├── README.md
├── requirements.txt
├── prompt_vibeblocks_code.md
└── vibeblocks_code/
    ├── __init__.py
    ├── main.py
    ├── blocks/
    │   ├── __init__.py
    │   ├── hypothesis.py
    │   ├── plan.py
    │   ├── implement.py
    │   ├── test.py
    │   └── evaluate.py
    ├── core/
    │   ├── __init__.py
    │   ├── block_runner.py
    │   ├── cli_executor.py
    │   ├── cli_runner.py
    │   ├── prompt_library.py
    │   ├── prompt_renderer.py
    │   └── workflow.py
    └── prompts/
        ├── hypothesis.yaml
        ├── planning.yaml
        ├── implementation.yaml
        ├── testing.yaml
        └── evaluation.yaml

Note: folders like build/ and *.egg-info/ are packaging artifacts and are not part of the core source code.

• Python 3.10+
• pip

python -m venv venv
source venv/bin/activate
pip install -e .

python -m pip wheel . -w dist
pip install dist/vibeblocks_code-*.whl

Main dependencies:

• vibeblocks
• pyyaml

File: vibeblocks_code/core/workflow.py

• Main function: run_workflow(problem: str, cli_command: str = "echo")
• Builds the Flow with these blocks:
  1. hypothesis
  2. plan
  3. implement
  4. test
  5. evaluate

Each block:

• Reads required values from context.
• Renders a YAML prompt.
• Executes the configured CLI.
• Saves output into ctx.data.

Included blocks:

• hypothesis.py: generates the initial hypothesis.
• plan.py: creates the implementation plan.
• implement.py: produces implementation output.
• test.py: generates/runs testing stage output.
• evaluate.py: evaluates results and sets next_action.

• core/block_runner.py: shared helpers (require_value, execute_block).
• core/cli_executor.py: robust CLI execution with timeout (120s).
• core/prompt_library.py: loads YAML prompts from vibeblocks_code/prompts/.
• core/prompt_renderer.py: thin prompt-rendering wrapper.

Location: vibeblocks_code/prompts/*.yaml

Available templates:

• hypothesis.yaml
• planning.yaml
• implementation.yaml
• testing.yaml
• evaluation.yaml

You can run the sample flow in two ways:

python -m vibeblocks_code.main

or with the installed command:

vibeblocks-code

• Uses problem = "Write a Python function that sorts a list".
• Uses cli_command="echo" (demo mode, no real LLM).
• Prints:
  • Status
  • flow Logs
  • accumulated Data in context

To use a real agent, pass another command to run_workflow (e.g., codex, gemini, etc.) from your own script:

from vibeblocks_code.core.workflow import run_workflow

result = run_workflow(
    problem="Implement a priority queue in Python",
    cli_command="codex"
)

print(result.status)
print(result.context.data)

Make sure your chosen CLI is installed and authenticated in your environment.

During execution, keys are populated in result.context.data, for example:

• problem
• hypothesis
• plan
• code
• tests
• evaluation (hypothesis_valid, next_action, reasoning)
• meta (stdout/stderr/exit_code per block)

• Missing required context key: ValueError.
• CLI timeout over 120s: controlled timeout handling.
• Non-zero CLI exit code: RuntimeError.
• Invalid JSON from evaluate: sets next_action="proxy.php?url=https%3A%2F%2Fgithub.com%2Fabort" and stores parse_error in meta.

The project uses modern packaging via pyproject.toml and setuptools:

• Distribution name: vibeblocks_code
• Expected wheel name: vibeblocks_code-<version>-py3-none-any.whl
• CLI entry point:
  • vibeblocks-code

Useful commands:

python -m pip install -e .
python -m pip wheel . -w dist
python -m pip show vibeblocks-code