0xrsydn/arch-dotfiles
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

pi: change model and agent harness as uiux for subagent extensions

Browse source
This commit is contained in:
Rasyidan Akbar F. 2026-03-16 07:01:29 +07:00
commit b31929bbf3
9 changed files with 577 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

178
.pi/agent/prompts/repo-init-deep.md Normal file
View 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

147
.pi/agent/prompts/repo-init.md Normal file
View file

@ -0,0 +1,147 @@
---
description: Set up or optimize the current repository for agent-first development (AGENTS.md, docs structure, progressive disclosure)
---
Set up or optimize the current repository for agent-first development. 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 state first.
2. Compare the repo against the checklist below.
3. Prefer minimal, high-leverage, versioned changes.
4. Preserve useful project-specific guidance instead of replacing it blindly.
## When to Use
- Setting up a new repo for agent-driven development
- Optimizing an existing repo's AGENTS.md / CLAUDE.md
- Restructuring docs for agent legibility
## Core Principles
### 1. AGENTS.md = Table of Contents, Not Encyclopedia
- **Max ~100 lines.** Short, stable entry point.
- Only universally applicable instructions (applies to EVERY task).
- Points to deeper sources of truth — doesn't contain them.
- Domain-specific rules go in sub-files (`docs/`, skills, or scoped AGENTS.md in subdirs).
### 2. Progressive Disclosure
- Agent starts with a small map and is taught where to look next.
- Use nested AGENTS.md files in subdirectories for scoped context.
- Skills for domain-specific workflows (loaded on demand, not always).
- Don't frontload — let the agent discover context as needed.
### 3. Repository = System of Record
- If it's not in the repo, it doesn't exist to the agent.
- Push decisions, architecture, plans, conventions INTO the repo as versioned artifacts.
- No tribal knowledge in Slack, Google Docs, or people's heads.
- Docs are code — they get reviewed, updated, and maintained.
### 4. Agent Legibility First
- Optimize for agent comprehension, not just human readability.
- Favor "boring" tech — composable, stable APIs, well-represented in training data.
- Make the app inspectable: logs, metrics, test output should be agent-parseable.
- Structured formats (JSON, markdown with clear headers) > prose walls.
### 5. Enforce, Don't Instruct
- Invariants via CI/linters > instructions in AGENTS.md.
- Type checks, tests, formatting rules catch mistakes mechanically.
- Agent can run verification itself (`make check`, `npm test`, etc.).
- Instructions the agent can't verify will eventually be ignored.
### 6. Less Instructions = Better Compliance
- LLMs reliably follow ~150-200 instructions max (frontier thinking models).
- Agent harnesses already consume ~50 instructions in system prompt.
- Every instruction in AGENTS.md competes for attention budget.
- When everything is "important," nothing is.
## AGENTS.md Template
```markdown
# AGENTS.md
## Project
<1-2 sentences: what this project is and does>
## Stack
<bullet list of key tech: language, framework, DB, infra>
## Structure
<brief map of key directories and what they contain>
## Development
<how to build, run, test — the essential commands>
## Docs
Detailed documentation lives in `docs/`:
- `docs/ARCHITECTURE.md` — system design, package layering, domain map
- `docs/CONVENTIONS.md` — code style, patterns, naming
- `docs/PLANS.md` — active execution plans and progress
- `docs/DECISIONS.md` — architecture decision records (ADRs)
## Verification
<how to verify changes: test commands, type checks, linters>
## Rules
<only universal, always-applicable rules — keep to <10 items>
```
## docs/ Structure
```
docs/
├── ARCHITECTURE.md # System design, domain map, package layering
├── CONVENTIONS.md # Code style, patterns, naming conventions
├── DECISIONS.md # Architecture Decision Records (ADRs)
├── PLANS.md # Active plans, completed plans, tech debt
└── <domain>/ # Domain-specific deep docs as needed
```
## 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).
**Commands:**
```bash
# If AGENTS.md exists but no CLAUDE.md
ln -s AGENTS.md CLAUDE.md
# If only CLAUDE.md exists
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md
# Verify
ls -la CLAUDE.md # should show -> AGENTS.md
```
## Checklist
When initializing or optimizing a repo:
- [ ] AGENTS.md exists and is <100 lines
- [ ] CLAUDE.md is symlinked to AGENTS.md (or vice versa)
- [ ] AGENTS.md contains: project summary, stack, structure map, dev commands, verification
- [ ] Domain-specific instructions are NOT in root AGENTS.md
- [ ] `docs/` directory exists with at minimum ARCHITECTURE.md
- [ ] Verification commands are documented and runnable by agent
- [ ] CI/linters enforce key invariants (not just documented)
- [ ] No critical knowledge lives only outside the repo
## Anti-Patterns
- ❌ Stuffing every possible command into AGENTS.md
- ❌ Adding "hotfix" instructions for one-off behavior issues
- ❌ Instructions that aren't verifiable or enforceable
- ❌ Monolithic instruction files that rot over time
- ❌ Architecture decisions living in chat/docs outside repo
## Sources
- OpenAI: https://openai.com/index/harness-engineering/
- HumanLayer: https://www.humanlayer.dev/blog/writing-a-good-claude-md