Spec: Scoped Agent Guidance Authoring Contract

Context

Harness scaffold continuation generates repository-aware instructions that a post-scaffold agent uses to author root, shared, docs, app, and package guidance. The first implemented contract made scoped prompts structure-first, but required agents to restate complete installed skill semantics and generic evidence policy. A representative continuation expanded those obligations to 1,718 lines.

Scoped AGENTS.md files need the repository invariants that change local work: semantic responsibilities, placement and dependency rules, local conventions, skill invocation pointers, Source Guide routing, mirrors, and validation seams. Installed skills remain the authority for their own semantics.

Non-Goals

• Rewrite this repository's current scoped AGENTS.md files.
• Redesign root /AGENTS.md or shared .agents/AGENTS.md guidance.
• Generate new scoped prompts below app, package, or standalone docs roots.
• Remove or reinterpret existing project-authored nested prompts.
• Change root/global Workflow Routing or phase invocation policy.
• Add skill prose or parallel descriptive fields to Context Plan, skill catalog, or prompt-spec schemas.
• Add a managed-reference inventory, place disclosed references in specialist guidanceFiles, or make Harness eagerly load them.
• Merge Package Source Context with curated Example Repository Context.

User Stories

US-001: Author concise scoped coding standards

As a post-scaffold agent, I want each docs or workspace prompt specification to identify its repository-specific structure and conventions so that final guidance places work where the repository expects it without generic prose.

US-002: Keep installed skills authoritative

As a repository maintainer, I want terse explicit-invocation pointers for every selected skill so that scoped prompts preserve intentional activation without copying skill semantics.

US-003: Preserve source and validation seams

As an implementation agent, I want Source Guide, mirror, reference, and narrow validation seams to remain explicit so that compactness does not hide completion.

US-004: Continue scaffold work from hi-cli

As an operator using hi scaffold, I want the hi-cli Scaffold branch to point the agent toward the complete scoped-authoring contract so that generated files lead to finished repository-aware guidance.

US-005: Preserve inherited prompt boundaries

As a Harness maintainer, I want the new contract limited to docs and workspace targets so that root/shared policy and project-authored nested prompts keep their existing ownership.

Acceptance Criteria

• AC-001: Every generated docs and workspace prompt specification requires only repository-specific structural invariants: semantic responsibilities, placement and dependency direction, entrypoint, composition, generated and colocation boundaries, and local coding or authoring conventions.
  • Covers: US-001
• AC-002: Generic evidence hierarchies and complete skill semantics remain out of generated scoped prompt obligations. Installed skill files remain their own semantic authority.
  • Covers: US-001
• AC-003: Each generated app/package workspace and the standalone docs scope has one scoped prompt target, and the contract creates no new deeper prompt layer.
  • Covers: US-001, US-005
• AC-004: Root and shared prompt specifications do not receive the scoped repository-invariant or skill-pointer obligations.
  • Covers: US-005
• AC-005: Conditional repository detail uses an exact task trigger and relative scope-owned Markdown target.
  • Covers: US-003
• AC-006: Every generated docs or workspace prompt specification preserves each selected non-phase skill ID once with a terse pointer to .agents/skills/<id>/SKILL.md: when the task explicitly invokes <id>, read the installed skill. Model discovery remains owned by the installed skill description.
  • Covers: US-002
• AC-007: Every final scoped prompt links opensrc/README.md and requires reading it when work depends on third-party library behavior; package-specific commands and precedence remain in the selected Source Guide.
  • Covers: US-003
• AC-008: Scaffold output includes a valid opensrc/README.md even when no per-library Source Guide is selected.
  • Covers: US-003
• AC-009: Every scoped prompt keeps its AGENTS.md source, sibling CLAUDE.md symlink mirror, narrow validation seam, and applicable docs-update seam.
  • Covers: US-003
• AC-010: The generated per-scope prompt specification remains the sole detailed authoring authority; generated system and handoff outputs point to its repository-invariant, skill-pointer, Source Guide, mirror, and validation checks without restating them.
  • Covers: US-001, US-002, US-003, US-005
• AC-011: The hi-cli Scaffold branch concisely names the repository-invariant, skill-pointer, Source Guide, mirror, and validation outcomes and routes to generated artifacts without copying their full checklist.
  • Covers: US-004
• AC-012: Scaffold/update preserves existing project-authored nested prompts and does not rewrite this repository's current scoped prompts as part of this capability.
  • Covers: US-005
• AC-013: A fixed representative 15-scope fixture totals at most 700 generated authoring-instruction lines while preserving every selected skill ID, exact trigger, Source Guide pointer, CLAUDE.md mirror, and validation seam.
  • Covers: US-001, US-002, US-003, US-005
• AC-014: The canonical hi-cli source, its bundled Harness copy, generated prompt instructions, and published stable baseline retain the tested contract without manual mirror edits.
  • Covers: US-004, US-005

Constraints

• Repository structure and local conventions dominate the scoped prompt budget. Raw trees, counts, versions, ports, command inventories, generic evidence policy, skill semantics, and duplicated root policy remain outside it.
• A scoped prompt describes semantic responsibilities and choices rather than a mechanically reproducible tree.
• The fixed 15-scope regression has a 700-line ceiling. Semantic seams, rather than per-scope practice counts, define completeness.
• Disclosed content is part of the authored scoped-guidance output, not a future documentation placeholder.
• Source inspection always has a visible generic index pointer, while reading and package-specific detail remain task-triggered.
• Phase skills stay out of scoped skill tables.
• Existing curated Example Repository Context remains selected-pack-specific and separate from package Source Guides.
• Shared reusable skill changes follow the canonical source-first workflow and are synchronized downstream from an immutable pushed ref.
• Operator workflow and AI scaffolding changes update the owning docs and runbook in the same implementation.

Dependency Readiness

Ready.

• Harness research dependency: remote research/scoped-agents-guidance resolves to immutable commit 792a463eac9ae9c8f1260de4d4aad6c017e2bbb8; the confirmed grill is retained by descendant commit f73b54e4df5d6609d7a047b799a4e3547754151c.
• Shared-skill dependency: Harness's configured source branch team/stefan/baseline-skills-wait-what in https://github.com/wearedevpunks/skills resolves to immutable commit 1b222d8b1c159052adf976e0a9b02717a7df1b90 and is available for the accepted source-first hi-cli change without importing unrelated source-line drift.
• No prototype or external provider dependency applies.

Branch/Base Intent

• Harness parent evidence: research/scoped-agents-guidance at 792a463eac9ae9c8f1260de4d4aad6c017e2bbb8.
• Harness child branch: team/stefan/refactor-scoped-agents-guidance; retain the research lineage during implementation, then squash the reviewed result onto the latest origin/main before baseline publication.
• Shared-skill child constraint: create a dedicated team/stefan/* branch from the configured source branch at 1b222d8b1c159052adf976e0a9b02717a7df1b90, push the canonical hi-cli change first, and sync Harness from that exact retained ref.

Accepted Technical Decisions

• Treat generated docs/workspace prompt specifications as the sole detailed contract and generated system/handoff text as routing surfaces.
• Update only the lazily reached hi-cli Scaffold branch with concise authoring hints; keep unrelated command branches free of scoped-prompt policy.
• Keep installed skill semantics in installed skill files; do not add descriptive fields or discovered prose to the context model.
• Author disclosed references as ordinary scope-owned Markdown, link them relatively through exact triggers, and verify every target in the same continuation.
• Keep disclosed references outside managed specialist guidance so they load only when their pointer fires.
• Emit the Source Guide index for every scaffold, including an empty guide set.
• Preserve current authored nested-prompt discovery and update behavior.
• Restrict the new scoped contract to docs and workspace targets even where the current renderer shares a generic non-root path with shared guidance.

Accepted Testing Decisions

• Lock compact generated docs/workspace prompt-spec wording and prove root/shared exclusion with focused content contracts.
• Prove the fixed 15-scope fixture stays within 700 lines while preserving skill IDs, explicit-invocation pointers, Source Guide, mirror, and validation seams.
• Lock generated handoff and system-prompt routing as pointers without a second detailed checklist.
• Prove opensrc/README.md exists and remains a valid target for both populated and empty Source Guide selections.
• Preserve existing nested-prompt/update tests.
• Test the canonical hi-cli Scaffold guidance before syncing; verify canonical and bundled bytes match after an exact-ref sync.
• Run focused CLI contracts before CLI type/static checks, wiki-content checks, a fresh scaffold drift check, clean squash integration, and baseline readback.

Verification Seams

• Detailed contract seam: generated docs and workspace prompt-spec Markdown.
• Boundary seam: generated root/shared/docs/workspace target differences.
• Continuation seam: generated agent handoff and system-prompt summaries.
• Skill seam: selected non-phase skill IDs and installed SKILL.md sources.
• Progressive-disclosure seam: each inline task trigger and its resolving scope-owned Markdown target.
• Source seam: emitted opensrc/README.md for empty and populated guide sets.
• Operator seam: the canonical and synchronized hi-cli Scaffold branch.
• Distribution seam: retained CLI/baseline artifacts and published stable baseline readback.

Parked Decisions

• Root/global Workflow Routing placement and invocation semantics. Owner: Stefan. Resume trigger: a dedicated root/global prompt requirements request.
• Root and shared prompt redesign. Owner: Stefan. Resume trigger: explicit scope expansion beyond scoped docs/workspace coding standards.
• Rewriting this repository's current scoped prompts. Owner: Stefan. Resume trigger: a separate Harness prompt migration request.
• Removing or reconciling existing authored nested prompts. Owner: repository maintainers. Resume trigger: explicit nested-prompt ownership requirements.
• Managed inventory or schema for disclosed reference content. Owner: Harness maintainers. Resume trigger: a proven need for Harness to generate, inventory, or reconcile those author-owned files mechanically.

Decision Log