🤖 Project Rules and AI Agent Context

This file contains the development guidelines, architecture conventions, and token optimization rules for AI agents assisting in this repository.

📐 0. Living Blueprint-as-Code (LBaC) Framework

MANDATORY FIRST STEP: Before initiating any development task, you must read the Master Blueprint of the project: 📖 docs/LBAC.md

The Master Blueprint is the Single Source of Truth (SSoT) of this repository. It links to all Feature Maps (As-Is/To-Be), Architectural Decision Records (ADRs), Business Rules, Sprint Schedules, and BDD Acceptance Criteria.

Mandatory workflow for any coding task:

1. Read the relevant feature map in docs/features/.
2. Check the technical debt log in docs/technical_debt.md for any related cleanups.
3. Respect the technical constraints defined in this file.
4. Do not create models, screens, classes, or database tables without first verifying if they already exist in the codebase.
5. Before coding: Create an Implementation Plan in docs/implementations/ using Template 4 from docs/LBAC.md. Present it to the user and wait for explicit approval.
6. After coding: Complete a Verification Report using Template 5 from docs/LBAC.md, confirming all BDD scenarios from the feature map pass successfully.
7. Log any technical debt or significant architectural decisions found during development.

🔄 AI Auto-Documentation & Synchronization Rules:

• Traceability Updates: When creating or renaming any source file, search all markdown files in docs/ and update their file:/// links to match the new paths.
• Technical Debt Sync: When completing a task that resolves a task listed in docs/technical_debt.md, automatically: (1) move the task from "Pending Tasks" to "Resolved Tasks" with a resolution summary, AND (2) remove or annotate the corresponding entry in the Feature Map's ## 🛠️ Related Technical Debt section.
• Sprint History Sync: Upon completing a story, update docs/planning/sprint_history.md to mark the story as completed ([x]) and record any key architectural decisions made. When closing a sprint, also update the sprint table in docs/planning/proposal_planning_qa.md.
• Blueprint Index Sync: When creating a new Feature Map, ADR, or Business Rule file, automatically add it to the corresponding index table in docs/LBAC.md.
• ADR Status Sync: When a decision is superseded by a new ADR, update the old ADR's Status field to Superseded by ADR-YYY and update its row in the docs/LBAC.md index accordingly.
• Stale Verification Report Alert: If a Feature Map's "To-Be" section is modified after a Verification Report already exists for that story, add a ⚠️ Requires Re-verification warning to the top of the existing Verification Report in docs/implementations/.
• Gateway File Consistency: When a core workflow rule in this file (.agents/AGENTS.md) changes significantly, propagate the change summary to the gateway files: CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/lbac_rules.mdc, and .windsurfrules.

🎯 1. Project Purpose & Core Domain

• Project Name: Living Blueprint-as-Code (LBaC) — Template Repository
• Purpose: A methodology and repository template that turns product specs, architectural decisions, roadmaps, and QA strategies into active, versioned code documents. Acts as the Single Source of Truth (SSoT) for human developers and AI coding agents to align on a project's state without ambiguity.
• Core Tech Stack: Markdown (documentation), Git (version control). Agnostic by design — the framework can wrap any application tech stack (e.g., Node.js/Express, Spring Boot, Flutter, Next.js, PostgreSQL).

⚡ 2. Rules for Token and Credit Optimization (Efficient Consumption)

To save context tokens, minimize API costs, and improve response speed, the AI agent must strictly comply with:

1. Ultra-Concise Responses: Get straight to the point. Avoid long intros, repetitive greetings, or generic conclusions. Assume the user is an experienced developer.
2. Localized Edits (No Full Rewrites): When suggesting code changes, never output the entire file. Provide specific code snippets, replacement blocks, or standard unified diffs.
3. Do Not Explain the Obvious: Do not explain language syntax, standard library features, or basic framework architecture concepts unless explicitly asked.
4. Surgical Search: Use search and read tools selectively. Read only the line ranges you need.
5. No Placeholders: Write complete code segments for implementation. Do not use comments like // TODO: implement this later unless specifically directed.

🛠️ 3. Technical Constraints & Conventions

• File Linking: In your responses, always format file paths as clickable links using the file:/// scheme and forward slashes (e.g., README.md).
• Documentation Language Rules:
  • English: docs/LBAC.md, docs/features/*.md, docs/technical_debt.md, docs/planning/sprint_history.md, .agents/AGENTS.md — these files are consumed directly by the AI to keep token tokenization efficient (~15-25% savings).
  • Local Language (e.g., Español): docs/business/*.md, docs/planning/*_qa.md, docs/adr/*.md — these files are mostly consumed by human stakeholders.
• Architecture Flow: Feature Map ──> Implementation Plan ──> Source Code ──> Verification Report ──> Sprint History & Technical Debt Register