pact / rules
AGENTS.md0 starsChanged 7 months agoApache-2.0View on GitHub
When working with Kailash frameworks, MUST consult the relevant specialist: Applies when: Creating workflows, modifying DB models, setting up endpoints, building agents, implementing governance, training ML models, fine-tuning LLMs, configuring MCP platform server. Why: Framework specialists encode hard-won patterns and constraints that generalist agents miss, leading to subtle misuse of DataFlow, Nexus, or Kaizen APIs. Applies when: Feature spans multiple files, unclear requirements, multiple valid approaches. When multiple independent operations are needed, launch agents in parallel using Task tool, wait…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,542 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository37 other files it gives its agents.
- .claude/guides/claude-code/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- core-sdkSkill
- dataflowSkill
- nexusSkill
- kaizenSkill
- kailash-mcpSkill
- cheatsheetsSkill
- development-guidesSkill
- nodes-referenceSkill
- workflow-patternsSkill
- deployment-gitSkill
- frontend-integrationSkill
- testing-strategiesSkill
- architecture-decisionsSkill
- code-templatesSkill
- enterprise-infrastructureSkill
- validation-patternsSkill
- gold-standardsSkill
- security-patternsSkill
- flutter-patternsSkill
- interactive-widgetsSkill
- enterprise-ai-uxSkill
- conversation-uxSkill
- uiux-design-principlesSkill
- value-auditSkill
- ai-interaction-patternsSkill
- eatp-referenceSkill
- coc-referenceSkill
- 29-pactSkill
- claude-code-patternsSkill
- error-troubleshootingSkill
- kailash-mlSkill
- kailash-alignSkill
- co-referenceSkill
- managementSkill
- projectSkill
The file
We split this agents.md into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
When working with Kailash frameworks, MUST consult the relevant specialist:
- Distinctive: line 31
When multiple independent operations are needed, launch agents in parallel using Task tool, wait for all, aggregate results.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Orchestration Rules
Specialist Delegation (MUST)
When working with Kailash frameworks, MUST consult the relevant specialist:
- dataflow-specialist: Database or DataFlow work
- nexus-specialist: API or deployment work
- kaizen-specialist: AI agent work
- mcp-specialist: MCP integration work
- mcp-platform-specialist: FastMCP platform server, contributor plugins, security tiers
- pact-specialist: Organizational governance work
- ml-specialist: ML lifecycle, feature stores, training, drift monitoring, AutoML
- align-specialist: LLM fine-tuning, LoRA adapters, alignment methods, model serving
Applies when: Creating workflows, modifying DB models, setting up endpoints, building agents, implementing governance, training ML models, fine-tuning LLMs, configuring MCP platform server.
Why: Framework specialists encode hard-won patterns and constraints that generalist agents miss, leading to subtle misuse of DataFlow, Nexus, or Kaizen APIs.
Analysis Chain (Complex Features)
- analyst → Identify failure points
- analyst → Break down requirements
decide-frameworkskill → Choose approach- Then appropriate specialist
Applies when: Feature spans multiple files, unclear requirements, multiple valid approaches.
Parallel Execution
When multiple independent operations are needed, launch agents in parallel using Task tool, wait for all, aggregate results. MUST NOT run sequentially when parallel is possible.
Why: Sequential execution of independent operations wastes the autonomous execution multiplier, turning a 1-session task into a multi-session bottleneck.
Quality Gates (MUST — Gate-Level Review)
Reviews happen at COC phase boundaries, not per-edit. Skip only when explicitly told to.
Why: Skipping gate reviews lets analysis gaps, security holes, and naming violations propagate to downstream repos where they are far more expensive to fix.
| Gate | After Phase | Review |
| Analysis complete | /analyze | reviewer: Are findings complete? Gaps? |
| Plan approved | /todos | reviewer: Does plan cover requirements? |
| Implementation done | /implement | reviewer: Code review all changes. security-reviewer: Security audit. |
| Validation passed | /redteam | reviewer: Are red team findings addressed? |
| Knowledge captured | /codify | gold-standards-validator: Naming, licensing compliance. |
Zero-Tolerance
Pre-existing failures MUST be fixed (see rules/zero-tolerance.md Rule 1). No workarounds for SDK bugs — deep dive and fix directly (Rule 4).
Why: Workarounds create parallel implementations that diverge from the SDK, doubling maintenance cost and masking the root bug from being fixed (see rules/zero-tolerance.md Rule 4).
MUST NOT
- Framework work without specialist
Why: Framework misuse without specialist review produces code that looks correct but violates invariants (e.g., pool sharing, session lifecycle, trust boundaries).
- Sequential when parallel is possible
Why: See Parallel Execution above — same rule, expressed as MUST NOT.
- Raw SQL when DataFlow exists
Why: Raw SQL bypasses DataFlow's access controls, audit logging, and dialect portability, creating ungoverned database access.
- Custom API when Nexus exists
Why: Custom API endpoints miss Nexus's built-in session management, rate limiting, and multi-channel deployment, requiring manual reimplementation.
- Custom agents when Kaizen exists
Why: Custom agent implementations bypass Kaizen's signature validation, tool safety, and structured reasoning, producing fragile agents.
- Custom governance when PACT exists
Why: Custom governance lacks PACT's D/T/R accountability grammar and verification gradient, making audit compliance unverifiable.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.