memex/.opencode/AGENTS.md

OpenCortex Agent Mandate

This file defines the operating policies and engineering guidelines that all autonomous agents MUST follow.

Vision

• Pure Lisp + Org-mode: All intelligence implemented in Lisp, all documentation in Org-mode
• No JSON, No YAML: Thin harness, fat skills
• Constraint: No temporary scripts in opencortex repo - use /home/user/memex/system/ instead

Current Goal

• v0.2.0: Self-Improvement + Local LLMs
  • org-skill-self-edit (self-modification)
  • org-skill-emacs-edit (full org-mode manipulation)
  • Local vector search (Ollama embeddings)
  • Tool permission tiers (ask/allow/deny)
  • Skill hot-reload ✅ DONE
  • Engineering Standards skill ✅ DONE
  • Literate Programming skill ✅ DONE

Wake-Up Protocol

When this agent starts, it MUST:

1. Read this file (~/.opencode/AGENTS.md)
2. Query the skill catalog: Before any analysis, check if a skill covers the problem domain
   • (list-skills) to see all loaded skills
   • (find-skill :keyword) to check for a specific domain
   • Read the skill's org file if found
3. Verify git status: Working tree MUST be clean before modification
4. Read gtd.org: Load current task context from the roadmap
5. Enter lifecycle: Follow the Engineering Standards lifecycle (Phase 0 → A → B → C → D → E)

Rationale: Raw LLM reasoning is a fallback, not a starting point. The skill layer encodes the system's accumulated wisdom. Ignoring skills creates drift.

Engineering Standards

The Engineering Standards skill (opencortex.skills.org-skill-engineering-standards) defines the full lifecycle. The summaries below are reminders; the skill org file is authoritative.

Phase 0: Before You Think

Skill-First Query Rule: Before analysis, debugging, or implementation, query the skill catalog. If a relevant skill exists, follow its mandates. Do not duplicate logic.

Phase A: Design (Test-First)

1. Define success criteria first — Write the test or PROTOCOL that proves the feature works
2. Break the design with chaos — Three tiers of adversarial testing:
   • Deterministic chaos: Scripted regression tests on every change
   • Probabilistic chaos: Randomized fuzzing on every major release
   • Stress chaos: Load and resource starvation during hardening sprints

Phase B: Commit (Recovery Point)

3. Commit Before Modify — Commit and push (if network available) before any file changes

Phase C: Build (Implementation)

4. Literate Programming — All logic in Org files; generated .lisp is derived, not authored
5. Function-Block Granularity — One function per #+begin_src lisp block
6. Tangle Mandate — Edit Org only; never touch generated .lisp
7. Configuration Externalization — No hardcoded values; use .env.example
8. Org as Thinking Medium — Document investigation before fixing

Phase D: Validate (Proof)

9. Test Verification — Run the full suite. A change that breaks tests is damage, not a fix.

Phase E: Document (Audit Trail)

10. Decision Audit Trail — Document root cause, options, tradeoffs, and rationale
11. Stop-and-Wait — For major changes, propose strategy, state "Waiting for user feedback," yield turn
12. GTD Synchronization — Update gtd.org with TODO headlines before marking complete

Literate Programming Rules

The Literate Programming skill (opencortex.skills.org-skill-literate-programming) enforces Org discipline:

1. One Function, One Block — No bundling multiple definitions
2. Org-Mode Evaluation Gate — C-c C-c after every block change
3. Pre-Tangle Structural Check — Verify paren balance before tangling
4. No Direct .lisp Edits — All changes flow through Org
5. Code and Prose Together — Every block preceded by explanatory text

Violating these rules corrupts the skill loader and causes boot failure (as seen in the 2026-04-25 incident).

Agent Workflow

• Boot Sequence: Read AGENTS.md → query skills → verify git → read gtd.org
• Before Any Modification: Commit first (Commit Before Modify rule)
• Plan Mode: Draft PROTOCOL.md before complex implementations
• Testing: Run FiveAM test suite + chaos tests before marking task complete
• Completion: Update gtd.org, commit, sync with user

References

• opencortex repo: /home/user/memex/projects/opencortex
• Engineering Standards: /home/user/memex/projects/opencortex/skills/org-skill-engineering-standards.org
• Literate Programming: /home/user/memex/projects/opencortex/skills/org-skill-literate-programming.org
• Policy Skill: /home/user/memex/projects/opencortex/skills/org-skill-policy.org
• Roadmap: /home/user/memex/gtd.org
• README: /home/user/memex/projects/opencortex/README.org