Open source · MIT license
Agents got better. Conducting them needs a method too.
A software factory of AI agents that proves its work: parallel threads, verified results, and short decisions only when they matter.
A cycle with clear responsibilities
Define the goal and plan, implement in the worktree, check evidence and deliver through the core. Every phase has a contract; the result does not depend on trusting an agent’s report.
Read the guide →Your attention, where it matters
Choose #Classic, #Maestro or #Auto for the full cycle. #Fast handles small changes within its limits. Modes control pauses; permissions and evidence remain explicit.
Read the guide →Evidence before belief
Claims carry reproducible commands. A baseline separates existing failures from regressions. Independent CHECK and verified push distinguish implementation from delivery.
Read the guide →Context with provenance
OrkMind connects governed memory and Company Brain. Context informs decisions; it does not replace thread state or grant authorization.
Read the guide →Concepts
How the pieces connect
The host presents, the core verifies and the runtime implements. Learn the boundaries before conducting your first cycle.
Read the guide →Start with the environment
Install the CLI and check your project’s requirements. The documentation covers setup, phases and verification. @orkastery/cli 0.5.0.
Documentation →npm install -g @orkastery/cli
ork doctorPoint three agents at the same repositoryand they get in each other’s way,then report that everything went fine.
The challenge is conducting the work: maintaining a roadmap, isolating threads, asking for the right decision, serializing merges and rerunning every claim.
Orkastery takes that role. The method and code are public; evidence accompanies the work and can be rerun.
Evidence before belief
Human attention where it matters
Missing data stays visible
Context with provenance
Six phases no agent skips
In the full cycle, every phase has a contract. Select a phase to see what it delivers. #Fast has its own scope, limited to GO.
F1 · GOAL
what matters and how to prove it
Verifiable goal, impact map, success criteria and claims with verification commands. No implementation.
ork requires A claim without a command is rejected as claims.unverifiable.
F2 · PLAN
the route, with one home for each decision
Tasks, touch_paths, decisions D1..Dn in one place and executable verification per task. No implementation.
ork requires A plan without executable verification cannot enter GO.
F3 · GO
implementation, one slice at a time
Implement one slice at a time, with an atomic commit per task inside the thread’s worktree.
ork requires Leases constrain writes to the thread’s worktree.
F4 · CHECK
scrutiny, with a command to run
Verification against the baseline, code review, tests, security and performance.
ork requires Failed evidence produces typed reasons, including verify.regression or claims.failed, with actual output.
F5 · SHIP
merges, one at a time
Serialized merge, command-verified push, updated roadmap and rollback plan.
ork requires Push counts only when git ls-remote matches the local SHA.
F6 · MASTER
feedback from a person
MASTER log with typed postmortem, lessons and a human score from 0 to 5.
ork requires Scores require a reason in every mode.
The full cycle ends with a MASTER log. #Fast has a separate, limited GO-only contract. Implementation and delivery are distinct outcomes.
Parallel threads, serialized merges
ork-pagamentos
GO
own worktree · own ledger · own score
ork-relatorio
CHECK
own worktree · own ledger · own score
ork-publicacao
SHIP
own worktree · own ledger · own score
lease main-tree
one thread merges at a time
the others wait in a FIFO queue
SHIP with push verified by git ls-remote
Illustration of parallel deliveries. Inspect your project with ork board --all.
-
main-treethe serialized merge gate -
worktree-write:<thread>writes inside its own worktree -
path:<glob>reserved file scope -
board:<card>one owner per card at a time -
service:<porta>an exclusive local port
Typed leases have a TTL. Threads requesting the same scope wait in FIFO order. ork board --all shows the current work.
How much pause do you want? Write a #TAG.
Choose where the cycle waits for you. Claims, verification and policies apply in every mode.
-
- pause to decide
- goal, plan and evidence, with prior push authorization
- use when
- The ork init default: careful assumptions and verified delivery.
- session slugs
- goal, plan, f34, f56
-
- pause to decide
- assumptions
- use when
- A clear solution: pause once to agree on assumptions.
- session slugs
- f12, f345, master
-
- pause to decide
- no scheduled pauses
- use when
- Documentation, research, configuration, audits and migrations.
- session slugs
- full
-
- pause to decide
- no scheduled pauses; pushing to the base still needs authorization
- use when
- A small, clear request within the Fast limits. GO only.
- session slugs
- go
block that pauses for a human decision
block that proceeds with decisions recorded in the ledger
Modes change pauses. They never relax verification. Configure each block’s runtime, model and effort with ork setup.
Your attention where it is needed
- working
- waiting for a person
- ended, with recorded state
A live session may be waiting for a person. The radar distinguishes activity, human waiting and evidence of termination.
Inspect sessions before concluding that a thread is working. The result depends on current observations.
ork sessions hitlDon’t take our word for it. Run it.
Reproducible commands check the work in the actual tree. A baseline separates regressions from existing debt.
ork verify <thread>
npm --prefix core run test:ci
ork modos-
the agent makes a claim
A claim needs executable evidence.
-
claims.jsonl
A claim records the statement, file and command that proves it.
-
ork verify
Reruns the command at the actual HEAD, in the actual worktree.
-
baseline recorded before GO
passed before Becomes
verify.regression: the thread introduced a failure.already failed Recorded as existing debt, separate from regressions.
no baseline Produces
verify.failed, without guessing responsibility. -
blocked gate
A typed reason, actual evidence and a suggested fix.
ork fix openderives the fix specification from the verify result.
Typed gate reasons
Examples of core reasons. Read the current policy with ork retry policy.
-
artifact.missingcorrigir-dirigido -
claims.failedcorrigir-dirigido -
claims.unverifiablecorrigir-dirigido -
verify.regressioncorrigir-dirigido -
verify.failedcorrigir-dirigido -
tree.blockedsincronizar-worktree -
lease.busyreexecutar -
runtime.model-unavailablereexecutar -
runtime.unavailablereexecutar -
runtime.rate-limitedesperar-janela -
policy.violationescalar-humano -
human.pendingescalar-humano -
cost.violationsem-retry
cost.violation forbids automatic retries: retrying would spend again.
Context for the next session
ork gate next
When the phase ends, the gate evaluates context-window usage.
- runtime_reported
- estimated, from transcript
- reported by the host
- unavailable
When no source can measure usage, the result is same-session with decididoPor: ausencia-de-medida. Missing data never becomes zero.
no
Same session. Work continues in place.
yes
New session with a triaged handoff, carrying the context needed for the next step.
Three levels of context
-
Critical
Always inline: state, locked decisions, criteria and claims.
-
Important
A
path#anchorpointer with a retrieval condition (retrieve_when). Requests outside that condition return no content. -
Summarizable
A short summary with required provenance:
source,locationand the source file’s SHA-256.
With OrkMind available, pointers can resolve through memory. File fallback uses path#anchor, with a typed reason for degraded operation.
Learn from delivery
From 0 to 5, how thoughtfully was this delivered?
clean delivery along the planned route
Score demonstration; no rating is submitted. Actual scores require human authorship and a reason. Use ork master pedir to request a score through an authenticated channel; ork master --batch shows the queue.
Typed postmortem classes
Fixed identifiers let failures be grouped consistently:
- sem-falha
- erro-de-spec
- base-avancou
- conflito
- rate-limit
- modelo
- processo
- scope-creep
- outra