DocuGraph AI Agent Guidelines & Protocol

AI Agent Guidelines & Protocol

This document establishes the operational protocol, architectural boundaries, and integration guidelines for AI coding agents (such as Claude Code, Cursor, Junie, and GitHub Copilot) interacting with the DocuGraph monorepo and Model Context Protocol (MCP) server.

The governing document for project scope, governance, and delivery phases is docs/00_MASTER_CONTEXT.md (MASTER-00). Where this document conflicts with MASTER-00, the latter prevails.

Operating Protocol for AI Agents

All AI agents operating within or alongside the DocuGraph codebase MUST adhere strictly to four mandatory rules:

Rule 1: Query MCP First Before Modifying Code

Before attempting implementation on any component or feature:

Execute the MCP tool get_task_context(taskId) specifying your target atomic ID (e.g. BE-01, FE-03).
Do NOT read the entire repository manually or load full documentation files into your prompt context.
Use only the localized context bundle returned by get_task_context to guide your code modifications.

Note (DEC-001 / MASTER-00): the DocuGraph MCP server does not exist yet — it is itself the Gate 0 deliverable (see MASTER-00). Until get_task_context is available, agents MUST read MASTER-00 and the localized atomic docs directly, respecting the phase field of each document.

Rule 2: Preserve YAML Frontmatter Headers

When creating, editing, or refactoring Markdown files within docs/:

Always preserve the exact YAML frontmatter header structure (id, title, type, status, tags, links).
Never strip or modify existing valid id values.
When creating a new file, assign an unused atomic ID following established naming patterns (US-XX, IX-XX, DS-XX, BE-XX, FE-XX, RF-XX, NFR-XX, SCHEMA-XX). Document types and the full methodology (roles, phases, templates) are defined in docs/00_METODOLOGIA.md (METODOLOGIA-00).

Rule 3: Enforce Atomic Referencing & DAG Linkage

When adding dependencies between documents:

Maintain depends_on (and related when applicable) in the links: block of the YAML frontmatter. depended_by is DERIVED from depends_on by the tool (downstream edges of the graph and impact analysis are computed from depends_on); do NOT hand-maintain it — explicit depended_by blocks are ignored by validation, so they cause no asymmetry warnings but also carry no meaning.
Use relative Markdown links in document body text referencing exact paths (e.g., [US-01](/n/us-01/)).
Ensure that the resulting reference graph forms a Directed Acyclic Graph (DAG). Do NOT create circular references.

Rule 4: Zero Content Duplication & Single Source of Truth

Never copy-paste specification text, API payload structures, or database schemas into multiple files:

Cite operationId definitions (e.g. loginUser) when referring to API endpoints; do NOT duplicate HTTP schemas in feature specs.
Cite relational tables (e.g. table: users) when referring to database schema; do NOT rewrite DDL in user stories or backend specs.
Refer to docs/00_BUSINESS_VISION.md (VISION-00) for business strategy and user personas.

Rule 5: KMP Library Discovery & Verification via klibs.io

When discovering, adding, or updating Kotlin dependencies for :docugraph-core or :docugraph-mcp:

Verify library coordinates, target platform support, and current stable versions via klibs.io (or https://klibs.io/ai).
Do NOT guess outdated package coordinates or use deprecated artifact group IDs.

Rule 6: Gate 0 Version Stack & Code Ownership

Kotlin Version: Maintain Kotlin 2.4.10 as the standard version in gradle/libs.versions.toml for Gate 0.
Code Proposing & Manual Transcription: The AI agent MUST present all code snippets, data models, and configurations in chat responses for the developer to review and transcribe manually. The AI agent MUST NOT create or edit source code files directly without explicit user request.

Rule 7: GitFlow & Logical Commit Granularity

GitFlow Branching: All work MUST be performed in dedicated branches (feature/<name>, bugfix/<name>) branching off develop.
Commit Granularity: Avoid excessive micro-commits. Group changes into 2 to 3 logical, self-contained commits following Conventional Commits (feat(...), fix(...), chore(...), docs(...)) where each commit compiles and passes tests independently.
Clean Integration: When merging feature branches into develop, use Squash Merge to maintain a concise, readable history on develop and main.

MCP Server Integration & Tool Matrix

The DocuGraph Kotlin MCP Server (:docugraph-mcp) provides eleven primary tools for AI agent assistance:

Tool Name	Parameters	Return Type	Primary Purpose
`get_task_context`	`taskId: String` `maxDepth: Int = 5` `contentMode: full or summary` `maxTokens: Int?`	`String` (Markdown Bundle)	Performs reverse topological traversal; full is the default (bounded), summary is explicit, and bodies respect an observable approximate budget weighted by depth.
`get_dependency_graph`	`nodeId: String` `depth: Int = 3`	`JSON` (Graph Tree)	Returns structured adjacency list of upstream dependencies and downstream dependents for visualization or deep analysis.
`upsert_document`	Document path, optional content (path-only), optional frontmatter	`JSON` (Write Result)	Creates or replaces Markdown (.md) and OpenAPI (.yaml/.yml); Markdown validates IDs, links, and DAG integrity. Omit `content` to have the server read the file from the workspace.
`upsert_batch`	`documents: Array`, `projectSlug: String?`	`JSON` (Batch Write Result)	Validates and writes interdependent documents as one coherent snapshot, with no partial writes on errors.
`update_frontmatter`	Document path, frontmatter fields	`JSON` (Write Result)	Updates selected frontmatter fields while preserving omitted fields and validating the graph.
`validate_traceability`	`workspacePath: String`	`JSON` (Validation Report)	Executes Tarjan’s cycle detection and link verification across all documentation nodes, returning errors, warnings, and missing frontmatters.
`lint_workspace`	`projectSlug: String?` `profile: advisory or strict`	`JSON` (Workspace Lint Report)	Read-only diagnostic separating structural integrity from convention advisories; always returns `mutated=false`.
`list_tasks`	`type: String?`, `status: String?` `includeDocuments: Boolean = false`	`JSON` (Task Status List)	Returns filters, workspace document/task counts, filtered tasks, and optional document metadata without Markdown bodies.
`get_acceptance_criteria`	`taskId: String`	`JSON` (Acceptance Criteria)	Extracts ordered, verifiable acceptance criteria from the task’s Markdown body.
`analyze_impact`	`taskId: String` `depth: Int = 5`	`JSON` (Impact Analysis)	Returns downstream affected nodes, critical paths, and an actionable change-impact summary.
`validate_document`	Document path, optional content (path-only), optional frontmatter	`JSON` (Validation Result)	Performs a read-only preflight of a Markdown candidate without writing it.

MCP Prompt Templates

AI agents or developer drivers should utilize standardized prompt structures when triggering high-level tasks via MCP:

Template 1: Task Implementation Directive (`prompt_implement_task`)

Role: AI Software Engineer
Context Bundle:
<INSERT OUTPUT FROM get_task_context(taskId)>

Directives:
1. Review the provided task spec (Target: {{taskId}}), upstream user stories, and API operation contracts.
2. Modify source files ONLY within the designated target module (e.g., `:docugraph-core` for graph logic or `:docugraph-mcp` for MCP behavior).
3. Do NOT duplicate code or modify unreferenced files.
4. Run project build and unit tests to verify implementation before completing.

Template 2: Traceability & Integrity Audit (`prompt_audit_traceability`)

Role: Documentation Integrity Auditor
Audit Report:
<INSERT OUTPUT FROM validate_traceability()>

Directives:
1. Analyze the reported validation errors (circular references, broken atomic IDs, unreferenced operationIds).
2. For circular dependencies: adjust frontmatter `depends_on` lists to restore an acyclic DAG.
3. For broken atomic links: correct relative file paths and frontmatter ID references.
4. Re-run `validate_traceability` to verify 100% clean report.

File Editing & Link Formatting Rules

AI agents editing documentation MUST use standard link syntaxes:

YAML Frontmatter Link Syntax:

links:
  depends_on: [VISION-00, US-01]   # fuente de verdad; depended_by se DERIVA de aquí
  related: [US-06]

Markdown Body Relative Link Syntax:

This feature implements [US-01](/n/us-01/) and relies on [table: users](/n/schema-01/#users).

Monorepo Boundaries & Safe Zones

When executing code tasks, AI agents MUST observe module boundaries:

Core Logic & Parsing: Edit :docugraph-core only for YAML frontmatter parser, graph algorithms, or DAG validation changes.
Reading surfaces: The active project has no client application module. Use Obsidian over the Git clone, Gitea for controlled web review/editing, and the MkDocs viewer for read-only browsing (see ROADMAP-00 Nivel 4). Historical FE-XX specifications are catalog artifacts only.
MCP Server: Edit :docugraph-mcp only for MCP resources, tools, transports (Stdio/SSE), or SDK integration. Remote transport (SSE/HTTP) is the active workstream for the self-hosted Oracle setup (DEC-013).
Backend Services: :docugraph-backend is not part of the active self-hosted implementation; its BE-XX specifications remain historical catalog artifacts.
Documentation & Research: Edit docs/ and research/ only for specification, governance, and research artifacts (hypotheses, experiments, metrics, decisions). Scope and phases are governed by MASTER-00.

Research & Validation Zone

DocuGraph is currently treated as the driver’s personal tool on top of validated technical foundations; the Shipaton 2026 delivery objective is frozen (DEC-011). Work is guided by the ordered roadmap docs/04_ROADMAP.md (ROADMAP-00) — from foundations to advanced. Since DEC-013 the architecture is self-hosted and free: Markdown + git as source of truth, Obsidian as local reading surface, agents writing via MCP, and an Oracle Always Free instance hosting the remote MCP (SSE/HTTP), Gitea, and a web viewer. Research artifacts live under research/:

research/00_RESEARCH_PLAN.md (RES-00) — Research plan and delivery sequence.
research/01_RESEARCH_QUESTIONS.md (RES-01) — RQ01–RQ12.
research/02_HYPOTHESES.md (RES-02) — H01–H14 (all SIN_PROBAR).
research/03_METRICS.md (RES-03) — Evaluation metrics.
research/experiments/EXP-01_recuperacion_contexto.md (EXP-01) — First mandatory experiment.
research/99_DECISION_LOG.md (DEC-LOG) — Decision register.

No hypothesis changes state without evidence; no phase is implemented without its gate approved (§15 of MASTER-00).

Traceability Index

Upstream Dependencies:
- README.md (README) — Monorepo Architecture & Atomic Methodology.
- docs/00_MASTER_CONTEXT.md (MASTER-00) — Governing Master Context, Governance & Delivery Phases.
- docs/00_METODOLOGIA.md (METODOLOGIA-00) — Driver’s Documentation Methodology (phases, roles, templates, RF-XX/DS-XX/NFR-XX conventions).
Downstream Linkages:
- docs/user_stories/US-04_get_task_context.md (US-04) — MCP Context Bundle Extraction.
- docs/user_stories/US-05_validate_traceability.md (US-05) — Automated Traceability Validation.
Usage Linkage:
- docs/usage/FLUJO_STDIO_AGENTES.md (USO-01) — Daily STDIO workflow for Claude Code, Codex, and Antigravity CLI.
Related Documents:
- docs/00_BUSINESS_VISION.md (VISION-00) — Product Vision & Personas (Proposal).
- research/00_RESEARCH_PLAN.md (RES-00) — Research Plan.
Task Templates:
- docs/templates/PLANTILLA_US.md (TPL-US) — User story template.
- docs/templates/PLANTILLA_IX.md (TPL-IX) — Interaction flow template.
- docs/templates/PLANTILLA_DS.md (TPL-DS) — Design specification template.
- docs/templates/PLANTILLA_BE.md (TPL-BE) — Backend task template.
- docs/templates/PLANTILLA_FE.md (TPL-FE) — Frontend task template.
- docs/templates/CRONOGRAMA.md (TPL-CRON) — Lightweight graph schedule convention.