chore: initial project setup with agent guide

.planning/codebase/ARCHITECTURE.md

@@ -0,0 +1,16 @@
+# Codebase Architecture (`ARCHITECTURE.md`)
+
+## Conceptual Core
+The project employs a **Master-Satellite Zero-Pollution Orchestration Model**.
+The architecture is designed to host local environments mapped centrally for LLM / Developer agents so that their capabilities and tracking modules do not leak into the developer's global OS environment.
+
+## Design Patterns & Layers
+1. **Master Repository Role (`new_gene`)**: Synchronizes third-party Submodules, flattens them via `.agent/scripts/extract_skills.js` and `.agent/scripts/sync_vendors.bat`, and seeds localized GSD skills via local bin instantiation.
+2. **Satellite Project Consumption**: Satellite repositories pull the tracked objects (like `.agent/get-shit-done/` binaries and `.agent/skills/gsd-*/` files), run `bootstrap.bat`, and safely isolate all code environments.
+
+## Execution Entry Points
+- Master Sync: `.agent/scripts/sync_vendors.bat/.sh` initializes NPM bounds, installs `uipro`/`get-shit-done-cc` strictly inside `.agent/env/node_modules/`, and runs them from the root via `.agent/env/node_modules/.bin/...` to safely isolate state.
+- Satellite Install: `bootstrap.bat/.sh` executes the runtime scripts sequentially (Git modules -> node env -> Python `.requirements` instantiation using a developer-provided `$AGENT_PYTHON_PATH`).
+
+## Data Flow
+The data flow travels exclusively via file IO (File reading -> Markdown modification) controlled by the Antigravity Agent framework executing `Task()` components or user IDE plugins. Git actions (add/commit/push) ensure cross-device immutability.

.planning/codebase/CONCERNS.md

@@ -0,0 +1,15 @@
+# Codebase Concerns (`CONCERNS.md`)
+
+## Known Technical Debt & Fragile Areas
+
+1. **UTF-8 Support on PowerShell**: 
+   The `sync_vendors.bat` script utilizes `chcp 65001 >nul` to support symbols and emojis (`🔄`, `⛏️`, `🌐`). However, invoking this `.bat` script directly from the new `powershell.exe` execution layers occasionally mangles the output characters or breaks parsing commands. Developers manually validating `sync_vendors.bat` in Powershell may observe syntax exceptions that don't manifest inside standard CMD executions.
+   
+2. **Path Encoding Depth Limitations**:
+   The GSD implementation maps Deep nested `.agent/vendor/**` repositories and heavily duplicates structure into `.agent/skills/`. For Windows systems overriding 260-character restrictions, this can theoretically introduce silent file truncation if the local `.agent` environment scales beyond expectations.
+
+3. **Submodule Divergences**:
+   The primary master hook uses `git submodule update --remote --merge`. Tracking upstream mains from multiple open-source repositories means breaking changes authored dynamically by upstream maintainers (e.g., `browser_use` rewriting its setup commands or `obsidian-skills` evolving) could cascade into local logic breaks, requiring a robust `translate_skills.js` sync layer to patch integration shifts.
+
+4. **Environment Abstraction Leaks**:
+   While Zero-Pollution aims to block system pollution, `bootstrap.bat` utilizes `AGENT_PYTHON_PATH` configured globally to execute `.requirements.txt`. There is an implicit assumption that this python executable is correctly mapped to an isolated virtual environment (`venv`). The architecture relies heavily on Developer compliance to not provide a root Python executable.

.planning/codebase/CONVENTIONS.md

@@ -0,0 +1,14 @@
+# Codebase Conventions (`CONVENTIONS.md`)
+
+## Code Style & Scripts
+- **Shell / Bash**: Ensure standard `$?` exit evaluation handling with `if [ $? -ne 0 ]; then exit 1; fi`.
+- **Batch Scripting**: Ensure `%errorlevel%` mapping with `if %errorlevel% neq 0 ( exit /b %errorlevel% )`. Uses `chcp 65001 >nul` for cross-platform UTF-8 emoji support.
+- **Node.js Scripts**: Typically wrapped recursively checking properties (`fs.existsSync`, `fs.readdirSync`), enforcing zero-pollution (ignoring flattened dependencies via explicit `fs.writeFileSync`).
+
+## Architectural Patterns
+- **Zero-Pollution Rule**: Never install global node_modules (`-g`) or system modifications. Path routing is managed securely using execution strings formatted like `path/to/local/bin` instead of relying on `$PATH`.
+- **Idempotency Rule**: The bootstrap processes (`bootstrap.sh`, `bootstrap.bat`) are designed to be run hundreds of times safely, using `if not exist` checks before taking any structural action.
+
+## Error Handling
+- Terminal outputs are robust, mapping explicit phases like `[1/5]`, `[2/5]` to terminal stdout.
+- Execution halts strictly on critical dependency update failures.

.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,17 @@
+# Codebase Integrations (`INTEGRATIONS.md`)
+
+## Webhooks & APIs
+- Currently, this project relies purely on Git synchronisation and CLI execution. Network activity is limited to downloading external packages (`npm install`, `pip install`, `git clone/pull`).
+- Once MCP tools are invoked, `claude-mem` likely interacts with SQLite logic or LLM memory endpoints depending on its runtime schema. `browser-use` interfaces with web targets directly.
+
+## Databases & Persistence
+- There are no central RDBMS or NoSQL layers native to this orchestration layer.
+- **Knowledge/Memory**: The project serves as an SSOT using markdown (`.planning/*`, `.agent/knowledge/*`).
+- **MCP state persistence**: Relies on specific plugin's local DBs (e.g., SQLite for mem logs).
+
+## Third-Party Authentication
+- Configured by `.agent/config/.env.agent` which includes API keys (Vikunja Task ID, Gitea instances, etc.), though the current codebase only seeds and checks for its existence without directly invoking the APIs inside the shell scripts.
+
+## Core External Tools
+- **Git**: Primary persistence and vendor orchestration transport mechanism.
+- **NPM & PIP**: Invoked asynchronously by bootstrap scripts to satisfy AI tool dependencies.

.planning/codebase/STACK.md

@@ -0,0 +1,29 @@
+# Codebase Stack (`STACK.md`)
+
+## Languages
+- **Shell / Batch Scripting**: Used heavily for the zero-pollution bootstrap scripts (`bootstrap.bat`, `bootstrap.sh`, `sync_vendors.bat`, `sync_vendors.sh`).
+- **JavaScript (Node.js)**: Used for vendor extraction and translation scripts (`extract_skills.js`, `translate_skills.js`).
+- **Python**: Required indirectly for running installed Python MCP servers (`browser_use`, `mini-swe`, `claude-mem`) during satellite bootstrapping.
+
+## Runtimes & Frameworks
+- **Node.js**: The `.agent/env` isolates local dependencies (e.g. `npm install`, `npx get-shit-done-cc`, `uipro-cli`). 
+- **Python**: Expected to be provided externally via user's `AGENT_PYTHON_PATH` to isolate plugin Python processes.
+- **Agent Engines**: Target runtimes interacting with this environment include Google Gemini CLI / Antigravity, Claude Code, and Copilot.
+
+## Core Dependencies
+- **UI & Workflow Generative Frameworks**:
+  - `get-shit-done-cc`: CLI orchestration framework for generating GSD workflows.
+  - `uipro-cli`: Generates UI/UX specification data.
+- **Git Submodules** (defined in `.gitmodules`):
+  - `.agent/vendor/superpowers`
+  - `.agent/knowledge/everything_claude`
+  - `.agent/knowledge/awesome_claude`
+  - `.agent/vendor/obsidian-skills`
+  - `.agent/services/claude-mem`
+  - `.agent/services/mcp-core`
+  - `.agent/vendor/browser_use`
+  - `.agent/vendor/mini-swe`
+
+## Configuration
+- `.agent/config/.env.agent`: Developer-specific agent configuration. Uses `.template` fallback.
+- `PROJECT.md` & `ROADMAP.md`: Project-level planning and tracker configurations.

.planning/codebase/STRUCTURE.md

@@ -0,0 +1,19 @@
+# Codebase Structure (`STRUCTURE.md`)
+
+## Directory Map
+
+- **Root Files**
+  - `bootstrap.bat` / `bootstrap.sh`: Primary runtime orchestrators for setting up the node/python environment.
+  - `.gitignore` & `.gitmodules`: Repository definitions protecting the ecosystem from pollution.
+  
+- **`.agent/` (The Enclave)**
+  - `.agent/env/`: The isolated local node environment container. Has its own `package.json` avoiding merging issues with user code.
+  - `.agent/scripts/`: Home of the Master Sync orchestration rules (`sync_vendors`, `extract_skills.js`, `translate_skills.js`).
+  - `.agent/skills/`: Holds the flattened markdown files (`SKILL.md`) that agents interpret on system boot. Note `gsd-*/` is whitelisted here.
+  - `.agent/vendor/`: The raw checked-out git repository targets before any translations/flattening is parsed out of them.
+  - `.agent/config/`: Runtime configurations specific to the current physical machine (`.env.agent`).
+  - `.agent/knowledge/`: Stores raw unstructured domain context for explicit queries.
+  
+- **`.planning/` (GSD Execution)**
+  - Manages the Project State (`PROJECT.md`, `ROADMAP.md`, `STATE.md`).
+  - `phases/`: Artifact history holding individual plans (`01-PLAN.md`) and the verification/summary reports mapping their outcomes.

.planning/codebase/TESTING.md

@@ -0,0 +1,12 @@
+# Codebase Testing (`TESTING.md`)
+
+## Structural Verification
+Given that this is an AI Framework Infrastructure project (Bootstrap Kit), formal unit testing via Jest/Vitest does not primarily apply to the root structure.
+
+## GSD Audit Testing
+Testing is defined strictly through the **Plan-Execute-Verify** cycle of the Get-Shit-Done (GSD) framework:
+- **`[Acceptance Criteria]`**: Each phase and subtask has shell commands evaluated by `grep` or file existence checks ensuring conditions are logically provable (e.g. `grep "npx get-shit-done-cc" .agent/scripts/sync_vendors.bat`).
+- **Verifiers**: The `.planning/phases/*-VERIFICATION.md` pattern uses dedicated checker agents to automatically validate system goals against the physical outcome on disk.
+
+## Continuous Integration
+At the moment, no GitHub Actions or standard CI test runners execute automated validation, as validation strictly hinges on local agent validation (`/gsd-verify-work` or `gsd-plan-checker` routines).