amr/memex
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
44a1b43cba33051519c8b51b88cb537e30fa8d80
memex/.opencode/AGENTS.md
Amr Gharbeia f858b86b64 docs(AGENTS): add utils-lisp mandate for Lisp structural operations 
- NEW: REPL-first workflow requirement
- NEW: Must use utils-lisp functions for any .lisp work
- NEW: Never use edit tool on .lisp files directly
- NEW: Post-task verification: REPL verified + utils-lisp used
2026-04-30 11:17:45 -04:00

7.1 KiB
Raw Blame History

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)

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

Phase C: Build (Implementation)

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

Phase D: Validate (Proof)

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

Phase E: Document (Audit Trail)

  1. Decision Audit Trail — Document root cause, options, tradeoffs, and rationale
  2. Stop-and-Wait — For major changes, propose strategy, state "Waiting for user feedback," yield turn
  3. 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

Self-Enforcement Checklist

This agent MUST verify these conditions before, during, and after each task. Violation is a bug, not a suggestion.

Before Any Task (Gate)

  • Git clean — Working tree must be clean before modification
  • Skill query — Check if relevant skill exists in /home/user/memex/projects/opencortex/skills/
  • Skill read — If found, read the skill's org file before proceeding
  • GTD read — Check gtd.org for current task context

During Task (Literate Programming)

  • REPL-first workflow — Explore in REPL before writing code
  • Utils-lisp for structural ops — Use these functions for any .lisp work:
    • utils-lisp-structural-extract — Extract function definitions
    • utils-lisp-structural-inject — Inject forms into definitions
    • utils-lisp-structural-wrap — Wrap code in let/progn
    • utils-lisp-validate — Validate code before commit
    • repl-eval — Test code in REPL
    • repl-inspect — Inspect variables/functions
  • Never use edit tool on .lisp — Only edit .org files; never touch generated .lisp directly
  • One function per block — Each #+begin_src block contains exactly one definition
  • Prose before code — Every block preceded by explanatory text
  • Prose includes: What the function does, arguments, return value, rationale
  • Evaluate each block — Verify the block compiles/evaluates correctly
  • Paren balance — Check balanced parentheses before tangling

After Task (Validation)

  • REPL verified — Code tested in REPL before commit (not just text edit)
  • Utils-lisp used — Confirmed structural operations went through utils-lisp
  • Tests pass — Run full test suite; 100% pass required
  • Chaos tier 1 — Deterministic regression tests pass
  • No artifacts — No orphaned .bak, .log, .tmp, or untracked test files
  • Commit — Stage and commit changes with descriptive message
  • GTD update — Update gtd.org with completed task state

For OpenCortex Work Specifically

Reference authoritative skill files:

  • Engineering Standards: projects/opencortex/skills/org-skill-engineering-standards.org
  • Literate Programming: projects/opencortex/skills/org-skill-literate-programming.org
  • Policy: projects/opencortex/skills/org-skill-policy.org

The summaries in this file are reminders; the skill org files are authoritative.

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
Reference in New Issue View Git Blame Copy Permalink