Docs
GitHubBlog

Search Documentation

Search for a page in the docs

Self-Describing Issues

OpenAlice issues are not database rows first. Inside a workspace, an issue is a Markdown file under .alice/issues/<id>.md.

That file is self-describing: it carries status, priority, schedule metadata, human comments, agent context, and links to tracked entities. The Web UI reads it as an Issue Board card; the launcher reads it as schedule input; the agent reads it as local task context.

File shape

---
id: issue_nvda_supply_chain
title: Track NVDA supply chain updates
status: open
priority: medium
when: "0 9 * * 1"
---

Watch [[NVDA]] and its major supply-chain names every Monday morning.

## Notes

- Check earnings-calendar changes.
- Push a short report to the Inbox.

The exact frontmatter can evolve, but the invariant is stable: the issue should be understandable as a file, not only as UI state.

Why Markdown

  • Agents can inspect and edit the issue with normal repo tools.
  • Humans can review changes in git diffs.
  • Scheduled work has a source file the agent can cite and update.
  • Links such as [[NVDA]] connect issues to tracked entities and backlinks.
  • The same artifact works in the terminal, the Web UI, and headless runs.

Scheduling

Scheduling is issue-shaped. Add a when field and a task body, and the scanner can launch a headless workspace run from the same file.

There is no separate cron object to keep in sync with the work item. The scheduled run reads the issue, executes in the workspace repo, and can update the issue or push results to the Inbox.

CLI and UI access

Agents usually create or update issues through alice-workspace issue helpers, but the file is still the source of truth.

alice-workspace issue create --title "Review CPI release"
alice-workspace issue list
alice-workspace issue update issue_123 --status in_progress

The Web UI's Issue Board renders those same files as cards, with filters for status and priority. Comments and status changes are file changes, so the workspace git history remains meaningful.

Cross-links

Self-describing issues participate in the same workspace graph as tracked entities, Inbox entries, and run records:

  • [[name]] references link issues to tracked entities.
  • Runs launched from an issue keep the issue id as provenance.
  • Inbox entries can point back to the workspace and issue that produced them.
  • Peer workspaces can resolve related files through explicit workspace ids.

Next Steps