Weekly Planner

File-based weekly planner using TOML for inbox capture, time-block scheduling, weekly review, task rollover, and optional calendar export or Google Calendar...

A lightweight, file-based weekly planner that lives in a workspace folder as plain text (.toml). It supports:

• Inbox capture (planner/inbox.toml) for fast, append-only task capture
• Weekly plans (planner/weeks/YYYY-Www.toml) with:
  • scheduled time blocks (can be published to a calendar)
  • unscheduled weekly bits / daily bits
  • an end-of-week review
• A runbook (planner/runbook.toml) of recurring blocks copied into each new week
• Optional mode cards (planner/modes/*.md) describing how the user wants to work in different contexts

When to use this skill

Use this skill when the user asks for any of the following:

• “Plan my week”, “time-block my week”, “create a weekly plan”, “make a schedule for next week”
• “Capture this in my inbox”, “add this to my planner”, “triage my tasks”
• “Create a new week file”, “roll over last week’s unfinished tasks”
• “Publish/sync my planner to my calendar”, “export an .ics for my week”
• “Do an end-of-week review”

Don’t use this skill for full project-management systems (Jira/Linear/etc.) unless the user explicitly wants that.

Quick start

1) Ensure the planner folder exists

Look for a planner/ folder in the current workspace that contains planner/config.toml.

If it doesn’t exist, initialise a fresh planner skeleton (safe: refuses to overwrite existing folders):

bash

python3 {baseDir}/scripts/init_planner.py --target ./planner

This creates:

• planner/config.toml
• planner/inbox.toml
• planner/runbook.toml
• planner/weeks/WEEK_TEMPLATE.toml
• planner/modes/*.md
• planner/scripts/new_week.py
• planner/scripts/rollover_week.py
• planner/scripts/validate.py
• planner/scripts/sync_week.py (Google Calendar sync via gog)
• planner/scripts/export_ics.py (calendar export without Google tooling)
• planner/logs/

2) Tell the user what to customise

Ask the user to review planner/config.toml and customise:

• timezone (IANA tz name, e.g. Europe/Berlin)
• modes.* (their mode names + labels)
• (Optional) calendar publish settings (see “Publish to calendar” below)

3) Create (or roll over) a week

Create a new week file:

bash

python3 planner/scripts/new_week.py --week-start 2026-03-02

Or roll over unfinished tasks from the most recent week:

bash

python3 planner/scripts/rollover_week.py --next

4) Validate before “publishing” anything

Run validation after edits (especially before calendar publish):

bash

python3 planner/scripts/validate.py --week planner/weeks/2026-W10.toml

Core workflows

A) Inbox capture

Goal: capture tasks with minimal friction.

Rules:

• Treat planner/inbox.toml as append-only.
• Add one [[items]] block per task.
• Keep each entry small; use notes only when it helps.

When the user says “add this to my inbox”, append a new item like:

toml

[[items]]
created = "YYYY-MM-DDTHH:MM:SS+01:00"
text = "(task description)"
mode = "ops"               # any key from config.toml [modes.*]
est_minutes = 30
priority = "medium"        # low|medium|high
status = "todo"            # todo|doing|done|dropped
notes = ""

If the user doesn’t specify mode, choose a reasonable default (usually their “ops/admin” mode).

B) Triage inbox → weekly plan

Goal: turn raw inbox items into (a) 2–3 outcomes, (b) a small set of scheduled blocks, and (c) a manageable list of unscheduled bits.

Process:

1. Read planner/inbox.toml.
2. Ask the user for:
   • hard constraints (deadlines, appointments, travel)
   • 2–3 outcomes they care about this week
   • anything non-negotiable (exercise, family time, admin)
3. Convert inbox items into one of:
   • time blocks (must happen at a specific time)
   • weekly bits (do sometime this week)
   • daily bits (do sometime on a specific day)
   • or mark as dropped if it’s not happening this week

Keep the plan intentionally small:

• 2–5 focus tasks
• A few high-leverage time blocks
• A short “bits” list the user can realistically finish

C) Create a new week file

Use when the user wants to start planning a new week.

1. Determine week_start (a Monday date in YYYY-MM-DD).

2. Generate the file (copies runbook blocks into [[time_blocks]]):

bash

python3 planner/scripts/new_week.py --week-start 2026-03-02

3. Then edit planner/weeks/2026-W10.toml:

• Fill [goals] outcomes (2–3 crisp outcomes)
• Add focus_tasks (2–5 items max)
• Add / adjust [[time_blocks]] (scheduled blocks)
• Add [[weekly_bits]] and [[daily_bits]] for unscheduled tasks

D) Roll over unfinished work (optional)

Use when the user has an existing week file and wants to start the next week without retyping.

Typical flow:

bash

python3 planner/scripts/rollover_week.py --next

This:

• finds the most recent week in planner/weeks/
• creates the next week (week_start + 7 days)
• copies runbook blocks into the new week’s [[time_blocks]]
• carries over unfinished weekly_bits and daily_bits

E) Publish time blocks to a calendar (optional)

Only [[time_blocks]] are published.

Two safe options:

Option 1: Google Calendar sync (direct, destructive)

This workflow is destructive by design — it updates/deletes managed events.

Safety rules (must follow):

• Only ever sync to a dedicated planner calendar (never the user’s main calendar).
• Always run dry-run first.
• Only run with --apply if BOTH are true:
  1. The user explicitly asked you to apply changes.
  2. calendar.write_enabled = true in planner/config.toml.

Requirements:

• gog CLI installed + authenticated (steipete/gogcli)

Dry-run:

bash

python3 planner/scripts/sync_week.py --week planner/weeks/2026-W10.toml

Apply:

bash

python3 planner/scripts/sync_week.py --week planner/weeks/2026-W10.toml --apply

Option 2: Export an .ics file (safe, non-destructive)

Works without Google tooling.

bash

python3 planner/scripts/export_ics.py --week planner/weeks/2026-W10.toml

This writes planner/weeks/2026-W10.ics, which the user can import into most calendar apps.

F) End-of-week review

At the end of the week, help the user fill:

• review.score (0–10)
• review.wins (1–5 bullets)
• review.fails (1–5 bullets)
• review.what_i_learned (short paragraph)
• review.next_week_focus (1–2 sentences)

Quality gates

Before publishing/syncing:

1. Run validation:

bash

python3 planner/scripts/validate.py --week planner/weeks/2026-W10.toml

2. Fix all errors.
3. Treat warnings as “strong suggestions” (overlaps, out-of-bounds blocks, unknown modes).

References

• File formats and schema: references/PLANNER_SCHEMA.md
• Calendar publish & safety model: references/CALENDAR_SYNC.md

Troubleshooting

“Python can’t import tomllib” / “No module named tomllib”

You’re on Python < 3.11.

Fix: install Python 3.11+ and re-run.

“gog: command not found”

Google Calendar sync requires the gog CLI.

Fix: either install gogcli (see references) or use the .ics export instead.

“Refusing to apply changes: calendar.write_enabled is false”

Intentional safety latch.

Fix: have the user set calendar.write_enabled = true once they’re confident in the dry-run output.