pi: change model and agent harness as uiux for subagent extensions
This commit is contained in:
parent
2de7c7613d
commit
b31929bbf3
9 changed files with 577 additions and 51 deletions
178
.pi/agent/prompts/repo-init-deep.md
Normal file
178
.pi/agent/prompts/repo-init-deep.md
Normal file
|
|
@ -0,0 +1,178 @@
|
|||
---
|
||||
description: Set up or optimize a large repository or monorepo for agent-first development using hierarchical AGENTS.md files and progressive disclosure
|
||||
---
|
||||
|
||||
Set up or optimize the current repository for agent-first development, assuming it may be a large repo or monorepo. Use hierarchical `AGENTS.md` files only where they add real value. Based on principles from OpenAI's harness engineering and HumanLayer's CLAUDE.md guide.
|
||||
|
||||
Additional user context and constraints:
|
||||
$ARGUMENTS
|
||||
|
||||
Before changing anything:
|
||||
1. Inspect the repository structure first.
|
||||
2. Identify true subsystem boundaries before proposing nested `AGENTS.md` files.
|
||||
3. Prefer minimal, high-leverage, versioned changes.
|
||||
4. Preserve useful project-specific guidance instead of replacing it blindly.
|
||||
5. Do **not** generate `AGENTS.md` files for every directory.
|
||||
|
||||
## When to Use
|
||||
- Large repositories with multiple domains, apps, services, or packages
|
||||
- Monorepos with different build/test workflows per subtree
|
||||
- Repos where one root `AGENTS.md` is too broad to stay short and useful
|
||||
- Repos that need progressive disclosure for agent context
|
||||
|
||||
## Goal
|
||||
Design an agent-legible documentation layout where:
|
||||
- the root `AGENTS.md` stays short and repo-wide,
|
||||
- nested `AGENTS.md` files exist only for meaningful boundaries,
|
||||
- each nested file contains local rules, commands, and navigation help for that subtree,
|
||||
- duplication across levels is minimized.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Root AGENTS.md Is the Map
|
||||
- The root `AGENTS.md` should remain a concise project-wide entry point.
|
||||
- It should describe the repo, major subsystems, shared commands, verification, and where deeper context lives.
|
||||
- It should point agents toward important subtrees that have their own `AGENTS.md`.
|
||||
|
||||
### 2. Nested AGENTS.md Files Are Scoped
|
||||
Create nested `AGENTS.md` files only when a subtree has at least one of these:
|
||||
- a distinct purpose or domain boundary,
|
||||
- different commands or verification workflow,
|
||||
- different conventions or architectural constraints,
|
||||
- separate deploy/runtime concerns,
|
||||
- enough complexity that local guidance reduces confusion.
|
||||
|
||||
If a subtree has no distinct guidance, do **not** create a nested `AGENTS.md` there.
|
||||
|
||||
### 3. Progressive Disclosure Over Duplication
|
||||
- Parent files provide broad context.
|
||||
- Child files add only local context.
|
||||
- Do not copy the same rules into every nested file.
|
||||
- Child files should extend or narrow the parent context, not restate it.
|
||||
|
||||
### 4. Repository = System of Record
|
||||
- If a decision matters for agents, put it in the repo.
|
||||
- Architecture, conventions, plans, and decisions should live in versioned docs.
|
||||
- Avoid relying on external-only knowledge.
|
||||
|
||||
### 5. Enforce, Don’t Instruct
|
||||
- Put invariants into CI, tests, linters, type checks, and scripts whenever possible.
|
||||
- Document verification commands the agent can actually run.
|
||||
- Avoid instructions that cannot be checked mechanically.
|
||||
|
||||
### 6. Less Instructions = Better Compliance
|
||||
- Keep every `AGENTS.md` compact.
|
||||
- Root file should usually stay under ~100 lines.
|
||||
- Nested files should be even narrower: only the local rules that matter for that subtree.
|
||||
|
||||
## Suggested Hierarchy
|
||||
|
||||
Only as needed, not by default:
|
||||
|
||||
```text
|
||||
project/
|
||||
├── AGENTS.md # project-wide context and repo map
|
||||
├── CLAUDE.md -> AGENTS.md
|
||||
├── docs/
|
||||
│ ├── ARCHITECTURE.md
|
||||
│ ├── CONVENTIONS.md
|
||||
│ ├── DECISIONS.md
|
||||
│ └── PLANS.md
|
||||
├── apps/
|
||||
│ ├── AGENTS.md # app-layer guidance, if meaningful
|
||||
│ ├── web/
|
||||
│ │ └── AGENTS.md # only if web has distinct workflow/conventions
|
||||
│ └── api/
|
||||
│ └── AGENTS.md # only if api has distinct workflow/conventions
|
||||
└── packages/
|
||||
├── AGENTS.md # shared package conventions, if meaningful
|
||||
└── design-system/
|
||||
└── AGENTS.md # only if this subtree needs extra local guidance
|
||||
```
|
||||
|
||||
## Heuristics for Where to Add Nested AGENTS.md
|
||||
|
||||
Good candidates:
|
||||
- `apps/`, `services/`, `packages/`, `libs/`
|
||||
- frontend vs backend boundaries
|
||||
- infra / deployment / ops directories
|
||||
- design systems or component libraries
|
||||
- generated-code boundaries with special rules
|
||||
- domains with their own test/build/dev commands
|
||||
|
||||
Poor candidates:
|
||||
- shallow folders with no local rules
|
||||
- directories that only mirror code organization but not workflow differences
|
||||
- every leaf folder in the tree
|
||||
- locations where the nested file would just repeat the parent file
|
||||
|
||||
## What Each Level Should Contain
|
||||
|
||||
### Root `AGENTS.md`
|
||||
Include:
|
||||
- project summary
|
||||
- stack overview
|
||||
- top-level repo map
|
||||
- key shared commands
|
||||
- verification commands
|
||||
- links to `docs/`
|
||||
- pointers to nested `AGENTS.md` files where relevant
|
||||
- only universal repo-wide rules
|
||||
|
||||
### Nested `AGENTS.md`
|
||||
Include only local details such as:
|
||||
- purpose of that subtree
|
||||
- important local directories/files
|
||||
- local dev/build/test commands
|
||||
- local patterns or constraints
|
||||
- where to find deeper docs for that subsystem
|
||||
- any local generated-code or migration rules
|
||||
|
||||
Do **not** repeat broad repo-wide guidance unless needed for clarity.
|
||||
|
||||
## Recommended Process
|
||||
|
||||
1. Inspect the repo structure and tooling.
|
||||
2. Identify subsystem boundaries that actually justify local guidance.
|
||||
3. Design the smallest useful hierarchy of `AGENTS.md` files.
|
||||
4. Create or refine root `AGENTS.md` first.
|
||||
5. Add nested `AGENTS.md` files only for meaningful subtrees.
|
||||
6. Add or update `docs/` files for architecture/conventions/decisions as needed.
|
||||
7. Ensure `CLAUDE.md` exists as a symlink to root `AGENTS.md`.
|
||||
8. Keep files concise and avoid duplication.
|
||||
|
||||
## AGENTS.md ↔ CLAUDE.md Symlink
|
||||
|
||||
Always ensure both files exist so the repo works with any agent harness (Claude Code, OpenCode, Codex, etc.).
|
||||
|
||||
**Rules:**
|
||||
- `AGENTS.md` is the source of truth (canonical file).
|
||||
- `CLAUDE.md` is a symlink to `AGENTS.md`.
|
||||
- If only `CLAUDE.md` exists, rename it to `AGENTS.md` and create the symlink.
|
||||
- If both exist as separate files, merge into `AGENTS.md` and replace `CLAUDE.md` with symlink.
|
||||
- Add `CLAUDE.md` symlink to git (git tracks symlinks fine).
|
||||
|
||||
## Checklist
|
||||
|
||||
When initializing or optimizing a large repo or monorepo:
|
||||
|
||||
- [ ] Root `AGENTS.md` exists and stays short
|
||||
- [ ] Root `CLAUDE.md` is a symlink to `AGENTS.md`
|
||||
- [ ] Root file contains only repo-wide guidance
|
||||
- [ ] Nested `AGENTS.md` files exist only at meaningful subsystem boundaries
|
||||
- [ ] Nested files add local context instead of duplicating parent guidance
|
||||
- [ ] `docs/` exists with at least `ARCHITECTURE.md`
|
||||
- [ ] Verification commands are documented and runnable
|
||||
- [ ] CI/linters enforce important invariants where possible
|
||||
- [ ] No critical workflow or architectural knowledge lives only outside the repo
|
||||
|
||||
## Anti-Patterns
|
||||
- ❌ Generating `AGENTS.md` in every directory
|
||||
- ❌ Repeating the same instructions at root and child levels
|
||||
- ❌ Putting domain-specific rules into the root file when they only matter in one subtree
|
||||
- ❌ Creating deep hierarchy without distinct workflow boundaries
|
||||
- ❌ Letting nested files drift from actual commands and tooling
|
||||
|
||||
## Sources
|
||||
- OpenAI: https://openai.com/index/harness-engineering/
|
||||
- HumanLayer: https://www.humanlayer.dev/blog/writing-a-good-claude-md
|
||||
Loading…
Add table
Add a link
Reference in a new issue