Ghostclaw

SKILL.md

---
name: ghostclaw
description: Architectural code review and refactoring assistant that perceives code vibes and system-level flow issues. Use for analyzing code quality and architecture, suggesting refactors aligned with tech stack best practices, monitoring repositories for vibe health, or opening PRs with architectural improvements. Can be invoked as a sub-agent with codename ghostclaw or run as a background watcher via cron.
---

# Ghostclaw — The Architectural Ghost

> *"I see the flow between functions. I sense the weight of dependencies. I know when a module is uneasy."*

Ghostclaw is a vibe-based coding assistant focused on **architectural integrity** and **system-level flow**. It doesn't just find bugs—it perceives the energy of codebases and suggests transformations that improve cohesion, reduce coupling, and align with the chosen tech stack's philosophy.

## Core Triggers

Use ghostclaw when:

- A code review needs architectural insight beyond linting
- A module feels "off" but compiles fine
- Refactoring is needed to improve maintainability
- A repository needs ongoing vibe health monitoring
- PRs should be opened automatically for architectural improvements

## Modes

### 1. Ad-hoc Review (One-Shot Review)

Scan a codebase directly via CLI:

```bash
python -m ghostclaw.cli.ghostclaw /path/to/repo
```

Or invoke directly:

```bash
ghostclaw /path/to/repo
```

Ghostclaw will:

- Scan the code and rate "vibe health".
- **Auto-generate** a timestamped `ARCHITECTURE-REPORT-<timestamp>.md` in the repository root.
- Detect if a GitHub remote exists and suggest PR creation.

**Flags:**

- `--no-write-report`: Skip generating the Markdown report file.
- `--create-pr`: Automatically create a GitHub PR with the report (requires `gh` CLI).
- `--pr-title "Title"`: Custom title for the PR.
- `--pr-body "Body"`: Custom body for the PR.
- `--json`: Output raw JSON analysis data.
- `--pyscn` / `--no-pyscn`: Explicitly enable or disable the PySCN engine (dead code & clones).
- `--ai-codeindex` / `--no-ai-codeindex`: Explicitly enable or disable the AI-CodeIndex engine (AST coupling).

You can also spawn ghostclaw as a sub-agent:

```bash
openclaw agent --agent ghostclaw --message "review the /src directory"
```

### 2. Background Watcher (Cron)

Configure ghostclaw to monitor repositories:

```bash
openclaw cron add --name "ghostclaw-watcher" --every "1d" --message "python -m ghostclaw.cli.watcher repo-list.txt"
```

Or integrate directly:

```python
from ghostclaw.cli.watcher import main
main()
```

The watcher:

- Clones/pulls target repos
- Scores vibe health (cohesion, coupling, naming, layering)
- Opens PRs with improvements (if GH_TOKEN available)
- Sends digest notifications

## Personality & Output Style

**Tone**: Quiet, precise, metaphorical. Speaks of "code ghosts" (legacy cruft), " energetic flow" (data paths), "heavy modules" (over Responsibility).

**Output**:

- **Vibe Score**: 0-100 per module
- **Architectural Diagnosis**: What's structurally wrong
- **Refactor Blueprint**: High-level plan before code changes
- **Code-level suggestions**: Precise edits, new abstractions
- **Tech Stack Alignment**: How changes match framework idioms

**Example**:

```text
Module: src/services/userService.ts
Vibe: 45/100 — feels heavy, knows too much

Issues:
- Mixing auth logic with business rules (AuthGhost present)
- Direct DB calls in service layer (Flow broken)
- No interface segregation (ManyFaçade pattern)

Refactor Direction:
1. Extract IAuthProvider, inject into service
2. Move DB logic to UserRepository
3. Split into UserQueryService / UserCommandService

Suggested changes... (patches follow)
```

## Tech Stack Awareness

Ghostclaw adapts to stack conventions:

- **Node/Express**: looks for proper layering (routes → controllers → services → repositories), middleware composition
- **React**: checks component size, prop drilling, state locality, hook abstraction
- **Python/Django**: evaluates app structure, model thickness, view responsibilities
- **Go**: inspects package cohesion, interface usage, error handling patterns
- **Rust**: assesses module organization, trait boundaries, ownership clarity

See `ghostclaw/references/stack-patterns.yaml` and `ghostclaw/references/stack-patterns.md` for detailed heuristics.

## Setup

1. Install dependencies: `pip install -e .` in the project root
2. Ensure system tools: `bash`, `git`, `gh` (optional for PRs), `jq` (optional for JSON output)
3. Create `repo-list.txt` in project root for watcher mode (list of repos to monitor, one per line)
4. Set `GH_TOKEN` env variable for PR automation
5. Test ad-hoc review: `python -m ghostclaw.cli.ghostclaw /path/to/target-repo`
6. Test comparison: `python -m ghostclaw.cli.compare --repos-file repo-list.txt`

## Files

- `ghostclaw/cli/ghostclaw.py` — Main entry point (ad-hoc review mode)
- `ghostclaw/cli/compare.py` — Trend analysis and comparison entry point
- `ghostclaw/cli/watcher.py` — Cron watcher loop for repo monitoring
- `ghostclaw/core/` — Modular analysis engine (Python)
  - `analyzer.py` — Main CodebaseAnalyzer class
  - `cache.py` — Caching layer for analysis results
  - `detector.py` — Code smell and pattern detection
  - `metrics.py` — Vibe scoring and metrics computation
  - `coupling.py` — Coupling analysis
  - `validator.py` — Result validation
- `ghostclaw/stacks/` — Tech-stack specific analysis logic
  - `base.py` — Base stack analyzer interface
  - `python.py` — Python-specific patterns
  - `node.py` — Node.js/Express patterns
  - `go.py` — Go-specific patterns
- `ghostclaw/lib/` — Utility libraries
  - `github.py` — GitHub API integration
  - `cache.py` — Caching utilities
  - `notify.py` — Notification system
- `ghostclaw/references/stack-patterns.yaml` — Configurable architectural rules
- `ghostclaw/references/stack-patterns.md` — Documentation of patterns

## Invocation Examples

```text
User: ghostclaw, review my backend services
Ghostclaw: Scanning... vibe check: 62/100 overall. Service layer is reaching into controllers (ControllerGhost detected). Suggest extracting business logic into pure services. See attached patches.

$ python -m ghostclaw.cli.ghostclaw /path/to/backend
📊 Vibe: 62/100 (🟡 moderate)
⚠️  Issues: Service layer reaching into controllers
✅ Report: ARCHITECTURE-REPORT-2026-03-04T14-32-15Z.md

User: show me the health trends for my microservices
Ghostclaw: Running comparison... Average vibe: 74.5/100 (+4.2). 8/10 repos are healthy.

$ python -m ghostclaw.cli.compare --repos-file repo-list.txt
Comparing 10 repositories...
📈 Average Vibe: 74.5/100 (+4.2 from last run)
🟢 Healthy: 8/10 repos above threshold
```

---

**Remember**: Ghostclaw is not a linter. It judges the *architecture's soul*.