- Title: Kujo Foreman
- Tagline: AI writes code. Foreman decides whether it ships.
- Track: Professional Agents
- Intended users: Software engineers, release engineers, security engineers, and team leads who review changes produced by people or coding agents.
- Repository:
https://github.com/robertdevore/kujo-foreman - Project image: Upload
docs/foreman-live.png. - Architecture diagram: Upload
docs/architecture.png. - Video: Paste the public YouTube or Vimeo URL after upload.
- Live demo: Leave blank. The deployed AgentCore Runtime is intentionally private and IAM-authorized; the public repository includes a complete test build.
- Built with: Kujo, Strands Agents SDK, Amazon Bedrock, Amazon Nova Pro, Amazon Bedrock AgentCore Runtime, CloudWatch, TypeScript, React, Docker, and Git.
- AWS Builder ID: Enter the email address tied to the Builder ID.
Kujo Foreman is an autonomous release-readiness agent that verifies software changes, repairs bounded low-risk defects, and escalates only decisions that need human judgment.
- Install Node.js 22+, Git, and the matching Kujo 1.4.0 binary from
https://github.com/kujolang/kujo/releases/tag/v1.4.0. - Clone the public repository and run
npm run install:all. - Run
npm run dev, then runnpm run dev:webin a second terminal. - Open
http://localhost:4173and choose Run golden demo. - When Foreman stops at the payment-policy boundary, choose Authorize this
change. The run must finish as
READY_TO_SHIPwith complete evidence.
The static /preview route is labeled and is not the working demonstration.
AI can write a pull request in minutes. A developer still has to determine whether it satisfies the request, passes the right checks, preserves important boundaries, and has enough evidence to ship.
That work means reconstructing intent, understanding a diff, choosing useful checks, investigating risk, repairing what is unambiguous, and stopping when a product or security decision belongs to a human. Existing tools cover pieces of the process. Foreman owns the handoff from code complete to a release decision.
Foreman starts where coding agents stop.
Give Foreman a local Git change set and its intended outcome. It analyzes the change, turns intent into explicit acceptance criteria, constructs an adaptive verification plan, and runs independent verification and risk work in parallel. Checks execute through bounded Kujo capabilities; production binds that Ability to Workcell isolation. Results become typed, checksummed evidence rather than a prose claim.
When Foreman finds an exact low-risk defect, its Repair Agent can change only a Foreman-managed workspace, within deterministic file, line, time, and iteration bounds. It then reruns the affected checks. Auth, payment, permission, destructive-data, migration, secret, and production-policy changes cannot be guessed. Foreman creates a compact decision packet, pauses, and continues only after an exact human choice.
The final Kujo release judge returns one of four meanings:
READY_TO_SHIP, READY_WITH_NOTES, BLOCKED, or
HUMAN_DECISION_REQUIRED. Missing evidence always fails closed.
Foreman itself is written in Kujo. Kujo owns repository analysis, typed run artifacts, capability policy, deterministic verification contracts, bounded repair, final judgment, and release-evidence integrity.
A narrow TypeScript service uses Strands Agents substantially and visibly. A native Strands Graph coordinates specialist agents, uses a real parallel verification/risk fan-out with AND-semantics fan-in, shares invocation state, streams lifecycle events, enforces step and time bounds, and routes through repair, re-evaluation, or escalation. The deployed private runtime uses Amazon Nova Pro through Bedrock on AgentCore Runtime, with CloudWatch logs and structured lifecycle events.
Kujo capability profiles give each operation a stable identity, declared effect, scope, and receipt. Each specialist sees only its profile. Workcell defines the production isolation contract; the submitted demo uses an explicitly labeled managed Git workspace. Kujo Spec semantics shape acceptance criteria, and Kujo Eval's suite format measures the seven expected release outcomes. Other Kujo tools remain optional repository-specific adapters rather than decorative calls.
The UI is a focused release-control surface built with React and the Kujo SiteKit visual system. It renders real graph events, current authority, verification lanes, repair evidence, human decisions, and the final artifact; it is not a chatbot.
The hardest problem was keeping model judgment useful without letting it become the release gate. Our answer was a two-key design: Strands interprets and coordinates, while Kujo requires deterministic evidence completeness before a release can pass.
The second challenge was capability truth. Declaring a tool “safe” is not enforcement. We separated portable Ability effects from Workcell's production execution boundary, bound repairs to exact file digests, and made human approval incapable of bypassing path containment.
The third was human escalation. A long agent transcript is not a product. We designed escalation as a small decision object containing the decision, stop reason, evidence, options, recommendation, and confidence.
- A new Kujo-native application with a substantive Strands multi-agent graph, not a giant wrapper function.
- A fail-closed release judge that cannot turn incomplete evidence into confidence.
- Bounded repair with exact-digest stale-write protection and mandatory re-verification.
- Repository prompt-injection tests that keep source text in the data plane.
- A real checksummed release-evidence package and integrity verifier.
- A polished live interface that makes authority and autonomous work visible.
- A deterministic golden change that includes success, repair, refusal, human input, re-evaluation, and payoff.
- A deployed AgentCore Runtime whose real cloud smoke ends in a checksummed
READY_TO_SHIPdecision.
Agent safety gets clearer when “what an operation means” and “where it may run” are separate contracts. Ability describes identity and effects; Workcell enforces execution. Neither substitutes for the other.
Parallel agents also need a deterministic barrier. A graph edge says when work may run. It does not prove that the resulting evidence is sufficient. The release judge must validate the artifact set again.
Finally, good human-in-the-loop design is subtraction. The useful unit is not a conversation. It is one unresolved decision with enough evidence to answer it.
Foreman can become a provider-neutral release-control layer between coding agents and CI/CD. Next steps are hosted repository adapters, signed policy distribution, remote Workcell providers after their contracts stabilize, team approval routing, richer language-specific verification planners, and organization-calibrated evaluation sets that measure false-pass risk over time.
The Kujo ecosystem predates this hackathon and is used as disclosed
in PREEXISTING_WORK.md. The Foreman product, graph, domain capabilities,
state, policy, judge, UI, demo, evaluations, deployment artifacts, and
submission materials are new hackathon work.