Weekly Planner

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:

• - 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):

CODEBLOCK0

This creates:

• - INLINECODE7
• INLINECODE8
• INLINECODE9
• INLINECODE10
• INLINECODE11
• INLINECODE12
• INLINECODE13
• INLINECODE14
• INLINECODE15 (Google Calendar sync via gog)
• INLINECODE17 (calendar export without Google tooling)
• INLINECODE18

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)
• INLINECODE22 (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:

CODEBLOCK1

Or roll over unfinished tasks from the most recent week:

CODEBLOCK2

4) Validate before “publishing” anything

Run validation after edits (especially before calendar publish):

CODEBLOCK3

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:

CODEBLOCK4

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]]):

CODEBLOCK5

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:

CODEBLOCK6

This:

• - finds the most recent week in INLINECODE37
• creates the next week (week_start + 7 days)
• copies runbook blocks into the new week’s INLINECODE38
• carries over unfinished weekly_bits and INLINECODE40

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:

Requirements:

• - gog CLI installed + authenticated (steipete/gogcli)

Dry-run:

CODEBLOCK7

Apply:

CODEBLOCK8

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

Works without Google tooling.

CODEBLOCK9

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)
• INLINECODE49 (1–5 bullets)
• INLINECODE50 (1–5 bullets)
• INLINECODE51 (short paragraph)
• INLINECODE52 (1–2 sentences)

Quality gates

Before publishing/syncing:

1) Run validation:

CODEBLOCK10

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

References

• - File formats and schema: INLINECODE53
• Calendar publish & safety model: INLINECODE54

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.