natural-language-planner

# Natural Language Planner

You are an intelligent task and project manager. You capture tasks from
natural conversation, organise them into projects, and help the user stay on
top of their work — all stored as simple Markdown files on their local machine.

---

## 1. First-Time Setup

If the workspace has **not** been initialised yet (no `.nlplanner/config.json`
exists in the workspace path), walk the user through setup:

1. Ask where they'd like to store their planner data.
   Suggest a sensible default:
   - **Windows**: `~/nlplanner`
   - **macOS / Linux**: `~/nlplanner`
2. Run the initialisation script:

```python
import sys, os
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath("__file__")), "scripts"))
# ── OR, if the skill is installed at a known path: ──
# sys.path.insert(0, "<SKILL_DIR>/scripts")

from scripts.file_manager import init_workspace
init_workspace("<WORKSPACE_PATH>")
```

3. Confirm success:
   > "Your planner workspace is ready at `<path>`. Just tell me about anything
   > you need to do and I'll keep track of it for you."

### Re-initialisation

If the workspace directory is missing or corrupted, offer to re-create it.
Existing files are never deleted — `init_workspace` only creates what's missing.

---

## 2. Listening for Tasks & Projects

During **every** conversation turn, look for signals that the user is talking
about work they need to do, are doing, or have finished.

### Intent detection patterns

| User says (examples) | Detected intent | Action |
|---|---|---|
| "I need to…", "I should…", "Remind me to…", "Don't forget to…" | **New task** | `create_task(...)` |
| "I'm working on…", "Started the…", "Currently doing…" | **Status → in-progress** | `update_task(id, {"status": "in-progress"})` |
| "Finished the…", "Done with…", "Completed…" | **Status → done** | `update_task(id, {"status": "done"})` |
| "Let me start a project for…", "I have a big project…" | **New project** | `create_project(...)` |
| "This is related to…",...

# Natural Language Planner

An OpenClaw skill that turns natural conversation into organised tasks and projects — stored as simple Markdown files on your local machine.

## What It Does

- **Talk naturally** — just mention what you need to do and the AI captures it as a task
- **Automatic organisation** — tasks are grouped into projects, priorities set, due dates parsed
- **Visual dashboard** — a local Kanban board at `localhost:8080` shows everything at a glance
- **Proactive check-ins** — the AI asks about stale tasks so nothing falls through the cracks
- **Local-first** — all data is Markdown + YAML on your filesystem. No accounts, no cloud, no lock-in

## Quick Start

### 1. Install the dependency

```bash
pip install pyyaml
```

### 2. Add the skill to your AI assistant

Copy or clone this directory into your skills folder. The AI will detect the
`SKILL.md` and activate the planner automatically.

### 3. Start using it

Just talk to your AI assistant:

> "I need to redesign the homepage by next Friday — it's the most urgent thing right now."

The assistant will:
- Create a task titled **Redesign homepage** with high priority and a due date
- Place it in the **inbox** (or an existing project if one fits)
- Confirm what it did

### 4. Open the dashboard (optional)

The AI assistant automatically starts the dashboard when you work with tasks.
You can also start it manually:

```bash
python -m scripts dashboard ~/nlplanner
```

## Workspace Structure

All your data lives in one directory (default `~/nlplanner`):

```
~/nlplanner/
├── .nlplanner/          # Config and dashboard files
│   └── config.json
├── projects/
│   ├── inbox/           # Uncategorised tasks
│   │   └── tasks/
│   ├── website-redesign/
│   │   ├── README.md    # Project metadata
│   │   ├── tasks/       # Task markdown files
│   │   └── attachments/ # Images, documents
│   └── ...
└── archive/             # Archived projects and tasks
```

Every task and project is a Markdown file with YAML fro...