Saltar a contenido

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: - Update the links: block in the YAML frontmatter of both the dependent document (depends_on) and the target document (depended_by). - Use relative Markdown links in document body text referencing exact paths (e.g., [US-01](docs/user_stories/US-01_login.md)). - 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 eight primary tools for AI agent assistance:

Tool Name Parameters Return Type Primary Purpose
get_task_context taskId: String
maxDepth: Int = 5		 String (Markdown Bundle) Performs reverse topological traversal from taskId to extract upstream user stories, API contracts, backend/frontend specs, and DB tables.
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, content, optional frontmatter JSON (Write Result) Creates or replaces Markdown (.md) and OpenAPI (.yaml/.yml); Markdown validates IDs, links, and DAG integrity.
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.
list_tasks type: String?, status: String? JSON (Task Status List) Lists task nodes with their id, path, type, and status, optionally filtered by type or status.
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.

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.

AI agents editing documentation MUST use standard link syntaxes:

  • YAML Frontmatter Link Syntax: 
    links:
  depends_on: [VISION-00, US-01]
  depended_by: [BE-01, FE-01]
  related: [US-06]
  • Markdown Body Relative Link Syntax: 
    This feature implements [US-01](docs/user_stories/US-01_login.md) and relies on [table: users](docs/domain/01_DATABASE_SCHEMA.md#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