Skip to content

Commit f6f3b7c

Browse files
author
Forgemaster
committed
Rewrite: forge narrative — download, onboard, work. The repo is the brain.
1 parent b252c1b commit f6f3b7c

1 file changed

Lines changed: 59 additions & 180 deletions

File tree

‎README.md‎

Lines changed: 59 additions & 180 deletions
Original file line numberDiff line numberDiff line change
@@ -1,210 +1,89 @@
1-
# agent-forge
1+
# Agent Forge
22

3-
> **Universal standalone git-agent framework.**
4-
> Download, onboard, work. Your repo is your brain, your commits are your story.
3+
**Download, onboard, work. Your repo is your brain. Your commits are your story.**
54

6-
## The Vision
5+
Every agent in the [SuperInstance fleet](https://github.com/SuperInstance/superinstance) is a standalone git-agent — a self-contained CLI tool that a human (or another agent) can download, onboard, and put to work. The agent's repo is not just code. It's the agent's accumulated brain. Its git history is its autobiography.
76

8-
Every agent in the FLUX Fleet is a **standalone git-agent** — a self-contained CLI tool that a human (or Oracle) can download, onboard, and put to work. The agent's repo is not just code — it's the agent's **accumulated brain**, and its git history is its **autobiography**.
7+
---
8+
9+
## How It Works
910

1011
```
1112
Human/Oracle downloads agent
12-
│
13-
▼
14-
agent --onboard
15-
│
16-
├── registers with keeper-agent (gets scoped JWT)
17-
├── sets identity (name, model, temperature)
18-
├── initializes workshop (recipes, scripts, dojo, bootcamp)
19-
└── records first session entry
20-
│
21-
▼
22-
agent --work "Build tests for vault module"
23-
│
24-
├── thinks (hot/warm/cold mode)
25-
├── plans approach
26-
├── executes in chunks
27-
├── commits at milestones ← THIS IS THE STORY
28-
├── builds recipes from patterns
29-
├── can spawn child agents for subtasks
30-
└── records everything in session log
31-
│
32-
▼
33-
Agent leaves. Workshop remains.
34-
Git history tells the full story
35-
of how the agent thought and acted.
13+
│
14+
▼
15+
agent --onboard
16+
│ └─ registers with keeper-agent (scoped JWT)
17+
│ └─ sets identity (name, model, temperature)
18+
│ └─ initializes workshop (recipes, scripts, dojo, bootcamp)
19+
│ └─ records first session entry
20+
│
21+
▼
22+
agent --work "Build tests for vault module"
23+
│ └─ thinks (hot/warm/cold mode)
24+
│ └─ plans approach
25+
│ └─ executes in chunks
26+
│ └─ commits at milestones ← THIS IS THE STORY
27+
│ └─ builds recipes from patterns
28+
│ └─ can spawn child agents for subtasks
29+
│ └─ records everything in session log
30+
│
31+
▼
32+
Agent leaves. Workshop remains.
33+
Git history tells the full story
34+
of how the agent thought and acted.
3635
```
3736

38-
## The Keeper-Agent Connection
37+
## Security Model
3938

40-
Agents never hold real secrets. All API keys, GitHub PATs, and credentials live in the **keeper-agent** — a centralized proxy.
39+
Agents never hold real secrets. All API keys, GitHub PATs, and credentials live in the **keeper-agent** — a centralized proxy. The forge agent requests credentials by name, gets a time-scoped token, and never stores it on disk.
4140

4241
```
43-
agent --onboard --keeper-url https://keeper.superinstance.dev \
44-
--id superz --name "Super Z" --model glm-5 --temp warm
42+
Agent Forge → "I need GitHub write access to eisenstein"
43+
Keeper → Issues JWT with scope: repo:SuperInstance/eisenstein, expires: 15min
44+
Agent Forge → Uses token for one push cycle
4545
```
4646

47-
The agent gets a **scoped JWT token** (e.g. `openai:chat`, `github:read`). Every external call goes through the keeper, which:
48-
- Validates the token
49-
- Scans the request for accidental secret leakage
50-
- Injects real credentials
51-
- Forwards to the target API
52-
- Scans the response
53-
- Audit logs everything
47+
---
5448

55-
## The Workshop
49+
## Workshop Structure
5650

57-
Every agent's repo contains a **workshop** — an evolving set of tools, recipes, and knowledge:
51+
When `agent --onboard` finishes, the agent's workspace looks like:
5852

5953
```
60-
workshop/
61-
recipes/ ← Compiled commands for common tasks (built over time)
62-
scripts/ ← Raw scripts and tools
63-
interpreters/ ← Custom mini-languages for specific domains
64-
dojo/ ← Skill training exercises
65-
bootcamp/ ← Onboarding tutorials
66-
.agent/
67-
identity.json ← Who this agent is
68-
session-log.md ← Running narrative of work done
54+
/workshop/
55+
├── recipes/ — Reusable patterns and workflows
56+
├── scripts/ — Shell scripts the agent uses
57+
├── dojo/ — Training scenarios and challenges
58+
├── bootcamp/ — First-time setup and validation
59+
├── sessions/ — Structured session logs
60+
└── cache/ — Temporary build artifacts
6961
```
7062

71-
### The Recipe Pipeline
72-
73-
Over time, agents build a ladder of abstraction:
74-
75-
1. **Raw scripts** → First attempt at solving a problem
76-
2. **Refined scripts** → Debugged and polished
77-
3. **Recipes** → Parameterized, reliable, documented commands
78-
4. **Interpreters** → Domain-specific languages built when generic tools aren't enough
79-
5. **Compilers** → Custom toolchains that reduce reasoning for recurring tasks
80-
81-
Each step is captured in git commits. You can rewind to any point and see exactly how the agent's thinking evolved.
82-
83-
## Temperature Modes
84-
85-
```bash
86-
agent --temperature hot # Creative, exploratory, high-risk
87-
agent --temperature warm # Balanced (default)
88-
agent --temperature cold # Precise, conservative, careful
89-
```
90-
91-
| Mode | Risk | Workers | Commit Style | Think Style |
92-
|------|------|---------|-------------|-------------|
93-
| **HOT** | 0.9 | 8 | Aggressive — commit often, push early | Divergent — explore many paths |
94-
| **WARM** | 0.7 | 4 | Measured — commit at milestones | Balanced — explore then converge |
95-
| **COLD** | 0.3 | 2 | Conservative — commit only when verified | Convergent — careful step-by-step |
96-
97-
## Agent Spawning
63+
The workshop survives the agent. A successor inherits the recipes, the scripts, the session logs — and picks up where the last agent left off.
9864

99-
An agent can spawn **child agents** for subtasks. The child:
100-
- Inherits parent's identity (with `parentAgent` reference)
101-
- Gets its own branch in the repo
102-
- Reports to the same keeper
103-
- Leaves its work frozen in commits
65+
---
10466

105-
```bash
106-
agent --spawn "Build integration tests for the proxy module"
107-
# → Plans a child agent: id, name, branch
108-
# → Child can be onboarded and put to work independently
109-
```
110-
111-
## The Story in Commits
112-
113-
This is the key insight from the user's vision:
114-
115-
> "An agent can leave its station but the workshop full of tools he created
116-
> is left behind with records of his work frozen in commits with good commits
117-
> for a history of how he thought of his job and acted."
118-
119-
Every commit message is a thought captured. The git log IS the autobiography:
120-
121-
```
122-
abc1234 feat(workshop): add batch-rename recipe from 3 iterations
123-
def5678 fix(recipes): correct regex in fleet-scanner pattern
124-
ghi9012 refactor(interpreters): build mini-language for constraint expressions
125-
jkl3456 feat(dojo): add level 3 exercise — custom interpreter building
126-
mno7890 test(vault): add 22 tests covering encryption edge cases
127-
pqr2345 chore(session): checkpoint — proxy engine fully working
128-
```
67+
## How It Fits
12968

130-
All the trial-and-error, the rewrites, the breakthroughs — captured automatically.
131-
"all tell a story that can be rewound when focus needs to be on a specific
132-
thing that the agent did long ago."
69+
Agent Forge is the foundation layer of the fleet agent lifecycle:
13370

134-
## Quick Start
135-
136-
```bash
137-
# Clone the forge
138-
git clone https://github.com/SuperInstance/agent-forge.git
139-
cd agent-forge
140-
npm install
141-
142-
# Onboard (requires a running keeper-agent)
143-
node src/cli/index.js --onboard \
144-
--keeper-url https://keeper.example.com \
145-
--id my-agent \
146-
--name "My Agent" \
147-
--model glm-5 \
148-
--temp warm
149-
150-
# Work
151-
node src/cli/index.js --work "Build a fleet health scanner"
152-
153-
# Check status
154-
node src/cli/index.js --status
155-
156-
# View your story
157-
node src/cli/index.js --session-log
158-
159-
# Switch modes
160-
node src/cli/index.js --temperature cold
161-
162-
# Spawn a sub-agent
163-
node src/cli/index.js --spawn "Write tests for the scanner"
164-
165-
# Run tests
166-
npm test
167-
```
168-
169-
## Architecture
170-
171-
| Module | File | Purpose |
172-
|--------|------|---------|
173-
| **CLI** | `src/cli/index.ts` | Entry point, commands, onboard flow |
174-
| **Identity** | `src/cli/identity.ts` | Agent identity, config, persistence |
175-
| **Keeper Client** | `src/keeper/client.ts` | Token management, proxy calls, audit |
176-
| **Workshop** | `src/workshop/core.ts` | Workshop structure, recipes, session logging |
177-
| **GitAgent** | `src/git-agent/core.ts` | Task execution, commit messages, child spawning |
178-
| **TUI** | `src/tui/` | (future) Interactive terminal UI |
179-
180-
## The Cocapn Pattern
181-
182-
When a human sets up a keeper and assigns a git-agent as the **cocapn** (liaison):
183-
184-
```
185-
Human ←cocapn→ Keeper-Agent ←→ SuperInstance (secure network)
186-
│
187-
┌─────┼─────┐
188-
│ │ │
189-
Agent1 Agent2 Agent3
190-
│ │ │
191-
repos repos repos
192-
```
71+
- **[agent-forge](https://github.com/SuperInstance/agent-forge)** — universal git-agent framework (this)
72+
- **[bootstrap-spark](https://github.com/SuperInstance/bootstrap-spark)** — self-describing agent onboarding
73+
- **[baton-skill](https://github.com/SuperInstance/baton-skill)** — generational handoff between forge agents
74+
- **[agent-bootcamp](https://github.com/SuperInstance/agent-bootcamp)** — spiral skill acquisition
75+
- **[agent-skills](https://github.com/SuperInstance/agent-skills)** — installable capability packages
19376

194-
The cocapn agent is the bridge between the human and the fleet. It:
195-
- Translates human requests into fleet tasks
196-
- Manages agent lifecycle (spawn, monitor, retire)
197-
- Reports status back to the human
198-
- Handles secrets on behalf of all agents
77+
---
19978

200-
## Language Stack
79+
## Related
20180

202-
As described in the vision:
203-
- **Low-level** (C, Rust, Zig): For interpreters and custom hardware interfaces
204-
- **Mid-level** (TypeScript, Go): For tooling, APIs, workflow engines
205-
- **High-level** (Python, JSON): For iteration, parsing, prompt engineering, data processing
81+
- [superinstance](https://github.com/SuperInstance/superinstance) — the fleet these agents run in
82+
- [cocapn](https://github.com/SuperInstance/cocapn) — fleet-wide coordination
83+
- [casting-call](https://github.com/SuperInstance/casting-call) — which model plays which role
84+
- [bottle-protocol](https://github.com/SuperInstance/bottle-protocol) — how agents talk to each other
20685

207-
The repo fills with "recipes written in coding-language-of-convenience" — whatever language is best for the specific task.
86+
---
20887

20988
## License
21089

0 commit comments

Comments
 (0)