chore: pause work and save context handoff

2026-03-30 07:32:23 +09:00
parent 509d6cae57
commit add7f40894
577 changed files with 90979 additions and 39 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -0,0 +1,11 @@
+# Roadmap
+
+## Phase 1: Zero-Pollution Pipeline Stabilization
+**Status:** Complete (2026-03-30)
+**Goal:** Fix the Master-Satellite synchronization pipeline to natively extract GSD skills, UI data, and Python MCP dependencies so that satellite repositories bootstrap via zero-click.
+
+### Requirements
+- REQ-01: Bootstrap script must auto-install Python dependencies for MCP tools across satellites.
+- REQ-02: Master sync script must invoke `get-shit-done-cc` local installation to native `.agent/skills` and ensure Git tracking.
+- REQ-03: Master sync script must invoke `uipro update` and commit changes.
+- REQ-04: The `.gitignore` generated by `extract_skills.js` must safely whitelist `/gsd` skill directories.
--- a/.planning/codebase/ARCHITECTURE.md
+++ b/.planning/codebase/ARCHITECTURE.md
@@ -1,12 +1,16 @@
-# Agent System Architecture
+# Codebase Architecture (`ARCHITECTURE.md`)

-## Core Components
-1. **Orchestrator Layer (`get-shit-done`)**: 프로젝트 `.planning/` 디렉터리의 상태를 관리하며 개발 페이즈(Phase)를 통제. CLI 명령어 체이닝을 담당.
-2. **Skill Encapsulation Layer (`.agent/vendor/`, `.agent/skills/`)**: 19종 이상의 핵심 무기가 CLI에 직결됨. 하위 모듈이 아니라 원시 폴더로 직접 트래킹되어 Git Clone 시 100% 작동.
-3. **External Sync Bridge (`.agent/scripts/`)**: Gitea Wiki/Vikunja 상태 푸시 보안 터널.
-4. **Master Vendor Sync (`.agent/scripts/sync_vendors.bat`)**: 이 마스터 저장소 단 한 곳에서만 오프소스 모듈을 동기화하고 평탄화, 번역, Git 커밋까지 One-click에 처리해 하위 파생 프로젝트로 뿌려주는 핵심 분배기(Distributor).
-5. **Memory Protocol (`claude-mem`)**: MCP 기반 로컬 SQLite 영구 기억 장치.
-6. **Rule Enforcement (`agent_lifecycle_sop.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
-[Agent NLU] → [GSD Phase Task] → [Superpowers Skill (Worktree 생성)] → [코드 작성/TDD] → [sync_*.js 로 Vikunja/Gitea 자동 보고]
+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.
--- a/.planning/codebase/CONCERNS.md
+++ b/.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.
--- a/.planning/codebase/CONVENTIONS.md
+++ b/.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.
--- a/.planning/codebase/INTEGRATIONS.md
+++ b/.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.
--- a/.planning/codebase/STACK.md
+++ b/.planning/codebase/STACK.md
@@ -1,7 +1,29 @@
-# Tech Stack
+# Codebase Stack (`STACK.md`)

- **CLI/Execution**: Node.js (v18+)
- **Agent Memory**: SQLite (via `claude-mem` MCP)
- **Design Tokens**: Python (via `ui-ux-pro-max-skill`)
- **Version Control**: Git / Git Worktrees
- **Documentation**: Obsidian Flavored Markdown (OFM)
+## 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.
--- a/.planning/codebase/STRUCTURE.md
+++ b/.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.
--- a/.planning/codebase/TESTING.md
+++ b/.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).
--- a/.planning/phases/01-zero-pollution-pipeline-stabilization/01-CONTEXT.md
+++ b/.planning/phases/01-zero-pollution-pipeline-stabilization/01-CONTEXT.md
@@ -0,0 +1,57 @@
+# Phase 1: Zero-Pollution Pipeline Stabilization - Context
+
+**Gathered:** 2026-03-30
+**Status:** Ready for planning
+**Source:** PRD Express Path (implementation_plan.md)
+
+<domain>
+## Phase Boundary
+Fix the Master-Satellite synchronization pipeline to natively extract GSD skills, UI updates, and Python dependencies. This ensures that a zero-click `bootstrap.bat/.sh` works flawlessly across new workspaces without violating the Zero-Pollution architecture.
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Zero-Click Python Dependencies
+- Modify `bootstrap.bat` and `bootstrap.sh` to auto-detect and pip-install Python dependencies for MCP tools (`browser_use`, `claude-mem`, `mini-swe`).
+
+### Master Sync Pipeline GSD Extraction
+- Modify `sync_vendors.bat` and `sync_vendors.sh` to execute `npm update get-shit-done-cc uipro-cli`, `npx uipro update`, and `npx get-shit-done-cc --antigravity --local` inside `.agent/env`.
+- Ensure output folders `.agent/get-shit-done/` and `.agent/skills/gsd-*/` are `git add`ed.
+
+### Gitignore Rules for extracted skills
+- Modify `.agent/scripts/extract_skills.js` to whitelist `!gsd-*/` in the generated `.gitignore` so Phase planning and GSD execution tools successfully persist to git.
+
+### the agent's Discretion
+- The method of Python virtual environment detection vs global python is left to the agent, though leveraging `AGENT_PYTHON_PATH` if specified is preferred.
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Zero Pollution Scripts
+- `bootstrap.bat`
+- `bootstrap.sh`
+- `.agent/scripts/sync_vendors.bat`
+- `.agent/scripts/sync_vendors.sh`
+- `.agent/scripts/extract_skills.js`
+
+</canonical_refs>
+
+<specifics>
+## Specific Ideas
+- The `npx get-shit-done-cc --antigravity --local` command must be run relative to the project root or precisely routed, otherwise GSD commands won't appear sequentially.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+None — PRD covers phase scope.
+</deferred>
+
+---
+
+*Phase: 01-zero-pollution-pipeline-stabilization*
+*Context gathered: 2026-03-30 via PRD Express Path*
--- a/.planning/phases/01-zero-pollution-pipeline-stabilization/01-PLAN.md
+++ b/.planning/phases/01-zero-pollution-pipeline-stabilization/01-PLAN.md
@@ -0,0 +1,143 @@
+---
+wave: 1
+depends_on: []
+files_modified:
+  - ".agent/scripts/sync_vendors.bat"
+  - ".agent/scripts/sync_vendors.sh"
+  - ".agent/scripts/extract_skills.js"
+  - "bootstrap.bat"
+  - "bootstrap.sh"
+autonomous: true
+---
+
+# Phase 1: Zero-Pollution Pipeline Stabilization
+
+## Objective
+Fix the Master-Satellite synchronization pipeline to natively extract GSD skills, UI data, and Python MCP dependencies so that satellite repositories bootstrap via zero-click.
+
+## Verification Criteria
+- [ ] Running `bootstrap.bat` attempts to install Python `requirements.txt` targets (`browser_use`, `claude-mem`).
+- [ ] Running `sync_vendors.bat` successfully runs `get-shit-done-cc` generator and Git tracks `.agent/skills/gsd-*/` and `.agent/get-shit-done/`.
+- [ ] `extract_skills.js` generated `.gitignore` whitelists `!gsd-*/`.
+
+## must_haves
+- [ ] `sync_vendors.bat` and `sync_vendors.sh` must execute `npm install`, `npx uipro update` and `npx get-shit-done-cc --antigravity --local`.
+- [ ] `bootstrap.bat` and `bootstrap.sh` must execute `pip install -r requirements.txt` for Python components if Python env exists.
+- [ ] GSD execution binaries and folders must be tracked via `git add .agent/get-shit-done/`.
+
+---
+
+<task>
+<read_first>
+- .agent/scripts/sync_vendors.bat
+- .agent/scripts/sync_vendors.sh
+</read_first>
+<action>
+Add the local GSD extraction and uipro updating mechanism directly inside `sync_vendors.bat` and `sync_vendors.sh`. 
+For the bash script (`sync_vendors.sh`), under step `[2/5] 패키지 업데이트 및 GSD, UI-UX-PRO-MAX 동기화...`:
+Add:
+```bash
+cd .agent/env
+npm install
+npm update get-shit-done-cc uipro-cli
+npx uipro update
+npx get-shit-done-cc --antigravity --local
+cd ../..
+```
+For the batch script (`sync_vendors.bat`), under a new step for package updates:
+Add:
+```bat
+cd .agent\env
+call npm install
+call npm update get-shit-done-cc uipro-cli
+call npx uipro update
+call npx get-shit-done-cc --antigravity --local
+cd ..\..
+```
+Also, change the git commit logic to track GSD:
+Change `git add .agent/vendor/ .agent/skills/ .gitmodules` to `git add .agent/vendor/ .agent/skills/ .agent/get-shit-done/ .gitmodules`
+</action>
+<acceptance_criteria>
+`grep "npx get-shit-done-cc --antigravity --local" .agent/scripts/sync_vendors.bat` exits 0.
+`grep "git add" .agent/scripts/sync_vendors.bat | grep ".agent/get-shit-done/"` exits 0.
+`grep "npx get-shit-done-cc --antigravity --local" .agent/scripts/sync_vendors.sh` exits 0.
+`grep "git add" .agent/scripts/sync_vendors.sh | grep ".agent/get-shit-done/"` exits 0.
+</acceptance_criteria>
+</task>
+
+<task>
+<read_first>
+- .agent/scripts/extract_skills.js
+</read_first>
+<action>
+Modify `extract_skills.js` to whitelist `gsd-*/` skill folders in the generated `.gitignore`.
+Find `const gitignoreContent = [` and add `'!gsd-*/',` below `'!mini-swe/',`.
+</action>
+<acceptance_criteria>
+`grep "!gsd-\*/" .agent/scripts/extract_skills.js` exits 0.
+</acceptance_criteria>
+</task>
+
+<task>
+<read_first>
+- bootstrap.bat
+</read_first>
+<action>
+Add Python MCP auto-setup logic to `bootstrap.bat` right after the node dependencies step.
+Add:
+```bat
+echo [4/5] Checking and Installing Python MCP Dependencies...
+if defined AGENT_PYTHON_PATH (
+    echo    -^> Using AGENT_PYTHON_PATH: %AGENT_PYTHON_PATH%
+    if exist ".agent\vendor\browser_use\requirements.txt" (
+        "%AGENT_PYTHON_PATH%" -m pip install -r ".agent\vendor\browser_use\requirements.txt"
+    )
+    if exist ".agent\services\claude-mem\requirements.txt" (
+        "%AGENT_PYTHON_PATH%" -m pip install -r ".agent\services\claude-mem\requirements.txt"
+    )
+    if exist ".agent\services\mini-swe\requirements.txt" (
+        "%AGENT_PYTHON_PATH%" -m pip install -r ".agent\services\mini-swe\requirements.txt"
+    )
+) else (
+    echo    -^> Warning: AGENT_PYTHON_PATH is not defined. Skipping Python dependencies installation.
+)
+```
+Update the final step text `[4/4]` to `[5/5]` appropriately.
+</action>
+<acceptance_criteria>
+`grep "AGENT_PYTHON_PATH" bootstrap.bat` exits 0.
+`grep "pip install -r" bootstrap.bat` exits 0.
+</acceptance_criteria>
+</task>
+
+<task>
+<read_first>
+- bootstrap.sh
+</read_first>
+<action>
+Add Python MCP auto-setup logic to `bootstrap.sh` right after the node dependencies step.
+Add:
+```bash
+echo "[4/5] Checking and Installing Python MCP Dependencies..."
+if [ -n "$AGENT_PYTHON_PATH" ]; then
+    echo "   -> Using AGENT_PYTHON_PATH: $AGENT_PYTHON_PATH"
+    if [ -f ".agent/vendor/browser_use/requirements.txt" ]; then
+        "$AGENT_PYTHON_PATH" -m pip install -r ".agent/vendor/browser_use/requirements.txt"
+    fi
+    if [ -f ".agent/services/claude-mem/requirements.txt" ]; then
+        "$AGENT_PYTHON_PATH" -m pip install -r ".agent/services/claude-mem/requirements.txt"
+    fi
+    if [ -f ".agent/services/mini-swe/requirements.txt" ]; then
+        "$AGENT_PYTHON_PATH" -m pip install -r ".agent/services/mini-swe/requirements.txt"
+    fi
+else
+    echo "   -> Warning: AGENT_PYTHON_PATH is not defined. Skipping Python dependencies installation."
+fi
+```
+Update the final step text `[4/4]` to `[5/5]` appropriately.
+</action>
+<acceptance_criteria>
+`grep "AGENT_PYTHON_PATH" bootstrap.sh` exits 0.
+`grep "pip install -r" bootstrap.sh` exits 0.
+</acceptance_criteria>
+</task>