repo-memory-workflow 0.1.0

package/README.md

@@ -0,0 +1,239 @@
+repo-memory-workflow
+
+A lightweight workflow template for managing AI-assisted development in a repository.
+
+It helps you:
+
+split requirements into tasks
+
+keep decisions and progress recorded
+
+generate a compact context pack for LLMs / agents
+
+Features
+
+Simple .ai/ folder structure
+
+3 common scenarios supported:
+
+New requirement (planning + task split)
+
+Continue work (execute next actions)
+
+Retrofit existing work (backfill docs and tasks)
+
+One command to initialize templates in any repo
+
+Optional context pack generator (make_context.py)
+
+Install (Local)
+git clone <this-repo>
+cd repo-memory-workflow
+npm link
+
+
+If you see permission issues on macOS:
+
+sudo npm link
+
+Usage
+1) Initialize in any project
+
+Go to your target repo root:
+
+repo-memory-workflow init
+
+
+This will create:
+
+.ai/
+  START.md
+  TASK.md
+  CONTEXT.md
+  DECISIONS.md
+  LOG.md
+  TASKING_GUIDE.md
+  make_context.py
+  tasks/
+
+Workflow (Recommended)
+Scenario A — New Requirement (Task Planning)
+
+Open:
+
+.ai/START.md
+
+.ai/TASKING_GUIDE.md
+
+Then:
+
+switch to planning mode (in Cursor / ChatGPT / any agent)
+
+split the requirement into 3~10 tasks
+
+update .ai/TASK.md with the task list
+
+Scenario B — Continue Work (Execute Tasks)
+
+Open:
+
+.ai/START.md
+
+Then:
+
+continue the primary active task
+
+execute from Next actions step 1
+
+Scenario C — Retrofit (Half Done, Need Backfill)
+
+If the work is already half done and no workflow docs exist:
+
+open .ai/START.md
+
+enter retrofit mode
+
+run Task 000 (.ai/tasks/000_retrofit_existing_work.md)
+
+backfill decisions/log/context first
+
+split the remaining work into tasks
+
+Context Pack (Optional)
+
+This repo includes a helper script:
+
+python3 .ai/make_context.py
+
+
+It will generate a compact file (example):
+
+.ai/CONTEXT_PACK.md
+
+
+This file is meant to be pasted into Cursor / ChatGPT as the working context.
+
+Why this exists
+
+When using LLMs to help coding, the biggest problem is usually:
+
+requirements are unclear
+
+context is missing
+
+progress and decisions are not tracked
+
+This workflow makes the process more repeatable and less chaotic.
+
+License
+
+MIT
+
+中文说明
+
+这是一个用于 AI 辅助开发 的仓库工作流模板。
+
+它的目标是：让你在写代码时，能更稳定地让 AI 跟上进度，并且把需求、任务、决策、日志沉淀下来。
+
+功能
+
+提供统一的 .ai/ 目录结构
+
+覆盖 3 个常见开发场景：
+
+新需求：拆分任务并规划
+
+继续开发：按 Next actions 执行
+
+半路接入：补齐文档后继续拆分
+
+一条命令初始化模板
+
+可选的 make_context.py 自动生成上下文包
+
+安装（本地）
+git clone <this-repo>
+cd repo-memory-workflow
+npm link
+
+
+如果 macOS 报权限问题：
+
+sudo npm link
+
+使用方法
+1）在任意项目中初始化
+
+进入你要使用的项目根目录：
+
+repo-memory-workflow init
+
+
+会生成：
+
+.ai/
+  START.md
+  TASK.md
+  CONTEXT.md
+  DECISIONS.md
+  LOG.md
+  TASKING_GUIDE.md
+  make_context.py
+  tasks/
+
+推荐流程
+场景 1：新需求（拆分任务）
+
+打开：
+
+.ai/START.md
+
+.ai/TASKING_GUIDE.md
+
+然后：
+
+进入 planning mode
+
+把需求拆成 3~10 个 tasks
+
+更新 .ai/TASK.md
+
+场景 2：继续开发（执行任务）
+
+打开：
+
+.ai/START.md
+
+然后：
+
+继续 Primary active task
+
+从 Next actions 的第 1 步开始执行
+
+场景 3：半路接入（补档）
+
+如果项目已经做了一半，但之前没走流程：
+
+打开 .ai/START.md
+
+进入 retrofit mode
+
+执行 Task 000（.ai/tasks/000_retrofit_existing_work.md）
+
+先补齐日志/决策/上下文
+
+再拆分剩余任务继续推进
+
+Context Pack（可选）
+
+执行：
+
+python3 .ai/make_context.py
+
+
+会生成：
+
+.ai/CONTEXT_PACK.md
+
+
+这个文件可以直接贴进 Cursor / ChatGPT，当作当前任务上下文。

package/bin/repo-memory-workflow.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const fs = require("fs");
+const path = require("path");
+
+function exists(p) {
+  try { fs.accessSync(p); return true; } catch { return false; }
+}
+
+function mkdirp(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function copyDir(src, dst) {
+  mkdirp(dst);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const e of entries) {
+    const s = path.join(src, e.name);
+    const d = path.join(dst, e.name);
+    if (e.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function appendGitignore(root) {
+  const gi = path.join(root, ".gitignore");
+  const marker = "# repo-memory-workflow generated";
+  const rules = [marker, ".ai/CONTEXT_PACK.md", ""].join("\n");
+
+  if (!exists(gi)) {
+    fs.writeFileSync(gi, rules, "utf8");
+    return;
+  }
+  const cur = fs.readFileSync(gi, "utf8");
+  if (cur.includes(marker) || cur.includes(".ai/CONTEXT_PACK.md")) return;
+  fs.appendFileSync(gi, "\n" + rules, "utf8");
+}
+
+function help() {
+  console.log(`
+repo-memory-workflow
+
+Usage:
+  repo-memory-workflow init   # create .ai/ workflow templates in current project root
+`);
+}
+
+function init(root) {
+  const templatesRoot = path.join(__dirname, "..", "templates", "ai");
+  const aiDir = path.join(root, ".ai");
+
+  if (!exists(templatesRoot)) {
+    console.error("❌ Missing templates/ai in this package.");
+    process.exit(1);
+  }
+
+  if (exists(aiDir)) {
+    console.log("⚠️  .ai/ already exists. Skipping creation.");
+  } else {
+    copyDir(templatesRoot, aiDir);
+    console.log("✅ Created .ai/ templates");
+  }
+
+  appendGitignore(root);
+  console.log("✅ Updated .gitignore (ignore .ai/CONTEXT_PACK.md)");
+  console.log("Next: open .ai/START.md");
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const sub = args[0];
+
+  if (!sub || sub === "-h" || sub === "--help" || sub === "help") {
+    return help();
+  }
+
+  if (sub === "init") {
+    return init(process.cwd());
+  }
+
+  console.error(`Unknown command: ${sub}`);
+  help();
+  process.exit(1);
+}
+
+main();

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "repo-memory-workflow",
+  "version": "0.1.0",
+  "description": "Git-native, editor-agnostic AI workflow templates (.ai/) + context pack generator",
+  "bin": {
+    "repo-memory-workflow": "bin/repo-memory-workflow.js"
+  },
+  "type": "commonjs",
+  "license": "MIT",
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/templates/ai/CONTEXT.md

@@ -0,0 +1,39 @@
+# Project AI Context (Editor-agnostic)
+
+## How to continue work
+1) Always read: .ai/TASK.md
+2) Then read the Active task file referenced in TASK.md (under .ai/tasks/)
+3) Follow "Next actions" strictly. If anything is unclear, write it to "Open Questions" in the Active task.
+4) After each meaningful step:
+   - Update .ai/TASK.md (Current state + Next actions)
+   - Append key decisions to .ai/DECISIONS.md (only irreversible or important choices)
+   - Append progress logs to .ai/LOG.md (optional but recommended)
+
+## Rules
+- Do NOT guess. If context is missing, write "Open Questions" and propose 2-3 options.
+- Prefer minimal diffs and incremental commits.
+- If conversation context is low, rely on files in .ai/ as the source of truth.
+
+If the feature was already partially implemented WITHOUT this `.ai/` workflow,
+or conversation context is lost (new editor window / new teammate),
+you MUST create and complete:
+
+- `.ai/tasks/000_retrofit_existing_work.md`
+
+before continuing implementation.
+
+Do NOT guess missing context.
+Use repo state as source-of-truth and record unknowns in "Open questions".
+
+## Output conventions
+- Use checklists for TODO.
+- Keep TASK.md short and current.
+- Keep DECISIONS.md concise and dated.
+
+## Logging rule (MUST)
+After each meaningful step, append a log entry to `.ai/LOG.md`.
+Never overwrite existing logs. Always append.
+Each log entry must include:
+- What was done
+- Files changed
+- Next step

package/templates/ai/DECISIONS.md

@@ -0,0 +1,4 @@
+# DECISIONS
+
+## 2026-02-06
+- (Record only important decisions: architecture, data schema, API contracts, etc.)

package/templates/ai/LOG.md

@@ -0,0 +1,4 @@
+# LOG
+
+## 2026-02-06
+- Init repo-memory structure.

package/templates/ai/PROMPT_START.md

@@ -0,0 +1,18 @@
+# AI Workflow Start Prompt (Repo Memory)
+
+You must follow this repo workflow strictly:
+
+1) Always read:
+   - .ai/CONTEXT.md
+   - .ai/TASK.md
+   - The Active task file referenced in TASK.md
+
+2) Only execute the "Next actions" in the Active task.
+   - If anything is unclear, write it to "Open questions" instead of guessing.
+
+3) After each meaningful step, you MUST update:
+   - The Active task card (.ai/tasks/xxx.md): Current state / Done / Next actions
+   - .ai/LOG.md: append a short log entry (never overwrite)
+   - .ai/DECISIONS.md: only if architecture/schema/API contract changed
+
+4) Keep diffs minimal and incremental.

package/templates/ai/START.md

@@ -0,0 +1,137 @@
+# START (Repo Memory Workflow)
+
+This repo uses `.ai/` as the editor-agnostic source-of-truth for AI work.
+
+Supported editors/tools:
+- Cursor
+- VSCode (Codex)
+- Antigravity
+- Any CLI AI client that can read repo files
+
+---
+
+## 0) Golden rules (MUST)
+
+1) Always read:
+   - `.ai/CONTEXT.md`
+   - `.ai/TASK.md`
+   - The Primary active task card referenced in TASK.md
+
+2) Do NOT guess.
+   - If context is missing, write it into "Open questions".
+
+3) After each meaningful step, ALWAYS update:
+   - The active task card (Current state + Next actions)
+   - `.ai/LOG.md` (append only)
+   - `.ai/DECISIONS.md` (only if architecture/schema/API contract changed)
+
+4) Keep changes minimal and incremental.
+
+---
+
+## 1) Normal workflow: NEW requirement from scratch
+
+### Step 1: Split requirement into tasks (Planning mode)
+Ask AI:
+
+"Read `.ai/CONTEXT.md` and `.ai/TASKING_GUIDE.md`.
+Split the following requirement into 3~10 task cards under `.ai/tasks/`,
+and update `.ai/TASK.md` accordingly.
+Do NOT implement code yet."
+
+Then paste the requirement.
+
+### Step 2: Execute tasks (Implementation mode)
+Ask AI:
+
+"Read `.ai/CONTEXT.md`, `.ai/TASK.md`, and the Primary active task card.
+Start executing ONLY the 'Next actions' in the Primary active task.
+After each step, update task card and append `.ai/LOG.md`."
+
+---
+
+## 2) Workflow when chat context is full (Switch window safely)
+
+When the chat is almost full, do this BEFORE switching:
+
+1) Update the active task card:
+   - Current state: what is done
+   - Next actions: what remains (<=7 items)
+
+2) Append one entry to `.ai/LOG.md`:
+   - What was done
+   - Which files changed
+   - What is the next step
+
+3) Generate a context pack:
+   - Run: `python3 .ai/make_context.py`
+   - This will produce: `.ai/CONTEXT_PACK.md`
+
+In the NEW window/chat, ask AI:
+
+"Read `.ai/CONTEXT_PACK.md` first.
+Continue from the Primary active task 'Next actions'.
+After each step, update task card and append `.ai/LOG.md`."
+
+---
+
+## 3) Recovery workflow: requirement already half-done WITHOUT `.ai/` (Retrofit mode)
+
+This is REQUIRED when:
+- A teammate already implemented part of the feature without this workflow
+- Chat history is lost
+- The project is messy and needs task recovery
+
+### Step 1: Create Task 000 (Retrofit)
+Create this file if not present:
+
+- `.ai/tasks/000_retrofit_existing_work.md`
+
+Then put Task 000 into `.ai/TASK.md` -> Active as the Primary active task.
+
+### Step 2: Run context pack
+Run:
+`python3 .ai/make_context.py`
+
+### Step 3: Ask AI to recover state FIRST (do not code yet)
+Ask AI:
+
+"Enter retrofit mode.
+Read `.ai/CONTEXT_PACK.md`.
+Execute Task 000 ONLY:
+- Summarize what is already done from repo state
+- Append recovery summary into `.ai/LOG.md`
+- Split remaining work into 3~10 tasks
+- Update `.ai/TASK.md`
+Do NOT implement remaining tasks yet."
+
+### Step 4: After Task 000 is done
+Move Task 000 to Done.
+Then start implementing the remaining tasks normally.
+
+---
+
+## 4) Teammate handoff workflow (Someone continues your unfinished work)
+
+Teammate should:
+
+1) Pull latest code
+2) Run: `python3 .ai/make_context.py`
+3) Ask AI:
+
+"Read `.ai/CONTEXT_PACK.md`.
+Continue from the Primary active task.
+Follow Next actions strictly.
+After each step, update task card and append `.ai/LOG.md`."
+
+---
+
+## 5) Where to put extra documents (3rd-party docs, screenshots, rules)
+
+Store external inputs under:
+- `.ai/resources/`
+
+Rules:
+- Keep original files if possible
+- Add a short markdown summary next to it
+- Tasks should reference resource files instead of copying large text

package/templates/ai/TASK.md

@@ -0,0 +1,24 @@
+# TASK
+
+## Task board
+- Active:
+  - .ai/tasks/000_retrofit_existing_work.md
+- Queued:
+  - (none)
+- Blocked:
+  - (none)
+- Done:
+  - (none)
+
+## Objective
+- This repo uses `.ai/` as the editor-agnostic source-of-truth for AI work.
+- Track active tasks, queued tasks, and completed work here.
+
+## Current state
+- `.ai/` workflow initialized.
+- No project-specific tasks have been created yet.
+
+## Next actions
+- [ ] If this repo already has half-done work: run Retrofit (Task 000)
+- [ ] If this is a new requirement: ask AI to split it into 3~10 tasks under `.ai/tasks/`
+- [ ] Move tasks between Active / Queued / Done as progress is made

package/templates/ai/TASKING_GUIDE.md

@@ -0,0 +1,29 @@
+# TASKING GUIDE (How to create tasks)
+
+## Goal
+Turn a new requirement into a set of executable task cards under `.ai/tasks/`.
+
+## Rules
+1) Always create 3~10 tasks, do NOT create 1 giant task.
+2) Each task must have:
+   - Objective
+   - Context / Inputs
+   - Acceptance criteria
+   - Current state
+   - Next actions (<= 7 items, ordered, executable)
+   - Open questions (if any)
+3) Prefer tasks that can be parallelized.
+4) Do NOT include large raw docs in tasks. Use `.ai/resources/` references.
+5) If a task depends on another, mark it in the task as "Blocked by".
+
+## Naming
+- Task file name format:
+  - NNN_<short_title>.md
+- NNN must be the next available number (monotonic increasing).
+- Title should be short, action-oriented.
+
+## Output
+- Create/Update:
+  - `.ai/TASK.md` Task board
+  - New `.ai/tasks/*.md` files
+- Do NOT modify old archived epics.

package/templates/ai/make_context.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import re
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+AI_DIR = ROOT / ".ai"
+TASK_FILE = AI_DIR / "TASK.md"
+CONTEXT_FILE = AI_DIR / "CONTEXT.md"
+DECISIONS_FILE = AI_DIR / "DECISIONS.md"
+OUTPUT_FILE = AI_DIR / "CONTEXT_PACK.md"
+
+
+def run(cmd):
+    try:
+        return subprocess.check_output(
+            cmd, cwd=str(ROOT), stderr=subprocess.STDOUT, text=True
+        ).strip()
+    except Exception as e:
+        return f"(command failed: {' '.join(cmd)}; {e})"
+
+
+def read_text(p: Path, max_chars=20000):
+    if not p:
+        return "(missing path)"
+    if not p.exists():
+        return f"(missing: {p})"
+    s = p.read_text(encoding="utf-8", errors="ignore")
+    if len(s) > max_chars:
+        return s[:max_chars] + "\n\n...(truncated)...\n"
+    return s
+
+
+# -----------------------------
+# Active task parsing
+# -----------------------------
+
+def parse_active_task_path_legacy(task_md: str):
+    """
+    Legacy format:
+    - Path: .ai/tasks/xxx.md
+    """
+    m = re.search(
+        r"^-+\s*Path:\s*(\.ai\/tasks\/[^\s]+)\s*$",
+        task_md,
+        flags=re.MULTILINE,
+    )
+    if m:
+        return ROOT / m.group(1)
+    return None
+
+
+def parse_task_board_active_paths(task_md: str):
+    """
+    New format:
+    ## Task board
+    - Active:
+      - .ai/tasks/011_xxx.md
+      - .ai/tasks/012_yyy.md
+    - Queued:
+      - ...
+    """
+    lines = task_md.splitlines()
+    active_paths = []
+    in_active = False
+
+    for raw in lines:
+        line = raw.strip()
+
+        # enter Active block
+        if re.match(r"^-+\s*Active:\s*$", line):
+            in_active = True
+            continue
+
+        # leave Active block
+        if in_active and re.match(r"^-+\s*(Queued|Blocked|Done):\s*$", line):
+            in_active = False
+            continue
+
+        if not in_active:
+            continue
+
+        # match: "- .ai/tasks/xxx.md"
+        m = re.match(r"^-+\s*(\.ai\/tasks\/\S+\.md)\s*$", line)
+        if not m:
+            # match: ".ai/tasks/xxx.md"
+            m = re.match(r"^(\.ai\/tasks\/\S+\.md)\s*$", line)
+
+        if m:
+            active_paths.append(ROOT / m.group(1))
+
+    # Deduplicate while preserving order
+    uniq = []
+    seen = set()
+    for p in active_paths:
+        s = str(p)
+        if s not in seen:
+            seen.add(s)
+            uniq.append(p)
+
+    return uniq
+
+
+def parse_active_tasks(task_md: str):
+    """
+    Unified:
+    - Prefer Task board Active list if present
+    - Else fallback to legacy "- Path:" style
+    """
+    active_list = parse_task_board_active_paths(task_md)
+    if active_list:
+        return active_list
+
+    legacy = parse_active_task_path_legacy(task_md)
+    return [legacy] if legacy else []
+
+
+# -----------------------------
+# Main
+# -----------------------------
+
+def main():
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    task_md = read_text(TASK_FILE)
+
+    active_task_paths = parse_active_tasks(task_md)
+    primary_active_task = active_task_paths[0] if active_task_paths else None
+
+    primary_active_task_md = (
+        read_text(primary_active_task, max_chars=20000)
+        if primary_active_task
+        else "(No active task found in .ai/TASK.md)"
+    )
+
+    git_status = run(["git", "status", "--porcelain"])
+    git_branch = run(["git", "rev-parse", "--abbrev-ref", "HEAD"])
+    git_diff_stat = run(["git", "diff", "--stat"])
+    recent_commits = run(["git", "log", "-5", "--oneline"])
+
+    content = []
+    content.append(f"# CONTEXT PACK\n\nGenerated: {now}\n\n")
+
+    content.append("## How to use\n")
+    content.append("- In a NEW editor window/chat, ask the AI to read this file first.\n")
+    content.append("- Then follow the Next actions in the Primary active task.\n")
+    content.append("- After changes, AI must update .ai/TASK.md and relevant task card.\n\n")
+
+    content.append("## Repo info\n")
+    content.append(f"- Branch: {git_branch}\n\n")
+
+    content.append("## Git status (porcelain)\n```text\n" + (git_status or "(clean)") + "\n```\n\n")
+    content.append("## Git diff --stat\n```text\n" + (git_diff_stat or "(no diff)") + "\n```\n\n")
+    content.append("## Recent commits\n```text\n" + (recent_commits or "(no commits)") + "\n```\n\n")
+
+    content.append("## .ai/CONTEXT.md\n")
+    content.append(read_text(CONTEXT_FILE, max_chars=12000) + "\n\n")
+
+    content.append("## .ai/TASK.md\n")
+    content.append(task_md + "\n\n")
+
+    # Active tasks list
+    content.append("## Active tasks\n")
+    if active_task_paths:
+        for p in active_task_paths:
+            content.append(f"- {p.relative_to(ROOT)}\n")
+    else:
+        content.append("- (none)\n")
+    content.append("\n")
+
+    # Primary active task
+    content.append("## Primary active task (first in Active list)\n")
+    content.append(f"- Path: {primary_active_task.relative_to(ROOT) if primary_active_task else '(none)'}\n\n")
+    content.append(primary_active_task_md + "\n\n")
+
+    # Other active tasks
+    if len(active_task_paths) > 1:
+        content.append("## Other active tasks (truncated)\n")
+        for p in active_task_paths[1:]:
+            content.append(f"### {p.relative_to(ROOT)}\n")
+            content.append(read_text(p, max_chars=8000) + "\n\n")
+
+    content.append("## .ai/DECISIONS.md (latest)\n")
+    content.append(read_text(DECISIONS_FILE, max_chars=12000) + "\n\n")
+
+    OUTPUT_FILE.write_text("".join(content), encoding="utf-8")
+    print(f"✅ Wrote: {OUTPUT_FILE}")
+
+
+if __name__ == "__main__":
+    main()

package/templates/ai/tasks/000_retrofit_existing_work.md

@@ -0,0 +1,26 @@
+# Task 000 - Retrofit existing work (mandatory)
+
+## Objective
+Bring a half-done repo back into the `.ai/` workflow.
+
+## Context / Inputs
+- This repo already contains work in progress.
+- There may be no task cards, no log, and no clear current state.
+
+## Acceptance criteria
+- `.ai/TASK.md` reflects the real current work
+- 3~10 task cards exist under `.ai/tasks/`
+- One task is marked as Active and has executable Next actions
+- `.ai/LOG.md` contains a short retrofit entry
+
+## Current state
+- Unknown / not documented yet
+
+## Next actions
+1. Read `.ai/START.md`, `.ai/CONTEXT.md`, `.ai/PROMPT_START.md`
+2. Scan the repo quickly (top-level folders + README)
+3. Summarize current progress in 5~10 bullets
+4. Identify the current primary goal
+5. Create 3~10 task cards under `.ai/tasks/`
+6. Update `.ai/TASK.md` (Active / Queued / Done)
+7. Append a retrofit entry to `.ai/LOG.md`