Orcastrata Ground

Inspiration

Agents are remarkably capable once they understand a project. The hard part is getting them to that point safely.

Real work rarely starts as a pristine repository. It starts as the directory someone already has: source code, half-finished notes, spreadsheets, research, media, unfamiliar formats, and decisions scattered across files. A new agent has to determine what is authoritative, what it may change, how to verify its work, and how another session can continue later.

I built Orcastrata Ground to make that first mile dependable. The goal is simple: meet projects where they are and make them easier for both agents and people to understand—before anything is changed.

What it does

Ground provides a Codex-first, local project-readiness workflow:

• It inspects code repositories, notes-first folders, and mixed collections.
• It distinguishes observed facts from assumptions, exclusions, opaque media, and unknown formats.
• It produces bounded context and handoff packets instead of dumping an entire directory into a model prompt.
• It converts natural-language intent into a typed, human-readable adoption preview.
• It shows the exact proposed writes, preservation rules, verification steps, and plan hash before requesting approval.
• It refuses stale or mismatched approval instead of guessing.
• It tracks what it owns, converges repeated plans to zero writes, and provides an ownership-aware removal preview.
• It leaves deterministic receipts so the next person or agent can understand what happened.

Natural language describes the desired outcome. It never silently becomes shell or mutation authority.

How I built it

Ground is implemented in TypeScript on Node.js 22 with a deterministic core and thin host adapters. The core owns inspection, typed plans, validation, hash-bound approval, preservation, receipts, replay, and recovery. The Codex plugin is a natural-language entry point into those same contracts rather than a separate implementation.

The project includes:

• a packaged CLI and real Codex plugin bundle;
• versioned schemas and human-readable architecture contracts;
• project adoption preview, apply, status, replay, and removal-preview flows;
• bounded mixed-content inspection, context, and handoff operations;
• offline package and installed-runtime conformance;
• explicit denial tests for stale approval, collisions, path escape, private content, provider authority, and unsafe lifecycle states; and
• an Apache-2.0 license with a release-shaped npm package candidate.

The current validation suite passes 410 tests. The npm dry-run contains 500 allowlisted package entries, including the compiled CLI and Codex plugin.

How I used Codex and GPT-5.6

Codex with GPT-5.6 was the primary engineering environment throughout Build Week. I used it to inspect and reconcile a large planning surface, turn product intent into bounded implementation checkpoints, implement the deterministic core and plugin packaging, and repeatedly test the complete installed journey.

The most valuable work was not one-shot generation. Codex helped diagnose a series of real integration failures: an installed binary that exited without running, packaged templates that were missing at runtime, output framing that varied through npm, stale current-state documentation, and idempotence checks that initially tested the wrong thing. GPT-5.6 helped trace each failure to a narrow cause, repair it, preserve the failed evidence, and run independent review before accepting the next candidate.

I also used bounded Scout, Worker, and Judge roles for parallel repository inspection and independent verification. That workflow directly influenced the product: Ground now produces compact context, exact assignments, receipts, and continuations because those artifacts made the build itself more reliable.

GPT-5.6 helped build, diagnose, repair, and validate Ground. It is not a runtime dependency; the shipped readiness operations are deterministic and local.

Challenges

The hardest part was balancing a welcoming first-time experience with honest authority boundaries. “Make this project agent-ready” should feel natural, but the sentence itself cannot authorize arbitrary writes.

Packaging was another substantial challenge. A command working from the source tree did not mean it worked after installation or from an unrelated directory. The final conformance path therefore packs the actual candidate, installs it in isolated temporary environments with lifecycle scripts disabled, invokes the installed binary, verifies exact outputs and hashes, and cleans up afterward.

Mixed directories also forced useful restraint. Ground can inventory an image or unknown file type without claiming that it understands its meaning. It can honor an explicit exclusion without reading or emitting excluded content.

Accomplishments

I am proud that Ground is more than an AGENTS.md generator or repository template. It demonstrates a complete local safety loop: inspect, explain, preview, approve, apply, verify, repeat, remove-preview, and receipt.

The strongest result is predictable behavior under failure. Wrong approval writes nothing. Changed project state invalidates the old plan. Repeating an accepted operation converges. Existing user files are preserved. Removal is ownership-aware. The package and installed plugin are exercised rather than assumed.

What I learned

The main lesson was that agent friendliness is not the same as adding more instructions. A project becomes agent-friendly when authority, current facts, commands, ownership, verification, and continuation are all legible and agree with one another.

I also learned that receipts are a product feature, not administrative noise. They let people move between sessions and tools without relying on a transcript or trusting a cached claim about the repository.

What's next

The immediate next step is publishing the prepared orcastrata-ground npm package so the public installation is one command:

npx orcastrata-ground@latest

After the hackathon I plan to complete observed onboarding and accessibility sessions, harden update/migration/rollback behavior, expand the adversarial fixture matrix, and qualify additional host adapters. Claude and real cross-host handoff are intentionally post-hackathon work; the current claim is the tested Codex-first local product.

Longer term, Ground becomes the project-grounding capability inside the wider Orcastrata/AOL architecture: one focused layer that prepares the directory before a broader agent system plans or executes work.

Built With

• typescript