mema-kit 1.1.0 → 1.2.0

package/README.md

@@ -91,6 +91,7 @@ claude
 ├── project/               # Stable project knowledge
 │   ├── architecture.md
 │   ├── requirements.md
+│   ├── structure.md
 │   └── decisions/
 ├── agent/                 # Cross-session knowledge
 │   ├── lessons.md

package/bin/cli.js

@@ -10,6 +10,8 @@ const VERSION_COMMENT = `<!-- mema-kit v${VERSION} -->`;
 const packageRoot = path.resolve(__dirname, '..');
 const skillsSource = path.join(packageRoot, 'skills');
 const targetDir = path.join(process.cwd(), '.claude', 'skills');
+const scriptsSource = path.join(packageRoot, 'scripts', 'bash');
+const scriptsTarget = path.join(process.cwd(), 'scripts', 'bash');
 
 // Parse arguments
 const args = process.argv.slice(2);
@@ -42,10 +44,13 @@ function runInstall() {
   // Create target directory
   fs.mkdirSync(targetDir, { recursive: true });
 
-  // Copy all skills
+  // Copy all skills and bash automation scripts
   copySkills();
+  copyScripts();
 
-  console.log('✓ mema-kit skills installed to .claude/skills/');
+  console.log('✓ mema-kit installed:');
+  console.log('    .claude/skills/   — Claude Code skills');
+  console.log('    scripts/bash/     — git automation scripts');
   console.log('');
   console.log('Next step: Open your project in Claude Code and run /mema.onboard');
   console.log('');
@@ -75,10 +80,13 @@ function runUpdate() {
     }
   }
 
-  // Copy (overwrite) all skills
+  // Copy (overwrite) all skills and bash automation scripts
   copySkills();
+  copyScripts();
 
-  console.log(`✓ mema-kit skills updated to v${VERSION}`);
+  console.log(`✓ mema-kit updated to v${VERSION}:`);
+  console.log('    .claude/skills/   — skills updated');
+  console.log('    scripts/bash/     — git automation scripts updated');
   console.log('');
   console.log('  .mema/ and CLAUDE.md were not modified.');
   console.log('');
@@ -107,6 +115,27 @@ function copySkills() {
   }
 }
 
+function copyScripts() {
+  // Create the target scripts/bash/ directory if it doesn't exist
+  fs.mkdirSync(scriptsTarget, { recursive: true });
+
+  const entries = fs.readdirSync(scriptsSource, { withFileTypes: true });
+
+  for (const entry of entries) {
+    // Only copy .sh files — do NOT inject version comments into bash scripts
+    if (!entry.isFile() || !entry.name.endsWith('.sh')) continue;
+
+    const sourcePath = path.join(scriptsSource, entry.name);
+    const targetPath = path.join(scriptsTarget, entry.name);
+
+    fs.writeFileSync(targetPath, fs.readFileSync(sourcePath));
+
+    // Preserve execute permissions — Node's writeFileSync does not copy the source
+    // file's mode, so scripts would be non-executable without this step
+    fs.chmodSync(targetPath, 0o755);
+  }
+}
+
 function addVersionComment(content) {
   // Remove any existing version comment
   const cleaned = content.replace(/<!-- mema-kit v[\d.]+ -->\n?/, '');

package/docs/guide.md

@@ -188,6 +188,7 @@ Every skill reads what previous skills wrote. The index ties it all together.
 ├── project/               # Stable project knowledge
 │   ├── architecture.md
 │   ├── requirements.md
+│   ├── structure.md       # Annotated directory tree
 │   └── decisions/
 ├── agent/                 # Cross-session knowledge
 │   ├── lessons.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mema-kit",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "AI-assisted development lifecycle kit",
   "bin": {
     "mema-kit": "bin/cli.js"
@@ -9,6 +9,7 @@
     "docs/",
     "bin/",
     "skills/",
+    "scripts/",
     "templates/"
   ],
   "keywords": [

package/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# check-prerequisites.sh — Validates environment prerequisites for mema-kit git automation.
+#
+# Called by git automation scripts before running to ensure git, gh, and repo
+# state are suitable. Also useful as a standalone diagnostic tool.
+#
+# USAGE:
+#   check-prerequisites.sh [--need-gh] [--json]
+#
+# OPTIONS:
+#   --need-gh   Also check that gh CLI is installed and authenticated
+#   --json      Emit results as JSON; messages go to stdout
+#
+# MODES:
+#   Flag mode    (--need-gh present): runs checks silently; exits 1 on first failure
+#   Summary mode (no --need-gh):      prints pass/fail for all four checks; always exits 0
+#
+# OUTPUT — text mode, flag:
+#   [silent on success]
+#   [missing] Required tool not found: git
+#   [error]   Not inside a git repository — run from your project root
+#   [missing] Required tool not found: gh
+#   [error]   gh CLI is not authenticated — run: gh auth login
+#
+# OUTPUT — text mode, summary:
+#   [ok]      git is available
+#   [ok]      inside a git repository
+#   [ok]      gh CLI is available
+#   [ok]      gh CLI is authenticated
+#
+# EXIT CODES:
+#   0 — all checks passed (flag mode), or summary printed (summary mode)
+#   1 — a required check failed (flag mode only)
+
+# ---------------------------------------------------------------------------
+# Self-locate and source shared library.
+# ${BASH_SOURCE[0]} is more reliable than $0 when invoked via symlinks or
+# called with an explicit path from a different working directory.
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/common.sh"
+# common.sh activates: set -euo pipefail, git_root, output_result,
+#                      check_prereq, parse_common_args
+
+# ---------------------------------------------------------------------------
+# Pass 1: parse common args.
+# Sets OUTPUT_FORMAT=json if --json is present so all output_result calls
+# below automatically emit JSON.
+# ---------------------------------------------------------------------------
+parse_common_args "$@"
+
+# ---------------------------------------------------------------------------
+# Pass 2: parse script-specific args.
+# Detect --need-gh to know whether to run gh checks and which mode to use.
+# ---------------------------------------------------------------------------
+NEED_GH=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --need-gh) NEED_GH=1 ;;
+    *)         ;;  # --json already handled; unknown flags silently ignored
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Mode selection.
+# Summary mode  = NEED_GH is 0 (no operational flags; --json alone doesn't count)
+#   → print pass/fail for all four checks; always exit 0
+# Flag mode     = NEED_GH is 1
+#   → run only the requested checks; silent on success; exit 1 on first failure
+# ---------------------------------------------------------------------------
+
+if [[ "$NEED_GH" -eq 0 ]]; then
+
+  # -------------------------------------------------------------------------
+  # SUMMARY MODE
+  # Run every check independently (no exit on failure) and print a status
+  # line for each. Useful for standalone debugging: bash check-prerequisites.sh
+  # -------------------------------------------------------------------------
+
+  # Check 1: git on PATH
+  if command -v git &>/dev/null; then
+    output_result "ok" "git is available"
+  else
+    output_result "missing" "git not found — install git to use mema-kit scripts" ', "check": "git"'
+  fi
+
+  # Check 2: inside a git repository
+  if git rev-parse --show-toplevel &>/dev/null 2>&1; then
+    output_result "ok" "inside a git repository"
+  else
+    output_result "error" "not inside a git repository — run from your project root" ', "check": "git-repo"'
+  fi
+
+  # Check 3: gh CLI on PATH
+  if command -v gh &>/dev/null; then
+    output_result "ok" "gh CLI is available"
+  else
+    output_result "missing" "gh CLI not found — install from https://cli.github.com" ', "check": "gh"'
+  fi
+
+  # Check 4: gh authenticated
+  # Guard: only attempt auth check if gh is present — avoids "command not found"
+  # noise when gh is not installed.
+  if ! command -v gh &>/dev/null; then
+    output_result "skipped" "gh CLI not installed — skipping auth check" ', "check": "gh-auth"'
+  elif gh auth status &>/dev/null 2>&1; then
+    output_result "ok" "gh CLI is authenticated"
+  else
+    output_result "error" "gh CLI is not authenticated — run: gh auth login" ', "check": "gh-auth"'
+  fi
+
+  exit 0
+
+fi
+
+# ---------------------------------------------------------------------------
+# FLAG MODE
+# Run only the checks appropriate for the requested flags.
+# Silent on success; output_result + exit 1 on first failure.
+# Callers use: check-prerequisites.sh --need-gh || exit 1
+# ---------------------------------------------------------------------------
+
+# Universal checks: git and repo state are always validated in flag mode.
+check_prereq git || exit 1
+
+if ! git rev-parse --show-toplevel &>/dev/null 2>&1; then
+  output_result "error" "Not inside a git repository — run from your project root" ', "check": "git-repo"'
+  exit 1
+fi
+
+# gh checks: only when --need-gh was passed (always true in flag mode currently,
+# but kept explicit for future extensibility).
+if [[ "$NEED_GH" -eq 1 ]]; then
+  check_prereq gh || exit 1
+
+  if ! gh auth status &>/dev/null 2>&1; then
+    output_result "error" "gh CLI is not authenticated — run: gh auth login" ', "check": "gh-auth"'
+    exit 1
+  fi
+fi
+
+# All checks passed — exit silently.
+exit 0

package/scripts/bash/commit-changes.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# commit-changes.sh — Validates a Conventional Commits message, shows the staged
+#                      diff, runs git commit, and pushes to the current branch.
+#
+# Called by /mema.implement at the end of the per-feature cycle, after all tasks
+# are complete and the user confirms their tests pass.
+#
+# USAGE:
+#   commit-changes.sh [--json] <commit-message>
+#
+# ARGUMENTS:
+#   commit-message  — Quoted Conventional Commits message (Claude generates this).
+#                     Format: type(scope): description
+#                     Example: feat(cli): add --json flag to output
+#
+# OPTIONS:
+#   --json   Emit result as JSON to stdout; all other messages go to stderr.
+#
+# OUTPUT — text mode:
+#   [ok]    Committed: abc1234 — feat(cli): add --json flag to output
+#   [error] Commit message format invalid. Expected: type(scope): description
+#   [error] Nothing is staged. Stage your changes before committing.
+#
+# OUTPUT — json mode:
+#   {"status": "ok", "message": "...", "committed": true, "sha": "abc1234", "branch": "feat-003-name", "commit_message": "feat: initial implementation"}
+#   {"status": "error", "message": "..."}
+#
+# EXIT CODES:
+#   0 — commit and push succeeded
+#   1 — validation failed, nothing staged, or unexpected error
+
+# ---------------------------------------------------------------------------
+# Self-locate and source shared library.
+# ${BASH_SOURCE[0]} is more reliable than $0 when invoked via symlinks or
+# called with an explicit path from a different working directory.
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/common.sh"
+# common.sh activates: set -euo pipefail, git_root, output_result,
+#                      check_prereq, parse_common_args
+
+# ---------------------------------------------------------------------------
+# Pass 1: Parse common args.
+# parse_common_args uses a for-loop and does NOT consume "$@", so the full
+# argument list is still available for our own parsing pass below.
+# Sets OUTPUT_FORMAT=json if --json is present.
+# ---------------------------------------------------------------------------
+parse_common_args "$@"
+
+# Verify git is available before doing anything else.
+check_prereq git || exit 1
+
+# ---------------------------------------------------------------------------
+# Pass 2: Parse script-specific args.
+# Extracts the commit message positional arg. --json is re-encountered here
+# and skipped — it was already handled by parse_common_args above.
+# ---------------------------------------------------------------------------
+commit_message=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json)
+      # Already handled by parse_common_args; skip.
+      shift
+      ;;
+    -*)
+      # Unknown flag — silently ignore to stay forward-compatible.
+      shift
+      ;;
+    *)
+      # Positional argument: the commit message (take the first one found).
+      if [[ -z "$commit_message" ]]; then
+        commit_message="$1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Input validation: require a non-empty commit message.
+# ---------------------------------------------------------------------------
+if [[ -z "$commit_message" ]]; then
+  echo "Error: missing required argument <commit-message>" >&2
+  echo "Usage: commit-changes.sh [--json] <commit-message>" >&2
+  echo "Example: commit-changes.sh \"feat(cli): add --json flag to output\"" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Conventional Commits format validation.
+# Pattern: type(optional-scope): description (description 1–72 chars)
+# This check runs before any git operation so that an invalid message
+# is rejected without touching the repository.
+#
+# NOTE: The regex variable must NOT be quoted in the =~ test; quoting it
+# would cause bash to treat it as a literal string rather than a pattern.
+# ---------------------------------------------------------------------------
+COMMIT_PATTERN='^(feat|fix|docs|style|refactor|test|chore|build|ci|perf|revert)(\(.+\))?: .{1,72}$'
+if [[ ! "$commit_message" =~ $COMMIT_PATTERN ]]; then
+  output_result "error" \
+    "Commit message format invalid. Expected: type(scope): description — e.g. feat(cli): add --json flag"
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Staged diff check.
+# git diff --staged --stat shows a human-readable summary of staged files.
+# If the output is empty, nothing is staged and we should not create an empty
+# commit. Diagnostic output always goes to stderr so it never taints JSON stdout.
+# ---------------------------------------------------------------------------
+staged="$(git diff --staged --stat)"
+if [[ -z "$staged" ]]; then
+  output_result "error" \
+    "Nothing is staged. Use git add to stage your changes before committing."
+  exit 1
+fi
+
+echo "Staged changes:" >&2
+echo "$staged" >&2
+
+# ---------------------------------------------------------------------------
+# Commit.
+# set -euo pipefail (inherited from common.sh) ensures any failure here exits
+# immediately with a non-zero code rather than silently continuing.
+# ---------------------------------------------------------------------------
+git commit -m "$commit_message"
+
+# ---------------------------------------------------------------------------
+# Push.
+# --set-upstream is idempotent: sets the remote tracking branch on the first
+# push, and is effectively a no-op on subsequent pushes if upstream is already
+# set. This handles the case where create-feature-branch.sh created a local
+# branch that has never yet been pushed to origin.
+# ---------------------------------------------------------------------------
+current_branch="$(git rev-parse --abbrev-ref HEAD)"
+git push --set-upstream origin "$current_branch"
+
+# ---------------------------------------------------------------------------
+# Capture the short SHA immediately after commit so the output reflects the
+# exact commit that was just created.
+# ---------------------------------------------------------------------------
+sha="$(git rev-parse --short HEAD)"
+
+output_result "ok" \
+  "Committed: ${sha} — ${commit_message}" \
+  ", \"committed\": true, \"sha\": \"${sha}\", \"branch\": \"${current_branch}\", \"commit_message\": \"${commit_message}\""

package/scripts/bash/common.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# common.sh — Shared bash library for mema-kit git automation scripts.
+#
+# USAGE (from any git automation script in scripts/bash/):
+#   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+#   source "${SCRIPT_DIR}/common.sh"
+#
+# After sourcing, call parse_common_args "$@" to handle the --json flag,
+# then use git_root, output_result, and check_prereq as needed.
+
+# ---------------------------------------------------------------------------
+# Double-source guard — safe to source multiple times.
+#
+# Uses ${COMMON_SH_LOADED:-} instead of $COMMON_SH_LOADED to avoid an
+# "unbound variable" error from set -u on the first source, before COMMON_SH_LOADED
+# has been defined.
+# ---------------------------------------------------------------------------
+[[ -n "${COMMON_SH_LOADED:-}" ]] && return 0
+COMMON_SH_LOADED=1
+
+# Strict mode: exit on any error (-e), treat unbound variables as errors (-u),
+# and propagate pipe failures (-o pipefail). Scripts that source this file
+# inherit these settings automatically.
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# git_root
+#
+# Prints the absolute path of the current git repository root to stdout.
+# Exits non-zero with an error message to stderr if not inside a git repo.
+#
+# Example:
+#   root="$(git_root)" || exit 1
+#   cd "$root"
+# ---------------------------------------------------------------------------
+git_root() {
+  # 2>/dev/null suppresses git's own "not a git repository" error message
+  # so we can emit a consistent error instead.
+  git rev-parse --show-toplevel 2>/dev/null || {
+    echo "Error: not inside a git repository" >&2
+    return 1
+  }
+}
+
+# ---------------------------------------------------------------------------
+# output_result <status> <message> [extra_json]
+#
+# Prints a result in JSON or plain-text format depending on OUTPUT_FORMAT.
+#
+# Arguments:
+#   status     — short status string (e.g. "ok", "error", "missing")
+#   message    — human-readable description
+#   extra_json — optional; pre-formatted JSON fragment starting with ", "
+#                e.g. ', "tool": "gh"'  is appended inside the JSON object
+#
+# Output format is controlled by OUTPUT_FORMAT (default: text):
+#   text → [status] message
+#   json → {"status": "…", "message": "…"[, extra_json fields]}
+#
+# Set OUTPUT_FORMAT=json by calling parse_common_args "$@" at the top of
+# each script, or by setting it directly before calling output_result.
+#
+# Examples:
+#   output_result "ok" "Branch created: 001-my-feature"
+#   output_result "missing" "Tool not found: gh" ', "tool": "gh"'
+# ---------------------------------------------------------------------------
+output_result() {
+  local status="$1"
+  local message="$2"
+  local extra="${3:-}"  # optional extra JSON fragment, e.g. ', "branch": "001-foo"'
+
+  if [[ "${OUTPUT_FORMAT:-text}" == "json" ]]; then
+    echo "{\"status\": \"${status}\", \"message\": \"${message}\"${extra}}"
+  else
+    echo "[${status}] ${message}"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# check_prereq <tool>
+#
+# Checks that <tool> is available on $PATH.
+# Returns 0 if found; calls output_result and returns 1 if missing.
+#
+# Example:
+#   check_prereq git || exit 1
+#   check_prereq gh  || exit 1   # non-fatal: caller may choose to degrade
+# ---------------------------------------------------------------------------
+check_prereq() {
+  local tool="$1"
+
+  if ! command -v "$tool" &>/dev/null; then
+    # ', "tool": "gh"' extends the JSON object so callers can read the tool name
+    output_result "missing" "Required tool not found: ${tool}" ", \"tool\": \"${tool}\""
+    return 1
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# parse_common_args "$@"
+#
+# Parses arguments shared across all git automation scripts.
+# Currently handles:
+#   --json   sets OUTPUT_FORMAT=json so output_result emits JSON
+#
+# NOTE: Call this at the top of each script, before using output_result,
+# so that the output format is set correctly for all subsequent calls.
+# Unknown flags are silently ignored — scripts can extend this with their
+# own argument parsing after calling parse_common_args.
+#
+# Example:
+#   parse_common_args "$@"
+#   # OUTPUT_FORMAT is now set; proceed to parse script-specific args
+# ---------------------------------------------------------------------------
+parse_common_args() {
+  for arg in "$@"; do
+    case "$arg" in
+      --json) OUTPUT_FORMAT=json ;;
+      *)      ;;  # ignore unknown flags
+    esac
+  done
+}

package/scripts/bash/create-feature-branch.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# create-feature-branch.sh — Creates a new git feature branch for the mema-kit per-feature cycle.
+#
+# Called by /mema.specify at the start of a new feature to create a consistently
+# named local branch. Designed to be idempotent and safe to re-run.
+#
+# USAGE:
+#   create-feature-branch.sh <NNN> <feature-name> [--short-name <name>] [--json]
+#
+# ARGUMENTS:
+#   NNN           — Feature number (e.g. "002")
+#   feature-name  — Kebab-case feature name (e.g. "create-feature-branch")
+#
+# OPTIONS:
+#   --short-name <name>  Override the branch name suffix (default: feature-name arg)
+#   --json               Emit result as JSON to stdout; all other messages go to stderr
+#
+# OUTPUT — text mode:
+#   [created] Branch created: feat-002-create-feature-branch
+#   [exists]  Branch already exists: feat-002-create-feature-branch
+#   [error]   Working directory is dirty — commit or stash changes before creating a branch
+#
+# OUTPUT — json mode:
+#   {"status": "created", "message": "...", "branch": "feat-002-name", "base": "main"}
+#   {"status": "exists",  "message": "...", "branch": "feat-002-name", "base": "main"}
+#   {"status": "error",   "message": "..."}
+#
+# EXIT CODES:
+#   0 — branch created or already existed (idempotent success)
+#   1 — dirty working directory, missing args, missing git, or unexpected error
+
+# ---------------------------------------------------------------------------
+# Self-locate and source shared library.
+# ${BASH_SOURCE[0]} is more reliable than $0 when invoked via symlinks or
+# called with an explicit path from a different working directory.
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/common.sh"
+# common.sh activates: set -euo pipefail, git_root, output_result,
+#                      check_prereq, parse_common_args
+
+# ---------------------------------------------------------------------------
+# Pass 1: Parse common args.
+# parse_common_args uses a for-loop and does NOT consume "$@", so the full
+# argument list is still available for our own parsing pass below.
+# Sets OUTPUT_FORMAT=json if --json is present.
+# ---------------------------------------------------------------------------
+parse_common_args "$@"
+
+# Verify git is available before doing anything else.
+check_prereq git || exit 1
+
+# ---------------------------------------------------------------------------
+# Pass 2: Parse script-specific args.
+# Extracts positional args and --short-name. --json is re-encountered here
+# and skipped — it was already handled by parse_common_args above.
+# ---------------------------------------------------------------------------
+feature_num=""
+feature_name=""
+short_name_override=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json)
+      # Already handled by parse_common_args; skip.
+      shift
+      ;;
+    --short-name)
+      # Guard against --short-name with no following value.
+      if [[ $# -lt 2 ]]; then
+        echo "Error: --short-name requires a value" >&2
+        exit 1
+      fi
+      short_name_override="$2"
+      shift 2
+      ;;
+    -*)
+      # Unknown flag — silently ignore to stay forward-compatible.
+      shift
+      ;;
+    *)
+      # Positional argument: first is NNN, second is feature-name.
+      if [[ -z "$feature_num" ]]; then
+        feature_num="$1"
+      elif [[ -z "$feature_name" ]]; then
+        feature_name="$1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Input validation.
+# Both a feature number and a branch name suffix are required. The suffix
+# comes from either <feature-name> or --short-name.
+# ---------------------------------------------------------------------------
+if [[ -z "$feature_num" ]]; then
+  echo "Error: missing required argument <NNN> (feature number, e.g. 002)" >&2
+  echo "Usage: create-feature-branch.sh <NNN> <feature-name> [--short-name <name>] [--json]" >&2
+  exit 1
+fi
+
+if [[ -z "$feature_name" && -z "$short_name_override" ]]; then
+  echo "Error: missing required argument <feature-name> (or use --short-name <name>)" >&2
+  echo "Usage: create-feature-branch.sh <NNN> <feature-name> [--short-name <name>] [--json]" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Capture base branch and construct target branch name.
+# base_branch is captured BEFORE any git operations so the output correctly
+# records the branch we diverged from, even after we switch branches.
+# ---------------------------------------------------------------------------
+base_branch="$(git rev-parse --abbrev-ref HEAD)"
+
+# Use --short-name override if provided; fall back to the feature-name positional arg.
+branch_name="feat-${feature_num}-${short_name_override:-${feature_name}}"
+
+# ---------------------------------------------------------------------------
+# Dirty-dir guard.
+# git status --porcelain is intentionally conservative: it reports untracked
+# files (??), staged changes, and unstaged changes. Any output means the
+# working directory is not clean enough for a safe branch creation.
+# The dirty file list always goes to stderr so it never taints JSON stdout.
+# ---------------------------------------------------------------------------
+dirty="$(git status --porcelain)"
+if [[ -n "$dirty" ]]; then
+  echo "Dirty files:" >&2
+  echo "$dirty" >&2
+  output_result "error" "Working directory is dirty — commit or stash changes before creating a branch"
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Idempotency check.
+# git branch --list "name" emits the branch name (with leading whitespace)
+# if it exists locally, or empty output if it does not. grep -q . tests for
+# any non-empty output (the dot matches any character, so any output passes).
+# If the branch exists: checkout (no-op if already on it; git returns 0) and exit 0.
+# ---------------------------------------------------------------------------
+if git branch --list "${branch_name}" | grep -q .; then
+  git checkout "${branch_name}"
+  output_result "exists" \
+    "Branch already exists: ${branch_name}" \
+    ", \"branch\": \"${branch_name}\", \"base\": \"${base_branch}\""
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Branch creation.
+# git checkout -b creates the branch and switches to it in one atomic step.
+# set -euo pipefail (inherited from common.sh) ensures any failure exits
+# immediately with a non-zero code rather than silently continuing.
+# ---------------------------------------------------------------------------
+git checkout -b "${branch_name}"
+
+output_result "created" \
+  "Branch created: ${branch_name}" \
+  ", \"branch\": \"${branch_name}\", \"base\": \"${base_branch}\""

package/scripts/bash/create-pr.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# create-pr.sh — Creates a draft GitHub pull request for the current feature branch.
+#
+# Called by /mema.implement after all tasks are complete and the branch has been
+# committed and pushed via commit-changes.sh. Designed to be idempotent and safe
+# to re-run: if a PR already exists for the current branch, the script exits 0
+# without creating a duplicate.
+#
+# Degrades gracefully when gh is not installed or the remote is not GitHub — prints
+# manual steps to stderr and exits 0 rather than failing hard.
+#
+# USAGE:
+#   create-pr.sh [--json] [--base <branch>] <title> [body]
+#
+# ARGUMENTS:
+#   title  — PR title (required); Claude supplies this
+#   body   — PR body/description (optional); defaults to empty string
+#
+# OPTIONS:
+#   --base <branch>  Base branch for the PR (default: main)
+#   --json           Emit result as JSON to stdout; all other messages go to stderr
+#
+# OUTPUT — text mode:
+#   [created] PR opened (draft): https://github.com/owner/repo/pull/42
+#   [exists]  PR already open: https://github.com/owner/repo/pull/42
+#   [missing] gh not installed — see manual steps above
+#   [skipped] Non-GitHub remote — PR creation skipped
+#   [error]   Branch 'feat-004-create-pr' has no remote tracking ref. Push first.
+#
+# OUTPUT — json mode:
+#   {"status": "created", "message": "...", "created": true,  "url": "...", "branch": "...", "draft": true}
+#   {"status": "exists",  "message": "...", "created": false, "url": "...", "branch": "...", "draft": true}
+#   {"status": "missing", "message": "...", "created": false, "branch": "..."}
+#   {"status": "skipped", "message": "...", "created": false, "branch": "...", "manual_url": "..."}
+#   {"status": "error",   "message": "..."}
+#
+# EXIT CODES:
+#   0 — PR created, PR already exists, gh missing (graceful), or non-GitHub remote (graceful)
+#   1 — branch not pushed, missing title, git not found, or unexpected error
+
+# ---------------------------------------------------------------------------
+# Self-locate and source shared library.
+# ${BASH_SOURCE[0]} is more reliable than $0 when invoked via symlinks or
+# called with an explicit path from a different working directory.
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/common.sh"
+# common.sh activates: set -euo pipefail, git_root, output_result,
+#                      check_prereq, parse_common_args
+
+# ---------------------------------------------------------------------------
+# Pass 1: Parse common args.
+# parse_common_args uses a for-loop and does NOT consume "$@", so the full
+# argument list is still available for our own parsing pass below.
+# Sets OUTPUT_FORMAT=json if --json is present.
+# ---------------------------------------------------------------------------
+parse_common_args "$@"
+
+# Verify git is available before doing anything else.
+check_prereq git || exit 1
+
+# ---------------------------------------------------------------------------
+# Pass 2: Parse script-specific args.
+# Extracts positional args (title, body) and --base. --json is re-encountered
+# here and skipped — it was already handled by parse_common_args above.
+# ---------------------------------------------------------------------------
+title=""
+body=""
+base_branch="main"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json)
+      # Already handled by parse_common_args; skip.
+      shift
+      ;;
+    --base)
+      # Guard against --base with no following value.
+      if [[ $# -lt 2 ]]; then
+        echo "Error: --base requires a value" >&2
+        exit 1
+      fi
+      base_branch="$2"
+      shift 2
+      ;;
+    -*)
+      # Unknown flag — silently ignore to stay forward-compatible.
+      shift
+      ;;
+    *)
+      # Positional argument: first is title, second is body.
+      if [[ -z "$title" ]]; then
+        title="$1"
+      elif [[ -z "$body" ]]; then
+        body="$1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Input validation: require a non-empty PR title.
+# ---------------------------------------------------------------------------
+if [[ -z "$title" ]]; then
+  echo "Error: missing required argument <title>" >&2
+  echo "Usage: create-pr.sh [--json] [--base <branch>] <title> [body]" >&2
+  echo "Example: create-pr.sh \"feat(cli): add --json flag\" \"Adds --json output mode\"" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Capture current branch. Done here (before any conditional exits) so it is
+# available in all output paths below.
+# ---------------------------------------------------------------------------
+current_branch="$(git rev-parse --abbrev-ref HEAD)"
+
+# ---------------------------------------------------------------------------
+# gh availability check — graceful degradation.
+# Unlike check_prereq (which exits 1 on failure), we exit 0 here because a
+# missing gh CLI is not an error — the user can create the PR manually.
+# Manual instructions always go to stderr; the machine result goes to stdout.
+# ---------------------------------------------------------------------------
+if ! command -v gh &>/dev/null; then
+  echo "gh CLI not found. To create a PR manually:" >&2
+  echo "  1. Ensure your branch is pushed: git push -u origin ${current_branch}" >&2
+  echo "  2. Open a PR at: https://github.com/<owner>/<repo>/compare/${current_branch}" >&2
+  output_result "missing" "gh not installed — see manual steps above" \
+    ", \"created\": false, \"branch\": \"${current_branch}\""
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Remote URL check — non-GitHub detection.
+# gh pr create only works with GitHub-hosted repos. If the origin remote is
+# GitLab, Bitbucket, or anything else, degrade gracefully instead of failing.
+# The || true prevents set -e from killing the script if origin doesn't exist.
+# ---------------------------------------------------------------------------
+remote_url="$(git remote get-url origin 2>/dev/null || true)"
+if [[ "$remote_url" != *github.com* ]]; then
+  echo "Remote is not GitHub (${remote_url:-no origin remote found})." >&2
+  echo "To create a PR manually, visit your hosting provider and open a PR for: ${current_branch}" >&2
+  output_result "skipped" "Non-GitHub remote — PR creation skipped" \
+    ", \"created\": false, \"branch\": \"${current_branch}\", \"manual_url\": \"${remote_url:-}\""
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Branch-pushed check — hard error (exit 1).
+# If the branch has no remote tracking ref, there is nothing gh can PR against.
+# This is a real error state, not a graceful-degradation case — the user must
+# push the branch first (commit-changes.sh handles this automatically).
+# ---------------------------------------------------------------------------
+if ! git rev-parse --abbrev-ref --symbolic-full-name "@{u}" &>/dev/null; then
+  output_result "error" \
+    "Branch '${current_branch}' has no remote tracking ref. Push the branch first (commit-changes.sh handles this)."
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Idempotency check — detect existing open PR before creating.
+# gh pr list --json url --jq '.[0].url' extracts the URL of the first result.
+# The || true prevents set -e from aborting if gh returns non-zero (e.g. no
+# open PRs found for this branch returns an empty list, not an error, but
+# older gh versions may exit non-zero in edge cases).
+# ---------------------------------------------------------------------------
+existing_url="$(gh pr list --head "${current_branch}" --state open --json url --jq '.[0].url' 2>/dev/null || true)"
+if [[ -n "$existing_url" ]]; then
+  output_result "exists" "PR already open: ${existing_url}" \
+    ", \"created\": false, \"url\": \"${existing_url}\", \"branch\": \"${current_branch}\", \"draft\": true"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Create the draft PR.
+# gh pr create prints the new PR URL to stdout; we capture it directly.
+# Diagnostic progress messages from gh go to stderr automatically.
+# set -euo pipefail (inherited from common.sh) ensures any failure here exits
+# immediately rather than silently continuing with an empty pr_url.
+# ---------------------------------------------------------------------------
+pr_url="$(gh pr create --draft --title "${title}" --body "${body:-}" --base "${base_branch}")"
+
+output_result "created" "PR opened (draft): ${pr_url}" \
+  ", \"created\": true, \"url\": \"${pr_url}\", \"branch\": \"${current_branch}\", \"draft\": true"

package/skills/_memory-protocol.md

@@ -84,6 +84,12 @@ Update `.mema/index.md` to reflect all changes made in Phase 3. This is **mandat
 - **UPDATE** when the stack or requirements change.
 - Keep current state only — these are reference documents, not history logs.
 
+### project/structure.md — Replace curation
+- **UPDATE** when directories or key files are added, renamed, or removed.
+- Keep current state only — this is a navigation reference, not a history log.
+- **NOOP** if no structural change occurred in this session.
+- Never delete — if the project structure is unknown, leave the file with a minimal tree rather than removing it.
+
 ### agent/lessons.md and agent/patterns.md — Consolidation curation
 - **Merge similar lessons.** "Drizzle needs type casting" and "Drizzle enum handling requires explicit cast" are the same lesson — keep one entry with both examples.
 - **UPDATE** with new examples when the same pattern/lesson recurs.

package/skills/mema.create-skill/SKILL.md

@@ -292,6 +292,10 @@ Follow the curation rules in `_memory-protocol.md`.
 
 **If a skill file was written** (user did not CANCEL):
 - ADD/UPDATE `agent/patterns.md` with a lightweight record: skill name, complexity level, one-sentence purpose, action taken (`created` / `enhanced` / `overwritten`), date (`YYYY-MM-DD`)
+- UPDATE `project/structure.md`:
+  - Add `├── [skill-name]/   — [skill purpose, one clause]` to the `.claude/skills/` subtree in `## Directory Tree`
+  - Add entry to `## Where to Find X`: `**[Skill name] skill:** .claude/skills/[skill-name]/SKILL.md`
+  - If `project/structure.md` does not exist, NOOP (structure.md is created by `/mema.onboard`)
 
 **If no file was written** (user cancelled at any step):
 - NOOP — no memory changes
@@ -301,4 +305,5 @@ Follow the curation rules in `_memory-protocol.md`.
 Update `.mema/index.md`:
 1. Re-read the current index
 2. If `agent/patterns.md` was modified, update its summary entry
-3. Update the `**Updated:**` date
+3. If `project/structure.md` was modified, update its summary entry
+4. Update the `**Updated:**` date

package/skills/mema.implement/SKILL.md

@@ -124,11 +124,30 @@ All [N] tasks implemented.
 
 ### Files changed
 [List of files created or modified]
-
-Archive this feature? (moves to archive/ and removes from active features)
 ```
 
-2. If user confirms, archive in Phase 3.
+2. **Git Automation Checkpoint:**
+   Check if `scripts/bash/commit-changes.sh` exists (use Glob: `scripts/bash/commit-changes.sh`):
+
+   **If found:**
+   - Ask the user: "All [N] tasks are complete. Please confirm your tests pass before I commit. (yes/no)"
+   - If **yes**:
+     - Compose a Conventional Commits message: `feat(<feature-name>): <brief description from spec Purpose>`
+     - Stage implementation files: run `git add <file> ...` for each file created or modified during this implementation (review the progress log in `status.md` for the file list)
+     - Run: `bash scripts/bash/commit-changes.sh --json "<commit_message>"`
+     - On `status: "ok"`: report "Committed [sha]." and print "**To undo: `git reset HEAD~1`**"
+       Then ask: "Would you like to open a draft PR? (yes/no)"
+       - If **yes** and `scripts/bash/create-pr.sh` exists:
+         Generate a PR title (same as the commit message description) and a short body summarising what was built, then run: `bash scripts/bash/create-pr.sh --json "<title>" "<body>"`
+         Handle all statuses: `created` → report URL; `exists` → report existing URL; `missing` → display the manual steps printed to stderr; `skipped` → note non-GitHub remote; `error` → report error
+       - If `create-pr.sh` not found: note "Run `npx mema-kit` to install PR automation scripts."
+     - On `status: "error"`: report the error; do NOT proceed to archiving
+   - If **no**: note "Skipping commit — remember to run `git add` + `git commit` + `git push` manually before opening a PR."
+
+   **If not found:** note: "Git scripts not installed — run `npx mema-kit` to enable automatic commit and PR creation."
+
+3. Archive this feature? (moves to `archive/` and removes from active features)
+   If user confirms, archive in Phase 3.
 
 ### 2h: Learn
 
@@ -143,6 +162,7 @@ Follow curation rules in `_memory-protocol.md`:
 
 - **Decisions made** during implementation → ADD to `project/decisions/YYYY-MM-DD-short-name.md`
 - **Architecture changes** → UPDATE `project/architecture.md`
+- **Structural changes** (new files, directories, or moves) → UPDATE `project/structure.md`: add/remove/rename the affected entries in `## Directory Tree` and `## Where to Find X`. If nothing structural changed, NOOP.
 - **Lessons learned** → ADD/UPDATE `agent/lessons.md`
 - **Patterns discovered** → ADD/UPDATE `agent/patterns.md`
 - **Task progress** → UPDATE `features/NNN-name/status.md` (done in 2f)

package/skills/mema.onboard/SKILL.md

@@ -220,6 +220,39 @@ Using scan findings, create files with **real content** (not empty placeholders)
 - [Constraint discovered]
 ```
 
+### `.mema/project/structure.md`
+
+Using the directory scan from Step 5b, write an annotated repo tree and navigation guide:
+
+```
+# Repository Structure
+
+**Status:** active | **Updated:** [today]
+
+## Directory Tree
+
+```
+[project-name]/
+[2–3 level annotated tree derived from Step 5b scan]
+```
+
+## Entry Points
+
+[Key files per subsystem, e.g.:]
+- `[entry file]` — [what it does]
+
+## Source vs. Generated
+
+- **Source:** [source dirs]
+- **Generated:** [build output, node_modules, etc.]
+- **Gitignored:** `.mema/`, [other gitignored items]
+
+## Where to Find X
+
+[Quick-reference for the top subsystems found during scan:]
+- **[Component type]:** `[path/]`
+```
+
 ### `.mema/agent/lessons.md`
 
 ```
@@ -262,6 +295,7 @@ Build the index from files just created:
 ## Project Knowledge
 - `project/architecture.md` — [one-line stack/architecture summary]
 - `project/requirements.md` — [one-line purpose summary]
+- `project/structure.md` — [one-line: e.g. "Annotated repo tree, 3 top-level dirs"]
 
 ## Agent Knowledge
 - `agent/lessons.md` — [N] lessons recorded
@@ -336,6 +370,7 @@ Print a summary of what was done:
 mema-kit initialized!
 
 [check] .mema/ structure created (product/, features/, project/, agent/)
+[check] project/structure.md generated
 [check] CLAUDE.md [generated / updated / already configured]
 [check] .gitignore updated
 

package/skills/mema.recall/SKILL.md

@@ -42,6 +42,7 @@ Read the following (skip any that don't exist):
 
 1. `.mema/project/architecture.md` — tech stack, structure, architecture pattern
 2. `.mema/project/requirements.md` — project purpose and constraints
+3. `.mema/project/structure.md` — annotated directory tree and navigation guide
 
 ## Step 5: Load Additional Files (Full Mode Only)
 
@@ -104,6 +105,13 @@ Stack: [tech stack from architecture.md]
 Stack: [tech stack]
 Architecture: [pattern]
 
+### Repository Structure
+[If project/structure.md exists:]
+[Top-level tree from ## Directory Tree (first level only)]
+Where to find:
+[Entries from ## Where to Find X, condensed to one line each]
+[If project/structure.md does not exist: omit section]
+
 ### Recent Decisions
 [For each decision file, list:]
 - **[Decision title]** — [one-line summary]

package/skills/mema.specify/SKILL.md

@@ -96,10 +96,24 @@ Write `.mema/features/NNN-name/spec.md`:
 [What this feature deliberately does NOT include]
 ```
 
+### Create Feature Branch (if scripts available)
+
+After saving `spec.md`, create (or check out) the feature branch:
+
+1. Parse the feature number and name from the feature directory path:
+   - Example: `features/005-skill-integration/` → NNN = `005`, name = `skill-integration`
+2. Check if `scripts/bash/create-feature-branch.sh` exists (use Glob: `scripts/bash/create-feature-branch.sh`)
+3. **If found:** run: `bash scripts/bash/create-feature-branch.sh <NNN> <name> --json`
+   - `status: "created"` → include in confirmation: "Branch created: feat-NNN-name"
+   - `status: "exists"` → include: "Branch already exists: feat-NNN-name (checked out)"
+   - `status: "error"` → surface the error message; note that spec.md was saved successfully; tell user to resolve the issue (e.g. commit or stash dirty files) and re-run `/mema.specify`
+4. **If not found:** note: "Git scripts not installed — run `npx mema-kit` to enable automatic branch creation."
+
 ### Confirm to User
 
 ```
 Spec saved: features/[NNN-name]/spec.md
+Branch:     [feat-NNN-name (created) | feat-NNN-name (exists) | error — see above | scripts not installed]
 
 [Feature name]: [one-line purpose summary]
 [N] acceptance criteria defined

package/templates/index.md

@@ -19,6 +19,7 @@
 
 - `project/architecture.md` — Project architecture (not yet documented)
 - `project/requirements.md` — Project requirements (not yet documented)
+- `project/structure.md` — Annotated directory tree (not yet documented)
 
 ## Agent Knowledge
 

package/templates/project/structure.md

@@ -0,0 +1,32 @@
+# Repository Structure
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Directory Tree
+
+<!-- Annotated 2–3 level tree. Update when directories are added or removed. -->
+<!-- Format: path/  — description -->
+
+```
+project-root/
+├── src/           — [description]
+│   └── ...
+└── package.json   — [description]
+```
+
+## Entry Points
+
+<!-- Key files to start reading for each subsystem -->
+- `path/to/entry.file` — [what it does]
+
+## Source vs. Generated
+
+<!-- What is hand-written vs. auto-generated vs. gitignored -->
+- **Source:** `src/`, `tests/`
+- **Generated:** `dist/`, `node_modules/`
+- **Gitignored:** `.mema/`, `node_modules/`, `.env`
+
+## Where to Find X
+
+<!-- Quick-reference for navigating the codebase -->
+- **[Component type]:** `path/to/dir/`