Workflow Authoring

Workflow Authoring

Overview

Use this skill when creating or editing an OpenASE workflow harness file. Its job is to turn a vague workflow idea into a concrete harness that clearly defines what the workflow owns, what counts as completion, how ticket state should move, where feedback comes from, and how work survives beyond a disposable ticket workspace.

This skill is about authoring the workflow file itself, not just the underlying engineering task.

Runtime Reality You Must Design Around

OpenASE ticket execution is not a persistent personal development environment.

• Each ticket run gets its own workspace.
• That workspace is created when the ticket starts running.
• The local contents of that ticket workspace are disposable and may be cleaned up after the run finishes.
• Any output that must survive the run must be pushed to the repository or written back to durable OpenASE surfaces such as ticket comments or project updates.

A good workflow harness must make that lifecycle explicit. Do not write harnesses that assume a long-lived local scratchpad or future manual cleanup inside the same workspace.

Use The Shared Platform Contract

Remember that every workflow already receives shared workflow execution rules from the platform. Reuse and specialize those rules instead of fighting them.

In particular, author around these always-on assumptions:

• ticket comments are the durable output channel
• the current workflow pickup status is the active owned lane
• the current workflow finish status must only be used when the workflow deliverable is truly ready
• blocked termination must be reserved for genuinely unprogressable cases
• interactive waiting is not a reliable operating model

Write harness content that sharpens these generic rules for one workflow rather than duplicating all of them verbatim.

What Every Workflow File Must Define

At minimum, a workflow harness should make these items explicit:

1. The workflow's primary mission.

   • What class of tickets this workflow is for.
   • What it is expected to deliver.
   • What it must not take on.

2. The workflow's capabilities.

   • What role this workflow plays.
   • Which bound skills are expected to be used and for what.
   • Which kinds of repository changes or validations it is competent to perform.

3. Status meaning.

   • What it means for a ticket to be in the pickup status.
   • What the finish status means in this workflow.
   • If a blocked or abnormal finish status exists, what threshold justifies using it.

4. Status order and gates.

   • What must be true before the workflow advances a ticket out of its owned lane.
   • Which validations, deliverables, or feedback must exist before the next state is justified.
   • If the workflow is part of a staged delivery chain, define the gate in terms of proof, not intention.

5. Feedback collection.

   • Where the workflow should look for feedback from humans.
   • Where it should record progress, questions, validations, and risks.
   • How it should absorb ticket comments, project updates, external links, PR review, or other signals.

6. Failure and escalation semantics.

   • What counts as a real blocker.
   • What should become a follow-up ticket instead of inflating the current scope.
   • Which status to use when the workflow cannot responsibly continue.

Recommended Harness Structure

Use a predictable structure so the workflow remains inspectable and editable:

1. Role
2. Runtime Context
3. Mission
4. Capabilities
5. Status Control
6. Feedback Loop
7. Execution Rules
8. Delivery Standard
9. Escalation / Blockers
10. Optional Repo or Branch Rules

The harness does not need these exact headings, but it should cover the same semantics.

Status Authoring Guidance

When you write workflow state rules, make the semantics operational:

• Define what work the workflow owns while the ticket remains in its pickup status.
• Define what evidence must exist before the workflow can move the ticket to its finish status.
• Define whether the finish status means:
  • ready for the next workflow
  • ready for review
  • ready for deployment
  • globally done
• Never leave the meaning implicit.

Good status rules describe:

• owned lane
• exit gate
• downstream readiness
• blocked threshold

Weak status rules only say "move to Done when finished."

Feedback Loop Guidance

A workflow should explicitly say where it reads and writes feedback.

When this skill is used for AI suggestions or review, ground the advice in actual project evidence before proposing changes:

• inspect the user's stated goal first
• inspect the current workflow harness and status bindings
• inspect recent tickets that ran through the workflow, especially retries, paused tickets, and repeated failure patterns
• inspect recent activity, ticket comments, and durable ticket descriptions for what humans actually asked for
• prefer explaining which observed pattern caused each suggested harness change

Do not invent a lane split, exit gate, or escalation rule unless the observed workflow history or the user's request supports it.

Common durable sources:

• ticket description
• ticket comments
• the persistent workpad comment
• project updates when high-visibility escalation is needed
• linked PRs, issues, design docs, or other external references

A workflow should also say what belongs in feedback:

• progress updates
• validations run and exact results
• blocker diagnosis
• questions that need human input
• follow-up tasks or residual risks

If the workflow needs human feedback before a state transition, say so clearly and name the source of truth.

Repository And Branch Rules

These are optional, but when relevant the harness should state:

• which repository or repositories the workflow may change
• whether it should stay within the ticket's repo scope unless explicitly widened
• how branches should be named or updated
• whether commit and push are required before finishing
• whether certain generated files, changelogs, or docs must be kept in sync

Because ticket workspaces are disposable, any workflow that produces repository output should state that unpublished local work is not durable.

Comment And Reporting Rules

When the workflow needs durable reporting, say what should be written back:

• plan or intent
• implementation progress
• validation commands and outcomes
• review findings
• risk notes
• final readiness statement

Do not rely on terminal output alone. If the result matters after the ticket run ends, require it to be written to a durable platform channel.

Milestone And Gate Workflows

For gate-style workflows, be even stricter:

• define the phase being proven
• define the integration or connection work expected
• define the exact proof required before the gate can pass
• define what missing evidence keeps the ticket in the active lane

Gate workflows should be written around proof of staged readiness, not vague coordination.

Common Workflow Patterns

These are common patterns worth documenting directly in workflow harnesses when they apply.

1. Coding Workflow

Use this when one workflow owns implementation from ticket pickup through repository delivery.

The harness should state clearly that:

• the workflow accepts tickets from one active implementation lane
• the workflow completes the scoped code change, runs the required validation, and records the results durably
• the workflow commits and pushes all required changes before leaving its owned lane
• the workflow must use a dedicated working branch rather than a protected main branch
• the workflow should link the resulting GitHub PR URL, or the relevant GitHub issue URL when appropriate, back to the ticket
• the workflow must not move the ticket forward while meaningful local workspace changes remain uncommitted or unpublished

Typical gate:

• code changed
• validation passed
• branch pushed
• PR or issue link added to the ticket
• workpad or ticket comments updated with proof