Scoped Agent Guidance Grill Status

• Working branch: team/stefan/refactor-scoped-agents-guidance
• Source research: [[content/docs/project/research/scoped-agent-guidance-research-report]]
• Scope: repository-owned scoped <directory>/AGENTS.md guidance only

Branch Dashboard

Current Round

• Round: R4
• Current frontier: empty
• Shared-understanding confirmation: confirmed

Locked Direction

• Folder/module structure and applied coding conventions dominate the scoped prompt budget.
• Structure means responsibilities, placement, dependency direction, entrypoints, composition roots, generated boundaries, and colocation rules.
• Applied conventions come from current Code Evidence. Documentation may orient discovery but cannot overrule or independently promote a rule.
• No arbitrary line count or practice count defines completeness.
• Each inline rule must apply to nearly every edit in the scope. Conditional detail remains governed through an exact triggered reference.
• Scoped prompts do not repeat root workflow, worker, or cross-surface policy.
• The reusable generated-prompt instructions are the delivery target. Current Harness scoped prompts are not rewrite targets.
• Code is the only normative source of scoped structure and coding conventions; documentation follows implementation.
• When live patterns compete, enforced constraints win, followed by the nearest stable module-family pattern. Preserve intentional family-specific patterns behind exact triggers; omit and report a rule when no boundary or winner is defensible.
• Generate one scoped prompt for each app/package workspace and no new prompts below those roots. Apply the contract to the existing standalone docs scope.
• Generated per-scope specs own detailed criteria. Update hi-cli with concise scaffold handoff hints; generated system and handoff artifacts route and verify the continuation.
• Every selected non-phase scoped skill appears in a compact table with short what/when guidance derived from the complete installed SKILL.md; universal and task-triggered activation remain explicit.
• Every scoped prompt explicitly links opensrc/README.md; load it when work depends on third-party library behavior.
• The author produces supporting reference content with each concise scoped prompt. Every reference has an exact inline task trigger; no required reference is left missing.

Parked Branches

• Whether generic Workflow Routing belongs in root /AGENTS.md or a global Harness layer. This grill only pins that it stays out of scoped prompts.
• Whether Workflow Routing means automatic activation, recommendation, or an explicit user-invocation stop. This is a root/global workflow decision.
• Shared .agents/AGENTS.md redesign.
• Rewriting current Harness scoped AGENTS.md files.
• Creating new nested scoped prompts below app/package workspace roots.
• Current Harness scoped-prompt rewrites, root/shared prompt redesign, and new deeper prompt layers remain parked. The user separately authorized direct implementation of the reusable contract after spec compilation.

Glossary

Terms

• Scoped Coding Standard: The nearest scoped AGENTS.md guidance that tells an agent where code belongs and which implementation conventions govern that scope. Avoid: local tips, workspace summary.
• Semantic Folder Map: A responsibility and dependency map for local module families, not a directory listing. Avoid: folder inventory, tree dump.
• Triggered Reference: An inline pointer that names the material, every task branch that requires it, and the exact target to load. Avoid: relevant docs, optional reading.
• Source Guide: A repo-local library inspection card currently stored at opensrc/<guide-id>.md and indexed by opensrc/README.md. Avoid: opensource.md, aggregate source guide.
• Package Source Context: Direct upstream library source inspected through a Source Guide and opensrc path. Avoid: example repository.
• Example Repository Context: A curated pack-owned repository used as evidence for applied framework patterns. Avoid: package source, arbitrary sample repository.
• Workflow Routing: The root/global map from task type to lifecycle entrypoint. Avoid: phase routing, folder routing.
• Generated Authoring Contract: The complete criteria emitted in .devpunks artifacts for the post-scaffold agent that authors final prompts. Avoid: duplicated hi-cli instructions.
• Scoped Skill Table: The complete list of selected non-phase skills for one scope, with concise what/when guidance for each row. Avoid: flat primary-skill list, hidden metadata-only inventory.
• Code Evidence: The normative executable repository evidence used to infer current structure and coding conventions: current production source, passing tests, schemas, configuration and manifests, and behavior-enforcing generators or scripts. Avoid: documented intent.
• Scoped Reference Content: Detailed repo-specific guidance authored with a scoped prompt and loaded only through an exact inline task trigger. Avoid: missing external reference, deeper scoped prompt.

Relationships

• One scoped prompt governs one stable directory scope and inherits every parent prompt on its path.
• A Triggered Reference belongs to one or more explicit task branches.
• A Source Guide governs one library source-inspection target.
• Package Source Context and Example Repository Context are separate evidence sources.
• One generated scoped prompt governs each app/package workspace root; deeper conditional knowledge is reached through Triggered References.
• The existing standalone docs prompt is also a Scoped Coding Standard.
• A scoped prompt and its Scoped Reference Content form one complete guidance output.
• hi-cli summarizes and routes to the Generated Authoring Contract without restating every detailed criterion.

Axioms

• A scoped prompt is a local coding standard, not a mini-wiki.
• Semantic structure comes before behavioral conventions.
• New code extends a confirmed structural home unless evidence proves that no existing home fits.
• Existing prompt prose is not authority without current repository evidence.
• Versions, ports, raw trees, counts, and command inventories stay in live authorities.
• Conditional detail can move out of the prompt only when its trigger and target remain explicit inline.
• Concrete curated example repositories remain scoped to relevant selected packs; root/shared guidance stays generic.
• Every scoped prompt links directly to opensrc/README.md.
• The opensrc/README.md index is read when work depends on third-party library behavior.
• Code is the only normative source of scoped standards. Documentation follows implementation and may only orient discovery.
• Generated output yields to its current generator when Code Evidence conflicts.
• Competing live patterns remain conditional when they map to stable module families. Without an enforceable or local boundary, no normative rule is invented.
• Every selected non-phase scoped skill stays visible in the Scoped Skill Table; each what/when cell states universal or task-triggered activation.
• Supporting Scoped Reference Content is authored in the same continuation as the scoped prompt; it is never represented as a missing future document.

Flagged Ambiguities

• "phase routing" was used for Workflow Routing. Resolution for this grill: it is inherited root/global guidance and is excluded from scoped prompts.
• "opensource.md" meant opensrc/README.md. Resolution: every scoped prompt links that existing index; no new aggregate is introduced.
• "always" means the README link is present in every scoped prompt. Reading is triggered when work depends on third-party library behavior.
• Primary skills here becomes a complete Scoped Skill Table. Every row has concise what/when guidance.
• Q3 was superseded by Q8: documented intent is not normative; code is the sole source of truth for scoped standards.
• "thin hi-cli" means concise handoff and routing guidance, not an unchanged skill. The detailed criteria remain in generated per-scope specs.
• Q14 incorrectly assumed a reference must pre-exist. Resolution: referenced content is part of the authored scoped-guidance output.
• "dominant pattern" does not mean the most frequent pattern. Resolution: enforced constraints and the nearest stable module-family boundary govern; unresolved ambiguity is reported rather than guessed.

Known Contract Conflicts

• Current scoped prompt specs do not require structure or applied-convention discovery.
• Scoped criteria call source inspection optional, while every generated prompt spec currently receives a generic source-inspection section.
• Root guidance hard-codes Effect source lookup instead of pointing to a generic scope-relevant Source Guide set.
• Prior requirements keep concrete curated repositories out of root/shared guidance, while the current generated root prompt spec lists them.
• Current Context Plan and prompt-spec data carry selected skill IDs but no what/when prose. The installed full SKILL.md files contain the activation authority, including rules not always present in frontmatter descriptions.
• Current generated system, handoff, summary, and scoped-spec text assumes a flat primary-skill list rather than the accepted Scoped Skill Table.
• opensrc/README.md is currently emitted only when at least one Source Guide exists. An always-valid link requires emitting the index even for an empty guide set.
• Current prompt discovery already creates root/shared, optional standalone docs, and one prompt per detected workspace. It does not create deeper workspace prompts, and update preserves existing authored nested prompts.
• Current scoped-section rendering groups every non-root target together, including shared .agents/AGENTS.md. Delivery must explicitly restrict the new contract to docs and workspace targets so shared guidance stays outside scope.

Delivery Constraints Proven During R3 Discovery

• The accepted structure-first and code-only authoring rules can be expressed in generated prose and locked by generator tests; they do not require a Context Plan or scaffold schema expansion.
• Selected skill IDs already resolve to installed .agents/skills/<id>/SKILL.md files after scaffold.
• Pre-rendered or stored skill guidance would require a new metadata authority; author-derived concise guidance from the full installed skill does not.
• Preserving existing project-authored nested prompts is compatible with the no-new-deeper-prompts rule. Removing or ignoring them would be a separate behavior change.
• Shared-skill source policy means an implementation change to hi-cli starts in the canonical shared skill repository and is then synchronized here.
• The exact hi-cli target is the lazily loaded Scaffold branch in hi-cli/references/post-command-flow.md; the top-level skill and unrelated command branches do not need the new criteria.
• Scoped Reference Content can be ordinary Markdown under its owning scope. Only an exact AGENTS.md filename creates another prompt scope.
• Keep Scoped Reference Content out of specialist guidanceFiles; eagerly loading it would defeat progressive disclosure.
• No Context Plan, prompt-spec, scaffold-manifest, or managed-reference schema is required for author-created reference content.