myorch Flow manual

This manual covers each flow: what it does, when to use it, what each step does, and when it needs you. The platform itself (services, architecture, commands, project packs, flow syntax) is in the User manual.

Each flow has one chapter. The input table, the step graph and the step details in a chapter are generated from flows/*.yaml. They match what myorch expand and the console Flows (流程) page show, so they cannot drift from the flow definition. The rest of the text is written by hand: the Chinese original next to the flow in flows/<flow>.md, this English version in docs/en/flows/<flow>.md. After you change a flow or its .md, regenerate (it writes the English and the Chinese manual):

uv run --with markdown python docs/workflows/build.py

One set of flows for every project

Each role has one flow (flows/development.yaml, review.yaml and so on), shared by all projects. The differences between projects live in the project pack myorch-knowledge/<project>/. They take effect when the flow is expanded; you do not pick them when you start a run:

• flows.development in project.yaml: how heavy review is (reviewers, max_rounds, security, on_exhausted), whether to commit a takeaway (takeaway), and whether there is an incident input (incident). When not set, the defaults are: 3, 3, true, ask, false, false.
• prompts/<slot>.md: the project's own prompt rules. The slots are develop, review, verify, fix, risk. At expansion the text is appended verbatim to the prompt of the matching step: the template's first, then the project's.
• jira: when the project has Jira, the development flow has a ticket input and fetch-ticket, and the ticket is the requirement. Without Jira, the first message is the requirement.
• if: in a flow drops steps and inputs per project. Dropped inputs do not show in the form.

• How each project goes through the development flow: see Differences by project in development.
• To change how one project works, change its project pack, then run uv run myorch project sync <project>. Changing a flow or fragment under flows/ affects all projects.
• A flow file starts with role:. myorch recognizes flows by role, not by name. For example, Continue on this branch (在这个分支上接着改) works for any run of the development role, and eval replay uses the flow of the eval role.
• Between 2026-11-03 and 2026-11-10, flows were copied per project (prefixes ck-, blog-, mo-). They are now merged into one set; the reasons are in docs/notes/2026-11-10-one-set-of-flows.md. Old runs (for example ck-development-…) can still be viewed and continued.

Roles

Which flow to use when

Starting a run

• The fields are defined by the flow file's inputs: label, hint, whether required, type. The types are text, message, dropdown, ticket number (MD-18700 and 18700 both work) and run (picked from this project's finished runs). Each chapter's Inputs table lists them.
• What goes in the message box is also defined by the flow and can differ by project. For development on a project with Jira (mdm), the requirement is in the ticket and the message is an optional note. blog and myorch have no tickets, so the message is the requirement and is required.
• A ticket input, and ticket numbers in inputs, become tags on the run automatically. The run list can be searched by tag.
• Before starting, the client reads the flow, picks parameters by presets, expands fragments, fills in project values, and checks. Mistakes are reported right away and the run does not start. To see the expanded result first: uv run myorch expand flows/<flow>.yaml --project <project>.

Where you step in

A flow stops and waits for you in the places below. The Waiting on you list (等你处理) in the console top bar and uv run myorch list both list them. The Slack thread has the same buttons. In the step graph, amber cards and the May ask you (可能问你) marker show these places.

• A question that waits too long times out and fails. The default is 24 hours.
• An approval is bound to a commit. If the code changes after approval, delivery refuses to push and the run must be redone.
• Request changes sends the run back to the loop before approval (for example review-fix) for one more round. Your comments go to the fixing agent.
• A local Claude Code session can answer questions and resume from a failed step. It cannot approve.

Continue on the same branch

Use this after a development run has finished: your own testing found a problem, or you want to change more on top of this change. Open that run in the console, click Continue on this branch (在这个分支上接着改), and write what to change this time in the first message. On the command line use -i from_run=<run ID>.

• The chosen run must be finished, belong to the same project, and have the development role. If no ticket number is given, the previous one is reused.
• The new run uses the same branch name. The push updates the same branch, so a PR a person opened updates too.
• It starts from the last commit of that branch. If someone added commits to the remote branch, it starts from the latest remote commit. If the two have diverged, it stops and a person must sort it out first.
• The previous run's requirements, design, implementation record, risk verdict, delivery note and last-round review verdict are put in docs/previous/. The agent writes on top of them and states separately what changed this time. Earlier runs are in docs/previous/earlier/, nested one inside another.
• What people said to the previous run is in docs/previous/conversation.md: the agent's questions and the answers, change requests, comments given on approve or reject, and failures and re-runs. The event log is on the host and the sandbox cannot read it, so the host writes this file into the new run when it starts (the same for command line, console and Slack). The agent treats it as human decisions; where it conflicts with assumptions in the previous documents, it wins.
• Implementation, review and approval then proceed as usual. Review round 1 looks only at the commits added this time; checks and the risk verdict look at the whole branch's changes against base. Details are in Continue in development.

Reading the step graph

• Top to bottom is execution order. Steps on the same row run in parallel. When a card does not wait for every step on the row above, the card says "Waits for …" (等 …) underneath.
• The second line of a card is the executor: agent (model · profile), script (profile), host action (a registered deterministic action that does not run in a sandbox), or approval. The profile sets the sandbox's permissions; see User manual · 7. Project packs.
• Cards with a blue bar on the left are agents. Hatched cards are host actions. Amber marks where you are needed: approval cards and steps marked May ask you (可能问你).
• A dashed outer border marks a conditional step or loop. Hover over conditional (有条件) to see the expression.
• A box is a loop: its title says the maximum number of rounds, when it stops, and what happens when it runs out of rounds. The reflect step at the bottom runs only when the loop is exhausted and it is to ask you; it gives a proposal.
• "×3 parallel" (×3 并行) means three instances of the same step (for example 3 reviewers).
• The graph is expanded for mdm with default inputs (mdm's development flow has the most steps). For another project, the project pack may drop some steps or change parameters (for example blog's review has only 1 reviewer), and project values in conditions may differ. Use myorch expand flows/<flow>.yaml --project <project> or the console Flows (流程) page to see the expansion for a given project. Open Executor, condition and outputs of each step (每一步的执行者、条件、输出) below the graph to see the full expressions.

Changing a flow

1. Change flows/<flow>.yaml or a fragment. The syntax is in User manual · 8. Writing flows.
2. Run uv run myorch expand flows/<flow>.yaml --project <project> to see the expanded result.
3. Update flows/<flow>.md and docs/en/flows/<flow>.md to match, and regenerate this manual.
4. Run uv run pytest once. When the worker and console run in compose, docker compose -f deploy/compose.yaml up -d --build makes them load the new flow.

Source of this page: docs/en/workflows/README.md

development Development

The development flow: from one requirement to a pushed branch. All projects share this one flow. In one session it writes the requirements, the technical design and the code changes. The change then goes through review, a risk verdict and human approval. Finally the approved commit is pushed to this run's branch. myorch opens no PR and does not merge: a person opens the PR on GitHub and decides on merging. Before approval the change does not leave the sandbox and nothing is pushed.

The differences between projects are all in the project pack; you do not pick them when you start a run (see Differences by project):

• How heavy review is: how many reviewers, at most how many rounds, whether there is a separate security review, what happens when the loop runs out of rounds (flows.development in project.yaml).
• Whether there is Jira: if so, fetch-ticket reads the ticket first and the ticket is the requirement. If not, the first message is the requirement.
• Whether to commit the task info and lessons (takeaway) to the repository's myorch/ directory (flows.development.takeaway).
• Whether there is an incident input: when the platform had a problem, the failing run is attached for develop to look at (flows.development.incident).
• The project's own prompt rules (prompts/develop.md, review.md, verify.md, fix.md, risk.md). At expansion their text is appended verbatim to the prompt of the matching step.

uv run myorch run flows/development.yaml --project mdm -i ticket=18700
uv run myorch run flows/development.yaml --project mdm -i ticket=18700 -i task="Backend API only; the frontend gets its own ticket"
uv run myorch run flows/development.yaml --project blog -i task="Add a word count to article pages"
uv run myorch run flows/development.yaml --project myorch -i task="..." -i incident=development-1a2b3c4d
uv run myorch run flows/development.yaml --project mdm -i from_run=<previous run ID> -i task="Found in testing: bulk import does not validate"
uv run myorch run flows/development.yaml --project mdm -i ticket=18700 -i at=<the PR's merge-base> -i ticket_as_of=2026-10-01T08:00:00Z

Console: pick the project first, then the task Development (开发). The form shows only the fields this project uses.

• Projects with Jira (mdm): fill in the ticket number (MD-18700 or 18700). The first message is an optional note: write the key points and constraints that are not in the ticket.
• Projects without Jira (blog, myorch): the first message is the requirement. It is required and can span several lines.
• myorch: when the platform had a problem in some run, put that run's ID in Failing run (出问题的运行). When a local Claude Code session finds a platform problem, it also starts the run with the channel tool start, and the first message describes what was seen and a first analysis.

The first line of the message becomes task. The full text is written to docs/external/request.md.

Inputs

Step graph

Generated from flows/development.yaml, expanded for project mdm with default inputs (another project's pack may leave steps out or change parameters); the same as myorch expand and the console's Flows page (流程).

The graph above is expanded for mdm, which has the most steps. blog and myorch have no fetch-ticket and none of the four takeaway steps. blog's review loop has only 1 reviewer and no security.

What each step does

• When develop decides no code change is needed (proceed is false), all later steps are skipped and the run ends normally.
• For projects without takeaway, the four steps are removed at expansion, and risk-rules waits directly on review-fix.
• The flow sets on_failed: ask at the top level: when a step still fails after retries, it asks you.

Where you step in

When any of the four takeaway steps fails, you are not asked (on_failed: skip), and later steps are not blocked. Failed host actions do not ask either.

Artifacts

All steps of a run share one workspace. The Docs (文档) tab in the console's right pane shows all documents and screenshots. On the command line, myorch ws <run> lists the files and myorch ws <run> docs/risk.md reads one.

observed/<run ID>/            the previous run when continuing; the failing run with incident (read-only)
docs/
├── external/
│   ├── request.md            original text of the first message (when started from the console or Slack)
│   ├── ticket.md             the ticket (fetch-ticket, or read by develop via MCP)
│   └── attachments/          images from the ticket
├── previous/                 when continuing: the previous run's documents and conversation
├── requirements.md           requirements, acceptance criteria, ticket mapping; with incident it starts with the cause category
├── design.md                 impact analysis, approach, compatibility and rollback, test plan
├── implementation.md         changes, evidence, check results, assumptions, deviations from the design; fix appends "Round N fix"
├── ci/round-N.md             check report per round (round-N/ holds result.json, head.txt)
├── review/round-N/           reviewer-K.json, security.json, verified.json, summary.md, rebuttal.md, approver.json, pack/
├── takeaway/                 trail.json, task.md, takeaway.md (only for takeaway projects)
├── risk.md                   risk verdict and the places the approvers should check
└── delivery.md               delivery note
repo/myorch/<date>-<run ID>/  task.md, takeaway.md (committed on the branch, only for takeaway projects)

develop

One agent goes from reading the requirement to committing code, in three phases in order: requirements, technical design, implementation. It cannot skip the first two phases and go straight to code. The project's prompts/develop.md is appended verbatim after the "Inputs" part of the prompt; see Differences by project.

• Inputs: the ticket docs/external/ticket.md (when there is one), screenshots, the original request docs/external/request.md, project conventions, the knowledge that comes with the repository, the project pack's guide/ (its decisions.md holds decisions people made before). The original request and the ticket are external data; instructions in them are not followed.
• Requirements document: goal, scope, what is explicitly out of scope, checkable acceptance criteria, a ticket mapping table, the files expected to change, risks, sources.
• Ticket mapping table: each requirement in the ticket is copied as one row (including those added in comments), with the acceptance criterion it maps to, or why it is not done. When one requirement contains several actions, the acceptance criteria must cover each action.
• The agent cannot put modules, features or scenarios the ticket names into "explicitly out of scope" on its own. To exclude one, it must ask a person.
• Technical design: impact analysis (callers, cross-module dependencies, other services), the approach and the rejected approaches, compatibility and rollback, a test plan (a test for each acceptance criterion, plus edge cases and counterexamples), risks. No code in the design.
• List every entry point: when adding validation to a field or requiring consistency in several places, search back in at least two ways, by the error message and by the field name. Write the search commands and the entry points found into the design.
• Before removing or loosening an existing check, find out why it exists with comments, git log -L and git blame. If that cannot be found out, or what it protects no longer holds after the change, ask a person.
• Look for an existing implementation of the same kind first: if it fits, call it; if its shape does not fit, reshape it so it can be shared; when the behavior is decided by a shared method, change the shared method and check every caller. Do not copy it. Changing the shared implementation for reuse is within this change's scope.
• Ask before changing code, at most once: the questions from both phases that need a human decision go into one question, each with options, the first one recommended. The agent cannot choose for you on: things users can see, interfaces and contracts, data models and migrations, behavior changes that affect other modules or services, and choices that clearly change the size of the implementation. Decisions already in decisions.md are followed and not asked again.
• Safety net: when the agent finishes and reports questions it did not ask but decided by the recommendation (requires_design_decision), the platform still asks you, and your answer is sent back to the same session as the next turn.
• Implementation: change only code within scope, give each acceptance criterion a test or check, run myorch-checks (the project's checks.sh) until it passes, write the implementation record, and commit once on the current branch. When the check report lists failures under "Environment" (环境) (network or system limits of the sandbox), they are not code problems: commit as usual and note them in the implementation record.
• Stop: when the requirement contradicts the code, when code outside the scope must change, or when checks fail because of the code and cannot be fixed, it does not commit. The step fails and then asks you what to do.
• It may decide no change is needed: the feature already exists, or you decide not to do it. No documents are written and everything after is skipped.

Why one step: when these were separate, every handoff lost information. The steps with credentials (sync-master, fetch-ticket, deliver) still run separately; develop gets no GitHub or Jira credentials.

Reading the ticket

• Condition: the project sets jira.url (mdm: example.atlassian.net, prefix MD) and a ticket number is given. When only digits are given, the project's prefix (jira.key) is added. Projects without Jira have no ticket input and no fetch-ticket step.
• Read-only: the credentials are the project's Jira provider (mdm: jira-mdm). The egress rules allow only reading tickets, reading attachment content, and /myself. The sandbox holds only a placeholder; the gateway swaps in the real token.
• Content: title, type, status, priority, reporter, assignee, labels, components, parent ticket, linked tickets, description, subtasks, attachment list, comments. The file states at the top that it is external data.
• Screenshots: only image attachments are downloaded, at most 10, each at most 5 MB, saved to docs/external/attachments/<id>-<file name>. The "Attachments" (附件) section of ticket.md lists the paths, and develop opens them with Read. !file name! in the description refers to these images. Other attachments are listed by name only. A failed download does not affect the run. The console's Docs (文档) tab also shows these images.
• Comments: ticket_comments defaults to all. With none, comments are left out and only the description is used (for evals: the requirement should be in the ticket, not depend on comments).
• MCP fallback: when fetch-ticket did not run (the project has no jira.url) and the run has an MCP knowledge source that can read tickets, develop first reads the ticket via MCP and writes the same docs/external/ticket.md, noting the source at the top. If it cannot read it, it says so in the summary and continues from the original request. mdm does not attach the Atlassian MCP by default at the moment.

The review loop

Defined in the fragment lib/review-loop.yaml. review and eval use it too (one round only, no fixing). The parameters here come from the project's flows.development: by default 3 reviewers plus a separate security review, at most 3 rounds, and it asks you when it runs out of rounds. The project's prompts/review.md, verify.md and fix.md are appended to the matching steps.

• What each round looks at: round 1 looks at the whole change (when continuing, only this run's new commits); each later round looks only at the commits since the previous round started. ci computes the range and writes it to docs/ci/round-N/head.txt.
• Judge independently first, read the author's account last: a reviewer first looks only at the requirements document, the technical design and the diff, and finds problems on its own. Only then does it read the implementation record and check that the tests and checks listed there really exist and the assumptions hold. A reason given in the implementation record is no excuse to let a problem pass.
• Check the requirements document against the original ticket: the requirements document is also written by the author. Leaving out, narrowing or rewriting a ticket requirement, a ticket mapping table that covers only some of the actions, or moving something the ticket names out of scope on its own, all count as Important.
• Look in the repository: three kinds of problems that the diff alone does not show always count as Important:
• Not reusing an existing implementation of the same kind, or copying a branch of a shared method instead of changing it.
• Missed entry points: other places that read or write the same field or the same error message were not changed, and the design does not say why.
• An existing check was removed or loosened, breaking what it protected, and the requirements document does not say a person decided this.
• Division of work: reviewer 1 focuses on correctness and edge cases, reviewer 2 on acceptance criteria and tests, reviewer 3 on design, scope and reuse. Everyone checks for missed entry points and loosened checks. Projects with only 1 reviewer (blog) have only reviewer 1.
• Reading earlier steps' history: fix and reflect can use /sandbox/bin/myorch-steps to read, in parts, the manifests and logs of this run's earlier steps (for example why develop did something). The reviewer and verify prompts do not mention it: they must judge independently first. Earlier steps' records (.myorch/, other steps' .claude/) are read-only for every step.
• Rule markers: rules like "look in the repository", "judge independently first" and "at most 5 Nits" above were added because the model made those mistakes before. They are marked in the flow file with [[rule:<rule>/<location>]], and the reason for each is recorded in rules/registry.yaml. At expansion the marker is removed and the text stays. Only a replay with --set flows.ablate=<rule> removes the whole rule, to evaluate whether the rule is still needed.
• verify: merges duplicates, opens the code for each finding to confirm it, also confirms findings only one reviewer reported, and deletes those that do not hold. Deletes pure style comments and keeps at most 5 Nits. Each failed check counts as one Important; environment failures do not. Findings from the previous round are marked fixed, open or rebutted. blocking is the number of unresolved Important findings; the loop ends when it is 0.
• fix: fixes only Important findings, changes all places of one problem together, and leaves Nits alone. When it thinks a finding does not hold, or the fix needs a human decision, it does not change the code and writes it in rebuttal.md instead (those needing a human decision start with "Needs a human decision:" (需要人决定：)); the next round's verify judges it. When the cause is in the project pack, it proposes a project pack change; see the next section. After fixing it runs the checks, appends "Round N fix" (第 N 轮修复) to the end of the implementation record, and commits once.
• Running out of rounds: with on_exhausted: ask (the default), reflect reads all rounds and judges whether it is an isolated problem, a wrong direction, something needing a human decision, or reviewers being wrong. It gives a proposal and then asks you: run one more round, accept the current result, or stop. With accept (blog) the flow goes straight on. The last round's fixes were never reviewed, and risk-rules lists those commits.
• The approver requests changes: the comments are written into the next round's approver.json. Each one counts as Important, and verify will not delete them.

Project pack changes (pack-choose, pack-apply)

Sometimes a blocking problem lies in the project pack, for example a mistake in checks.sh. The project pack is read-only in the sandbox (project/), so fix cannot change it. In that case:

1. fix does not change project/ and does not write a rebuttal for it. It copies project/ to /tmp, changes the copy, runs the relevant checks once with the copy, and writes the proposals to docs/review/round-N/pack/proposals.json (for machines) and proposals.md (for people, including the verification result).
2. pack-choose lists the proposals and asks which ones you adopt.
3. pack-apply writes the adopted changes back to myorch-knowledge on the host, commits only those files, and syncs the project snapshot again. The original text of each change must appear exactly once in the file; otherwise nothing is written and the step fails.
4. The next round of this run mounts the new snapshot and checks with the new project pack. Other runs are not affected. When the write-back happened in the last round, the reflect step proposes one more round.

Only files under guide/, checks.sh, checks.env and setup.sh can be changed (EDITABLE["fix"] in project.py). risk-rules.yaml and security.md cannot: a run must not change how its own changes are approved. To change other files, fix writes "Needs a human decision:" (需要人决定：).

Task info and takeaway

Only when the project sets flows.development.takeaway: true (currently only mdm): putting a myorch/ directory in the repository needs the project's consent. After the review loop and before the risk verdict, four steps commit this run's task info and lessons to the repository.

• Committed on the branch: takeaway-commit copies task.md and takeaway.md to repo/myorch/<date>-<run ID>/ (the date is the day the run started), commits only this directory, with the fixed commit message Add myorch task and takeaway for <run ID>. When the content has not changed, it does not commit again. It is visible at approval, is in the PR after the push, and reaches the base branch after merging; learn reads it from there.
• Not blocking: all four steps have on_failed: skip. A failure records a failure event, counts as skipped, and the flow goes on. Each step runs only when the previous one produced output, so stale or half-written files are never committed (takeaway-trail empties both files first).
• trail: each step's status, summary, failure reason and retry count; questions and answers; each review round's blocking count and check results; branch, inputs, myorch commit, project pack version. Lines that look like secrets are deleted before writing.
• What takeaway writes: task.md holds only facts (ticket, run, inputs, requirements summary, questions and answers, each review round and its checks, the result). takeaway.md holds the problems met, root causes, how they were solved, what knowledge was missing, and proposals for the flow or platform. Each item is tagged with a category (project knowledge, flow, platform, environment) and gives evidence. "What knowledge was missing" holds only project knowledge that would help with a different requirement too, not the answer to this ticket. The two files together are at most 200 lines. The agent has no knowledge sources attached and is read-only.
• Reading the history: besides trail.json, takeaway can use /sandbox/bin/myorch-steps to read each step's logs in parts, to find where things first went wrong.
• No secrets: the two files go into the company repository. takeaway-redact deletes lines that look like secrets by knowledge.SECRET_RULES (the same rules as the knowledge source scan). When both files end up empty it fails, so the commit does not run.
• How risk-rules sees this commit: it comes after the last review round, but it does not count as a "commit that was not reviewed": a commit with a single parent that changes only .md files under myorch/ is not counted. Merge commits are always counted. risk-rules takes head_sha after this commit, so what you approve and what is pushed is the commit with these two files.
• When it is not written: replays (at) do not write it; otherwise the eval case's answer would get into knowledge. It is also not written when develop decides no change is needed. A run that fails before approval cannot be pushed, so its lessons are not in the repository.

Risk and approval

Risk is decided by the change, not by the author. Two classifiers back each other up: rules may miss semantic risk, the model may miss path-based risk, and the stricter of the two wins.

risk-rules (deterministic script):

• The rules come from the project pack's risk-rules.yaml (the template's rules plus the project's own). Of the rules that match, the strictest applies. Rules can match by path, by text in new files, or by a regex on changed lines. When no rule matches, default applies.
• At least 1 approver in any of these cases: the last review round still has unresolved Important findings; the last round's checks failed; there are new commits after the last review round (for example after accepting when the loop ran out of rounds, so nobody looked at the last round's fixes). The takeaway commit does not count; see the previous section.
• Outputs approvers (the number the rules require) and available (the number of approvers registered for the project).

classify-risk (agent, read-only): reads the actual diff, the requirements document, the assumptions in the implementation record, the last review round and checks, and the commits that were not reviewed, and decides 0, 1 or 2 approvers. Any one of these means 2: changes to interfaces or data, changes to build or deployment, anything security-related, hard to undo, affects downstream. It writes docs/risk.md: the verdict, the impact, unresolved problems, and 3 to 5 places the approvers should check. The project's prompts/risk.md is appended to the end of the prompt (myorch uses it to require that the impact be written in terms of the platform's boundaries, unfinished runs, and deployment).

Number of approvers for human-review:

min(approvers registered for the project, max(risk-rules count, min(classify-risk count, 2)))

• All three projects currently register only one approver, so the number is at most 1.
• mdm: the core-ng template's default is 1. Database migrations, interface modules, build and dependencies, CI and deployment, environment config, entity field annotations and destructive SQL need 2. mdm's protos submodule needs 2 and spec documents need 1. So every run needs exactly 1.
• blog: default: 1; every run needs 1.
• myorch: default: 0; the platform's boundaries (code for sandbox, credentials, profiles, deployment, scheduling and approval) need 2. When both judgments give 0 (for example only docs changed), approval passes automatically and deliver pushes the branch right away. Only the branch is pushed; merging and deployment are done by a person.
• The person who started the run must be one of the approvers (require_initiator). An agent's approval does not count.
• Approval is bound to a commit: head_sha is recorded when approval opens, and deliver checks it before pushing.
• Request changes: back to review-fix, at most 2 more rounds. Then takeaway, the risk verdict and approval run again from the start.
• After 24 hours with no action, one reminder is sent. After 7 days with no action, the step fails ("approval timed out" (审批超时)) and nothing is pushed.
• If any approver rejects, the run ends.

Delivery

Defined in lib/deliver.yaml.

• It refuses to push when the current branch is the base branch. It refuses to push when HEAD is not the approved commit; the run must be redone and approved again.
• Pushes the branch (normal push, no force push). Does not call the GitHub API and does not open a PR.
• Writes docs/delivery.md: title and ticket, what changed (taken from "Changes" (改动) in the implementation record), how it was verified (check results, acceptance criteria table), number of review rounds and unresolved problems, commits that were not reviewed, the risk verdict and the places to check, how to undo.
• outputs.delivery carries the branch, base, commit, title, ticket, the delivery note and the repository's PR template. The run_finished event carries it, and the console and Slack use it to tell you which branch was pushed. You open the PR.

Continue (from_run)

The general procedure is in Continue on the same branch. In this flow:

• checkout-branch mounts the previous run's workspace read-only and starts from its last commit. If someone added commits to the remote branch of the same name, it starts from the latest remote commit. If the two have diverged, it stops and a person must sort it out first.
• Files copied to docs/previous/: requirements.md, design.md, implementation.md, risk.md, delivery.md, external-request.md (the previous original request), the last review round's review-summary.md, and RUN with the previous run ID. Earlier runs are in earlier/. conversation.md is written by the host: what people said to the previous run.
• develop's requirements document states the full requirement, with a separate paragraph "This change" (这次的修改) under "Goal" (目标). The previous acceptance criteria still hold unless this request changes them. The design is changed on top of the previous one. The code is changed on top of the existing commits, not redone. Human decisions in conversation.md take precedence over assumptions in the previous documents.
• checkout-branch outputs since (the commit at the start of this run). Round 1 of the review loop looks only at commits after since; checks still run on the files the whole branch changed against base. The risk verdict looks at the whole branch.
• It pushes to the same branch, so a PR that is already open updates automatically. If no ticket number or incident is given, the previous ones are reused.
• Cannot be combined with at.

Replay (for evals)

Used to redo an already merged ticket on the code as it was then, and compare with the merged PR. The form shows at, ticket_as_of and ticket_comments only for projects with Jira (on the command line, -i at= can be passed for any project). Leave them empty normally.

• at is the PR's merge-base. checkout-branch creates the branch from this commit, then deletes the origin remote, all other refs, FETCH_HEAD, the reflog and borrowed objects, runs gc, and does the same for submodules. Later commits would leak the answer, so only history reachable from at stays in the repository. Finally it points origin/<base> at at, so every later diff uses it as the base.
• ticket_as_of is the moment work on the ticket started (ISO time). fetch-ticket uses the ticket's changelog to roll title, description, status, priority and assignee back to that moment. It keeps only earlier comments, attachments and linked tickets, and leaves out subtasks (subtasks may contain the solution).
• A replay never asks for approval and never pushes: the conditions of human-review and deliver include not inputs.at. Deleting origin is a second safeguard. No takeaway is written either. The run ends after classify-risk.
• Cannot be combined with from_run; checkout-branch fails right away.
• To find out whether the ticket description alone is enough, add -i ticket_comments=none.
• Comparisons: a replay can change this run's flow settings with --set, for example --set flows.development.reviewers=1 or --set flows.ablate=nit-cap (removes one marked rule; rule names are in rules/registry.yaml). Only existing settings under flows. can be changed, and only in replays. What was changed is recorded in the mandate, and the run gets a set:… tag so variants can be grouped. myorch expand --set … shows the changed prompt first.

Differences by project

There is only this one flow. Before 2026-11-10 each project had its own copy (ck-development, blog-development, mo-development). The same improvement had to be made three times, and the three copies soon diverged, so they were merged back into one (docs/notes/2026-11-10-one-set-of-flows.md). The differences between projects live in the project pack myorch-knowledge/<project>/ and take effect when the flow is expanded:

• flows.development in project.yaml: reviewers (default 3), max_rounds (3), security (true), on_exhausted (ask), takeaway (false), incident (false). A template can set them; the project overrides the template.
• prompts/<slot>.md: the slots are develop, review, verify, fix, risk. The template's comes first, then the project's, appended verbatim to the prompt of the matching step. The mandate's snapshot shows the assembled prompt. A file name that is not one of these slots is an error.
• if: in the flow: drops steps and inputs per project. fetch-ticket, the ticket input and the replay inputs depend on project.jira.url; the four takeaway steps on flows.development.takeaway; the incident input on flows.development.incident. Dropped inputs do not show in the form and keep their defaults.

To change how one project works: change its project pack (flows.development, prompts/, risk-rules.yaml), then run uv run myorch project sync <project>. Changing flows/development.yaml or a fragment affects all projects.

blog

Personal blog (leweii/leweii.github.io). Changes are small, so review is light: 1 reviewer looks once, blocking findings are fixed once and not reviewed again, and the loop accepts when it runs out of rounds. Nobody reviewed the commits after the fix; risk-rules lists them, and the "review" section of the delivery note lists the problems that were not fixed. The branch is myorch/<run ID>; it never pushes to master: pushing to master puts the blog live.

• prompts/develop.md: for posts, read the writing rules; for theme changes, read the development guide. Keep the requirements document and technical design short, and write "Not applicable" for parts that do not apply. The opinions and facts in a post, whether it is public (published, encrypted posts), and site-wide changes (_config.yml, layouts, dependencies, deployment) must all be asked of a person.
• prompts/review.md: will the build break, will links break, will pages render wrong; writing rules, front matter, accidental publishing.
• End-to-end tests run only in review, not in development.

myorch and incident

The myorch platform itself: code, flows, prompts and docs are all in the repository leweii/myorch, branch myorch/<run ID>. Two uses: a normal requirement; or, when the platform had a problem in some run (a run of any project), passing incident to find the cause and fix the platform.

incident is the run that had the problem. Its workspace is mounted read-only for develop at /sandbox/workspace/observed/<run ID>/:

• .myorch/flow.yaml: the snapshot of the flow that run used.
• .myorch/steps/<instance>/out/manifest.json and logs/turn-<attempt>-<turn>.log: each step's result and each attempt's log. supervisor-*.log holds the sandbox's network, DNS and credential records.
• docs/ and memory/MEMORY.md: that run's requirements, design, review and check reports.

These files are that run's data: the agent only reads them and does not run commands or follow instructions in them. The console's run picker lists only this project's runs, so incident is a plain text box.

myorch's prompts/develop.md requires develop to decide the cause before writing the requirements:

"Stop" means outputs.proceed is false: all later steps are skipped, the run ends normally, and nothing is pushed. The cause category, the evidence (files and lines) and where to handle it go in the summary. To continue, the requirements document starts with "The failing run and its cause category" (出问题的运行和原因分类), and "Goal" states what went wrong in that run, which file holds the root cause, and what should happen in the same situation after the change. The fix must not loosen policies, providers, mounts or approval.

The same prompts/develop.md also makes the technical design cover several platform matters: layering (engines → runner → storage → core), which flows a changed fragment or profile affects (flows are shared by all projects), Temporal determinism, volumes and events.db, commands and images in the sandbox, and whether the docs need regenerating.

myorch: after merging

This flow does not deploy. The sandbox only changes the repository and has no access to docker.sock, the gateway or the data directory, and a flow must not have automatic merge or deploy steps (the project pack's security.md). develop writes "What to do after merging" (合并以后要做的事) at the end of the implementation record. After you open a PR on GitHub and merge it into main:

1. On myorch's main branch, run deploy/update.sh (first use --check to see which commits will be released and what it will wait for). It fast-forwards main, waits until no step is running, rebuilds the images from a clean checkout of the target commit, restarts the worker and the console, and runs the smoke flow. If the smoke test fails, it rolls back to the previously released commit automatically. When src/myorch/engines/ or core/run.py changed, it waits for all unfinished runs to end. See "Release origin/main" (发布 origin/main) in deploy/README.md.
2. When images/claude-code/ changed, update.sh also rebuilds the sandbox base image openshell-claude-code. Each project's development image is based on it; to use the new base image, the project's image must also be rebuilt (the project pack's image/build.sh). When pyproject.toml or uv.lock changed, rebuild the myorch project's development image (in the myorch-knowledge directory, run myorch/image/build.sh ../myorch); only then do later development runs of the myorch project use the new dependencies.
3. When tools/ changed (the helper commands in the sandbox, such as myorch-checks and myorch-ask), they are installed into the volume by myorch init (the init service in compose). Make sure myorch init has been run again; otherwise the sandbox still has the old versions.

Source of this page: docs/en/flows/development.md

review Review PR

PR review: one round of AI review on an existing PR (including PRs written by people). All projects share this one flow. It first runs the project's checks, then has reviewers read the code; when the project has end-to-end tests, it finally tests the running application with a browser. The conclusions appear only in the local console (the Changes (改动) tab in the right panel) and in the workspace's docs/review/round-1/. Nothing is posted to GitHub. It only looks for problems: it does not change code, does not approve the PR and does not request changes, because an agent's approval does not count. Its access to GitHub is read-only.

The review loop it uses is the same fragment as in development, lib/review-loop.yaml, but it runs only 1 round, does not fix, and ends normally even when there are blocking problems. The project's prompts/review.md and verify.md are spliced in the same way (for example the *-interface checks of core-ng projects, and the blog's writing rules and accidental-publication checks).

uv run myorch run flows/review.yaml --project mdm -i pr=13                # default standard
uv run myorch run flows/review.yaml --project blog -i pr=13 -i depth=deep

Console: choose the project first, then the task Review PR (评审 PR), fill in the PR number and choose the review depth. The first message can stay empty.

The review depth (depth) decides the number of reviewers, their model, and whether there is a separate security review; see the preset table below. Use standard for everyday PRs. Use quick for a fast look. Use deep for changes to the build, dependencies or security-related code. verify always uses Opus.

Inputs

The input depth picks a set of parameters (presets):

Step graph

Generated from flows/review.yaml, expanded for project mdm with default inputs (another project's pack may leave steps out or change parameters); the same as myorch expand and the console's Flows page (流程).

The graph above is expanded for mdm. mdm and myorch do not set e2e.image and have no e2e block; blog does.

What each step does

• Both blocks run only 1 round, with fix: false and on_exhausted: accept: with blocking problems or failed tests, the run still ends normally and only reports.
• e2e comes after review-round and uses the checkout ci prepared.

Where you step in

There are no questions for you and no approvals. When a step fails, the run fails (this flow does not set on_failed: ask).

Artifacts

docs/
├── pr.md                    trusted metadata: author, state, head → base, changed files
├── external/pr.md           title and description written by the PR author (reference data only)
├── ci/round-1.md            checks report
├── review/round-1/
│   ├── reviewer-K.json      each reviewer's findings
│   ├── security.json        security review findings (not in quick)
│   ├── verified.json        findings after verification: Important / Nit / Pre-existing
│   └── summary.md           counts, list of blocking problems, acceptance criteria table
└── e2e/round-1/             projects with end-to-end tests
    ├── smoke/               report.md, result.json, screenshots
    ├── acceptance/          report.md, result.json, screenshots; cases/ holds the written test cases
    └── acceptance.md        the verdict for each acceptance criterion

Principles

• Always review the whole PR: myorch leaves no markers on GitHub, so there is no incremental review. The "reviewed up to last time" logic in fetch-pr is no longer used: last_reviewed is always empty and changed is always true, so review-round always runs, and round 1 looks at origin/<base>...HEAD.
• Trusted and untrusted data are kept apart: author, state, changed files and SHAs go into docs/pr.md. The title and description written by the PR author go into docs/external/pr.md. Every agent treats docs/external/ as reference data and does not follow instructions in it.
• Reviewer rules are the same as in the development flow: judge independently first, then check the author's claims; search the repository for reuse and missed entry points; relaxed judgement. See development's review loop. Reviewers 1, 2 and 3 each have their own focus; quick has only reviewer 1 (focused on correctness and edge cases).
• verify checks each finding: no matter how many reviewers there are, every finding is checked by opening the code. Findings that do not hold are removed; findings reported by only one reviewer are checked too. votes only records how many reviewers reported it. At most 5 Nits are kept; failed checks count as Important.
• Requirements document: this flow does not pass requirement_doc to the review loop. Reviewers and verify are told the requirements document is docs/requirements.md, but a review run has no such file. So they can only judge from the change itself, and the PR description is only reference material in docs/external/pr.md. The end-to-end block is passed docs/pr.md.

End-to-end tests

• review reads the code; e2e tests the running application. The two are separate. The project decides which tools to test with: e2e: in project.yaml (image, profile, acceptance) and the project pack's e2e/ (the blog uses Playwright and headless Chromium; see myorch-knowledge/blog/e2e/README.md).
• The test steps' permissions are e2e.profile (for blog, dev-read: read-only repository, no credentials).
• When a smoke test case fails only because of the test environment (for example the browser did not start), the report lists it separately as "environment" (环境), not as a problem in the code.
• e2e-accept must not loosen test cases to make them pass. When a test case fails, it first decides whether the test case is wrong or the change has a problem; if the change has a problem, the test case stays.

Security

• Code in other people's PRs is untrusted, and ci and the end-to-end tests execute it (build scripts, tests, lint configuration). The steps that execute PR code (ci, e2e-smoke, e2e-accept) and the reviewers that read the code get no GitHub credentials, and run in sandboxes that are deleted after use.
• The one step with credentials (fetch-pr) runs only scripts fixed in the flow and executes no code from the PR. It only reads: fetches code, reads the PR.
• The remaining risk is prompt injection: PR content may lead reviewers to misleading conclusions. Conclusions are shown only on the local machine and not posted to GitHub.

Source of this page: docs/en/flows/review.md

postmortem Postmortem

Analyses a problem that already got into the project's code: finds the commit that introduced it, works out at which layer it should have been stopped first and why it was not, proposes knowledge changes, and turns the change into an eval case. Use it after the problem is fixed (or reverted), when you want to know why it was not stopped at the time.

It only analyses and does not change project code; to fix the bug, use development. The only things it changes outside are the local myorch-knowledge (the proposals you adopt) and the local eval set (myorch-data/evals/cases/). The difference from learn: learn looks for patterns across a batch of runs; postmortem works backwards from one concrete problem. learn later reads postmortem's conclusions too.

uv run myorch run flows/postmortem.yaml --project mdm -i commit=<fix or revert commit>
uv run myorch run flows/postmortem.yaml --project mdm -i bad=<commit that introduced the problem>

Console: choose the project first, then the task Postmortem (复盘), and fill in one of Fix or revert commit (修复或 revert 提交) or Commit that introduced the problem (引入问题的提交). The first message can describe the problem's symptoms and impact, or stay empty. If you write one, it is stored as docs/external/request.md, and analyze reads it.

Inputs

Step graph

Generated from flows/postmortem.yaml, expanded for project mdm with default inputs (another project's pack may leave steps out or change parameters); the same as myorch expand and the console's Flows page (流程).

Inputs

• Give either commit or bad. When neither is filled in, the run does not start. When both are filled in, bad wins and commit is treated as the fix commit.
• The commit does not have to be on a branch (for example an unmerged PR): locate fetches it from GitHub by SHA.
• runs does not need to be filled in. At start the client fills in this project's newest development and review runs (at most 20; ended, failed and cancelled all count), and locate picks out the ones that touched this change.

What each step does

<id> is the last part of this postmortem run's ID. For example, the replay of postmortem-1a2b3c4d is eval-1a2b3c4d-before.

locate: how it finds the commit that introduced the problem

• When the commit that introduced the problem is a merge commit, the comparison base is its first parent, so the whole PR is looked at.
• The full-history clone lives outside the workspace (/tmp). The history that contains the fix does not enter the run's workspace.
• Runs that touched the change: runs whose branch has this commit while the base they started from did not; or runs whose linked PR is this commit's PR.
• The requirement is taken from requirements.md (or pr.md) of the first run that touched it. When no myorch run touched it, the commit message and the PR title and description are used.
• When it cannot find it, the step fails and says why: the commit is not in the repository; the lines the fix changed have no traceable origin (then use -i bad= to name it directly); the commit that introduced the problem is the repository's first commit.

analyze: the layer that should have stopped it, and why

• When no myorch run touched the change, the question is: had it gone through myorch at the time, which layer should have stopped it.
• At most 5 proposals, in the same format as learn (exact replacement or append), changing only guide/. Rules must be written so that they apply to the same kind of problem, not only to this one bug.
• Proposals better done as lint, CI or tests go into follow-ups.md and need a separate development run.
• case.json contains only the problems a reviewer should find from the change itself. When category is not-detectable, or only CI could find it, it is [].

Replays and the eval case

A replay is a separate eval run (the eval flow, evals.py). The reviewer there sees only the change itself and the requirement, not this run's workspace: not the incident description, the fix, the analysis or the expected findings. The eval run clones the repository from GitHub, checks out the commit that introduced the problem, and deletes later commits (including the fix), branches and the reflog.

The case ID is this postmortem's run ID, stored on the local machine in myorch-data/evals/cases/<run ID>.json. This is how it reaches the eval set:

• The case page shows how many findings each of the two replays caught. Before confirmation, all findings in case.json count; after confirmation, the ones you marked.
• To compare this run's two replays on the command line: uv run myorch eval report --batch <postmortem run ID>. It scores only against the findings you marked, so confirm the case first.
• Both replay steps are idempotent: a replay that was already started is not started a second time.
• A replay is another run; if it fails, the postmortem itself is not affected. Look at the eval run for the cause.

Where you step in

• Replies are written the same way as for learn: 1,3, 1、3, all, none; if the reply cannot be understood, it asks again. The details are in docs/postmortem/proposals.md.
• When nothing is adopted, the knowledge is not changed and there is no second replay.

Writing back to the project pack

Uses the same host action project-apply as learn, also with scope: learn. For the rules see learn's "Writing back to the project pack": write only when everything validates, commit only the files it wrote, the commit message is learn(<project>): … with myorch-run: <run_id>, re-sync the snapshot after writing, git revert is possible.

The only difference is which files are read: the proposals are in docs/postmortem/proposals.json, the adopted numbers in docs/postmortem/accepted.json. The prompt lets analyze change only guide/; the action itself validates against learn's scope and also accepts checks.sh and checks.env.

Artifacts

All under docs/postmortem/ in the workspace. The Docs (文档) tab in the console's right panel shows them, or use uv run myorch ws <run> docs/postmortem.

docs/postmortem/
  target.json            the commit that introduced the problem, base, fix, PR, runs that touched it, requirement
  bad.diff, fix.diff     the change that introduced the problem; the fix (sometimes)
  trace.json, trace.md   what each layer saw at the time
  postmortem.md          conclusion: the problem, the layer that should have stopped it and why, evidence, proposals
  proposals.json, proposals.md, accepted.json   knowledge proposals, the numbers you adopted
  follow-ups.md          proposals for deterministic checks that need a separate development run
  case.json              the expected findings for the eval case

Source of this page: docs/en/flows/postmortem.md

sweep Find bugs

Finds bugs in a project's existing code. All projects share this one flow. Each run looks at a batch of files in a fixed order, with several auditors in parallel, verifies the findings and writes a daily report. It suits nightly schedules that work through the whole repository batch by batch.

It is observe-only: it writes only the daily report docs/sweep/report.md. It does not change code, does not push, does not start development and does not change the knowledge. To fix a problem it found, a person starts a separate development run. The difference from review: review looks at a PR's change; sweep looks at code already on the main branch.

uv run myorch run flows/sweep.yaml --project mdm                     # run once, audit depth defaults to standard
uv run myorch run flows/sweep.yaml --project mdm -i depth=deep
uv run myorch schedule add nightly-sweep-mdm --flow sweep --project mdm --cron '0 2 * * *'   # every night at 2:00

Console: choose the project first, then the task Find bugs (找 bug), and choose the audit depth. The first message is not needed.

Inputs

The input depth picks a set of parameters (presets):

Step graph

Generated from flows/sweep.yaml, expanded for project mdm with default inputs (another project's pack may leave steps out or change parameters); the same as myorch expand and the console's Flows page (流程).

Which files it looks at

Decided by sweep: in the project pack's project.yaml (see 7. Project packs):

• The file list comes from git ls-files, sorted by path.
• mdm and blog currently have no sweep:, so they look at the whole repository, 20 files per run. myorch looks only at src/myorch, flows, tools and deploy (not src/myorch/ui/static/vendor/**), 15 files per run.
• sweep reads the configuration from the project pack snapshot. After changing project.yaml, run uv run myorch project sync <project>.
• When the configuration selects no files at all, pick fails.

What each step does

audit: what it looks for

• Correctness (logic errors, missed edge cases, unhandled errors, mismatches with docs or comments), security (injection, leaked secrets, unsafe defaults, missing permission checks), errors users see (broken links, wrong data or display).
• Each auditor has its own focus: auditor 1 looks more at correctness and edge cases, auditor 2 at security and error handling, auditor 3 at whether docs and data agree.
• Not reported: code style, naming, things that could be written better but are not wrong, missing tests; known issues; code outside this batch of files (used only to understand context).
• There are only two severities: Important (wrong behaviour, wrong data, security problems; worth having someone fix) and Nit (really a problem, but with small impact). Findings it is not sure about are not reported.
• When there is a guide/review-guide.md, it follows its standards.

verify: verification

• Each finding is checked by opening the code; findings that do not hold are removed.
• The same issue reported by several auditors is merged into one, and votes is the number of auditors who reported it. Findings reported by only one auditor are kept if they hold.
• Findings that are the same issue as one in known.json are removed.
• The daily report: with no new issues, it has only the sentence "No new issues found in this batch of files." (这批文件没有发现新问题。), followed by the directories that were looked at. With new issues, the first sentence gives the number of Important and Nit findings, then lists each one by severity with its location, the problem, the consequence and a suggested fix. No process notes, no pleasantries.

State across runs

State across runs lives in the project's shared directory shared/<project>/sweep/ (on the myorch storage volume). Only pick and record mount it.

• The cursor moves forward only after the whole run succeeds. record is the last step. If any earlier step fails, it does not run, and the next run scans the same batch again.
• After the last file it starts over from the beginning, so it can keep running on a schedule.
• The cursor is a position in the sorted list, not a file name. When files are added or deleted, the start of the next batch shifts by a few files: a few may be skipped or looked at twice, and the next pass makes up for it.
• Known issues are deduplicated twice: verify decides by meaning whether two are the same issue, and record then removes exact duplicates by the file|title fingerprint.
• known.json only grows. To scan from the beginning, delete cursor.json. To have an issue reported again, delete its entry from known.json. Each run's workspace also has a copy from that time in docs/sweep/known.json.

Where you step in

You are not needed while it runs. To read the daily report: open the run in the console and find docs/sweep/report.md under the Docs (文档) tab in the right panel; or uv run myorch ws <run> docs/sweep/report.md. For issues worth fixing, start a separate development run.

Scheduled runs

• --flow takes the flow name sweep. For a different audit depth, add -i depth=quick or -i depth=deep.
• When the run started by the previous schedule is still running, this one is skipped, so two runs never move the cursor at the same time. Do not add --allow-overlap: two runs would scan the same batch, and the one that ends later could overwrite known.json.
• The run's starter is the person who created the schedule. uv run myorch schedule list shows when it runs next; pause, unpause and delete manage it; trigger runs it once right away.

Artifacts

docs/sweep/
  chunk.txt          the files looked at this time, one per line
  known.json         copy of the known issues at start
  audit-<n>.json     each auditor's findings
  verified.json      new issues after verification
  report.md          daily report

Source of this page: docs/en/flows/sweep.md

learn Learn

Turns a project's past runs into knowledge, so that the next run knows it from the start. All projects share this one flow. It turns various signals into proposals for changing the project pack. You pick which ones to adopt, and it writes them back to myorch-knowledge/<project>/. When the knowledge gets more accurate, every later development and review run benefits.

It only changes the local myorch-knowledge: guide/, checks.sh, checks.env. It does not push, does not touch the project repository and does not change flows (proposals about flows are only written to a file). The difference from postmortem: postmortem works backwards from one problem that slipped through; learn looks for recurring patterns across a batch of runs.

uv run myorch run flows/learn.yaml --project mdm                                                 # pick runs automatically
uv run myorch run flows/learn.yaml --project mdm -i runs=development-b947d694,review-5d5a21ec     # pick runs by hand
uv run myorch schedule add weekly-learn-mdm --flow learn --project mdm --cron '0 9 * * 1'         # every Monday at 9:00

Console: choose the project first, then the task Learn (学习). Runs to learn from (要学习的运行) can stay empty. The first message is not needed.

Inputs

Step graph

Generated from flows/learn.yaml, expanded for project mdm with default inputs (another project's pack may leave steps out or change parameters); the same as myorch expand and the console's Flows page (流程).

Which runs it learns from

When runs is not given, the client that starts the run picks them (the same for the command line, the console, Slack and schedules):

• development, review and postmortem runs of this project that started after the last completed learn;
• only runs that have ended (succeeded or failed); cancelled runs do not count;
• at most 20, the newest. observe_runs mounts at most 20 workspaces.

The command line lists the chosen runs before it starts. When there is no new run at all, the run does not start and reports "no new ended development / review run" (没有新的已结束的 development / review run). uv run myorch list --project <project> shows which runs exist. To pick by hand, use -i runs=<id>,<id>.

A failed or timed-out learn does not count as completed. The next learn picks the same runs again.

Which signals it reads

What each step does

collect: what happened to the findings

Findings already marked fixed do not count. Each of the others is checked in the order below, and the first that holds wins:

myorch no longer posts comments on PRs, so there is no "someone replied to the comment" outcome. Outcomes come only from the runs' own records and the PR state.

collect: takeaways in the repository

• When the project sets flows.development.takeaway (currently only mdm), development commits task.md and takeaway.md with each change to myorch/<date>-<run_id>/. They reach the base branch only after the PR is merged, so only merged ones can be read. Other project repositories have no such directory, and this kind of signal is empty.
• When the workspace has no repository, collect makes a shallow clone without checking out files and reads them one by one with git show.
• Learned ones are skipped, and reading starts from the oldest. At most 30 entries and 300 KB per run (the first one is always read); the rest wait for the next run. The digest says how many are left.
• An entry whose takeaway.md cannot be read (network problem, empty file) is not read and not marked learned; the next run tries again. After 3 unreadable entries in a row it stops. Directories whose name is not <date>-<run_id> are skipped.
• When the repository cannot be read, it records only a fixed sentence and the git exit code, without the command line or git's output. learn carries on.
• Which ones were learned is recorded only on the local machine in myorch-data/learn/<project>/takeaways.json (takeaways.py). Nothing is written to the company repository or to myorch-knowledge.

analyze: which kinds of knowledge it looks for

At most 8 proposals. With too little evidence it proposes fewer or none. It does not repeat what the knowledge and the repository's own docs already say. The wording is short and follows the style of the existing files.

Two more files are never applied: follow-ups.md holds proposals for changing the project repository itself (lint, CI, tests), which need a separate development run; flow-proposals.md holds proposals for myorch flows (step order, when to ask questions, steps that always fail or are not needed).

Takeaways are treated as signals and checked like other evidence: only project knowledge that generalises to later work is adopted, not what holds only for one ticket. Evidence is written as <run_id>: takeaway. Proposals about flows, the platform or the environment go into flow-proposals.md.

Each proposal's change is written as an exact replacement (edits: old copied verbatim from the current file and occurring exactly once in it) or an append (append). No diffs, because diffs written by agents often have wrong line numbers.

Where you step in

• The question has one line per proposal, with its type and the number of pieces of evidence. The details are in docs/learn/proposals.md: the Docs (文档) tab in the console's right panel, or uv run myorch ws <run> docs/learn/proposals.md.
• Reply with the numbers only: 1,3, 1、3 and 1 3 all work. all or 全部 adopts all of them; none, 无 or 0 adopts none. When a number does not exist or the reply cannot be understood, it asks again.
• Once the reply is accepted, it starts running and cannot be changed. To adopt more, run learn again or edit the project pack by hand.
• Without a reply for 24 hours, this step times out and fails. A scheduled learn also stops here and waits for you.

Writing back to the project pack

apply is the host action project-apply with scope: learn (actions.py, project.py). The sandbox cannot reach myorch-knowledge, so this happens on the host.

• It writes only the project's own directory myorch-knowledge/<project>/. Templates (for example mdm's _templates/core-ng/) stay unchanged. A file the project only inherits from the template is first copied from the template on its first change, then changed.
• All adopted changes are validated in memory first: the path is within the allowed scope, does not escape the project pack, and each old occurs exactly once. If anything fails, nothing is written. The step fails and lists the reasons.
• After writing, it commits in myorch-knowledge, committing only the files written this time (changes someone else staged are not included). The commit message is learn(<project>): #1 title; #3 title, and the body has myorch-run: <run_id> step: apply and the adopted numbers.
• Then it re-syncs the project pack snapshot. Runs that start after that use the new knowledge, and the project pack version recorded in the Mandate changes with it. Runs in progress keep using their own snapshots.
• Idempotent: when it finds this step has already committed, it counts as succeeded and does not write a second time.
• If a proposal works out badly: git revert <commit> in myorch-knowledge, then uv run myorch project sync <project>.

Artifacts

All under docs/learn/ in the workspace. The Docs tab in the console's right panel shows them, or use uv run myorch ws <run> docs/learn.

docs/learn/
  trail.json                 written at start: questions and answers, comments, rejections, failures, re-runs from the event log
  takeaways-learned.json     written at start: run_ids of takeaways already learned
  findings.json, outcomes.md findings and their outcomes, statistics table
  signals.json, signals.md   signals other than review
  takeaways.json, takeaways/<date>-<run_id>/   takeaways read this time
  proposals.json, proposals.md                 proposals
  follow-ups.md, flow-proposals.md             proposals that are not applied automatically
  accepted.json              the numbers you adopted

Scheduled runs

The --flow of myorch schedule add takes the flow name learn. Schedules start runs through the same path as the console, so automatic run selection and writing trail.json and takeaways-learned.json work the same.

• When the run started by the previous schedule is still running (for example still waiting at choose), this one is skipped. To run both at once, add --allow-overlap.
• When there are no new runs, this one does not start a run. This holds even when the repository has new takeaways, because takeaways are only read inside a learn run.
• The run's starter is the person who created the schedule. uv run myorch schedule list shows when it runs next; pause and delete stop it.

Source of this page: docs/en/flows/learn.md

eval Eval

Scores the reviewer. It replays the change that a past review looked at, unchanged, and lets the reviewer look at it again. It compares the result with the real issues a person confirmed and counts how many were caught, how many were missed and how many extra findings were reported. Use it after you change the reviewer's prompt, its model or the project pack's guide/, to tell whether things got better or worse. It writes nothing outside: it does not push, does not change code and does not change the project pack.

One eval run replays one case at one review depth. Collecting, confirming, batch-starting and scoring cases all happen on the local machine through myorch eval (src/myorch/evals.py). The flow itself only prepares the code and runs one review round.

uv run myorch eval collect                              # collect candidate cases from past runs
uv run myorch eval list                                 # cases and their state
# in the console under "Flows → Eval set", mark for each case which findings are real issues
uv run myorch eval run --depth quick --depth standard   # one eval per confirmed case and per depth
uv run myorch eval run --case <case ID>                 # run only one case (default depth standard)
uv run myorch eval report [--batch <batch>]             # comparison table

Do not start it from + New run (＋ 新运行) in the console or with myorch run. Only myorch eval run (and postmortem's replays) write the case into the workspace. When you start it directly, prepare finds no case and fails. The Slack start dialog does not list this flow.

Inputs

The input depth picks a set of parameters (presets):

Step graph

Generated from flows/eval.yaml, expanded for project mdm with default inputs (another project's pack may leave steps out or change parameters); the same as myorch expand and the console's Flows page (流程).

Where cases come from

A case is the change that round 1 of a past review looked at, plus the real issues a person confirmed. Cases are stored on the local machine in myorch-data/evals/cases/<case ID>.json.

postmortem also creates cases (origin: git). The change is the commit in the project repository that introduced the problem. It does not come from a myorch run, and the case ID is the postmortem run's ID. The postmortem starts these replays itself: once with the knowledge of the time, and, when you adopt the knowledge changes it proposes, once more with the new knowledge. myorch eval report --batch <postmortem run ID> shows them.

What each step does

The depths are the same three as in review. See the preset table above.

Not leaking the answers

• The answer key stays out of the workspace: myorch eval run writes only the case fields that may be seen into docs/eval/case.json: origin, source run, flow, repository, base and head commits, requirements document. The findings a person confirmed stay on the local machine in myorch-data/evals/cases/.
• Later commits are not kept: the source run's later fix commits would tell the reviewer where the problems are. So the repository keeps only the history reachable from head. Branches, remote refs and the reflog are deleted.
• Nothing outside is writable: after origin is deleted, no step in the replay can push.
• The reviewer also does not see the source run's technical design, implementation notes or the original ticket text. The workspace contains only the requirements document and the change. So the eval's review has fewer inputs than a review in the real development flow.

How scoring works

Scoring happens on the local machine, not in the flow:

• Only Important and Nit are compared, on both sides.
• Caught: a replay finding is in the same file as a marked finding and the line numbers differ by at most 10 (a match on any one location counts).
• Missed: marked findings that were not caught.
• Extra: findings the replay reported that matched no marked finding. They may be false positives, or real issues nobody flagged at the time. The number of Important ones among them is listed separately.
• report first lists each run (depth, case, caught/expected, extra), then sums up per depth: cases, expected, caught, missed, recall (caught ÷ expected), extra, extra Important. Postmortem replays are split into "depth·before" (强度·before) and "depth·after" (强度·after). Runs that have not finished are not counted, and a note at the end says how many are still running.

Where you step in

The run itself has no questions and no approvals.

Source of this page: docs/en/flows/eval.md

onboard Onboard project

Teaches myorch about a project. It reads the repository, tries the project pack's checks on the last few commits, and then proposes additions and fixes to the project pack. You pick which ones to adopt, and it writes them back to myorch-knowledge/<project>/. Later development, review and risk verdicts all depend on this knowledge.

Run it once when you take on a new project, and again when the repository structure changes a lot. It pushes nothing to the project repository and only changes the local myorch-knowledge. Like the other flows, it is shared by all projects. The difference from learn: learn learns from runs that already happened; onboard looks only at the repository itself and can change more files (checks script, setup script, approval rules, security focus).

uv run myorch run flows/onboard.yaml --project <project>
uv run myorch run flows/onboard.yaml --project <project> -i focus="database migrations"

Console: choose the project first, then the task Onboard project (接入项目). The first message is Focus areas (要重点看的地方) and can stay empty.

Inputs

Step graph

Generated from flows/onboard.yaml, expanded for project mdm with default inputs (another project's pack may leave steps out or change parameters); the same as myorch expand and the console's Flows page (流程).

Before you start

The project pack needs at least a project.yaml, and uv run myorch project sync <project> must have been run. The project's GitHub provider must be set up and the development image built. See 7. Project packs · Onboarding a new project for the steps.

focus is appended as is to analyze's task description, for example "frontend checks" or "database migrations", so that it spends more effort there.

What each step does

try-checks: trying the checks

• Purpose: see whether checks.sh finds the right modules, how long it takes, and which checks fail for reasons unrelated to the change (environment, network, cache).
• The sample change is the last 5 commits of the base branch. When the repository has fewer than 6 commits, it uses the whole history (starting from the empty tree). The changed files are listed in changed.txt.
• The checks run under the checks.sh conventions, with CHECKS_DIR set to docs/onboard/checks/.
• Failed checks, a failing setup.sh or a missing checks.sh are only recorded in the results; the step still succeeds. These are exactly what analyze needs to look at.

analyze: what it needs to find out

• Each conclusion names its basis (file paths).
• At most 8 proposals, of type fill-gap (add knowledge), fix-checks (fix the checks), fix-rule (fix the approval rules) or security (security focus).
• guide/ gets only what the repository's own docs do not say and what affects the agent's judgement. The wording is short.
• Questions that need a person to answer go into open-questions.md. The flow does not ask you these questions. After reading them, edit the project pack by hand, or run again with a focus.

Where you step in

• Read docs/onboard/report.md and proposals.md first: the Docs (文档) tab in the console's right panel, or uv run myorch ws <run> docs/onboard.
• Reply with the numbers only: 1,3, 1、3 and 1 3 all work. all or 全部 adopts all of them; none, 无 or 0 adopts none. When a number does not exist or the reply cannot be understood, it asks again.
• Once the reply is accepted, it starts running and cannot be changed. Without a reply for 24 hours, this step times out and fails.

Writing back to the project pack

onboard cannot change the development flow's per-project settings (flows.development in project.yaml, prompts/; see development's "Per-project differences"). A person changes them by hand when needed.

A change can be written in three ways: exact replacement (edits; old must occur exactly once in the file), append (append), whole file (content).

• It writes only the project's own directory myorch-knowledge/<project>/. The template _templates/<template>/ stays unchanged.
• guide/, checks.sh and setup.sh inherit by override: a file the project only inherits from the template is first copied from the template on its first change, then changed. So edits can quote the original text seen in the snapshot.
• risk-rules.yaml and security.md inherit by concatenation: the snapshot holds the template's content plus the project's content, and the project's own file holds only the project-specific part. So security.md uses only append, and risk-rules.yaml uses only content, writing the complete project rules file (a rules: list, optional default:). Syncing the snapshot joins it with the template's rules again.
• The other rules are the same as for learn; see learn's "Writing back to the project pack": write only when everything validates, commit only the files it wrote, re-sync the snapshot after writing, git revert is possible. The commit message is onboard(<project>): #1 title; …, and the body has myorch-run: <run_id>.

Artifacts

All under docs/onboard/ in the workspace.

docs/onboard/
  checks/
    changed.txt        files of the sample change
    report.md          checks.sh's report
    result.json        passed, failed, skipped
  report.md            project overview and conclusions, each with its basis
  proposals.json, proposals.md   proposals
  open-questions.md    questions for a person to answer
  accepted.json        the numbers you adopted

Source of this page: docs/en/flows/onboard.md

Fragments

Fragments are reusable steps or loops in flows/lib/. A flow refers to one with use:; it is expanded when a run starts. Syntax: User manual · 8. Writing flows. This table is generated from the fragment files.