Project Context Sync

Automatically updates PROJECT_STATE.md after each commit with recent git info and optional AI-generated summaries to track project status and next steps.

Security Scan

The skill's behavior (installing a git hook that can read a local Clawdbot config and POST commit data to a local gateway using a bearer token) is coherent with its stated purpose, but there are mismatches and undeclared runtime requirements that the user should review before installing.

Purpose & Capability

The skill's name and files match its stated purpose (install a post-commit hook that keeps PROJECT_STATE.md up-to-date). However, the shipped scripts read a Clawdbot gateway config (~/.clawdbot/clawdbot.json) and may use a CLAWDBOT_TOKEN — these runtime interactions are related to the AI-summary feature but are not declared in the skill's metadata (no required env vars or binaries are listed).

Instruction Scope

The runtime script (update-context.sh) collects repository metadata (commit messages, changed files, diff stats) and, when AI mode is enabled, will send that context to a local HTTP gateway endpoint (/v1/chat/completions) with a bearer token read from the user's Clawdbot config or from environment (CLAWDBOT_TOKEN). That behavior is within the feature's scope, but it reads a user config file and a secret token (undocumented in metadata) and transmits repository context to a network endpoint — potential data exposure if the gateway is misconfigured or forwards requests externally.

Install Mechanism

No external downloads or remote installs are performed; install.sh copies provided scripts into the repository's .git/hooks and writes .project-context.yml and PROJECT_STATE.md. This is expected for a hook-based tool, but it does modify repo hooks and .gitignore. The install script also uses sed -i '' (BSD sed) which may be platform-specific.

Credentials

skill.json declares no required env vars or binaries, but update-context.sh expects git, curl, and (optionally) jq and reads ~/.clawdbot/clawdbot.json or CLAWDBOT_TOKEN for a bearer token. The token read from the user's home config is effectively a secret; requesting/using it is relevant to AI summaries but the metadata doesn't declare that requirement or ask for user confirmation, so there's a mismatch.

Persistence & Privilege

always is false and the skill only installs a per-repository post-commit hook (no system-wide always-on flag). The hook runs update-context.sh in the background on each commit. It does not modify other skills or global agent settings.

What to consider before installing

What to check before installing: - Review the scripts locally (install.sh, update-context.sh, post-commit-hook.sh). The installer will modify .git/hooks/post-commit and write .project-context.yml and PROJECT_STATE.md into the repo. - Understand AI mode: if ai_summary: true, the hook may read ~/.clawdbot/clawdbot.json or the CLAWDBOT_TOKEN env var and POST commit context (commit messages, changed filenames, diff stats) to http://localhost:<port>/v1/chat/completions with that bearer token. Confirm your Clawdbot gateway is configured to bind only to loopback and is not proxying requests to an external/untrusted service. - Secrets: the script reads a token from your home config — treat that as sensitive. If you don't want any tokens read or network calls, set ai_summary: false in .project-context.yml before installing. - Tooling: the scripts use git, curl, and optionally jq; ensure those are available. Note sed -i '' is BSD/macOS style and may not work unchanged on Linux (the install/uninstall scripts use it). - Test safely: install in a disposable/test repository first to observe behavior. Make a commit and inspect PROJECT_STATE.md and whether any network calls occur (e.g., run update-context.sh manually and watch curl). - Uninstall: uninstall.sh will attempt to remove the hook or the appended lines; it leaves PROJECT_STATE.md and .project-context.yml in place (remove manually if desired). Given the undeclared access to a local token file and the potential to transmit repository information, proceed only if you trust the code and your local Clawdbot gateway configuration. If you want to be conservative, disable ai_summary or inspect/modify update-context.sh to remove or alter the network call before installing.

Keep a living project state document updated after each commit, so any agent (or future session) can instantly understand where things stand.

What It Does

┌─────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│ Git Commit  │ ──▶ │ Post-commit Hook │ ──▶ │ PROJECT_STATE.md    │
│             │     │                  │     │ (auto-updated)      │
└─────────────┘     └──────────────────┘     └─────────────────────┘

After each commit, the hook:

1. Gathers git info (last commit, recent history, branch, changed files)
2. Optionally calls an LLM to generate a smart summary
3. Updates PROJECT_STATE.md in the repo root

Installation

# From the repo you want to enable:
cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/install.sh

Or if you have the skill in your path:

project-context-sync install

This will:

1. Install a post-commit hook in .git/hooks/
2. Create .project-context.yml with default config
3. Create initial PROJECT_STATE.md
4. Add PROJECT_STATE.md to .gitignore

Uninstall

cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/uninstall.sh

Manual Update

Trigger an update without committing:

cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/update-context.sh

Configuration

Edit .project-context.yml in your repo root:

project_context:
  # Use AI to generate smart summaries (default: true)
  ai_summary: true
  
  # How many recent commits to include
  recent_commits: 5
  
  # Include diff stats in context
  include_diff_stats: true
  
  # Sections to include
  sections:
    - last_commit
    - recent_changes
    - current_focus    # AI-generated
    - suggested_next   # AI-generated

AI Summary Mode

With ai_summary: true (default):

• Generates intelligent summaries of what changed
• Infers current focus from recent commit patterns
• Suggests next steps
• Costs tokens but provides rich context
• Requires: Gateway HTTP API enabled (see below)

With ai_summary: false:

• Just logs raw git info
• Fast and free
• Less intelligent but still useful

Enabling the Gateway HTTP API

AI mode uses Clawdbot's OpenAI-compatible endpoint (/v1/chat/completions). This is disabled by default for security. To enable:

// ~/.clawdbot/clawdbot.json
{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true }
      }
    }
  }
}

Security notes:

• The endpoint inherits gateway auth (requires bearer token)
• With bind: "loopback" (default), only local processes can connect
• The script reads the token from ~/.clawdbot/clawdbot.json automatically
• Risk is minimal for local development setups

Output

PROJECT_STATE.md will contain:

# Project State
*Auto-updated by project-context-sync*

## Last Commit
- **Hash:** abc123
- **Message:** Implement isPro check for app blocking
- **Branch:** feature/subscription-gating
- **When:** 2026-01-29 12:34
- **Files changed:** 3

## Recent Changes
- abc123: Implement isPro check for app blocking
- def456: Add PaywallPrompt component
- ...

## Current Focus
[AI-generated summary of what's being worked on]

## Suggested Next Steps
[AI-suggested based on commit patterns]

Notes

• PROJECT_STATE.md is gitignored by default (regenerated locally)
• The hook requires Clawdbot to be running for AI summaries
• Without Clawdbot, falls back to raw git info mode