Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (42 loc) · 7.33 KB

AGENTS.md

File metadata and controls

58 lines (42 loc) · 7.33 KB
Raw

AGENTS.md

Guidance for agents working on this repository — what it is, the philosophy behind it, and how to improve its skills and assets.

What this repo is

A personal PRP (Product Requirement Prompt) framework — an agentic-engineering workflow packaged as Claude Code Agent Skills. It is not an application: its "source" is prompts and assets — skills, agents, templates, and curated docs.

PRP = PRD + curated codebase intelligence + agent/runbook — the minimum context an AI needs to ship a vertical slice of working software in one pass.

This framework is load-bearing: it's used on real, active projects every day. Treat changes accordingly — preserve behavior, stay conservative, and don't destabilize working skills for the sake of elegance.

Philosophy

The principles that govern everything here:

  • Context is King — give the agent all the context it needs (inline, in references, or fetched at runtime), curated, never dumped.
  • Validation loops — workflow skills ship executable gates the agent loops on until green; prefer an authoritative external check over a self-reported "done."
  • Information dense — real patterns, real file:line, real commands; no filler, no restating what the model already knows.
  • Progressive success — ship the lean spine first, validate, then enrich.
  • Prescribe the craft, not the content — be strict on how a skill is built; stay agnostic about what a given skill or its output should contain (that's per-project, the author's call). The one deliberate escape hatch is a free-form "Agent Notes" canvas.
  • One source of truth — a skill lives in one place; if it must exist in two, generate/sync one from the other rather than hand-maintaining both.
  • Structure implies a maintainer — never add a stateful section (status markers, lifecycle, amendments) that nothing keeps current.
  • Fidelity first — when porting or refactoring, preserve behavior exactly and prove it, then optimize.

What lives where

  • .claude/skills/ — the skills, and the working source of truth. Each is a self-contained Agent Skill: a SKILL.md spine plus optional references/, templates/, scripts/. Manual experiments stay top-level so explicit invocation remains discoverable; register them in PLUGIN_EXCLUDED_SKILLS in sync_plugin.py to keep them out of the plugin other people install. They still render to .agents/skills/, because that target is the author's own Codex install rather than a public distribution.
  • ~/.prp/<key>/ — per-project artifacts and runtime state, stored out-of-repo and shared across the project's worktrees. Artifact-writing skills resolve it with the canonical inline convention block; $PRP_HOME overrides the store root.
  • plugins/prp-core/ — the same skills + agents (+ plugin-only hooks) packaged as a distributable plugin. Its skills/ and agents/ are generated from .claude/ by scripts/sync_plugin.py — never edit them directly; edit the .claude/ source and regenerate. The script owns intentional launcher-path rewrites for bundled skill scripts and excludes personal agents (gpui-researcher). hooks/, README.md, and .claude-plugin/ are plugin-only and hand-maintained.
  • .agents/skills/, .codex/agents/ — the OpenAI Codex CLI render of the pack, also generated by scripts/sync_plugin.py — never edit directly. Skills minus the Claude-only ones (prp-research-team; prp-orchestrate and prp-meta-skill are rendered — orchestrate's delegation mechanics rewrite to harness-agnostic language, meta-skill's authored-skill paths map to .agents/skills), with Claude-isms rewritten (Task-tool dispatch → "spawn the X subagent", prp-core: namespace dropped, /prp-x → $prp-x mentions, an Arguments note replacing $ARGUMENTS substitution); agents converted to Codex custom-agent TOML.
    • Codex reads $CODEX_HOME/skills (~/.codex/skills), not ~/.agents/skills — in Codex, .agents/ is the plugin location (~/.agents/plugins/marketplace.json). Verified against codex-cli 0.147.0; skills surface in the @ picker, and $prp-x is how Codex refers to one in prose. Install globally by symlinking each rendered skill into ~/.codex/skills/ (per-skill, because that directory is shared with every other Codex skill), and ~/.codex/agents → .codex/agents for the subagents. Symlinks track every sync; copies go stale silently.
    • Anything dropped into .agents/skills/ that .claude/skills/ did not generate is deleted by sync_plugin.py's stale prune. Other tools do install skills there (~/.agents/skills is a cross-tool convention some of them use), so keep this directory exclusively prp's; the .gitignore rule (.agents/skills/* with !.agents/skills/prp-*) is the backstop against committing a guest, not against losing one.
  • .claude/agents/, plugins/prp-core/agents/ — advisory review/research subagents. Report-only by prompt (they never modify files or commit), not enforced via tools: allowlists.
  • claude_md_files/ — framework-specific CLAUDE.md examples (Rust, Python, Node, React, …).
  • old-prp-commands/ — the retired slash-command generation, including its old PRPs/templates/ and PRPs/ai_docs/. Reference only — do not maintain or extend it.

How to improve skills and assets

  1. Author or refactor with prp-meta-skill (/prp-core:prp-meta-skill). It encodes the craft: lean SKILL.md, detail in references/, output shapes in templates/, a third-person trigger-rich description, an imperative body, no duplication, and self-containment (no cross-skill file references).
  2. Classify the skill type (workflow / artifact-generator / knowledge / tool-wrapper) and apply only the principles that fit — don't force phases or validation loops onto a knowledge skill.
  3. Regenerate the distribution targets (Claude plugin + Codex render) whenever you touch a skill or agent: python3 scripts/sync_plugin.py (verify with --check).
  4. Bundled scripts must be location-agnostic — derive the project root from git/cwd, never from __file__; the script operates on the user's project, not the skill directory.
  5. Validate the change: skills are markdown (nothing to build); prp_loop.py must pass python3 -m py_compile; python3 scripts/sync_plugin.py --check must pass; the real test is triggering the skill and exercising it end-to-end.

Conventions

  • Agent naming: skills always reference the pack's subagents with the plugin namespace — prp-core:code-reviewer, prp-core:codebase-explorer, … — never bare names. This assumes the prp-core plugin is enabled wherever the skills run (including this repo).
  • Commits & PRs: conventional style (feat(prp-core): …, refactor(…): …), written as a human would — no AI attribution, no Co-Authored-By: Claude.
  • Branches: work on a feature branch; main and development are the primary branches and are kept in sync.
  • Contributing: see CONTRIBUTING.md — changes are scrutinized because the skills are load-bearing.

Don't

  • Don't treat this as an application — there are no app build/test/deploy gates to add here.
  • Don't maintain or extend old-prp-commands/.
  • Don't break a working skill's behavior for a refactor — fidelity first.
  • Don't add cross-skill file references — it breaks self-containment and the plugin sync.