/tasks -- Personal Task Tracker

Track personal tasks across projects with source linking, history, and automatic carry-forward.

Design principles:

• Distributed per-folder _tasks.yaml files (like _insights.yaml)
• Root file holds projects registry + cross-project tasks
• Per-folder discovery: closest _tasks.yaml for local operations
• --all flag aggregates all files across vault
• Private by default (user-only unless explicitly shared)
• Source linking back to meetings/decisions
• History preservation for audit trail

Architecture

Distributed File Layout (v2)

~/Documents/Vault/
  _tasks.yaml                              # Root: projects registry + cross-project tasks
  _tasks-history.md                        # Completed tasks log (append-only)
  _projects/acme/_tasks.yaml               # Org-level tasks
  _projects/acme/ops/management/_tasks.yaml     # Domain tasks
  _projects/acme/ops/marketing/_tasks.yaml      # Domain tasks
  _projects/acme/projects/mobile-v3/_tasks.yaml # Project tasks
  _projects/bravo/_tasks.yaml              # Org-level
  _projects/bravo/side-project/_tasks.yaml      # Project tasks
  _private/_tasks.yaml                     # Personal tasks
  _contacts/david-ekberg_consulting/_tasks.yaml # Contact tasks

Placement Rule

_tasks.yaml can exist at any level where a CLAUDE.md or CHANGELOG.md exists.

ID Namespacing

IDs are unique per file. Visualisation displays as context#id (e.g., mobile-v3#3). Skills always operate on one file, so local IDs suffice.

Data Model

Per-file schema (v2)

version: 2
last_updated: 260304
context: "acme-mobile-v3"       # Folder identity (like _insights.yaml)
scope: project                   # root | org | project | personal

tasks:
  - id: 1
    task: "Fix database connection issue"
    tags: [backend]
    source:
      type: meeting              # the SHAPE, from task_source_types in the contract
      channel: email             # OPTIONAL (CR-152): how it arrived. Free text, never checked
      file: "meetings/260303-daily-standup.md"
    priority: P0
    due: 260307
    created: 260303
    status: pending              # pending | in_progress | blocked | completed | cancelled
    closed: null                 # optional (CR-127): the day status became completed or cancelled
    blocked_reason: null
    verksamhet: null             # optional (CR-135): a venture the vault declares; absent is valid
    projekt: null                # optional (CR-135): a portfolio row, matched by prefix
    private: false
    recurring: false             # optional (CR-163): a standing chore, no date by design
    notes:
      - date: 260303
        note: "Identified"

next_id: 2

Key fields:

• No project: field per task (implicit from folder context)
• context + scope fields at file level (mirrors _insights.yaml)
• version: 2 distinguishes from v1
• kind (optional, CR-123): a task's kind, from the folder profile's task_kinds. The podcast profile declares episode_idea | guest_lead | housekeeping | publication, because its ledger is the host's editorial backlog: announcements in a summary's Follow-up section (a guest's own plans, calls to action to listeners) never become tasks. A profile that declares no kinds writes no kind.
• verksamhet, projekt, objekttyp (optional, CR-135): context: used to carry venture, project, activity type and subject in one free-text slot. The three fields split it. verksamhet is one of the ventures the vault declares in _config/task-attributes.yaml, or absent: a follow-up or a watch belongs to no business, so an absent venture is a valid answer and never a finding (keep a venture, deliberately none and undecided apart when migrating). projekt must match a row of the portfolio table in _INDEX-projekt.md, by prefix (goa matches Goa 2026). objekttyp is written only when the entry is not an Uppgift (Idé, Projekt, Löpande ansvar, KPI, Länk, Note/logg): such an entry is re-marked and moved, never deleted. context: narrows to the subject line. All three are validated where the entry is written: before appending, run python3 task_attributes.py --validate '<json>' --root <folder> and do not write the entry if it exits 1 (it prints [REFUSED] lines; ask for a corrected value instead). The check is a script, not an instruction to remember: any writer (the add flow, transcript task extraction, an inbox importer) calls it. Only the author knows the venture then; /ops check reports the rest and never rewrites.
• The enums are checked (CR-122): /ops check reports a missing task (often written as title), a status, priority, source.type, scope or kind outside the declared values. Report only.

Root file keeps

• projects: registry (vault paths, shared_view settings)
• Cross-project tasks (rare)
• Reference to _tasks-history.md

_tasks-history.md (Completed Tasks Log)

# Task History

Completed tasks archive. Append-only log.

---

## 2026-02

### 260220

- [x] **acme#47** War room mobile app
  - Context: acme-mobile-v3
  - Source: [260219-war-room.md](path/to/file.md)
  - Created: 260219 | Completed: 260220
  - Duration: 1 day

File Discovery

When a /tasks command runs, find the target _tasks.yaml:

1. Look for _tasks.yaml in current working directory
2. Walk up parent directories toward vault root
3. Closest match wins for local operations (show, add, done)
4. --all flag scans all _tasks.yaml files across the vault

New file creation

If no _tasks.yaml exists in the current folder and a task is being added:

1. Create with v2 schema
2. Derive context from folder name
3. Derive scope from path depth (root/org/project/personal)
4. Start with next_id: 1

Commands

Renamed in v1.79.0 (CR-089); /tasks show was removed in v1.81.0. An old name is not recognised: say that it is now /tasks list, and do not run it.

/tasks list (the default; was show)

Show current active tasks from the local _tasks.yaml.

Default: Current folder's _tasks.yaml (or nearest ancestor).

/tasks list              # Local file
/tasks list --all        # Aggregate all _tasks.yaml files
/tasks list P1           # Filter by priority
/tasks list #board       # Filter by tag
/tasks list due:this-week  # Filter by due date

Output format:

# Active Tasks -- acme-mobile-v3 (12)

### P0 - Critical
1. [ ] Fix database connection issue (due: 260307)
   Source: [260303-daily-standup.md](meetings/260303-daily-standup.md)

### P1 - This Week
2. [ ] Release v1.1.62 (due: today)
3. [~] Handle Android DND -- IN PROGRESS

### P2 - Important
4. [ ] Include end-user changelog in build posts

---
Last updated: 260304

/tasks add "description"

Add a new task to the local _tasks.yaml.

Flow:

> /tasks add "Review contract terms"

Adding task to: acme-mobile-v3/_tasks.yaml

Priority? [P2] P0 P1 P2 P3
> P1

Due date? [none] today tomorrow YYMMDD "before X"
> 260310

Tags? (comma-separated)
> contracts, legal

Source? (meeting file or "manual")
> manual

Venture? [none] <declared ventures>     # optional; run --validate before writing, refuse on exit 1 (CR-135)
> none

Private? [no] yes
> no

Task #15 created:
- Review contract terms
- Context: acme-mobile-v3 | Priority: P1 | Due: 260310

/tasks done <id> or /tasks done <id> <id> ...

Mark task(s) as completed in the local _tasks.yaml.

1. Set status: completed and closed: YYMMDD (CR-127: the same edit; a cancelled task gets closed: too. completed: is a legacy alias, accepted on read and never written; rows with an unknown closing day stay unknown, no backfill)
2. Append entry to root _tasks-history.md
3. Report remaining active task count

> /tasks done 3

Completing task #3: "Handle Android DND" (acme-mobile-v3)

Task #3 marked complete.
- Duration: 4 days (created 260301)
- Logged to _tasks-history.md

Remaining active tasks: 11

/tasks cancel <id> or /tasks cancel <id> <id> ...

Mark task(s) as cancelled in the local _tasks.yaml (CR-127: the second finished state has its own writer).

1. Set status: cancelled and closed: YYMMDD in the same edit (never completed:)
2. Append entry to root _tasks-history.md, marked cancelled
3. Report remaining active task count

/tasks import <file.md>

Import tasks from a meeting summary. Target = folder where source file lives.

> /tasks import meetings/260303-daily-standup.md

Scanning for action items in: 260303-daily-standup.md

Found 4 action items:
1. Fix database connection issue (Alex)
2. Complete store descriptions (Grace)
3. Create individual accounts (Sam)
4. Investigate CLI enforcement gap (Sam)

Import all? [yes] no select
> yes

Importing 4 tasks to acme-mobile-v3/_tasks.yaml...
Tasks #15-18 created.

/tasks weekly

Generate weekly review. Aggregates all _tasks.yaml files.

> /tasks weekly

# Weekly Review: 260224-260302

## Completed This Week (8)
- acme#12 Kickoff brand meeting
- acme-mobile-v3#45 Release v1.1.60
- ...

## Carried Forward (5)
- acme#32 Offer team lead 1-on-1 - 12 days old
- ...

## Blocked (1)
- side-project#3 Integrate content - waiting on partner

## New This Week (7)
- acme-mobile-v3#15-18 from standup
- ...

## Stats
- Completed: 8
- Added: 7
- Net: -1 (backlog shrinking)

/tasks archive

Archive completed tasks older than 30 days from history.

/tasks help

Print the commands above, one line each, and where the ledger for the current folder resolves to (workflows.task_ledger).

Integration with Other Skills

/transcript (Step 4: task import)

When /transcript finds action items, import to the local _tasks.yaml in the contact/project folder where the transcript lives (not vault root).

/ops (Step 7 + Step 9)

• Step 7: Write _tasks.yaml in the project/domain folder (replaces task-priority-matrix.md)
• Step 9: Task import targets local _tasks.yaml

Privacy Model

• Tasks with private: true: only visible in personal views
• Tasks with private: false: can appear in shared dashboards
• Default for meeting imports: private: false
• Default for manual adds: private: true
• Sensitive tags (#costs, #personal, #confidential): private: true

Convention Files

File Format Details

YAML Schema (v2)

type: object
required: [version, context, scope, tasks, next_id]
properties:
  version:
    type: integer
    const: 2
  last_updated:
    type: [integer, string]  # YYMMDD
  context:
    type: string
  scope:
    enum: [root, org, project, personal]
  projects:
    type: object  # Only in root file
  tasks:
    type: array
    items:
      type: object
      required: [id, task, priority, created, status]
      properties:
        id: { type: integer }
        task: { type: string }
        tags: { type: array, items: { type: string } }
        source:
          type: object
          properties:
            type: { enum: [meeting, decision, manual, imported, content, correspondence, analysis] }
            channel: { type: string }      # open by design (CR-152)
            file: { type: string }
            section: { type: string }
        priority: { enum: [P0, P1, P2, P3] }

source.type is the shape; source.channel is how it arrived (CR-152)

Two questions, and the field used to ask only the first. type says what kind of thing the task came from -- a meeting, a decision, a two-way thread, material received, something the owner derived from reading their own data. channel says how it reached them -- email, chat, sms, teams, voice-memo, file, call.

A person filing a task knows the channel before they know the shape, which is why one vault accumulated twenty-two undeclared words in type: email and mail held 105 rows while correspondence, the declared word for the same material, held 6. Those were not wrong answers -- they were right answers to the question the field was not asking.

Legacy spellings are read, never written and never rewritten. task_source_aliases in the contract maps each old word to its {type, channel} pair. A row that says type: email keeps saying it; the reader resolves it, and /ops check reports the ledger's habit in one advisory line rather than one finding per row. Backfilling a guess over 281 rows would be worse than the gap and is the re-dump CR-122 forbids -- the same call CR-127 made one field over.

When you write a new row: use the canonical pair. type: correspondence, channel: email -- not type: email.

    due: { type: [string, integer, "null"] }
    created: { type: [string, integer] }
    status: { enum: [pending, in_progress, blocked, completed, cancelled] }
    blocked_reason: { type: [string, "null"] }
    closed: { type: [string, integer, "null"] }      # CR-127: day it became completed or cancelled
    completed: { type: [string, integer, "null"] }   # legacy alias of closed (read only)
    private: { type: boolean }
    recurring: { type: boolean }  # optional (CR-163); a standing chore. Absent means false
    kind: { type: string }   # optional (CR-123); legal values = the profile's task_kinds
    verksamhet: { type: [string, "null"] }  # optional (CR-135); a declared venture, or absent
    projekt: { type: [string, "null"] }     # optional (CR-135); matches a portfolio row by prefix
    objekttyp: { type: string }             # optional (CR-135); only when not an Uppgift
    notes:
      type: array
      items:
        type: object
        properties:
          date: { type: [string, integer] }
          note: { type: string }

next_id: type: integer

---

## Implementation Notes

### Skill Location

~/.claude/skills/tasks/ # Symlinked ~/repos/core-skills/skills/tasks/ # Actual location

### Dependencies

- None (standalone skill)
- Optional integration with: transcript, ops

### Language

- Skill prompts: English
- Task content: Preserves original language (Swedish or English)
- Swedish character enforcement when task content is Swedish

---

## Handoff snapshots are not tasks (CR-033)

A frozen snapshot in `.handoff/` is context, not intent. It never generates a task, and `/tasks` never scans `.handoff/`.

If a snapshot's subject should become work, the **user** decides that and the task is written normally — stating the subject in its own words, never linking the snapshot (snapshots are not referenced from living documents).

## Future Enhancements

1. **Recurring tasks** -- `recur: weekly` for repeating tasks
2. **Subtasks** -- Hierarchical task breakdown
3. **Time tracking** -- Optional time spent logging
4. **Delegation** -- Assign tasks to others
5. **Calendar sync** -- Export due dates to calendar