---
name: calendar
description: Display an agent's weekly plan as a calendar grid with day columns and hour rows
trigger: aweek calendar, weekly calendar, plan calendar, show calendar, agent calendar
---

# aweek:calendar

Display an agent's weekly plan as a calendar grid with day columns and hour rows. Tasks are numbered so users can ask about any task by number.

## Instructions

You MUST follow this exact workflow when this skill is invoked.

### Step 1: Select an Agent

List all available agents:

```bash
aweek exec calendar listAgentsForCalendar
```

The call returns a JSON array of `{ id, name, role }` records. Treat an
empty array as the no-agents case.

- If no agents exist, inform the user: "No agents found. Use /aweek:hire to create one first." and stop.
- If only one agent exists, auto-select it.
- If multiple agents exist, ask the user to pick one using AskUserQuestion.

### Step 2: Resolve the Week (optional)

If the user **didn't** mention a specific week, skip this step and go to Step 3 —
the renderer defaults to the agent's latest approved plan.

If the user mentioned a week (e.g. *"week 17"*, *"the week of April 20"*, *"next
week"*, *"2026-W14"*), pass that string verbatim to `loadAndRenderGrid` as a
`week` field — it accepts every shape below — or pre-resolve it to the
canonical `YYYY-Www` so you can confirm the choice in your reply:

```bash
echo '{ "input": "next" }' | aweek exec calendar resolveWeekKey --input-json -
```

Accepted shapes:

| Input | Meaning |
|-------|---------|
| `2026-W17` | Canonical ISO week (case-insensitive `W`) |
| `2026-04-20` | Any ISO date — derives the ISO week containing it |
| `17` or `W17` | Bare week number — uses the current ISO year (in the project time zone) |
| `current`, `this`, `now` | Current week |
| `next` | Next ISO week |
| `prev`, `previous`, `last` | Previous ISO week |

Invalid input throws — the skill should surface the error message and re-ask.

### Step 3: Render the Calendar Grid

The default output is a **GitHub-flavored markdown table** (`format: "markdown"`).
Claude Code's terminal UI re-flows pipe tables to the available width, so the
calendar expands / contracts with the window instead of sitting in a fixed
120-column box. Pass `format: "box"` only when the host cannot render markdown
tables (e.g. raw log tails) — the Unicode box-drawing grid still works but its
columns are fixed.

Run the grid renderer to get the calendar text and task index. Add a `week`
field when targeting a specific week (omit for the latest approved plan):

```bash
echo '{
  "agentId": "<AGENT_ID>",
  "week": "<WEEK_OR_DATE_OR_ALIAS>",
  "opts": {
    "format": "markdown",
    "startHour": 9,
    "endHour": 18,
    "showWeekend": false,
    "spread": "spread"
  }
}' | aweek exec calendar loadAndRenderGrid --input-json -
```

The response JSON contains `success`, `output` (the rendered grid text),
`taskIndex` (the numbered task list), and `errors` when `success === false`.
When the requested week has no plan on disk, `errors` lists every available
week so you can prompt the user to pick one of them.

**IMPORTANT — Not collapsed display:** After running the command, you MUST
output the calendar text as direct text in your response — for `format: "markdown"`,
paste the markdown table itself (no surrounding code block, so the UI renders
it as a table); for `format: "box"`, wrap `result.output` in a fenced code
block so the Unicode borders don't reflow. Do NOT just reference the bash
output — copy `result.output` and display it yourself so it appears expanded,
not collapsed inside a bash result.

### Step 4: Stop (no follow-up question)

The rendered grid already ends with `Select a task number (1-N) to see details.`
— that is the only prompt the user needs. Do **not** emit an `AskUserQuestion`,
a "What would you like to do?" menu, an adjust-view picker, or any other
interactive step after displaying the calendar. Just end your turn.

Keep `result.taskIndex` in mind for the follow-up turn: if the user later
types a task number (or asks about a specific task), look it up there and
respond with its details. Do not volunteer that lookup until asked.

## Render Options

| Option | Default | Description |
|--------|---------|-------------|
| `format` | `markdown` | `markdown` (responsive pipe table — default) or `box` (fixed-width Unicode grid) |
| `startHour` | 9 | First hour row (0-23) |
| `endHour` | 18 | Last hour row exclusive (1-24) |
| `terminalWidth` | — | **Box format only.** Available terminal columns; auto-fits `cellWidth` when set |
| `cellWidth` | auto | **Box format only.** Explicit per-day column width. Overrides `terminalWidth` |
| `showWeekend` | false | Include Saturday and Sunday columns |
| `spread` | `pack` | Distribution: `pack` (fill days) or `spread` (round-robin) |

## How It Works

- Tasks are numbered in column-major order (top-to-bottom per day, then the next day) for selection
- **Review slots** (daily-review and weekly-review) receive selection numbers identical to regular work tasks — you can select them by number and apply status transitions (`pending`, `in-progress`, `completed`, `failed`, `skipped`) exactly the same way
- Each hour row is as tall as its fullest cell. Every task gets its own block of wrapped lines inside the cell; empty cells pad with blanks to line up.
- Each task displays up to **30 visible characters** (`<icon> <num>. <description>`). Anything beyond collapses with a trailing `…`. Those 30 chars wrap across cell lines based on column width — narrow columns just use more rows.
- Half-hour tasks (e.g. `runAt` at `HH:30`) bucket into the same `HH:00` cell as `HH:00` tasks, so they don't disappear from the view.
- Status icons show progress: ○ pending, ► in-progress, ✓ completed, ✗ failed; ◆ marks review slots (also selectable by number)
- The calendar is displayed as direct text (not bash output) so it's always visible
- **Time zone:** day columns and hour rows reflect the user's configured time zone in `.aweek/config.json` (`timeZone`). `runAt` is stored as an absolute UTC ISO string, projected into that zone for display. Update the config file to switch zones; no per-agent override yet.

## Related Skills

- `/aweek:plan` — Edit weekly plans (add/remove tasks, adjust goals, approve/reject)
- `/aweek:summary` — Dashboard view across all agents
- `/aweek:hire` — Create a new agent with identity, goals, and initial plan

## Data Directory

Agents are stored in `.aweek/agents/<agent-id>.json` relative to the project root.