[nisavid]

 

• 
  • AGENTS.md
  • docs/plugin-system/design-principles.md

^{IMPL means non-test source and configuration. TEST means automated verification. DOC means reviewer and user documentation. GEN means generated artifacts. OTHER means files outside those categories. FILES shows added, modified, and removed files as +, ~, and −.}

Summary

Provingkit had no written statement of the methodology its equipment follows. This PR records the core maxim Ivan stated on 2026-10-16 as the opening section of docs/plugin-system/design-principles.md, and points to it from AGENTS.md so that agents writing, revising, or reviewing equipment reach it.

The new section, "Equip agents to adapt from principles", makes three points:

• The maxim. The section states it in Ivan's words from Record Provingkit's core methodology: principles agents adapt from, not prescribed command shapes #605, with two trims: a repeated "any" and "at the same time". In short: agents derive situational policies from consistent principles toward satisfied intents, and grounding paired with agility keeps them coherent and predictable while leaving them autonomous and flexible.
• How to tell the approaches apart. A principle-first rule names the intent it serves, the principle, and the boundary, and leaves the agent to derive the wording, commands, and steps each situation needs. A shape-first rule prescribes the wording or command itself.
• The one exception. Exact wording or commands appear only where an external system matches on them, such as the Conventional Commits header that Cocogitto's commit-msg hook checks. They are marked as an adapter to that system and name the principle they serve.

The AGENTS.md pointer, placed after the CONTEXT.md instruction under "Project context", reads: "Equipment is designed principle-first. Before writing, revising, or reviewing it, read the core maxim that opens docs/plugin-system/design-principles.md."

The change only adds text. The page's other sections and the rest of AGENTS.md are unchanged, and no existing equipment is rewritten to conform. Auditing existing equipment against the maxim and bringing it into line is #613.

Boundary

• Owning surface: the Kit's shared design rationale and the repository's agent instructions. No plugin member changes.
• Issue: nisavid/provingkit#605: records the methodology it asks for; closing it after merge is a separate step.
• Release, publication, installation, or live-qualification authority: none.

Provenance and compatibility

• Source revision or history: the maxim is Ivan's words as quoted in Record Provingkit's core methodology: principles agents adapt from, not prescribed command shapes #605, less the two trims above; the pattern it rules out restates his words there. Ivan approved the section and pointer wording on 2026-10-16, ruled that the adapter exception covers commands as well as wording, and chose the Cocogitto example. He then approved two wording fixes from review, which are the second commit: the adapter label now covers "wording or command", and the pointer says equipment "is designed principle-first" rather than asserting that existing equipment already conforms.
• Compatibility aliases or historical references: none. Existing headings and their anchors are unchanged; the new section sits before "Design for the agents we have".

Validation

Run at 3600e662 from the repository root:

• The Provingkit definition and repository exclusions pass: python scripts/validate_provingkit.py . prints Provingkit source validation passed, python -m unittest tests.test_validate_provingkit runs 104 tests with result OK, and git diff --check over the PR's range is clean.
• Every affected member's focused tests and source validator pass: no plugin member is affected.
• Supported derived locks regenerate without a diff: no content lock, release record, or plugin validator reads either changed file.

An independent Tricritical review of the change ran intent, runtime, and structure critics, each on two models. Its first round, on 9a9b2d38, found nothing blocking; it accepted two wording fixes, which 3600e662 applies, and recorded one follow-up outside the change, now #613. Its second round, on 3600e662, found nothing.

Remaining work

• Merge: Ivan decides.

Review checklist

• The six Agent Plugin members remain independently identified, including Proseweaving.
• Member manifests keep independent identities and versions.
• Historical Linux or macOS inputs are not presented as current qualification.
• This change creates no Provingkit release, tag, release-manifest instance, marketplace publication, or live installation.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added guidance for documenting equipment intent, principles, and boundaries while allowing situation-specific wording and steps.
  • Clarified that exact wording and commands belong in adapters for external systems, linked to the principles they support.
  • Updated contributor guidance to read the plugin-system design principles before writing, revising, or reviewing equipment.

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: ASSERTIVE
• Plan: Team
• Run ID: b8d02b31-7c34-45e1-b717-6b3b9c16ec73

📥 Commits

Reviewing files that changed from the base of the PR and between 3600e66 and af5a740.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Team
• Run ID: 62856c1c-132c-4b62-b505-c003b458aa85

📥 Commits

Reviewing files that changed from the base of the PR and between fc50152 and 3600e66.

📒 Files selected for processing: 2

• AGENTS.md
• docs/plugin-system/design-principles.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• nisavid/ci (manual)

Included review availability: This review used your included allowance. 1 included review remains after this review. Your included PR review attempts over the past 7 days set your current allowance at 4 reviews per hour.

📝 Walkthrough

The design principles document adds guidance for stating equipment intent, principles, and boundaries while leaving situation-specific wording and steps to agents. AGENTS.md directs agents to read the document’s core maxim before working on equipment.

Changes: Equipment guidance

Layer / File(s)	Summary
Principles and agent instruction docs/plugin-system/design-principles.md, AGENTS.md	The design principles document distinguishes adaptable principles from exact prescriptions. It limits exact prescriptions to cases where an external system matches them and identifies them as adapters tied to a principle. AGENTS.md directs agents to read the core maxim before writing, revising, or reviewing equipment.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~4 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 3600e

No actionable merge risk remains in this documentation-only change.

Architecture risk: 🔵 Low · up to 3600e

The change affects 2 systems.

Changed systems: AGENTS.md, docs

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — AGENTS.md (service) was modified; 1 changed file maps to changed impact.
• observed — docs (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in AGENTS.md: Adds an instruction to read the core maxim in docs/plugin-system/design-principles.md before writing, revising, or reviewing equipment.
• observed — Modified behavior in docs/plugin-system/design-principles.md: Adds guidance to equip agents with adaptable principles rather than prescribed command shapes. It distinguishes principle-first rules, which leave implementation to the agent within stated boundaries, from shape-first rules, which prescribe wording or commands. Exact prescriptions are limited to cases where an external system matches them, and are labeled as adapters tied to the underlying principle.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main documentation change: opening the design principles with the core maxim.
Description check		The description is complete and aligned with the repository template. It explains the change, boundary, provenance, validation results, remaining work, and review checklist status.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches: 💡 1

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{A rabbit reads the guiding page,
Then sets the tools for every stage.
Principles show the path ahead,
While exact commands stay narrowly spread.
Hop by hop, the work takes shape,
With room to think and room to adapt.}

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[greptile-apps]

Confidence Score: 5/5

[Low impact] This documentation-only change appears safe to merge.

Summary

Adds the core maxim to docs/plugin-system/design-principles.md and directs equipment authors and reviewers to it from AGENTS.md.

• Equipment rules guide agents by principles, with narrow exceptions for fixed wording.

_{Reviews (1) · Last reviewed commit: "docs(plugin-system): extend adapter mark..." · Reviewed by Greptile}

[linear-code]

IDV-2139