Under the Hood

How ORKA bridges the gap between your OS and your Agent.

The Dual-Folder System

ORKA is zero-dependency in your actual code. It lives entirely in two hidden directories at the root of your project. This means you can delete ORKA at any time without breaking your app.

📂 .agent/ (Static Intelligence)

Contains the skills, tools, and executable logic. This is read-only for the most part.

  • ├── skills/
  • ├── workflows/
  • └── scripts/

🧠 .orka/ (Dynamic Memory)

Contains the project's memories, plans, and state. This is read-write and evolves with your project.

  • ├── brain.md
  • ├── plan.md
  • └── state.md
my-project/
├── .agent/           # The "Hands"
│   ├── skills/
│   │   ├── orka-init/
│   │   ├── react-app/
│   │   └── node-api/
│   └── tools/
│
├── .orka/            # The "Brain"
│   ├── brain.md        # Context & Knowledge
│   ├── plan.md         # Current Objectives
│   └── graph.json      # Dependency Graph
│
├── src/                # Your actual code
├── package.json
└── README.md
👤
🤖
📁
ORKA Runtime

The Context Engine

When you type "Use ORKA", the runtime intercepts the request. It doesn't send your raw prompt to the model immediately.

  1. 1. State Injection

    ORKA reads .orka/state.md to understand the current project status (e.g., "Login page is half-done").

  2. 2. Constraint Loading

    It loads design rules from active skills. If you're doing React, it loads React Hooks rules. If Python, PEP8.

  3. 3. Deterministic Planning

    It generates a formal plan.md step-by-step checklist. You approve it, THEN it executes.