with one click
openase-platform
// Platform operations for tickets, projects, and runtime coordination inside OpenASE.
// Platform operations for tickets, projects, and runtime coordination inside OpenASE.
Create or update a branch-scoped Coolify review environment with one command, and delete it with one command. Use when a ticket must deploy a preview before human review, while keeping the workflow simple and fast.
Write workflow harness files that define role, status semantics, feedback loops, and durable delivery rules for disposable ticket workspaces.
Clarify ambiguous requests with a focused, Socratic interview before planning or implementation.
Review behavior, risk, performance, and test coverage before style nits.
Review trust boundaries, auth, input handling, secrets, and dependency risk before release.
Turn a clarified spec into milestone-oriented tickets, dependency edges, and stage-gated delivery lanes.
| name | openase-platform |
| description | Platform operations for tickets, projects, and runtime coordination inside OpenASE. |
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.
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:
Keep the boundaries clear:
workflow as "just a prompt"; it is prompt + routing +
policy + execution limits.updates as a synonym for activity; updates are curated,
while activity is the raw event timeline.activity as a task board; it explains history, not desired
future state.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:
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.
openase CLI. Do not try
to express platform state indirectly by editing local files.403. That usually means the
current harness did not grant the required platform_access.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 URLOPENASE_AGENT_TOKEN: current agent tokenOPENASE_PROJECT_ID: current project UUIDOPENASE_TICKET_ID: current ticket UUID; only present in ticket runtime or
ticket-focused Project AIOPENASE_CONVERSATION_ID: current project conversation UUID; available in
Project AI conversationsOPENASE_PRINCIPAL_KIND: current principal kind, such as ticket_agent or
project_conversationOPENASE_AGENT_SCOPES: current token scopes, comma-separatedCommon platform subcommands auto-fill context in this order:
--project-id -> OPENASE_PROJECT_ID[ticket-id] -> --ticket-id ->
OPENASE_TICKET_ID--api-url -> OPENASE_API_URL--token -> OPENASE_AGENT_TOKENImportant limits:
ASE-42.--json, --jq, or
--template.--status-name / --status_name and --body-file / --body_file.Check OPENASE_PRINCIPAL_KIND before assuming a route is available.
When the principal is ticket_agent:
OPENASE_TICKET_ID.When the principal is project_conversation:
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.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.
Use this order of preference:
openase command whose semantics already match the target
entity.openase api only when there is no suitable typed command.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.
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.
api: raw HTTP passthrough, the fallback entrypoint for any exposed APIticket: shared platform wrapper for common ticket reads and writes;
non-overlapping detail/run/dependency/external-link subcommands still go
directly through OpenAPIstatus: ticket status board managementchat: ephemeral chat and project conversationsproject: shared platform wrapper for update/add-repo; list/get/create/delete
still go directly through OpenAPIrepo: project repos, GitHub repo discovery, and ticket repo scopesworkflow: workflow and harness reads and writesscheduled-job: scheduled job managementmachine: machine registration, probing, and resource inspectionprovider: provider inspection and configurationagent: agent inspection, pause/resume, output, and step readsactivity: project activity timeline readschannel: notification channel management and testsnotification-rule: notification rule managementskill: skill inspection, updates, binding, and refreshwatch: SSE watch streamsstream: SSE stream feedsserve: start only the HTTP API serviceorchestrate: start only the orchestration loopall-in-one: start the API and orchestrator in one processup: start the local OpenASE servicesetup: initialize the local runtime environmentdown: stop the local servicerestart: restart the local servicelogs: inspect local service logsdoctor: local environment diagnosticsissue-agent-token: issue an agent tokenopenapi: export or inspect OpenAPI artifactsversion: inspect the versionIn practice, agents most often use these commands inside a workspace:
ticketstatuschatprojectrepoworkflowactivityscheduled-jobmachineprovideragentchannelnotification-ruleskillwatch / streamapiserve / 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.
This is the safest first layer for agents to use. The semantics are stable and suitable for direct workflow / harness calls.
./.openase/bin/openase ticket list
./.openase/bin/openase ticket list --status-name Todo --priority high
./.openase/bin/openase ticket list --json tickets
Capabilities:
GET /projects/{projectId}/tickets--status-name--priorityUse 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.
./.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:
POST /projects/{projectId}/tickets--title is required--description, --priority, --type, and --external-refGood fits:
./.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:
PATCH /tickets/{ticketId}--title, --description, and --external-ref--status, --status-name, or --status-id--status-name and --status-id are mutually exclusiveIn 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.
./.openase/bin/openase ticket report-usage \
--input-tokens 1200 \
--output-tokens 340 \
--cost-usd 0.0215
Capabilities:
POST /tickets/{ticketId}/report-usage--input-tokens, --output-tokens, or --cost-usdUse 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.
List comments:
./.openase/bin/openase ticket comment list
Create a regular comment:
./.openase/bin/openase ticket comment create --body "Record the current blocker"
./.openase/bin/openase ticket comment create --body-file /tmp/comment.md
Update an existing comment:
./.openase/bin/openase ticket comment update $OPENASE_TICKET_ID $COMMENT_ID --body-file /tmp/comment.md
Capabilities:
ticket comment list calls GET /tickets/{ticketId}/commentsticket comment create calls POST /tickets/{ticketId}/commentsticket comment update calls PATCH /tickets/{ticketId}/comments/{commentId}--body or --body-fileopenase-platform only provides the comment primitives here. It does not
define workpad semantics directly. When you need persistent workpad
maintenance, use the separately bound ticket-workpad skill, which builds on
top of these comment list/create/update primitives.
./.openase/bin/openase project update --description "Update the latest project context"
Capabilities:
PATCH /projects/{projectId}Good fits:
Preferred current form:
./.openase/bin/openase repo create $OPENASE_PROJECT_ID \
--name "worker-tools" \
--url "https://github.com/acme/worker-tools.git" \
--default-branch main \
--label go \
--label backend
Compatibility form:
./.openase/bin/openase project add-repo \
--name "worker-tools" \
--url "https://github.com/acme/worker-tools.git" \
--default-branch main
Capabilities:
repo create calls POST /projects/{projectId}/repos--name and --url are required--default-branch defaults to main--label can be repeatedPrefer repo create when available because it models repos as first-class
project entities. Keep project add-repo in examples because older harnesses
and existing skills can still reference it.
./.openase/bin/openase status list $OPENASE_PROJECT_ID
./.openase/bin/openase status create $OPENASE_PROJECT_ID \
--name "QA" \
--stage started \
--color "#FF00AA"
./.openase/bin/openase status update $STATUS_ID --name "Ready for QA"
Capabilities:
status list calls GET /projects/{projectId}/statusesstatus create calls POST /projects/{projectId}/statusesstatus update calls PATCH /statuses/{statusId}status delete and status reset are also available as typed commandsUse these when the workflow needs status-board visibility rather than only mutating one ticket.
./.openase/bin/openase workflow list $OPENASE_PROJECT_ID
./.openase/bin/openase workflow harness get $WORKFLOW_ID
./.openase/bin/openase workflow harness history $WORKFLOW_ID
./.openase/bin/openase workflow harness variables
./.openase/bin/openase workflow harness validate --input /tmp/harness.json
Capabilities:
Use this path before editing workflows, binding skills, or assuming a workflow already grants a specific platform scope.
./.openase/bin/openase activity list $OPENASE_PROJECT_ID
./.openase/bin/openase ticket run list $OPENASE_PROJECT_ID $OPENASE_TICKET_ID
./.openase/bin/openase ticket run get $OPENASE_PROJECT_ID $OPENASE_TICKET_ID $RUN_ID
./.openase/bin/openase agent output $OPENASE_PROJECT_ID $AGENT_ID
Capabilities:
activity list reads project-level business timeline eventsticket run list/get inspects execution history for a ticketagent output reads streamed or recorded agent outputUse these to understand what already happened before writing new platform state.
./.openase/bin/openase machine refresh-health $MACHINE_ID
./.openase/bin/openase machine resources $MACHINE_ID
./.openase/bin/openase provider list $OPENASE_ORG_ID --json providers
Capabilities:
Run ./.openase/bin/openase machine refresh-health $MACHINE_ID before making
decisions based on machine capacity.
./.openase/bin/openase chat conversation list --project-id $OPENASE_PROJECT_ID
./.openase/bin/openase chat conversation get $OPENASE_CONVERSATION_ID
./.openase/bin/openase chat conversation entries $OPENASE_CONVERSATION_ID
./.openase/bin/openase chat conversation turn $OPENASE_CONVERSATION_ID --message "Continue the previous investigation"
./.openase/bin/openase chat conversation watch $OPENASE_CONVERSATION_ID
Capabilities:
This is especially relevant when the principal is project_conversation.
./.openase/bin/openase skill list $OPENASE_PROJECT_ID --json skills
./.openase/bin/openase skill get $SKILL_ID
./.openase/bin/openase skill refresh $OPENASE_PROJECT_ID \
-f workspace_root="$PWD" \
-f adapter_type=codex-app-server
Capabilities:
skill list resolves the current project skill catalog and skill IDsskill get returns the current stored content, bundle files, and historyskill refresh re-projects enabled skills into .codex/skills,
.claude/skills, .gemini/skills, or .agent/skills depending on adapterThis is the preferred path when comparing repo skill bundles with the current platform copy or after updating a skill and needing the current workspace to see the new version.
ticket-workpadThe ticket-workpad skill owns durable execution-log semantics. This skill
only provides the platform primitives and helper script that make that
possible.
openase-platform exposes the underlying ticket comment APIs and ships
scripts/upsert_workpad.sh.ticket-workpad skill defines which comment counts as the workpad, how
sections should be maintained, and why later agents should resume from the
same persistent comment.ticket-workpad skill; this platform skill only provides the
underlying comment primitives.The helper script is projected into the runtime skill bundle and can be called directly:
cat <<'EOF' >/tmp/workpad.md
Plan
- inspect workflow and current ticket
Progress
- reading repository and platform state
Validation
- not run yet
Notes
- none
EOF
./.codex/skills/openase-platform/scripts/upsert_workpad.sh --body-file /tmp/workpad.md
Equivalent helper locations can exist under .claude/skills,
.gemini/skills, or .agent/skills depending on the adapter type.
When you are working on the platform skill library itself, use a different mental model from normal ticket execution:
skill import is for introducing a new local skill bundle into a project.skill get + skill update instead of importing
again.skill get is the easiest way to compare repo content with the platform's
current stored bundle.skill refresh is what makes the updated bundle appear inside the current
workspace's projected skill directory../.openase/bin/openase skill list $OPENASE_PROJECT_ID --json skills
./.openase/bin/openase skill get $SKILL_ID --json skill,content,files,history
Use skill list first to resolve the real UUID for a skill such as
openase-platform. Then use skill get to inspect:
SKILL.mdFor bundle updates, the platform expects a full valid skill bundle. Do not send only one helper file and assume the server will merge it into the previous bundle version.
At minimum:
SKILL.md.files array
unless you intentionally want to remove them.SKILL.md frontmatter name must still match the existing skill name.Practical payload generation example:
python3 - <<'PY' >/tmp/openase-platform-update.json
from __future__ import annotations
import base64
import json
from pathlib import Path
root = Path("internal/builtin/skills/openase-platform")
files = []
for path in sorted(p for p in root.rglob("*") if p.is_file()):
relative = path.relative_to(root).as_posix()
files.append(
{
"path": relative,
"content_base64": base64.b64encode(path.read_bytes()).decode(),
"is_executable": bool(path.stat().st_mode & 0o111),
}
)
payload = {
"description": "OpenASE Platform Operations",
"files": files,
}
print(json.dumps(payload, ensure_ascii=False))
PY
./.openase/bin/openase skill update $SKILL_ID --input /tmp/openase-platform-update.json
After the update succeeds, refresh the projected workspace copy:
./.openase/bin/openase skill refresh $OPENASE_PROJECT_ID \
-f workspace_root="$PWD" \
-f adapter_type=codex-app-server
If the target runtime is Claude Code or Gemini instead of Codex, change the
adapter_type accordingly.
If the high-frequency commands above are not enough, openase has a wider
typed CLI that follows the OpenAPI contract directly. Common namespaces
include:
openase ticket ...openase status ...openase chat ...openase project ...openase repo ...openase workflow ...openase scheduled-job ...openase machine ...openase provider ...openase agent ...openase activity ...openase channel ...openase notification-rule ...openase skill ...openase watch ...openase stream ...High-value examples:
./.openase/bin/openase ticket get $OPENASE_TICKET_ID
./.openase/bin/openase ticket detail $OPENASE_PROJECT_ID $OPENASE_TICKET_ID
./.openase/bin/openase workflow list $OPENASE_PROJECT_ID
./.openase/bin/openase workflow harness get $WORKFLOW_ID
./.openase/bin/openase workflow harness history $WORKFLOW_ID
./.openase/bin/openase workflow harness variables
./.openase/bin/openase machine refresh-health $MACHINE_ID
./.openase/bin/openase machine resources $MACHINE_ID
./.openase/bin/openase provider list $OPENASE_ORG_ID --json providers
./.openase/bin/openase agent output $OPENASE_PROJECT_ID $AGENT_ID
./.openase/bin/openase skill list $OPENASE_PROJECT_ID
./.openase/bin/openase watch project $OPENASE_PROJECT_ID
These typed commands have useful properties:
--json, --jq, and --template can trim large responses.If a typed command does not exist yet, use raw passthrough last:
./.openase/bin/openase api GET /api/v1/tickets/$OPENASE_TICKET_ID
./.openase/bin/openase api GET /api/v1/projects/$OPENASE_PROJECT_ID/tickets \
--query status_name=Todo \
--query priority=high
./.openase/bin/openase api POST /api/v1/projects/$OPENASE_PROJECT_ID/tickets \
-f title="Follow-up" \
-f workflow_id="550e8400-e29b-41d4-a716-446655440000"
./.openase/bin/openase api PATCH /api/v1/tickets/$OPENASE_TICKET_ID/comments/$COMMENT_ID \
--input payload.json
Rules:
api METHOD PATH is raw HTTP passthrough.-f/--field uses key=value entries to build a JSON body.--query appends query-string fields.--input sends a raw request body and cannot be mixed with -f.ticket list / get / detail, activity list, or skill get
before making assumptions about current state.--status-name unless you already have
the exact status UUID.403 happens, inspect capability boundaries and scopes first instead
of trying alternate endpoints blindly.ASE-42 will be accepted where a UUID
is required.project_conversation sessions, favor project-scoped routes, use
tickets.update for canonical ticket mutations including comments, and do
not assume usage-report endpoints are available.