Scoped Agent Guidance Research

Question and method

The target is a refactor of repository-owned scoped AGENTS.md files. Each one should lead with its scope's semantic folder and module structure, placement rules, dependency direction, and public boundaries, then state the coding conventions applied in neighboring production code and tests. The intended result is code that looks native to that part of the repository. Three readonly lanes covered the current prompt tree and inheritance boundary, the CLI authoring contract, a comparison repository, and standards already proven by code, tests, runbooks, and project notes. This thread concerns only scoped <directory>/AGENTS.md files. Root /AGENTS.md and .agents/AGENTS.md were inspected only to establish what scoped guidance inherits; neither is a target of the proposed refactor. This report records evidence and a landing model. It does not authorize the refactor or settle the open product choices below. No prompt, generator, schema, projection, or production code should change during this research phase.

Trusted facts

The existing contract already separates detection from authorship

hi scaffold is required to emit prompt specs rather than hard-code final repository prompts. A follow-up agent authors root, docs, and workspace AGENTS.md files from repository evidence (docs/reference/dp-requirements.md:193-220).
The generated scoped spec defines a small house structure, selected packs, primary skills, and authoring rules. It explicitly says to preserve repository-specific constraints and route broader monorepo concerns to the root (apps/cli/src/content/scaffold-copy.ts:115-173).
Root and scoped AGENTS.md files are the neutral authored sources. Sibling CLAUDE.md files are mirrors. Prompt discovery emits specs for root, shared, docs, nested prompts, and workspaces, while direct managed prompt output is limited to the shared prompt and explicit additional targets (apps/cli/src/scaffold/output.ts:1540-1590, apps/cli/src/scaffold/output.ts:2139-2241).
In this checkout, .agents/AGENTS.md and apps/wiki/AGENTS.md are managed prompt outputs. The other root/scoped prompt bodies are repository-authored sources (.devpunks/scaffold-manifest.json:66-88, .devpunks/scaffold-manifest.json:1876-1882, .devpunks/scaffold-manifest.json:4368-4376).

The three prompt layers have distinct documented contracts

.agents/AGENTS.md is the shared engineering-behavior baseline. It should not own Harness surface topology or scope-local coding standards (apps/wiki/content/docs/harness/prompt-surfaces/prompt-surfaces.mdx:23-31).
Root /AGENTS.md is already a 23-line repository router. It states surface ownership, lifecycle routing, cross-surface contract coordination, validation routing, inheritance and worker policy, then a few repo-wide source, URL, and documentation rules. Its baseline-publishing procedure is a current branch-specific exception (AGENTS.md:3-23). The generated root criteria describe the same concise shape and explicitly omit a root Primary skills here list (apps/cli/src/content/scaffold-copy.ts:72-113).
Scoped <directory>/AGENTS.md files are the local implementation layer. The current CLI contract gives them a heading, a flat primary-skill list, one ownership paragraph, optional source/URL guidance, a docs rule, and any extra focused sections the author decides to add (apps/cli/src/content/scaffold-copy.ts:115-135). It does not yet require a folder-placement standard, applied coding conventions, or triggered disclosure of branch-specific detail.

Prompt writing has a clear information-placement test

A pointer must name its material and the distinct branches that trigger loading it. Weak pointers make important guidance unreliable (.agents/skills/writing-for-agents/SKILL.md:10-18).
Inline steps, inline reference, and disclosed reference form an information hierarchy. Branch-specific material belongs behind a pointer; concepts and caveats should stay co-located (.agents/skills/writing-for-agents/SKILL.md:29-43).
Completion criteria should be checkable and exhaustive. Vague endings invite premature completion (.agents/skills/writing-for-agents/SKILL.md:45-52).
Code, config, scripts, and layout are already sources of truth. Restating cheap lookups in prompts creates stale caches; prompts earn their load by capturing unwritten conventions, reasons, and gotchas (.agents/skills/writing-for-agents/SKILL.md:76-81).

Collective Intelligence comparison evidence

The comparison used the local collective-intelligence checkout on dev at 0ddc23a39718 and made no changes there.

Its root prompt explicitly says to read root first and the nearest scoped prompt next, and to keep durable app/package rules at the lowest owning scope (collective-intelligence/AGENTS.md:3-24).
Its root contains a surface/ownership map, root commands and local runtime topology, workflow routing, cross-scope dependency and generation rules, and validation routing (collective-intelligence/AGENTS.md:5-79). Its nine-line intermediate packages/AGENTS.md keeps cross-package guidance compact and sends package-specific work to the nearest package prompt (collective-intelligence/packages/AGENTS.md:1-9).
Its scoped prompts include a 311-line backend prompt, a 148-line dashboard prompt, a 145-line Studio prompt, and a 177-line frontend-integration prompt. Those files include feature lifecycles, runtime configuration, and environment reference (collective-intelligence/apps/backend/AGENTS.md:1-311, collective-intelligence/apps/dashboard/AGENTS.md:1-148, collective-intelligence/apps/studio/AGENTS.md:1-145, collective-intelligence/packages/fe-integrations/AGENTS.md:1-177).
Its backend prompt keeps a migration prohibition inline and points the full procedure to apps/backend/MIGRATIONS.md (collective-intelligence/apps/backend/AGENTS.md:262-264).
Its root command and local-runtime section includes ports, aliases, environment mappings, credentials, and service behavior (collective-intelligence/AGENTS.md:26-49).

Observed prompt facts

apps/api/AGENTS.md still describes a migration that must happen before real backend behavior, although the app now composes real Effect services, layers, resources, and HTTP contracts (apps/api/AGENTS.md:5, apps/api/src/platform/runtime/application.ts:105-228, packages/contract/src/api.ts:1-25).
apps/wiki/AGENTS.md caches a frontmatter enum that committed wiki content does not follow. It declares authority over the entire app, while its primary skills and body concentrate on content and ingest (apps/wiki/AGENTS.md:1-17, apps/wiki/AGENTS.md:42-101, apps/wiki/content/docs/get-started/introduction.mdx:1-7, apps/wiki/specs/cli/IP-321-hi-native-cli-presentation-contract/PLAN.md:1-7).
The three nested CLI prompts expose overlapping flat skill lists even where the deepest scope says runtime behavior belongs elsewhere (apps/cli/AGENTS.md:3, apps/cli/src/AGENTS.md:3, apps/cli/src/data/AGENTS.md:3-5).
Scoped primary-skill inventories currently range from four to twenty-five always-visible names without task triggers. Root calls them scoped defaults, while the specialist manifest treats selected skills as mandatory for matching work (AGENTS.md:15, apps/cli/src/data/subagents/manifest.mjs:104-118).
apps/wiki/AGENTS.md is 132 lines and governs the full wiki surface while embedding content schemas, ingest procedure, linking, and linting detail (apps/wiki/AGENTS.md:18-132).
Root owns a broad docs-update rule. API, CLI data, and UI repeat local variants (AGENTS.md:23, apps/api/AGENTS.md:9, apps/cli/src/data/AGENTS.md:7, packages/ui/AGENTS.md:7).
CLI data work inherits the same docs-update obligation at three nested levels (apps/cli/AGENTS.md:15, apps/cli/src/AGENTS.md:9, apps/cli/src/data/AGENTS.md:7).

Inferences from the observed prompt facts

Root answers which surface owns work, what crosses a surface, and how the repository routes workflow and proof. Scoped guidance should answer where code belongs inside that surface and which local implementation shape neighboring code has established. Moving those local standards into root would defeat inheritance rather than reduce scoped sprawl.
Collective Intelligence's explicit root-to-nearest-scope inheritance and compact intermediate package layer are useful patterns. Its large scoped prompts and root runtime inventory are cautionary examples of conditional detail becoming always-loaded cache.
The wiki prompt loads several content-specific branches for every edit under the app even though runtime and projection work do not use all of them.
The wiki prompt's content focus leaves runtime and projection work with a weak local execution contract.
Flat primary-skill inventories are weak pointers because they do not identify which task branches should load each skill.
Repeated "relevant docs" endings lack a checkable completion bound and duplicate root policy.

Landing model

The evidence supports keeping the existing author-from-evidence contract. The layer placement below remains a synthesis. The scoped coding-standard direction is accepted.

Accepted direction: scoped coding standards

Each scoped AGENTS.md should be the explicit coding standard for its scope. Its job is to make the repository's idiomatic implementation choices available before an agent writes code. It should not be capped at an arbitrary two or three practices. Coverage is complete when the structural contract and every recurring convention that materially changes code placement or implementation is governed. Completeness does not mean putting everything inline: always-applicable standards stay in the scoped prompt, while conditional detail is governed through a precisely triggered reference to its authoritative home.

The prompt budget should be weighted in this order:

Folder and module structure: name the semantic module families, what belongs in each, allowed dependency direction, public and composition roots, and where tests, fixtures, adapters, and generated artifacts belong. Describe responsibilities and placement decisions, not a directory listing an agent can reproduce mechanically.
Applied coding conventions: state the naming, module shape, imports and exports, API and type design, state ownership, error and recovery, lifecycle, and test patterns repeated in neighboring production code and contract tests. These are existing practices to extend, not generic style preferences.
Supporting operational rules: include validation, integration, configuration, caching, deployment, and release rules only where they affect implementation in the scope or guard a non-obvious boundary.

Current topology and representative sibling modules/tests are the first evidence, not the conclusion. Repetition can still encode a legacy, transitional, or accidental shape. Classify each candidate as contract-enforced, repeatedly applied, documented intent, tentative inference, or insufficient evidence before promoting it into prompt text. Executable contracts, configuration, and scripts strengthen the case; durable docs and project notes explain reasons and gotchas. Existing prompt text is a candidate to verify, not authority by itself. Once a structural home is confirmed, extending it should be the default. A new top-level bucket or architectural shape needs evidence that no confirmed home fits and an explicit reason for the change.

Structure gives the remaining dimensions their context:

folder/module responsibilities and code placement;
dependency direction, public entrypoints, composition roots, and generated boundaries;
colocated tests, fixtures, adapters, and integration seams;
framework, API/type, naming, error, lifecycle, and state conventions;
validation and operational evidence owned by the scope.

The evidence inventory must determine which dimensions apply. A scope should not receive generic sections merely to fill this list.

Progressive disclosure contract for scoped guidance

Progressive disclosure is part of correctness, not a word-count cleanup. A scoped prompt must let an agent make the common placement and implementation decisions immediately, while making every conditional branch discoverable before that branch is edited.

Information band	Keep here	Examples
Always inline in the scoped prompt	Scope boundary; semantic folder/module responsibilities; placement and dependency direction; public/composition/generated boundaries; conventions that govern nearly every edit; a short branch router; narrow validation routing	Where a new capability, adapter, route, schema, test, fixture, or public export belongs; whether feature code may import provider code; the repeated module/API/error shape
Disclose behind an exact trigger	Detailed standards used only by a recognizable task branch	Schema and migration procedure; provider-adapter lifecycle; runtime composition; generated projection ownership; specialized fixtures or integration tests; UI cache/state rules; deployment and release operations
Read from the live authority	Facts that code or configuration answers cheaply	Raw directory tree; exact package versions, ports, command inventory, file/test counts, generated inventories, current defaults

Every disclosed pointer must name all three parts: the material, the task branch that triggers it, and the exact target. For example: Schema or migration work: read [Database structure and migration contract](...) before editing schema, migrations, persistence, or runtime layers. Phrases such as "read relevant docs" or an unqualified list of skills fail this test because the agent cannot determine when loading is required.

This yields a compact local router without weakening the coding standard. The prompt remains heavily weighted toward folder structure and applied coding conventions; long branch-specific explanations move, but their governing triggers stay inline.

Layer	Owns	Suitable content	Exclude
Root `AGENTS.md`	Repository-wide routing and invariants	Surface ownership, cross-surface contracts, validation routing, workflow routing, and true repo-wide source/URL/docs invariants	Workspace details or branch-specific release operations
Scoped `AGENTS.md`	Scope coding standard	Semantic folder/module map; placement and dependency rules; public/composition boundaries; colocated test, fixture, adapter, and generated-code conventions; then applied API, error, lifecycle, state, integration, and validation practices; triggered skill/doc pointers	Histories, exact versions/counts, mechanically enforced defaults, generic advice, duplicated root rules
Durable docs/wiki	Explanation and operations	Rationale, architecture, runbooks, longer failure modes, decision history	Always-loaded workflow instructions
Topology and neighboring code/tests	Primary applied evidence	Semantic homes, dependency direction, public seams, colocation, module shape, and conventions repeated across representative implementations	Bare directory listings or one-off patterns treated as standards
Config/scripts	Executable and operational authority	Schemas, commands, generated ownership, validation behavior, and current defaults	Narrative copies in prompts when lookup is cheap
Prompt specs/context plan	Generated structure	Detected scopes, packs, skills, ownership/provenance metadata	Invented repository prose
Subagent/provider projections	Derived execution surfaces	Authored guidance plus compiled specialist metadata	Independent hand edits or a second source of truth

The scoped coding-standard pattern to test is:

Scope boundary and semantic folder/module map.
Placement, dependency-direction, entrypoint, colocation, and generated-code rules.
Applied coding conventions grouped beneath the structural area they govern, with related rules and caveats co-located.
Triggered pointers for branch-specific examples, skills, runbooks, or source guides whose full detail does not belong inline.
Checkable testing and validation expectations for the scope.
No repeated root policy, generic coding advice, or cheap directory inventory.

This changes the role of Primary skills here: it should stop acting as an unqualified pack inventory. Whether it becomes a minimal always-on list plus triggered pointers, or remains the exact generated scoped list with trigger semantics defined elsewhere, is an open product decision. The compiler derives that list from the scope's non-phase skill contributions and passes it directly into each prompt spec (apps/cli/src/scaffold/output.ts:996-1004, apps/cli/src/scaffold/output.ts:2143-2153).

Gap in the CLI-running author contract

The current continuation agent is told to read generated specs, activate writing-for-agents, and author root and scoped prompts from repository evidence (.devpunks/AGENT-HANDOFF.md:39-58, .devpunks/AGENT-SYSTEM-PROMPT.md:241-258). The generated specs add concise root/scoped shape, local primary skills, root de-duplication, and preservation of repository-specific seed constraints (.devpunks/specs/prompts/root.md:123-131, .devpunks/specs/prompts/apps/cli/prompt.md:61-69). This is a sound authoring process, but its scoped result is under-specified:

the scoped spec does not require topology or representative-neighbor inspection;
it does not require folder placement or coding conventions as explicit output;
it does not require the author to separate universal rules from conditional branches;
it has no sprawl or weak-pointer acceptance check;
its content tests lock headings, skill shape, and phase-skill exclusion, but not structural evidence, applied conventions, or progressive disclosure (apps/cli/src/content/content.test.ts:815-872, apps/cli/src/content/content.test.ts:910-929).

PromptSpecSummary currently carries target path, scope, packs, skills, and source references, not discovered structure or convention evidence (apps/cli/src/scaffold/models.ts:98-108). A later design must decide whether the generated model carries richer evidence or whether the continuation agent discovers it directly. Either way, future acceptance criteria should make the result checkable: structure first, conventions derived from representative neighbors, evidence status preserved, conditional detail behind exact triggers, and no duplicated root policy or cheap environment cache. This is a contract recommendation only; no generator change is authorized by this report.

Initial structure and convention evidence

These are initial evidence-backed conventions, not an exhaustive inventory or final prompt text. The table currently contains both structural and behavioral ground; the refactor must lead each scope with the structural home that makes the behavior meaningful. Folder names alone are cheap cache. Include one only when it carries a non-obvious responsibility, dependency, colocation, public boundary, or generated-ownership rule.

Structure and placement evidence

Scope	Evidence status	Candidate structural implication	Primary authority
`apps/api`	Contract-enforced but transitional	New domain work has a strong candidate home in `features/<capability>` for services, models, policies, ports, public roots, and reusable test layers; provider/persistence implementations sit in `integrations`; transport and composition sit in `platform/http` and `platform/runtime`; root `index.ts` stays a shallow process adapter. Root-level legacy modules mean this is not yet universal.	`apps/api/src/index-boundary.test.ts:5-25`; `apps/api/src/features/report-submission/index.ts:1-27`; `apps/api/src/features/report-submission/testing.ts:18-65`; `apps/api/src/database-injection-contract.test.ts:12-67`
`apps/backoffice`	Repeatedly applied; one feature boundary enforced	The current split places Next route files in `app`, capability UI/actions in `features/<capability>`, reusable technical mechanics in `modules`, and remaining shared visual pieces in `components`. The operator-shell contract enforces direct feature imports, but large route files and mixed components make a universal thin-route rule unsupported.	`apps/backoffice/src/app/page.tsx:16-21`; `apps/backoffice/src/features/public-domain-root-contract.test.ts:21-41`; `apps/backoffice/src/features/operator-workflows/actions.ts:1-13`; `apps/backoffice/src/modules/control-plane/client.ts:1-16`
`apps/cli`	Contract-enforced	A feature's application/use-case boundary and Effect service ports belong under `features/<capability>` using `application.ts`, `port.ts`, an explicit `index.ts`, and only needed model, interaction, action, or error files. Concrete mechanics belong in `integrations`, selection/wiring in `platform`, command declarations in `cli`, and rendering in `presentation`.	`apps/cli/src/features/command-boundary-contract.test.ts:24-64`; `apps/cli/src/features/command-boundary-contract.test.ts:349-446`; `apps/cli/src/features/repository-scaffolding/index.ts:1-26`; `apps/cli/src/platform/feature-application-operations.ts:454-461`
`apps/cli/src/data`	Contract-enforced within the projection-script family	Shipped catalogs, hooks, manifests, and executable projection scripts live under `src/data`; TypeScript asset selection/rendering lives under `src/content`. Existing projection scripts pair `.mjs` runtime files with `.d.mts` declarations, colocated tests, and nearest `test-fixtures`; distribution code packages the data tree.	`apps/cli/src/content/data.ts:63-102`; `apps/cli/src/data/scripts/harness-projection/contract.test.ts:19-35`; `apps/cli/src/data/scripts/harness-projection/contract.test.ts:70-77`; `apps/cli/scripts/build-dist.mjs:46-58`
`apps/wiki`	Repeatedly applied; projection ownership enforced	Canonical routed pages live under `content/docs/<route>`; Next endpoints under `src/app`; Fumadocs loading/page-tree behavior under `src/lib/source.ts`; MDX extensions under `src/components/mdx*`; and projection/check tooling with its tests under `scripts`. Current code does not establish a domain-first React split or uniformly thin routes.	`apps/wiki/src/app/docs/[[...slug]]/page.tsx:13-59`; `apps/wiki/src/lib/source.ts:9-16`; `apps/wiki/src/components/mdx.tsx:1-14`; `apps/wiki/scripts/sync-content.mjs:23-70`
`docs`	Documented intent	Detailed implementation reference and operator runbooks belong in root `docs`; linked or summarized copies under the wiki's `/docs/project` tree provide Fumadocs discoverability.	`docs/README.md:33`
`packages/auth`	Repeatedly applied	Authentication policy and ports currently live under `features/operator-authentication`; provider-specific normalization/delivery adapters live under `integrations`; root `index.ts` composes configuration, database, provider, and Effect dependencies.	`packages/auth/src/public-domain-root-contract.test.ts:5-67`; `packages/auth/src/index.ts:13-34`; `packages/auth/src/index.ts:50-83`
`packages/db`	Contract-enforced	Schema declarations belong under `schema`, persistence construction under `persistence`, and connection/configuration layers under `runtime`; the explicit public root preserves a one-way boundary that prevents runtime modules from importing persistence.	`packages/db/src/public-domain-root-contract.test.ts:29-57`
`packages/contract`	Contract-enforced	Each protocol area has its own root module and `api.ts` composes those roots. Protocol areas remain independent of sibling areas rather than collapsing into generic `schemas` or `errors` buckets.	`packages/contract/src/public-domain-root-contract.test.ts:6-32`
`packages/scaffold`	Contract-enforced	Stable model families publish through explicit subpath roots such as `baseline`, `catalog`, `context-plan`, and `harness-capability`; the package intentionally lacks a broad `index.ts`, keeps one-way domain-root dependencies, and excludes runtime environment/filesystem concerns.	`packages/scaffold/src/public-domain-root-contract.test.ts:14-38`; `packages/scaffold/src/public-domain-root-contract.test.ts:107-118`
`packages/env`	Export-enforced; placement intent partly inferred	The package exposes three flat public surfaces: `config`, `server`, and `web`. Provider-injected Effect configuration is currently implemented in `config`; the evidence does not yet establish a broader placement rule for future environment work.	`packages/env/package.json:6-10`; `packages/env/src/config.ts:6-49`
`packages/config`	Observed and consumer-tested	The package is currently flat and configuration-only, with an external consumer fixture proving public options. More evidence is needed before turning the absence of a `src` hierarchy into a prohibition.	`packages/config/package.json:1-12`; `packages/config/public-config-contract.test.ts:11-47`
`packages/ui`	Export-enforced and consumer-tested	Reusable primitives currently live in `src/components`, shared helpers in `src/lib`, and global tokens/styles in `src/styles`; those folders map to explicit package subpath exports. The single public contract test is evidence for behavior, not a general test-colocation rule.	`packages/ui/package.json:6-11`; `packages/ui/src/public-ui-contract.test.tsx:39-63`
`apps/web`	Insufficient evidence	The parked public surface establishes ownership but not a repeated implementation topology. A deeper local structure standard would be invented before real product behavior exists.	`apps/web/src/app/page.tsx:1-10`; `apps/web/src/lib/auth-client.ts:1`; `apps/web/src/public-routes.test.tsx:23-50`

Applied convention examples

These rules remain useful, but they follow the structural standard for their scope rather than competing with it for equal prompt weight.

Scope	Candidate scoped coding standard	Primary authority
`apps/cli`	Register command modules through the declaration graph and keep presentation at the outer boundary; return semantic `OperationResult` values, let that boundary own mode, streams, and exit status, and prove packaging changes from the installed tarball	`apps/cli/src/cli/command-registry.ts:43-129`; `apps/cli/src/presentation/operation-result.ts:29-92`; `apps/cli/src/presentation/present.ts:130-258`; `apps/cli/scripts/assert-package-surface.mjs:49-117`
`apps/api`	Keep feature services independent of provider selection and compose persistence/providers at runtime roots; register owned resources in the lazy, idempotent lifecycle and keep provider I/O outside report-delivery transactions	`apps/api/src/index-boundary.test.ts:5-25`; `apps/api/src/platform/runtime/resources.ts:36-189`; `apps/api/src/features/report-submission/service.ts:74-125`
`apps/api` deployment	Preserve the nested `/api/:path*` rewrite so Effect receives the original route	`apps/api/vercel.json:1-10`; `.agents/notes/2026-05-25-vercel-api-catchall-rewrite.md:3-5`
`apps/backoffice`	Keep authentication and control-plane access in their owning modules and mutations in feature actions; bind protected reads to the request, treat UI visibility as non-authoritative, and design exact cache invalidation with each mutation	`apps/backoffice/src/modules/auth/authorization.ts:17-33`; `apps/backoffice/src/modules/control-plane/client.ts:35-88`; `apps/backoffice/src/features/operator-workflows/actions.ts:32-120`
`packages/contract`	Evolve the owning protocol root, producer, consumer, typed failures, endpoint declaration, and semantic contract fixture together	`packages/contract/src/public-protocol-contract.test.ts:205-273`
`packages/env`	Decode new Effect configuration in the `config` boundary from an injected provider, treat empty values as absent, and keep secret values out of failures	`packages/env/src/config.ts:6-49`; `packages/env/src/public-env-contract.test.ts:140-215`
`packages/auth`	Normalize Better Auth, persistence, and Resend exceptions in integration adapters before feature policy	`packages/auth/src/index.ts:50-101`; `packages/auth/src/integrations/better-auth-operation.ts:7-24`; `packages/auth/src/integrations/auth-persistence-operation.ts:18-46`
`packages/db`	Acquire pools in runtime through Effect scope and retain real Postgres evidence for schema, transaction, and resource changes	`packages/db/src/runtime/drizzle-client.ts:20-46`; `packages/db/src/postgres-contract.test.ts:265-347`
`packages/config`	Prove public configuration through an external compiler consumer, not only internal units	`packages/config/public-config-contract.test.ts:11-47`
`packages/ui`	Prove components and tokens through semantic HTML, variants/state, and published CSS consumption, not only internal units	`packages/ui/src/public-ui-contract.test.tsx:39-63`
`apps/wiki`	Source absence is not deletion authority; projection inventories own pruning. Route metadata alone may not expose a page because sidebar composition is custom	`apps/wiki/scripts/sync-content.mjs:23-179`; `apps/wiki/src/lib/source.ts:16-56`; `.agents/notes/2026-05-27-wiki-sidebar-page-tree.md:3-10`
`apps/web`	Keep the surface parked and thin; route shared UI, backend contracts, and private knowledge to their owning scopes	`AGENTS.md:3`; `apps/web/AGENTS.md:5`

Exact test counts, versions, worker counts, SHAs, and timings should stay out of scoped prompts. Their live authorities are scripts, package metadata, task configuration, workflows, and verification inventories.

Future authoring and propagation boundaries

If a Harness-only prompt refactor is later authorized:

Edit only the repository-authored scoped AGENTS.md sources selected by the delivery. Root /AGENTS.md remains an inherited boundary, not part of this refactor.
Treat apps/wiki/AGENTS.md separately because the current scaffold manifest manages it. .agents/AGENTS.md is not a scoped coding-standard target.
Regenerate provider agents and mirrors through .agents/scripts/sync-subagents.mjs; do not patch provider output directly.
Verify a second sync is byte-stable, manifest/context validation passes, all prompt mirrors resolve to their authored sources, and a fresh hi check --json reports no changed files or drift.

For a reusable scaffold-contract change, the authoritative landing surfaces are:

prompt/scoping rules in apps/cli/src/content/prompts.ts and apps/cli/src/content/scaffold-copy.ts;
target compilation in apps/cli/src/scaffold/output.ts;
specialist defaults in apps/cli/src/content/subagents.ts;
stable ownership/schema types in packages/scaffold;
canonical provider projection sources under apps/cli/src/data/scripts, then regenerated active mirrors.

Update recompiles the active manifest from context contributions, so editing only .agents/subagents/manifest.mjs is not durable (apps/cli/src/update/run.ts:3244-3251). Generator/shared-prompt changes flow through the npm CLI distribution; default projection assets also flow through the baseline (apps/cli/scripts/build-dist.mjs:46-58, apps/cli/scripts/build-baseline.mjs:224-233).

Conflicts and unresolved product decisions

Decisions that affect the scoped refactor

Skill semantics: Are primary skills mandatory for every edit in a directory, or branches triggered by task shape? Root calls them local defaults, while specialist guidance says assigned skills are mandatory for matching work; neither defines per-edit activation semantics for the flat scoped list (AGENTS.md:15, apps/cli/src/data/subagents/manifest.mjs:104-118).
Managed wiki prompt: Should apps/wiki/AGENTS.md remain baseline-managed, become project-authored, or split into managed structure plus project guidance?
Wiki scope: Should wiki content/schema guidance and wiki app/runtime guidance be separate scoped files? Which executable schema is authoritative?
Source-inspection precedence: Should Effect's local-source-first rule be an explicit scoped override to the shared official-docs-first rule?
Documentation authority: Root docs/ owns detailed operator and implementation reference while the wiki owns durable routed content and discoverability (docs/README.md:33). The scoped prompts need a checkable projection rule rather than repeated "relevant docs" wording.
Wiki development: Docs still say webpack is required, while the current package and Next configuration select Turbopack (docs/README.md:72, apps/wiki/package.json:5-14, apps/wiki/next.config.mjs:7-12). Do not encode either choice in a new prompt until the repository decides which evidence is current.
Change boundary: A local prompt rewrite and a reusable scaffold-model change are different deliveries. The latter changes generation, ownership, projection, release, and consumer-update contracts.

Out-of-scope system findings exposed by the boundary check

Root command criteria drift: the wiki says root prompts may own root command conventions, while the generated root criteria omit commands (apps/wiki/content/docs/harness/prompt-surfaces/agents-md.mdx:19-38, apps/cli/src/content/scaffold-copy.ts:72-113). This research does not decide a root rewrite. If reconciled later, only stable repo-wide entrypoints that change behavior belong inline; a command inventory remains a live package.json lookup.
Shared-template path collision: sharedAgentsPromptTemplate reads data/AGENTS.md, which resolves to the repo-scoped apps/cli/src/data/AGENTS.md; the scaffold then writes that body to consumer .agents/AGENTS.md (apps/cli/src/content/prompts.ts:35, apps/cli/src/content/data.ts:63-70, apps/cli/src/scaffold/output.ts:1392-1394). The content test currently locks this behavior (apps/cli/src/content/content.test.ts:791-798). This is a separate generator defect, not scoped-prompt prose to preserve.
Shared phase-skill contradiction: the shared prompt spec says phase skills never appear in scoped lists, while .agents deliberately bypasses that filter and the generated shared spec lists phase skills (apps/cli/src/scaffold/output.ts:996-1004, .devpunks/specs/prompts/shared-agents.md:8-18).
Single-repository collapse tension: the handoff says single-repo layouts should stitch scoped guidance into root. For a large single repository this conflicts with lowest-stable-owner inheritance and progressive disclosure (apps/cli/src/scaffold/format-summary.ts:227-233).
Provider/root worker conflict: root requires plan-derived worker waves; shared provider guidance defaults to one implementation worker (AGENTS.md:17, .agents/AGENTS.md:89-99). It does not change the scoped coding-standard model and needs separate ownership.

Narrow validation for a later refactor

Prompt/compiler/projection behavior: bun run --cwd apps/cli test -- src/content/content.test.ts src/data/subagents/manifest.test.ts src/data/scripts/sync-subagents.test.ts src/data/scripts/harness-projection/contract.test.ts src/features/context-planning/public-context-contract.test.ts src/scaffold/output.test.ts
Schema changes: bun run --cwd packages/scaffold test, bun run --cwd packages/scaffold check-types, and bun run --cwd apps/cli check-types.
Generated projection: node .agents/scripts/sync-subagents.mjs, rerun it to prove byte stability, verify manifest/context equality and prompt-mirror targets, then require hi check --json to report no changed files or drift.
Wiki projection: node apps/wiki/scripts/sync-content.mjs, inspect the diff, then run bun run --cwd apps/wiki check.

The ownership lane could not execute its targeted Vitest command because this worktree has no installed vitest binary. Its static source and symlink checks passed. No production tests were claimed.

Recommended next route

Run a bounded requirements grill before implementation. Treat scoped prompts as structure-first coding standards; that weighting is settled. Close the remaining skill semantics, managed wiki-prompt ownership, wiki split, reference destinations, and local-only versus reusable-scaffold boundary. Then produce one implementation plan whose discovery tasks inventory each scope's semantic folder/module structure and applied conventions, structure first, before authoring. Keep its write scopes aligned across scoped prompt edits, any separately authorized generator/schema changes, projection regeneration, and docs/validation. Root and shared prompt changes require their own explicit scope.

Scoped Agent Guidance Research

On this page