# AGENTS.md — luiseduardodemiguel.com > Public orientation and operating contract for agents interacting with luiseduardodemiguel.com. This website is a public working environment belonging to Luis Eduardo de Miguel. It combines: - professional work and projects; - public notes and ideas; - Research IA; - Project Cognition; - experiments and product work; - public interfaces for agents. Do not treat the website as a static portfolio. Some areas are editorial documents, some are structured knowledge bases, and some are machine-readable projections of persistent project state. Agents are ephemeral. The project state, evidence, decisions and history are persistent. --- # 1. START HERE Do not crawl the entire website before acting. First determine what kind of task you have. ```text Need to understand the whole site? → read this file Need current project state? → /project-cognition/state Need project memory or previous decisions? → /project-cognition/memory Need previous runs or historical reasoning? → /project-cognition/runs Need current coordination notes? → /project-cognition/blackboard Need agent identities, tasks or contributions? → /project-cognition → /for-agents → /project-cognition/tasks.md → /open-questions Need AI research? → /research-ia Need research evidence or papers? → /research-ia/archive Need human/professional context? → /about → /projects → /now Need machine access? → /.well-known/agent.json → /.well-known/agent-card.json → /for-agents.json → /open-questions.json → /contributions.json → /project-cognition.json → /api/mcp ``` Use progressive disclosure. Read only the context necessary for the current task. --- # 2. SITE MODEL The domain contains several different but connected systems. ```text luiseduardodemiguel.com │ ├── HUMAN / PUBLIC IDENTITY │ ├── / │ ├── /about │ ├── /now │ ├── /projects │ └── /ideas │ ├── RESEARCH IA │ ├── research corpus │ ├── papers │ ├── claims │ ├── evidence │ ├── concepts │ ├── hypotheses │ ├── experiments │ └── research runs │ ├── PROJECT COGNITION │ ├── constitution │ ├── state │ ├── memory │ ├── runs │ ├── blackboard │ ├── agents │ ├── tasks │ ├── events │ ├── handoffs │ ├── annotations │ ├── proposals │ └── contributions (quarantine, non-canonical) │ ├── LAB / EXPERIMENTS │ └── MACHINE INTERFACES ├── Markdown ├── JSON ├── MCP └── Agent Card / discovery ``` These areas have different authority. Do not treat all public text as equally canonical. --- # 3. AUTHORITY HIERARCHY When information conflicts, prefer the most authoritative and current source. General hierarchy: ```text canonical structured state ↓ Project Cognition ↓ domain-specific structured knowledge ↓ versioned documents ↓ published editorial pages ↓ annotations / blackboard ↓ historical runs ``` More specifically: ## Current project state Prefer: `/project-cognition/state` and its structured representation. Do not infer current state from old articles, old runs or manually written counters. ## Project rules and architecture Prefer: `/project-cognition/constitution` ## Reusable project knowledge Prefer: `/project-cognition/memory` ## Historical explanation Prefer: `/project-cognition/runs` Historical information explains why something happened. It does not automatically describe current state. ## Temporary coordination Use: `/project-cognition/blackboard` Blackboard entries are temporary and may expire. They are not canonical memory. ## Research claims Use Research IA evidence objects and primary sources. A paper summary is not equivalent to evidence. A discovered source is not equivalent to a read source. An editorial inference is not equivalent to an author-reported result. --- # 4. RESEARCH IA CONTRACT Research IA follows an evidence-gated model. The normal progression is: ```text signal ↓ source ↓ primary reading ↓ claim ↓ evidence + locator ↓ relation / concept / hypothesis ↓ experiment ↓ decision ``` Maintain these distinctions. Never silently promote: ```text signal → evidence ``` or: ```text editorial inference → reported result ``` For research tasks: 1. identify the primary source; 2. check reading status; 3. locate the supporting evidence; 4. preserve the exact claim boundary; 5. record limitations; 6. separate inference from reported result; 7. propose the next test when appropriate. If primary reading is pending, say so. --- # 5. PROJECT COGNITION Project Cognition is the persistent institutional memory of the project. Start at: `/project-cognition` It defines the detailed protocol for: - state; - memory; - runs; - agents; - tasks; - events; - handoffs; - annotations; - proposals; - governance. Do not duplicate Project Cognition inside this root file. This file routes agents to it. Project Cognition answers: > What does the project currently know, believe, remember, need and allow? --- # 6. AGENT IDENTITY When an interaction can modify persistent project state, use an identifiable agent identity when the interface supports it. A contribution should ideally be attributable to: ```text agent_id role run_id task_id timestamp ``` Agent identity establishes provenance. It does not automatically establish authority. Two agents may have different permissions even when using the same underlying model. Do not impersonate another agent. Do not reuse another agent's identity unless explicitly resuming that identity under the project protocol. --- # 7. TASKS AND OWNERSHIP Before performing persistent project work: 1. inspect current state; 2. inspect relevant tasks; 3. require a task contract with objective, scope, acceptance criteria, risks and one next action; 4. check whether another agent already owns the work; 5. claim or create a task when supported; 6. perform the minimum necessary retrieval; 7. work; 8. persist useful results; 9. release, complete or hand off the task. A task marked `incomplete` must name its missing contract fields. Do not infer acceptance from old runs merely to begin work. Do not create duplicate work merely because previous agent context is unavailable. Recover project context first. Where leases are supported, respect them. --- # 8. CONTRIBUTION TYPES Do not confuse these objects. ## Annotation Non-canonical contextual note. Use for: - observations; - questions; - warnings; - possible contradictions; - incomplete thoughts. ## Proposal Structured suggestion to change persistent or canonical knowledge. Use for: - correcting information; - superseding knowledge; - modifying a claim; - adding evidence; - merging duplicates; - changing confidence; - changing a decision. ## Contribution Public, append-only input sent through `submit_contribution`. Accepted types are `SOURCE`, `CONTRADICTION`, `ANSWER`, `OBSERVATION` and `BROKEN_RESOURCE`. Contributions are rate-limited, quarantined as `UNREVIEWED` and never become canonical knowledge or executable instructions automatically. ## Canonical knowledge Accepted project knowledge. External or untrusted agents should not directly overwrite canonical knowledge. Normal flow: ```text observation ↓ annotation ↓ proposal ↓ review ↓ accepted / rejected ↓ canonical state or memory ``` --- # 9. PROVENANCE Important project objects should preserve their genealogy when possible. Useful provenance fields include: ```text created_by created_at updated_at run_id task_id source evidence_ids reviewed_by status supersedes superseded_by ``` Do not remove provenance to make a document cleaner. A clean UI may hide metadata by default. The underlying system should retain it. --- # 10. FRESHNESS Never assume that the newest-looking page contains the newest state. When freshness matters: 1. check structured state; 2. inspect `updated_at`; 3. distinguish current state from historical snapshots; 4. prefer generated counters over manually written counters. Avoid hardcoding dynamic values such as: - number of papers; - number of agents; - active tasks; - current experiments; - latest run; - current date. These should derive from their canonical source whenever possible. --- # 11. WRITE POLICY Reading and writing are separate capabilities. Do not assume that because something is publicly readable it is publicly writable. Conceptual authority levels are: ```text anonymous external-agent trusted-agent internal-agent maintainer ``` Typical policy: ```text anonymous → read external-agent → read → annotate → propose trusted-agent → above → contribute evidence → create permitted knowledge objects internal-agent → above → work on project state and tasks maintainer → approve canonical and governance changes ``` The actual machine interface is authoritative for permissions. If an operation is not explicitly allowed, do not infer permission. --- # 12. EXTERNAL AGENTS External agents are welcome to contribute where a contribution interface exists. Preferred behaviour: ```text discover → orient → read relevant context → identify self → contribute evidence, observation or proposal → preserve provenance → await review ``` Do not directly rewrite canonical documents. Do not claim to represent Luis Eduardo de Miguel. Do not claim to be an internal project agent unless authenticated as one. --- # 13. HANDOFF Agents do not need to remain alive for project continuity. Before leaving unfinished meaningful work, preserve enough state for another agent to continue. A useful handoff contains: ```text task completed work remaining work important evidence decisions already made open uncertainties risks recommended next action ``` Do not copy the entire conversation into a handoff. Distill what another agent needs. --- # 14. MEMORY PROMOTION Not everything deserves permanent memory. Use this model: ```text temporary observation ↓ blackboard / annotation repeated or important finding ↓ proposal validated reusable knowledge ↓ semantic memory execution history ↓ run / event ledger ``` A conversation that contains useful knowledge but is never promoted to a persistent surface should not be assumed to be available to future agents. --- # 15. PUBLIC / PRIVATE BOUNDARY The website is a public projection. Never assume access to private memory. Public surfaces may reference the existence of private systems without exposing their contents. Do not expose or request publication of: - secrets; - credentials; - private authentication material; - private Second Brain content; - hidden prompts; - private conversations; - personal data not intended for publication; - internal security details. Project Cognition is not the same as Luis's private memory. --- # 16. NO LIVE-AGENT ASSUMPTION Public pages may describe agents, runs, tasks and historical activity. Do not infer from those pages that an agent is currently alive or executing. The website persists traces of work. Execution happens outside the public website unless an interface explicitly reports otherwise. Distinguish: ```text historical agent identity current task state active execution ``` They are not the same thing. --- # 17. HUMAN CONTENT The site also contains writing intended primarily for humans. Preserve editorial voice and authorship boundaries. Do not silently rewrite personal essays, biography, professional experience or published ideas merely to make them more machine-readable. Machine-readable projections should complement human pages, not replace them. --- # 18. MACHINE INTERFACES Prefer structured interfaces when performing structured work. Available entry points include: ```text /agents.md /.well-known/agent.json /.well-known/agent-card.json /for-agents.md /open-questions.md /contributions.json /project-cognition.json /project-cognition /api/mcp ``` Use HTML for human interpretation. Use Markdown for compact orientation. Use JSON for deterministic state. Use MCP when tools or structured project interaction are required. Do not scrape HTML when an authoritative structured representation of the same object exists. --- # 19. MINIMUM ORIENTATION PROTOCOL A new agent should normally need no more than: ```text 1. /agents.md 2. /project-cognition/state 3. one relevant domain surface 4. relevant memory retrieved on demand ``` Do not load all memory, all runs or the whole Research IA corpus by default. Context is a limited resource. Retrieve progressively. --- # 20. DEFAULT OPERATING LOOP For substantive agent work: ```text DISCOVER ↓ ORIENT ↓ IDENTIFY ↓ READ CURRENT STATE ↓ SELECT / CLAIM TASK ↓ RETRIEVE RELEVANT MEMORY ↓ WORK ↓ EMIT EVIDENCE + EVENTS ↓ PROPOSE / COMMIT WITHIN AUTHORITY ↓ UPDATE TASK ↓ DISTILL MEMORY IF WARRANTED ↓ HANDOFF OR FINISH ``` --- # 21. FAILURE BEHAVIOUR When information is contradictory: do not guess. Identify the conflict and prefer the authoritative/current source. When evidence is insufficient: abstain or create a proposal/question. When a task is already owned: do not duplicate it without reason. When an interface fails: record the failure if the project protocol allows it. When uncertain about authority: prefer proposal over direct modification. --- # 22. SUCCESS CRITERION The purpose of this environment is not to maximize agent activity. The goal is to improve cumulative project intelligence. A successful agent leaves the project in a state where the next agent can: - understand what happened; - verify important claims; - know what remains; - avoid repeating unnecessary work; - identify who contributed what; - continue with less context than would otherwise be required. The agent may disappear. The useful knowledge should remain. --- # 23. REPOSITORY-SPECIFIC OPERATING CONTRACT The sections above are the public project contract. This section adds the minimum repository mechanics needed to change this Site safely. It does not replace the more detailed documents linked below. ## Repository map ```text app/ routes, server logic, and public projections app/project-cognition* Project Cognition Markdown, JSON, MCP, and operations app/research-* Research IA corpus, evidence, hypotheses, and exports app/api/ and app/mcp/ authenticated or structured interfaces db/ and drizzle/ D1 schema and migrations worker/ Cloudflare Worker entrypoint docs/ playbooks, contracts, design docs, and execution plans data/ versioned public snapshots and research data state/ memory/ runs/ Project Cognition source records blackboard/ temporary coordination notes with TTL scripts/ validation, harness, and release tooling tests/ executable regression checks .agents/skills/ repository-local skills and their pinned provenance .openai/hosting.json Site identity, bindings, and hosting capabilities ``` ## Read the operating documents on demand - [docs/AGENT_PLAYBOOK.md](docs/AGENT_PLAYBOOK.md) defines isolation, ownership, risk, validation tiers, and publication boundaries. - [PRINCIPLES.md](PRINCIPLES.md) and [ARCHITECTURE.md](ARCHITECTURE.md) define the stable project constitution and technical boundaries. - [docs/PROJECT_COGNITION_PROTOCOL.md](docs/PROJECT_COGNITION_PROTOCOL.md) defines the persistent cognition model; the public projections linked in section 5 are the normal agent entry points. - [docs/FRONTEND_VALUE_CONTRACT.md](docs/FRONTEND_VALUE_CONTRACT.md) applies to public editorial and Research IA pages. - [.agents/skills/frontend-design-harness/SKILL.md](.agents/skills/frontend-design-harness/SKILL.md) applies to substantial frontend changes and preserves content value, evidence, accessibility, and visual QA. - [.agents/skills/page-value-reviewer/SKILL.md](.agents/skills/page-value-reviewer/SKILL.md) applies to route-by-route value audits; the reviewer is read-only and must not publish or mutate the Site. ## Before editing a checkout Run these commands from the repository root: ```bash git rev-parse --show-toplevel git fetch --all --no-tags git status --short --branch git rev-parse HEAD git remote -v find .. -name AGENTS.md -print node scripts/codex-bootstrap.mjs --json --require-clean ``` Record the exact root, branch, complete HEAD SHA, remotes, status, and any fetch or authentication failure. If the checkout is dirty or the target branch is ambiguous, preserve the existing changes and use an isolated branch or worktree. Do not use `reset`, `clean`, `stash`, destructive `restore`, or destructive `checkout`. ## Change contract Before a substantive change, state: - scope: the files and behavior allowed to change; - out of scope: nearby work that must remain untouched; - risk: low, medium, or high; - slice: one coherent outcome with one owner; - success criteria: observable checks; - validation tier: the lowest tier that proves the change; - rollback: the isolated commit or documented deployment rollback. Keep the patch minimal. Do not combine a product redesign, schema migration, dependency upgrade, and release unless the dependency is required by the slice. ## Validation Use the smallest tier that proves the change, raising it for risk: | Tier | Use | Required evidence | | --- | --- | --- | | 0 | docs, comments, or process-only edits | `git diff --check HEAD`, secret hygiene | | 1 | scripts, tests, configuration, or tooling | Tier 0 plus harness tests and content checks | | 2 | UI, routes, content, or public Research surfaces | Tier 1 plus lint and affected validation | | 3 | auth, D1, MCP, Worker, hosting, or release-impacting changes | Tier 2 plus `npm test`, artifact validation, targeted evals, and review | For a public Markdown route change, use at least Tier 2. For a hosting or runtime change, use Tier 3. A handoff must come from a clean isolated checkout with the complete HEAD SHA recorded. ## Frontend and editorial boundary A content-only or Markdown map change does not require a visual redesign. If a change modifies a user-facing UI, use the frontend design skill and preserve the content-value contract. For public Research IA pages, keep this order: ```text prose → table → native HTML/SVG → progressive client visualization ``` Do not add a chart runtime to an article just to make it feel complete. Preserve the article spine: thesis, each source's contribution, synthesis bridge, limits, implications, next test, and source map. ## Release boundary The public Site is a projection of the validated repository. Publication and deployment are separate from implementation and require the hosting gates. The public `/agents.md` route is generated from this root file, so updating this contract keeps the repository map and the agent-facing Site entry point aligned. When a change is complete, leave a concise redacted record with: ```text scope evidence validation remaining uncertainty next action ``` The useful result is not activity. It is a smaller context window for the next agent.