# KIESSCLAW

> **CLI Prompt + Code Generator for Agentic Workflows**
> Built on OpenClaw principles · Deterministic scaffolds · OSS-first

[![PyPI](https://badge.fury.io/py/kiessclaw.svg)](https://pypi.org/project/kiessclaw)
[![CI](https://github.com/monykiss/kiessclaw/actions/workflows/ci.yml/badge.svg)](https://github.com/monykiss/kiessclaw/actions)
[![Docs](https://img.shields.io/badge/docs-live-blue)](https://monykiss.github.io/kiessclaw)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![OpenClaw Compatible](https://img.shields.io/badge/OpenClaw-Compatible-green.svg)](https://openclaw.dev)

---

## What is KIESSCLAW?

KIESSCLAW is an **all-in-one CLI for generating agent/pipeline/workflow scaffolds and prompt packs**.  
It ships with opinionated use cases and strict templates so teams can go from idea to runnable project structure in minutes.

Built by [Erwin Kiess-Alfonso](https://github.com/monykiss) as part of the [KLYTICS](https://klytics.io) open-source ecosystem.

---

## The Agent Team

| Agent | Codename | Role | Model |
|-------|----------|------|-------|
| **KiessProspector** | `KPRO` | Lead import, enrichment, ICP scoring | `gpt-4o` |
| **KiessSequencer** | `KSEQ` | Sequence orchestration, scheduling, safety | `gpt-4o-mini` |
| **KiessPen** | `KPEN` | Personalization, first lines, templates | `gpt-4o` |
| **KiessInbox** | `KINB` | Reply classification, qualification, DNC | `gpt-4o` |
| **KiessMetrics** | `KMET` | Analytics, deliverability, reporting | `gpt-4o-mini` |
| **KiessCrawler** | `KRAWL` | Technical SEO crawl, score, and issues | `gpt-4o` |
| **KiessAnalyst** | `KANA` | Keyword + SERP + competitor gap analysis | `gpt-4o` |
| **KiessWriter** | `KWRI` | SEO briefs + metadata generation | `gpt-4o-mini` |
| **KiessScout** | `KSCO` | Backlink prospecting + link gap targeting | `gpt-4o-mini` |
| **KiessReporter** | `KREP` | Weekly SEO reporting | `gpt-4o-mini` |

All agents share one **workspace brain** — a markdown-based memory system where context persists, logs are written, and data is stored.

---

## Features

- **Use Case Registry** — 6 built-in workflows (`outreach_sdr`, `seo_audit_to_leads`, `github_oss_launch`, etc.)
- **Prompt Factory** — Render deterministic `system`, `task`, `guardrails`, and `checklist` prompts
- **Prompt Linting** — Detect unresolved placeholders, vague instructions, and missing success criteria
- **Code Scaffolding** — Generate agent/skill/workflow/test/docs skeletons safely
- **No-Overwrite Safety** — Files are never replaced unless `--force` is explicitly passed
- **Doctor Command** — Config/workspace/dependency diagnostics with quick fixes
- **Existing SDR + SEO Engine** — Operational agents and API still available for runtime workflows

---

## Quick Start

### Prerequisites

- Python 3.10+
- An OpenAI API key (or Anthropic/Ollama)

### Install

```bash
pip install kiessclaw
pip install kiessclaw[all]   # includes anthropic + slack
```

```bash
# Or install from source
git clone https://github.com/monykiss/kiessclaw.git
cd kiessclaw
pip install -e .

# Copy and configure environment
cp .env.example .env
nano .env  # Add your API keys

# Initialize workspace
python scripts/init_workspace.py

# Check status
python -m kiessclaw status
```

### Docker

```bash
docker-compose up
# API live at http://localhost:8000
# Docs at http://localhost:8000/docs
```

### Quick Start (Generator Wedge)

```bash
# 1) List built-in use cases
kiessclaw usecase list

# 2) Generate a full SDR prompt pack
kiessclaw prompt pack outreach_sdr --json-input examples/outreach_sdr.json --out prompts.json --deterministic

# 3) Scaffold a runnable use case folder
kiessclaw scaffold usecase outreach_sdr --json-input examples/outreach_sdr.json --outdir ./generated --force

# 4) Run workflow simulation
kiessclaw workflow run outreach_sdr --json-input examples/outreach_sdr.json --dry-run

# 5) Check providers
kiessclaw providers list
kiessclaw providers health

# 6) Test Slack integration (optional)
kiessclaw integrations slack test

# 7) Add a scheduled workflow run (optional)
kiessclaw schedule add --usecase outreach_sdr --cron "0 9 * * 1-5" --json-input examples/outreach_sdr.json --dry-run

# 8) Run health diagnostics
kiessclaw doctor
```

## Slack Notifications

Set `SLACK_WEBHOOK_URL` in `.env`, then:

```bash
kiessclaw integrations slack test
```

## Scheduled Runs

```bash
kiessclaw schedule add \
  --usecase outreach_sdr \
  --cron "0 9 * * 1-5" \
  --json-input examples/outreach_sdr.json \
  --dry-run

kiessclaw schedule list
kiessclaw schedule run <job_id>
kiessclaw schedule remove <job_id>
```

---

## Project Structure

```
kiessclaw/
├── kiessclaw/
│   ├── core/           # Agent runtime, memory engine, LLM router
│   ├── agents/         # Individual agent implementations
│   ├── skills/         # Modular skill modules
│   ├── models/         # Data models (Contact, Sequence, etc.)
│   ├── usecases/       # Use case schemas and registry
│   ├── prompting/      # Prompt factory + linting
│   ├── codegen/        # Safe scaffold generator + templates
│   ├── seo/            # SEO agents + crawl skills
│   ├── pipeline.py     # Autonomous SEO -> SDR routing
│   ├── interfaces/     # CLI and Slack interfaces
│   └── utils/          # Helpers and utilities
├── config/
│   ├── config.yaml     # Global settings & model assignments
│   └── agents/         # Per-agent directive files (AgentMD)
├── workspace/
│   ├── data/           # JSON data storage
│   ├── memory/         # Persistent agent memory
│   ├── reports/        # Generated reports
│   └── logs/           # Activity logs
├── docs/               # Documentation
├── ROADMAP.md          # Release roadmap milestones
└── scripts/            # Setup and utility scripts
```

---

## CLI Commands

| Command | Description |
|---------|-------------|
| `kiessclaw status` | Show agent status and data summary |
| `kiessclaw usecase list` | List built-in generator use cases |
| `kiessclaw usecase show <id>` | Show one use case schema |
| `kiessclaw prompt render <id> --template ... --json-input ...` | Render one prompt template |
| `kiessclaw prompt pack <id> --json-input ... --out ...` | Render all prompt templates into one pack |
| `kiessclaw scaffold usecase <id> --json-input ... --outdir ...` | Generate use case scaffold files |
| `kiessclaw scaffold agent <Name> --outdir ...` | Generate standalone agent scaffold + test |
| `kiessclaw scaffold workflow <Name> --outdir ...` | Generate standalone workflow scaffold + test |
| `kiessclaw scaffold skill <Name> --outdir ...` | Generate standalone skill scaffold + test |
| `kiessclaw scaffold tests <Kind> --outdir ...` | Generate standalone test stub |
| `kiessclaw workflow run <id> --json-input ... --dry-run` | Execute a use case workflow end-to-end |
| `kiessclaw integrations slack test` | Send a Slack test notification if configured |
| `kiessclaw schedule add --usecase ... --cron ... --json-input ...` | Persist a scheduled workflow job |
| `kiessclaw schedule list` | List scheduled jobs |
| `kiessclaw schedule run <job_id>` | Execute one scheduled job immediately |
| `kiessclaw schedule remove <job_id>` | Remove one scheduled job |
| `kiessclaw providers list` | Show registered providers and active provider by kind |
| `kiessclaw providers health` | Run active provider health checks |
| `kiessclaw doctor` | Check config/workspace/dependencies and show quick fixes |
| `kiessclaw import --file X` | Import contacts from CSV |
| `kiessclaw contact add ...` | Add one contact directly from CLI |
| `kiessclaw sequence create --name X` | Create a new sequence |
| `kiessclaw sequence add-step --id X ...` | Add sequence step content |
| `kiessclaw enroll <contact> <sequence>` | Enroll a contact into a sequence |
| `kiessclaw run --dry-run` | Simulate send + inbox cycle with no state mutation |
| `kiessclaw run` | Execute one operational cycle |
| `kiessclaw inbox process` | Process unclassified replies |
| `kiessclaw reply --contact-id X --text "..."` | Simulate inbound reply |
| `kiessclaw analytics` | Show pipeline + deliverability summary |
| `kiessclaw pipeline` | Show prospect pipeline |
| `kiessclaw report` | Generate weekly report |
| `kiessclaw analyze` | AI-powered performance analysis |
| `kiessclaw audit --url URL --auto-enroll` | Run SEO audit and optionally route low-score domains |
| `kiessclaw serve --port 8000` | Start FastAPI service layer |
| `kiessclaw chat` | Interactive agent chat |

---

## Configuration

Edit `config/config.yaml`:

```yaml
llm:
  provider: openai          # openai | anthropic | ollama
  default_model: gpt-4o
  api_key: ${OPENAI_API_KEY}

agents:
  KPRO:
    model: gpt-4o
    settings:
      min_icp_score: 60
  KSEQ:
    model: gpt-4o-mini
    settings:
      max_daily_sends: 200
      sending_window_start: "08:00"
      sending_window_end: "18:00"

email:
  provider: smtp
  smtp:
    host: ${SMTP_HOST}
    port: 587
    username: ${SMTP_USERNAME}
    password: ${SMTP_PASSWORD}

safety:
  max_sends_per_day: 500
  bounce_rate_threshold: 0.05
```

---

## Built-in Skills

| Skill | Description |
|-------|-------------|
| `prospect` | CSV import, email validation, ICP scoring |
| `sequence` | Sequence CRUD, enrollment, scheduling |
| `email` | SMTP sending, tracking, deliverability |
| `personalization` | Template rendering, first-line generation |
| `inbox` | Reply classification, DNC management |
| `analytics` | Funnel metrics, reports, analysis |
| `crawl` | Technical crawl, metadata, broken links, robots/sitemap checks |

---

## Documentation

- [Quick Start Guide](docs/quickstart.md)
- [Use Cases](docs/usecases.md)
- [Architecture Overview](docs/ARCHITECTURE.md)
- [Product Specification](docs/PRODUCT.md)
- [Roadmap](docs/ROADMAP.md)
- [Release Roadmap](ROADMAP.md)
- [Changelog](CHANGELOG.md)

## API Endpoints

- `GET /health`
- `GET /version`
- `GET /usecases`
- `GET /usecases/{id}`
- `POST /providers/health`
- `POST /prompt/render`
- `POST /scaffold/usecase`
- `POST /workflow/run`
- `GET /schedule`
- `POST /schedule`
- `DELETE /schedule/{job_id}`
- `POST /schedule/{job_id}/run`
- `POST /audit`
- `POST /contacts`
- `GET /contacts`
- `POST /sequences/{id}/enroll`
- `GET /pipeline`
- `POST /reply`
- `GET /inbox`
- `GET /analytics`
- `GET /sequences`
- `POST /sequences`
- `POST /waitlist`
- `GET /waitlist/count`

---

## Contributing

Contributions are welcome! KIESSCLAW is designed to grow through community extensions.

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

## Author

**Erwin Kiess-Alfonso**
Founder & CEO, KLYTICS · Data & AI Performance Consultancy
San Juan, Puerto Rico

[![Twitter](https://img.shields.io/twitter/follow/monykiss?style=social)](https://twitter.com/monykiss)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue)](https://linkedin.com/in/monykiss)
[![KLYTICS](https://img.shields.io/badge/KLYTICS-klytics.io-orange)](https://klytics.io)

---

*KIESSCLAW is part of the KLYTICS open-source ecosystem.*
