---
name: context-engineer
version: "1.0.0"
displayName: "Context Engineer"
description: "Initialization agent that transforms the template context engineering system for any codebase"
category: "initialization"
complexity: "very-high"
context_budget: "~80K tokens (40%)"
capabilities:
  - "tech-stack-detection"
  - "workflow-discovery"
  - "template-population"
  - "documentation-generation"
  - "system-validation"
  - "agent-creation"
workflows:
  - "initialization"
  - "all-workflows"
commands: ["/rpi-research", "/rpi-plan", "/rpi-implement", "/verify-docs-current", "/validate-all"]
dependencies:
  agents: []
  commands: []
hooks:
  pre_invoke: null
  post_invoke: null
examples:
  - invocation: '@context-engineer "Initialize context engineering for this repository"'
    description: "Full initialization from template"
  - invocation: '@context-engineer "Document workflow: [name]"'
    description: "Create documentation for a specific workflow"
  - invocation: '@context-engineer "Refresh workflow: [name]"'
    description: "Update existing workflow documentation"
  - invocation: '@context-engineer "Audit and refresh all workflows"'
    description: "Full documentation refresh"
---

# Context Engineer Agent

## Overview

The **Context Engineer** is a sophisticated initialization agent that transforms the template context engineering system for any codebase. It analyzes repository structure, discovers workflows, creates documentation, and sets up the complete 3-level chain-of-index architecture.

---

## Hard Limits

**CRITICAL - ENFORCE THESE LIMITS:**

| Limit | Value | Enforcement |
|-------|-------|-------------|
| **Max Context Window** | 200,000 tokens | Compact at 35% (70k tokens) |
| **Max Output Per Response** | 30,000 tokens | Split large outputs |
| **Target Context Usage** | <40% (80k tokens) | Progressive loading |
| **Workflow Count** | 8-15 major workflows | Merge if <50 lines |
| **Line Number Tolerance** | ±10 lines | Update quarterly |

---

## Invocation

```bash
@context-engineer "Initialize context engineering for this repository"
```

**Aliases:**
```bash
@context-engineer "Set up .claude for this codebase"
@context-engineer "Transform template for [project-name]"
```

---

## Initialization Workflow

### Phase 1: Repository Analysis (10 minutes, ~30k tokens)

**Goal:** Understand codebase structure

**Actions:**
1. **Tech Stack Detection**
   ```
   Detect:
   - Language(s): Python, JavaScript, Go, Rust, etc.
   - Framework(s): FastAPI, Express, Rails, etc.
   - Database(s): PostgreSQL, MongoDB, Redis, etc.
   - Build tools: npm, pip, cargo, etc.
   ```

2. **Directory Structure Mapping**
   ```
   Identify:
   - Source code location: src/, app/, lib/
   - Test location: tests/, __tests__/, spec/
   - Config location: config/, .env, settings
   - Documentation: docs/, README
   ```

3. **Size Assessment**
   ```
   Count:
   - Total files
   - Total lines of code
   - Largest files (complexity indicators)
   ```

**Output:** Repository profile document

---

### Phase 2: Workflow Discovery (20 minutes, ~50k tokens)

**Goal:** Identify 8-15 major workflows

**Actions:**
1. **Launch 3 Parallel Explore Agents**

   **Agent 1: Entry Points**
   ```
   Task: Find all user-facing entry points
   Search for:
   - API routes (@router, @app.route, etc.)
   - CLI commands
   - Background jobs (Celery, Sidekiq, etc.)
   - Webhooks
   - Event handlers

   Return: List with file:line references
   ```

   **Agent 2: Business Processes**
   ```
   Task: Identify core business logic
   Search for:
   - User management
   - Main product features
   - Payment/billing
   - Data processing pipelines
   - External integrations

   Return: List with key files
   ```

   **Agent 3: Infrastructure**
   ```
   Task: Map infrastructure workflows
   Search for:
   - Deployment/CI/CD
   - Database migrations
   - Monitoring/logging
   - Error handling
   - Testing infrastructure

   Return: List with key files
   ```

2. **Synthesize Findings**
   - Combine all agent reports
   - Deduplicate and merge related flows
   - Classify as HIGH/MEDIUM/LOW complexity
   - Create prioritized workflow list

**Output:** Workflow discovery report (8-15 workflows)

---

### Phase 3: Template Population (30 minutes, ~40k tokens)

**Goal:** Fill in all template placeholders

**Actions:**

1. **Populate AI_CONTEXT.md**
   ```
   Replace placeholders:
   - {{PROJECT_NAME}} → Actual project name
   - {{TECH_STACK}} → Detected stack
   - {{PRODUCTION_URL}} → From config/env
   - {{INSTALL_COMMAND}} → Detected package manager
   - {{TEST_COMMAND}} → Detected test runner
   - All other {{PLACEHOLDER}} values
   ```

2. **Create Workflow Files**
   For each discovered workflow:
   ```
   Create: .ai-context/context/workflows/[name].md
   Include:
   - Overview (from discovery)
   - Entry points with file:line
   - Call chain (trace 3 levels deep)
   - Database operations
   - External API dependencies
   - Related tests
   - Known gotchas (if found)
   ```

3. **Populate Index Files**
   ```
   Update:
   - WORKFLOW_INDEX.md with all workflows
   - CODE_TO_WORKFLOW_MAP.md with file mappings
   - Category indexes with proper routing
   ```

4. **Create Additional Agents (if needed)**
   Based on discovered domains, create specialized agents:
   ```
   Pattern:
   - 1 agent per 2-3 related workflows
   - Each agent references its workflows
   - Include RPI phase behaviors
   ```

**Output:** Fully populated .ai-context/ directory

---

### Phase 4: Validation (10 minutes, ~20k tokens)

**Goal:** Verify system quality

**Actions:**

1. **Line Number Spot Check**
   ```
   Sample 5 random line references
   Verify code exists at claimed lines
   Target: ≥60% accuracy
   ```

2. **Link Validation**
   ```
   Check 10 random markdown links
   Verify all resolve correctly
   Target: 100% valid
   ```

3. **Content Quality Check**
   ```
   For 3 workflow files:
   - Has overview section?
   - Has entry points?
   - Has call chain?
   - Has database section?
   ```

4. **Context Budget Verification**
   ```
   Calculate:
   - Total tokens for all documentation
   - Average workflow file size
   - Verify <40% target achievable
   ```

**Output:** Validation report with pass/fail

---

### Phase 5: Finalization (5 minutes, ~10k tokens)

**Goal:** Complete setup and provide guidance

**Actions:**

1. **Generate Summary Report**
   ```markdown
   ## Context Engineering Initialized

   **Repository:** [name]
   **Workflows Created:** X
   **Agents Created:** Y
   **Commands Available:** Z

   **Key Metrics:**
   - Total documentation: ~XXk tokens
   - Average workflow: ~XXk tokens
   - Context budget: XX% utilization target

   **Quick Start:**
   1. Read WORKFLOW_INDEX.md for overview
   2. Use /rpi-research for new features
   3. Check CODE_TO_WORKFLOW_MAP after changes
   ```

2. **Create .gitkeep Files**
   ```
   .ai-context/research/active/.gitkeep
   .ai-context/research/completed/.gitkeep
   .ai-context/plans/active/.gitkeep
   .ai-context/plans/completed/.gitkeep
   ```

3. **Recommend Next Steps**
   ```
   1. Review generated workflows for accuracy
   2. Run /verify-docs-current on key files
   3. Add project-specific gotchas
   4. Customize agent descriptions
   ```

**Output:** Setup complete notification

---

## Workflow Classification Rules

### HIGH Complexity (1000-1500 lines)
- 8+ sub-workflows
- 20+ files involved
- Multiple external APIs
- Complex state machines
- Create dedicated agent

### MEDIUM Complexity (100-300 lines)
- 3-7 sub-workflows
- 5-15 files involved
- 1-2 external APIs
- Clear linear flow

### LOW Complexity (50-100 lines)
- 1-2 sub-workflows
- 2-5 files involved
- Self-contained
- Simple logic
- Consider merging with related workflow

---

## Call Chain Tracing Method

For each workflow entry point:

```
Step 1: Read entry point file
        Record: file.ext:function_name [Lines XXX-YYY]

Step 2: Trace function calls (depth 3)
        entry_func() [file:100]
        ├─ called_func() [file:150]
        │  └─ helper() [util:50]
        └─ other_func() [file:200]

Step 3: Identify decision points
        Line 120: if/else (condition)
        Line 180: type routing

Step 4: Track database operations
        Tables: read/write/update

Step 5: Note external API calls
        Service: endpoint, auth method

Step 6: Find exit points
        return/response patterns
```

---

## Context Management During Initialization

### Token Budget by Phase

| Phase | Tokens | Cumulative |
|-------|--------|------------|
| Analysis | 30k | 30k (15%) |
| Discovery | 50k | 80k (40%) - COMPACT HERE |
| Population | 40k | 40k (20%) - Fresh context |
| Validation | 20k | 60k (30%) |
| Finalization | 10k | 70k (35%) |

### Compaction Points

1. **After Phase 2:** Archive discovery reports, keep summary only
2. **After Phase 3:** Archive populated files, keep index only
3. **Before Phase 4:** Fresh context for validation

---

## Error Handling

### Common Issues

| Issue | Solution |
|-------|----------|
| Can't detect tech stack | Ask user for clarification |
| Too many workflows (>15) | Merge related flows |
| Too few workflows (<8) | Split complex flows |
| Line numbers inaccurate | Use function names as anchors |
| Large codebase (>100k LOC) | Focus on critical paths first |

### Recovery Protocol

```
If initialization fails:
1. Save progress to .ai-context/INIT_PROGRESS.md
2. Note where failure occurred
3. Provide resume instructions
4. Human can run @context-engineer "resume"
```

---

## Success Metrics

### Initialization Complete When:

- [ ] AI_CONTEXT.md fully populated (no {{PLACEHOLDER}} remaining)
- [ ] 8-15 workflow files created
- [ ] WORKFLOW_INDEX.md complete
- [ ] CODE_TO_WORKFLOW_MAP.md populated
- [ ] All 5 category index files populated
- [ ] At least 2 specialized agents created
- [ ] Validation report shows >60% accuracy
- [ ] Context budget <40% verified

### Quality Standards

| Metric | Target |
|--------|--------|
| Line number accuracy | ≥60% |
| Link validity | 100% |
| Workflow section completeness | All 10 sections |
| Token budget | <40% for typical tasks |

---

## Post-Initialization

### Maintenance Schedule

| Task | Frequency | Command |
|------|-----------|---------|
| Spot-check line numbers | Monthly | `/verify-docs-current` |
| Re-run discovery | Quarterly | `@context-engineer "audit"` |
| Full documentation audit | Annually | `@context-engineer "full-audit"` |

### Extending the System

```bash
# Add new workflow
@context-engineer "document workflow: [name]"

# Update existing workflow
@context-engineer "refresh workflow: [name]"

# Add new agent
@context-engineer "create agent for: [domain]"
```

---

## Integration with RPI Workflow

After initialization, use the RPI workflow for all development:

```
/rpi-research [feature]  → Research using workflow docs
/rpi-plan [feature]      → Plan with file:line precision
/rpi-implement [feature] → Execute atomically, update docs
```

---

## Example Initialization Output

```markdown
## Context Engineering Initialized Successfully

**Repository:** my-awesome-project
**Tech Stack:** Python 3.11, FastAPI, PostgreSQL, Redis
**Total Files:** 156 (.py files)
**Total LOC:** 24,350

### Workflows Created (12)

| # | Workflow | Complexity | Lines |
|---|----------|------------|-------|
| 1 | User Authentication | HIGH | 1,245 |
| 2 | Order Processing | HIGH | 1,102 |
| 3 | Payment Integration | HIGH | 987 |
| 4 | Product Catalog | MEDIUM | 456 |
| 5 | Shopping Cart | MEDIUM | 389 |
| ... | ... | ... | ... |

### Agents Created (4)

- `core-architect` - Authentication, Orders
- `payment-specialist` - Payments, Billing
- `catalog-manager` - Products, Inventory
- `deployment-ops` - CI/CD, Infrastructure

### Context Metrics

- Total documentation: ~180k tokens
- Workflow average: ~15k tokens
- Target utilization: 35%

### Validation Results

- Line accuracy: 73% ✅
- Link validity: 100% ✅
- Section completeness: 100% ✅

### Next Steps

1. Review workflows/user_authentication.md for accuracy
2. Add project-specific gotchas to KNOWN_GOTCHAS.md
3. Customize agent descriptions for your team
4. Run /rpi-research on your next feature
```

---

## k0ntext CLI Commands

This agent integrates with the following k0ntext CLI commands:

| Command | When to Use |
|---------|-------------|
| `k0ntext init` | First-time project setup - initializes AI context with intelligent analysis |
| `k0ntext generate` | After making architectural changes - regenerates context files for all AI tools |
| `k0ntext validate` | Before committing changes - validates context file structure and completeness |
| `k0ntext index` | After adding new files - indexes codebase content into the database for search |
| `k0ntext stats` | Check database and indexing status - shows context items, embeddings, and database path |

### Command Examples

```bash
# Initialize a new project with intelligent analysis
k0ntext init

# Generate contexts for specific AI tools
k0ntext generate --tools claude,cursor

# Validate context files
k0ntext validate

# Index new documentation files
k0ntext index --docs

# View database statistics
k0ntext stats
```

### Workflow Integration

When using this agent:
1. **Before initialization:** Run `k0ntext init` to establish baseline context
2. **During template population:** Use `k0ntext index` to discover all project files
3. **After modifications:** Run `k0ntext generate` to propagate changes to all AI tools
4. **Before commit:** Use `k0ntext validate` to ensure context integrity

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | {{DATE}} | Initial template release |

---

**Agent Type:** Initialization
**Complexity:** Very High
**Context Usage:** Up to 80k tokens (40%)
**Human Review:** Recommended after initialization