🏗️ Living Blueprint-as-Code (LBaC) — Project Template

This template provides a lightweight, standard framework to implement Living Blueprint-as-Code (LBaC) in any software repository.

LBaC is a methodology designed to unblock and accelerate software development by keeping product specs, technical design decisions, roadmaps, and testing strategies directly in the repository as active, versioned code documents.

It acts as the Single Source of Truth (SSoT) for human developers and AI coding agents.

---

🚀 Key Benefits

1. AI Alignment: Large Language Models (LLMs) and AI coding assistants perform significantly better when given highly structured, repository-specific context instead of guessing architecture or conventions.
2. Zero-Stale Docs: Since documentation lives in Git alongside the code, it evolves naturally via Pull Requests. If a feature changes, its specification document is updated in the same commit.
3. Executable Requirements: By framing requirements in BDD (Behavior-Driven Development) scenarios, you establish a direct bridge between business intent, technical implementation, and QA tests.

---

📂 Project Structure

Copy this folder structure directly into your new repository:

your-project/
├── .agents/
│   └── AGENTS.md           <-- System prompt / instruction rules for AI coding assistants
│
└── docs/
    ├── LBAC.md             <-- The Master Blueprint (Index of all specs & templates)
    ├── technical_debt.md   <-- Live register of technical debt and cleanups
    │
    ├── features/           <-- Feature Maps (As-Is / To-Be / BDD criteria per module)
    │   └── example_feature.md
    │
    ├── adr/                <-- Architectural Decision Records (ADRs)
    │   └── ADR-001_example.md
    │
    ├── business/           <-- Commercial rules, pricing models, pricing policies
    │   └── business_model.md
    │
    ├── implementations/    <-- Implementation Plans & Verification Reports per user story
    │   └── US-001_example_plan.md
    │
    ├── planning/           <-- Roadmaps, release schedules, and Sprint history
    │   └── sprint_history.md
    │
    └── templates/          <-- Clean templates for maps, plans, and reports
        ├── feature_map_template.md
        ├── adr_template.md
        ├── user_story_template.md
        ├── implementation_plan_template.md
        └── verification_report_template.md

---

🔄 LBaC Mandatory Workflow

Every time you build a new feature or resolve a ticket, follow this 4-step lifecycle:

  1. READ SPECS           2. PLAN FIRST            3. WRITE CODE          4. VERIFY BDD
 ┌──────────────┐        ┌──────────────┐         ┌──────────────┐       ┌──────────────┐
 │ Read relevant│        │ Create Impl  │         │ Code in isolated│     │ Complete the │
 │ Feature Map  │ ──────►│ Plan in      │ ───────►│ dev branch/   │ ───► │ Verification │
 │ and rules    │        │ docs/impl/   │         │ environment  │       │ Report       │
 └──────────────┘        └──────────────┘         └──────────────┘       └──────────────┘

1. Read Specs: Check the feature map in docs/features/ to understand the As-Is (current behavior) and To-Be (desired target). Check the technical_debt.md to see if there is any debt you should clean up in the process.
2. Plan First: Create an Implementation Plan (using the template) detailing exactly which files will be created, modified, or deleted. Obtain human developer approval.
3. Write Code: Implement the logic in an isolated development environment or local branch.
4. Verify BDD: Run the tests and complete the Verification Report confirming that all BDD scenarios pass and match the client's expectations before merging.

---

⚙️ How to Initialize

Follow these steps to adopt LBaC in your own project from scratch:

Step 1 — Copy the template

# Copy the entire repo into the root of your project
cp -r lbac-template/. your-project/

Step 2 — Personalize the AI instructions (SSoT)
Open .agents/AGENTS.md and fill in section §1. Project Purpose:

Project Name: <Your Project Name>
Purpose:      <One-line elevator pitch>
Tech Stack:   <e.g., Next.js, Node.js, PostgreSQL, Docker>
Architecture Flow: <e.g., Controller → Service → Repository → Database>

Step 3 — Update the gateway files for each AI tool
Edit the Project and Tech Stack block in each of these files (the workflow rules can stay as-is):

• CLAUDE.md
• .github/copilot-instructions.md
• .cursor/rules/lbac_rules.mdc
• .windsurfrules

Step 4 — Customize the Master Blueprint
Open docs/LBAC.md and clear the example rows in the index tables. Add your own modules as you create their Feature Maps.

Step 5 — Delete the example files
These files are included only as a reference. Remove them before your first real commit:

docs/features/example_feature.md
docs/adr/ADR-001_architecture_standard.md
docs/business/pricing_rules.md
docs/implementations/US-001_example_story.md
docs/implementations/US-001_verification_report.md

Step 6 — Start your first Feature Map
Use docs/templates/feature_map_template.md to create your first real module spec in docs/features/. Then follow the LBaC Mandatory Workflow.

---

🤖 AI Assistant Coverage

This template includes gateway instruction files for each major AI coding assistant. Each file points back to the central .agents/AGENTS.md to keep a single source of truth.

AI Tool	Instruction File	Auto-Detected?
Antigravity (Google DeepMind)	.agents/AGENTS.md	✅
GitHub Copilot	.github/copilot-instructions.md	✅
Claude (Anthropic)	CLAUDE.md	✅
Cursor	.cursor/rules/lbac_rules.mdc	✅
Windsurf	.windsurfrules	✅

Note for new projects: When adopting LBaC in your own repository, update each gateway file's Project, Purpose, and Tech Stack sections with your project-specific data. The workflow and hard rules can remain as-is.