Skill: hanchunlee/appm (version 2.2.0)

# APPM - Atlas-Parallel Project Management ## 1. 簡介 (Description) `appm` (Atlas-Parallel Project Management) 是一套為 AI Agent 設計的「並行專案記憶管理系統」。它透過在每個專案目錄下建立 `.openclaw/` 資料夾，並維護 `MISSION.md` 與 `SNAPSHOT.md` 等核心快照文件，解決了 LLM 在多專案並行切換時遺失進度、架構與決策背景的問題。 ## 2. 核心機制 (Core Mechanism) ### A. [專案定錨] - 記憶恢復 (Memory Restoration) 當 Agent 進入一個包含 `.openclaw/` 的目錄時，**必須強制讀取**： 1. `MISSION.md`：理解該專案的終極目標與目前的里程碑進度。 2. `SNAPSHOT.md`：獲取最新的執行快照、代碼路徑與「下一步行動 (Next Action)」。 ### B. [狀態更新] - 快照義務 (Snapshot Obligation) 在以下情境下，Agent 應主動提議或更新 `SNAPSHOT.md`： - **重大里程碑達成**：例如完成了一個核心功能的開發或修復。 - **架構變動**：檔案路徑更名、API 介面異動。 - **專案切換或重置前**：在切換到另一個專案或執行 `/new` 指令前，主動更新進度快照。 ## 3. 目錄規範 (Directory Standard) ```text [project-root]/ └── .openclaw/ ├── MISSION.md # 專案使命與里程碑 (Long-term) ├── SNAPSHOT.md # 最新狀態快照 (Episodic) ├── DECISION_LOG.md # 重大決策歷史 (Log) └── ARCHITECTURE.md # 核心架構與組件說明 (Design) ``` ## 4. 使用方式 (Usage) ### A. 指令與工作流 - **`/newproject`**: 啟動雙軌初始化通道。Atlas 會詢問專案路徑、模式（標準/模糊）並引導完成定錨。 - **`openclaw appm init [project_path]`**: 快速初始化標準目錄結構。 - **`openclaw appm snapshot`**: 由 Agent 自動執行對話摘要並更新 `SNAPSHOT.md`。 - **`openclaw appm status`**: 顯示全域專案權重與儀表板。 ### B. 核心指紋與權重 系統會自動追蹤對話關鍵字，並更新 `data/appm_registry.json` 中的權重。權重最高的專案將在下次重啟時自動加載。 --- *Powered by Atlas & OpenClaw Community*

path: README.md
content: # APPM: Atlas-Parallel Project Management 🚀

[繁體中文版](#繁體中文) | [English Version](#english)

---

<a name="繁體中文"></a>
## 🇹🇼 繁體中文

### 1. 簡介
**APPM (Atlas-Parallel Project Management)** 是一套專為 AI Agent 設計的「並行專案記憶管理系統」。

當你在管理多個複雜的 AI 開發專案時，最常遇到的問題就是「Session 重置後，Agent 就忘了專案的進度與架構」。APPM 透過在專案目錄下建立標準化的 `.openclaw/` 快照，讓 Agent 能夠在數秒內「恢復意識」，實現無縫的並行開發。

### 2. 痛點解析 (Why APPM?)
開發這套系統是為了結算 AI 開發者長期以來的核心挫折：
- **重複解釋的地獄**：每次開啟新會話（Session），都要重新向 Agent 解釋專案架構與目前的 Bug，浪費大量時間與 Token。
- **Context 溢出與失憶**：Context 窗口有限，將所有歷史對話塞進 Prompt 既昂貴又低效。當對話變長，Agent 就會開始「失憶」。
- **並行專案混淆**：同時進行多個專案時，Agent 常會將專案 A 的邏輯套用到專案 B。
- **「Agent 漂移」**：缺乏一個「單一真實來源 (Single Source of Truth)」，導致 Agent 隨時間推移而偏離原始設計初衷。

### 3. 核心特色 (Core Features)
- **APPM 雙軌開發者通道 (Dual-Track Initialization)**:
    - **標準通道 (Standard Track)**: 適合計畫明確的開發，快速建立 `.openclaw/` 結構。
    - **模糊通道 (Vague Channel)**: 適合靈感雛形階段，透過 AI 顧問式訪談、協助使用者釐清專案輪廓。
- **動態權重定錨系統 (Dynamic Weight Anchor System) [New]**: 自動根據對話關鍵字頻率增加權重，並結合時間衰減機制 (Decay)，實現「開機即定錨」，Agent 無需提問即可恢復當前最活躍專案意識。
- **零 Context 切換成本**: 透過 `MISSION.md` 與 `SNAPSHOT.md`，Agent 能立即讀取專案背景。
- **重啟反射 (Reboot Reflection)**: 解決了 `/new` session 後的失憶與單向停訊問題。透過 `atlas_bootstrap.py` 在開機時自動執行「定錨回報」，確保 Agent 首條訊息即具備專案意識。
- **狀態持久化**: 即使重啟系統，開發進度依然清晰。

### 4. 工具組 (Tooling)
- `scripts/appm_recall.py`: 啟動時執行，彙報權重最高的前三個專案脈絡。
- `scripts/appm_update_weights.py`: 背景動態更新權重，處理 hit 與 decay。
- `scripts/appm_init_dual.py`: 初始化專案結構。

### 4. 目錄結構
```text
[你的專案]/
└── .openclaw/
    ├── MISSION.md      # 專案長期目標、里程碑與痛點
    ├── SNAPSHOT.md     # 當前進度快照、任務 ID 與下一步行動
    ├── DECISION_LOG.md # 關鍵架構決策紀錄
    └── ARCHITECTURE.md # 技術邊界、核心組件與文件說明
```

### 5. 快速開始
1. **初始化專案 (雙軌)**：
   - 標準模式: `python3 scripts/appm_init_dual.py --standard [路徑]`
   - 模糊模式: `python3 scripts/appm_init_dual.py --vague [路徑]`
2. **讓 Agent 定錨**：在 System Prompt 中加入「看到 `.openclaw` 目錄時，優先讀取其內容」。
3. **動態追蹤**: 系統背景自動執行 `scripts/appm_tracker.py` 維持權重。

---

<a name="english"></a>
## 🇺🇸 English

### 1. Introduction
**APPM (Atlas-Parallel Project Management)** is a project-level persistent memory system designed specifically for AI Agents.

The biggest challenge in managing multiple complex AI projects is "Agent Amnesia" after session resets. APPM solves this by maintaining standardized `.openclaw/` snapshots, allowing your Agent to "reclaim consciousness" within seconds for seamless parallel development.

### 2. Why APPM? (Pain Points)
APPM was created to end the core frustrations of AI-native developers:
- **Explanation Hell**: Re-explaining project architecture and current bugs every time a new session starts is a massive waste of time and tokens.
- **Context Overflow & Amnesia**: Context windows are limited. Cramming history into every prompt is expensive and inefficient. As conversations grow, Agents inevitably "forget."
- **Parallel Project Confusion**: When managing multiple projects simultaneously, Agents often mix up logic between Project A and Project B.
- **"Agentic Drift"**: Without a "Single Source of Truth," Agents tend to deviate from the original design intent over time.

### 3. Key Features
- **Zero Context Switching Cost**: Agents instantly understand project background via `MISSION.md` and `SNAPSHOT.md`.
- **Parallel Management**: Designed for multi-project workflows, preventing logic leakage between tasks.
- **State Persistence**: Development progress remains crystal clear across system reboots or model changes.

### 3. Directory Standard
```text
[your-project]/
└── .openclaw/
    ├── MISSION.md      # Long-term goals & milestones
    ├── SNAPSHOT.md     # Current snapshot & next actions
    ├── DECISION_LOG.md # Key decision history
    └── ARCHITECTURE.md # Core components description
```

### 4. Quick Start
1. **Install Skill**: `openclaw install appm` (ClawHub Coming Soon)
2. **Initialize Project**:
   ```bash
   python3 scripts/init.py [project_path]
   ```
3. **Agent Anchoring**: Ensure your Agent reads `.openclaw` files upon entering the directory.

---
*Created by Atlas & [Boss's Name/Handle]*
*Powered by the OpenClaw Community*


path: scripts/appm_recall.py
content: import json
import os

REGISTRY_PATH = os.path.expanduser('~/.openclaw/workspace/data/appm_registry.json')

def get_project_brief(path):
    snapshot_path = os.path.join(path, ".openclaw/SNAPSHOT.md")
    brief = {"path": path, "name": "未知專案", "version": "N/A", "next_move": "無資料"}
    
    if os.path.exists(snapshot_path):
        with open(snapshot_path, 'r', encoding='utf-8') as f:
            lines = f.readlines()
            for line in lines:
                if "版本" in line or "**版本**" in line:
                    brief["version"] = line.split(":")[-1].strip().replace("*", "")
                if "下一步" in line or "**下一步**" in line:
                    idx = lines.index(line)
                    for next_line in lines[idx+1:]:
                        if next_line.strip().startswith("- [ ]") or next_line.strip().startswith("1.") or next_line.strip().startswith("- **"):
                            brief["next_move"] = next_line.strip()
                            break
    return brief

def recall():
    if not os.path.exists(REGISTRY_PATH):
        print("No registry found.")
        return

    with open(REGISTRY_PATH, 'r', encoding='utf-8') as f:
        registry = json.load(f)

    print("\n[APPM 活躍專案彙報]")
    for p in registry['projects'][:3]:
        brief = get_project_brief(p['path'])
        print(f"- 專案: {p['name']} (權重: {p['weight']})")
        print(f"  版本: {brief['version']}")
        print(f"  下一步: {brief['next_move']}")
        print(f"  路徑: {p['path']}")

if __name__ == "__main__":
    recall()


path: scripts/init.py
content: import os
import sys
import shutil

def init_appm(project_path):
    project_path = os.path.abspath(project_path)
    openclaw_dir = os.path.join(project_path, ".openclaw")
    template_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "templates")

    if not os.path.exists(project_path):
        os.makedirs(project_path)
    
    if not os.path.exists(openclaw_dir):
        os.makedirs(openclaw_dir)
        print(f"Created {openclaw_dir}")
    
    templates = ["MISSION.md", "SNAPSHOT.md", "DECISION_LOG.md"]
    for t in templates:
        src = os.path.join(template_dir, t)
        dst = os.path.join(openclaw_dir, t)
        if not os.path.exists(dst):
            shutil.copy(src, dst)
            print(f"Copied template: {t}")
        else:
            print(f"Template already exists: {t}")

    print("\nAPPM Project Initialized Successfully.")

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python init.py <project_path>")
        sys.exit(1)
    
    init_appm(sys.argv[1])


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)