PLOWSHAREMarkdown: bounded judgment
A model conductor follows declared stages, tools, delegates, completion guidance and permitted returns. The shipped coding procedure moves through goal, specification, plan, test design, tests, code and review.
05 / BUILD & EXTENDSHAPE BEHAVIOR WITH EXISTING PRIMITIVES
Your idea.
Your system.
Begin with a role, skill, hook or procedure. Use an SDK when another application needs to participate. Extend the owning server capability when new durable behavior is required.
Start with the
smallest useful change.
Most new behavior can reuse the platform’s existing lifecycle and access controls. Choose a boundary around the capability you actually need.
| You want to add | Start with |
|---|---|
| A specialist role or tool combination | Agent or bot Markdown definition |
| Reusable instructions and supporting resources | A skill package with explicit caller grants and context mode |
| A repeatable procedure with checks | Markdown or JavaScript orchestration |
| Lifecycle guidance, policy or notification | A hook at the documented callback tier |
| Continuing internal asynchronous work | A messaging instance and permitted project route |
| External observations or applications | Integration runtime or a narrow public SDK adapter |
| New server-owned durable behavior | The owning domain, typed operation contract and specialist repository |
Write the procedure.
Retain the run.
Describe input, output, evidence, human decisions and failure behavior. Give each stage a useful result and make the required verification explicit.
JavaScript: explicit sequence
A synchronous step function emits one host command and retained JSON state. It validates the previous result before advancing. The server journals commands and applies the same grants, hooks and gates.
Checks that mean something
A required command check can refuse stage completion when the build fails. Human acceptance remains a separate observation. Updating agreed requirements invalidates earlier acceptance rather than quietly moving the bar.
Author with Studio
The granted design workflow interviews you, writes a draft, trials its exact source and presents lint or refusal information. Installation requires a specific human answer. A successful trial is still distinct from a completed live procedure.
Install into the effective tier.
Use and build orchestrations ↗
Shipped, global, Personal, project and rooted-session definitions have documented resolution rules. Inspect definitions in the same project and session where they will run. Existing runs keep pinned source bytes and their hash.
Put policy where
the work happens.
JavaScript or supported erasable TypeScript hooks respond to documented lifecycle callbacks. They can guide a run, gate an action, annotate a result or request a notification.
Choose the seam
Prompt, tool, stage, approval, fold, delivery and log callbacks supply different context and permit different decisions. A tool policy can inspect a proposed edit; a stage gate can prevent completion or publication.
Choose the owner
Personal, project and attached local hook tiers have different inheritance and reload lifetimes. All hooks run on the server, including files supplied by a client. Local hook source is pinned when a log opens.
Handlers are synchronous and return permitted decisions as data. They have no arbitrary filesystem or network access, and cannot grant forbidden tools or undo an already committed external effect. Callback coverage differs by subsystem; use the placement guide for the chain you need.
Hook placement, events and authoring ↗One protocol.
Several languages.
Build clients and external adapters on the authenticated plowshare-v1 WebSocket contract. Operational requests preserve server authentication, project access and durable work identity.
| Language | Surface | Runtime |
|---|---|---|
| JavaScript / TypeScript | Typed operation catalogue and a ready-to-connect Node SDK | Node 22.12+ for Node transport |
| Java / JVM | Validated DTO clients with private WebSocket transport | Java 21+ |
| Python | Async generic client and convenience methods | Python 3.11+ |
| C# | Async generic client and convenience methods | .NET 8+ |
| Go | Context-aware generic client and convenience methods | Go 1.23+ |
Wire coverage and convenience
Generic native clients expose registered operations without recreating every response as a language-specific domain model. Calling an operation does not install a filesystem or process provider.
Delivery and reconciliation
Requests and replies are correlated and validated. Accepted work needs its status read. SDK clients do not automatically reconnect and replay operations; uncertain delivery stays visible so the caller can reconcile the existing identity.
SDK artifacts can be built locally. Remote package publication and Go discovery hosting are not configured in the current SDK guide. Configure server origins and adapter addresses explicitly, and keep adapters outside server internals.
SDK contracts, builds and conformance ↗Run what
you can inspect.
The source build uses Java 21, Node 22.12+, pnpm and Python 3. The server requires PostgreSQL with pgvector, configured providers and persistent storage.
Build the parts you need
Use the committed Gradle wrapper and documented module targets. Packaged clients are separate from the server. The initial native distribution target is macOS Apple Silicon; public release signing and additional native platforms remain follow-up work.
Distribution guide ↗Operate durable state
Preserve PostgreSQL, server data, workspaces and private configuration when replacing binaries. Verify authenticated operations, configured providers and relevant workflows alongside readiness. Upgrade and rollback need a coherent compatible backup set.
Server operation guide ↗Runtime contributions follow typed interfaces, strict boundary validation and specialist repository ownership. Automated checks, fixture conformance and live provider acceptance establish different evidence. Plowshare remains in active development.
Explore the Apache 2.0 source ↗