Enhance documentation and configuration for graphify and PRP core - #10
Merged
rodrigorjsf merged 22 commits intoApr 22, 2026
Merged
Conversation
Adds graphify skill reference and invocation instructions to both .github/copilot-instructions.md and CLAUDE.md to guide users on knowledge graph functionality.
Add graphify-out/cache/ to .gitignore to exclude generated knowledge graph cache files from version control.
Add .graphifyignore to exclude internal graphify directories and .mcp.json to configure the graphify MCP server for local development.
Introduces new documentation files covering various AI agent communication protocols, including A2A, MCP, and ACP, along with their applications, architectural paradigms, and future directions. The updates aim to standardize understanding and facilitate interoperability among AI agents, enhancing collaborative capabilities across diverse systems. Key documents include a detailed guide on AI agent protocols, a summary of emerging communication standards, and insights into fluid human-agent collaboration.
Add five shared reference files to both the shipped plugin and the .claude/ dev mirror: - harness-taxonomy.md: component class definitions (artifact/advisory/utility) - context-budget-policy.md: smart-zone, compaction, and brief size rules - execution-policy.md: four delegation modes (inline/subagent/parallel/harness) - artifact-lifecycle.md: PRP artifact locations, naming, and archival rules - agent-prompt-style.md: HumanLayer-inspired one-job/hard-boundary/fixed-output structure Shipped and mirror copies are identical line-for-line. Grounded in wiki/knowledge/harness-engineering.md and context-engineering.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a repo-only deterministic contract checker for the prp-core plugin: - scripts/prp_core_prompt_eval.py: runner with --list, --case, --all flags - tests/prp-core/prompt-cases.json: 6 cases (plan, implement, review, issue-fix, mirror-parity, hook-schema) - tests/prp-core/fixtures/: example request fixtures for each workflow family - tests/prp-core/README.md: docs and usage guide - .github/workflows/prp-core-prompt-evals.yml: CI on plugin/mirror/script changes Harness checks: required contract strings in skills, shipped/mirror parity, and research-team-stop.sh six-section schema alignment. Contract checks (plan/implement/review/issue-fix) intentionally FAIL now and will PASS after Task 3 updates skills with shared contract language. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add Context Contract section to 12 skills referencing shared context-budget-policy and execution-policy references. Normalize 5 orchestration-heavy agents (codebase-analyst, codebase-explorer, plan-critic, prp-advisor, web-researcher) with HumanLayer-inspired CRITICAL one-job declaration, explicit DO NOT boundaries, and pointer to agent-prompt-style.md. All changes mirrored to .claude/ mirror. Eval harness: 6/6 pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
artifact-paths.md and agent-conventions.md now point to the authoritative policy files in plugins/prp-core/references/ instead of duplicating policy inline. Hook shell syntax verified. Eval harness: 6/6 pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- plugins/prp-core/README.md: add references/ section with policy file table - plugins/prp-core/CLAUDE.md: update version note and add references/ scope - docs/prp-core-harness-architecture.md: new — component taxonomy, budget policy, delegation modes, agent structure, plugin vs repo boundaries - docs/prp-core-prompt-evals.md: new — harness usage, test case guide, CI - README.md: add references/ and docs/ to repository layout tree Eval harness: 6/6 pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Plugin artifacts must be self-contained. Replace the external source attribution in agent-prompt-style.md with an inline description of the pattern itself. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Introduce a new .gitattributes file to mark specific directories as linguist-generated, including .claude/, docs/, graphify-out/, and wiki/. This helps improve repository statistics and file handling in GitHub.
Modify the .gitattributes file to remove the linguist-generated markers for the .claude/, docs/, graphify-out/, and wiki/ directories, ensuring they are no longer treated as generated files by GitHub Linguist.
…t-generated Revise the .gitattributes file to ensure that the .claude/, docs/, graphify-out/, and wiki/ directories are properly marked as linguist-generated, improving file handling in GitHub.
Add autoresearch-ref directory and a rule to ignore all PDF files in the .gitignore, improving file management and reducing clutter in the repository.
Delete several obsolete documentation files related to the PRP Core Harness Architecture, Prompt Evaluations, and agent protocols, streamlining the repository and removing clutter. This includes the removal of files that no longer align with the current project structure and focus.
Modify the .gitignore file to include the docs/ directory, enhancing file management and reducing clutter in the repository.
Delete multiple outdated documentation files and query markdowns from the graphify-out directory, including various agent protocols, structured outputs, and context engineering documents. This cleanup enhances repository organization and aligns with the current project focus.
…oval, rule fixes - Root CLAUDE.md: replace skills inventory table with weighted Priorities section (Smart Zone/Harness-First/Subagent Isolation/Artifact-First/Progressive Disclosure); add rubber-duck to root-only extras; add pre-creation prp-advisor instruction; shorten graphify trigger to 1 line; net −6 lines - wiki/CLAUDE.md: fix typo; remove vague overview sentence and directory listing block (agent-inferable via filesystem); net −9 lines - prp-workflow.md: remove functionally-dead 'Before Creating' pre-creation section (path-scope chicken-and-egg bug); disambiguate 'the skill's' → prp-prd/prp-plan - plugins/prp-core/CLAUDE.md: remove stale version header (high-churn inventory) - .claude/rules/: add dev-only marker to 4 unshipped rules that cover plugin paths - NEW .claude/rules/harness-engineering.md: path-scoped harness conventions with 5 weighted priorities grounded in context-budget-policy.md and wiki - NEW .claude/rules/reference-conventions.md: authoring conventions for references/ - NEW .github/instructions/harness-engineering.instructions.md: Copilot review checks for smart zone, harness rails, subagent isolation, plugin boundary, artifact discipline Always-loaded tokens: ~480 → ~330 (net −150 tokens) Eval harness: 6/6 pass Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- GRAPH_REPORT.md: updated word count from ~358,130 to ~358,074 words; refined the corpus check summary to maintain clarity and relevance.
…in README - Add plugins/prp-core/rules/harness-engineering.md (plugin-facing version): user-relevant paths only (.claude/**/*.md, *.prd.md, *.plan.md), no dev eval command, references use relative references/ path. Ships the same 5 smart-zone priorities as the dev mirror so plugin users get harness enforcement too. - Fix plugins/prp-core/rules/prp-workflow.md: disambiguate 'the skill's' → 'prp-prd skill's' and 'prp-plan skill's' to match the dev mirror fix. - Expand plugins/prp-core/README.md with full artifact registry: every skill (why it exists, what it produces, upstream/downstream connections), every agent (class, role, invoked by), both rules (why each ships), both hooks (structural contract each enforces), all 5 references (why + used by), artifact directory tree with per-directory purpose, and workflow overview diagram. Rules count table updated 1 → 2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- GRAPH_REPORT.md: increased word count from ~358,074 to ~359,895 words; reaffirmed that the corpus is sufficiently large to enhance graph structure value.
rodrigorjsf
added a commit
that referenced
this pull request
Apr 22, 2026
* docs: update README to credit original project and provide links for deeper understanding * Enhance documentation and configuration for graphify and PRP core (#10) * docs: add graphify skill documentation Adds graphify skill reference and invocation instructions to both .github/copilot-instructions.md and CLAUDE.md to guide users on knowledge graph functionality. * chore: ignore graphify output cache Add graphify-out/cache/ to .gitignore to exclude generated knowledge graph cache files from version control. * feat: add graphify MCP configuration Add .graphifyignore to exclude internal graphify directories and .mcp.json to configure the graphify MCP server for local development. * docs: add comprehensive documentation for AI agent protocols Introduces new documentation files covering various AI agent communication protocols, including A2A, MCP, and ACP, along with their applications, architectural paradigms, and future directions. The updates aim to standardize understanding and facilitate interoperability among AI agents, enhancing collaborative capabilities across diverse systems. Key documents include a detailed guide on AI agent protocols, a summary of emerging communication standards, and insights into fluid human-agent collaboration. * feat(prp-core): add shared harness reference layer Add five shared reference files to both the shipped plugin and the .claude/ dev mirror: - harness-taxonomy.md: component class definitions (artifact/advisory/utility) - context-budget-policy.md: smart-zone, compaction, and brief size rules - execution-policy.md: four delegation modes (inline/subagent/parallel/harness) - artifact-lifecycle.md: PRP artifact locations, naming, and archival rules - agent-prompt-style.md: HumanLayer-inspired one-job/hard-boundary/fixed-output structure Shipped and mirror copies are identical line-for-line. Grounded in wiki/knowledge/harness-engineering.md and context-engineering.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(repo): add prp-core prompt evaluation harness Add a repo-only deterministic contract checker for the prp-core plugin: - scripts/prp_core_prompt_eval.py: runner with --list, --case, --all flags - tests/prp-core/prompt-cases.json: 6 cases (plan, implement, review, issue-fix, mirror-parity, hook-schema) - tests/prp-core/fixtures/: example request fixtures for each workflow family - tests/prp-core/README.md: docs and usage guide - .github/workflows/prp-core-prompt-evals.yml: CI on plugin/mirror/script changes Harness checks: required contract strings in skills, shipped/mirror parity, and research-team-stop.sh six-section schema alignment. Contract checks (plan/implement/review/issue-fix) intentionally FAIL now and will PASS after Task 3 updates skills with shared contract language. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(prp-core): standardize context and agent contracts Add Context Contract section to 12 skills referencing shared context-budget-policy and execution-policy references. Normalize 5 orchestration-heavy agents (codebase-analyst, codebase-explorer, plan-critic, prp-advisor, web-researcher) with HumanLayer-inspired CRITICAL one-job declaration, explicit DO NOT boundaries, and pointer to agent-prompt-style.md. All changes mirrored to .claude/ mirror. Eval harness: 6/6 pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(rules): link guardrail rules to shared references artifact-paths.md and agent-conventions.md now point to the authoritative policy files in plugins/prp-core/references/ instead of duplicating policy inline. Hook shell syntax verified. Eval harness: 6/6 pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: refresh documentation for harness evolution - plugins/prp-core/README.md: add references/ section with policy file table - plugins/prp-core/CLAUDE.md: update version note and add references/ scope - docs/prp-core-harness-architecture.md: new — component taxonomy, budget policy, delegation modes, agent structure, plugin vs repo boundaries - docs/prp-core-prompt-evals.md: new — harness usage, test case guide, CI - README.md: add references/ and docs/ to repository layout tree Eval harness: 6/6 pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore: update plugin version * refactor(references): remove external HumanLayer attribution Plugin artifacts must be self-contained. Replace the external source attribution in agent-prompt-style.md with an inline description of the pattern itself. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore: add .gitattributes to manage linguist-generated files Introduce a new .gitattributes file to mark specific directories as linguist-generated, including .claude/, docs/, graphify-out/, and wiki/. This helps improve repository statistics and file handling in GitHub. * chore: update .gitattributes to remove linguist-generated markers Modify the .gitattributes file to remove the linguist-generated markers for the .claude/, docs/, graphify-out/, and wiki/ directories, ensuring they are no longer treated as generated files by GitHub Linguist. * chore: update .gitattributes to correctly mark directories as linguist-generated Revise the .gitattributes file to ensure that the .claude/, docs/, graphify-out/, and wiki/ directories are properly marked as linguist-generated, improving file handling in GitHub. * chore: update .gitignore to include autoresearch-ref and PDF files Add autoresearch-ref directory and a rule to ignore all PDF files in the .gitignore, improving file management and reducing clutter in the repository. * chore: remove outdated documentation files Delete several obsolete documentation files related to the PRP Core Harness Architecture, Prompt Evaluations, and agent protocols, streamlining the repository and removing clutter. This includes the removal of files that no longer align with the current project structure and focus. * chore: update .gitignore to ignore docs directory Modify the .gitignore file to include the docs/ directory, enhancing file management and reducing clutter in the repository. * chore: remove deprecated documentation and query files Delete multiple outdated documentation files and query markdowns from the graphify-out directory, including various agent protocols, structured outputs, and context engineering documents. This cleanup enhances repository organization and aligns with the current project focus. * refactor(memory): improve-claude pass — harness priorities, bloat removal, rule fixes - Root CLAUDE.md: replace skills inventory table with weighted Priorities section (Smart Zone/Harness-First/Subagent Isolation/Artifact-First/Progressive Disclosure); add rubber-duck to root-only extras; add pre-creation prp-advisor instruction; shorten graphify trigger to 1 line; net −6 lines - wiki/CLAUDE.md: fix typo; remove vague overview sentence and directory listing block (agent-inferable via filesystem); net −9 lines - prp-workflow.md: remove functionally-dead 'Before Creating' pre-creation section (path-scope chicken-and-egg bug); disambiguate 'the skill's' → prp-prd/prp-plan - plugins/prp-core/CLAUDE.md: remove stale version header (high-churn inventory) - .claude/rules/: add dev-only marker to 4 unshipped rules that cover plugin paths - NEW .claude/rules/harness-engineering.md: path-scoped harness conventions with 5 weighted priorities grounded in context-budget-policy.md and wiki - NEW .claude/rules/reference-conventions.md: authoring conventions for references/ - NEW .github/instructions/harness-engineering.instructions.md: Copilot review checks for smart zone, harness rails, subagent isolation, plugin boundary, artifact discipline Always-loaded tokens: ~480 → ~330 (net −150 tokens) Eval harness: 6/6 pass Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * update(graph_report): adjust word count and refine corpus check summary - GRAPH_REPORT.md: updated word count from ~358,130 to ~358,074 words; refined the corpus check summary to maintain clarity and relevance. * docs(plugin): ship harness-engineering rule + full artifact registry in README - Add plugins/prp-core/rules/harness-engineering.md (plugin-facing version): user-relevant paths only (.claude/**/*.md, *.prd.md, *.plan.md), no dev eval command, references use relative references/ path. Ships the same 5 smart-zone priorities as the dev mirror so plugin users get harness enforcement too. - Fix plugins/prp-core/rules/prp-workflow.md: disambiguate 'the skill's' → 'prp-prd skill's' and 'prp-plan skill's' to match the dev mirror fix. - Expand plugins/prp-core/README.md with full artifact registry: every skill (why it exists, what it produces, upstream/downstream connections), every agent (class, role, invoked by), both rules (why each ships), both hooks (structural contract each enforces), all 5 references (why + used by), artifact directory tree with per-directory purpose, and workflow overview diagram. Rules count table updated 1 → 2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * update(graph_report): increment word count and confirm corpus adequacy - GRAPH_REPORT.md: increased word count from ~358,074 to ~359,895 words; reaffirmed that the corpus is sufficiently large to enhance graph structure value. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces a standardized prompt structure for all PRP agents and adds comprehensive reference documentation for core harness policies, artifact lifecycle, execution policy, and component taxonomy. It updates agent prompts to follow the new structure, clarifies workflow and artifact path conventions, and introduces new engineering rules to ensure consistency, context efficiency, and artifact discipline across the codebase.
Standardization of Agent Prompts:
.claude/agents/now follow a unified format: a critical role declaration, explicit "DO NOT" boundaries, core responsibilities, strategy, and output format, as defined in the new reference guide. [1] [2] [3] [4] [5]Addition of Authoritative Reference Files:
Rule and Convention Updates:
.claude/rules/now reference the new authoritative documentation rather than duplicating policy, and clarify agent conventions, artifact path contracts, and hook conventions. [1] [2] [3]Harness Engineering and Workflow Enhancements:
Most important changes:
Agent Prompt Standardization
agent-prompt-style.md. [1] [2] [3] [4] [5].claude/references/agent-prompt-style.mdfile defines this structure and provides adaptation guidance for existing agents.Policy and Reference Documentation
.claude/references/harness-taxonomy.md,.claude/references/artifact-lifecycle.md,.claude/references/context-budget-policy.md, and.claude/references/execution-policy.mdto centralize core harness, artifact, and execution policies. [1] [2] [3] [4]Rule File Updates
.claude/rules/agent-conventions.md,.claude/rules/artifact-paths.md, and.claude/rules/hook-conventions.mdto reference these new authoritative sources and clarify their scope as dev-only, non-shipped rules. [1] [2] [3]Engineering and Workflow Conventions
.claude/rules/harness-engineering.mdwith prioritized engineering conventions for context management, artifact discipline, and subagent isolation..claude/rules/prp-workflow.mdto specify which skills/templates are used during PRP artifact creation and updates. [1] [2]