Agentic Scaffolding

Design the repository as the agent's working environment: durable knowledge, executable constraints, inspectable systems, safe capabilities, and feedback loops. The correct scaffold is project-specific. Derive it from the user's workflow and failure modes; never impose a universal directory tree.

Operating Contract

• Ask before prescribing. Establish who uses the system, what agents do, where they run, and which failures matter.
• Start from friction. Add scaffolding for observed or credible failure modes, not fashion.
• Keep the repository authoritative. Durable decisions, commands, interfaces, plans, and review lessons must be versioned near the code they govern.
• Use progressive disclosure. Persistent context routes; focused sources explain; scripts execute.
• Match documentation to its audience. Private product repositories should avoid README.md files and use scoped AGENTS.md files for agent-facing guidance. Reserve READMEs for public projects with outside human consumers.
• Prefer enforcement to reminders. If code can check a rule reliably, encode it in a linter, type, script, test, or CI gate.
• Verify outcomes in the real surface. Source inspection is not proof of a working application.
• Separate trust domains. Treat model behavior and generated code as untrusted even when the harness is trusted.
• Evaluate every layer. Routing, rule adherence, task outcome, cost, and latency are different measurements.

First: Interview the User

Do not design from generic best practices alone. Use references/discovery.md to resolve the material choices. Ask only questions whose answers change the architecture; inspect the repository first when it can answer them.

At minimum establish:

1. Work: task classes, duration, ambiguity, concurrency, and required autonomy.
2. People: who assigns work, reviews results, and owns guidance.
3. Repository: monorepo/polyrepo, languages, architecture, test/deploy paths, and existing instructions.
4. Runtime: local machine, CI, devbox, VM, sandbox, network and secret access.
5. Evidence: what proves success—tests, browser paths, previews, logs, metrics, traces, artifacts.
6. Pain: repeated mistakes, stale knowledge, unsafe actions, context loss, review bottlenecks, or orchestration overhead.

If material uncertainty remains, present 2–3 viable architectures with explicit tradeoffs and ask the user to choose. Otherwise select the smallest adequate design and state the assumptions.

Design the Scaffold

Read references/architecture.md, then choose only the layers the project needs.

Default repository home

Unless the repository already has a well-established equivalent, create a root agentic-scaffolding/ directory as the durable home for deeper agent-facing material. Keep the root AGENTS.md concise and link from it to agentic-scaffolding/AGENTS.md; do not copy deeper material into the always-loaded file.

Use agentic-scaffolding/ for the project's scaffold index and the focused architecture, workflow, plan, reference, evaluation, and governance artifacts selected below. Keep runtime-discovered files in their required native locations—for example .agents/skills/—and link to them from the scaffold index rather than breaking tool conventions.

Before creating a file, choose its destination from the repository's declared layout, including files produced by other skills. Distinguish source, configuration, generated output, plans, retained research, temporary files, and credentials. Existing root clutter is not a placement convention. Keep retained research in the project's data location, such as data/.

Do not create agentic-scaffolding/scripts/ or agentic-scaffolding/temp/. Executable helpers belong in existing project tooling or a runtime-required native location. Put temporary files in the OS temporary directory ($TMPDIR or /tmp), never in the repository. This includes disposable screenshots, logs, downloads, and intermediate build output; tool-required generated outputs keep their required locations.

In a private product repository, default to a scoped AGENTS.md in each human-maintained directory. Each nested file should state only that directory's local commands, boundaries, ownership, conventions, and routes while inheriting parent guidance; never copy the full parent file. Omit generated, vendored, build-output, and purely organizational directories, and omit any file that would contain no local contract. Public projects may use READMEs for external onboarding, but agent-operational guidance still belongs in AGENTS.md.

The root AGENTS.md should identify agentic-scaffolding/AGENTS.md as the canonical deeper index, route agents to relevant files, and contain only the rules and triggers that must always load.

Default source layout and push gate

Unless an established framework or repository convention requires otherwise, place first-party application and library code under src/, grouped immediately below it by coherent system or component rather than by incidental file type. Keep configuration, generated output, vendored code, migrations, and tool-required entry points in their native locations. Each meaningful src/<system-or-component>/ boundary should have scoped AGENTS.md guidance when it has local rules.

Treat this layout as an executable architecture invariant. Prefer GritQL for structural and dependency rules and Biome for supported lint, format, and import rules. If neither cleanly expresses path placement, add the smallest repository-owned structural check rather than forcing the wrong tool.

Run the canonical architecture, GritQL, and Biome checks from a blocking pre-push hook and from CI. The root AGENTS.md must name the exact command and state: never use --no-verify, disable or edit around the hook, suppress failures, or push while the check is unavailable. Fix violations; if the hook or its dependencies cannot run, stop and report the blocker. CI must run the same command because a local Git hook alone is not an enforceable trust boundary.

1. Persistent policy

Use AGENTS.md, CLAUDE.md, or the agent's native equivalent for rules that must be present every session:

• repository map and canonical sources
• exact build, test, run, and verification entry points
• non-standard architecture, compatibility, security, and data rules
• mandatory if/then workflow triggers
• destructive-action and Git/workspace boundaries
• exact mandatory pre-push command, prohibition on bypassing it, and stop-on-unavailable behavior

Keep it compact. Prefer a map to an encyclopedia. Generic repository summaries often add cost without improving outcomes; persistent context earns its place by routing retrieval or preventing a costly mistake.

2. Repository knowledge

Store durable knowledge in focused, owned files:

• architecture and domain boundaries
• product specifications and accepted decisions
• active/completed execution plans and technical debt
• operational, security, reliability, and performance requirements
• generated schemas and version-matched external references
• examples with rationale, exceptions, and known flaws

Give each source a clear owner and freshness signal. Keep current decisions and operational facts in one canonical source; plans, tickets, and other guidance link to it rather than copy values that can drift.

3. On-demand workflows

Create a skill when a workflow is repeatable, task-specific, too detailed for persistent instructions, and has a concrete output. Each skill needs:

• a precise trigger and explicit non-goals
• a narrow contract and completion condition
• routed references rather than copied knowledge
• deterministic scripts only where mechanics repeat
• verification and a stable result format

Critical skills need an explicit persistent if/then trigger. Availability alone does not guarantee invocation.

4. Executable constraints

Split judgment from mechanics:

• Prose: intent, tradeoffs, product judgment, architecture rationale, exceptions.
• Code: formatting, dependency boundaries, schemas, naming, generated-file rules, required metadata, security checks, and repeatable command sequences.

Custom error messages should tell an agent how to repair the violation. Enforce invariants centrally; allow implementation freedom locally.

5. Legible execution environment

Agents need direct, scoped access to the evidence humans use:

• isolated runnable application per task when practical
• browser or client automation for user-visible paths
• searchable logs, metrics, and traces
• deterministic setup/start/reset commands
• structured command output and retained failure artifacts
• exact links between source, runtime evidence, and acceptance criteria

Expose the smallest sufficient interface. Start with files and standard tools when they preserve structure and remain inspectable; add typed tools for permissioned capabilities, stable service boundaries, or dangerous operations.

For external account or OAuth setup, establish the agent's host and the machine/browser the user can actually see. Use the user's normal browser for provider sign-in. Provide the account/project ID, client type, exact origin and callback where applicable, and private credential destination together. Resolve known values from context before asking. Inspect non-secret credential metadata before activation and verify a real sign-in afterward.

6. Continuity and orchestration

For work that crosses sessions, preserve state outside the context window:

• acceptance criteria or a feature/task ledger
• progress, decisions, discoveries, and remaining work
• clean checkpoints and reproducible startup instructions
• proof artifacts for completed steps

For concurrent autonomous work, use one isolated workspace per task and a durable control plane such as the issue tracker. Model dependencies explicitly. Prefer objectives and observable handoff states over a rigid sequence of model micro-steps.

7. Security boundaries

Map these actors separately: trusted harness, model-driven agent, credentials, generated code, filesystem/environment, network destinations, and external content.

Default controls:

• least-privilege, task-scoped tools
• no raw secrets in model context or generated-code environments
• imported credential files go directly to an ignored private location with owner-only access, never the repository root or tracked guidance
• isolated execution for generated code
• workspace and filesystem boundaries
• egress controls or credential brokering where network access is required
• approvals for irreversible or high-impact actions
• teardown and state cleanup between tasks

A shared sandbox protects the host but does not protect harness credentials from generated code inside that sandbox. For sensitive workloads, separate harness compute from execution compute.

8. Verification and evals

Define proof before increasing autonomy:

• Code contract: focused tests, types, linters, structural checks.
• Application contract: launch the real system and exercise the changed path.
• Operational contract: inspect logs, metrics, traces, migrations, or deployment evidence.
• Handoff contract: attach concise evidence another reviewer can reproduce.

Build evals from real failures and unseen fixtures. Measure separately:

1. Did the agent load the right guidance?
2. Did it follow the relevant rule?
3. Did the final artifact satisfy observable acceptance criteria?
4. What did the scaffold cost in tokens, latency, and maintenance?

Always compare against a baseline without the scaffold. Do not interpret compliance as task success.

9. Maintenance loop

When an agent fails, classify the missing capability before changing prompts:

• missing or undiscoverable knowledge → improve the map or canonical source
• missed workflow → fix the trigger or persistent routing
• repeated mechanical violation → add an executable check
• unverifiable result → expose the real surface or signal
• lost state → add a durable progress artifact
• unsafe capability → narrow or isolate the boundary
• ambiguous objective → improve acceptance criteria or issue structure

Promote evidence into the narrowest durable artifact: canonical doc, skill, exemplar, linter, eval, or coverage-gap record. Require human acceptance for changes that encode organizational taste or policy.

Before relocating files, identify their code, build, documentation, and ticket consumers. Update their references with the move, run the affected workflow, and compare output when behavior should stay unchanged. Read back edited ticket links to confirm their saved destination.

Decision Rules

Read references/decision-guide.md when choosing among patterns. Defaults:

• Persistent context for always-applicable policy; skills for vertical workflows.
• A compact retrieval index for broad, version-specific knowledge; not full docs in the prompt.
• Filesystem and standard tools before bespoke retrieval APIs; typed tools at security or semantic boundaries.
• Interactive agents for ambiguous judgment; issue-driven orchestration for routine, well-specified work.
• One agent/workspace per independent task; shared state only through explicit artifacts.
• Hard gates for security, money, data integrity, migrations, and irreversible actions regardless of throughput.
• In private product repositories, scoped AGENTS.md files over READMEs; READMEs only when external human consumers need public onboarding.
• First-party runtime code under src/, grouped by system or component; GritQL/Biome plus the smallest necessary structural check enforce the boundary.
• One canonical blocking pre-push command, repeated in CI; root AGENTS.md forbids --no-verify, hook bypass, suppression, or pushing when the check cannot run.

Required Deliverable

Return a project-specific scaffold proposal or implementation with:

1. Current-state findings: existing strengths, gaps, and observed failure modes.
2. Decisions: chosen layers, rejected alternatives, assumptions, and tradeoffs.
3. Artifact map: exact files, tools, ownership, load order, and lifecycle.
4. Trust model: actors, secrets, boundaries, approvals, and teardown.
5. Verification model: commands and real scenarios proving work.
6. Maintenance model: how evidence becomes guidance, enforcement, and evals.
7. Adoption sequence: smallest useful first change, then later layers only when justified.

For implementation requests, make the smallest coherent end-to-end change and verify it. For audit or design requests, do not edit unless asked.

Anti-Patterns

• Copying another company's complete tree without matching its workflow.
• A giant context file containing architecture, docs, tutorials, and every command.
• Skills that restate persistent policy or exist without a reliable trigger.
• Tool proliferation that hides data the agent could inspect directly.
• Documentation-only rules that are deterministic enough to enforce.
• Agent-generated context summaries that merely duplicate the repository.
• README proliferation in private product repositories where scoped AGENTS.md files would provide inherited, enforceable agent guidance.
• Declaring completion from a green unit test when the changed user path was never run.
• Shared credentials available to generated code.
• Parallel agents editing one workspace without ownership boundaries.
• Adding autonomy before observability, rollback, and proof-of-work exist.

Sources

See references/sources.md for primary engineering posts, public repository examples, and empirical studies behind these patterns.