geloforge 0.9.0 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -58
- package/VERSION +1 -1
- package/core/compatibility.json +1 -1
- package/package.json +10 -2
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# GeloForge
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Stop re-explaining your codebase — give every AI coding agent a shared, proof-verified memory.**
|
|
4
4
|
|
|
5
|
-
Switch freely between **Cursor,
|
|
5
|
+
Switch freely between **Cursor, Claude Code, VS Code, Codex CLI, Gemini CLI, and Antigravity** without losing architectural context, risking overlapping edits, or trusting hallucinated `"tests pass!"` claims. GeloForge is a local-first, **zero-dependency** CLI and MCP server that keeps project memory, scoped tasks, real test receipts, pinned MCP tools, and portable skills right inside your Git repo.
|
|
6
6
|
|
|
7
7
|
[](https://github.com/63L0/GeloForge/actions/workflows/ci.yml)
|
|
8
8
|
[](https://www.npmjs.com/package/geloforge)
|
|
@@ -10,7 +10,9 @@ Switch freely between **Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI, and
|
|
|
10
10
|
[](./package.json)
|
|
11
11
|
[](./LICENSE)
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
**Zero databases. Zero cloud lock-in. Zero external runtime packages.** Just plain Markdown, YAML, and JSON schemas checked into your repository.
|
|
14
|
+
|
|
15
|
+

|
|
14
16
|
|
|
15
17
|
*[Read the full multi-session case study & reproduction steps →](./docs/dogfooding-v06.md)*
|
|
16
18
|
|
|
@@ -18,121 +20,132 @@ Switch freely between **Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI, and
|
|
|
18
20
|
|
|
19
21
|
## Why GeloForge?
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
Every time you open a fresh AI chat or jump from one coding tool to another, hard-won decisions vanish. GeloForge gives your whole stack one deterministic **Second Brain**:
|
|
22
24
|
|
|
23
25
|
| Without GeloForge | With GeloForge |
|
|
24
26
|
| --- | --- |
|
|
25
|
-
| Re-explaining architecture
|
|
26
|
-
| Agents claiming *"fixed!"* without running tests | **
|
|
27
|
-
| Two AI tools overwriting each other's files | **Cooperative Leases:** Scope
|
|
28
|
-
| Surprise MCP tool changes or unreviewed agent habits | **Pinned Tools & Signed Skills:** `mcp lock --check`
|
|
27
|
+
| Re-explaining specs, architecture, and bugs in every chat | **Contextual BM25 & 3-Zone Packets:** Deterministic context (`brain/` + 15-lang symbol map + skills) in seconds |
|
|
28
|
+
| Agents claiming *"fixed!"* without running tests | **Evidence-Gated Tasks:** Real exit-code receipts (`verify` / `evidence capture`) block fake completion |
|
|
29
|
+
| Two AI tools silently overwriting each other's files | **Cooperative Leases & Worktrees:** Scope claims flag collisions early; Git worktrees isolate parallel work |
|
|
30
|
+
| Surprise MCP tool changes or unreviewed agent habits | **Pinned MCP Tools & Signed Skills:** `mcp lock --check` detects schema drift; skills stay quarantined until approved |
|
|
31
|
+
| Guesswork setup and unnoticed config drift | **Skill Advisor, Doctor & Hooks:** Analyze goals for skills, check health in one command, and run opt-in guardrails |
|
|
29
32
|
|
|
30
33
|
---
|
|
31
34
|
|
|
32
35
|
## Quick start
|
|
33
36
|
|
|
34
|
-
**Prerequisites:** Node.js 20+ and Git installed
|
|
37
|
+
**Prerequisites:** Node.js 20+ and Git installed (`npx geloforge` works immediately — no global install required).
|
|
35
38
|
|
|
36
39
|
### Option A — New to CLI? Paste this to your AI coding agent
|
|
37
40
|
|
|
38
|
-
|
|
41
|
+
Open **Cursor, Claude Code, Codex, Gemini CLI, or Antigravity** inside your project folder and paste:
|
|
39
42
|
|
|
40
43
|
```text
|
|
41
44
|
Set up GeloForge in this repository safely. First run `npx geloforge adopt --dry-run` and explain what files will be added without modifying my existing code. After I confirm, run `npx geloforge adopt`, `npx geloforge mcp init`, `npx geloforge hooks init --dry-run`, and `npx geloforge doctor`. Then run `npx geloforge skills suggest` to recommend matching skills and ask what my first goal is. Do NOT edit my app code or auto-promote skills.
|
|
42
45
|
```
|
|
43
46
|
|
|
44
|
-
> Want ready-to-paste prompts for
|
|
45
|
-
|
|
46
|
-
### Option B — Run the CLI yourself
|
|
47
|
+
> Want ready-to-paste prompts for tasks, tests, checkpoints, and skill drafting? See **[Beginner AI Prompts](./docs/beginner-prompts.md)**.
|
|
47
48
|
|
|
48
|
-
|
|
49
|
+
### Option B — Run the CLI yourself (30 seconds)
|
|
49
50
|
|
|
50
51
|
```bash
|
|
51
|
-
# 1. Preview
|
|
52
|
+
# 1. Preview safely without touching existing code
|
|
52
53
|
npx geloforge adopt --dry-run
|
|
53
54
|
|
|
54
|
-
# 2.
|
|
55
|
+
# 2. Onboard your repo + run one-command health diagnostics
|
|
55
56
|
npx geloforge adopt
|
|
56
57
|
npx geloforge status
|
|
57
58
|
npx geloforge doctor
|
|
58
|
-
```
|
|
59
59
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
```bash
|
|
60
|
+
# 3. Connect AI editors (Cursor, VS Code, Claude Code, Gemini CLI, or --client antigravity)
|
|
63
61
|
npx geloforge mcp init
|
|
62
|
+
|
|
63
|
+
# 4. Preview optional ambient guardrails (Git pre-commit, Claude Stop, Gemini AfterAgent)
|
|
64
64
|
npx geloforge hooks init --dry-run
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
-
|
|
67
|
+
Starting from scratch instead? Scaffold an isolated project with one of 5 domain profiles (`web`, `desktop`, `mobile`, `automation`, `ai-system`):
|
|
68
68
|
|
|
69
|
-
|
|
69
|
+
```bash
|
|
70
|
+
npx geloforge init --name "My Web App" --profile web --git
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
> Guides: [5-minute quickstart](./docs/quickstart-5min.md) · [Creating a new project](./docs/new-projects.md)
|
|
70
74
|
|
|
71
75
|
---
|
|
72
76
|
|
|
73
77
|
## See it in action
|
|
74
78
|
|
|
75
|
-
|
|
79
|
+
Use one repeatable proof-backed workflow from goal discovery through verified completion:
|
|
76
80
|
|
|
77
81
|
```bash
|
|
78
|
-
# 1.
|
|
79
|
-
npx geloforge
|
|
80
|
-
|
|
81
|
-
# 2. Build a compact, budget-aware context packet (with symbol map)
|
|
82
|
-
npx geloforge context --task TASK-0001 --map
|
|
82
|
+
# 1. Discover matching skills or stage a quarantined draft for your goal
|
|
83
|
+
npx geloforge skills suggest --goal "Harden checkout webhook validation"
|
|
83
84
|
|
|
84
|
-
#
|
|
85
|
-
npx geloforge
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
Want to record an intermediate check *without* closing the task yet? Run:
|
|
85
|
+
# 2. Create a scoped task and compile a budget-aware context packet + symbol map
|
|
86
|
+
npx geloforge task new --title "Harden checkout webhook validation" --activate
|
|
87
|
+
npx geloforge context --task TASK-0001 --map --skills
|
|
89
88
|
|
|
90
|
-
|
|
89
|
+
# 3. Capture intermediate test receipts (without closing the task yet)
|
|
91
90
|
npx geloforge evidence capture --task TASK-0001 -- node --test
|
|
91
|
+
|
|
92
|
+
# 4. Verify & complete — fails closed as `draft` if tests fail; saves checkpoint on pass
|
|
93
|
+
npx geloforge verify --task TASK-0001 -- node --test
|
|
92
94
|
```
|
|
93
95
|
|
|
94
|
-
If
|
|
96
|
+
If any check fails or times out, GeloForge records `draft` evidence (never `verified`) and refuses to mark the task verified until real checks pass.
|
|
95
97
|
|
|
96
98
|
---
|
|
97
99
|
|
|
98
100
|
## What you can do
|
|
99
101
|
|
|
100
|
-
|
|
101
|
-
- **
|
|
102
|
-
- **
|
|
103
|
-
- **
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
- **
|
|
102
|
+
### Smart Memory & Token-Efficient Context
|
|
103
|
+
- **Contextual BM25 & 3-Zone Context Compiler:** `npx geloforge context` ranks Markdown headings and docs with zero-dependency BM25, anchors critical policies/conflicts at edge positions to fight context rot, and supports `quick`/`working`/`deep` budgets, `--from-diff`, `--exclude-unverified`, and opt-in `--cache`.
|
|
104
|
+
- **15+ Language Codebase Symbol Map:** Add `--map` to extract `.gitignore`-aware function/class outlines and 1-hop import boosts (JS/TS, Python, Go, Rust, Java, C#, Kotlin, C/C++, Shell, SQL, Markdown, JSON, YAML, TOML) while hard-blocking `.env*`, keys, binaries, and build folders.
|
|
105
|
+
- **Session Checkpoints & Verified Cross-Agent Handoffs:** Save `CHKPT-NNNN` resume notes (`checkpoint create|resume`) and inspect `HANDOFF-NNNN` packets (`handoff --inspect`) that separate audited `EVID-*` receipts from `unverified_claims` and flag Git HEAD drift.
|
|
106
|
+
|
|
107
|
+
### Verification, Security & Governance
|
|
108
|
+
- **Command-Backed Evidence & Secret Redaction:** `verify` and `evidence capture` spawn checks directly (`shell: false`), redact detected secrets, and let `task done --require-evidence` block unverified completion.
|
|
109
|
+
- **MCP Tool-Surface Pinning (`mcp lock`):** Snapshot configured stdio MCP server tool schemas to `.geloforge/mcp-lock.json` via canonical SHA-256 digests and run `npx geloforge mcp lock --check` to catch silent tool poisoning or schema drift.
|
|
110
|
+
- **Signed Governance & Zero-Network Reliability:** Gate ADR/constraint edits (`proposal preview|sign|promote`) and skill promotions on pinned Ed25519 keys, transactional rollback journals, cross-process `.state.lock` protection, zero external network calls, and offline regression evals (`npm run eval`).
|
|
111
|
+
|
|
112
|
+
### Skills, MCP & Multi-Agent Workflows
|
|
113
|
+
- **Project/Goal Skills Advisor (`skills suggest`):** Inspect project markers, active tasks, and `--goal` strings to recommend matching [agentskills.io](https://agentskills.io)-compatible `SKILL.md` workflows, stage quarantined drafts (`--scaffold-draft`), statically security-lint (`skills lint`), and promote/rollback safely (`skills promote|rollback`) with progressive Tier 0/1/2 token loading.
|
|
114
|
+
- **Zero-Dependency MCP Server (`geloforge mcp`):** 6 project-confined MCP tools (`geloforge_status`, `geloforge_recommend`, `geloforge_context`, `geloforge_task`, `geloforge_checkpoint`, `geloforge_skills`) with `--read-only` support, `input_examples`, and self-correcting error hints.
|
|
115
|
+
- **Bounded Coding Loops & Opt-In Staging Audits:** Run capped `implement → verify → review → fix` cycles (`loop run`) gated by fail-closed `policy_checks`, or automate staging error audits (`autonomous watch|learn`) with n8n failure delivery and multi-provider adapters (`codex`, `gemini`, `antigravity`).
|
|
116
|
+
- **Cooperative File Leases & Git Worktrees:** Claim scopes (`task claim --scope src/`) so parallel editors warn on overlapping work automatically, and manage isolated checkouts with `worktree add|remove`.
|
|
117
|
+
|
|
118
|
+
### Diagnostics & Ambient Guardrails
|
|
119
|
+
- **One-Command Diagnostics (`geloforge doctor`):** Audit Node version, Second Brain schemas (`12` strict JSON schemas), Git state, peer leases, skill lint, MCP lock drift, and hook status with actionable fix commands.
|
|
120
|
+
- **Opt-In Ambient Hooks (`geloforge hooks init`):** Add lightweight Git `pre-commit` validation/lock checks plus Claude Code (`hooks.Stop`) and Gemini CLI (`hooks.AfterAgent`) reminders while preserving existing settings — zero background daemons.
|
|
121
|
+
- **Human-in-the-Loop Co-Pilot (`geloforge recommend`):** Surface ranked next actions, pending skill drafts, open conflicts (`CONF-NNNN`), and active peer leases without auto-executing destructive edits.
|
|
107
122
|
|
|
108
123
|
---
|
|
109
124
|
|
|
110
125
|
## How it fits your project
|
|
111
126
|
|
|
112
|
-
Everything GeloForge
|
|
127
|
+
Everything GeloForge creates lives in readable project folders — never modifying your application source code:
|
|
113
128
|
|
|
114
|
-
| Folder |
|
|
129
|
+
| Folder | Purpose |
|
|
115
130
|
| --- | --- |
|
|
116
|
-
| `brain/` |
|
|
117
|
-
| `tasks/` | Scoped `TASK-NNNN` contracts with
|
|
118
|
-
| `evidence/` | Tamper-evident `EVID-NNNN` logs of
|
|
119
|
-
| `handoffs/` | Recovery checkpoints (`CHKPT-NNNN`) and cross-agent `HANDOFF-NNNN`
|
|
120
|
-
| `.agents/skills/` | Reviewed
|
|
131
|
+
| `brain/` | Source of truth: PRD, constraints, architecture decisions (`ADR-*`), and `state/current.yaml` |
|
|
132
|
+
| `tasks/` | Scoped `TASK-NNNN` contracts with objectives, file scope, and acceptance criteria |
|
|
133
|
+
| `evidence/` | Tamper-evident `EVID-NNNN` logs of real commands, exit codes, and redacted outputs |
|
|
134
|
+
| `handoffs/` | Recovery checkpoints (`CHKPT-NNNN`) and structured cross-agent `HANDOFF-NNNN` records |
|
|
135
|
+
| `.agents/skills/` | Reviewed reusable workflows unlocked on demand (`proposals/skills/` isolates unapproved drafts) |
|
|
121
136
|
|
|
122
137
|
---
|
|
123
138
|
|
|
124
139
|
## Documentation
|
|
125
140
|
|
|
126
|
-
- [Beginner AI prompts](./docs/beginner-prompts.md) — ready-to-paste prompts
|
|
127
|
-
- [5-minute quickstart](./docs/quickstart-5min.md) — fastest hands-on walkthrough
|
|
128
|
-
- [CLI and MCP guide](./docs/advanced-usage.md) — full command
|
|
129
|
-
- [Portable Agent Skills](./docs/portable-skills.md) — progressive disclosure,
|
|
130
|
-
- [Creating a new project](./docs/new-projects.md) — templates and domain profiles
|
|
131
|
-
- [Known limitations](./docs/known-limitations.md) & [Security policy](./SECURITY.md) —
|
|
141
|
+
- [Beginner AI prompts](./docs/beginner-prompts.md) — ready-to-paste prompts so any AI agent can run GeloForge for you
|
|
142
|
+
- [5-minute quickstart](./docs/quickstart-5min.md) — fastest hands-on CLI walkthrough
|
|
143
|
+
- [CLI and MCP guide](./docs/advanced-usage.md) — full command flags, `mcp lock`, `loop run`, worktrees, and staging audits
|
|
144
|
+
- [Portable Agent Skills](./docs/portable-skills.md) — progressive disclosure, static security lint, and Ed25519 promotion
|
|
145
|
+
- [Creating a new project](./docs/new-projects.md) — greenfield starter templates and 5 domain profiles
|
|
146
|
+
- [Known limitations](./docs/known-limitations.md) & [Security policy](./SECURITY.md) — trust boundaries and offline safety model
|
|
132
147
|
- [Changelog](./CHANGELOG.md) & [GitHub releases](https://github.com/63L0/GeloForge/releases)
|
|
133
148
|
|
|
134
149
|
## Contributing
|
|
135
150
|
|
|
136
|
-
Issues, bug reports, and pull requests are welcome!
|
|
137
|
-
|
|
138
|
-
For local test setup and pull request checks, read the [contribution guide](./CONTRIBUTING.md).
|
|
151
|
+
Issues, bug reports, and pull requests are welcome! Share your OS, Node.js version, and command output via [GitHub Issues](https://github.com/63L0/GeloForge/issues). For local tests and PR checks, read [CONTRIBUTING.md](./CONTRIBUTING.md).
|
package/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.9.
|
|
1
|
+
0.9.1
|
package/core/compatibility.json
CHANGED
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "geloforge",
|
|
3
|
-
"version": "0.9.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.9.1",
|
|
4
|
+
"description": "Zero-dependency local CLI & MCP server for AI coding agents — shared project memory, verified test evidence, skill advisor, MCP tool pinning, and cross-agent handoffs.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"repository": {
|
|
@@ -15,10 +15,18 @@
|
|
|
15
15
|
"keywords": [
|
|
16
16
|
"ai-coding",
|
|
17
17
|
"ai-harness",
|
|
18
|
+
"mcp",
|
|
19
|
+
"mcp-server",
|
|
18
20
|
"agent-skills",
|
|
21
|
+
"coding-agent",
|
|
22
|
+
"claude-code",
|
|
23
|
+
"cursor",
|
|
24
|
+
"codex",
|
|
25
|
+
"gemini-cli",
|
|
19
26
|
"context-engineering",
|
|
20
27
|
"project-memory",
|
|
21
28
|
"cross-agent-handoff",
|
|
29
|
+
"zero-dependency",
|
|
22
30
|
"developer-tools"
|
|
23
31
|
],
|
|
24
32
|
"engines": {
|