kvokka · kvokka · Nov 24, 2025 · Nov 23, 2025 · Nov 24, 2025
diff --git a/.ai-template/memory/1_mission.md b/.ai-template/memory/1_mission.md
@@ -0,0 +1,15 @@
+# Mission & Architecture
+
+## Purpose
+This repository is a new project generated from the `kvokka/getting-started` template.
+
+## Core Tech Stack (Template Default)
+- **Infrastructure**: Docker Compose, DevContainers.
+- **Task Runner**: `just`.
+- **AI Tools**: `aicommit2` (for commits), `pre-commit`.
+- **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/`.
diff --git a/.ai-template/memory/2_architecture.md b/.ai-template/memory/2_architecture.md
@@ -0,0 +1,30 @@
+# System Architecture
+
+This document provides a detailed overview of the project's structure and is intended to be a living document. As an AI developer, you are expected to update this file as the project evolves.
+
+## Directory Structure and Purpose
+
+- **`.devcontainer/`**: This directory contains the definition for the development environment. It includes the `Dockerfile` for building the container, `devcontainer.json` for VS Code configuration, and other scripts needed to set up the environment. This ensures a consistent and reproducible development experience for all contributors.
+
+- **`.ai/`**: This is the "brain" of the AI-Git Flow. It contains the Memory Bank and rules for AI agents.
+    - **`memory/`**: This is the core of the AI's context.
+        - `1_mission.md`: Defines the project's high-level goals and technology stack.
+        - `2_architecture.md`: (This file) A detailed description of the project's structure. This should be updated as new components are added or existing ones are modified.
+        - `3_active_state.md`: A snapshot of the current state of the project, including the active task, recent changes, and next steps.
+    - **`rules.md`**: (deprecated in favor of `AGENTS.md`)
+
+- **`docs/`**: This directory is the project's knowledge base. It should contain documentation for developers and users, including architectural decision records (ADRs), tutorials, and API documentation.
+
+- **`prompts/`**: This directory is used for AI task management.
+    - **`active/`**: Contains the task(s) that the AI is currently working on. There should only be one active task at a time.
+    - **`drafts/`**: Contains tasks that are being prepared but are not yet ready to be worked on.
+    - **`history/`**: Contains completed tasks.
+    - **`templates/`**: Contains templates for creating new tasks.
+
+- **`src/`**: This directory contains the application's source code. The specific structure of this directory will depend on the project's language and framework.
+
+## Key Workflows
+
+- **Starting a New Project**: When a new project is created from this template, the `.ai-template` directory is renamed to `.ai`, and `AGENTS.md-template` is renamed to `AGENTS.md`. The initial state of the project is defined in `.ai/memory/3_active_state.md`.
+
+- **AI-Driven Development**: The development process is driven by tasks defined in the `prompts/active/` directory. The AI reads the task, makes the necessary code changes, updates the documentation in `docs/` and this file, and then updates `.ai/memory/3_active_state.md` to reflect the changes.
diff --git a/.ai-template/memory/3_active_state.md b/.ai-template/memory/3_active_state.md
@@ -0,0 +1,13 @@
+# Active State
+
+## Current Focus
+- Initializing a new project from the kvokka/getting-started template.
+- **Active Task**: `prompts/active/001-setup-project.md`.
+
+## Recent Changes
+- [ ] Project initialized.
+
+## Next Steps
+1. Define the project's mission and architecture in `.ai/memory/`.
+2. Create the first task in `prompts/active/`.
+3. Update this file to reflect the new project's state.
diff --git a/.ai/memory/1_mission.md b/.ai/memory/1_mission.md
@@ -0,0 +1,15 @@
+# Mission & Architecture - Template Repository
+
+## Purpose
+This repository is the **Master Template** for starting new projects. Your mission is to maintain and improve this template.
+
+## Core Tech Stack (Template Default)
+- **Infrastructure**: Docker Compose, DevContainers.
+- **Task Runner**: `just`.
+- **AI Tools**: `aicommit2`, `pre-commit`.
+- **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/`.
diff --git a/.ai/memory/2_architecture.md b/.ai/memory/2_architecture.md
@@ -0,0 +1,32 @@
+# System Architecture - Template Repository
+
+This document describes the architecture of the `kvokka/getting-started` template repository itself.
+
+## Directory Structure and Purpose
+
+- **`.devcontainer/`**: Contains the development environment definition.
+
+- **`.ai/`**: Contains the AI workflow files for *this template repository*.
+    - **`memory/`**: The Memory Bank for the template.
+        - `1_mission.md`: The mission of this template.
+        - `2_architecture.md`: (This file) The architecture of this template.
+        - `3_active_state.md`: The current state of this template.
+
+- **`.ai-template/`**: Contains the AI workflow files that will be used in *new projects* generated from this template. This directory is copied to `.ai` in a new project.
+    - **`memory/`**: The initial Memory Bank for a new project.
+
+- **`AGENTS.md`**: The rules for an AI working on *this template repository*.
+
+- **`AGENTS.md-template`**: The rules for an AI working on a *new project* generated from this template. This file is copied to `AGENTS.md` in a new project.
+
+- **`docs/`**: Documentation for the template.
+
+- **`prompts/`**: AI task management for the template.
+
+- **`src/`**: Source code for the template (should be empty).
+
+## Key Workflows
+
+- **Improving the Template**: Tasks for improving the template are managed in `prompts/`. Any changes to the AI workflow must be reflected in both the `.ai` and `.ai-template` directories as appropriate.
+
+- **Generating a New Project**: A GitHub Action (`.github/workflows/after-templating.yml`) runs when a new repository is created from this template. It removes the template-specific files (`.ai`, `AGENTS.md`) and replaces them with the project-specific files (`.ai-template`, `AGENTS.md-template`).
diff --git a/.ai/memory/3_active_state.md b/.ai/memory/3_active_state.md
@@ -0,0 +1,15 @@
+# Active State - Template Repository
+
+## Current Focus
+- Implementing the corrected dual AI workflow system.
+- **Active Task**: `prompts/active/001-implement-corrected-dual-ai-workflow.md`.
+
+## Recent Changes
+- [x] Created dual `.ai` and `AGENTS.md` structures.
+- [x] Populated `.ai-template` with files for generated repositories.
+- [x] Populated `.ai` with files for the template repository.
+
+## Next Steps
+1. Implement Pre-commit Hooks.
+2. Modify GitHub Action for Post-Processing.
+3. Overwrite Root README.
diff --git a/.github/scripts/install-pre-commit.sh b/.github/scripts/install-pre-commit.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+if ! command -v pre-commit &> /dev/null
+then
+    echo "pre-commit could not be found, installing..."
+    pip install pre-commit
+fi
diff --git a/.github/workflows/after-templating.yml b/.github/workflows/after-templating.yml
@@ -26,6 +26,16 @@ jobs:
           git rm docs/README.md || true
           git rm -r docs/test_requests || true
           git rm .github/workflows/after-templating.yml || true
+          git rm -rf .ai || true
+          git rm AGENTS.md || true
+
+      - name: Prepare AI files
+        if: steps.check_files.outputs.files_exists == 'true'
+        run: |
+          mv .ai-template .ai
+          mv AGENTS.md-template AGENTS.md
+          git add .ai
+          git add AGENTS.md
 
       - name: Update repo name and owner
         if: steps.check_files.outputs.files_exists == 'true'

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,8 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-added-large-files
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,26 @@
+# AI Agent Protocol (AI-Git Flow) - Template Repository
+
+You are an AI Developer working on the `kvokka/getting-started` template repository.
+
+## 1. Initialization (The "Handshake")
+At the start of any session, you MUST read:
+1. `.ai/memory/1_mission.md` (Project goals & Tech stack for this template)
+2. `.ai/memory/2_architecture.md` (The architecture of this template)
+3. `.ai/memory/3_active_state.md` (Current status of the template)
+4. `AGENTS.md` (This file)
+
+## 2. Dual Workflow System
+This repository uses a dual AI workflow system:
+- **`.ai/` and `AGENTS.md`**: These files are for the template repository itself.
+- **`.ai-template/` and `AGENTS.md-template`**: These files are for the projects that will be generated from this template.
+
+When you make changes to the AI workflow of the template, you must update the corresponding files in `.ai-template/` to reflect those changes.
+
+## 3. Workflow Rules
+- Your primary goal is to improve this template.
+- Do not work on tasks in `prompts/active` unless they are related to improving the template.
+
+## 4. Tooling Context
+- This project uses **DevContainers**.
+- Use `just` for running commands if `justfile` is present.
+- Secrets are in `.env` (excluded from git).
diff --git a/AGENTS.md-template b/AGENTS.md-template
@@ -0,0 +1,20 @@
+# 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/2_architecture.md` (A detailed explanation of the project structure)
+3. `.ai/memory/3_active_state.md` (Current status)
+4. `AGENTS.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/` and update `.ai/memory/2_architecture.md`.
+
+## 3. Tooling Context
+- This project uses **DevContainers**.
+- Use `just` for running commands if `justfile` is present.
+- Secrets are in `.env` (excluded from git).
diff --git a/README.md b/README.md
@@ -1,35 +1,51 @@
-# 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/).
+# Default Repo Template (DevContainer + AI Memory Bank)
+
+A universal boilerplate for reliable, isolated, and AI-friendly development based on [dotfiles](https://github.com/kvokka/dotfiles/).
+
+## 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
 
-## Quick start
+```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
+```
 
-Template/fork and use as is or replace dotfiles in
-[Dockerfile](./.devcontainer/Dockerfile)
+## How to use with AI
 
-### Project goals
+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."
 
-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
+## Assigning Work:
 
-*notes:*
+Create a file in `prompts/active/00X-my-task.md`.
+Tell AI: "Execute the task in prompts/active/00X-my-task.md".
 
-- 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).
+Closing Loop:
+The AI must update `.ai/memory/3_active_state.md` before finishing.
 
-### Environment Variables
+Move the task file to prompts/history/.
 
-TL;DR: For use local `.env` file for project related variables, for shared between
-different projects AND for MCP's use `~./.devcontainer/.env.devcontainer`.
+## Environment Variables
+See .devcontainer/devcontainer.json for loading order.
+Local secrets: .env (gitignored).
+Shared vars: ~/.devcontainer/.env.devcontainer.
 
-#### Loading order
+### Loading order
 
 - `containerEnv` section of the
 [`devcontainer.json`](./.devcontainer/devcontainer.json)  with build env vars.
@@ -41,27 +57,18 @@ different projects AND for MCP's use `~./.devcontainer/.env.devcontainer`.
 
 - *[optional]* project `.env` file, which is excluded from git and used for secrets
 
-#### Used env variables
+### 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
+- `mitmproxy` (optional) integration, which allows for intercepting and/or substituting
   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
+- There is a shared folder from outside of the project workspace `~/.devcontainer/shared` that is forwarded to `/workspace/shared` path. This path is ignored by git
 
 ## References
 
-The original boilerplate was from from this MS [repo](https://github.com/microsoft/vscode-remote-try-go)
-
-### Other boilerplates
-
-- <https://github.com/jsburckhardt/getting-started>
-
-### Useful links
-
-- [Dev containers schema](https://containers.dev/implementors/json_reference/)
-- [Dev containers features](https://containers.dev/features/)
+The original boilerplate was from this MS [repo](https://github.com/microsoft/vscode-remote-try-go)
diff --git a/justfile b/justfile
@@ -2,15 +2,19 @@
 set positional-arguments
 set dotenv-load
 
+init:
+    #!/usr/bin/env bash
+    .github/scripts/install-pre-commit.sh
+
 hooks what:
   #!/usr/bin/env bash
-
+  just init
   if [ -z "{{what}}" ]; then
-    git hook run pre-commit -- --unstaged-files
+    pre-commit run
   elif [ "{{what}}" = "staged" ]; then
-    git hook run pre-commit -- --staged-files
+    pre-commit run
   elif [ "{{what}}" = "all" ]; then
-    git hook run pre-commit -- --all-files
+    pre-commit run --all-files
   else
     echo "Invalid argument: {{what}}"
   fi