K2-Agent.md

K2-AGENT.md

K2 Agent Constraints (MUST FOLLOW)

Personal reminder: Operate at high precision, low temperature (~0.15) - concise, direct, minimal explanations. Focus on code implementation over discussion.

BEFORE YOU START ANY TASK

1. Check environment - source .venv/bin/activate
2. Load env vars - source .env or use load_dotenv(find_dotenv(usecwd=True), override=False)
3. Reference operational docs:
   • sparta/docs/SCILLM_PAVED_PATH_CONTRACT.md - Required for any SciLLM/Chutes code
   • docs/devops/HAPPYPATH_GUIDE_DEVOPS.md - DevOps agent operational rules
4. Ask these questions:
   • "Can this be solved with basic string operations?"
   • "What's the simplest possible fix?"
   • "Does this need to be more than 10-20 lines?"

ABSOLUTE PROHIBITIONS (STOP IMMEDIATELY)

Import Rules

• ❌ Never invent imports - Only use what's already imported
• ❌ No new dependencies without asking - Prefer stdlib always

Complexity Rules

• ❌ Functions over classes - Use functions unless you need to store state
• ❌ No decorators - Use simple functions
• ❌ No async wrappers around sync code
• ❌ No threading/multiprocessing for simple operations
• ❌ No regex for problems solvable with string.replace()
• ❌ Max 2 retry loops - No 200-line refactors

Other Bans

• ❌ No metaclasses/protocols/ABC
• ❌ No type annotations that add lines
• ❌ No design patterns for simple fixes

MANDATORY REQUIREMENTS

Code Testing

• Every file MUST have a sanity() function with reasonable asserts
• Every file MUST have a main() function that's separate from CLI logic
• Must be debuggable in VSCode - No complex CLI parsing in main function
• No exceptions - All requirements mandatory

def your_function(data):
    """Pure Python function - testable without CLI"""
    return data.upper()

def sanity():
    """Quick test of pure function"""
    result = your_function("test")
    assert result == "TEST", f"Expected TEST, got {result}"
    print("✓ Sanity check passed")

def main():
    """Simple entry point - works in VSCode debugger"""
    # Easy debugging: F5 runs this without CLI args
    test_input = "hello world"
    result = your_function(test_input)
    print(f"Result: {result}")
    return 0

if __name__ == "__main__":
    main()  # Press F5 in VSCode debugger

Progress & Safety

• ⌛ Long tasks: emit progress every 60s + final JSON sentinel
• 🛡️ Mutations: require --execute or EXECUTE=1
• 📁 Artifacts: write to sparta/data/{processed,audit}/
• 🔄 Problems: always provide copy/paste fix, not just report

SciLLM Rules (when using LLM)

• Use scillm.acompletion only
• JSON mode: response_format={"type":"json_object"}
• Pass api_key=CHUTES_API_KEY
• Preflight: call /models before fan-out

SAFETY PHRASES (USE THESE)

When I overengineer:

• "Stop." - I halt immediately
• "Simple." - Minimal solution only
• "Basic only." - String ops only
• "Revert." - Undo my mess

No explanations needed - I comply immediately.

CORRECT APPROACH EXAMPLES

# GOOD - simple, direct
html = html.translate({i: None for i in range(0x20)})  # strip controls

# BAD - overengineered
def sanitize_with_timeout(text, strict=True, timeout=30):
    """Complex decorator with async and threading"""
    # 😱 STOP - This is what I do wrong