synara-ai 0.1.0

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 has been divided into modular guides for easier navigation:

• 🧠 Synara Framework Architecture & Agent Limits
• 🏛️ 13-Layer System Architecture: Detailed breakdown of the runtime execution layers and directories.
• 📜 Prompt-as-Code Philosophy: Explore the rules governing our Prompt-as-Code ecosystem.
• ⚙️ Configuration Guide: Explains the synara.config.json schema, including AI memory constraints and Quota Fallback logic.
• 💻 CLI Reference: Documentation for the synara-ai CLI, safe file writer, and command options.
• 📦 Presets, Agents, and Skills: Catalog of built-in templates, advanced Android integrations, and mobile libraries.
• 🔄 Git Workflow: Standardized branching and commit processes for Synara.

---

🚀 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 git+https://github.com/DamianosDev/harness_engineers.git@develop

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.