Scoped Agent Guidance Grill Log

Purpose: pin the requirements for repository-owned scoped AGENTS.md files that teach agents where code belongs and how idiomatic code is written without turning every prompt into a large reference manual.

Primary evidence:

• [[content/docs/project/research/scoped-agent-guidance-research-report]]
• AGENTS.md and the nearest scoped prompt tree
• apps/cli/src/content/scaffold-copy.ts
• apps/cli/src/scaffold/output.ts
• [[content/docs/project/grilling/opensrc-knowledge-refactor-grill-status]]

This grill governs scoped <directory>/AGENTS.md only. Root /AGENTS.md and .agents/AGENTS.md are inherited boundaries, not prompt-refactor targets.

Evidence Clarifications

• The earlier phrase phase routing meant the root-level map from task type to workflow entrypoint. The repository calls this Workflow Routing. It is not folder routing or a scoped coding convention and does not belong in scoped prompts.
• No opensource.md file exists. The current source-inspection artifacts are opensrc/README.md plus per-library Source Guides under opensrc/<guide-id>.md.
• Package Source Context and curated Example Repository Context are separate. The prior opensrc grill already decided that concrete curated repositories belong only to scopes whose selected packs provide them; root/shared guidance remains generic.

Branch: Scoped Prompt Purpose and Priority

Q1

Prerequisites:

• none

Question: What is the primary role and content priority of a scoped AGENTS.md?

Accepted answer:

• A scoped AGENTS.md is the explicit coding standard for its scope.
• Its content is weighted first toward semantic folder/module structure, placement, dependency direction, public/composition/generated boundaries, and then the coding conventions proven by neighboring production code and tests.
• It describes responsibilities and choices, not a mechanically reproducible directory listing.
• Common standards stay inline. Conditional detail uses exact task-triggered references so completeness does not require prompt sprawl.
• Generic coding advice, duplicated root policy, versions, ports, counts, raw trees, and command inventories do not belong in the scoped prompt.

Source:

• User explicitly accepted the structure-first coding-standard direction before R1.

Branch: Requirement Reach

Q2

Prerequisites:

• none

Question: Do these requirements govern current Harness scoped prompts, the reusable CLI authoring contract, or both?

Accepted answer:

• The delivery target is the reusable instruction system that tells the post-scaffold agent how to author generated scoped prompts.
• Do not rewrite this project's current scoped AGENTS.md files as part of this work.
• Current Harness prompts and code are evidence and validation fixtures, not prompt-rewrite targets.
• The hi-cli scaffold branch overlaps only where it routes the agent through generated .devpunks authoring artifacts and verifies completion.

Q7

Prerequisites:

• Q2

Question: Do generated authoring artifacts own the complete scoped-prompt criteria while hi-cli remains a thin post-command router?

Accepted answer:

• Yes. Generated .devpunks system, handoff, and scoped prompt-spec artifacts own the complete authoring criteria.
• hi-cli routes the post-scaffold agent into those artifacts and verifies the declared completion path. It does not duplicate the criteria.
• Delivery must keep those generated instructions internally aligned.

Q13

Prerequisites:

• Q2
• Q7

Question: Which generated artifacts must enforce the complete authoring contract?

Accepted answer:

• Update hi-cli; thin routing does not mean leaving the skill unchanged.
• The hi-cli scaffold branch owns concise handoff knowledge, hints, and guidance that direct the post-scaffold agent toward the new scoped-prompt criteria and generated artifacts.
• Generated per-scope prompt specs retain the detailed authoring criteria. Generated system and handoff artifacts route and verify the full scaffold continuation.
• Do not duplicate the complete detailed criteria inside hi-cli.

Branch: Evidence Promotion

Q3

Prerequisites:

• none

Question: Which evidence classes may become mandatory scoped coding rules?

Accepted answer:

• Documented intent is sufficient evidence for a scoped coding standard.
• The authoring flow may assume that authoritative repository documentation is current and will be refreshed through the repository's documentation process.
• Contract-enforced and repeatedly applied practices remain valid evidence too.
• Precedence when documented intent conflicts with current code remains a follow-up decision.
• This answer was later superseded by Q8. It remains here as decision history.

Q8

Prerequisites:

• Q3

Question: What wins when documented intent and current code conflict?

Accepted answer:

• Code is the only normative source of truth for scoped structure and coding conventions.
• Documentation follows implementation because it is written during the delivery phase after implementation.
• Documentation may help an author find relevant code, but it cannot overrule or independently promote a scoped coding standard.
• This answer supersedes Q3's earlier acceptance of documented intent as sufficient evidence.

Q11

Prerequisites:

• Q8

Question: Which executable repository artifacts count as Code Evidence?

Accepted answer:

• Code Evidence includes current production source, passing tests, schemas, configuration and manifests, and generators or scripts that enforce repository behavior.
• Generated output may provide evidence, but its current generator is normative when they conflict.
• Documentation is not normative Code Evidence.

Q16

Prerequisites:

• Q8
• Q11

Question: How does the author handle two competing patterns that both remain live in Code Evidence?

Accepted answer:

• Enforced constraints take precedence.
• Otherwise, follow the nearest stable module-family pattern for the work being changed.
• When different module families intentionally use different live patterns, preserve both behind exact scope or task triggers.
• When Code Evidence provides no defensible boundary or winner, omit the disputed normative rule and report the ambiguity.
• Documentation, taste, and raw frequency alone do not choose a winner.

Branch: Scoped Ownership

Q4

Prerequisites:

• none

Question: When does a stable subtree earn a deeper scoped prompt?

Accepted answer:

• It does not. Generate one scoped AGENTS.md for each detected app and package workspace; do not generate new prompts below those workspace roots.
• Deeper conditional detail uses exact triggered references instead of another prompt layer.
• Rewriting, removing, or reconciling this repository's existing deeper prompts is outside this delivery.

Q15

Prerequisites:

• Q4
• Q9

Question: Does the new scoped contract include the existing standalone docs prompt?

Accepted answer:

• Yes. The existing standalone docs prompt is a scoped prompt and receives the same structure-first, progressive-disclosure contract.
• For a docs scope, structure means content-folder responsibilities, placement, routing, frontmatter or schema boundaries, and applied authoring conventions.
• Root and shared prompt redesign remain outside this scoped-prompt delivery.

Branch: Skill Activation

Q5

Prerequisites:

• none

Question: What activation semantics does Primary skills here have?

Accepted answer:

• Use a hybrid model.
• Genuinely universal local skills remain always active.
• Task-specific skills use exact task triggers.

Q9

Prerequisites:

• Q5

Question: How does the hybrid skill model appear in each final scoped prompt?

Accepted answer:

• Replace the flat Primary skills here list with a compact table.
• List every selected non-phase scoped skill, not only universally active skills.
• Give each row short guidance that says what the skill helps with and when to use it. That cell distinguishes universal activation from exact task triggers.
• Do not hide selected skills only in generated metadata.

Q12

Prerequisites:

• Q9

Question: What authority supplies each skill table's what/when guidance?

Accepted answer:

• The selected skill ID resolves to its installed .agents/skills/<id>/SKILL.md.
• The post-scaffold author reads the complete skill file and condenses its purpose and activation rules into the table's what/when cell.
• The author must preserve explicit-only, trigger, and exclusion rules and must not invent behavior.
• Do not add Context Plan, catalog, or prompt-spec schema fields merely to store pre-rendered skill prose.

Branch: Source Guidance

Q6

Prerequisites:

• none

Question: Does opensource.md mean the existing Source Guide system or a new aggregate file?

Accepted answer:

• Use the existing opensrc/README.md index.
• Every final scoped prompt must link to opensrc/README.md explicitly.
• Do not introduce a new opensource.md aggregate.
• Do not hard-code Effect or another library as the generic scoped source rule.
• Per-library Source Guides and curated Example Repository Context remain separate artifacts.

Q10

Prerequisites:

• Q6

Question: Is the Source Guide index link always visible but loaded only for library-dependent work?

Accepted answer:

• Yes. Every scoped prompt explicitly links opensrc/README.md.
• Read that index when the task depends on third-party library behavior.
• Follow the relevant per-library Source Guide from the index rather than copying package-specific commands or precedence rules into the scoped prompt.

Branch: Progressive Disclosure

Q14

Prerequisites:

• Q1
• Q4

Question: Where does conditional detail go when no durable target already exists?

Accepted answer:

• The question's premise was rejected. The progressively disclosed content is itself authored reference content; it does not depend on a pre-existing document.
• The post-scaffold author produces the concise scoped AGENTS.md and its supporting reference content as one complete scoped-guidance output.
• Each reference is linked from the scoped prompt with an exact task trigger.
• Existing authoritative material may be reused, but prior existence is not a prerequisite: the author creates any required reference content in the same continuation.
• Do not emit missing-reference placeholders or defer required reference content to later documentation work.

Shared Understanding

• Confirmed by the user on 2026-08-11 after Q16 closed the final frontier.
• The confirmed decisions are ready for create-spec compilation.
• Specification and implementation authorization was granted separately after confirmation; it does not alter the accepted requirements above.