synara-ai 0.1.1

Synara reusable CLI tool

Synara Framework: AI Agent Prompts & Architecture

This project defines and implements the Synara Framework, a robust architecture for orchestrating autonomous Multi-Agent systems using a strict Prompt-as-Code philosophy. This framework controls behavior, optimizes context windows, and raises the reliability of AI Agents throughout the software development lifecycle by decoupling agent intelligence from rigid execution logic.

---

📖 Documentation Hub

The Synara Framework documentation is now hosted on our interactive platform for easier navigation:

• 🚀 Introduction to Synara: Overview of the framework, limits, and Prompt-as-Code philosophy.
• 🏛️ 13-Layer System Architecture: Detailed breakdown of the runtime execution layers and directories.
• 🔄 Operational Workflow: Interactive React Flow diagrams showing multi-agent pipelines and delegations.
• ⚙️ Configuration Guide: Explains the synara.config.json schema, including AI memory constraints and Quota Fallback logic.
• 💻 CLI Reference: Documentation for the synara-ai CLI, templates, and command options.

---

🚀 Installation

Synara provides a standalone CLI (synara-ai) that can be installed globally via pipx or brew.

Option 1: Install via pipx (Recommended)

This is the recommended way to install Python CLIs as it creates an isolated environment.

pipx install synara-ai

Option 2: Install via Homebrew

You can install the CLI directly from the source code using the provided Homebrew formula:

brew install ./Formula/synara-ai.rb

---

⚡ Core Principles

The Synara system operates on four main technical pillars:

1. Prompt-as-Code: Agent intelligence, behavior, and roles must be defined explicitly in Markdown files with YAML frontmatter (.synara/agents/*.md), completely decoupled from Python execution code.
2. Context Engineering: Deliver exactly what the agent needs through a Context Pack (intentional context compression), rather than stuffing the entire codebase. This prevents the AI from hallucinating.
3. No Vibes Allowed: Force the AI to perform structured, step-by-step planning and reasoning before writing any code.
4. Anti-Slop: Constraint the output format via an Output Contract, automatically rejecting wordy or redundant responses and preventing unrelated logic changes.

---

📜 Prompt-as-Code Architecture

Synara strictly enforces that all Agent definitions must live in Markdown files, not hardcoded in Python. This guarantees modularity, easy maintenance, and protects the system from architectural regression.

Dynamic Agent Loading

When an agent is requested, the system uses the markdown_loader.py module to dynamically parse the Markdown files located in .synara/agents/*.md.

Each file must contain a YAML Frontmatter block:

---
name: code-reviewer
description: Expert code reviewer specializing in SOLID principles and clean architecture.
model: models/gemini-3.1-pro-high
tools:
  - view_file
  - run_command
---

The content below the frontmatter serves as the Agent's specific System Prompt.

AST Guardrails

To prevent future developers or AI systems from regressing into a hardcoded architecture, the project utilizes strict AST (Abstract Syntax Tree) unit tests (tests/test_architecture_guardrails.py). If any large string constant (prompt) is detected directly inside the Python agent controllers, the CI pipeline will instantly fail.