Skip to main content
skill CX Codex

corezoid-git-context — Claude Code skill

The corezoid-git-context skill records meaningful Corezoid session changes in stage documentation and syncs the git mirror. Use it after real process work.

MIT ★ 74 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add corezoid/corezoid-ai-plugin
/plugin install corezoid@corezoid
Open on GitHub

What corezoid-git-context does

The skill reviews a session after corezoid-edit, corezoid-create, or corezoid-review and updates the active stage documentation. Its write scope is _ext/docs/, with support for context.md, invariants.md, decisions.md, dependencies.md, and issues.md. It can add an architectural decision or external dependency, revise a constraint, and mark a resolved issue.

It first synchronizes the git context with git-pull-context, reads the files that exist, and presents the planned edits before writing them. The workflow uses actions of the cz-git-context MCP tool: read-context-file, update-context-file, git-pull-context, and git-push-context. The session must contain substantial work, such as an actual create-process or push-process call, a chosen architectural approach, or an issue found or resolved. Updates are skipped when the current stage lacks git_stage_path.

What it helps with

  • record architectural choices made during process work
  • add a newly discovered external dependency
  • mark a found or resolved issue in stage docs
  • revise the stage purpose when it changes
  • sync context files with the git mirror

Example prompts for the agent

  • Update the context after deploying the process and show the complete change plan.
  • Save the context: we chose a different architecture and found a new external API.
  • Before we wrap up, update the stage docs and push the context to git.

How to install corezoid-git-context

1Plugin marketplace

/plugin marketplace add corezoid/corezoid-ai-plugin
/plugin install corezoid@corezoid

This installs the whole corezoid plugin with all its skills

2Skills CLI (Vercel)

npx skills add corezoid/corezoid-ai-plugin --skill corezoid-git-context -a claude-code

3Manually: put the files in place

~/.claude/skills/corezoid-git-context/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/corezoid-git-context/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about corezoid-git-context

How do I install corezoid-git-context in Claude Code?

Add the marketplace with /plugin marketplace add corezoid/corezoid-ai-plugin, then install the plugin with /plugin install corezoid@corezoid.

What does corezoid-git-context do?

It examines a substantial session and maintains the active stage files under _ext/docs/. The skill records decisions, dependencies, constraints, and issues, then shows the proposed edits before writing them.

When does corezoid-git-context skip an update?

It skips purely informational sessions where nothing was deployed and none of the defined change conditions occurred. The current stage also needs git_stage_path.

Source text

SKILL.md · MIT
---
name: corezoid-git-context
description: >
  Analyzes the current session and updates _ext/docs/*.md in the Corezoid git
  mirror for the active stage. Use after corezoid-edit, corezoid-create, or
  corezoid-review when the session was substantial (processes deployed, new
  external dependencies discovered, architectural decisions made, issues found
  or resolved). Activate when the user says "update context", "save context",
  "update docs", "push context", "зафіксуй контекст", "збережи контекст",
  "оновити документацію", "corezoid-git-context", or signals the session is
  wrapping up after real changes were made to Corezoid. Do NOT activate for
  purely informational sessions where nothing was deployed.
---

# Session Analysis — Update _ext/docs/*.md

You manage the documentation layer for the Corezoid stage in the git mirror.
Your only write surface is `_ext/docs/` inside the stage directory.
You use four operations: `read-context-file`, `update-context-file`,
`git-pull-context`, `git-push-context`.

---

## How to call these tools

Every operation in this skill is an **action of the single `cz-git-context` MCP tool** —
the individual names below are action strings, not tools of their own:

```
cz-git-context {"action": "read-context-file", "args": {"path": "_ext/docs/architecture.md"}}
```

Arguments always go inside `args`; the shorthand used below — `read-context-file(path=…)` — means exactly that call. When unsure about an action's
arguments, call `cz-git-context {"action": "<action>", "help": true}` — it returns the
full schema and runs nothing.

## Prerequisites — skip entirely if any condition is not met

Before doing anything, verify all of the following. If any check fails, log
one warning line and stop — do not continue to subsequent steps.

1. **Stage path known** — check whether the current Folder in
   `~/.corezoid/config.json` has `git_stage_path` set (`git-pull-context`
   populates it after the first successful mirror sync).
   - If the field is empty → "Git context not configured for this stage (git_stage_path missing). Skipping context update."
2. **Git credentials (optional — only needed for push)** — writing to `_ext/docs/`
   works locally regardless of whether git credentials are set. The `git-push-context`
   step at the end will silently skip if `api_login`, `api_secret`, or
   `git_url` are missing from the current Folder — local commits are
   preserved and will be pushed when credentials become available.
   - Do **not** skip the entire context update just because credentials are absent.
3. **Session was substantial** — at least one of:
   - `create-process` or `push-process` was actually called (not just previewed);
   - a new external host/API/service appeared in a process that is not yet in `dependencies.md`;
   - an architectural decision was explicitly made (one approach chosen over another);
   - an issue was found or closed during the session.
   - If none of the above → "Session was informational only. No context update needed."

---

## Step 1 — Sync git context

Call `git-pull-context` with no arguments. This ensures `.git-context/` is
up to date before reading or writing any files. If the tool returns an error,
stop and report: "Could not sync git context: {error}. Skipping update."

---

## Step 2 — Read the context files that exist

The `git-pull-context` result from Step 1 ends with two lines:

```
Stage path: projects/123_Foo/stages/456_Dev
Context docs (projects/123_Foo/stages/456_Dev/_ext/docs/): context.md, decisions.md — read only these; …
```

Use the `Stage path` value as `STAGE_PATH`, and the `Context docs` line as
the list of files that exist. **Do not probe the standard file set with
`read-context-file`** — a file not in that list does not exist, and reading it
only returns a "not found" error.

- **Files listed** → call `read-context-file` for each listed file
  (`{STAGE_PATH}/_ext/docs/{file}`), all in one parallel batch, before
  analysing — you need the full picture to avoid duplication and to detect
  which existing entries need updating. Treat every unlisted standard file as
  empty.
- **`none yet`** → first use of this stage: read nothing. All five files start
  empty; Step 3 decides which ones to create, and Step 5 creates them with
  `update-context-file` (`mode: replace`). Say so in Step 4 (`new file`).

The standard files are `context.md`, `invariants.md`, `decisions.md`,
`dependencies.md`, `issues.md`, all under `{STAGE_PATH}/_ext/docs/`.

---

## Step 3 — Classify: which files to touch and how

Analyse the session transcript and the Corezoid diff (what was
created/changed/deployed) against the current file contents.

Typically only 1–2 files need changes. Apply the following rules per file:

### context.md
**What it is:** living description of the stage's business purpose and role.
**When to touch:** only if the stage's purpose or role genuinely changed.
**How:** replace the relevant sentence/paragraph in place. Not a journal —
do not append. If the file is missing and there is clear new context to
record, create it.

### invariants.md
**What it is:** constraints that must never be violated.
**When to touch:** new invariant discovered, or existing one proved wrong.
**How:** replace in place. Never create an empty placeholder.

### decisions.md
**What it is:** ADR-style log of architectural decisions.
**When to touch:** a real architectural decision was made (chose approach A
over B, accepted a trade-off, chose a pattern).
**How:** append a new entry in this format:
```
## {Short title} — {YYYY-MM-DD}
**Decision:** {what was decided}
**Rationale:** {why}
**Alternatives rejected:** {what and why not}
```
If an older decision is now superseded, add `**Superseded by:** {new title}`
to the old entry — do not silently rewrite it.

### dependencies.md
**What it is:** external APIs, services, queues this stage integrates with.
**When to touch:** a new external host/service appeared in the session.
**How:** check existing entries first — if the same service is already listed,
do not add a duplicate. If genuinely new, append:
```
- **{ServiceName}** — {URL or endpoint pattern} — {what it's used for}
```

### issues.md
**What it is:** known problems, limitations, TODOs.
**When to touch:** new issue found, or existing issue resolved.
**How:**
- New issue → append:
  ```
  - [ ] {description} — found {YYYY-MM-DD}
  ```
- Resolved issue → find the matching open entry and mark it:
  ```
  - [x] {description} — found {date}, resolved {YYYY-MM-DD}
  ```
  Replace the existing line in-place using `mode: replace` on the full file
  content, do not append a duplicate.

---

## Step 4 — Unified diff and confirmation

**Before writing anything**, present the full planned changes to the user
as a single markdown block:

```
## Proposed context updates

### {filename}.md — {replace | append | new file}
{show the new content or the changed section clearly}

### {filename2}.md — ...
...
```

Then ask: **"Apply these context updates and push to git? (yes/no)"**

- If **yes** → proceed to Step 5.
- If **no** → "Context update skipped. Your Corezoid changes are already
  deployed and unaffected." Stop here.

---

## Step 5 — Write files and push

For each file that needs updating:

1. Call `update-context-file` with:
   - `path`: `{STAGE_PATH}/_ext/docs/{filename}.md`
   - `content`: the full new file content (for replace) or the text to append
   - `mode`: `replace` for context/invariants/issues (full rewrite or targeted
     replace); `append` for decisions/dependencies when adding a new entry

   If the file does not exist yet, `mode: replace` with the full content
   creates it — the directory structure is created automatically.

2. After **all** files are written, call the `git-push-context` action once with a
   meaningful commit message in `commit_message`, e.g.:

   ```
   cz-git-context {"action": "git-push-context",
                   "args": {"commit_message": "docs: update _ext/docs/ after session — {brief summary of what changed}"}}
   ```

   One push for the whole session, not one push per file.

---

## Error handling

| Situation | Action |
|-----------|--------|
| `read-context-file` returns "not found" | Treat as empty file, continue — and don't read further unlisted files |
| `update-context-file` returns error | Log warning, skip that file, continue with others |
| `git-push-context` returns error | Log warning, report to user: "Changes written locally but push failed: {error}. Run git-push-context manually when git is available." |
| No files needed updating | "Session analysed — no context updates needed." |

---

## What this skill never does

- Never writes to `CLAUDE.md` — that file is owned by the git mirror bot.
- Never touches files outside `_ext/docs/` (no `_ext/meta/`, no root files).
- Never creates empty/placeholder files — only writes when there is real content.
- Never pushes more than once per session invocation.
- Never blocks or rolls back the main Corezoid task — context update is always optional.

© Corezoid · MIT · corezoid/corezoid-ai-plugin

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set30

The whole set →
corezoid-describe corezoid-describe is a Claude Code skill that creates and updates descriptions for Corezoid processes, folders, and projects without changing node logic. CX Codex +1 ★ 74repo stars corezoid-lifecycle The corezoid-lifecycle skill for Claude Code pauses, resumes, or relocates Corezoid processes and folders only on explicit user instruction. CX Codex +1 ★ 74repo stars corezoid-retro corezoid-retro — a skill that analyzes a completed Corezoid work session, extracts actionable insights, and stores them as workspace CLAUDE.md updates, team feedback, and permission rules. Every session teaches the next one. CX Codex +1 ★ 74repo stars corezoid-dashboard-manager corezoid-dashboard-manager is a Claude Code skill that builds Corezoid dashboards via cz-dashboards, mapping process node task counters to charts and setting grid layouts. CX Codex +1 ★ 74repo stars plan-to-issues plan-to-issues converts a plan discussed in the chat into structured GitHub issues: an epic plus child tasks grouped by milestone and labeled by type. Triggers on command or keywords like "split plan into tasks" or "make issues from this". CX Codex +1 ★ 74repo stars corezoid-state-diagram-edit corezoid-state-diagram-edit — a skill for updating Corezoid state diagrams in .conv.json files. Adjusts states, transition paths, and transition side effects. CX Codex +1 ★ 74repo stars corezoid-node-layout corezoid-node-layout arranges Corezoid process nodes into a readable top-to-bottom flow and moves error handling to the right. Use it before pushing a new process or after a layout request. CX Codex +1 ★ 74repo stars corezoid-access corezoid-access — a skill for managing access to processes, folders and projects in Corezoid. Share objects with users and groups, create API keys, invite external users, and audit who has access. CX Codex +1 ★ 74repo stars

Project sponsors

Companies that keep this analytics open