Agentic Repo Environment

Agentic Repo Environment

Improve the repository environment for coding-agent discovery, execution, verification, and learning. Treat effective AGENTS.md instructions as routing, not proof of agent readiness.

Select mode and authority

• Bootstrap a new or young repository. Inspect available evidence, conduct a bounded owner interview for scaffold-changing choices, recommend one minimum profile, and materialize accepted or safely reversible environment paths.
• Retrofit an existing repository. Trace grounded task scenarios, improve the environment, and preserve supported behavior, compatibility, baseline failures, and unrelated work.
• Renew after an accepted execution correction, escaped defect, repeated intervention, stale route, or measured burden. Qualify the learning, trial the smallest reusable change, and record its disposition.
• Treat assessment or recommendation requests as read-only diagnosis, even when they ask whether the repository is agent-ready.

An explicit Bootstrap, Retrofit, Renew, or agent-ready request authorizes behavior-preserving repository knowledge changes and fixed verification wiring. It does not authorize new product behavior, domain meaning, application or service architecture, production-code redesign, supported-command semantics, external settings, secrets, production actions, deletion of a pre-existing path, commits, pushes, deployment, or release acceptance. Promotion criteria do not grant execution permission; use existing explicit task authorization or adopted policy without asking again for authority already granted.

For read-only assessment, use the common spine through diagnosis, then report task-path evidence, material gaps, repair owners, next actions, and verification criteria without changes. Distinguish demonstrated defects from missing evidence; no change or an unresolved result can be justified. Reuse sufficient diagnosis within lifecycle work rather than requiring a separate assessment.

Own the repository environment

• Information architecture: effective instruction precedence, task-to-authority placement, consumption rules, and freshness across current intent, domain and architecture knowledge, executable contracts, observed implementation, derived views, and history. Keep plausible competing authorities visible until resolved.
• Execution environment: accepted runtime setup and one stable agent-facing path per recurring setup, development, focused-check, broader-verification, build, diagnosis, or maintenance intent.
• Evidence and control environment: fixed verification wiring, hooks, non-deployment CI, permissions, and automation bounded by resource budgets, pause paths, retries, cleanup, stop conditions, and accountable review capacity. Enable unattended operation only after its artifact, command, and evidence loop are stable. Enforce hard rules or label them advisory.
• Learning environment: repository-level intake, trial, promotion, supersession, rollback, and reopening paths for accepted corrections.

Recommend repository placement without choosing product, domain, application, service, deployment, or data architecture. Route missing semantic or structural decisions to their owners.

Bootstrap through evidence and recommendations

Inspect the repository, product evidence, constraints, and existing answers before asking questions. Ask only about choices that change maintained scaffolding: target work classes, the first representative slice, fixed runtime and delivery constraints, the evidence contract, autonomy, information owners, and renewal policy.

Classify each scaffold-changing choice as:

• accepted;
• recommended reversible default, with rationale and reversal path;
• consequentially unresolved, blocking only dependent slices; or
• deferred, because the walking skeleton does not need it.

Recommend one minimum profile instead of an unranked menu. Without an accountable response, return a conditional recommendation and do not materialize a consequential unresolved choice.

Design logical information architecture before a file tree. Materialize only owners with real content or an accepted need. Establish one walking skeleton from clean setup through representative work, focused feedback, broader evidence, and useful failure output. Establish renewal intake when repeated agent work, recurring intervention, or an accepted automation goal justifies it. Otherwise defer the interface with an activation signal; do not block Bootstrap or create governance artifacts merely to prepare for hypothetical learning.

Read references/bootstrap.md only for Bootstrap decisions and its walking skeleton; use existing owners and systems when renewal intake is justified.

Retrofit grounded task journeys

Start from recent changes, repeated work, maintained responsibilities, or measured friction. Trace each scenario from the effective instruction route through minimum sufficient authority, command selection, focused feedback, broader evidence, and handoff. Existing artifacts and green commands prove presence, not task fitness.

Change only surfaces that displace observed friction. Preserve accepted meaning while improving document function, concern separation, retrieval, freshness, commands, diagnostics, and fixed evidence wiring. Finish with a demonstrated material improvement or an evidence-backed no-op; an AGENTS.md edit alone is not completion.

Renew from accepted corrections

Bind the smallest sufficient episode evidence: task and revision, effective context, material actions, diff, checks, external evaluation, correction, and relevant intervention cost. Bound missing evidence. A raw failure, model reflection, or unaccepted preference is not a learning label; recover diagnosis or acceptance before treating it as a reusable correction.

Keep local transcripts, session IDs, and raw review logs in an existing private or ignored evidence surface. Maintained owners carry accepted decisions and reusable guidance with self-contained rationale and accessible evidence; do not archive episodes in specifications.

For each candidate:

1. Confirm the correction. Establish what changed the result and who accepted that meaning.
2. Assign the mechanism. Distinguish context, authority, procedure, runtime, feedback, permission, architecture, task-local implementation, model variance, and product ambiguity.
3. Test learnability. Retain only a supported, reusable, stable enough, encodable, and verifiable correction.
4. Select the lowest durable owner. Prefer removing the cause or adding an executable control over a tool affordance, route, repo skill, prose rule, or historical note.
5. Trial a qualified candidate. Replay the source episode, exercise an appropriate held-out or contrast case, and protect an existing guardrail before promotion.
6. Dispose and consolidate. Promote, retain as a trial, keep task-local, route, quarantine, reject, supersede, or roll back. Replace obsolete paths instead of growing instructions and controls monotonically.
7. Observe. Record the validity limit and reopening or reversal signal.

Scale evidence to the mechanism and consequence; a local route repair may use direct checks. Automate collection and trials only when repetition justifies them. A changed instruction, selector, check, judge, or gate must not be its own sole proof. Increase independence with risk.

Read references/renewal.md only for Renew qualification, trials, promotion, and dispositions. An evidence-backed non-promotion outcome completes evaluation without requiring an environment change or a passing promotion trial.

Compose without losing lifecycle ownership

For authorized lifecycle work, resolve missing specialist decisions, then resume the active mode; a route is not completion. Read-only diagnosis ends with its owned result.

• Use technical-writing for document function, domain-modeling for semantic conflict, architecture-surface-mapping for an unfamiliar path, and software-system-design for unresolved application structure.
• Use software-failure-diagnosis for an unexplained mechanism and software-verification for an unfixed claim, method, oracle, scope, or independent verdict.
• Route behavior changes to scoped-change-implementation; production-code structure to behavior-preserving-refactoring or its design owner; supported command semantics to software-contract-evolution; and repo skill authoring to skill-creator.
• Use platform-capability-design only for a supported shared product.

Execute the common spine

1. Establish scope and authority. Inspect Git state, effective instructions, accepted constraints, and existing systems of record. Preserve unrelated work.
2. Bind representative evidence. Select diagnostic task paths, accepted Bootstrap workflows, grounded Retrofit scenarios, or the Renew episode. Trace its information, runtime, command, evidence, and control owners; preserve baseline failures and reuse sufficient current evidence. Expand inspection when an unresolved mechanism, dependency, or guardrail can change the repair or its verification. Bootstrap still needs the complete representative setup-to-verification path; narrow Renew episodes need no fresh repo-wide inventory.
3. Diagnose the earliest gap. Separate an environment defect from missing product, domain, architecture, compatibility, or release authority.
4. Obtain owned decisions. Resolve mechanical routing and behavior-preserving changes directly. Route only blocked slices.
5. Implement the smallest coherent change. Keep local and CI paths on one implementation. Do not add empty templates, duplicate truth, a generic control plane or memory service, speculative controls, or one-off repo skills.
6. Verify the delta. Repeat affected consumer paths and reuse unaffected evidence; prose-only edits need runtime checks only for changed claims or executable inputs, suspect evidence, required gates, or explicitly fresh verification. Preserve known failures. For a running-system outcome, identify the actual target and exercise its consumer path within existing authority. Use a fresh context for changed instruction or retrieval behavior when available; otherwise record not run.
7. Consolidate and report. Redirect or deprecate superseded paths. Delete a pre-existing path only with explicit exact-target authority and applicable compatibility evidence. When replacing a tracked or supported path, also prove replacement use and consumer coverage.

Read references/setup-checklist.md when several surfaces need one durable implementation, review, or handoff record.

Strengthen verification proportionately

Classify focused and broader evidence as present, absent, not applicable, or disputed. Presence, test count, coverage, or a green gate does not prove adequacy.

Before changing test selection, broader-gate composition, CI enforcement, or permissions, freeze pre-change claims, exercised and omitted scope, skips, and exit semantics. Preserve a pre/post scope delta. Use a fixed negative control or independent evidence; the changed control cannot certify itself.

Quality gates

• Bootstrap produces an accepted or safely reversible walking skeleton; renewal intake is usable when justified, otherwise explicitly deferred with an activation signal.
• Retrofit demonstrates a material task-path improvement or an evidence-backed no-op while preserving behavior and baseline failure identity.
• Renew evaluation ends with an evidence-backed disposition, including no environment change. Promotion requires an accepted correction and passing replay, contrast, and guardrail evidence. Failed or unavailable evidence prevents promotion, not an honest rejection or deferral.
• Each sampled path reaches minimum sufficient authority and risk-matched evidence. Unresolved meaning, untested partitions, and unavailable independent evidence remain visible.
• Added files, checks, dependencies, and automation displace demonstrated burden. Superseded instructions and controls do not accumulate silently.

Completion

Report the mode, authority, decision frontier or episode, representative paths, changed owners, stable commands, exact evidence and before-and-after limits, preserved behavior, and dispositions. Name path consolidation, blocked slices, and the next renewal or reopening signal. Bootstrap remains incomplete while its accepted runtime or a required official path is unavailable or failing.