Skip to content

Commit 05e09dc

Browse files
faugustdevfaugustdev
committed
Initial release: GCC skill with full documentation
0 parents  commit 05e09dc

File tree

7 files changed

+800
-0
lines changed

7 files changed

+800
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Contributing to Git Context Controller (GCC)
2+
3+
Thanks for your interest in contributing. This document covers how to get involved.
4+
5+
## Ways to Contribute
6+
7+
- **Bug reports**: Open an issue describing the problem, steps to reproduce, and expected behavior
8+
- **Feature requests**: Open an issue with the proposed feature and its use case
9+
- **Code contributions**: Submit a pull request (see workflow below)
10+
- **Documentation**: Improve README, file format specs, or add examples
11+
- **New agent integrations**: Adapt GCC for agents beyond Claude Code
12+
13+
## Development Setup
14+
15+
```bash
16+
# Fork and clone the repository
17+
git clone https://github.com/<your-username>/git-context-controller.git
18+
cd git-context-controller
19+
20+
# Test the initialization script
21+
./scripts/gcc_init.sh /tmp/test-gcc
22+
```
23+
24+
## Pull Request Workflow
25+
26+
1. Fork the repository
27+
2. Create a feature branch: `git checkout -b feature/my-improvement`
28+
3. Make your changes
29+
4. Test with a real Claude Code session to verify the skill works correctly
30+
5. Commit with a clear message describing *why*, not just *what*
31+
6. Push and open a pull request against `main`
32+
33+
## PR Guidelines
34+
35+
- Keep PRs focused on a single change
36+
- Update documentation if you change behavior
37+
- Add examples for new features when possible
38+
- Follow existing file format conventions
39+
40+
## Code Style
41+
42+
- Shell scripts: Use `set -e`, quote variables, POSIX-compatible where possible
43+
- Markdown: ATX headings (`#`), fenced code blocks, reference-style links for repeated URLs
44+
- YAML: 2-space indentation, quoted strings for values containing special characters
45+
46+
## File Format Changes
47+
48+
If you modify the GCC file formats (`commit.md`, `log.md`, `metadata.yaml`, `main.md`):
49+
50+
1. Update `references/file_formats.md` with the new format
51+
2. Update `SKILL.md` if the change affects how the agent uses the format
52+
3. Update `scripts/gcc_init.sh` if initialization output changes
53+
4. Add a migration note if the change breaks backward compatibility
54+
55+
## Reporting Issues
56+
57+
When reporting bugs, include:
58+
59+
- What you were trying to do
60+
- The agent platform (Claude Code, Cursor, etc.)
61+
- The error or unexpected behavior
62+
- Contents of relevant `.GCC/` files if applicable
63+
64+
## License
65+
66+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 git-context-controller contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Git Context Controller (GCC)
2+
3+
**Structured context management framework for LLM agents.**
4+
5+
GCC implements Git-like operations (COMMIT, BRANCH, MERGE, CONTEXT) to manage long-horizon agent memory as a persistent, versioned file system.
6+
7+
> Based on the research paper: [Git Context Controller](https://arxiv.org/abs/2508.00031)
8+
9+
---
10+
11+
## Why GCC?
12+
13+
LLM agents lose context as conversations grow. Critical decisions, technical reasoning, and intermediate results vanish behind token limits. GCC solves this by giving agents a structured memory system:
14+
15+
- **No more lost context** -- milestones are persisted with full technical reasoning
16+
- **Safe experimentation** -- branches isolate alternative approaches without polluting the main flow
17+
- **Cross-session continuity** -- agents recover exactly where they left off
18+
- **Multi-agent handoff** -- one agent's work is readable by another
19+
20+
## How It Works
21+
22+
```
23+
┌─────────────────────────────────┐
24+
│ .GCC/ │
25+
│ │
26+
│ main.md (roadmap) │
27+
│ metadata.yaml (state) │
28+
│ commit.md (history) │
29+
│ log.md (OTA traces) │
30+
│ │
31+
│ branches/ │
32+
│ ├── feature-x/ │
33+
│ │ ├── summary.md │
34+
│ │ ├── commit.md │
35+
│ │ └── log.md │
36+
│ └── experiment-y/ │
37+
│ ├── summary.md │
38+
│ ├── commit.md │
39+
│ └── log.md │
40+
└─────────────────────────────────┘
41+
```
42+
43+
### The OTA Cycle
44+
45+
Agents operate through **Observation-Thought-Action** cycles, logged in real time:
46+
47+
```
48+
┌───────────┐ ┌───────────┐ ┌───────────┐
49+
│ OBSERVE │────>│ THINK │────>│ ACT │
50+
│ │ │ │ │ │
51+
│ Read logs │ │ Analyze │ │ Execute │
52+
│ Check │ │ Decide │ │ COMMIT │
53+
│ state │ │ strategy │ │ BRANCH │
54+
└───────────┘ └───────────┘ │ MERGE │
55+
^ └─────┬─────┘
56+
│ │
57+
└───────────────────────────────────┘
58+
Logged to log.md
59+
```
60+
61+
### Command Flow
62+
63+
```
64+
User works on task
65+
│
66+
▼
67+
┌──────────────┐ milestone? ┌──────────┐
68+
│ OTA Cycle │────────────────> │ COMMIT │──> commit.md
69+
│ (ongoing) │ └──────────┘
70+
└──────┬───────┘
71+
│
72+
│ need alternative?
73+
▼
74+
┌──────────────┐ ┌──────────┐
75+
│ BRANCH │────────────────> │ Isolated │──> branches/<name>/
76+
│ │ │ workspace│
77+
└──────────────┘ └────┬─────┘
78+
│
79+
validated?
80+
│
81+
▼
82+
┌──────────┐
83+
│ MERGE │──> main.md updated
84+
└──────────┘
85+
86+
┌──────────────┐
87+
│ CONTEXT │──> Retrieve memory at any resolution
88+
│ --branch │ (summary, traces, metadata, full)
89+
│ --log │
90+
│ --metadata │
91+
│ --full │
92+
└──────────────┘
93+
```
94+
95+
## Installation
96+
97+
### As a Claude Code Skill
98+
99+
```bash
100+
# Via skills.sh
101+
npx skills add <owner>/git-context-controller
102+
103+
# Manual installation
104+
# Copy the skill to your project's .claude/skills/ directory
105+
cp -r gcc/ your-project/.claude/skills/gcc/
106+
```
107+
108+
### Standalone
109+
110+
```bash
111+
# Clone the repository
112+
git clone https://github.com/<owner>/git-context-controller.git
113+
114+
# Initialize GCC in your project
115+
./scripts/gcc_init.sh /path/to/your/project/.GCC
116+
```
117+
118+
## Quick Start
119+
120+
Once installed, GCC activates automatically. Use commands or natural language:
121+
122+
| Action | Command | Natural Language |
123+
|---|---|---|
124+
| Save progress | `/gcc commit` | "save this milestone" |
125+
| Try alternative | `/gcc branch experiment` | "branch to try a different approach" |
126+
| Integrate results | `/gcc merge experiment` | "merge the experiment results" |
127+
| Recover context | `/gcc context --full` | "where were we?" |
128+
| View recent work | `/gcc context --log` | "show recent activity" |
129+
| Check structure | `/gcc context --metadata` | "what files do we have?" |
130+
131+
## Commands Reference
132+
133+
### COMMIT
134+
135+
Persists a milestone with full technical context.
136+
137+
```
138+
/gcc commit <summary>
139+
```
140+
141+
Each commit captures:
142+
- Sequential ID and timestamp
143+
- Branch context and purpose
144+
- Previous progress summary
145+
- Detailed technical contribution
146+
- Files touched
147+
148+
### BRANCH
149+
150+
Creates an isolated workspace for experimentation.
151+
152+
```
153+
/gcc branch <name>
154+
```
155+
156+
Creates a new directory under `.GCC/branches/<name>/` with its own commit history, OTA log, and summary.
157+
158+
### MERGE
159+
160+
Synthesizes a completed branch back into the main flow.
161+
162+
```
163+
/gcc merge <branch-name>
164+
```
165+
166+
Updates `main.md` with results, marks the branch as merged or abandoned, and creates a synthesis commit.
167+
168+
### CONTEXT
169+
170+
Retrieves historical memory at different resolution levels.
171+
172+
```
173+
/gcc context [--branch [name] | --log [n] | --metadata | --full]
174+
```
175+
176+
| Flag | Returns | Use Case |
177+
|---|---|---|
178+
| `--branch` | Branch summary + recent commits | Understand what happened on a branch |
179+
| `--log [n]` | Last N OTA entries (default: 20) | Debug or resume interrupted work |
180+
| `--metadata` | Project structure, dependencies | Recover file tree and config |
181+
| `--full` | Complete roadmap from main.md | Cross-session recovery or agent handoff |
182+
183+
## File Formats
184+
185+
### main.md
186+
187+
Global roadmap with objectives, milestones, and active branches.
188+
189+
### commit.md
190+
191+
Structured commit entries with branch purpose, previous progress, and detailed contribution.
192+
193+
### log.md
194+
195+
Sequential OTA (Observation-Thought-Action) trace entries. Capped at 50 entries.
196+
197+
### metadata.yaml
198+
199+
Infrastructure state: branch registry, file tree, dependencies, configuration.
200+
201+
See [`references/file_formats.md`](references/file_formats.md) for complete format specifications with examples.
202+
203+
## Configuration
204+
205+
GCC behavior is controlled via `metadata.yaml`:
206+
207+
```yaml
208+
proactive_commits: true # Auto-suggest commits after milestones
209+
proactive_commits: false # Only commit when explicitly requested
210+
```
211+
212+
Toggle with natural language: "enable/disable proactive commits"
213+
214+
## Project Structure
215+
216+
```
217+
git-context-controller/
218+
├── SKILL.md # Claude Code skill definition
219+
├── README.md # This file
220+
├── LICENSE # MIT License
221+
├── CONTRIBUTING.md # Contribution guidelines
222+
├── scripts/
223+
│ └── gcc_init.sh # Initialization script
224+
├── references/
225+
│ └── file_formats.md # Detailed format specifications
226+
└── examples/
227+
└── sample_session.md # Example GCC session walkthrough
228+
```
229+
230+
## Contributing
231+
232+
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
233+
234+
## References
235+
236+
- **Paper**: [Git Context Controller: Structured Context Management for LLM Agents](https://arxiv.org/abs/2508.00031)
237+
- **Concept**: [Emergent Mind - GCC Topic](https://www.emergentmind.com/topics/git-context-controller-gcc)
238+
239+
## License
240+
241+
[MIT](LICENSE)

0 commit comments

Comments
 (0)