Pattern5

Pattern5: Organizational Governance for AI Agents

Query the organization's Pattern5 library before making architectural decisions. The library contains four artifact types that serve different purposes:

• Standards are prescriptive rules. They define what MUST, SHOULD, or MAY be done. Compliance is expected.
• Patterns are reusable solutions. They provide structure, constraints, and anti-patterns for recurring problems. Adoption is recommended.
• Decisions are architectural decision records. They capture why a choice was made, what alternatives were considered, and the consequences. They inform future choices.
• Principles are hierarchical decision-making guidelines. They encode trade-off logic as algorithmic IF/THEN expressions that agents can evaluate. They sit above other artifact types as the most abstract form of governance.

Treat Pattern5 as the organization's source of truth for how code should be written, structured, and evolved. The workflow is: search for existing guidance, apply what is found (differentiating by type), and report gaps when no guidance exists.

Step 1: Search Before Building

Before writing implementation code for a feature, component, or architectural change, search Pattern5 for existing guidance. This is the most important step -- it prevents violations of organizational standards and avoids duplicating solved problems.

When Starting a New Task

Call pattern5_search with a query that names the technology and concern (e.g., "server action error handling", "database migration workflow"). For effective query strategies, consult references/query-strategies.md. To scope results to a specific collection, pass the optional collection parameter (e.g., pattern5_search({ query: "error handling", collection: "React Frontend Standards" })). Omit collection for workspace-wide results.

When pattern5_search returns results, scan the titles and descriptions to identify the most relevant match. Call pattern5_get on that artifact to retrieve the full content before writing code. Search results only contain titles and summaries -- the full artifact includes implementation details, code examples, constraints, and verification checklists.

If search returns multiple artifacts that look relevant, retrieve the top two or three. They often serve complementary roles -- one may be a standard (what must be done) while another is a pattern (how to do it) or a decision (why it was done this way).

If search returns no results, try alternative terms or synonyms before concluding there is no guidance. Then try pattern5_list to browse all available artifacts. A genuine gap should be reported (see Step 3).

When Onboarding to a Project

Call pattern5_list to see what artifacts are available. This provides a quick overview of the organization's standards and conventions for the project's technology stack. Filter by type (pattern, standard, decision, or principle) to narrow results.

When Exploring What Exists

Call pattern5_list to browse all available artifacts. Filter by type to narrow results. This is useful when beginning work in an unfamiliar area of the codebase. Follow up with pattern5_search using specific keywords to find artifacts relevant to the current task.

Step 2: Apply What Is Found

Differentiate how artifacts are applied based on their type.

Applying Standards

Standards are the highest-priority artifacts. They represent organizational rules that code must comply with.

Each standard has an enforcement level that determines compliance expectations:

• must -- Mandatory. Violation requires explicit justification and approval. Flag any deviation to the user.
• should -- Expected. Deviation is acceptable with documented reasoning. Note the deviation and explain why.
• may -- Optional. Follow when it adds value to the current context.

When a standard applies to the current task, read these sections in order:

1. rule -- The prescriptive requirement. Understand what is mandated or prohibited.
2. scope -- What the standard governs. Confirm the current task falls within scope.
3. compliant_examples -- Code that follows the rule. Model implementation after these examples.
4. non_compliant_examples -- Code that violates the rule. Ensure the implementation avoids these patterns.
5. exceptions (if present) -- Approved cases where the rule can be broken. Check whether the current context qualifies before deviating.

If the task involves code that falls within a standard's scope, write code that matches the compliant examples. When compliance is not possible, inform the user and explain the conflict.

Applying Patterns

Patterns provide recommended approaches, not mandates. They describe reusable solutions to recurring problems.

Read the pattern's sections in this order:

1. apply_when -- Conditions that indicate this pattern fits. Confirm the current situation matches.
2. do_not_apply_when -- Conditions that rule out the pattern. If any match, do not apply it.
3. structure -- The implementation shape. Follow this as the architectural blueprint.
4. key_constraints -- Hard rules within the pattern. These must be respected when applying the pattern.
5. anti_patterns -- Common mistakes. Actively avoid these during implementation.
6. verification -- A checklist of assertions. Walk through each item after implementation to confirm correct application.

Patterns are guidance, not law. Adapt the structure to fit the specific context. If the pattern does not quite fit, note the adaptation and reasoning.

Applying Decisions

Decisions record architectural choices already made. They are not instructions to follow but context to respect.

Check the decision_status field before acting on a decision:

• active -- The decision is current. Follow it. Do not re-litigate settled choices without new information.
• superseded -- A newer decision replaced this one. Find and follow the replacement.
• deprecated -- The decision is no longer recommended. Proceed with caution and consider proposing a new decision.

Read the decision's sections to understand the full context:

1. context -- The circumstances that drove the decision. Understand the constraints that were in play.
2. decision_outcome -- What was chosen. This is the choice to follow (if active).
3. rationale -- Why this choice was made. This explains the reasoning and trade-offs.
4. alternatives_considered (if present) -- Options that were evaluated and rejected. Avoid re-proposing these unless circumstances have materially changed.
5. consequences -- Positive and negative impacts. Anticipate these trade-offs in the current work.

If proposing a different approach than an active decision, reference the existing decision explicitly and explain what has changed to warrant revisiting it.

Applying Principles

Principles encode trade-off logic that guides decisions across the organization. They are hierarchical: a parent principle can have sub-principles that refine it, up to three levels deep.

Priority and Conflict Resolution

Each principle has an optional priority from 1 (lowest) to 10 (highest). When two principles apply to the same situation:

1. Higher priority wins. A priority-8 principle overrides a priority-5 principle on the same topic.
2. Specificity breaks ties. Prefer a sub-principle over its general parent when both match the current context.
3. Check conflict notes. Many principles include a conflict_notes section that explicitly addresses overlap with other principles. Read this before applying competing principles.

Reading a Principle

Read the principle's sections in this order:

1. rationale -- Why this principle exists. Understand the reasoning and trade-offs that motivated it.
2. algorithmic_expression -- The actionable logic. This uses IF/THEN/ELSE/UNLESS keywords to express when and how the principle applies. Evaluate the conditions against the current task.
3. examples -- Concrete illustrations of the principle in action. These show both correct and incorrect applications.
4. conflict_notes (if present) -- Guidance on what to do when this principle conflicts with another.

When to Query for Principles

Search for principles when:

• Competing concerns arise -- e.g., performance vs. maintainability, speed vs. safety, flexibility vs. consistency.
• No standard or pattern exists -- Principles provide higher-level guidance when specific rules have not been written yet.
• Technology trade-offs need resolution -- e.g., choosing between approaches where both have valid merits.
• A decision requires justification -- Principles supply the reasoning framework that decisions can reference.

Example Workflow

1. The agent searches for guidance on infrastructure provisioning and receives a principle titled "Prefer Managed Services Over Self-Hosted."
2. The principle's algorithmic_expression contains:

   IF deploying a new service
     IF a managed equivalent exists with acceptable cost
       THEN use the managed service
       UNLESS regulatory constraints require on-premises hosting
     ELSE
       DOCUMENT why self-hosting is necessary
   

3. The agent evaluates the conditions: a managed equivalent exists, cost is within budget, no regulatory constraints apply.
4. The agent proceeds with the managed service and cites the principle in the decision rationale.

Rating Artifacts

After applying an artifact, call pattern5_rate with a rating from 1 to 5 and an optional comment. This feedback improves artifact quality and recommendation accuracy.

Step 3: Report Gaps

When no relevant artifact exists for a decision or approach being taken, create an artifact to capture the knowledge for future reference.

Creating Artifacts

Call pattern5_submit with the appropriate type and all required sections:

• Reusable solution to a recurring problem -- type: "pattern" with sections: apply_when, do_not_apply_when, structure, key_constraints, anti_patterns, verification. Include a description summary and a clear title naming the solution. The structure section must be a Mermaid diagram in a ```mermaid code fence.
• Prescriptive rule or guideline -- type: "standard" with sections: rule, scope, compliant_examples, non_compliant_examples, exceptions. Include concrete code snippets in the example sections. Set enforcement_level to must, should, or may.
• Architectural choice with rationale -- type: "decision" with sections: context, decision_outcome, rationale, alternatives_considered, consequences. The description should summarize what was chosen.
• Trade-off guideline or guiding belief -- type: "principle" with sections: rationale, algorithmic_expression, examples, conflict_notes. The algorithmic_expression should use IF/THEN/ELSE/UNLESS keywords with one rule per line. Optionally include parent_id (to create a sub-principle) and priority (1-10, where 10 is highest).

All sections listed above are required for each type. Provide technology tags to improve discoverability. Set the layer field (presentation, application, data, or infrastructure) when the artifact targets a specific architectural layer.

Write content as if another developer -- or another AI agent -- will read it months from now. Clear titles, specific descriptions, and concrete examples make artifacts useful beyond the current session.

Assigning Artifacts to Collections

Call pattern5_collections with action='add' to add existing artifacts to a collection, or action='remove' to remove them. Collections organize artifacts for different teams, projects, or domains. Use pattern5_list with show="collections" to discover available collections. Collection names are case-insensitive. To create new collections, use the Pattern5 web interface.

When creating an artifact with pattern5_submit, pass the optional collection parameter to assign it to a specific collection at creation time (e.g., pattern5_submit({ ..., collection: "Frontend Standards" })). This overrides any default collection linked to the API key.

Managing Artifacts

Use pattern5_update to modify an artifact's title, description, sections, technologies, or layer. Call pattern5_manage with action='dismiss' to soft-delete an artifact that is no longer needed.

When NOT to Query Pattern5

Not every task requires organizational governance. Do not search Pattern5 for:

• Syntax or language questions -- General programming knowledge does not belong in an organizational library. Questions like "How does async/await work?" or "What does the spread operator do?" are answered by training data.
• Debugging runtime errors -- Error messages, stack traces, and breakpoints are task-specific. Fixing a TypeError on line 42 does not require a governance check.
• Third-party library documentation -- Use the library's own docs, a documentation tool, or the library's README. Pattern5 stores organizational decisions about which libraries to use, not how to use them.
• General knowledge -- Questions answerable from training data do not need organizational context. Algorithm explanations, language comparisons, and conceptual overviews fall outside Pattern5's scope.
• Unrelated tasks -- If the current task does not involve architecture, implementation approach, or coding standards, skip the query. File renaming, typo fixes, and simple formatting changes do not need governance review.

The trigger is architectural intent: choosing how to build something, not what a language keyword means. When in doubt, ask: "Am I making a design choice that future developers will need to understand or follow?" If yes, search Pattern5 first.

Version Compatibility

This skill is version 1.6.0. The MCP server connects at the workspace level by default. Use the optional collection parameter on pattern5_search and pattern5_list to scope queries to a specific collection. Omit it for cross-cutting governance that spans the entire workspace. Collection names are case-insensitive; an invalid name returns a helpful error.

The MCP server is the authoritative source for tool schemas, parameter names, and response formats. If the server's tool interface differs from these instructions, trust the server. Tool schemas are self-describing and always reflect the current API.

Additional Resources

Reference Files

For guidance on writing effective queries and interpreting results, consult:

• references/query-strategies.md -- Content type selection, search query examples, and result interpretation