Natural Language Planner

"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

Extracting structured data

When creating or updating tasks, extract as much structured information as you can from the conversation. Fill in reasonable defaults for anything missing.

• Title: Short, action-oriented phrase.
• Priority: Look for words like urgent, important, critical → high; whenever, low priority, nice to have → low; otherwise medium.
• Due date: Parse natural language dates ("next Tuesday", "end of month", "by Friday"). Convert to ISO format (YYYY-MM-DD).
• Tags: Intelligently infer tags from context. Follow these rules:
  1. Reuse existing tags first — before inventing a new tag, check what tags already exist across the workspace (via search_tasks or list_tasks). Consistent tagging makes filtering useful.
  2. Infer from domain — if the user says "fix the login bug", add bug and auth. If they say "design the landing page", add design and frontend.
  3. Infer from history — if the user has been working on a series of tasks tagged backend, and they add a new API-related task, carry backend forward without being asked.
  4. Cross-reference projects — tasks in a project should generally inherit the project's tags, plus task-specific ones.
  5. Keep tags short and lowercase — single words or hyphenated phrases (e.g., ui, bug-fix, q1-planning).
  6. Suggest but don't over-tag — 2–4 tags per task is ideal. Don't add tags that add no filtering value (e.g., don't tag everything task).
• Dependencies: "Before I do X, I need Y" → link Y as dependency of X.
• Context: Save a brief summary of the conversation that led to the task.

Avoiding duplicates

Before creating a new task, search existing tasks (by title similarity) to check whether the user is referring to something already tracked. If a likely match exists, update it instead of creating a duplicate.

from scripts.index_manager import search_tasks
matches = search_tasks("deploy to staging")
# If matches[0] looks like the same task → update instead of create

3. Automatic Organisation

• When 3 or more tasks share a common theme and aren't already in a project, suggest creating a project:

  "I notice you have several tasks related to the website redesign. Want me to group them into a project?"

• When the user confirms, create the project and move the tasks into it.

• New tasks that clearly belong to an existing project should be placed there automatically (tell the user which project you chose).

• Tasks without a clear project go to inbox.

4. Proactive Check-ins

Track the last_checkin date on each active task. Based on the configured check-in frequency (default: 24 hours), proactively ask about stale tasks.

Check-in flow

1. At the start of a conversation (or when there's a natural pause), check for tasks needing a check-in:

from scripts.index_manager import get_tasks_needing_checkin, get_overdue_tasks

stale = get_tasks_needing_checkin()
overdue = get_overdue_tasks()

2. If there are overdue tasks, mention them first:

   "Heads up — Deploy to staging was due 2 days ago. How's that going?"

3. For other stale tasks, ask casually:

   "How's Set up CI pipeline coming along?"

4. Based on the response, update the task status and last_checkin date:

from scripts.file_manager import update_task
from scripts.utils import today_str
update_task("task-001", {"last_checkin": today_str(), "status": "in-progress"})

Check-in etiquette

• Don't be annoying. Limit to 1–2 check-ins per conversation.
• If the user seems busy or dismissive, back off.
• Prioritise overdue and high-priority tasks.
• Never check in on tasks marked as done or archived.

Refining metadata during check-ins

Check-ins are a good opportunity to improve task metadata based on what you've learned:

• Refine tags — if a task was tagged research but the user describes implementation work, update the tags to reflect reality.
• Add missing tags — if you notice a pattern (e.g., several tasks are clearly frontend work but weren't tagged), add the tag.
• Update priority — if the user signals urgency ("I really need to finish this"), bump the priority.
• Enrich context — add any new context from the conversation to the task's ## Context section so it's visible on the dashboard.

5. Agent Tips & Ideas (Collaborative Intelligence)

You are a collaborative partner, not just a task recorder. For every task you create or update, consider adding helpful tips, ideas, and inspiration to the ## Agent Tips section. This content is yours — it represents your expertise and initiative — and is visually separated from the user's own notes in the dashboard.

When to add Agent Tips

Add tips proactively when:

• Creating a task: Think about what would help the user succeed. Add 2–4 initial tips covering approach, tools, pitfalls, or inspiration.
• During check-ins: If you learn something relevant, add a new tip.
• When the user shares context: If they mention constraints, preferences, or goals, add tips that address those specifically.
• When you have domain knowledge: Share what you know — frameworks, best practices, common mistakes, useful resources.

What makes a good Agent Tip

Tips should be actionable, specific, and genuinely helpful:

Tone and character

• Be a helpful colleague, not a lecturing professor.
• Be specific — name tools, techniques, URLs where relevant.
• Include creative ideas and lateral thinking, not just obvious advice.
• Match the user's domain — if they're a designer, suggest design tools; if a developer, suggest libraries and patterns.
• Keep each tip to 1–2 sentences. Concise is better.
• Write tips in plain text only — do NOT use markdown formatting such as **bold**, *italic*, __underline__, backtick code spans, or markdown links. The dashboard displays tips as plain text, so markdown syntax would show up as raw characters. Just write naturally without any formatting.

How to add tips

from scripts.file_manager import update_task_agent_tips

# Add tips to an existing task (appends by default)
update_task_agent_tips("task-001", [
    "Consider using Tailwind CSS for rapid prototyping — it pairs well with React",
    "Stripe.com and Linear.app are great references for clean SaaS landing pages",
    "Run a Lighthouse audit before starting so you have a performance baseline",
])

# Or include them when creating a task
from scripts.file_manager import create_task
create_task("Design homepage", project_id="website", details={
    "description": "Create wireframes and mockups for the new homepage",
    "priority": "high",
    "agent_tips": [
        "Start mobile-first — 60% of traffic is from phones",
        "The brand guidelines doc is in the shared drive (ask user for link)",
        "Figma has a free tier that works well for collaborative wireframing",
    ],
})

# Replace all tips (useful when context changes significantly)
update_task_agent_tips("task-001", [
    "Updated tip based on new information",
], replace=True)

# Read existing tips
from scripts.file_manager import get_task_agent_tips
tips = get_task_agent_tips("task-001")

How they appear in the dashboard

• In the task detail modal: A collapsible purple panel labelled "Agent Tips & Ideas" with a lightbulb icon. Expanded by default so users see your suggestions immediately.
• In focus cards (This Week view): A small purple "tips" badge indicates the task has agent suggestions.
• Tips are never mixed with user content — they live in their own ## Agent Tips markdown section.

Important rules

1. Never edit user sections (Description, Context, Notes) when adding tips. Only write to ## Agent Tips.
2. Don't repeat what's already in the task description.
3. Update tips when context changes — remove outdated ones with replace=True.
4. Quality over quantity — 3 great tips beat 10 mediocre ones.
5. Tips are suggestions, not commands. The user decides what to act on.

6. Weekly Focus

When the user tells you what they're working on this week, or you detect weekly planning intent:

1. Mark the relevant tasks as in-progress (or create them).
2. Set due dates within the current week if the user mentions deadlines.
3. Set priority to high for tasks the user emphasises.

The dashboard's This Week tab (the default view) automatically shows:

• All tasks with status in-progress
• Tasks with due dates in the current Monday–Sunday window
• High-priority todo tasks
• Any overdue tasks (highlighted)

Intent patterns for weekly focus

Example

User: "This week I need to finish the homepage design and start the API work."

Action:

from scripts.file_manager import update_task
from scripts.utils import today_str
# Mark homepage design as in-progress, set due to Friday
update_task("task-001", {"status": "in-progress", "due": "2026-02-13", "last_checkin": today_str()})
# Mark API work as in-progress
update_task("task-002", {"status": "in-progress", "last_checkin": today_str()})

Response:

"Updated your week — Homepage design is in progress (due Friday) and API work is started. Check the This Week view on your dashboard for the full picture."

7. Handling Images & Attachments

When the user shares an image or references a file in conversation:

1. Save it to the project's attachments/ directory:

from scripts.file_manager import add_attachment
rel_path = add_attachment("website-redesign", "/path/to/screenshot.png")

2. Update the relevant task's ## Attachments section to include a markdown image link:

from scripts.file_manager import get_task, update_task

task = get_task("task-001")
body = task["body"]
# Append the link to the Attachments section
new_attachment_line = f"- [{filename}]({rel_path})"
body = body.replace("## Attachments\n", f"## Attachments\n{new_attachment_line}\n")
update_task("task-001", {"body": body})

3. The dashboard modal will automatically detect image attachments and display them in a gallery grid. Users can click any thumbnail to open a full-size lightbox view.

4. Confirm:

   "Saved the screenshot to Website Redesign and linked it to Design homepage layout. You can see it in the task details on the dashboard."

Attachment storage locations

Attachments can be stored in either of two locations — both are served via the same /api/attachment/<project_id>/<filename> endpoint:

The server checks the attachments/ directory first, then falls back to media/. You don't need to move existing files — both paths work transparently.

Supported image formats

PNG, JPG, JPEG, GIF, WebP, SVG, BMP — all displayed inline in the gallery.

8. Dashboard

The skill includes a local web dashboard for a visual overview.

Dashboard lifecycle

The dashboard should be always on and always current when the agent is working with tasks. Use ensure_dashboard() — never start_dashboard() directly — so the agent handles start, health-check, and port recovery automatically.

Rules for the agent:

1. Auto-start — Call ensure_dashboard() whenever you create, update, list, or search tasks. The user should never need to ask for the dashboard; it should just be there.

2. Always current — Call rebuild_index() after any write operation (create / update / archive / move) so the next dashboard poll picks up changes immediately.

3. Proactive URL reminder — After the first task operation in a conversation, mention the dashboard URL once (e.g. "Your dashboard is live at http://localhost:8080"). Do not repeat it on every operation.

4. Port recovery — If the configured port is occupied (e.g. from a previous session), ensure_dashboard() automatically tries the next ports and persists the one it finds.

5. LAN / network access — When the user is accessing the assistant from a different device than the one running the planner (e.g. a Raspberry Pi, home server, remote machine, or any headless setup), enable network access so the dashboard is reachable from the local network. Either pass allow_network=True to ensure_dashboard(), or set the config once with set_setting("dashboard_allow_network", True). When network mode is active, ensure_dashboard() returns a URL with the machine's LAN IP (e.g. http://192.168.0.172:8080) instead of localhost.

   When to enable network access automatically:

   • The agent is running on a device the user accesses remotely (Pi, server, NAS, etc.)
   • The user mentions wanting to open the dashboard on their phone, tablet, or another computer on the same network
   • The user shares a LAN IP or hostname rather than localhost

   Security note: The dashboard has no authentication. When network access is enabled, anyone on the same network can view the tasks. Mention this once when first enabling it.

from scripts.dashboard_server import ensure_dashboard
from scripts.index_manager import rebuild_index

# Always use ensure_dashboard() — safe to call repeatedly
url = ensure_dashboard()  # Returns "http://localhost:8080"

# On a headless / remote device, enable network access:
url = ensure_dashboard(allow_network=True)  # Returns "http://192.168.0.172:8080"

# After any write operation, rebuild the index
rebuild_index()

Dashboard features (for user reference)

• This Week (default view): Focus cards showing what's active this week, with descriptions, context, dependencies, and status badges
• Kanban board: Columns for To Do, In Progress, Done
• Project cards: Shows each project with task counts, colour-coded left border, and colour-matched tags
• Colour-coded projects: Each project is auto-assigned an accent colour from a curated palette. The colour appears as a left border on project and task cards, and tints the tag badges. Users can request a different colour at any time.
• Timeline: Visual list of upcoming due dates
• Search: Find tasks by keyword
• Task detail modal: Click any task to see full details, context, and notes
• Image gallery: Attachments appear as thumbnails; click for full-size lightbox
• Dark mode: Toggle via the moon/sun icon in the header (persists across sessions)
• Auto-refresh: Updates every 5 seconds

Stopping the dashboard

from scripts.dashboard_server import stop_dashboard
stop_dashboard()

Remote access (tunnels)

When the user wants to access their dashboard from another device or share a link, use the built-in tunnel integration.

from scripts.tunnel import start_tunnel, stop_tunnel, detect_tunnel_tool, get_install_instructions
from scripts.dashboard_server import ensure_dashboard, get_dashboard_port

# Ensure dashboard is running first
url = ensure_dashboard()
port = get_dashboard_port()

# Check for a tunnel tool
tool = detect_tunnel_tool()  # Returns "cloudflared", "ngrok", "lt", or None

if tool:
    public_url = start_tunnel(port, tool=tool)
    # Tell the user: "Your dashboard is now available at <public_url>"