pacificstudio/openase/openase-platform

OpenASE Platform Operations

Prefer the wrapper injected into the workspace:

./.openase/bin/openase ticket list --status-name Todo

This wrapper is the openase binary with the current workspace's OpenASE platform context already attached. Use it first. Do not hand-roll URLs, guess endpoints, bypass the platform by writing the database directly, or fake platform state.

Core Concepts

Use these distinctions before you choose commands or explain the platform to a user:

• workflow: the execution policy for a role. A workflow decides which agent

handles work, which ticket statuses it may pick up, which statuses count as finished, which harness instructions and skills are active, and which platform scopes the runtime may use.

• updates: curated project progress threads for humans. Use these for

milestone checkpoints, risk reporting, stakeholder communication, and discussion. Updates are intentionally higher-signal than raw runtime logs.

• activity: the append-only project event stream. It records what actually

happened across tickets, agents, workflows, and platform writes for traceability, debugging, and auditability.

One short mental model:

• workflows decide how work runs
• activity records what happened
• updates summarize what matters

Keep the boundaries clear:

• Do not describe workflow as "just a prompt"; it is prompt + routing +

policy + execution limits.

• Do not treat updates as a synonym for activity; updates are curated,

while activity is the raw event timeline.

• Do not treat activity as a task board; it explains history, not desired

future state.

What This Skill Is For

OpenASE is not a small helper that just runs commands. It is an issue-driven automated software engineering platform. Per the PRD, it is responsible for at least:

• Project control: descriptions, statuses, repos, workflows, skills, and

scheduled jobs

• Ticket control: lifecycle, status transitions, comment primitives,

usage/cost, and external links

• Execution control: agents, providers, machines, runtimes, and orchestration

loops

• Controlled autonomy: agents can operate the platform within granted scope

and close the loop from claim to execution to platform writeback to follow-up tickets

• Auditability: every platform write goes through the API / ActivityEvent /

timeline and stays attributable

For agents, the core purpose of openase is not just inspection. It is reading and writing real control-plane state inside platform-enforced boundaries. The tickets you create, project descriptions you update, repos you register, and comments you append all affect later scheduling, UI state, audit trails, and other agents' context.

Treat openase as the control-plane API for the current engineering project.

• The code repository is only a workspace, not the task system.
• Tickets, projects, workflows, skills, and machines in OpenASE are the real

control-plane entities.

• When you need to change platform state, prefer the openase CLI. Do not try

to express platform state indirectly by editing local files.

• Read before you write: inspect the current state first, then make the

smallest necessary change.

• If you exceed scope, the platform returns 403. That usually means the

current harness did not grant the required platform_access.

Runtime Contract First

The runtime injects a capability contract that tells you which principal kind, scopes, and environment variables are actually available in this session. Treat that runtime contract as the source of truth.

Common environment variables include:

• OPENASE_API_URL: OpenASE API base URL
• OPENASE_AGENT_TOKEN: current agent token
• OPENASE_PROJECT_ID: current project UUID
• OPENASE_TICKET_ID: current ticket UUID; only present in ticket runtime or

ticket-focused Project AI

• OPENASE_CONVERSATION_ID: current project conversation UUID; available in

Project AI conversations

• OPENASE_PRINCIPAL_KIND: current principal kind, such as ticket_agent or

project_conversation

• OPENASE_AGENT_SCOPES: current token scopes, comma-separated

Common platform subcommands auto-fill context in this order:

• project scope: --project-id -> OPENASE_PROJECT_ID
• ticket scope: positional [ticket-id] -> --ticket-id ->

OPENASE_TICKET_ID

• API URL: --api-url -> OPENASE_API_URL
• token: --token -> OPENASE_AGENT_TOKEN

Important limits:

• Most ID parameters require UUIDs and do not accept human-readable ticket

identifiers such as ASE-42.

• Output defaults to JSON and can be filtered with --json, --jq, or

--template.

• When platform calls fail, the CLI prints the HTTP method, path, status, and

API error code directly, so you do not need to guess.

• Tokens are short-lived and scope-bound; not every workflow can modify

projects, repos, or scheduled jobs.

• Shared wrapper flags accept both kebab-case and snake_case, such as

--status-name / --status_name and --body-file / --body_file.

Principal-Specific Constraints

Check OPENASE_PRINCIPAL_KIND before assuming a route is available.

When the principal is ticket_agent:

• Treat this as the current ticket runtime.
• Current-ticket routes are limited to the ticket identified by

OPENASE_TICKET_ID.

• Project-level writes still depend on the scopes listed above.

When the principal is project_conversation:

• Treat this as a project-scoped conversation runtime, not a ticket runtime.
• Use the canonical ticket mutation routes when tickets.update is granted;

this includes ticket comment operations, and project scope still comes from the token claims even though the suffix stays aligned with the human control plane.

• Do not assume ticket usage-report endpoints are available.
• Ticket-runtime-only routes can reject this principal kind even when

OPENASE_TICKET_ID is present.

• OPENASE_CONVERSATION_ID is often the stable runtime identity you should

use when inspecting the current Project AI session.

If you are unsure which write path to use, inspect OPENASE_PRINCIPAL_KIND and OPENASE_AGENT_SCOPES first, then pick the smallest typed command that matches the granted scope.

Command Selection Rules

Use this order of preference:

1. Prefer a typed openase command whose semantics already match the target

entity.

1. Read current state first, then write the minimum necessary change.
2. Use openase api only when there is no suitable typed command.
3. Do not edit local files to "represent" platform state.
4. Do not rely on database access, guessed URLs, or undocumented compatibility

paths.

This skill is about platform reads and writes. It is not a substitute for the separate ticket-workpad skill, repository code changes, or workflow-specific execution instructions.

Top-Level Commands

Below is the current top-level openase command surface from source. Not every command is appropriate for agents; the first groups are the ones you will use most often.

Agent / API Surface

• api: raw HTTP passthrough, the fallback entrypoint for any exposed API
• ticket: shared platform wrapper for common ticket reads and writes;

non-overlapping detail/run/dependency/external-link subcommands still go directly through OpenAPI

• status: ticket status board management
• chat: ephemeral chat and project conversations
• project: shared platform wrapper for update/add-repo; list/get/create/delete

still go directly through OpenAPI

• repo: project repos, GitHub repo discovery, and ticket repo scopes
• workflow: workflow and harness reads and writes
• scheduled-job: scheduled job management
• machine: machine registration, probing, and resource inspection
• provider: provider inspection and configuration
• agent: agent inspection, pause/resume, output, and step reads
• activity: project activity timeline reads
• channel: notification channel management and tests
• notification-rule: notification rule management
• skill: skill inspection, updates, binding, and refresh
• watch: SSE watch streams
• stream: SSE stream feeds

Service / Control Plane Operations

• serve: start only the HTTP API service
• orchestrate: start only the orchestration loop
• all-in-one: start the API and orchestrator in one process
• up: start the local OpenASE service
• setup: initialize the local runtime environment
• down: stop the local service
• restart: restart the local service
• logs: inspect local service logs
• doctor: local environment diagnostics

Admin / Schema / Utility

• issue-agent-token: issue an agent token
• openapi: export or inspect OpenAPI artifacts
• version: inspect the version

In practice, agents most often use these commands inside a workspace:

• ticket
• status
• chat
• project
• repo
• workflow
• activity
• scheduled-job
• machine
• provider
• agent
• channel
• notification-rule
• skill
• watch / stream
• api

serve / orchestrate / up / down / restart / issue-agent-token are more about platform operations or control-plane startup and are usually not the first choice for normal ticket execution.

Safe Default Commands

This is the safest first layer for agents to use. The semantics are stable and suitable for direct workflow / harness calls.

1. List current project tickets

./.openase/bin/openase ticket list
./.openase/bin/openase ticket list --status-name Todo --priority high
./.openase/bin/openase ticket list --json tickets

Capabilities:

• Calls GET /projects/{projectId}/tickets
• Supports multi-value filtering with --status-name
• Supports multi-value filtering with --priority

Use this before creating follow-up tickets or mutating status. It gives you the real project board state instead of assuming a ticket name or status lane.

2. Create a ticket

./.openase/bin/openase ticket create \
  --title "Add integration coverage" \
  --description "Split the follow-up work" \
  --priority high \
  --type task \
  --external-ref "PacificStudio/openase#39"

Capabilities:

• Calls POST /projects/{projectId}/tickets
• --title is required
• Optional: --description, --priority, --type, and --external-ref

Good fits:

• You discover that a follow-up ticket is needed
• You need to split work that is outside the current scope
• You need to attach follow-up security, testing, or deployment work back to

the platform explicitly

3. Update the current ticket

./.openase/bin/openase ticket update --description "Record new findings from execution"
./.openase/bin/openase ticket update --status-name Done
./.openase/bin/openase ticket update $OPENASE_TICKET_ID --external-ref "gh-123"

Capabilities:

• Calls PATCH /tickets/{ticketId}
• Can update --title, --description, and --external-ref
• Can update status via --status, --status-name, or --status-id
• --status-name and --status-id are mutually exclusive
• At least one update field is required

In project_conversation runtimes, do not assume the current-ticket variant is available. Prefer the canonical ticket mutation routes exposed by the typed command shape in the current runtime contract.

4. Record usage / cost

./.openase/bin/openase ticket report-usage \
  --input-tokens 1200 \
  --output-tokens 340 \
  --cost-usd 0.0215

Capabilities:

• Calls POST /tickets/{ticketId}/report-usage
• Records incremental usage instead of overwriting totals
• Set at least one field: --input-tokens, --output-tokens, or --cost-usd

Use this only when the current runtime exposes a compatible ticket route. Project-conversation runtimes can lack current-ticket reporting endpoints even if OPENASE_TICKET_ID exists.

5. Manage ticket comments

List comments:

./.openase/bin/openase ticket comment list

Create a regular comment: