engaku 0.2.0__tar.gz

engaku-0.2.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: engaku
+Version: 0.2.0
+Summary: AI persistent memory layer for VS Code Copilot
+License: MIT
+Project-URL: Homepage, https://github.com/JorgenLiu/engaku
+Project-URL: Repository, https://github.com/JorgenLiu/engaku
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# engaku
+
+AI persistent memory layer for VS Code Copilot — keeps project context, rules, and active tasks in front of the agent at every turn through VS Code Agent Hooks.
+
+## What it does
+
+`engaku` gives VS Code Copilot durable project memory stored in `.ai/` Markdown files. Agent Hooks automatically inject current context into every conversation, surface active-task steps on each prompt, and remind the agent when a task plan is complete and ready for review.
+
+## Installation
+
+```bash
+pip install engaku
+```
+
+Or install directly from source:
+
+```bash
+pip install git+https://github.com/JorgenLiu/engaku.git
+```
+
+## Quick Start
+
+```bash
+# Bootstrap .ai/ and .github/ structure in your repo
+engaku init
+```
+
+After running `init`, VS Code Agent Hooks are active. The `@dev`, `@planner`, `@reviewer`, and `@scanner` agents are available via `.github/agents/`. No further manual steps are needed — hooks fire automatically on SessionStart, UserPromptSubmit, Stop, and PreCompact.
+
+## What `engaku init` creates
+
+```
+.ai/
+  overview.md       — project description, constraints, tech stack
+  tasks/            — planner-managed task plans
+  decisions/        — architecture decision records
+.github/
+  copilot-instructions.md   — global agent rules
+  agents/           — dev, planner, reviewer, scanner agent definitions
+  instructions/     — .instructions.md stubs for hooks, templates, tests
+  skills/           — bundled skills (systematic-debugging, verification-before-completion, frontend-design)
+```
+
+## Subcommands
+
+| Command | Purpose |
+|---------|---------|
+| `init` | Bootstrap `.ai/`, `.github/` structure and install VS Code Agent Hooks |
+| `inject` | Inject `.ai/overview.md` + active-task context (SessionStart / PreCompact hook) |
+| `prompt-check` | Detect rule/constraint in user prompt and inject active-task steps (UserPromptSubmit hook) |
+| `task-review` | Detect completed task plans and emit handoff reminder (Stop hook) |
+| `apply` | Apply `.ai/engaku.json` model config to `.github/agents/` frontmatter |
+
+## How it works
+
+After `engaku init`, four Agent Hooks fire automatically:
+
+- **`SessionStart`** → `engaku inject`: injects `overview.md` and the current active-task context at the start of every session.
+- **`PreCompact`** → `engaku inject`: re-injects context before conversation compaction so the agent doesn't lose project memory.
+- **`UserPromptSubmit`** → `engaku prompt-check`: scans each user prompt for new rules or constraints and injects the active-task's unchecked steps as a system message so the agent always knows what to do next.
+- **`Stop`** → `engaku task-review`: after each agent turn, checks whether all steps in an in-progress task plan are ticked and emits a handoff reminder if so.
+
+## Requirements
+
+- Python ≥ 3.8 (stdlib only, no third-party dependencies)
+- VS Code with GitHub Copilot

engaku-0.2.0/README.md

@@ -0,0 +1,66 @@
+# engaku
+
+AI persistent memory layer for VS Code Copilot — keeps project context, rules, and active tasks in front of the agent at every turn through VS Code Agent Hooks.
+
+## What it does
+
+`engaku` gives VS Code Copilot durable project memory stored in `.ai/` Markdown files. Agent Hooks automatically inject current context into every conversation, surface active-task steps on each prompt, and remind the agent when a task plan is complete and ready for review.
+
+## Installation
+
+```bash
+pip install engaku
+```
+
+Or install directly from source:
+
+```bash
+pip install git+https://github.com/JorgenLiu/engaku.git
+```
+
+## Quick Start
+
+```bash
+# Bootstrap .ai/ and .github/ structure in your repo
+engaku init
+```
+
+After running `init`, VS Code Agent Hooks are active. The `@dev`, `@planner`, `@reviewer`, and `@scanner` agents are available via `.github/agents/`. No further manual steps are needed — hooks fire automatically on SessionStart, UserPromptSubmit, Stop, and PreCompact.
+
+## What `engaku init` creates
+
+```
+.ai/
+  overview.md       — project description, constraints, tech stack
+  tasks/            — planner-managed task plans
+  decisions/        — architecture decision records
+.github/
+  copilot-instructions.md   — global agent rules
+  agents/           — dev, planner, reviewer, scanner agent definitions
+  instructions/     — .instructions.md stubs for hooks, templates, tests
+  skills/           — bundled skills (systematic-debugging, verification-before-completion, frontend-design)
+```
+
+## Subcommands
+
+| Command | Purpose |
+|---------|---------|
+| `init` | Bootstrap `.ai/`, `.github/` structure and install VS Code Agent Hooks |
+| `inject` | Inject `.ai/overview.md` + active-task context (SessionStart / PreCompact hook) |
+| `prompt-check` | Detect rule/constraint in user prompt and inject active-task steps (UserPromptSubmit hook) |
+| `task-review` | Detect completed task plans and emit handoff reminder (Stop hook) |
+| `apply` | Apply `.ai/engaku.json` model config to `.github/agents/` frontmatter |
+
+## How it works
+
+After `engaku init`, four Agent Hooks fire automatically:
+
+- **`SessionStart`** → `engaku inject`: injects `overview.md` and the current active-task context at the start of every session.
+- **`PreCompact`** → `engaku inject`: re-injects context before conversation compaction so the agent doesn't lose project memory.
+- **`UserPromptSubmit`** → `engaku prompt-check`: scans each user prompt for new rules or constraints and injects the active-task's unchecked steps as a system message so the agent always knows what to do next.
+- **`Stop`** → `engaku task-review`: after each agent turn, checks whether all steps in an in-progress task plan are ticked and emits a handoff reminder if so.
+
+## Requirements
+
+- Python ≥ 3.8 (stdlib only, no third-party dependencies)
+- VS Code with GitHub Copilot

engaku-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=45"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "engaku"
+version = "0.2.0"
+description = "AI persistent memory layer for VS Code Copilot"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://github.com/JorgenLiu/engaku"
+Repository = "https://github.com/JorgenLiu/engaku"
+
+[project.scripts]
+engaku = "engaku.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"engaku" = [
+    "templates/*.md",
+    "templates/*.json",
+    "templates/agents/*.md",
+    "templates/ai/*.md",
+    "templates/ai/*.json",
+    "templates/instructions/*.md",
+    "templates/skills/*/*.md",
+]

engaku-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

engaku-0.2.0/src/engaku/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

engaku-0.2.0/src/engaku/__main__.py

@@ -0,0 +1,3 @@
+from engaku.cli import main
+
+main()

engaku-0.2.0/src/engaku/cli.py

@@ -0,0 +1,64 @@
+import argparse
+import sys
+
+from engaku import __version__
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="engaku",
+        description="AI persistent memory layer for VS Code Copilot",
+    )
+    parser.add_argument(
+        "--version", action="version", version="%(prog)s " + __version__
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+    subparsers.required = True
+
+    # engaku init
+    subparsers.add_parser(
+        "init",
+        help="Initialize .ai/ knowledge structure and .github/ hooks/agents in target repo",
+    )
+
+    # engaku inject
+    subparsers.add_parser(
+        "inject",
+        help="Inject .ai/overview.md + active-task context (SessionStart/PreCompact/SubagentStart hook)",
+    )
+
+    # engaku prompt-check
+    subparsers.add_parser(
+        "prompt-check",
+        help="Detect potential rule/constraint in user prompt (UserPromptSubmit hook)",
+    )
+
+    # engaku task-review
+    subparsers.add_parser(
+        "task-review",
+        help="Detect all-complete task plans and emit handoff reminder (Stop hook)",
+    )
+
+    # engaku apply
+    subparsers.add_parser(
+        "apply",
+        help="Apply .ai/engaku.json model config to .github/agents/ frontmatter",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        from engaku.cmd_init import run
+        sys.exit(run())
+    elif args.command == "inject":
+        from engaku.cmd_inject import run
+        sys.exit(run())
+    elif args.command == "prompt-check":
+        from engaku.cmd_prompt_check import run
+        sys.exit(run())
+    elif args.command == "task-review":
+        from engaku.cmd_task_review import run
+        sys.exit(run())
+    elif args.command == "apply":
+        from engaku.cmd_apply import run
+        sys.exit(run())

engaku-0.2.0/src/engaku/cmd_apply.py

@@ -0,0 +1,130 @@
+"""
+engaku apply
+Apply .ai/engaku.json configuration to .github/agents/ files.
+
+Reads model assignments from .ai/engaku.json and writes the model: field
+into each matching .github/agents/{name}.agent.md frontmatter.  If an agent
+file has no model: field, one is inserted immediately after the name: line.
+
+Usage:
+  engaku apply
+"""
+import json
+import os
+import re
+import sys
+
+from engaku.constants import CONFIG_FILE
+from engaku.utils import load_config
+
+
+def _update_agent_model(agent_path, model):
+    """Update or insert model: field in agent frontmatter.
+
+    Returns (changed, reason) where changed is True if the file was written.
+    """
+    with open(agent_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    if not content.startswith("---\n"):
+        return False, "no frontmatter"
+
+    close = content.find("\n---", 4)
+    if close == -1:
+        return False, "unclosed frontmatter"
+
+    # Guard against false match (--- embedded inside a multiline value)
+    after_close = content[close + 4:]
+    if after_close and after_close[0] not in ("\n", "\r"):
+        return False, "malformed frontmatter"
+
+    fm = content[4:close]       # YAML body — no trailing newline
+    rest = content[close:]      # starts with \n---
+
+    model_line = "model: ['{}']".format(model)
+
+    if re.search(r"^model:", fm, re.MULTILINE):
+        new_fm = re.sub(r"^model:.*$", model_line, fm, flags=re.MULTILINE)
+    else:
+        # Insert immediately after the name: line if present, else append.
+        if re.search(r"^name:", fm, re.MULTILINE):
+            new_fm = re.sub(
+                r"(^name:.*$)",
+                r"\1\n" + model_line,
+                fm,
+                count=1,
+                flags=re.MULTILINE,
+            )
+        else:
+            new_fm = fm + "\n" + model_line
+
+    if new_fm == fm:
+        return False, "no change"
+
+    with open(agent_path, "w", encoding="utf-8") as f:
+        f.write("---\n" + new_fm + rest)
+    return True, "ok"
+
+
+def run(cwd=None):
+    if cwd is None:
+        cwd = os.getcwd()
+
+    config_path = os.path.join(cwd, CONFIG_FILE)
+    if not os.path.isfile(config_path):
+        sys.stderr.write(
+            "error: {} not found.\n"
+            "Run 'engaku init' to create it.\n".format(config_path)
+        )
+        return 1
+
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            json.load(f)
+    except ValueError as exc:
+        sys.stderr.write(
+            "error: invalid JSON in {}: {}\n".format(config_path, exc)
+        )
+        return 1
+
+    config = load_config(cwd)
+
+
+    # ── agents → .github/agents/ ─────────────────────────────────────────────
+    agents_config = config.get("agents", {})
+    agents_dir = os.path.join(cwd, ".github", "agents")
+    changed = 0
+    skipped = 0
+
+    for agent_name in sorted(agents_config):
+        model = agents_config[agent_name]
+        agent_path = os.path.join(agents_dir, "{}.agent.md".format(agent_name))
+        if not os.path.isfile(agent_path):
+            sys.stdout.write(
+                "  [skip]    {}.agent.md (file not found)\n".format(agent_name)
+            )
+            skipped += 1
+            continue
+
+        updated, reason = _update_agent_model(agent_path, model)
+        if updated:
+            sys.stdout.write(
+                "  [updated] {}.agent.md -> {}\n".format(agent_name, model)
+            )
+            changed += 1
+        else:
+            sys.stdout.write(
+                "  [skip]    {}.agent.md ({})\n".format(agent_name, reason)
+            )
+            skipped += 1
+
+    total_changed = changed
+    total_skipped = skipped
+    sys.stdout.write(
+        "\napply complete: {} updated, {} skipped.\n".format(total_changed, total_skipped)
+    )
+    return 0
+
+
+def main():
+    sys.exit(run())

engaku-0.2.0/src/engaku/cmd_init.py

@@ -0,0 +1,185 @@
+"""
+engaku init
+Initialize .ai/ knowledge structure and .github/ hooks + agents in the current
+git repository.
+
+Files created (never overwritten if they already exist):
+  .ai/
+    overview.md
+    engaku.json
+    decisions/.gitkeep
+    tasks/.gitkeep
+    docs/.gitkeep
+  .github/
+    agents/
+      dev.agent.md
+      planner.agent.md
+      reviewer.agent.md
+      scanner.agent.md
+    instructions/
+      hooks.instructions.md
+      tests.instructions.md
+      templates.instructions.md
+    skills/
+      systematic-debugging/SKILL.md
+      verification-before-completion/SKILL.md
+      frontend-design/SKILL.md
+      proactive-initiative/SKILL.md
+    copilot-instructions.md
+"""
+import os
+import shutil
+import subprocess
+import sys
+
+
+def _templates_dir():
+    return os.path.join(os.path.dirname(__file__), "templates")
+
+
+def _is_git_repo(cwd):
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--git-dir"],
+            cwd=cwd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        return result.returncode == 0
+    except OSError:
+        return False
+
+
+def _copy_template(src, dst, out):
+    """Copy src to dst unless dst already exists. Prints [create] or [skip]."""
+    if os.path.exists(dst):
+        out.append("[skip]   {}".format(dst))
+        return
+    dst_dir = os.path.dirname(dst)
+    if dst_dir and not os.path.isdir(dst_dir):
+        os.makedirs(dst_dir)
+    shutil.copy2(src, dst)
+    out.append("[create] {}".format(dst))
+
+
+def _touch_gitkeep(path, out):
+    """Create an empty .gitkeep inside path, creating path if needed."""
+    if not os.path.isdir(path):
+        os.makedirs(path)
+    gk = os.path.join(path, ".gitkeep")
+    if os.path.exists(gk):
+        out.append("[skip]   {}".format(gk))
+    else:
+        open(gk, "w").close()
+        out.append("[create] {}".format(gk))
+
+
+def _ensure_vscode_setting(cwd, key, value, out):
+    """Merge a single key/value into .vscode/settings.json, creating it if needed.
+
+    Uses simple JSON load/dump so existing user settings are preserved.
+    Skips if the key is already set to the desired value.
+    """
+    import json
+    vscode_dir = os.path.join(cwd, ".vscode")
+    settings_path = os.path.join(vscode_dir, "settings.json")
+
+    if not os.path.isdir(vscode_dir):
+        os.makedirs(vscode_dir)
+
+    settings = {}
+    if os.path.exists(settings_path):
+        try:
+            with open(settings_path, "r", encoding="utf-8") as f:
+                settings = json.load(f)
+        except (ValueError, OSError):
+            settings = {}
+
+    if settings.get(key) == value:
+        out.append("[skip]   {} ({} already set)".format(settings_path, key))
+        return
+
+    settings[key] = value
+    with open(settings_path, "w", encoding="utf-8") as f:
+        json.dump(settings, f, indent=2)
+        f.write("\n")
+    out.append("[create] {} ({} = {})".format(settings_path, key, json.dumps(value)))
+
+
+def run(cwd=None):
+    if cwd is None:
+        cwd = os.getcwd()
+
+    if not _is_git_repo(cwd):
+        sys.stderr.write(
+            "Error: {} is not a git repository.\n"
+            "Run `git init` first, then re-run `engaku init`.\n".format(cwd)
+        )
+        return 1
+
+    tpl = _templates_dir()
+    out = []
+
+    # ── .ai/ skeleton ────────────────────────────────────────────────────────
+    _copy_template(
+        os.path.join(tpl, "ai", "overview.md"),
+        os.path.join(cwd, ".ai", "overview.md"),
+        out,
+    )
+    _copy_template(
+        os.path.join(tpl, "ai", "engaku.json"),
+        os.path.join(cwd, ".ai", "engaku.json"),
+        out,
+    )
+    _touch_gitkeep(os.path.join(cwd, ".ai", "decisions"), out)
+    _touch_gitkeep(os.path.join(cwd, ".ai", "tasks"), out)
+    _touch_gitkeep(os.path.join(cwd, ".ai", "docs"), out)
+
+    # ── .github/agents/ ──────────────────────────────────────────────────────
+    agents_dir = os.path.join(cwd, ".github", "agents")
+    for name in ("dev.agent.md", "planner.agent.md",
+                   "reviewer.agent.md", "scanner.agent.md"):
+        _copy_template(os.path.join(tpl, "agents", name), os.path.join(agents_dir, name), out)
+
+    # ── .github/instructions/ ─────────────────────────────────────────────
+    instructions_dir = os.path.join(cwd, ".github", "instructions")
+    for name in ("hooks.instructions.md", "tests.instructions.md", "templates.instructions.md"):
+        _copy_template(
+            os.path.join(tpl, "instructions", name),
+            os.path.join(instructions_dir, name),
+            out,
+        )
+
+    # ── .github/skills/ ──────────────────────────────────────────────────────
+    skills_dir = os.path.join(cwd, ".github", "skills")
+    for skill in ("systematic-debugging", "verification-before-completion", "frontend-design", "proactive-initiative"):
+        _copy_template(
+            os.path.join(tpl, "skills", skill, "SKILL.md"),
+            os.path.join(skills_dir, skill, "SKILL.md"),
+            out,
+        )
+
+    # ── .github/copilot-instructions.md ──────────────────────────────────────
+    _copy_template(
+        os.path.join(tpl, "copilot-instructions.md"),
+        os.path.join(cwd, ".github", "copilot-instructions.md"),
+        out,
+    )
+    # ── .vscode/settings.json ── enable agent-scoped hooks (Preview) ─────────
+    _ensure_vscode_setting(cwd, "chat.useCustomAgentHooks", True, out)
+
+    for line in out:
+        sys.stdout.write(line + "\n")
+
+    created = sum(1 for l in out if l.startswith("[create]"))
+    skipped = sum(1 for l in out if l.startswith("[skip]"))
+    sys.stdout.write(
+        "\nDone. {} file(s) created, {} skipped.\n"
+        "Tip: Run the scanner agent in Copilot chat to generate .instructions.md files.\n".format(created, skipped)
+    )
+    return 0
+
+
+def main(argv=None):
+    sys.exit(run())
+

engaku-0.2.0/src/engaku/cmd_inject.py

@@ -0,0 +1,108 @@
+import json
+import os
+import sys
+
+from engaku.utils import parse_frontmatter, read_hook_input
+
+
+def _find_active_task(cwd):
+    """Scan .ai/tasks/*.md for first file with status: in-progress.
+
+    Returns (title, unchecked_lines) tuple or None.
+    """
+    tasks_dir = os.path.join(cwd, ".ai", "tasks")
+    if not os.path.isdir(tasks_dir):
+        return None
+    try:
+        entries = sorted(os.listdir(tasks_dir))
+    except OSError:
+        return None
+    for filename in entries:
+        if not filename.endswith(".md"):
+            continue
+        filepath = os.path.join(tasks_dir, filename)
+        try:
+            with open(filepath, "r", encoding="utf-8") as f:
+                content = f.read()
+        except OSError:
+            continue
+        fm, body = parse_frontmatter(content)
+        if fm is None:
+            continue
+        status = None
+        title = None
+        for line in fm.splitlines():
+            if line.startswith("status:"):
+                status = line[len("status:"):].strip()
+            elif line.startswith("title:"):
+                title = line[len("title:"):].strip()
+        if status != "in-progress":
+            continue
+        if title is None:
+            title = filename[:-3]
+        unchecked = [l for l in body.splitlines() if l.strip().startswith("- [ ]")]
+        return (title, unchecked)
+    return None
+
+
+def run(cwd=None):
+    if cwd is None:
+        cwd = os.getcwd()
+    ai_dir = os.path.join(cwd, ".ai")
+    overview_path = os.path.join(ai_dir, "overview.md")
+
+    context_parts = []
+
+    if os.path.isfile(overview_path):
+        with open(overview_path, "r", encoding="utf-8") as f:
+            content = f.read().strip()
+        if content:
+            context_parts.append(content)
+
+    inner = "\n\n---\n\n".join(context_parts)
+    project_context = "<project-context>\n{}\n</project-context>".format(inner) if inner else ""
+
+    parts = []
+    if project_context:
+        parts.append(project_context)
+
+    active_task = _find_active_task(cwd)
+    if active_task:
+        title, unchecked = active_task
+        task_lines = ["<active-task>", "## {}".format(title)]
+        task_lines.extend(unchecked)
+        task_lines.append("</active-task>")
+        parts.append("\n".join(task_lines))
+
+    additional_context = "\n\n".join(parts)
+
+    # Determine event from stdin so PreCompact can use a different output format.
+    # PreCompact uses the common output format (systemMessage), not hookSpecificOutput.
+    hook_input = read_hook_input()
+    event = hook_input.get("hookEventName", "SessionStart")
+
+    if event == "PreCompact":
+        output = {"systemMessage": additional_context}
+    elif event == "SubagentStart":
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "SubagentStart",
+                "additionalContext": additional_context,
+            }
+        }
+    else:
+        # SessionStart (and default)
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": additional_context,
+            }
+        }
+
+    sys.stdout.write(json.dumps(output, ensure_ascii=False))
+    sys.stdout.flush()
+    return 0
+
+
+def main(argv=None):
+    sys.exit(run())