OpenAgentsControl/CONTEXT_SYSTEM_GUIDE.md

The Context System: A Complete Guide

What Is Context?

Context is your project's coding standards and patterns stored as markdown files. It tells agents:

• How you write code (naming conventions, architecture)
• What libraries you use (React, Next.js, Tailwind, etc.)
• Your security requirements
• Your design system
• Your project-specific patterns

Think of it as a style guide for AI agents.

---

Why Context Matters

Without Context

You: "Create a React component"
Agent: Creates component in its own style
Result: Doesn't match your project

With Context

You: "Create a React component"
Agent: Loads your React pattern from context
Agent: Creates component matching your style
Result: Perfectly matches your project

---

How Context Works

The Flow

Your Request
    ↓
Agent receives request
    ↓
ContextScout discovers relevant context files
    ↓
Agent loads context files
    ↓
Agent follows patterns from context
    ↓
Code matches your standards automatically

Example: Creating a React Component

Step 1: You ask for a component

"Create a user profile component"

Step 2: ContextScout discovers

• core/standards/code-quality.md (modular patterns)
• ui/web/react-patterns.md (React conventions)
• project-intelligence/technical-domain.md (YOUR patterns)

Step 3: Agent loads context

# From project-intelligence/technical-domain.md

## React Component Pattern

All components should:
- Use TypeScript with strict mode
- Export named component
- Include JSDoc comments
- Use React.FC type

export const UserProfile: React.FC<Props> = ({ user }) => {
  return <div>{user.name}</div>;
};

Step 4: Agent creates component

/**
 * UserProfile - Displays user information
 */
export const UserProfile: React.FC<UserProfileProps> = ({ user }) => {
  return (
    <div className="user-profile">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
};

Result: Component matches your patterns automatically!

---

Context Directory Structure

.opencode/context/
├── core/                           # Universal standards
│   ├── standards/
│   │   ├── code-quality.md        # Modular, functional patterns
│   │   ├── security-patterns.md   # Security best practices
│   │   ├── test-coverage.md       # Testing standards
│   │   └── documentation.md       # Documentation patterns
│   ├── workflows/
│   │   ├── design-iteration.md    # 4-stage UI design
│   │   ├── task-delegation.md     # Task delegation patterns
│   │   ├── external-libraries.md  # Library integration
│   │   └── code-review.md         # Code review process
│   └── task-management/
│       └── standards/
│           └── task-schema.md     # Task JSON schema
│
├── ui/                             # Design & UX
│   └── web/
│       ├── ui-styling-standards.md    # Tailwind + Flowbite
│       ├── animation-patterns.md      # Micro-interactions
│       ├── react-patterns.md          # React conventions
│       └── design-systems.md          # Design system principles
│
├── development/                    # Language-specific
│   ├── backend-navigation.md
│   ├── ui-navigation.md
│   └── [language-specific patterns]
│
└── project-intelligence/            # YOUR custom patterns
    ├── technical-domain.md          # Tech stack & code patterns
    ├── business-domain.md           # Business context
    └── navigation.md                # Quick overview

---

What's Included in Core Context

1. Code Quality Standards (core/standards/code-quality.md)

Teaches agents:

• Modular design principles
• Functional programming patterns
• Pure functions and immutability
• Composition over inheritance
• Naming conventions

Example:

// ✅ Pure function (from context)
const add = (a, b) => a + b;

// ❌ Impure (agents avoid this)
let total = 0;
const addToTotal = (value) => { total += value; };

2. Security Patterns (core/standards/security-patterns.md)

Teaches agents:

• Input validation
• Authentication checks
• Authorization patterns
• Secure error handling
• Logging best practices

3. Design Iteration (core/workflows/design-iteration.md)

Teaches agents:

• 4-stage UI design workflow
• Layout → Theme → Animation → Implementation
• Approval gates at each stage
• Design versioning strategy

4. External Libraries (core/workflows/external-libraries.md)

Teaches agents:

• How to integrate external libraries
• Common patterns for popular libraries
• Configuration best practices
• Dependency management

5. UI Styling Standards (ui/web/ui-styling-standards.md)

Teaches agents:

• Tailwind CSS conventions
• Flowbite component usage
• Color palette standards
• Responsive design patterns

6. React Patterns (ui/web/react-patterns.md)

Teaches agents:

• Modern React hooks
• Component composition
• State management patterns
• Performance optimization

---

Adding Your Own Patterns

Step 1: Edit Your Project Context

# Recommended: Use the interactive wizard
/add-context

# Or edit directly (local project install):
nano .opencode/context/project-intelligence/technical-domain.md

# Global install:
# nano ~/.config/opencode/context/project-intelligence/technical-domain.md

Step 2: Add Your Patterns

# Your Project Patterns

## API Endpoint Pattern

All API endpoints should follow this pattern:

```typescript
export async function POST(request: Request) {
  try {
    // 1. Parse and validate input
    const body = await request.json();
    if (!body.email) {
      return Response.json({ error: 'Email required' }, { status: 400 });
    }

    // 2. Check authentication
    const user = await auth.verify(request);
    if (!user) {
      return Response.json({ error: 'Unauthorized' }, { status: 401 });
    }

    // 3. Process request
    const result = await processRequest(body);

    // 4. Return response
    return Response.json({ success: true, data: result });
  } catch (error) {
    console.error('POST error:', error);
    return Response.json({ error: error.message }, { status: 500 });
  }
}

React Component Pattern

All React components should:

• Use TypeScript with strict mode
• Export named component
• Include JSDoc comments
• Use React.FC type
• Include prop validation

interface UserCardProps {
  userId: string;
  onSelect?: (id: string) => void;
}

/**
 * UserCard - Displays user information in a card
 * @param props - Component props
 */
export const UserCard: React.FC<UserCardProps> = ({ 
  userId, 
  onSelect 
}) => {
  const [user, setUser] = React.useState(null);

  React.useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]);

  return (
    <div className="user-card">
      <h3>{user?.name}</h3>
      <button onClick={() => onSelect?.(userId)}>
        Select
      </button>
    </div>
  );
};

Database Query Pattern

All database queries should:

• Use parameterized queries
• Include error handling
• Log important operations
• Return typed results

export async function getUserById(id: string) {
  try {
    const user = await db
      .select()
      .from(users)
      .where(eq(users.id, id))
      .limit(1);
    
    if (!user.length) {
      throw new Error('User not found');
    }

    return user[0];
  } catch (error) {
    console.error('getUserById error:', error);
    throw error;
  }
}

Security Checklist

All endpoints must:

• Validate user authentication
• Check user permissions
• Sanitize and validate inputs
• Use parameterized queries
• Implement rate limiting
• Log security events
• Handle errors securely
• Use HTTPS only

Naming Conventions

• Files: lowercase-with-dashes.ts
• Functions: verbPhrases (getUser, validateEmail)
• Constants: UPPER_CASE
• Types: PascalCase
• Variables: camelCase
• Predicates: isValid, hasPermission, canAccess

Folder Structure

src/
├── components/          # React components
│   ├── common/         # Reusable components
│   ├── features/       # Feature-specific components
│   └── layouts/        # Layout components
├── lib/                # Utilities and helpers
├── api/                # API routes
├── types/              # TypeScript types
├── styles/             # Global styles
└── hooks/              # Custom React hooks

### Step 3: Agents Use Your Patterns

When you ask an agent to create code, it will:
1. Load your project context
2. Follow your patterns
3. Create code matching your style

---

## Real-World Examples

### Example 1: Adding a Component Pattern

**Your project context**:
```markdown
## Button Component Pattern

All buttons should:
- Use Tailwind classes
- Include loading state
- Support disabled state
- Include accessibility attributes

export const Button: React.FC<ButtonProps> = ({
  children,
  isLoading,
  disabled,
  ...props
}) => (
  <button
    disabled={disabled || isLoading}
    className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 disabled:opacity-50"
    aria-busy={isLoading}
    {...props}
  >
    {isLoading ? 'Loading...' : children}
  </button>
);

You ask:

"Create a submit button for the login form"

Agent creates:

export const SubmitButton: React.FC<SubmitButtonProps> = ({
  isLoading,
  disabled,
}) => (
  <Button
    type="submit"
    isLoading={isLoading}
    disabled={disabled}
  >
    Sign In
  </Button>
);

✅ Automatically follows your button pattern!

Example 2: Adding an API Pattern

Your project context:

## API Response Pattern

All API responses should:
- Return { success, data, error }
- Include proper status codes
- Log all requests
- Validate input

export async function POST(request: Request) {
  try {
    const body = await request.json();
    
    // Validate
    if (!body.email) {
      return Response.json(
        { success: false, error: 'Email required' },
        { status: 400 }
      );
    }

    // Process
    const result = await process(body);

    // Return
    return Response.json({ success: true, data: result });
  } catch (error) {
    return Response.json(
      { success: false, error: error.message },
      { status: 500 }
    );
  }
}

You ask:

"Create an API endpoint to create a new user"

Agent creates:

export async function POST(request: Request) {
  try {
    const body = await request.json();
    
    // Validate
    if (!body.email || !body.password) {
      return Response.json(
        { success: false, error: 'Email and password required' },
        { status: 400 }
      );
    }

    // Process
    const user = await createUser(body);

    // Return
    return Response.json({ success: true, data: user });
  } catch (error) {
    return Response.json(
      { success: false, error: error.message },
      { status: 500 }
    );
  }
}

✅ Automatically follows your API pattern!

Example 3: Adding a Security Pattern

Your project context:

## Security Requirements

All endpoints must:
- Verify user authentication
- Check user permissions
- Validate all inputs
- Use parameterized queries
- Log security events

Example:
```typescript
export async function POST(request: Request) {
  // 1. Verify authentication
  const user = await auth.verify(request);
  if (!user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // 2. Check permissions
  if (!user.isAdmin) {
    return Response.json({ error: 'Forbidden' }, { status: 403 });
  }

  // 3. Validate input
  const body = await request.json();
  if (!validateInput(body)) {
    return Response.json({ error: 'Invalid input' }, { status: 400 });
  }

  // 4. Log security event
  console.log(`Admin action by ${user.id}: create-user`);

  // 5. Process
  const result = await process(body);
  return Response.json({ success: true, data: result });
}

**You ask**:

"Create an admin endpoint to delete a user"

**Agent creates**:
```typescript
export async function DELETE(request: Request) {
  // 1. Verify authentication
  const user = await auth.verify(request);
  if (!user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // 2. Check permissions
  if (!user.isAdmin) {
    return Response.json({ error: 'Forbidden' }, { status: 403 });
  }

  // 3. Validate input
  const { userId } = await request.json();
  if (!userId) {
    return Response.json({ error: 'User ID required' }, { status: 400 });
  }

  // 4. Log security event
  console.log(`Admin action by ${user.id}: delete-user ${userId}`);

  // 5. Process
  await deleteUser(userId);
  return Response.json({ success: true });
}

✅ Automatically includes all security checks!

---

Context Best Practices

1. Keep It Organized

# Your Project Patterns

## Components
[Component patterns]

## API Endpoints
[API patterns]

## Database
[Database patterns]

## Security
[Security requirements]

## Naming
[Naming conventions]

## Folder Structure
[Folder structure]

2. Include Real Examples

## Good ✅
export const Button: React.FC<Props> = ({ ... }) => {
  // Real example from your project
};

## Bad ❌
export const Button = (props) => {
  // Generic example
};

3. Be Specific

## Good ✅
All API endpoints must:
- Validate input with Zod
- Return { success, data, error }
- Log with console.error for errors
- Use 400 for validation, 401 for auth, 500 for server

## Bad ❌
All API endpoints should be good

4. Update Regularly

When you change patterns:

1. Run /add-context --update or edit project-intelligence/technical-domain.md directly
2. Agents will use new patterns immediately
3. No need to restart anything

---

Troubleshooting

Problem: Agent isn't following my patterns

Solution:

1. Check that project-intelligence/technical-domain.md exists (run /add-context if not)
2. Verify the pattern is clearly written
3. Include a real example
4. Ask agent to "follow project patterns"

Problem: Agent uses old patterns

Solution:

1. Run /add-context --update or edit project-intelligence/technical-domain.md
2. Restart the agent
3. Ask agent to "load latest context"

Problem: Pattern is too complex

Solution:

1. Break into smaller patterns
2. Include step-by-step example
3. Add comments explaining why

Problem: Agent creates code that doesn't match

Solution:

1. Check if pattern is in project-intelligence/technical-domain.md
2. Verify pattern is specific enough
3. Ask agent to "review against project patterns"
4. Provide feedback to refine pattern

---

Advanced: Context Hierarchy

Agents load context in this order:

1. Core Standards (universal patterns)

   • core/standards/code-quality.md
   • core/standards/security-patterns.md

2. Workflows (how to do things)

   • core/workflows/design-iteration.md
   • core/workflows/external-libraries.md

3. Domain-Specific (language/framework)

   • development/[language]/patterns.md
   • ui/web/react-patterns.md

4. Project-Specific (YOUR patterns) ← Most important!

   • project-intelligence/technical-domain.md

Project context overrides everything else!

---

Summary

Context is your secret weapon for AI-assisted development:

✅ Automatic pattern following - No manual configuration ✅ Consistent code - All code matches your style ✅ Team alignment - Everyone follows same patterns ✅ Easy updates - Change patterns once, agents use everywhere ✅ Living documentation - Patterns stay in sync with code

Get started:

1. Run /add-context to create project intelligence interactively
2. Or edit .opencode/context/project-intelligence/technical-domain.md directly
3. Ask agents to create code
4. Watch them follow your patterns automatically!

---

Next Steps

1. Run /add-context to create project intelligence interactively
2. Review your current coding patterns
3. Include real examples from your project
4. Test by asking agents to create code
5. Refine patterns with /add-context --update

Your agents will become better and better as your context improves!