Surface Inventory
The layered files and generated specs that shape agent behavior
Prompt surfaces exist to prevent private forks of the AI workflow. If every developer edits local guidance, the repository only looks harnessed. The actual agent behavior has drifted.
Harness treats generated prompt surfaces as managed output: inspectable in the repo, changed at the baseline or pack source, and redistributed through the CLI. Their job is to make context ownership explicit.
Surface Inventory
The core prompt-surface question is: where does this rule belong? Broad quality criteria belong high. Repo identity belongs at the root. Scoped skills and examples belong near the code. Durable non-obvious knowledge belongs in notes. Short-lived intent belongs in the current run.
| Surface | Owns | Must not own |
|---|---|---|
Repo .agents/AGENTS.md | Generated shared quality criteria, engineering posture, validation habits, source inspection habits, and team operating taste. | Repo-specific app maps, package invariants, product requirements, or local business logic. |
Root AGENTS.md | Repo identity, app/package ownership, workflow routing, cross-surface contract rules, validation routing, and source-of-truth rules. | Detailed rules for one app, package, docs surface, framework-specific task, or root Primary skills here lists. |
Scoped AGENTS.md | Local ownership rules, scoped skill activation, upstream examples to inspect, and invariants for the files nearby. | Company-wide quality criteria or broad lifecycle workflow definitions. |
| Memory notes | Durable non-obvious gotchas, decisions, setup quirks, and hard-won debugging findings. | Session summaries, changelogs, obvious file maps, or material that belongs in specs, runbooks, or wiki pages. |
| Prompt handoff and generated specs | Scaffold-time guidance, setup handoff, detected packs, and instructions for the next agent run. | Private local preferences or final product truth that belongs in the consumer repository. |
| Hooks and required-tool manifests | Repeatable guardrails for checks, formatting, tool availability, and validation ergonomics. | Explanations that belong in docs or rules that require human judgment. |
Managed Output
Prompt surfaces are managed artifacts. Operators inspect them, but they do not personalize them in place. If a durable rule needs to change, the change belongs in the harness baseline, pack source, scaffold logic, or owning repo source that generates the surface.
Root and scoped prompts are still repo-tailored. They are generated by the agent running dp / punks setup with the scaffold guidance, detected packs, and actual repository evidence. The result should fit the repo, but the source of that fit remains the managed setup flow rather than private local edits.
Consumer-repo business logic stays in the consumer repo. The CLI distributes the harness surfaces and setup contract, but it does not become the source of truth for a target product.
Setup Flow
punks scaffold setup writes the shared harness baseline, selected skills, hook files, subagent templates, prompt specs, required-tool manifests, setup handoff, and .devpunks/scaffold-manifest.json. The setup agent then materializes root and scoped prompt surfaces from those instructions and the repository it is standing in. Root specs carry criteria and invariants for that step; they are not a hardcoded final root prompt.
That split keeps two things true:
- the CLI stays deterministic at detection, pack resolution, and baseline distribution time
- the generated prompts are tailored to the current repo instead of copied as generic text
Drift Signals
Prompt drift has two main causes:
- The harness baseline changes. Core guidance, packs, skills, hooks, or setup templates were updated upstream, so the repository needs a manual
dp update/punks updaterun to receive the new managed surface. - The repo surface was edited by hand. A user changed a generated prompt surface locally, creating a private variant of the AI workflow.
The fix is not a longer one-off prompt. Upstream changes should flow through the update command. Local edits should be removed and replaced by a change to the harness source that generated the surface.