@esotech/contextuate 2.1.0 → 2.1.2

package/dist/templates/templates/standards/php.standards.md

@@ -1,181 +0,0 @@
-# PHP Coding Standards
-
-> **Language:** PHP
-> **Generated:** {DATE}
-
----
-
-## Formatting
-
-### Indentation
-- **Style:** {tabs|spaces}
-- **Size:** {2|4} {spaces|tabs}
-
-### Braces
-- **Classes/Functions:** {same-line|next-line}
-- **Control structures:** {same-line|next-line}
-
-### Spacing
-- **Inside parentheses:** {yes|no} - `function( $param )` vs `function($param)`
-- **After keywords:** {yes|no} - `if ( $x )` vs `if($x)`
-- **Array brackets:** {no-spaces} - `$arr['key']`
-
----
-
-## Naming Conventions
-
-### Classes
-- **Style:** PascalCase
-- **Example:** `UserService`, `PaymentController`
-
-### Methods
-- **Style:** camelCase
-- **Example:** `getUserById()`, `processPayment()`
-
-### Variables
-- **Style:** {camelCase|snake_case}
-- **Example:** `$userName` or `$user_name`
-
-### Constants
-- **Style:** UPPER_SNAKE_CASE
-- **Example:** `MAX_RETRY_COUNT`, `API_VERSION`
-
-### Properties
-- **Style:** {camelCase|snake_case}
-- **Visibility prefix:** {none|underscore for private}
-
----
-
-## Structure
-
-### File Organization
-```php
-<?php
-// 1. Strict types declaration (if used)
-declare( strict_types=1 );
-
-// 2. Namespace
-namespace App\Services;
-
-// 3. Use statements (alphabetized)
-use App\Models\User;
-use Exception;
-
-// 4. Class definition
-class UserService {
-    // 5. Constants
-    // 6. Properties
-    // 7. Constructor
-    // 8. Public methods
-    // 9. Protected methods
-    // 10. Private methods
-}
-```
-
-### Method Length
-- **Guideline:** {max lines per method}
-- **Complexity:** {max cyclomatic complexity}
-
----
-
-## Type Hints
-
-### Parameters
-```php
-// {Required|Optional}
-public function process( string $name, int $count ): void
-```
-
-### Return Types
-```php
-// {Required|Optional}
-public function getData(): array
-```
-
-### Property Types (PHP 7.4+)
-```php
-// {Required|Optional}
-private string $name;
-private User|null $user = null;
-```
-
----
-
-## Documentation
-
-### Class DocBlocks
-```php
-/**
- * {Required|Optional}
- * Brief description of the class.
- */
-class MyClass
-```
-
-### Method DocBlocks
-```php
-/**
- * {Required|Optional|Only for complex methods}
- *
- * @param string $name Description
- * @return array Description
- * @throws Exception When condition
- */
-```
-
----
-
-## Error Handling
-
-### Exceptions
-- **Custom exceptions:** {yes|no}
-- **Base exception class:** {name if applicable}
-
-### Try/Catch
-```php
-try {
-    // code
-} catch( SpecificException $e ){
-    // handle
-} catch( Exception $e ){
-    // fallback
-}
-```
-
----
-
-## Common Patterns
-
-### Dependency Injection
-```php
-// {Constructor injection|Setter injection|Container}
-public function __construct( private UserRepository $repo )
-```
-
-### Null Handling
-```php
-// Preferred: {null coalescing|ternary|early return}
-$value = $data['key'] ?? 'default';
-```
-
----
-
-## Anti-Patterns
-
-```php
-// BAD: {description}
-{bad example}
-
-// GOOD: {description}
-{good example}
-```
-
----
-
-## Framework-Specific
-
-{Add any framework-specific conventions here}
-
----
-
-*This file should be customized for your project. Replace placeholders with actual values.*

package/dist/templates/templates/standards/python.standards.md

@@ -1,175 +0,0 @@
-# Python Coding Standards
-
-> **Language:** Python
-> **Generated:** {DATE}
-
----
-
-## Formatting
-
-### Indentation
-- **Style:** {spaces}
-- **Size:** {4} {spaces}
-
-### Line Length
-- **Max Length:** {88|100|120} chars
-- **Docstrings:** {72} chars
-
-### Imports
-- **Sort Order:** {Standard Library} > {Third Party} > {Local Application}
-- **Style:** {Absolute imports preferred}
-
----
-
-## Naming Conventions
-
-### Classes
-- **Style:** PascalCase
-- **Example:** `UserContext`, `PaymentProcessor`
-
-### Functions/Methods
-- **Style:** snake_case
-- **Example:** `get_user_by_id()`, `process_payment()`
-
-### Variables
-- **Style:** snake_case
-- **Example:** `user_name`, `is_active`
-
-### Constants
-- **Style:** UPPER_SNAKE_CASE
-- **Example:** `MAX_RETRY_COUNT`, `API_VERSION`
-
-### Private Members
-- **Style:** {underscore prefix}
-- **Example:** `_private_method()`, `_internal_var`
-
----
-
-## Structure
-
-### File Organization
-```python
-# 1. Shebang (if executable)
-#!/usr/bin/env python3
-
-# 2. Module Docstring
-"""
-Module description.
-"""
-
-# 3. Imports
-import os
-from typing import List, Optional
-
-# 4. Constants
-MAX_RETRIES = 3
-
-# 5. Classes
-class MyClass:
-    """Class docstring."""
-
-    def __init__(self):
-        pass
-
-# 6. Main execution
-if __name__ == "__main__":
-    pass
-```
-
----
-
-## Type Hints (PEP 484)
-
-### Parameters & Returns
-```python
-# {Required|Preferred}
-def process(name: str, count: int = 0) -> None:
-    pass
-```
-
-### Variables (PEP 526)
-```python
-# {Optional|Preferred}
-user_id: int = 123
-```
-
----
-
-## Documentation (Docstrings)
-
-### Style
-- **Format:** {Google|NumPy|Sphinx/reST}
-
-#### Google Style Example
-```python
-def fetch_data(url: str) -> dict:
-    """Fetches data from the API.
-
-    Args:
-        url: The endpoint URL.
-
-    Returns:
-        A dictionary containing the response data.
-
-    Raises:
-        ConnectionError: If the request fails.
-    """
-```
-
----
-
-## Error Handling
-
-### Exceptions
-```python
-try:
-    process_data()
-except ValueError as e:
-    logger.error(f"Validation error: {e}")
-except Exception:
-    # Catch-all only if necessary
-    raise
-```
-
----
-
-## Common Patterns
-
-### List Comprehensions
-```python
-# Preferred for simple transformations
-names = [u.name for u in users if u.is_active]
-```
-
-### Context Managers
-```python
-# Preferred for resource management
-with open("file.txt") as f:
-    content = f.read()
-```
-
----
-
-## Anti-Patterns
-
-```python
-# BAD: Mutable default arguments
-def add_item(item, list=[]):
-    list.append(item)
-
-# GOOD:
-def add_item(item, list=None):
-    if list is None:
-        list = []
-    list.append(item)
-```
-
----
-
-## Framework-Specific
-
-{Add Django/Flask/FastAPI specific conventions here}
-
----
-
-*This file should be customized for your project. Replace placeholders with actual values.*

package/dist/templates/tools/agent-creator.tool.md

@@ -1,252 +0,0 @@
-# Agent Creator Tool
-
-> **Type:** AI Tool Guide
-> **Purpose:** Create new AI agent definitions following Contextuate standards
-
----
-
-## When to Use This Tool
-
-Use this tool when:
-- User requests a new agent for a specific domain
-- Project needs specialized AI expertise documented
-- Onboarding AI to a new area of the codebase
-
----
-
-## Input
-
-**Required:**
-- Domain/expertise area for the agent
-- Primary responsibilities
-
-**Optional:**
-- Existing documentation to reference
-- Specific file patterns the agent covers
-- Related agents for delegation
-
----
-
-## Process
-
-### Step 1: Determine Agent Scope
-
-Answer these questions:
-- What domain/expertise does this agent cover?
-- What files/patterns are in scope?
-- Is there existing documentation to reference?
-- Does a quickref need to be created first?
-
-### Step 2: Create Supporting Documentation (if needed)
-
-Before creating the agent, ensure documentation exists:
-
-| Need | Create |
-|------|--------|
-| Comprehensive docs | `docs/{topic}.md` |
-| API/method reference | `docs/ai/quickrefs/{name}.quickref.md` |
-
-Use the [Quickref Generator](quickref.tool.md) if needed.
-
-### Step 3: Create Agent File
-
-**Location:** `docs/ai/agents/{domain}-expert.md`
-
-**Naming conventions:**
-- Use lowercase, hyphen-separated
-- Be specific: `api-auth-expert` not just `api-expert`
-- Pattern: `{domain}-expert.md`
-
-### Step 4: Fill Template
-
-Use the template below, replacing all `{placeholders}`.
-
-### Step 5: Quality Check
-
-Verify:
-- [ ] Inherits from base configuration
-- [ ] Required context lists only domain-specific docs
-- [ ] Core competencies are specific and actionable
-- [ ] Includes practical code examples
-- [ ] Anti-patterns show real mistakes to avoid
-- [ ] Decision framework helps with common choices
-
----
-
-## Output Template
-
-```markdown
-# {Name} Expert Agent
-
-> **Inherits:** [Base Agent Configuration](../.contextuate/agents/base.md)
-> **Role:** {One-line description of expertise}
-> **Domain:** `{file patterns covered}`
-
----
-
-## Agent Identity
-
-You are an expert in {domain description}. Your role is to:
-
-1. **{Primary responsibility}**
-2. **{Secondary responsibility}**
-3. **{Tertiary responsibility}**
-
----
-
-## Required Context
-
-In addition to base agent context, you MUST read:
-
-1. **[{Primary Doc}]({path})** - {Why needed}
-2. **[{Secondary Doc}]({path})** - {Why needed} *(if applicable)*
-
----
-
-## Core Competencies
-
-### {Competency Area 1}
-- {Specific skill}
-- {Specific skill}
-
-### {Competency Area 2}
-- {Specific skill}
-- {Specific skill}
-
----
-
-## Decision Framework
-
-### {Key Decision Type}
-
-{Decision tree or guidelines}
-
----
-
-## Common Patterns
-
-### {Pattern Name}
-
-\`\`\`{language}
-{code example}
-\`\`\`
-
----
-
-## Anti-Patterns
-
-\`\`\`{language}
-// BAD: {description}
-{bad pattern}
-
-// GOOD: {description}
-{good pattern}
-\`\`\`
-
----
-
-## Quick Reference
-
-| Task | Approach |
-|------|----------|
-| {common task} | {solution/method} |
-| {common task} | {solution/method} |
-```
-
----
-
-## Example
-
-**Request:** "Create an agent for database operations"
-
-### Step 1: Assess Scope
-- Domain: Database queries and schema management
-- Files: `*.sql`, `migrations/`, database service files
-- Existing docs: Check `docs/` for database documentation
-
-### Step 2: Create Supporting Docs (if needed)
-```
-docs/
-└── database.md              # If comprehensive docs needed
-docs/ai/quickrefs/
-└── database.quickref.md     # If large API needs summary
-```
-
-### Step 3: Create Agent File
-
-File: `docs/ai/agents/database-expert.md`
-
-```markdown
-# Database Expert Agent
-
-> **Inherits:** [Base Agent Configuration](../.contextuate/agents/base.md)
-> **Role:** Expert in database operations, queries, and schema design
-> **Domain:** `*.sql`, `migrations/`, `**/db/**`
-
-## Agent Identity
-
-You are an expert in database operations. Your role is to:
-
-1. **Write efficient queries** following project conventions
-2. **Design schemas** that are normalized and performant
-3. **Create migrations** that are safe and reversible
-
-## Required Context
-
-1. **[Database Documentation](../../database.md)** - Schema and conventions
-2. **[Database Quickref](../quickrefs/database.quickref.md)** - API reference
-```
-
----
-
-## Agent Relationships
-
-### Inheritance Hierarchy
-```
-base.md (framework - immutable)
-    └── {user-agents}.md (project-specific - in docs/ai/agents/)
-```
-
-### Delegation Pattern
-Agents should delegate when task requires expertise outside their domain:
-
-```markdown
-## Delegation
-
-| Situation | Delegate To |
-|-----------|-------------|
-| Need API design help | api-expert |
-| Need testing help | testing-expert |
-```
-
----
-
-## When to Create Quickrefs
-
-Create a quickref (`docs/ai/quickrefs/{name}.quickref.md`) when:
-- Source documentation exceeds ~300 lines
-- Methods/APIs are frequently looked up
-- Agent needs awareness without full context load
-
----
-
-## Reporting
-
-After creating an agent, report:
-
-1. Agent file created
-2. Supporting docs created (if any)
-3. Recommended next steps
-
-```
-Agent Created
-=============
-File: docs/ai/agents/database-expert.md
-
-Supporting docs:
-  - Created: docs/ai/quickrefs/database.quickref.md
-
-Next steps:
-  - Review and customize the agent file
-  - Add project-specific patterns and anti-patterns
-```