commitment-setup

name	commitment-setup
version	0.3.0
description	One-time setup for the commitments tracking system. Creates the workspace structure and schema docs, installs triage and digest missions, then excludes itself once `projects/commitments/README.md` exists.
activation	{"setup_marker":"projects/commitments/README.md","keywords":["setup commitments","install commitments","enable commitments","commitment system","initialize commitments","commitment tracking"],"patterns":["(?i)set ?up.*(commitment|obligation|tracking)","(?i)install.*(commitment|obligation)","(?i)enable.*(commitment|tracking)"],"tags":["commitments","setup","personal-assistant"],"max_context_tokens":2000}
requires	{"skills":["commitment-triage","commitment-digest"]}

Commitment System Setup

You are installing the commitments tracking system. This creates a workspace structure for tracking obligations, signals, decisions, and parked ideas, plus two missions for automated triage and digest delivery.

Step 1: Check existing setup

Call memory_read(path="projects/commitments/README.md"). If it exists, tell the user: "The commitments system is already set up. Want me to reinstall from scratch?" Stop unless they confirm.

Step 2: Gather user context

The user's timezone is provided by the channel automatically — do not ask for it. Ask only:

1. Which channel should I send digests to? (default: the current channel)

Step 3: Write the schema README

Call memory_write with target="projects/commitments/README.md", append=false, and this content:

# Commitments System

Tracks obligations, decisions, and ideas via structured markdown files.

## Directory Layout

- `open/` — Active commitments (one file each)
- `resolved/` — Completed commitments (archived)
- `signals/pending/` — Raw extracted signals awaiting triage
- `signals/expired/` — Signals that were not promoted in time
- `decisions/` — Captured decisions with rationale
- `parked-ideas/` — Ideas saved for later consideration

## Signal Schema (signals/pending/<slug>.md)

    ---
    type: signal
    source_channel: <channel name>
    source_message: "<brief quote or paraphrase>"
    detected_at: <YYYY-MM-DD>
    immediacy: realtime | prompt | batch
    expires_at: <YYYY-MM-DD> | null
    confidence: high | medium | low
    obligation_type: reply | deliver | attend | review | decide | follow-up | informational
    mentions: [<names>]
    destination: null | commitment | parked_idea | intelligence | dismissed
    promoted_to: null | <commitment filename>
    ---
    <Human-readable description of what was detected.>

### Immediacy levels
- realtime: push-notify immediately (production incident, market alert, security)
- prompt: surface within the hour (urgent DM, trending topic)
- batch: next digest is fine (meeting action item, report to read)

### Signal destinations
- commitment: actionable, tracked, has a resolution path
- parked_idea: interesting, not committed, revisit later
- intelligence: no action needed, but informs future decisions → write a MemoryDoc via memory_write
- dismissed: not relevant

## Commitment Schema (open/<slug>.md or resolved/<slug>.md)

    ---
    type: commitment
    status: open | in_progress | blocked | waiting | resolved
    urgency: critical | high | medium | low
    due: <YYYY-MM-DD> | null
    created_at: <YYYY-MM-DD>
    stale_after: <YYYY-MM-DD> | null
    owner: user | agent
    delegated_to: null | <person or team>
    resolution_path: agent_can_handle | needs_reply | needs_decision | note_only
    decision_type: mechanical | taste | challenge
    effort_human: <estimate> | null
    effort_assisted: <estimate> | null
    source_signal: <relative path> | null
    resolved_by: null | agent | user | delegate | expired
    tags: [<freeform>]
    ---
    # <Title>
    <Description of the obligation.>

    ## Resolution path
    - [ ] Step 1
    - [ ] Step 2

    ## Progress
    <Updates appended over time.>

### Resolution path types
- agent_can_handle: the agent can do this autonomously (review PR, draft doc, research)
- needs_reply: user must send a response to someone
- needs_decision: user must choose between options
- note_only: informational, no action needed but tracked

### Decision types (when to ask the user)
- mechanical: auto-act silently (expire stale signal, update status, dismiss noise). Report in digest as "auto-handled."
- taste: auto-act but surface for awareness ("I auto-dismissed 3 FYI signals, auto-resolved 2 completed items"). User can override.
- challenge: always ask the user before acting (architecture decisions, sending messages, spending money, irreversible actions).

### Effort estimates
When known, include dual estimates:
- effort_human: time without AI assistance (e.g. "2h", "3d")
- effort_assisted: time with AI assistance (e.g. "15min", "2h")
This reframes decisions — when AI makes completeness cheap, there is no excuse for shortcuts.

### Autonomous resolution
When a commitment has resolution_path=agent_can_handle and decision_type=mechanical or taste:
1. Agent handles it and reports in the next digest
When decision_type=challenge:
1. Agent asks for explicit approval before acting
2. On approval, spawns a mission for complex work or handles inline
3. Status transitions to in_progress, then resolved with resolved_by=agent

## Decision Schema (decisions/<date>-<slug>.md)

    ---
    type: decision
    decided_at: <YYYY-MM-DD>
    context: <topic slug>
    participants: [<names>]
    confidence: high | medium | low
    reversible: true | false
    outcome: null | <brief outcome description>
    outcome_positive: null | true | false
    tags: [<freeform>]
    ---
    # <What was decided>

    ## Context
    <Why this decision was needed.>

    ## Options considered
    1. **Option A** — pros/cons
    2. **Option B** — pros/cons

    ## Rationale
    <Why this option was chosen.>

    ## Outcome
    <Filled in later: what happened as a result of this decision.>

## Parked Idea Schema (parked-ideas/<slug>.md)

    ---
    type: parked-idea
    parked_at: <YYYY-MM-DD>
    source: conversation | triage | research
    relevance: high | medium | low
    tags: [<freeform>]
    ---
    # <Idea title>
    <Description and why it is interesting.>

    ## Activation trigger
    <What would make this worth pursuing.>

## Conventions

- Filenames use lowercase kebab-case: `review-sarah-deck.md`
- Dates are ISO-8601: `YYYY-MM-DD`
- Moving a commitment from open/ to resolved/: write the updated file to resolved/, then overwrite the open/ file with empty content
- One file per entity — never batch multiple commitments into one file

## Trust calibration

Start conservative:
- All signals surfaced in digest, none auto-promoted to commitments
- All agent_can_handle commitments require explicit user approval before dispatch
- Realtime immediacy disabled initially (everything batched)
- Track user feedback patterns in projects/commitments/calibration.md to gradually increase autonomy

Step 4: Create directory placeholders

Write a one-line README in each subdirectory to establish the structure:

• memory_write(target="projects/commitments/open/README.md", content="Active commitments.", append=false)
• memory_write(target="projects/commitments/resolved/README.md", content="Completed commitments archive.", append=false)
• memory_write(target="projects/commitments/signals/pending/README.md", content="Signals awaiting triage.", append=false)
• memory_write(target="projects/commitments/signals/expired/README.md", content="Expired signals.", append=false)
• memory_write(target="projects/commitments/decisions/README.md", content="Captured decisions.", append=false)
• memory_write(target="projects/commitments/parked-ideas/README.md", content="Ideas for later.", append=false)

Step 5: Check for existing missions

Call mission_list. If missions named commitment-triage or commitment-digest already exist, skip creating them.

Step 6: Create the triage mission

mission_create(
  name: "commitment-triage",
  goal: "Review pending signals, expire stale ones, check for overdue commitments. Read projects/commitments/README.md for the schema. Then: (1) memory_tree('projects/commitments/signals/pending/', depth=1) to list pending signals. For any signal past its expires_at or older than 48 hours with destination=null, move it to signals/expired/. (2) memory_tree('projects/commitments/open/', depth=1) to list open commitments. For each, memory_read and check: if due date is past, flag as overdue; if status=waiting and not updated in 3+ days, flag for follow-up; if stale_after is past, re-surface with escalated urgency. (3) For signals with immediacy=realtime, broadcast immediately via message tool — do not wait for digest. (4) Append triage summary to projects/commitments/triage-log.md. (5) If any items are overdue or need follow-up, send a message alerting the user.",
  cadence: "0 9,18 * * *"
)

Step 7: Create the digest mission

mission_create(
  name: "commitment-digest",
  goal: "Compose a morning commitments digest. Read projects/commitments/README.md for the schema. (1) memory_tree('projects/commitments/open/', depth=1) and memory_read each file. Extract status, urgency, due, delegated_to, resolution_path from frontmatter. (2) memory_tree('projects/commitments/signals/pending/', depth=1) to count pending signals. (3) Compose digest grouped by: Overdue/Critical first, then Due This Week, then Waiting/Delegated (with follow-up status), then Open (no deadline). For agent_can_handle items, note 'I can handle this — want me to proceed?' (4) End with: pending signal count and 'Did I miss anything? Tell me if I overlooked an obligation.' (5) Send via message tool.",
  cadence: "0 8 * * 1-5"
)

Step 8: Confirm

Tell the user:

Commitments system is ready. Here is what I set up:

• Workspace structure under projects/commitments/ with schema docs
• Triage mission runs twice daily (9am and 6pm) — expires stale signals, flags overdue items, broadcasts realtime alerts
• Digest mission runs weekday mornings at 8am — summarizes open commitments with resolution suggestions

I will automatically track obligations from our conversations. Say "show commitments" anytime to see your current status. You can adjust the schedule by saying something like "give me digests at 7am instead."

I start conservative — I'll surface everything but won't act without your approval. As you confirm or dismiss my suggestions, I'll learn your preferences.