Global, Project, and Scoped Prompts
How prompt authority narrows from shared agent culture to local ownership
Every prompt rule needs the lowest stable owner.
If the rule applies everywhere, keep it global. If it describes the repository, keep it at the project root. If it only becomes true inside one app, package, or docs surface, put it there. This is how Harness keeps prompts small without hiding context.
Here, global means the repo-distributed quality baseline.
Placement Table
| Layer | Belongs Here | Does Not Belong Here |
|---|---|---|
| Global | Quality criteria, validation posture, source inspection habits, interaction norms, and rules the agent should respect in every repo. | Consumer-repo business logic, app maps, package invariants, or product requirements. |
| Project | Repo identity, app/package boundaries, root commands, source-of-truth rules, and conventions that apply across the repository. | Detailed implementation guidance for one app, framework, package, or docs surface. |
| Scoped | Local ownership, scoped skill activation, source examples, dependency inspection targets, and invariants that become true near the files. | Company-wide quality criteria, broad repo orientation, or lifecycle sequencing that belongs in skills. |
Run Path
During a run, the agent should move down the tree until the rule becomes specific enough to act. It starts from the generated global baseline, reads the project root for repository identity, then loads scoped guidance near the files it will change.
That path is what activates the right skills and examples without loading the whole harness into every task. A CLI edit should discover CLI scaffold guidance and relevant upstream examples. A wiki edit should discover routed MDX ownership and docs workflow skills.
Generation Path
punks scaffold setup emits prompt specs, setup handoff, detected packs, selected skills, and managed baseline assets. The setup agent uses those inputs plus repository evidence to materialize root and scoped prompts.
The generated prompts should preserve app/package boundaries, keep local examples current, activate scoped skills where they are useful, and avoid copying consumer-repo business logic into the harness baseline.
If a rule belongs at a different layer, regenerate through the setup or update path instead of patching the prompt locally.