{"id":28224829,"url":"https://github.com/dasiths/vibecodingbreadcrumbdemo","last_synced_at":"2026-02-09T22:32:34.824Z","repository":{"id":287580097,"uuid":"965152413","full_name":"dasiths/VibeCodingBreadcrumbDemo","owner":"dasiths","description":"This repository serves as an example showcasing a structured approach for collaborating with AI agents (like GitHub Copilot Chat or similar LLM-based assistants) during software development.","archived":false,"fork":false,"pushed_at":"2025-06-04T14:28:21.000Z","size":2055,"stargazers_count":13,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-22T08:22:55.408Z","etag":null,"topics":["agent","breadcrumb","copilot","github-copilot","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dasiths.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-12T14:28:08.000Z","updated_at":"2025-08-11T06:57:24.000Z","dependencies_parsed_at":"2025-06-04T15:42:20.889Z","dependency_job_id":null,"html_url":"https://github.com/dasiths/VibeCodingBreadcrumbDemo","commit_stats":null,"previous_names":["dasiths/vibecodingbreadcrumbdemo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dasiths/VibeCodingBreadcrumbDemo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasiths%2FVibeCodingBreadcrumbDemo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasiths%2FVibeCodingBreadcrumbDemo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasiths%2FVibeCodingBreadcrumbDemo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasiths%2FVibeCodingBreadcrumbDemo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dasiths","download_url":"https://codeload.github.com/dasiths/VibeCodingBreadcrumbDemo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasiths%2FVibeCodingBreadcrumbDemo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29283615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T21:57:15.303Z","status":"ssl_error","status_checked_at":"2026-02-09T21:57:11.537Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","breadcrumb","copilot","github-copilot","vibe-coding"],"created_at":"2025-05-18T10:08:26.964Z","updated_at":"2026-02-09T22:32:34.809Z","avatar_url":"https://github.com/dasiths.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Structured workflows for coding with AI agents using the Breadcrumb Protocol\n\n\u003cimg src=\"logo.png\" alt=\"Breadcrumb Protocol\" width=\"100px\"\u003e \n\nThe Breadcrumb Protocol is a structured workflow for collaborating with AI agents during software development. It centres around creating and maintaining shared documentation files (\"breadcrumbs\") that track each task's progress and serve as a single source of truth.\n\nThis protocol creates a traceable history of decisions and implementations, making code reviews easier and ensuring both parties maintain shared context throughout development tasks.\n\nThe Breadcrumb Protocol implements these themes through a simple yet powerful concept: a shared scratch pad that allows both the developer and AI to align their vision at all times. Each development task gets its own “breadcrumb” file - a single source of truth that tracks progress from requirements through implementation.\n\nYou can read more about it here \u003chttps://dasith.me/2025/04/02/vibe-coding-breadcrumbs/\u003e.\n\n## Overview\n\nThis repository serves as an example showcasing a structured approach for collaborating with AI agents (like GitHub Copilot Chat or similar LLM-based assistants) during software development. It provides a specific set of instructions, defined within this project, that guide the AI agent's behaviour to ensure clarity, maintain context, and produce well-documented changes.\n\nThe core idea is to establish a predictable and transparent workflow where the AI agent acts as a diligent collaborator, leveraging project-specific knowledge and adhering to a defined process for planning, implementation, and documentation.\n\n1. **Structured Planning \u0026 Task Management:** Breaking complex goals into well-defined phases and actionable tasks with clear success criteria. This approach provides AI with clear, manageable units of work, reducing ambiguity and allowing it to focus its generation capabilities effectively.\n\n2. **Centralized \u0026 Accessible Knowledge Context:** Establishing designated locations with consistent naming conventions for project-related information, including domain knowledge and specifications. This makes it easier for the AI to access and utilize the “ground truth” of your project.\n\n3. **Living Documentation \u0026 Shared Understanding:** Maintaining a dynamic, collaborative record of the development process that acts as an external, persistent memory for both the developer and the AI assistant.\n\n## Development Workflow\n\n![Development workflow](image.png)\n\n[*Assumes spec is already created...*]\n1. Prompt the agent: *[Instructions file has details on domain knowledge and specs]*\n    ```text\n    Help me create a aspnet api project according to the spec. I don't need the database context just yet so we can return a hardcoded response from the request processor.\n\n    Location: src/backend/\n    Solution name: CarRental\n    Project name: CarRental.Api\n\n    Use dotnet 9. Use this document on instructions of how to add swagger/openapi endpoint. https://devblogs.microsoft.com/dotnet/dotnet9-openapi/\n    ```\n2. Follow conversation with agent.\n    - Provide input, confirm plans.\n    - If the agent in veering off path, pause, give it instructions and ask to update the breadcrumb with the new context before continuing.\n    - You also have the opportunity to update breadcrumb yourself and start a new conversation with the agent and continue from where it left off.\n3. Results in breadcrumb: [2025-04-13-1723-car-rental-api-setup.md](.github/.copilot/breadcrumbs/2025-04-13-1723-car-rental-api-setup.md)\n\n### Demo \n[![Demo](http://img.youtube.com/vi/etYG-6-9Mlk/0.jpg)](http://www.youtube.com/watch?v=etYG-6-9Mlk \"Example\")\n\n## How It Works: Agent Instructions\n\nThe AI agent operating within this repository is expected to follow a specific set of rules and protocols defined in its prompt (often configured within the AI tool's settings or provided at the start of an interaction). \n\nSee the [full prompt](.github/copilot-instructions.md) for more details.\n\nKey aspects of these instructions include:\n\n1.  **Domain Knowledge Integration:**\n    * The agent uses files within `.github/.copilot/domain_knowledge` as the authoritative source for understanding the project's context, entities, workflows, and language.\n    * It is expected to update these files as the understanding of the domain evolves during development.\n\n2.  **Specification Adherence:**\n    * The agent refers to specification files located in `.github/.copilot/specifications` to guide implementation.\n    * It uses a defined template (`.github/.copilot/specifications/.template.md`) for structure and clarifies which specifications are relevant if needed.\n\n3.  **The Breadcrumb Protocol:** This is the central pillar of the collaborative process:\n    * **Purpose:** To create a shared \"scratchpad\" or log (a \"breadcrumb\" file) for each task, ensuring alignment between the user and the agent, and documenting the development journey.\n    * **Creation:** For each new task, a breadcrumb file is created in `.github/.copilot/breadcrumbs` with the format `yyyy-mm-dd-HHMM-{title}.md`.\n    * **Structure:** Each breadcrumb file includes mandatory sections: Requirements, User Comments, Plan, Decisions, Implementation Details, Changes Made, Before/After Comparison, and References.\n    * **Workflow:**\n        * Updates happen *before* coding changes.\n        * The implementation **Plan** requires explicit user approval before starting work.\n        * The breadcrumb is updated *after* each significant change.\n        * It serves as the single source of truth for the task's context and progress.\n    * **Planning:** Plans are structured into phases and tasks, include checklists, reference domain knowledge/specs, prioritize tests, and have clear success criteria.\n    * **Execution:** The agent follows the approved plan, marks tasks as complete *after* successful implementation (including passing tests), and updates the breadcrumb accordingly.\n\n## Repository Structure\n`.github/copilot-instructions.md`: contains instruction for the agent.\n\n`.github/.copilot/` directory is crucial for this workflow:\n* `domain_knowledge/`: Contains files defining the project's context and rules.\n* `specifications/`: Holds requirement specifications, organized by feature or area.\n    * `.template.md`: Template for new specification files.\n* `breadcrumbs/`: Stores the collaborative log files created for each task according to the Breadcrumb Protocol.\n\nExample\n```text\n.github/.copilot/\n├── breadcrumbs/\n│   ├── 2025-04-13-0130-car-rental-entity-model.md\n│   ├── 2025-04-13-0135-aspnet-core-api-specification.md\n│   └── 2025-04-13-1723-car-rental-api-setup.md\n│\n├── domain_knowledge/\n│   └── entities/\n│       └── car-rental-entities.md\n│\n└── specifications/\n    ├── application_architecture/\n    │   └── aspnet-core-minimal-api.spec.md\n    └── .template.md\n```\n\n## Goal\n\nBy enforcing these instructions, this repository demonstrates a method to:\n\n* Improve the reliability and predictability of AI agent contributions.\n* Maintain a clear, documented trail of requirements, decisions, and implementation steps.\n* Facilitate easier review of changes by linking code modifications back to the documented plan and reasoning within the breadcrumb files.\n* Ensure the agent consistently leverages project-specific context (domain knowledge and specifications).\n\nThis setup provides a template and example for teams looking to integrate AI agents more deeply and effectively into their development workflows.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdasiths%2Fvibecodingbreadcrumbdemo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdasiths%2Fvibecodingbreadcrumbdemo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdasiths%2Fvibecodingbreadcrumbdemo/lists"}