agentic-stack-portable-brain

What this skill does

```markdown
---
name: agentic-stack-portable-brain
description: Portable .agent/ folder (memory + skills + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Hermes, Pi, or DIY Python and keeps knowledge across harness switches.
triggers:
  - set up agentic stack for this project
  - install portable agent brain
  - add agent memory to my project
  - configure claude code with agentic stack
  - switch my agent to a different harness
  - set up persistent agent memory and skills
  - run the dream cycle for agent lessons
  - graduate or reject agent candidate lessons
---

# agentic-stack-portable-brain

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

## What agentic-stack does

`agentic-stack` gives any AI coding agent a **portable brain**: a `.agent/` folder containing four memory layers, a progressive-disclosure skill system, enforced permissions, and adapters for eight harnesses. When you switch from Claude Code to Cursor (or any other supported harness), the agent's accumulated knowledge travels with the project — no re-learning, no lost lessons.

### Core concepts

| Concept | Description |
|---|---|
| **Memory layers** | `working/` (session), `episodic/` (action log), `semantic/` (graduated lessons), `personal/` (preferences) |
| **Skills** | Markdown files with trigger matching; manifest always loads, full `SKILL.md` only when relevant |
| **Protocols** | Typed tool schemas, `permissions.md`, delegation contracts |
| **Review protocol** | `auto_dream.py` stages candidates mechanically; host agent reviews with CLI tools |
| **Harness adapters** | Thin shims per tool (CLAUDE.md, .windsurfrules, AGENTS.md, etc.) |

---

## Installation

### macOS / Linux (Homebrew)

```bash
brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack
brew install agentic-stack

cd your-project
agentic-stack claude-code   # or: cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python
```

### Windows (PowerShell)

```powershell
git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack
.\install.ps1 claude-code C:\path\to\your-project
```

### Clone and install manually

```bash
git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack

# macOS / Linux / Git Bash
./install.sh claude-code /path/to/your-project

# Windows PowerShell
.\install.ps1 claude-code C:\path\to\your-project
```

### Supported harness names

```
claude-code | cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python
```

### Upgrade

```bash
brew update && brew upgrade agentic-stack
```

---

## Onboarding wizard

The wizard runs automatically after adapter installation and writes:
- `.agent/memory/personal/PREFERENCES.md` — first file the AI reads each session
- `.agent/memory/.features.json` — feature toggles

```bash
# accept all defaults silently (CI / scripted environments)
agentic-stack claude-code --yes

# re-run wizard on an existing project
agentic-stack claude-code --reconfigure
```

### Wizard questions

| Question | Default |
|---|---|
| What should I call you? | *(skip)* |
| Primary language(s)? | `unspecified` |
| Explanation style? | `concise` |
| Test strategy? | `test-after` |
| Commit message style? | `conventional commits` |
| Code review depth? | `critical issues only` |

### Manual preference editing

```bash
# Edit preferences any time
$EDITOR .agent/memory/personal/PREFERENCES.md

# Toggle features
$EDITOR .agent/memory/.features.json
```

`.features.json` example:

```json
{
  "fts_memory_search": false
}
```

---

## Key CLI commands

### Review protocol (host-agent tools)

```bash
# List pending candidate lessons, sorted by priority
python3 .agent/tools/list_candidates.py

# Accept a candidate (--rationale required — rubber-stamping is structurally impossible)
python3 .agent/tools/graduate.py <id> --rationale "evidence holds, matches PREFERENCES"

# Reject a candidate (--reason required; decision history preserved)
python3 .agent/tools/reject.py <id> --reason "too specific to this repo to generalize"

# Requeue a previously-rejected candidate
python3 .agent/tools/reopen.py <id>
```

### Memory search [BETA]

```bash
# Enable during onboarding or toggle manually in .features.json, then:
python3 .agent/memory/memory_search.py "deploy failure"
python3 .agent/memory/memory_search.py --status
python3 .agent/memory/memory_search.py --rebuild
```

Falls back to `ripgrep` → `grep` when FTS5 index is not enabled. Index stored at `.agent/memory/.index/` (gitignored).

### Nightly staging cycle (cron)

```bash
# Add to crontab: runs at 03:00 daily, safe to run unattended
crontab -e
# Paste:
0 3 * * * python3 /absolute/path/to/project/.agent/memory/auto_dream.py >> /absolute/path/to/project/.agent/memory/dream.log 2>&1
```

`auto_dream.py` only does mechanical work: cluster, stage, prefilter, decay. No git commits, no network calls, no LLM reasoning.

---

## Repository layout

```
.agent/
├── AGENTS.md                   # the map every harness reads
├── harness/                    # conductor + hooks (standalone path)
├── memory/
│   ├── working/                # session-scoped scratch
│   ├── episodic/               # action log (all skill events)
│   ├── semantic/
│   │   ├── lessons.jsonl       # source of truth for graduated lessons
│   │   └── LESSONS.md          # rendered from lessons.jsonl
│   ├── personal/
│   │   └── PREFERENCES.md      # loaded first every session
│   ├── auto_dream.py           # nightly staging cycle
│   ├── cluster.py              # Jaccard single-linkage clustering
│   ├── promote.py              # stage candidates
│   ├── validate.py             # heuristic prefilter
│   ├── review_state.py         # candidate lifecycle + decision log
│   ├── render_lessons.py       # lessons.jsonl → LESSONS.md
│   └── memory_search.py        # [BETA] FTS5 search
├── skills/
│   ├── _index.md               # always-loaded lightweight manifest
│   ├── _manifest.jsonl         # trigger → skill mapping
│   └── *.SKILL.md              # full skill files (lazy-loaded)
├── protocols/
│   ├── permissions.md          # enforced by pre-tool-call hook
│   ├── tool-schemas/           # typed schemas per tool
│   └── delegation.md           # sub-agent contract
└── tools/
    ├── list_candidates.py
    ├── graduate.py
    ├── reject.py
    ├── reopen.py
    ├── memory_reflect.py
    └── skill_loader.py

adapters/
├── claude-code/    # CLAUDE.md + .claude/settings.json (PostToolUse, Stop hooks)
├── cursor/         # .cursor/rules/*.mdc
├── windsurf/       # .windsurfrules
├── opencode/       # AGENTS.md + opencode.json
├── openclaw/       # .openclaw-system.md
├── hermes/         # AGENTS.md
├── pi/             # AGENTS.md + .pi/skills symlink → .agent/skills
└── standalone-python/  # run.py DIY conductor
```

---

## Seed skills (shipped with every install)

| Skill | Purpose |
|---|---|
| `skillforge` | Creates new skills from recurring patterns |
| `memory-manager` | Runs reflection cycles, surfaces candidate lessons |
| `git-proxy` | All git ops with safety constraints |
| `debug-investigator` | Reproduce → isolate → hypothesize → verify loop |
| `deploy-checklist` | Gate between staging and production |

---

## Code examples

### Python: running the staging cycle programmatically

```python
import subprocess
import sys
from pathlib import Path

def run_dream_cycle(project_root: str) -> None:
    dream_script = Path(project_root) / ".agent" / "memory" / "auto_dream.py"
    log_path = Path(project_root) / ".agent" / "memory" / "dream.log"

    if not dream_script.exists():
        raise FileNotFoundError(f"auto_dream.py not found at {dream_script}")

    with log_path.open("a") as log_file:
        result = subprocess.run(
            [sys.executable, str(dream_script)],
            stdout=log_file,
            stderr=log_file,
            cwd=project_root,
        )

    if result.returncode != 0:
        print(f"Dream cycle exited w