Skip to content

team-setup.md

Latest commit

 

History

History
167 lines (133 loc) · 7.05 KB

team-setup.md

File metadata and controls

167 lines (133 loc) · 7.05 KB
Raw

Team setup — install agent instructions

graphify-temporal install auto-detects which AI coding assistant you're using and injects instructions so the agent knows how to run temporal enrichment without you having to explain it.

Quick start

# Auto-detect all clients and install instructions
graphify-temporal install

# Install for a specific client
graphify-temporal install --platform opencode
graphify-temporal install --platform claude

# Remove instructions from all clients
graphify-temporal uninstall

Supported clients

Client Instruction file What it gets
Claude Code CLAUDE.md Block + skill (.claude/skills/graphify-temporal/)
OpenCode AGENTS.md Block + plugin (.opencode/plugins/graphify-temporal.js) + skill (.opencode/skills/graphify-temporal/) + opencode.json registration
Codex AGENTS.md ## graphify-temporal block
Gemini CLI GEMINI.md ## graphify-temporal block
Cursor .cursor/rules/graphify-temporal.mdc ## graphify-temporal block
CodeBuddy CODEBUDDY.md ## graphify-temporal block
Copilot .github/copilot-instructions.md ## graphify-temporal block
Windsurf .windsurf/rules/graphify-temporal.md ## graphify-temporal block
Aider AGENTS.md ## graphify-temporal block
Kilo Code AGENTS.md ## graphify-temporal block
Trae AGENTS.md ## graphify-temporal block

How detection works

Each client has one or more marker files/directories. If any marker exists under the project root, the client is considered present. For example:

Client Markers checked
OpenCode .opencode/ directory
Claude Code CLAUDE.md or .claude/ directory
Codex .codex/ directory
Gemini CLI GEMINI.md or .gemini/ directory
Cursor .cursor/ directory or .cursorrules file
CodeBuddy CODEBUDDY.md or .codebuddy/ directory
Copilot .github/copilot-instructions.md
Windsurf .windsurf/ directory
Aider .aider/ directory or .aider.conf.yml
Kilo Code .kilo/ directory
Trae .trae/ directory

What gets injected

The ## graphify-temporal block contains:

  • Setup — pip install git+..., git clone ... && pip install ., and uv venv && uv pip install -e ".[dev]"
  • All enrich, query, timeline, stats commands with examples and agent guidance, including --git for repos where filesystem timestamps are checkout artifacts (cloned repos, CI checkouts) rather than real history
  • Root-cause tracing (impact) — with explicit "use this proactively during debugging, before manually grepping" guidance, since 10 of the 11 supported clients have no runtime hook (see below) and this injected prose is the only lever that gets an agent to reach for impact on its own
  • install / uninstall commands
  • Test command — .venv/bin/pytest tests/ -v
  • Key facts — zero pip deps, idempotent, cross-platform, st_birthtime support, --git requires the git binary but falls back to stat automatically if absent, impact is read-only (never writes to graph.json)

The block is delimited by ## graphify-temporal and the next ## heading. On re-install the block is replaced in-place — never duplicated. On uninstall the block is removed cleanly, preserving one blank line before the next section.

OpenCode plugin

For OpenCode, graphify-temporal install also writes a JavaScript plugin:

.opencode/plugins/graphify-temporal.js

And registers it in .opencode/opencode.json:

{
  "plugin": [
    ".opencode/plugins/graphify-temporal.js"
  ]
}

The plugin hooks into tool.execute.before and checks whether graphify-out/graph.json exists but nodes lack file_mtime or dir_mtime. If so, it reminds the agent to run graphify-temporal enrich before it reaches for raw file reads. The reminder fires once per session.

Not extended for impact, deliberately. A tool.execute.before hook only sees tool calls, never the user's chat text — it structurally cannot detect "the user described a bug involving two related modules," which is exactly the trigger impact needs. That pattern-matching only happens in the LLM's own reading of the conversation, which is what the injected "Root-cause tracing" prose (see above) targets instead. Extending the plugin here would mean guessing at bash-command content for signs of debugging — fragile and unrequested — so it was considered and rejected rather than silently omitted. The skill (see below) is the mechanism that fills this gap: its description is the trigger surface the plugin structurally cannot be.

Skill (OpenCode + Claude Code)

For clients that support agent skills, install also writes a discoverable skill — the same SKILL.md format both clients use:

.opencode/skills/graphify-temporal/SKILL.md
.claude/skills/graphify-temporal/SKILL.md

The skill's frontmatter description names the situations where the agent should reach for the tool on its own — post-/graphify enrichment, time-based questions ("what changed this week"), order-of-work questions (timeline), and root-cause tracing ("X broke Y", "what did I touch") — so query/timeline/ impact get used without the agent having to read the full instruction block. The body carries the same flag heuristics and command examples as the block.

A .graphify-temporal_version marker sits next to SKILL.md (same pattern as graphify's .graphify_version): re-running install after an upgrade rewrites the skill only when the version changed. uninstall removes the skill files and the directory, but preserves any files you added there.

Idempotency

install and uninstall are safe to run multiple times:

  • install twice — the block is replaced with the current version, no duplication
  • install twice (skill) — skipped entirely when the version marker matches
  • uninstall when nothing is installed — succeeds silently
  • install after uninstall — writes a fresh block as if it were the first time

Workflow for a team

  1. One person runs graphify-temporal install and commits the instruction files + .opencode/plugins/ + .opencode/skills/ + .claude/skills/ + opencode.json.
  2. Everyone pulls — their AI assistant immediately knows how to run enrichment.
  3. After modifying code, each developer runs graphify-temporal enrich to keep timestamps current (idempotent, no harm in re-running).

Since every teammate's checkout is itself a git clone, --use-birthtime/ default mtime will show ~the same value for every file that hasn't been touched locally since the clone — not useful for tracing who-wrote-what. For a team repo, prefer:

graphify-temporal enrich --git

This reads dates from the shared commit history instead, so file_mtime and git_commit_date/git_author reflect the team's actual authorship timeline regardless of when each person cloned the repo. See timestamps.md for the resolution order and fallback rules.