Metadata-Version: 2.4
Name: agentic-dev-workspace
Version: 0.1.0
Summary: Agentic Environment & Resource Orchestrator
Author-email: Nikhil <nikhil@example.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: typer>=0.9.0

<div align="center">

# 🧠 agentic-dev-workspace

### *A dual-agent AI coding environment that gets cheaper and smarter every session*

<br/>

[![CI](https://github.com/nikhil49023/agentic-dev-workspace/actions/workflows/ci.yml/badge.svg)](https://github.com/nikhil49023/agentic-dev-workspace/actions/workflows/ci.yml)
[![Architecture](https://img.shields.io/badge/Architecture-Dual--Agent-cba6f7?style=flat-square)](#architecture)
[![Memory](https://img.shields.io/badge/Memory-Persistent_Vault-a6e3a1?style=flat-square)](#agent-memory)
[![Research](https://img.shields.io/badge/Research-Self--Hosted_Firecrawl-89b4fa?style=flat-square)](#deep-research)
[![Workers](https://img.shields.io/badge/Workers-Groq_%2F_Ollama-f38ba8?style=flat-square)](#worker-llms)
[![Tests](https://img.shields.io/badge/Tests-23_passing-a6e3a1?style=flat-square)](#tests)
[![License](https://img.shields.io/badge/License-MIT-eba0ac?style=flat-square)](LICENSE)

<br/>

> **Stop paying for the same context twice.**  
> This workspace enforces a strict separation between cloud reasoning and local execution —  
> every session is cheaper than the last because your agent's memory compounds.

</div>

---

## The Problem This Solves

Every AI coding session with a default agent starts cold:

```
Session 1:  Re-reads your stack    Re-searches the docs    Re-derives the architecture  → 35,000 tokens
Session 2:  Re-reads your stack    Re-searches the docs    Re-derives the architecture  → 35,000 tokens
Session N:  Same.                  Same.                   Same.                        → 35,000 tokens
```

This workspace makes sessions **additive, not repetitive:**

```
Session 1:  Discovers → writes to .agent-memory/                                        → 20,000 tokens
Session 2:  Reads vault (400 tokens) → builds on it                                    →  5,000 tokens
Session 10: Vault is rich, graph is indexed, preferences are captured                  →  1,500 tokens
```

**Estimated savings: ~87% per session on mature projects.**

---

## 📐 Architecture
<br/>

```
┌────────────────────────────────────────────────────────────────────────────┐
│                      AGENTIC WORKSPACE ARCHITECTURE                        │
│                                                                            │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │          ☁️  CLOUD REASONING AGENT  (Main Agent)                    │  │
│  │                                                                     │  │
│  │   Focus: Planning · Logic · Debugging · Code Synthesis              │  │
│  │   Rules: .cursorrules  (6 enforced protocols)                       │  │
│  │                                                                     │  │
│  │   READS memory at session start ───────────────────────────────┐   │  │
│  │                                                                 ▼   │  │
│  │                      ┌──────────────────────────────────────┐  │   │  │
│  │                      │      💾 .agent-memory/ VAULT         │  │   │  │
│  │                      │  project_profile.md  (ground truth)  │  │   │  │
│  │                      │  research_vault.md   (scraped docs)  │◄─┘   │  │
│  │                      │  decisions.md        (ADR history)   │      │  │
│  │                      │  user_preferences.md (your style)    │      │  │
│  │                      └──────────────┬───────────────────────┘      │  │
│  │                                     │ Workers write here            │  │
│  └───────────────┬─────────────────────┴──────────────┬───────────────┘  │
│                  │                                     │                   │
│         DELEGATES                             NAVIGATES VIA               │
│                  │                                     │                   │
│  ┌───────────────▼─────────────┐       ┌──────────────▼─────────────┐   │
│  │  🕷️  deep_research.py       │       │  📊 code-review-graph MCP  │   │
│  │                             │       │                             │   │
│  │  → Firecrawl crawls docs    │       │  Hub/bridge nodes           │   │
│  │  → Worker LLM cleans it     │       │  Semantic search            │   │
│  │  → Auto-saves to vault      │       │  Minimal context fetch      │   │
│  └───────────────┬─────────────┘       └────────────────────────────┘   │
│                  │                                                         │
│  ┌───────────────▼─────────────────────────────────────────────────────┐  │
│  │  ⚡  worker_agent.py  →  Groq (cloud speed)  OR  Ollama (local free) │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────┘
```

---

## 📉 The Cost Curve

The more you use the workspace, the cheaper each session becomes:

```
Token cost per session
                                                                           
High │ ████████████████████  Default agent (flat — re-derives everything)
     │
     │ ▓▓▓░                  This workspace (Session 1 — research + setup)
     │    ░░░
     │      ░░░
Low  │         ░░░░░░░░░░░   This workspace (Session 5+ — vault is warm)
     └──────────────────────────────────────────────────────────────────▶
          1    2    3    5    10   20   50
```

**Why it compounds downward:**

| Mechanism | How it saves tokens |
|---|---|
| **Research is one-time** | Crawl Stripe docs once → stored forever in vault → never re-crawled |
| **Vault replaces file reads** | 80-token vault entry vs 500-token raw source file for the same fact |
| **Preferences stop correction loops** | Agent writes type hints first time → zero re-write back-and-forth |
| **Graph gets richer** | More code → more precise hub/bridge detection → smaller context slices |
| **Session boot loads warm context** | `make start` loads vault in ~400 tokens vs 5,000+ token cold re-derivation |

---

## 🔄 Session Lifecycle (How You Work With It)

```mermaid
sequenceDiagram
    autonumber
    actor You
    participant Start as make start
    participant Vault as 💾 Memory Vault
    participant Graph as 📊 Code-Review-Graph
    participant Research as 🕷️ deep_research.py
    participant Worker as ⚡ Groq / Ollama
    participant Agent as ☁️ Cloud Agent

    You->>Start: Begin session
    Start->>Vault: Read user_preferences.md
    Start->>Vault: Read project_profile.md
    Start->>Start: diagnose.sh (Firecrawl? Ollama? .env?)
    Start-->>You: SESSION READY banner + pending tasks

    You->>Agent: "Add Stripe webhook support"
    Agent->>Vault: Check research_vault.md for Stripe docs
    Note over Agent,Research: Not found — initiates research
    Agent->>Research: deep_research.py --url stripe.com/docs/webhooks
    Research->>Worker: Clean + structure raw docs
    Worker-->>Vault: Saved to .agent-memory/stripe_webhooks.md
    Agent->>Graph: semantic_search("POST webhook route")
    Graph-->>Agent: router.py L87-L112 (40 lines, not 400)
    Agent->>Vault: Read stripe_webhooks.md
    Agent-->>You: Implementation plan (no guessing)
    You->>Agent: Approve
    Agent-->>You: ✅ Feature complete

    You->>Start: make end
    Start->>Vault: Prompt to commit .agent-memory/ changes
    Start->>Vault: Clear session notes
```

---

## 🗂️ File Structure

```
agentic-dev-workspace/
│
├── 📋 .cursorrules                    ← 6 enforced agent protocols
├── 📖 README.md
├── 🧬 SELF_IMPROVEMENT.md             ← How the workspace evolves
├── 👤 PERSONALIZATION.md              ← How preferences are captured
├── ⚙️  Makefile                        ← make start / make research URL=...
├── 📦 requirements.txt
├── 🚫 .gitignore
├── 🔑 .env.example
│
├── 💾 .agent-memory/
│   ├── project_profile.md             ← Tech stack, schemas, dir structure
│   ├── research_vault.md              ← Auto-populated by Firecrawl pipeline
│   ├── decisions.md                   ← ADR-001 through ADR-005+
│   └── user_preferences.md            ← Your permanent standing instructions
│
├── 🤖 scripts/
│   ├── utils.py                       ← ⭐ Shared utility layer (log, paths, env)
│   ├── setup.sh                       ← One-command venv + dep bootstrap
│   ├── diagnose.sh                    ← Pre-flight: Python·Firecrawl·Ollama·.env
│   ├── session_start.py               ← Boot: vault load + service check + tasks
│   ├── session_end.py                 ← Close: commit memory + clear session notes
│   ├── agent_memory.py                ← Memory vault CRUD CLI
│   ├── worker_agent.py                ← Groq / Ollama task dispatcher
│   ├── deep_research.py               ← Firecrawl → worker → memory pipeline
│   └── personalize.py                 ← Standing preference capture
│
├── 🧪 tests/
│   ├── run_tests.sh                   ← bash tests/run_tests.sh
│   ├── test_agent_memory.py           ← 13 tests (list/add/read/delete/summarize)
│   └── test_personalize.py            ← 10 tests (add all categories + clear)
│
└── 🔧 .github/workflows/
    └── ci.yml                         ← Syntax check + tests on every push
```

---

## 🚀 Quick Start

### 1. Spin Up Local Services

**Firecrawl** (self-hosted scraping):
```bash
git clone https://github.com/mendableai/firecrawl.git ~/firecrawl
cd ~/firecrawl && docker compose up -d
# Running at http://localhost:3002
```

**Ollama** (local worker LLM):
```bash
# Install from https://ollama.com
ollama pull llama3.1
# Running at http://localhost:11434
```

### 2. Bootstrap Workspace
```bash
git clone https://github.com/nikhil49023/agentic-dev-workspace.git
cd agentic-dev-workspace

bash scripts/setup.sh       # Creates .venv, installs deps, copies .env
source .venv/bin/activate

# Edit .env — add your Groq key (optional but recommended for speed)
```

### 3. Verify Everything Works
```bash
make diagnose
```

```
  ✅ PASS  Python 3.11.x (≥ 3.10 required)
  ✅ PASS  .venv/ exists
  ✅ PASS  .env file present
  ✅ PASS  Git repo on branch: master
  ✅ PASS  Firecrawl reachable at http://localhost:3002
  ✅ PASS  Ollama reachable at http://localhost:11434  (models: llama3.1)
  ⚠️  WARN  GROQ_API_KEY not configured — Ollama still works
```

### 4. Start Your First Session
```bash
make start
```

---

## ⌨️ Makefile — Full Command Reference

```bash
# ── Session Lifecycle ──────────────────────────────────────────────────────
make start                    # Boot: load vault + service check + show tasks
make end                      # Close: commit memory + clear session notes
make diagnose                 # Pre-flight health check

# ── Deep Research (Firecrawl Pipeline) ────────────────────────────────────
make research URL=https://fastapi.tiangolo.com/tutorial/
make research-groq URL=https://stripe.com/docs/webhooks

# ── Worker LLM ────────────────────────────────────────────────────────────
make ask PROMPT="Write a FastAPI rate limiting middleware stub"
make ask-groq PROMPT="Summarise this module: ..."

# ── Memory Vault ──────────────────────────────────────────────────────────
make memory-list
make memory-read K=stripe_webhooks
make memory-add K=my_key CONTENT="my structured fact"
make memory-summarize         # Dump all entries as one LLM context block

# ── Personalization ───────────────────────────────────────────────────────
make remember NOTE="Always use type hints in Python"
make prefs                    # View all standing preferences
make clear-session            # Wipe transient session notes

# ── Tests & Setup ─────────────────────────────────────────────────────────
make test                     # Run all 23 tests
make setup                    # Re-run venv bootstrap
```

---

## 🧠 The `.cursorrules` Contract

The 6 enforced agent protocols — the backbone of the workspace:

| # | Protocol | Forbids | Mandates |
|---|---|---|---|
| 1 | **Role Boundaries** | Cloud LLM doing grunt work | Workers handle generation |
| 2 | **Research Protocol** | `google_search`, raw `read_url` | `deep_research.py` + Firecrawl only |
| 3 | **Navigation Protocol** | Full file dumps | `code-review-graph` MCP first |
| 4 | **Memory Protocol** | Planning without vault context | Read vault before every plan |
| 5 | **Personalization** | Forgetting user directives | `personalize.py add` on every preference |
| 6 | **Execution Tracker** | Losing progress across restarts | `task.md` always maintained |

---

## 👤 Personalization — The Agent Learns Your Style

When you say anything the agent should always remember, it captures it instantly:

```bash
make remember NOTE="Always add docstrings to every Python function"
make remember NOTE="I prefer PostgreSQL over SQLite"
make remember NOTE="Never use var in JavaScript"
```

These are stored permanently in `.agent-memory/user_preferences.md` and read **at the start of every session**. Your preferences travel with you across every project.

See [PERSONALIZATION.md](PERSONALIZATION.md) for the full guide including trigger phrases and categories.

---

## 🧬 How It Keeps Getting Better

Four compounding self-improvement loops — see [SELF_IMPROVEMENT.md](SELF_IMPROVEMENT.md):

```
Loop 1: Research Accumulation
  Research a library once → stored forever → never re-crawled

Loop 2: Architectural Self-Documentation
  Feature added → profile.md updated → no re-derivation next session

Loop 3: User Preference Learning
  Say a preference → captured → applied to every future task

Loop 4: Codebase Graph Evolution
  More code → richer graph → more precise context fetching
```

---

## 🧪 Tests

```bash
make test
```

```
Ran 23 tests in 3.1s — OK
```

| Test File | Coverage |
|---|---|
| `test_agent_memory.py` | list, add (append/normalise), read, delete (reserved key guard), summarize |
| `test_personalize.py` | all 5 categories, multi-add preservation, clear-session isolation |

---

## 🔧 CI / GitHub Actions

Every push and PR runs:
1. Python 3.11 setup
2. `pip install -r requirements.txt`
3. Syntax check on all 7 scripts
4. Full 23-test suite

[![CI](https://github.com/nikhil49023/agentic-dev-workspace/actions/workflows/ci.yml/badge.svg)](https://github.com/nikhil49023/agentic-dev-workspace/actions/workflows/ci.yml)

---

<div align="center">

**Built to make AI-assisted development fast, cheap, and hallucination-free.**  
*The longer you use it, the better it gets.*

[⭐ Star on GitHub](https://github.com/nikhil49023/agentic-dev-workspace) · [📖 SELF_IMPROVEMENT.md](SELF_IMPROVEMENT.md) · [👤 PERSONALIZATION.md](PERSONALIZATION.md)

</div>
