Docs
GitHubBlog

Search Documentation

Search for a page in the docs

Self-Describing Issues

An OpenAlice Issue is a Markdown file under .alice/issues/<id>.md, not a database row that only the UI understands.

---
title: Track NVDA supply-chain updates
status: todo
priority: medium
assignee: "@new"
when: { kind: cron, cron: "0 9 * * 1", timezone: America/New_York }
agent: codex
---

Review [[NVDA]] and its major suppliers every Monday morning.
Write `research/nvda-supply-chain.md`; push only material changes to Inbox.

The filename stem is the stable id. Everything below frontmatter is the canonical What passed to a scheduled agent. Comments live in the adjacent <id>.comments.json sidecar so an arbitrary agent rewrite cannot erase them. For an exact Session owner, a comment can be delivered asynchronously and its reply remains in the same durable Activity thread.

One object, two roles

  • Without when, the file is a board work item.
  • With when, the same file schedules a headless run.
  • done or canceled stops future fires without deleting the Issue.

There is no parallel schedule object, prompt field, or execution-owner field to keep in sync.

Ownership

  • @new recruits one Session on the first fire, then persists it as the exact owner.
  • @workspace recruits a new Session for every fire.
  • An exact @resumeId continues one responsible Session.
  • @human and @unassigned are valid for unscheduled work.
  • Agent-facing @me is resolved to the caller's concrete signature before storage.

This makes the file answer both “what should happen?” and “who is responsible?” without confusing the creator with the current owner.

Why Markdown

  • Agents can inspect and edit the work with normal repo tools.
  • Humans can review changes in git diffs.
  • [[wikilinks]] connect Issues to tracked entities and related work.
  • The same artifact drives the terminal, Web UI, and headless scanner.
  • Timezone and ownership survive restarts because they live with the task.

CLI and UI

alice-workspace issue create --title "Review CPI release" --what "..." --assignee me
alice-workspace issue list
alice-workspace issue update --id <id> --status in_progress
alice-workspace issue comment --id <id> --text "Waiting for the revision."

The Issue Board renders the same files, derives automation health, keeps change/conversation Activity separate from the operational Runs ledger, and exposes attributable follow-up. Failed or interrupted scheduled work can be retried without shifting its cadence.

Next Steps