AgentReady

Status: A079 returned GO and A080 accepted the narrow local evaluator submission candidate — 2026-07-21. Current checkpoint: T012. The exact six local artifacts and two isolated offline rehearsals passed; public identity, repository sharing, recording, licensing, authenticated submission, release, and Production V1 remain unresolved or unproved.

AgentReady is a proposed deterministic readiness engine for agent-built software, including projects directed by people who do not write code themselves.

Its promise is simple:

Fork one repository or run one command, describe what you want to build, and start with a personalized, inspectable engineering system—not an empty folder, a generic template, or a pile of hidden agent instructions.

The intended product combines a forkable starter, a safe CLI/core, guided onboarding, versioned rules/skills/scripts and data contracts, agent execution profiles, Git-worktree and cross-operator protocols, thin host adapters, optional MCP interoperability, a human-readable project wiki, a derived project graph, and a resumable proof loop. It should help a person move from an idea to a production-grade project while keeping every important decision, task, source, test, failure, and receipt readable by both humans and language models.

Codex is the patient-zero/reference host and the intended Build Week evidence lane. It is not AgentReady's authority model or portability ceiling: the CLI, schemas, profiles, catalogs, worktree rules, collaboration packets, and receipts must remain useful without it.

Ground Collection Demo Candidate

Drop in the project you actually have, not the project a tool assumes you have.

The Clock-A candidate introduces a universal ProjectCollection contract and a CodeRepository profile. Ground is an internal Orcastrata successor capability; its read-only CLI can inspect and summarize a bounded local collection and emit a handoff. AgentReady's existing plan/apply flow remains the mutation authority. The candidate does not interpret media contents, provide a live model or provider, establish Privacy enforcement, publish AgentReady, or prove Production V1.

Current Clock-A boundary: T012 remains the sole active checkpoint. Ground owns read-only inspect, context, and handoff only; the generic AgentReady fixture plan/apply lifecycle is separate and has no CollectionManifest binding. A079 returned GO and A080 accepted only LOCAL_CLOCK_A_EVALUATOR_SUBMISSION_CANDIDATE, backed by six hashed local artifacts, two isolated offline rehearsals, exact v2 npm framing with retained raw evidence, installed arbitrary-CWD lifecycle proof, source preservation, cleanup, and the A078 validation ladder. A074 through A077 remain immutable historical NO-GO provenance for the entrypoint, packaged-template, transport-timing, and leading-LF repairs; they are not current blockers. No publication, repository share, recording, upload, naming, licensing, authenticated submission, T011, or T017 gate advanced, so this is not Production V1 proof. Historical A071 claim ceiling: LOCAL_CLOCK_A_GROUND_COLLECTION_DEMO_CANDIDATE_PENDING_A072_JUDGE.

After building, the fixture demo is copy-pasteable. The first three commands exercise Ground's read-only evidence surface. The following generic plan and apply commands independently demonstrate the existing marker-protected fixture lifecycle; they do not consume or derive from the Ground manifest.

npm run build
export GROUND_DEMO_ROOT="${TMPDIR:-/tmp}/agentready-ground-demo"
node dist/src/cli/index.js ground inspect --root "$GROUND_DEMO_ROOT"
node dist/src/cli/index.js ground context --root "$GROUND_DEMO_ROOT"
node dist/src/cli/index.js ground handoff --root "$GROUND_DEMO_ROOT" --outcome 'Make this mixed project collection agent-ready without changing its source content'
node dist/src/cli/index.js plan --root "$GROUND_DEMO_ROOT" --outcome 'Make this mixed project collection agent-ready without changing its source content' --users 'builder'
node dist/src/cli/index.js apply --root "$GROUND_DEMO_ROOT" --outcome 'Make this mixed project collection agent-ready without changing its source content' --users 'builder' --approve 98c9048e612aa1f61b1eb6a73c6b949256ca09c91ab45658bd2593ef37a5e5ab

The exact walkthrough and evidence limits are in docs/guides/ground-collection-readiness-demo.md.

The Product in One Minute

After the separately gated npm publication succeeds, the intended first-time install command is:

npx orcastrata-ground@latest

Ground then previews an exact Codex installation plan, asks for approval, and leaves a receipt-backed local plugin/runtime installation. Until the package is actually published, use the local package/evaluator paths in the guides; do not present the npx command as currently installable.

After restarting Codex, open the directory you want to modernize and ask:

Make this directory agent-ready. Preserve my existing files, explain what you
found, and show me the exact plan before changing anything.

AgentReady should:

1. inspect the repository and host capabilities;
2. compile plain-language intent into a readable brief with explicit assumptions and unknowns;
3. compose independent project, operator, and agent-execution profiles;
4. preview an engineering envelope containing rules, skills, deterministic operations, tests, data/fixtures, artifacts, ownership, risks, and recovery;
5. preview a deterministic file and policy plan and require explicit approval;
6. install only the selected profile and adapters;
7. create human- and machine-readable project truth and build catalogs;
8. derive a navigable code, document, goal, test, ownership, and evidence graph;
9. prepare a bounded goal with observable success criteria;
10. run or hand off work through resumable checkpoints and isolated worktrees when selected;
11. verify the result independently; and
12. leave signed or attestable receipts that explain what happened.

The core must remain useful without an LLM. Models may interpret intent, propose plans, implement, review, and explain; deterministic code owns schemas, generation, validation, migrations, permissions, receipts, replay, and safety gates.

Product Shape

flowchart LR
    U["Human intent"] --> O["Guided intent compiler"]
    O --> A["CLI or host-neutral adapter"]
    A --> C["Deterministic AgentReady core"]
    C --> P["Project + operator + execution profiles"]
    C --> T["Rule / skill / script / data catalogs"]
    C --> K["Human-readable knowledge layer"]
    C --> G["Derived project graph"]
    C --> R["Runs, checkpoints, receipts"]
    C --> W["Git worktree facts + static collaboration packets"]
    P --> B["GoalBuddy board truth (optional)"]
    B --> X["Codexmax execution and audit (optional)"]
    C --> M["MCP adapter (optional)"]
    X --> R
    K --> G
    R --> G

The intended boundaries are:

• Forkable starter: distribution, examples, documentation, contracts, fixtures, and a visible demo.
• CLI/core: deterministic project inspection, planning, generation, validation, indexing, migration, receipts, and replay.
• Host adapters: native-feeling Codex and Claude skill/plugin surfaces that call the same core.
• Operator/build layer: plain-language intent briefs, independent profile axes, versioned rule/skill/script/data catalogs, and deterministic engineering-envelope previews.
• Worktree/collaboration layer: Git-derived worktree facts plus file-backed claims, handoffs, reviews, and integration receipts; never a second task board.
• Goal layer: GoalBuddy-compatible goal oracle and board state when available.
• Execution layer: Codexmax-compatible planning, routing, worker, verification, recovery, and closeout when available.
• Knowledge layer: Markdown-first project context with source provenance and explicit review state, inspired by the local LLM Wiki model.
• Graph layer: derived relationships among code, contracts, documentation, decisions, goals, tests, artifacts, and evidence. “Graphify-like” is a design requirement here; no exact local Graphify dependency has yet been identified.
• MCP: an optional standards-based access adapter, never the owner of orchestration or project truth.

Proposed Profiles

| Profile | Intended user | What it enables | | --- | --- | --- | | Starter | A solo builder or small prototype | Clear repo map, contracts, commands, baseline tests, docs, and safe agent instructions | | Agentic | A builder actively using Codex or Claude | Starter plus skills, task intake, context routing, local receipts, and agent-aware quality gates | | Orchestrated | A long-horizon or multi-agent project | Agentic plus goal boards, checkpoints, worker ownership, recovery, independent audit, and cost/quality telemetry | | Specialized | A domain-specific project such as a workout coach | Orchestrated plus selected domain packs, compliance prompts, datasets, evals, and domain-specific gates |

Profiles are additive policy bundles, not four separate codebases. Every generated surface must say who owns it, why it exists, how to validate it, and how to remove or migrate it.

These are project capability profiles. AgentReady separately composes an operator mode—Guided Builder, Technical Maintainer, or Automation/CI—and an agent execution profile such as Guided Sequential, Parallel Read/Single Writer, Disjoint Worktree Build, Data-Intensive, Review-Heavy, or Cross-Host. A friendlier interface can change explanation depth; it cannot silently change authority or safety.

Guided Building Without Giving Up Engineering

A non-technical operator should be able to state a product outcome in ordinary language and receive an inspectable engineering envelope: users, scope, assumptions, architecture, rules, skills, deterministic commands, tests, data/fixture contracts, artifacts, risks, ownership, recovery, and one safe next action. Plain language is input, not approval. It must never become arbitrary shell execution or a hidden project mutation.

AgentReady's generated build kit is intended to make repeat work cheaper and more reliable for both people and agents:

• rules define authority, safety, evidence, data, worktree, collaboration, and release boundaries;
• skills route a host from the operator's intent to the relevant deterministic workflow using progressive disclosure;
• scripts are thin, cataloged invocations of versioned core behavior or existing repository commands;
• data contracts normalize, validate, cache, sample, and summarize data once rather than repeatedly spending model context on raw bulk input;
• tests and receipts prove that each rule → skill → operation → artifact chain behaves as claimed; and
• agent profiles bound roles, tools, paths, context/token budgets, concurrency, worktrees, handoffs, and independent review.

Solo use remains first-class. When several people or hosts collaborate, Git owns repository/worktree truth, the selected goal or issue system owns task truth, and AgentReady contributes static ownership/handoff packets and evidence. It does not silently merge, push, clean another operator's worktree, or create a competing board.

Agentic Optimization Is a Core Requirement

AgentReady is specifically intended to make projects easier and cheaper for agents to reason about over long runs. A generated project must therefore include, at the profile-appropriate depth:

• a short AGENTS.md navigation map rather than a monolithic instruction dump;
• progressive context routing from project map → task/role index → exact source/contract;
• human-readable command/API, skill/tool, capability, goal/evidence, and source-map indexes generated from canonical facts;
• bounded sub-agent roles: read-only Scout, Planner, file-scoped Worker, independent Judge/Auditor, with a parent/PM retaining board truth;
• one-writer-by-default ownership and explicit disjoint-scope proof before parallel writes;
• plan → execute → verify → judge → accept/retry loops with failure history and changed-hypothesis retries;
• per-role context manifests and token budgets that load only the sources needed for the assignment;
• fresh-session rollover packets that point to durable files instead of replaying whole transcripts; and
• evals that measure context loaded, tokens/turns, authoritative-source discovery, irrelevant-context rate, resume success, quality, and evidence completeness together.

The index model deliberately builds on patterns already proven locally: project-scaffold uses a repository profile plus CLI/skills/roadmap indexes; Civulacrum uses a short agent map, CLI/API and script indexes, capability ledgers, tree maps, and release-blocker indexes; AOL uses a command registry over shared canonical state and derived read models; LLM Wiki preserves source → distilled → wiki provenance. AgentReady should compile those strengths into a small profile-aware system instead of copying the full breadth of any one project.

Planning Package

Read these in order:

1. AGENTREADY_MASTER_PRODUCT_AND_BUILD_SPEC.md — canonical product definition, complete feature inventory, architecture, trust model, test strategy, dogfood plan, and production definition of done.
2. AGENTREADY_OPERATOR_BUILD_AND_COLLABORATION_SPEC.md — normative Guided Builder, rules/skills/scripts/data, agent-profile, worktree, collaboration, and host-neutral contracts.
3. AGENTREADY_LONG_HORIZON_ROADMAP.md — checkpoint contracts, dependencies, validation ladders, retry rules, go/no-go gates, and independent closeout.
4. AGENTREADY_OPEN_QUESTIONS_AND_SUGGESTED_ANSWERS.md — preserved proposal history and rationale behind the canonical 29/1/29/11 decision register.
5. AGENTREADY_RESEARCH_AND_RESOURCE_MAP.md — official standards, research, comparable systems, local reference projects, and explicit adopt/validate/reject guidance.
6. AGENTREADY_GPT_PRO_GOAL_PROMPT.md — a paste-ready prompt for GPT Pro to compile these materials into a durable GoalBuddy/Codexmax long-horizon implementation goal.
7. PLANNING_REPORT.md — work performed, validation boundary, assumptions, and remaining risks for this documentation pass.

The architecture decision index records the 2026-07-17 owner direction and exact T001 boundaries. The live task board remains docs/goals/agentready-production-v1/state.yaml; ADRs, packets, indexes, and receipts do not replace it. The accepted generated-target layout uses .agentready/project.yaml, blueprint.yaml, policy.yaml, manifest.json, lock.json, and the named .agentready/ directories; silent aliases are rejected.

AGENTREADY_MASTER_PRODUCT_AND_BUILD_SPEC.md plus accepted owner decisions and ADRs govern product intent. The canonical decision register records 29 accepted current-direction decisions, one experiment-bound decision, 29 accepted architecture constraints pending final evidence-gated decisions, and 11 unresolved decisions. The validated GoalBuddy docs/goals/agentready-production-v1/state.yaml is current board truth. Checkpoint receipts establish only their exact local evidence boundaries; they do not establish installability, broad host/platform support, release, publication, or Production V1.

Hackathon Thesis

AgentReady fits the Developer Tools track: a developer should be able to install it, point it at a new or existing project, and obtain a reproducible engineering harness that helps Codex with GPT-5.6 complete meaningful work while preserving human control and inspectable evidence.

The proposed three-minute demonstration is not “an agent writes a to-do app.” It is:

1. initialize or adopt a deliberately incomplete real project;
2. show AgentReady explaining the repo and selecting a profile;
3. use Codex with GPT-5.6 to implement a bounded feature;
4. inject or encounter a real failure;
5. resume from a durable checkpoint instead of restarting;
6. verify the feature through an independent gate; and
7. open the human-readable graph and receipt that show exactly what changed and why.

The differentiator is visible engineering reliability: fast start, cross-host portability, explicit project truth, safe recovery, and proof a human can audit.

Immediate Non-Goals

The first production path should not become:

• another general-purpose autonomous-agent framework;
• a daemon that silently controls a developer’s machine;
• a model marketplace or credential broker;
• a new replacement for Codex, Claude, GoalBuddy, Codexmax, git, CI, or MCP;
• a graph database that becomes a second source of truth;
• a template that copies hundreds of unused files into every repository;
• an enforcement system that blocks work before users can understand or configure it; or
• a hackathon-only illusion whose happy path cannot survive a clean install.

Current Boundary

This folder contains the accepted architecture plus a locally built and tested deterministic foundation, safe fixture-only lifecycle, readiness diagnostics, source-linked graph/knowledge layer, structural host-neutral adapters, and an optional fixture-backed read-only MCP stdio subset. AgentReady remains an internal working name; Orcastrata Ground is the external package candidate. The repository is licensed under Apache-2.0, and the hackathon/post-hackathon split—including deferred Claude work—is tracked in ROADMAP.md. The exact npm name appeared unregistered when checked on 2026-07-21, but it is not reserved until an authorized publication succeeds. Real hook installation or enforcement, additional dependencies, network/provider/credential use, remote or worktree mutation, publication, deployment, release, and public production claims still require their exact gates and evidence.