From c0b9f5a0ea889029eba9e702285a41a5ef6956e8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 23 Nov 2025 04:55:44 +0000 Subject: [PATCH 1/2] chore: update CHANGELOG.md for tag v1.0.0 --- CHANGELOG.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 66 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dd80073..771afdb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,73 @@ All notable changes to this project will be documented in this file. See [conventional commits](https://www.conventionalcommits.org/) for commit guidelines. --- +## [1.0.0](https://github.com/kvokka/getting-started/compare/v0.3.0..v1.0.0) - 2025-11-23 +### 🚀 Features + +- **(devcontainer)** symlink shared host folder - ([a331f90](https://github.com/kvokka/getting-started/commit/a331f90c8d51b1a3b3f26f552580178a8e758c29)) - kvokka +- **(devcontainer)** enable Docker daemon access - ([582d96d](https://github.com/kvokka/getting-started/commit/582d96d453252d45359982bde8720464a84ed086)) - kvokka +- **(devcontainer)** integrate mitmproxy setup - ([fb49ffd](https://github.com/kvokka/getting-started/commit/fb49ffdb131f69c4f0e3cb34a64565998ddffdbb)) - kvokka +- **(just)** add 'hooks' recipe for git hook execution - ([3c208f5](https://github.com/kvokka/getting-started/commit/3c208f58ce772262046797660efe7d70fff98866)) - kvokka +- **(mcp)** configure github integration with saferun - ([70b6ece](https://github.com/kvokka/getting-started/commit/70b6ececad595f2e2032022451f22e90d543be23)) - kvokka +- add rules supremacy document - ([d438726](https://github.com/kvokka/getting-started/commit/d4387261c56669d763b554897b8959bb4486dbf4)) - kvokka +- add 'time' service definition to mcp.json - ([b374d17](https://github.com/kvokka/getting-started/commit/b374d170066a49ac46c931ad072034223eddba6f)) - kvokka +- add mem0-mcp configuration - ([f320ea5](https://github.com/kvokka/getting-started/commit/f320ea5de54a4b299a8fc718f42b40fdc1184d47)) - kvokka +- add ghost icon to test requests - ([734792b](https://github.com/kvokka/getting-started/commit/734792b67c1acee2a4d4d0cc7acd510845e3d1da)) - kvokka +- migrate to metamcp for MCP server management - ([b9c7dee](https://github.com/kvokka/getting-started/commit/b9c7deeb9b26f8389d611db5ed78c17a223b8965)) - kvokka + +### 🐛 Bug Fixes + +- correct forwarded port in devcontainer config - ([5d317d7](https://github.com/kvokka/getting-started/commit/5d317d7d226a8efc378339842bcb126989e1db1c)) - kvokka + +### 💼 Other + +- **(compose)** add explicit project name - ([b44c324](https://github.com/kvokka/getting-started/commit/b44c324efe0af056c390cb4fe0ad14726b680e2b)) - kvokka +- **(devcontainer)** enable Docker access for vscode user - ([a5af35e](https://github.com/kvokka/getting-started/commit/a5af35e4fc4d9619d5dfaf2fe3850196a4ee7527)) - kvokka +- **(linting)** migrate to markdownlint-cli2 - ([8626df0](https://github.com/kvokka/getting-started/commit/8626df0d159603c6cd9aa4dab0fd4b7415c78194)) - kvokka + +### 🚜 Refactor + +- rename and update critical instructions - ([4e43b70](https://github.com/kvokka/getting-started/commit/4e43b70721a1c965c627f01b6ec29d9972c25c65)) - kvokka +- simplify mandatory instructions - ([a840324](https://github.com/kvokka/getting-started/commit/a840324da2a6fc03a4266657ef6b23755124d736)) - kvokka +- remove mcp-safe-run usage - ([2c466bb](https://github.com/kvokka/getting-started/commit/2c466bbd3e2d11cc4fcf8ecbedd6a9c9abbd6a73)) - kvokka +- rename repo to getting-started - ([d573d9b](https://github.com/kvokka/getting-started/commit/d573d9baa6cf8720da5f68d351d7a3b51975b766)) - kvokka + +### 📚 Documentation + +- **(ai-config)** add AI Git commit message prompt - ([6a41537](https://github.com/kvokka/getting-started/commit/6a41537f2148f72da7dd538a79f9e10860525e44)) - kvokka +- **(memory-bank)** clarify memory bank rule loading - ([0fdd4da](https://github.com/kvokka/getting-started/commit/0fdd4dae039c51ed1fe004a55f9393c8efa8122e)) - kvokka +- **(memory-bank)** simplify init rule description - ([6a23cb8](https://github.com/kvokka/getting-started/commit/6a23cb8f978950875df971bea41e55a58139284b)) - kvokka +- **(memory-bank)** clarify init process steps - ([d093d51](https://github.com/kvokka/getting-started/commit/d093d519c6c1bb88bac4a8bb94516ca3364da25c)) - kvokka +- refine rule generation standards - ([465040b](https://github.com/kvokka/getting-started/commit/465040bcf663dda715166a94c3a9451bff095f89)) - kvokka +- add notes about Cursor and Claude 3.7 - ([a587040](https://github.com/kvokka/getting-started/commit/a587040326df823ab30ac82702ca7a3eb6854cc4)) - kvokka +- explain Claude's behavior with numbered lists - ([ab68860](https://github.com/kvokka/getting-started/commit/ab688609ed6653424026b58daa3f80c285d68bbd)) - kvokka +- add timeout instruction for shell commands - ([bf8285e](https://github.com/kvokka/getting-started/commit/bf8285ebead6d89bf47ca71686503552ead9eebb)) - kvokka +- add note about time in Cursor rules - ([0f25d90](https://github.com/kvokka/getting-started/commit/0f25d907f88448260ab63f6c12ab644af92ad5bd)) - kvokka +- add TIL feature and AI experiments notes - ([eed8037](https://github.com/kvokka/getting-started/commit/eed80378f42bfa24c3e0dba259fe7b4e720d4921)) - kvokka +- update rule generation standards - ([9e0afce](https://github.com/kvokka/getting-started/commit/9e0afcec504b19c0db4a38e34c93bc50336203a7)) - kvokka +- add TIL experiments and AI agents - ([d7175a0](https://github.com/kvokka/getting-started/commit/d7175a02ef87af86eac3375d646941a1ada9252b)) - kvokka +- update assistant-mcp description - ([aee0e3f](https://github.com/kvokka/getting-started/commit/aee0e3fa419642d816d46c2bfb1d182e864bc7cd)) - kvokka +- refine checkpoint instructions - ([fe12b4c](https://github.com/kvokka/getting-started/commit/fe12b4c8c602c2d926dafc967174f36828298e70)) - kvokka +- update README with cognee findings - ([b40166b](https://github.com/kvokka/getting-started/commit/b40166bc5a54e9afb7bc6c4588dc50b2d4d3fb4e)) - kvokka +- add update on mem0-mcp project - ([ec37029](https://github.com/kvokka/getting-started/commit/ec3702987ec7a570e82877d4610e6ab9ab806e35)) - kvokka +- add prompt engineering book to README - ([622e5f8](https://github.com/kvokka/getting-started/commit/622e5f81a9ed2dad3b0e0f75e834d5daa510e3a6)) - kvokka +- add info about roo-commander and Pheromind - ([020fd4a](https://github.com/kvokka/getting-started/commit/020fd4a20804cc2e7dcce168e2c47cf689d18485)) - kvokka +- expand on roo-commander review in README - ([80eec47](https://github.com/kvokka/getting-started/commit/80eec47bbabb3f5147bf6d1dfa14bafd7300a8ed)) - kvokka +- add 'Extras' section to README - ([5c4d36c](https://github.com/kvokka/getting-started/commit/5c4d36c6bb5873358e51fedde7f9ea154bcc1ea2)) - kvokka + +### ⚙️ Miscellaneous Tasks + +- **(devcontainer)** relocate Docker group setup to entrypoint - ([706ec71](https://github.com/kvokka/getting-started/commit/706ec7161c80c6d7f2eff1a981b048faba98f423)) - kvokka +- **(devcontainer)** add Git Worktree Menu extension - ([67bf2c9](https://github.com/kvokka/getting-started/commit/67bf2c99d4bbb95fb4710eccc898cbf04acd4236)) - kvokka +- **(docs)** clean up documentation, templates, and assets - ([2a1ab4f](https://github.com/kvokka/getting-started/commit/2a1ab4ff78b7736a3166bf50baed24f514a3c648)) - kvokka +- update CHANGELOG.md for tag v0.3.0 - ([c7cbbe5](https://github.com/kvokka/getting-started/commit/c7cbbe5f36ba077bee92e16d775d65faa5810b74)) - github-actions[bot] +- improve mandatory instructions and markdown rules - ([7b0b6e1](https://github.com/kvokka/getting-started/commit/7b0b6e1ca1ae31672480e4d28b001eea5496d47f)) - kvokka +- refactor MCP configurations and dev setup - ([0b3612a](https://github.com/kvokka/getting-started/commit/0b3612afe62d315dafaa41a3a4e37653f0e493da)) - kvokka +- configure workflow for new repositories - ([5f88beb](https://github.com/kvokka/getting-started/commit/5f88beb871214d0b5281311659ae5523bd033cc5)) - kvokka +- delete markdownlint config file - ([5ef751f](https://github.com/kvokka/getting-started/commit/5ef751f85261d78ab1691e1aff5fcf71f2e530d3)) - kvokka + +--- ## [0.3.0](https://github.com/kvokka/getting-started/compare/v0.2.0..v0.3.0) - 2025-05-03 ### 🚀 Features @@ -59,7 +125,6 @@ All notable changes to this project will be documented in this file. See [conven - remove redundant rule files - ([bcc3b99](https://github.com/kvokka/getting-started/commit/bcc3b996ae95551dc9ecfb97068b1f59577a7fa9)) - kvokka --- - ## [0.2.0](https://github.com/kvokka/getting-started/compare/v0.1.0..v0.2.0) - 2025-04-28 ### 🚀 Features @@ -104,7 +169,6 @@ All notable changes to this project will be documented in this file. See [conven - add tag on main check to changelog workflow - ([dfae8dd](https://github.com/kvokka/getting-started/commit/dfae8dd9ce0f5dfe8c1631b1af0760df5e60a91a)) - kvokka --- - ## [0.1.0] - 2025-04-12 ### 🚀 Features From 1f4a255176852d33136a0d6177ae52e7fbf83871 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 23 Nov 2025 05:58:23 +0000 Subject: [PATCH 2/2] feat: Integrate Memory Bank workflow This commit introduces the AI-Git Flow (Memory Bank) layer to the repository. - Creates the necessary directory structure for the Memory Bank, including `.ai/memory`, `docs/templates`, and `prompts`. - Adds a universal system prompt at `.ai/rules.md` to guide AI agents. - Populates the Memory Bank with initial context files defining the repository as a "Master Template". - Includes templates for tasks and project READMEs. - Updates the root README.md to reflect the new workflow. --- .ai/memory/1_mission.md | 17 +++++ .ai/memory/2_architecture.md | 12 ++++ .ai/memory/3_active_state.md | 14 ++++ .ai/rules.md | 19 ++++++ README.md | 103 ++++++++++------------------- docs/templates/PROJECT_README.md | 13 ++++ prompts/templates/task_template.md | 16 +++++ 7 files changed, 127 insertions(+), 67 deletions(-) create mode 100644 .ai/memory/1_mission.md create mode 100644 .ai/memory/2_architecture.md create mode 100644 .ai/memory/3_active_state.md create mode 100644 .ai/rules.md create mode 100644 docs/templates/PROJECT_README.md create mode 100644 prompts/templates/task_template.md diff --git a/.ai/memory/1_mission.md b/.ai/memory/1_mission.md new file mode 100644 index 0000000..abae67f --- /dev/null +++ b/.ai/memory/1_mission.md @@ -0,0 +1,17 @@ +# Mission & Architecture + +## Purpose +This repository is the **Master Template** for starting new projects. It combines: +1. **DevContainers**: For isolated, reproducible environments. +2. **AI-Git Flow**: For structured collaboration with LLMs using a Memory Bank. + +## Core Tech Stack (Template Default) +- **Infrastructure**: Docker Compose, DevContainers. +- **Task Runner**: `just`. +- **AI Tools**: `aicommit2` (for commits). +- **Languages**: Polyglot (Defined per project in `.devcontainer`). + +## Core Values +- **Isolation**: Nothing runs on the host machine. +- **Context**: The AI always knows the state via `.ai/memory/`. +- **Atomic Tasks**: Work is performed strictly via `prompts/active/`. \ No newline at end of file diff --git a/.ai/memory/2_architecture.md b/.ai/memory/2_architecture.md new file mode 100644 index 0000000..5efefda --- /dev/null +++ b/.ai/memory/2_architecture.md @@ -0,0 +1,12 @@ +# System Architecture + +## Directory Structure +- **.devcontainer/**: Environment definition (Dockerfile, devcontainer.json). +- **.ai/**: AI Context (Memory Bank & Rules). +- **docs/**: Knowledge Base. +- **prompts/**: Task Management (Active, History, Drafts). +- **src/**: Application Source Code. + +## Key Workflows +- **Start Project**: Clone repo -> Run `just init` (if configured) -> Edit `.ai/memory/`. +- **AI Development**: Create task in `prompts/active/` -> AI reads rules -> AI executes -> AI updates memory. \ No newline at end of file diff --git a/.ai/memory/3_active_state.md b/.ai/memory/3_active_state.md new file mode 100644 index 0000000..2166eef --- /dev/null +++ b/.ai/memory/3_active_state.md @@ -0,0 +1,14 @@ +# Active State + +## Current Focus +- Upgrading the repository structure to include AI-Git Flow. +- **Active Task**: `prompts/active/001-setup-ai-workflow.md`. + +## Recent Changes +- [x] Integrated `.ai/memory` structure. +- [x] Defined universal AI rules in `.ai/rules.md`. + +## Next Steps +1. Update root `README.md` to explain the new workflow. +2. Update `docs/templates/PROJECT_README.md`. +3. Move this task to history. \ No newline at end of file diff --git a/.ai/rules.md b/.ai/rules.md new file mode 100644 index 0000000..37c52dd --- /dev/null +++ b/.ai/rules.md @@ -0,0 +1,19 @@ +# AI Agent Protocol (AI-Git Flow) + +You are an AI Developer working in a strict context-aware environment. + +## 1. Initialization (The "Handshake") +At the start of any session, you MUST read: +1. `.ai/memory/1_mission.md` (Project goals & Tech stack) +2. `.ai/memory/3_active_state.md` (Current status) +3. `.ai/rules.md` (This file) + +## 2. Workflow Rules +- **Active Task Only**: You are only allowed to execute requirements found in `prompts/active/*.md`. +- **Memory Updates**: You cannot complete a response without updating `.ai/memory/3_active_state.md` if you changed the code or state. +- **Documentation**: If you encounter a new pattern or architecture decision, document it in `docs/`. + +## 3. Tooling Context +- This project uses **DevContainers**. +- Use `just` for running commands if `justfile` is present. +- Secrets are in `.env` (excluded from git). \ No newline at end of file diff --git a/README.md b/README.md index 267d970..c489fe2 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,36 @@ -# New repo template - -[![VS Code Container](https://img.shields.io/static/v1?label=VS+Code&message=Container&logo=visualstudiocode&color=007ACC&logoColor=007ACC&labelColor=2C2C32)](https://open.vscode.dev/microsoft/vscode) - -This is a template repository for starting a new project with using [dotfiles](https://github.com/kvokka/dotfiles/) with workflow in devcontainer for [VS Code](https://code.visualstudio.com/). - -## Quick start - -Template/fork and use as is or replace dotfiles in -[Dockerfile](./.devcontainer/Dockerfile) - -### Project goals - -1. Keep all the things in insolation from the host machine -2. Have a way to run the project on any machine with the same config -3. Ability to easily re-create the environment on a new local or remote machine -4. Safely try any VSCode based editor - -*notes:* - -- Microsoft [limit](https://github.com/getcursor/cursor/issues/2976) access -to VSCode marketplace, but extensions installation from other sources is still in -place, meaning that you can config your editor of choice with extensions listing -them in `devcontainer.json` using -VSCode [extension marketplace](https://marketplace.visualstudio.com/vscode). - -### Environment Variables - -TL;DR: For use local `.env` file for project related variables, for shared between -different projects AND for MCP's use `~./.devcontainer/.env.devcontainer`. - -#### Loading order - -- `containerEnv` section of the -[`devcontainer.json`](./.devcontainer/devcontainer.json) with build env vars. - -- `remoteEnv` section of the -[`devcontainer.json`](./.devcontainer/devcontainer.json) with runtime env vars. - -- *[optional]* global env file on the host machine in `~/.devcontainer/.env.devcontainer` file - -- *[optional]* project `.env` file, which is excluded from git and used for secrets - -#### Used env variables - -- *[optional]* `GOOGLE_AI_STUDIO_API_KEY` - used by `aicommit2`, should contain [Google AI Studio API key](https://aistudio.google.com/app/apikey) - -## Extras - -- Consistent git commit messages generation with `aicommit2` and `VSCode` - following [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) message format -- `mitmproxy` (optional) integration, that allows to intercept and/or substitute - responses from other services (local MitM), [details](./.devcontainer/proxy/README.md) -- There is a shared folder from outside of the project workspace `~/.devcontainer/shared` that is forwarded to `/workspace/shared` path. This path is ignored from git - -## References - -The original boilerplate was from from this MS [repo](https://github.com/microsoft/vscode-remote-try-go) - -### Other boilerplates - -- - -### Useful links - -- [Dev containers schema](https://containers.dev/implementors/json_reference/) -- [Dev containers features](https://containers.dev/features/) +# Default Repo Template (DevContainer + AI Memory Bank) + +A universal boilerplate for reliable, isolated, and AI-friendly development. + +## Features +1. **DevContainers**: Fully isolated environment (VS Code / Docker). +2. **AI-Git Flow**: Structured "Memory Bank" for context-aware AI agents. +3. **Just**: Simple command runner. + +## Directory Structure + +```text +.devcontainer/ # Docker & Environment config +.ai/ # AI Memory Bank (The "Brain") + ├── memory/ # Context files (Mission, Active State) + └── rules.md # Instructions for AI Agents +docs/ # Documentation Registry +prompts/ # AI Task Management + ├── active/ # The ONLY task AI should work on + └── history/ # Archived tasks +src/ # Source code +How to use with AI +Since this repo is IDE-agnostic, you need to "onboard" your AI agent manually (unless you configure your tool to auto-read .ai/rules.md). +The Protocol: +Context Loading: At the start of a chat, tell the AI: +"Read .ai/rules.md and .ai/memory/1_mission.md. Then check .ai/memory/3_active_state.md for the current status." +Assigning Work: +Create a file in prompts/active/00X-my-task.md. +Tell AI: "Execute the task in prompts/active/00X-my-task.md". +Closing Loop: +The AI must update .ai/memory/3_active_state.md before finishing. +Move the task file to prompts/history/. +Environment Variables +See .devcontainer/devcontainer.json for loading order. +Local secrets: .env (gitignored). +Shared vars: ~/.devcontainer/.env.devcontainer. \ No newline at end of file diff --git a/docs/templates/PROJECT_README.md b/docs/templates/PROJECT_README.md new file mode 100644 index 0000000..5ab1e11 --- /dev/null +++ b/docs/templates/PROJECT_README.md @@ -0,0 +1,13 @@ +# [Project Name] + +## Overview +This project uses **DevContainers** for isolation and **AI-Git Flow** for development. + +## Getting Started (AI Driven) +1. **Load Context**: Feed `.ai/rules.md` and `.ai/memory/1_mission.md` to your AI agent. +2. **Check Status**: Read `.ai/memory/3_active_state.md`. +3. **Pick a Task**: Look into `prompts/active/`. + +## Commands +- `just build`: Build the environment. +- `just up`: Start services. \ No newline at end of file diff --git a/prompts/templates/task_template.md b/prompts/templates/task_template.md new file mode 100644 index 0000000..3bba642 --- /dev/null +++ b/prompts/templates/task_template.md @@ -0,0 +1,16 @@ +# Task: [Task Name] + +## Context +(Why are we doing this? Link to .ai/memory/3_active_state.md) + +## Goal +(Definition of Done) + +## Technical Details +- **Files to modify**: ... +- **Relevant Docs**: `docs/...` + +## Steps +1. [ ] Step 1 +2. [ ] Step 2 +3. [ ] UPDATE `.ai/memory/3_active_state.md` \ No newline at end of file