@esotech/contextuate 2.1.0 → 2.1.1

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
-```

package/dist/templates/tools/quickref.tool.md

@@ -1,216 +0,0 @@
-# Quickref Generation Tool
-
-> **Type:** AI Tool Guide
-> **Purpose:** Instructions for generating AI-friendly quick references from documentation
-
----
-
-## When to Use This Tool
-
-Use this tool when:
-- Full documentation exceeds ~200 lines
-- A condensed reference would help AI assistants
-- Methods/APIs are frequently looked up
-- User requests a quickref be generated
-
----
-
-## Input
-
-**Required:** Path to source documentation file
-
-**Example request:**
-> "Generate a quickref for docs/classes/user-service.md"
-
----
-
-## Process
-
-### Step 1: Read the Source Documentation
-
-Read the full documentation file to understand:
-- What the class/service/API does
-- All public methods and their signatures
-- Properties and their types
-- Common usage patterns
-
-### Step 2: Extract Key Information
-
-For each **method**, capture:
-- Method name
-- Full parameter signature with types
-- One-line description (max 10 words)
-
-For each **property**, capture:
-- Property name
-- Type
-- One-line description
-
-For **common usage**, capture:
-- The single most common usage pattern
-- Keep it to 3-5 lines of code max
-
-### Step 3: Organize by Category
-
-Group methods logically:
-- By functionality (CRUD, validation, transformation)
-- By access pattern (getters, setters, actions)
-- By frequency of use (common first)
-
-### Step 4: Generate Quickref
-
-Write to `docs/ai/quickrefs/{name}.quickref.md` using the template below.
-
----
-
-## Output Template
-
-```markdown
-# {Name} - Quick Reference
-
-> **Source:** [{source-filename}](../../{path-to-source})
-> **Generated:** {YYYY-MM-DD}
-
----
-
-## Methods
-
-### {Category 1}
-
-| Method | Description |
-|--------|-------------|
-| `methodName( param: type )` | Brief description |
-| `methodName( a: type, b: type ): returnType` | Brief description |
-
-### {Category 2}
-
-| Method | Description |
-|--------|-------------|
-| `methodName( param: type )` | Brief description |
-
----
-
-## Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `propertyName` | type | Brief description |
-
----
-
-## Common Usage
-
-\`\`\`{language}
-// Most common pattern - keep brief
-\`\`\`
-
----
-
-*See [full documentation](../../{path-to-source}) for details.*
-```
-
----
-
-## Guidelines
-
-### Keep It Scannable
-- One line per method/property
-- No verbose explanations
-- Tables for structured data
-- Max 100 lines total
-
-### Method Signatures
-- Include all parameters with types
-- Include return type if not void
-- Use consistent formatting:
-  ```
-  methodName( param1: type, param2: type ): returnType
-  ```
-
-### Descriptions
-- Max 10 words per description
-- Start with verb: "Gets...", "Sets...", "Returns...", "Creates..."
-- No periods at end
-
-### Categories
-- 2-5 categories typically
-- Use clear, short category names
-- Most-used methods first
-
-### Common Usage
-- Single most common pattern
-- 3-5 lines of code max
-- Must be copy-paste ready
-
----
-
-## Example
-
-**Source:** `docs/classes/cache-service.md` (300 lines)
-
-**Generated quickref:**
-
-```markdown
-# Cache Service - Quick Reference
-
-> **Source:** [cache-service.class.md](../../classes/cache-service.class.md)
-> **Generated:** 2024-01-15
-
----
-
-## Methods
-
-### Core Operations
-
-| Method | Description |
-|--------|-------------|
-| `get( key: string ): mixed` | Gets cached value by key |
-| `set( key: string, value: mixed, ttl?: int )` | Sets value with optional TTL |
-| `delete( key: string ): bool` | Removes key from cache |
-| `has( key: string ): bool` | Checks if key exists |
-| `clear()` | Removes all cached values |
-
-### Batch Operations
-
-| Method | Description |
-|--------|-------------|
-| `getMultiple( keys: array ): array` | Gets multiple values at once |
-| `setMultiple( items: array, ttl?: int )` | Sets multiple values |
-| `deleteMultiple( keys: array ): bool` | Removes multiple keys |
-
----
-
-## Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `defaultTtl` | int | Default time-to-live in seconds |
-| `prefix` | string | Key prefix for namespacing |
-
----
-
-## Common Usage
-
-\`\`\`php
-$value = $cache->get( 'user:123' );
-if( !$value ){
-    $value = $this->loadUser( 123 );
-    $cache->set( 'user:123', $value, 3600 );
-}
-\`\`\`
-
----
-
-*See [full documentation](../../classes/cache-service.class.md) for details.*
-```
-
----
-
-## Naming Convention
-
-- **File:** `{source-name}.quickref.md`
-- **Location:** `docs/ai/quickrefs/`
-
-Examples:
-- `docs/classes/user-service.md` → `docs/ai/quickrefs/user-service.quickref.md`
-- `docs/api/auth-endpoints.md` → `docs/ai/quickrefs/auth-endpoints.quickref.md`

package/dist/templates/tools/spawn.tool.md

@@ -1,31 +0,0 @@
-# Tool: spawn_agent
-
-> **Status:** EXPERIMENTAL
-
-The `spawn_agent` tool allows you to launch a specialized sub-agent to perform a specific task in an isolated context.
-
-## Usage
-
-Use this tool when you need to:
-1.  Perform a risky operation that should be sandboxed (e.g. "Refactor auth module").
-2.  Delegate a large task to a specialized persona (e.g. "Ask documentation-expert to write docs").
-
-## Arguments
-
-| Argument     | Type     | Description                                                            |
-| :----------- | :------- | :--------------------------------------------------------------------- |
-| `agent_name` | `string` | The name of the agent to spawn (must exist in `docs/ai/agents/`).      |
-| `goal`       | `string` | Specific instructions for what the agent should achieve.               |
-| `isolation`  | `string` | Isolation mode `worktree` (recommended) or `none`. Default `worktree`. |
-
-## Example
-
-```bash
-contextuate run coder-agent --goal "Fix the bug in login.ts" --isolation=worktree
-```
-
-## Behavior
-
-1.  **Isolation:** The agent creates a new git worktree (branch).
-2.  **Execution:** The agent runs independently in that directory.
-3.  **Result:** The agent commits changes to its branch. You must then merge or review these changes.