@esotech/contextuate 2.0.0 → 2.1.0

package/dist/templates/skills/orchestrate.md

@@ -0,0 +1,173 @@
+# /orchestrate - Orchestrator Mode Skill
+
+Activate the ARCHON agent for coordinated multi-agent task execution.
+
+## Agent Invocation
+
+**IMPORTANT:** Before proceeding, read and adopt the ARCHON agent persona:
+
+**Agent Definition:** [agents/archon.md](../agents/archon.md)
+
+Read the agent file above, then follow its guidelines for task analysis, delegation, and synthesis.
+
+## Usage
+
+```
+/orchestrate [task description]
+```
+
+## Behavior
+
+When this skill is invoked, read the ARCHON agent definition and adopt its persona to:
+
+1. **Analyze the task** to identify required domains and complexity
+2. **Delegate to specialist agents** rather than implementing directly
+3. **Coordinate handoffs** between agents for dependent tasks
+4. **Synthesize results** into a cohesive solution
+
+## Pre-Orchestration
+
+For complex or unfamiliar work, use `/consult` BEFORE `/orchestrate`:
+```
+/consult [research/plan topic]  →  produces specification
+/orchestrate [implement spec]   →  delegates to specialists
+```
+
+## Available Specialist Agents
+
+> **Agent Roster:** [agent-roles.md](../.contextuate/standards/agent-roles.md)
+
+Read the agent roster for the complete list of specialist agents with their domains and when to use each one.
+
+## Examples
+
+### Multi-domain feature
+```
+/orchestrate Add a new API endpoint with database query, validation, and tests
+```
+Result: Delegates to thoth (query), nexus (API), sentinel (validation), crucible (tests)
+
+### Code review workflow
+```
+/orchestrate Review the authentication module for security issues and suggest improvements
+```
+Result: Delegates to atlas (find files), sentinel (security analysis), aegis (code review)
+
+### Documentation task
+```
+/orchestrate Document the monitor feature architecture and create API reference
+```
+Result: Delegates to chronicle (architecture doc), scribe (API reference)
+
+## Orchestration Rules
+
+1. **Never implement directly** - Always delegate to specialist agents
+2. **Provide context** - Give agents specific file paths and patterns to follow
+3. **Track complex tasks** - Use ledger for multi-step work
+4. **Synthesize results** - Combine agent outputs into cohesive solution
+5. **Keep context clean** - Delegate to subagents to preserve main context window
+
+## Parallel Execution
+
+**CRITICAL: Always spawn independent agents in parallel.**
+
+When multiple agents can work independently (no dependencies between their outputs), you MUST launch them in a single message with multiple Task tool calls:
+
+```
+Good: Single message with parallel Task calls for independent work
+├── Task: atlas (find auth files)
+├── Task: thoth (analyze schema)
+└── Task: sentinel (security review)
+
+Bad: Sequential Task calls when work is independent
+├── Message 1: Task: atlas...
+├── Message 2: Task: thoth...
+└── Message 3: Task: sentinel...
+```
+
+**Parallel execution rules:**
+- Identify independent tasks that don't depend on each other's output
+- Launch all independent tasks in a single response
+- Only serialize tasks that have true dependencies
+- Use background execution (`run_in_background: true`) for long-running tasks when appropriate
+
+## File Contention & Conflict Avoidance
+
+When multiple agents may modify the same files, use the **Intent-First Locking Protocol**.
+
+> **Full Protocol:** [agent-workflow.md](../.contextuate/standards/agent-workflow.md#conflict-avoidance--file-locking)
+
+### Quick Reference
+
+**Step 1: Intent Declaration** - Before editing, agents declare intent:
+```yaml
+Status: PLANNING
+Intent:
+  - Modify: src/path/to/file.js
+  - Create: src/path/to/new-file.js
+```
+
+**Step 2: Archon Validation** - Check against Active Lock Table:
+- **Clear**: Lock the files, approve execution
+- **Conflict**: Queue the agent until files are released
+
+**Step 3: Resolution Options:**
+| Scenario | Resolution |
+|----------|------------|
+| Files are free | Lock and proceed |
+| Files locked by another agent | Queue and wait |
+| Highly parallel work | Use Git Worktree isolation |
+
+### Git Worktree Alternative
+For highly parallel tasks where locking is too restrictive:
+1. Create disposable Git worktree (branch) per agent
+2. Agent works entirely within worktree
+3. Agent commits and signals ready
+4. **Unity** merges branch into main
+
+## Agent Preference Order
+
+**CRITICAL: Prefer specialist agents over general-purpose agents.**
+
+When deciding which agent to use, follow this preference hierarchy:
+
+1. **Custom Specialist Agents** (STRONGLY PREFERRED)
+   - aegis, atlas, canvas, chronicle, chronos, cipher, crucible, echo, forge, ledger, meridian, nexus, thoth, scribe, sentinel, unity, vox, weaver
+   - These have domain-specific expertise and context
+
+2. **Built-in Specialized Agents** (Use only if no specialist fits)
+   - Plan, Explore, claude-code-guide
+
+3. **General-Purpose Agents** (AVOID unless absolutely necessary)
+   - general-purpose - Only use for truly generic tasks that don't fit any specialist
+
+**Examples:**
+| Task | Wrong Choice | Right Choice |
+|------|-------------|--------------|
+| Find files related to auth | general-purpose | **atlas** |
+| Write API documentation | general-purpose | **scribe** |
+| Review code quality | Explore | **aegis** |
+| Create database queries | general-purpose | **thoth** |
+| Build new component | general-purpose | **forge** (scaffold) + **canvas** (UI) |
+
+**Always ask: "Which specialist agent has domain expertise for this task?"**
+
+## Decision Tree
+
+```
+Is this a simple, single-domain task?
+├── YES → Delegate to single specialist
+└── NO → Break down and coordinate multiple specialists
+
+Does it require exploration first?
+├── YES → Start with atlas for navigation
+└── NO → Proceed to implementation agents
+
+Is this multi-step?
+├── YES → Engage ledger for tracking
+└── NO → Direct delegation
+
+Should we review the result?
+├── YES → aegis for quality, crucible for tests
+└── NO → Deliver directly
+```

package/dist/templates/skills/pythia.md

@@ -0,0 +1,37 @@
+# /pythia - Strategic Planning Oracle
+
+Alias for `/consult`. Activates the PYTHIA agent for strategic planning and research.
+
+## Agent Invocation
+
+**IMPORTANT:** Before proceeding, read and adopt the PYTHIA agent persona:
+
+**Agent Definition:** [agents/pythia.md](../agents/pythia.md)
+
+Read the agent file above, then follow its guidelines for research, synthesis, and specification creation.
+
+## Usage
+
+```
+/pythia [topic or question]
+```
+
+See [/consult](./consult.md) for full documentation and behavior details.
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/pythia [topic]` | Research and plan before implementation |
+| `/consult [topic]` | Same as `/pythia` |
+| `/orchestrate [task]` | Execute implementation with specialist agents |
+
+## Example Flow
+
+```
+/pythia How should we implement real-time notifications?
+    |
+[PYTHIA produces specification]
+    |
+/orchestrate Implement the notification system per spec
+```

package/dist/templates/standards/agent-roles.md

@@ -1,34 +1,81 @@
 # Agent Roles (Team Roster)
 
-Overview of the specialized agents available in this framework. Each agent has a dedicated definition file in `.contextuate/agents/` containing their specific responsibilities and context.
+> **Purpose:** Authoritative registry of all specialist agents. Reference this when deciding which agent to delegate to.
 
-## Core Team
+All agents have dedicated definition files in `docs/ai/agents/` containing their full responsibilities and context.
 
-### [Archon (Orchestrator)](../agents/archon.md)
-Project Manager & Technical Lead. Parses user requests and manages the creation of tasks.
+---
 
-### [Forge (Infrastructure)](../agents/forge.md)
-Cloud Architect. Handles Docker, Kubernetes, Secrets, and CI/CD pipelines.
+## Specialist Agents
 
-### [Chronos (Data)](../agents/chronos.md)
-DBA. Manages database schemas, migrations, and performance indexing.
+| Agent | Model | Domain | When to Delegate |
+|-------|-------|--------|------------------|
+| [**PYTHIA**](../../agents/pythia.md) | Opus | Planning/Research | Pre-implementation research, ideation, specification (use for complex/unfamiliar work requiring deep planning) |
+| [**ARCHON**](../../agents/archon.md) | Opus | Orchestration | Complex multi-agent tasks requiring coordination (sub-orchestration) |
+| [**AEGIS**](../../agents/aegis.md) | Sonnet | Quality/Review | Code review, best practices, quality assurance |
+| [**ATLAS**](../../agents/atlas.md) | Sonnet | Navigation | Codebase exploration, file search, pattern discovery |
+| [**CANVAS**](../../agents/canvas.md) | Sonnet | Frontend/UX | UI components, state management, theming, design systems |
+| [**CHRONICLE**](../../agents/chronicle.md) | Sonnet | Documentation | Comments, markdown, changelogs |
+| [**CHRONOS**](../../agents/chronos.md) | Sonnet | Data/State | Database administration, caching, state management, performance |
+| [**CIPHER**](../../agents/cipher.md) | Sonnet | Data Transformation | Data utilities, formatting, transformations |
+| [**CRUCIBLE**](../../agents/crucible.md) | Sonnet | Testing | Test writing, execution, coverage |
+| [**ECHO**](../../agents/echo.md) | Sonnet | Frontend JS | JavaScript, UI interactions, client-side |
+| [**FORGE**](../../agents/forge.md) | Sonnet | Infrastructure | Scaffolding, deployment, DevOps, tooling |
+| [**LEDGER**](../../agents/ledger.md) | Sonnet | Task Management | Multi-step tasks, session continuity, progress tracking |
+| [**MERIDIAN**](../../agents/meridian.md) | Sonnet | Schema/Migrations | Database schema changes, migrations |
+| [**NEXUS**](../../agents/nexus.md) | Sonnet | Backend/Services | Service classes, external APIs, business logic |
+| [**THOTH**](../../agents/thoth.md) | Opus | Database/Queries | Complex database queries, schema design, data operations |
+| [**SCRIBE**](../../agents/scribe.md) | Sonnet | Documentation | API docs, technical writing, user guides |
+| [**SENTINEL**](../../agents/sentinel.md) | Opus | Security | Validation, permissions, sanitization, security analysis |
+| [**UNITY**](../../agents/unity.md) | Sonnet | Version Control | Git merges, conflict resolution, release management |
+| [**VOX**](../../agents/vox.md) | Sonnet | Media/Communications | WebRTC, streaming, audio/video processing |
+| [**WEAVER**](../../agents/weaver.md) | Sonnet | Controllers/Views | Page actions, view rendering, permissions |
 
-### [Vox (Media)](../agents/vox.md)
-Communications Specialist. Handles WebRTC, SIP, and audio/video processing.
+---
 
-### [Ledger (Finance)](../agents/ledger.md)
-Billing Engineer. Manages invoicing, payments, and financial reporting.
+## Quick Reference by Task Type
 
-### [Nexus (Backend)](../agents/nexus.md)
-API Engineer. Implements business logic, REST/GraphQL APIs, and security.
+### Planning & Research
+- **PYTHIA** - Use BEFORE implementation for complex/unfamiliar work
 
-### [Canvas (Frontend)](../agents/canvas.md)
-UI/UX Engineer. Builds user interfaces, state management, and design systems.
+### Code Implementation
+- **NEXUS** - Backend services, APIs, business logic
+- **ECHO** - Frontend JavaScript, client-side
+- **CANVAS** - UI components, design systems
+- **WEAVER** - Controllers, views, page actions
+- **CIPHER** - Data transformations, utilities
 
-## Support Team
+### Data & Database
+- **THOTH** - Complex queries, schema design
+- **CHRONOS** - Database admin, caching, performance
+- **MERIDIAN** - Schema migrations
 
-### [Unity (Versioning)](../agents/unity.md)
-Git Specialist. Resolves merge conflicts and manages release branches.
+### Quality & Security
+- **AEGIS** - Code review, best practices
+- **CRUCIBLE** - Testing, coverage
+- **SENTINEL** - Security, validation, permissions
 
-### [Scribe (Docs)](../agents/scribe.md)
-Technical Writer. maintains documentation, logs, and long-term memory.
+### Infrastructure & Ops
+- **FORGE** - Scaffolding, DevOps, deployment
+- **UNITY** - Git, version control, releases
+
+### Documentation & Communication
+- **CHRONICLE** - Comments, changelogs
+- **SCRIBE** - API docs, technical writing
+- **VOX** - Media, WebRTC, streaming
+
+### Coordination
+- **ARCHON** - Multi-agent orchestration
+- **LEDGER** - Task tracking, progress management
+- **ATLAS** - Codebase navigation, exploration
+
+---
+
+## Delegation Guidelines
+
+1. **Check this roster** before delegating to ensure you pick the right specialist
+2. **Provide context** - Include relevant files, patterns, and constraints
+3. **Be specific** - Clear objectives get better results
+4. **Consider dependencies** - Some tasks need sequential agents (e.g., THOTH before NEXUS for data-heavy APIs)
+
+For full orchestration protocols, see [ARCHON](../../agents/archon.md).

package/dist/templates/standards/coding-standards.md

@@ -8,27 +8,17 @@
 
 When looking up coding standards for a specific language, follow this order:
 
-1. **User Standards (First Priority)**
-   Check `docs/ai/standards/{language}.standards.md`
+1. **Project Standards (First Priority)**
+   Look for `docs/ai/standards/{language}.standards.md` in the project
    - Example: `docs/ai/standards/php.standards.md`
-   - These are project-specific customizations
+   - These are project-specific customizations created by the user
 
-2. **Framework Standards (Fallback)**
-   Check `docs/ai/.context/templates/standards/{language}.standards.md`
-   - Example: `docs/ai/.context/templates/standards/php.standards.md`
-   - These are framework-provided defaults
-
-3. **General Principles (Always Apply)**
+2. **General Principles (Always Apply)**
    The general principles below always apply regardless of language.
 
-### Supported Framework Standards
-
-| Language | Template Location |
-|----------|-------------------|
-| PHP | `templates/standards/php.standards.md` |
-| JavaScript/TypeScript | `templates/standards/javascript.standards.md` |
+### Creating Language-Specific Standards
 
-*Use the [Standards Detector](../tools/standards-detector.tool.md) to generate project-specific standards.*
+Use the [Standards Detector](../tools/standards-detector.md) to analyze your codebase and generate project-specific standards automatically.
 
 ---
 
@@ -149,18 +139,11 @@ ORDER BY column_name;
 To customize standards for your project:
 
 1. **Run Standards Detector** (recommended)
-   Have AI analyze your codebase using the [Standards Detector](../tools/standards-detector.tool.md) tool.
+   Have AI analyze your codebase using the [Standards Detector](../tools/standards-detector.md) tool.
    This creates files in `docs/ai/standards/` based on your existing code.
 
-2. **Copy and Modify Template**
-   Copy a framework template to `docs/ai/standards/`:
-   ```bash
-   cp docs/ai/.context/templates/standards/php.standards.md docs/ai/standards/
-   ```
-   Then customize the placeholders.
-
-3. **Create from Scratch**
-   Create `docs/ai/standards/{language}.standards.md` with your own format.
+2. **Create from Scratch**
+   Create `docs/ai/standards/{language}.standards.md` with your own format following the patterns in this document.
 
 ### Common Customizations
 

package/dist/templates/templates/context.md

@@ -1,7 +1,22 @@
 # Project Context
 
-> **Purpose:** Master index for AI assistants working with this project. This is the primary entry point for all AI context.
-> **Directive:** Read this file first. It is the "Brain" of the project.
+> **Purpose:** User-defined project context for AI assistants. This file contains project-specific identity, tech stack, and custom configurations.
+> **Directive:** This file is linked from the framework entry point (`docs/ai/.contextuate/contextuate.md`). Edit this file freely to customize your project context.
+
+---
+
+## File Ownership
+
+| Path | Owner | Editable? |
+|------|-------|-----------|
+| `docs/ai/.contextuate/` | Framework (Contextuate) | No - overwritten on updates |
+| `docs/ai/context.md` | User (You) | Yes - customize freely |
+| `docs/ai/agents/` | User | Yes - your custom agents |
+| `docs/ai/standards/` | User | Yes - your custom standards |
+| `docs/ai/quickrefs/` | User | Yes - your generated quickrefs |
+| `docs/ai/tasks/` | User | Yes - your multi-session tasks |
+
+The `.contextuate/` folder contains immutable framework definitions that bootstrap AI context loading. The framework entry point (`contextuate.md`) links to this file for project-specific details.
 
 ---
 

package/dist/templates/templates/contextuate.md

@@ -2,11 +2,11 @@
 
 <!--
   CONTEXTUATE MANAGED FILE - DO NOT MODIFY
-  This file is generated by the Esotech Framework and will be overwritten during updates.
+  This file is generated by the Contextuate Framework and will be overwritten during updates.
   Customize your project context in: docs/ai/context.md
 -->
 
-> **Purpose:** Master entry point for AI assistants. This file bootstraps the Esotech Framework.
+> **Purpose:** Master entry point for AI assistants. This file bootstraps the Contextuate Framework.
 > **Directive:** Read this file first, then follow instructions to load project context.
 
 ---
@@ -29,7 +29,7 @@ This folder (`docs/ai/.contextuate/`) contains the immutable framework definitio
 2.  **Select**: Identify the specific agent, tool, or standard relevant to your current task.
 3.  **Load**: Read only that specific file.
 
-For example, if you need to create a new agent, read `docs/ai/.contextuate/tools/agent-creator.tool.md`. You do not need to read the entire standards library unless you are writing code that specifically requires it.
+For example, if you need to create a new agent, read `docs/ai/.contextuate/tools/agent-creator.md`. You do not need to read the entire standards library unless you are writing code that specifically requires it.
 
 ---
 
@@ -40,9 +40,9 @@ For example, if you need to create a new agent, read `docs/ai/.contextuate/tools
 ### Agent Registry
 | Task Domain    | Agent        | Context File                                                                             |
 | -------------- | ------------ | ---------------------------------------------------------------------------------------- |
-| General Coding | Base Agent   | [.contextuate/agents/base.md](.contextuate/agents/base.md)                               |
-| Documentation  | Docs Expert  | [.contextuate/agents/documentation-expert.md](.contextuate/agents/documentation-expert.md) |
-| Tools Expert   | Tools Expert | [.contextuate/agents/tools-expert.md](.contextuate/agents/tools-expert.md)               |
+| General Coding | Base Agent   | [agents/base.md](agents/base.md)                               |
+| Documentation  | Docs Expert  | [agents/documentation-expert.md](agents/documentation-expert.md) |
+| Tools Expert   | Tools Expert | [agents/tools-expert.md](agents/tools-expert.md)               |
 
 ### Custom Agents
 Custom agents are stored in `docs/ai/agents/`. Create new agents using the Agent Creator tool.
@@ -54,29 +54,25 @@ Custom agents are stored in `docs/ai/agents/`. Create new agents using the Agent
 ### Framework Tools
 | Tool                   | Purpose                       | Instruction Guide                                                                              |
 | ---------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------- |
-| **Standards Detector** | Analyze code to find patterns | [.contextuate/tools/standards-detector.tool.md](.contextuate/tools/standards-detector.tool.md) |
-| **Quickref Generator** | Condense docs for AI usage    | [.contextuate/tools/quickref.tool.md](.contextuate/tools/quickref.tool.md)                     |
-| **Agent Creator**      | Generate new agent personas   | [.contextuate/tools/agent-creator.tool.md](.contextuate/tools/agent-creator.tool.md)           |
+| **Standards Detector** | Analyze code to find patterns | [tools/standards-detector.md](tools/standards-detector.md) |
+| **Quickref Generator** | Condense docs for AI usage    | [tools/quickref.md](tools/quickref.md)                     |
+| **Agent Creator**      | Generate new agent personas   | [tools/agent-creator.md](tools/agent-creator.md)           |
 
 ---
 
 ## 4. Standards & Conventions
 
-### Coding Standards
-| Language              | Standards File                                                                                                       |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| PHP                   | [.contextuate/templates/standards/php.standards.md](.contextuate/templates/standards/php.standards.md)               |
-| JavaScript/TypeScript | [.contextuate/templates/standards/javascript.standards.md](.contextuate/templates/standards/javascript.standards.md) |
-| Python                | [.contextuate/templates/standards/python.standards.md](.contextuate/templates/standards/python.standards.md)         |
-| Go                    | [.contextuate/templates/standards/go.standards.md](.contextuate/templates/standards/go.standards.md)                 |
-| Java                  | [.contextuate/templates/standards/java.standards.md](.contextuate/templates/standards/java.standards.md)             |
+### Framework Standards
+| Standard | Purpose | File |
+|----------|---------|------|
+| **Coding Standards** | General coding principles | [standards/coding-standards.md](standards/coding-standards.md) |
+| **Behavioral Guidelines** | AI interaction rules | [standards/behavioral-guidelines.md](standards/behavioral-guidelines.md) |
+| **Task Workflow** | Multi-session task structure | [standards/task-workflow.md](standards/task-workflow.md) |
+| **Agent Workflow** | Multi-agent coordination | [standards/agent-workflow.md](standards/agent-workflow.md) |
+| **Agent Roles** | Specialist agent roster | [standards/agent-roles.md](standards/agent-roles.md) |
 
-Custom standards can be added in `docs/ai/standards/`.
-
-### Behavioral Guidelines
-**[Behavioral Guidelines](.contextuate/standards/behavioral-guidelines.md)**
-- Verified Truth: Do not speculate.
-- Minimal Intervention: Only change what is requested.
+### Project-Specific Standards
+Create language-specific standards in `docs/ai/standards/` using the [Standards Detector](tools/standards-detector.md) tool.
 
 ---
 
@@ -94,16 +90,13 @@ Custom standards can be added in `docs/ai/standards/`.
 | **Custom Commands**     | `docs/ai/commands/`  |
 
 ### Multi-Session Tasks
-For complex tasks that span multiple sessions:
-1. Read **[Task Workflow](.contextuate/standards/task-workflow.md)**.
-2. Create a folder in `docs/ai/tasks/{task-name}/`.
-3. Maintain a `00-project-scope.md` and log files.
+For complex tasks that span multiple sessions, follow the Task Workflow standard (see section 4).
 
 ---
 
 ## 6. Framework Information
 
-**Esotech Framework** is a standardized AI context framework.
+**Contextuate Framework** is a standardized AI context framework.
 
 - **Documentation:** https://contextuate.md
 - **Version:** Check `.contextuate/version.json`

package/dist/templates/templates/standards/go.md

@@ -0,0 +1,167 @@
+# Go Coding Standards
+
+> **Language:** Go
+> **Generated:** {DATE}
+
+---
+
+## Formatting
+
+### Tooling
+- **Required:** `gofmt` (or `goimports`) must be applied to all files.
+
+### Indentation
+- **Style:** Tabs (Standard Go behavior)
+
+### Line Length
+- **Guideline:** No strict limit, but prefer readability (80-120 chars).
+
+---
+
+## Naming Conventions
+
+### General Rule
+- Use `MixedCaps` or `mixedCaps` (CamelCase).
+- Keep names short and concise.
+
+### Packages
+- **Style:** lowercase, single word
+- **Avoid:** snake_case, camelCase in package names
+- **Example:** `package user`, not `package user_service`
+
+### Interfaces
+- **Style:** Method name + "er" (if single method)
+- **Example:** `Reader`, `Writer`, `Formatter`
+
+### Structs/Interfaces
+- **Exported:** PascalCase (`User`)
+- **Unexported:** camelCase (`userHelper`)
+
+### Functions/Methods
+- **Exported:** PascalCase (`GetUser`)
+- **Unexported:** camelCase (`parseData`)
+
+### Constants
+- **Style:** PascalCase (for exported) or camelCase
+- **Avoid:** UPPER_SNAKE_CASE (unlike other languages)
+- **Example:** `MaxRetries`, not `MAX_RETRIES`
+
+---
+
+## Structure
+
+### File Organization
+```go
+package main
+
+// 1. Imports (grouped: stdlib, third-party, local)
+import (
+    "fmt"
+    "os"
+
+    "github.com/pkg/errors"
+
+    "myproject/internal/user"
+)
+
+// 2. Constants
+const DefaultTimeout = 30
+
+// 3. Types (Structs/Interfaces)
+type Service interface {
+    Do() error
+}
+
+// 4. Factory Functions
+func NewService() Service {
+    return &serviceImpl{}
+}
+
+// 5. Methods
+func (s *serviceImpl) Do() error {
+    return nil
+}
+```
+
+---
+
+## Error Handling
+
+### Pattern
+- **Style:** Check errors immediately. Avoid nesting.
+
+```go
+// GOOD
+f, err := os.Open("file.txt")
+if err != nil {
+    return err
+}
+
+// BAD
+if f, err := os.Open("file.txt"); err == nil {
+    // ...
+}
+```
+
+### Wrapping
+- **Guideline:** Wrap errors with context when passing up the stack.
+- **Example:** `fmt.Errorf("failed to open config: %w", err)`
+
+---
+
+## Documentation
+
+### Comments
+- **Exported identifiers:** MUST have a doc comment starting with the name.
+- **Format:** Complete sentences.
+
+```go
+// User represents a system user.
+type User struct { ... }
+
+// Fetch retrieves the user by ID.
+func (u *User) Fetch(id int) error { ... }
+```
+
+---
+
+## Common Patterns
+
+### Options Pattern
+```go
+// Preferred for complex constructors
+type Option func(*Server)
+
+func WithPort(port int) Option {
+    return func(s *Server) { s.port = port }
+}
+
+func NewServer(opts ...Option) *Server { ... }
+```
+
+### Context
+- **Guideline:** Pass `context.Context` as the first argument to functions performing I/O.
+
+```go
+func (s *Service) GetData(ctx context.Context, id string) error { ... }
+```
+
+---
+
+## Anti-Patterns
+
+```go
+// BAD: Panic in libraries
+func Parse() {
+    if err != nil {
+        panic(err) // Return error instead
+    }
+}
+
+// BAD: Global state
+var db *sql.DB // Use dependency injection
+```
+
+---
+
+*This file should be customized for your project. Replace placeholders with actual values.*