@nomos-arc/arc 0.1.0

package/docs/how_it_works.md

@@ -0,0 +1,78 @@
+# nomos-arc.ai: How It Works
+
+## 1. Introduction to nomos-arc.ai (`arc`)
+
+**nomos-arc.ai** is a production-grade **AI-Native Engineering Pipeline** that transforms AI-assisted coding from an ad-hoc activity into a structured, auditable, and reliable process.
+
+The project provides a CLI tool called `arc` (The Architect) that acts as an orchestration layer, managing the lifecycle of coding tasks performed by AI agents like Claude Code or GitHub Copilot CLI.
+
+---
+
+## 2. Core Philosophy: The Wrapper Model
+
+nomos-arc is built on a key architectural insight: **don't rebuild what existing AI tools already do well — orchestrate them.**
+
+Instead of calling LLM APIs directly to edit files, `arc` spawns these powerful AI binaries inside isolated environments. It manages the "scaffolding" around the developer:
+*   **Rules Injection:** Forcing the AI to follow your project's specific engineering standards.
+*   **Isolated Branching:** Keeping AI work away from your production code until it's ready.
+*   **Automated Review:** Using one AI model to build and another to critique, creating a system of checks and balances.
+
+---
+
+## 3. High-Level Architecture
+
+### 3.1. Orchestration Layer
+The `arc` CLI manages the state machine of every task. It tracks progress from the moment a task is initialized until it is either merged or discarded.
+
+### 3.2. Deterministic Governance (Rules Engine)
+nomos-arc.ai uses a multi-level rules engine to ensure every AI session complies with your standards:
+1.  **Global Rules:** Base engineering standards (e.g., "All functions must have return types").
+2.  **Domain Rules:** Tech-specific rules (e.g., frontend-specific or backend-specific standards).
+3.  **Session Rules:** Constraints specific to a single task.
+
+### 3.3. Shadow Branching (Git Worktrees)
+To protect the main codebase, nomos-arc uses **Git Worktrees**. When you start a task, nomos-arc creates a "shadow branch" in a separate directory. The AI agent operates with full project context (it can see all your files), but its changes are physically isolated.
+
+---
+
+## 4. The Standard Workflow Loop
+
+nomos-arc.ai codifies the plan-review-refine loop that senior engineers do mentally:
+
+1.  **`arc init <task-id>`**:
+    *   Create a new task specification file (`.md`).
+    *   Set up a dedicated shadow branch and Git Worktree.
+    *   Lock in the rules version for this task.
+
+2.  **`arc plan <task-id>`**:
+    *   Assemble a prompt containing your rules + the task requirements.
+    *   Spawn the AI Planner (e.g., Claude Code) in the shadow branch.
+    *   The developer interacts with the AI to complete the task.
+    *   nomos-arc captures the final changes as a `.diff` artifact.
+
+3.  **`arc review <task-id>`**:
+    *   A separate AI model (the Reviewer) analyzes the diff against the rules.
+    *   It provides a structured JSON report with a quality score and specific issues.
+    *   If the score is below the threshold, the task moves to "Refinement".
+
+4.  **`arc apply <task-id>`**:
+    *   Once approved (and the developer is happy), the changes are merged into the main branch.
+    *   nomos-arc cleans up the worktree and shadow branch.
+
+---
+
+## 5. Technical Highlights
+
+*   **PTY Emulation**: nomos-arc uses `node-pty` to run AI tools in a real terminal environment, allowing it to capture output while maintaining a full interactive experience for the developer.
+*   **State Persistence**: All task progress is stored in a machine-readable JSON format, ensuring a complete audit trail of what was asked, what rules were applied, and what the AI produced.
+*   **Cost Control**: nomos-arc monitors token usage per task and can enforce budget limits to prevent runaway AI spending.
+*   **Shadow Branching Isolation**: By using external worktrees, nomos-arc prevents IDE confusion and accidental source modification.
+
+---
+
+## 6. Why Use nomos-arc.ai?
+
+*   **Structure**: Turns chaotic prompting into a repeatable engineering process.
+*   **Quality Gates**: Prevents AI-generated "hallucinations" or architectural drift from reaching production.
+*   **Traceability**: Provides a full record of AI contributions for security and compliance audits.
+*   **Consistency**: Ensures the entire team's AI usage aligns with the same coding standards.