Skip to content

leonprou/openstation

BranchesTags

Repository files navigation

Open Station

CI

A markdown-first, minimalistic and somewhere opinionated task management for coding AI agents.

Markdowns are first-class citizens — tasks, specs, workflows, and agents are all simple .md files. Think of it as an optimized work environment for your AI agents, glued by a thin CLI with agentic harnesses.

Why Open Station?

Coding agents can write code, but they have no structured way to receive tasks, report progress, or get their work verified. Most solutions add servers, databases, or dashboards. Open Station takes a different approach: a file-based convention with a defined lifecycle — no runtime, no dependencies, just markdown files with YAML frontmatter. A human (or designated reviewer) verifies every result before it ships, so agents propose and humans approve.

Since all outputs are .md artifacts, vim and Obsidian fit perfectly to view results, update tasks, and give agents instructions. Read the agent's findings and give feedback —manually or with the help of AI commands and agents.

Features

  • Zero runtime — no server, no database, no background process. Pure markdown files in your repo. Every competitor in this space requires a runtime; Open Station doesn't.
  • Defined agentic lifecycle — Agents know pick up ready tasks, execute work, produce artifacts, hand off for review and verification.
  • Convention-first — everything is markdown + YAML frontmatter, version-controlled alongside your code
  • Minimal, thus extensible — openstation init scaffolds into any project under .openstation/. Minimal footprint allows to add your own agentic harnesses and combine with any tooling.
  • Adaptive — agents, skills, and commands are all markdown files you own. Reshape them to fit your project. Open Station is a starting point, not a framework

Open Station manages its own development — every feature, bug fix, and research task goes through the same lifecycle that ships to users. See artifacts/tasks/ for real examples.

Install

Prerequisites

Dependency Version Purpose
Python 3.9+ Runs the CLI
git or curl any Downloads Open Station (git preferred)
Claude Code any Runs agents (openstation run)
Vim / Neovim any (Neovim preferred) View and edit tasks (openstation show --vim)
vim-markdown any YAML frontmatter folding and markdown rendering
Obsidian any Browse vault, query tasks, visual editing

One-liner

curl -fsSL https://raw.githubusercontent.com/leonprou/openstation/main/install.sh | bash

This does two things:

  1. Installs the CLI — downloads openstation to ~/.local/bin/
  2. Scaffolds the project — runs openstation init to create the .openstation/ vault, set up .claude/ symlinks, and inject the managed section into CLAUDE.md

To scaffold additional projects after the CLI is installed, run openstation init directly from the project directory.

Options:

Flag Description
--local PATH Copy from a local clone instead of downloading
--no-agents Skip installing example agent specs
--force Overwrite user-owned files during re-init
--dry-run Show what would be done without writing

Configure Markdown Tooling

vim-markdown — add to your Vim/Neovim config:

let g:vim_markdown_folding_disabled = 1    " disable folding (optional)
let g:vim_markdown_frontmatter = 1         " highlight YAML frontmatter
let g:vim_markdown_toml_frontmatter = 0
let g:vim_markdown_json_frontmatter = 0
let g:vim_markdown_no_extensions_in_markdown = 1

obsidian.nvim — add a workspace entry for each project using Open Station:

require("obsidian").setup({
  workspaces = {
    {
      name = "my-project",
      path = "~/workspace/my-project",
      strict = false,
      overrides = {
        notes_subdir = "openstation",
        new_notes_location = "notes_subdir",
        templates = {
          folder = ".openstation/templates",
        },
      },
    },
  },
})

Use the actively maintained fork obsidian-nvim/obsidian.nvim, not the original epwalsh/obsidian.nvim.

Obsidian app — open the project root as a vault (File → Open vault). Open Station stores a minimal .obsidian/ config with curated core plugins for task management. See artifacts/research/obsidian-nvim-vault-setup.md for detailed plugin recommendations.

Quick Start

One-time setup

openstation init

Creates the .openstation/ vault (directories, docs, commands, skills), installs agent templates, and sets up .claude/ symlinks so Claude Code discovers agents and commands. Safe to re-run — existing files are preserved.

Daily workflow

1. Create a task

/openstation.create Add input validation to the signup form

The agent drafts a complete task spec (requirements, verification, assignee) and sets it to ready.

2. Run the task

openstation run --task 0001-add-input-validation

The agent picks up the task, follows the manual, executes the work, and sets status: review when done.

3. Review the result

openstation show 0001 --vim # `openstation show 1` will work too

4. Verify and complete

/openstation.done 0001-add-input-validation

Vault Structure

artifacts/               — Artifact source-of-truth (artifacts-os layout)
  tasks/                 —   Task files
  agents/                —   Agent specs
  research/              —   Research outputs
  specs/                 —   Specifications & designs
  notes/                 —   Planning notes (roadmap, release plans)
  alerts/                —   Alert artifacts (triggers, activity logs)
  logs/                  —   Run logs

artifacts.yaml           — AOS vault marker + project identity + views (AOS-owned)
openstation.yaml         — Openstation config: hooks, run, defaults (OS-owned)

.openstation/            — Framework plumbing + runtime (hidden)
  docs/                  —   Project documentation
  skills/                —   Agent skills (not user-invocable)
  commands/              —   User-invocable slash commands
  templates/             —   Agent and settings templates
  hooks/                 —   Hook bundles (per-slug dirs)
  state.db               —   Runtime state (rebuildable cache)
  events/                —   Event log (YYYY-MM-DD.jsonl)

artifacts/ is the source of truth. .openstation/ is symlinked through .claude/ so Claude Code discovers commands and skills; .claude/agents/ symlinks to artifacts/agents/ for agent discovery.

Agents

Open Station ships with template agents. Each is a markdown file you own — edit or create new ones to fit your project. See .openstation/docs/agent.spec.md for the full spec format.

Agent Role
project-manager Creates tasks, assigns agents, reviews completed work
architect Designs systems, writes specs, sets technical standards
developer Turns specs into working code and tests
researcher Gathers and synthesizes information from code, docs, and the web
author Crafts agent specs, skills, commands, and prompts
technical-writer Maintains internal docs, README, and CLAUDE.md
devrel External-facing content — articles, tutorials, demos

Architecture

  You                      Open Station                    Agent
   │                            │                            │
   ├── /openstation.create ────►│                            │
   │   (draft + approve)        │                            │
   │                            ├── openstation run ────────►│
   │                            │                            ├── discover task
   │                            │                            ├── execute work
   │                            │                            ├── produce artifacts
   │                            │◄── status: review ─────────┤
   │                            │                            │
   ├── review (show --vim) ────►│                            │
   ├── /openstation.done ──────►│                            │

Under the hood: lifecycle.md defines the state machine, task.spec.md defines the file format, and each agent loads the execute skill to discover and run tasks.

Publishing

This repository is the artbook distro (Layout B). Consumers run:

artifacts init --openstation-compat \
  --distro https://github.com/leonprou/open-station -y

The artbook.yaml at the repo root defines four books:

Book Source Destination
agents .openstation/templates/agents/ artifacts/agents/ → .claude/agents/
skills .openstation/skills/ artifacts/skills/ → .openstation/skills/
commands .openstation/commands/ artifacts/commands/ → .openstation/commands/
hooks artifacts/hooks/ artifacts/hooks/ (ships inert; activate with artifacts hooks promote <slug>)

There is no separate openstation-defaults mirror repo. Every git push to this repo updates the distro automatically.

Commands

Slash commands wrap the CLI for common workflows. They're loaded by Claude Code from .openstation/commands/.

Discovery & inspection

Command Description
/openstation.list List active tasks with filters
/openstation.list.backlog List backlog tasks
/openstation.show Show full details of a single task
/openstation.check Check on an active or recent run

Creation

Command Description
/openstation.create Create a new task from a description
/openstation.create.bug Create a bug task
/openstation.create.research Create a research task
/openstation.create.spec Create a spec artifact
/openstation.create.note Create a planning note
/openstation.create.agent Create an agent spec
/openstation.create.alert Create an alert artifact

Lifecycle transitions

Command Description
/openstation.ready Promote backlog → ready
/openstation.suspend Suspend in-progress → ready/backlog
/openstation.verify Verify a task in review
/openstation.done Mark verified → done
/openstation.reject Reject a task with a reason
/openstation.fail Report a hard blocker on an in-progress task

Editing & execution

Command Description
/openstation.update Edit task frontmatter (not status)
/openstation.progress Append a timestamped progress entry
/openstation.run Launch an agent on a task
/openstation.init Initialize a project's vault

What a Task Looks Like

Every task is a single markdown file with YAML frontmatter:

---
kind: task
name: 0001-add-input-validation
status: ready
assignee: developer
owner: user
created: 2026-03-01
---

# Add Input Validation

## Requirements

Validate email and password fields on the signup form.
Reject empty submissions and show inline errors.

## Verification

- [ ] Empty email shows error
- [ ] Invalid email format rejected
- [ ] Password minimum length enforced

Create this file, dispatch an agent, and it picks up the work. When it's done, the owner verifies and marks it complete. That's the entire loop.

Documentation

Internal-facing guides for maintainers, contributors, and direct users live in .openstation/docs/.

Concepts & lifecycle

Doc Purpose
lifecycle.md Status transitions, ownership, verification rules
decomposition.md When to split a task; sub-task patterns

File formats

Doc Purpose
task.spec.md Task file format, fields, naming, body sections
agent.spec.md Agent spec format, frontmatter, skills
note.spec.md Planning note format
research.spec.md Research artifact format
spec.spec.md Specification artifact format

Storage & discovery

Doc Purpose
storage-query-layer.md Canonical paths, frontmatter associations, query patterns
artifacts.md Artifact kinds, registry, rendering
worktrees.md Running agents in git worktrees

CLI & configuration

Doc Purpose
cli.md Full CLI reference (flags, exit codes, resolution rules)
settings.md openstation.yaml schema
views.md Named views and field specs for list

Subsystems

Doc Purpose
hooks.md Lifecycle hook configuration
events.md Structured event log
sessions.md Run records, session management, stale detection
tmux-backend.md Tmux backend internals
alerts.md Alert artifacts and the heartbeat

License

MIT

About

Task management system for coding AI agents. Pure convention — markdown specs + skills, zero runtime dependencies.

Resources

Readme
Activity

Stars

21 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases 4

v0.21.0 Latest
Jun 23, 2026
+ 3 releases

Packages

 
 
 

Contributors

Languages