ebade: The Agent-First Protocol 🧠🌱

🌗 Hybrid Workflow: The Best of Both Worlds

ebade splits the development process into two distinct, high-efficiency phases:

1. 🛡️ Offline Architect (Deterministic)

The ebade CLI runs locally and requires 0 tokens. It uses pattern matching and predefined architectural rules to scaffold your project's skeleton, design system, and file structure.

• Speed: Instant results.
• Reliability: 100% deterministic (no hallucinations).
• Cost: Free.

2. 🧠 Online Agent (Generative)

Once the scaffold is ready, your AI Agent (Claude, Cursor, etc.) takes over to fill in the complex business logic using the project.ebade.yaml as its source of truth.

• Focus: AI only works on the "hard parts."
• Efficiency: ~70% token savings by not generating boilerplate.
• Alignment: The agent follows the rules ebade already set in stone.

"Code is a legacy byproduct. Intent is the source of truth."

ebade is not just another framework. It is a compilation protocol designed for an era where AI Agents are the primary developers. It shifts the paradigm from "Human-Centric Coding" to "Agentic Intent Modeling."

🎬 The Power of Intent

Watch how ebade transforms 20 lines of YAML into a production-ready, full-stack Next.js application.

⚔️ The Battle of Entropy

| Legacy Coding (High Entropy) | ebade Protocol (Low Entropy) | | :--- | :--- | | "Write me a dashboard..." | "@intent('saas-dashboard')" | | AI guesses folders, imports, and state. | ebade enforces architecture. | | 1,500+ tokens burned (Noise). | <250 tokens used (Pure Signal). | | Hallucinations likely. | Deterministic output. |

🛠️ The Syntax (Cheat Sheet)

ebade uses a high-density decorator syntax designed to fit within an Agent's context window.

| Decorator | Purpose | Example | | :--- | :--- | :--- | | @page | Defines routes & paths | @page('/dashboard') | | @intent | The "What" of the logic | @intent('user-auth') | | @requires | Data & Auth dependencies | @requires(['user', 'db']) | | @compose | Intent orchestration | @compose(['header', 'list']) | | @outcomes | Result handlers & UI | @outcomes({ success: '/dashboard' }) | | @expects | Tests as Specification | @expects([{ scenario: 'happy-path' }]) |

📖 Full Syntax Specification

🧠 The Architect: Prompt-to-Product

In v1.1.0, we introduce ebade Pulse. ebade continues to be the most stable professional-grade, multi-target framework built natively for AI agents. Whether it's Web (Next.js), Android (Flutter), or iOS (SwiftUI), ebade forges your legacy with a single prompt. 🚀

# One-shot project creation
npx ebade build "A luxury concierge service with pricing, testimonials and a gold theme"

• Intent Intelligence: Automatically detects app type (SaaS, E-commerce, Blog).
• Universal LogicForge: Generates Types, Services, and Mocks for Next.js, Flutter, and SwiftUI simultaneously.
• Dynamic Design: Generates a premium HSL color palette from your prompt.
• Smart Scaffolding: Detects needed components (auth, charts, forms) and dynamically creates routes.
• Green AI Dashboard: Integrated sustainability metrics to measure token and carbon savings.

🚀 Quick Start

1. Build from Prompt (One-Shot)

npx ebade build "Create a dark themed eco-monitor with real-time stats"

2. Scaffold from Intent (Professional)

# Generate project from an existing .ebade.yaml
npx ebade scaffold examples/saas-dashboard.ebade.yaml ./my-app

3. For AI Agents (MCP)

Add ebade to your AI agent (Claude, Cursor, Windsurf) via the Model Context Protocol:

{
  "mcpServers": {
    "ebade": {
      "command": "npx",
      "args": ["-y", "ebade-mcp-server"]
    }
  }
}

🏗️ Architecture: First Principles

ebade operates on the principle of The Online Compiler. It treats AI as a deterministic component of the toolchain, not a creative oracle.

• Standardized Intent Tree (SIT): Parses YAML/TS into a logical graph.
• Target Adapters: Compiles intent into Next.js, Flutter, or SwiftUI (0-token boilerplate).
• AgentRules: Automatically generates .cursorrules and .clauderules to keep your agent aligned.

🏗️ Explore the Architecture

📊 Benchmark: ~70% Fewer Tokens

| Task | Legacy (Next.js) | ebade (Protocol) | Savings | | :--- | :--- | :--- | :--- | | SaaS Dashboard ⭐ | 1,850 tokens | 245 tokens | 86.8% | | Checkout Flow | 258 tokens | 66 tokens | 74.4% | | Product Grid | 133 tokens | 63 tokens | 52.6% |

"The greenest code is the code you don't generate." 🌱

📦 Project Structure

• cli/: The core scaffolding engine & EbadeArchitect.
• packages/mcp-server/: The bridge for AI agents via MCP.
• www/: The ebade.dev landing page & playground.
• examples/: Real-world intent templates for various app types.

🤝 Contributing

ebade is open source and welcomes contributions! Whether it's a new adapter, a component template, or a bug fix, we'd love to have you.

1. Star this repo ⭐
2. Try the MCP server with your AI agent
3. Open issues with ideas and feedback
4. Submit PRs for new features

See CONTRIBUTING.md for full guidelines.

💎 Support the Movement

ebade is an ambitious project aiming to redefine software engineering for the AI age. Your support helps us build a more sustainable "Green AI" future.

• Become a GitHub Sponsor 💖
• Star the repo to show your support ⭐
• Share the project with other enthusiasts 🚀

🔒 Privacy & Telemetry

ebade collects anonymous usage statistics (ebade Pulse) to help us understand how the framework is used and to improve it.

• What we collect: Command name, target platform (Next.js/Flutter), basic OS info, and performance metrics (files generated, tokens saved).
• What we NEVER collect: Your code, your ebade YAML content, project names, or any personal information.
• How to disable: Set EBADE_TELEMETRY_DISABLED=1 in your environment.

📄 License

MIT © ebade Contributors — Made with ❤️ in Türkiye 🇹🇷

Built for AI. Readable by humans. Revolutionary by design.

TypeScript made JavaScript better for humans. ebade makes frameworks better for AI.