@itz4blitz/agentful 1.0.1 → 1.1.0
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 +609 -57
- package/bin/cli.js +33 -5
- package/lib/server/auth.js +1 -17
- package/package.json +13 -6
- package/version.json +1 -1
package/README.md
CHANGED
|
@@ -1,16 +1,583 @@
|
|
|
1
1
|
# agentful
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Pre-configured AI agent toolkit with self-hosted remote execution
|
|
4
4
|
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
[](https://www.npmjs.com/package/@itz4blitz/agentful)
|
|
7
7
|
[](https://github.com/itz4blitz/agentful/actions)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Run specialized AI agents on your infrastructure with full control over data, costs, and integrations. Deploy to Oracle Cloud's free tier ($0/month), integrate with any CI/CD platform, and get agents that understand YOUR codebase.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
---
|
|
12
12
|
|
|
13
|
-
##
|
|
13
|
+
## Why agentful?
|
|
14
|
+
|
|
15
|
+
### Self-Hosted Remote Agent Execution
|
|
16
|
+
|
|
17
|
+
Run AI agents on **your infrastructure** with complete control:
|
|
18
|
+
|
|
19
|
+
- **$0/month on Oracle Cloud free tier**: 4 ARM cores, 24GB RAM, always free
|
|
20
|
+
- **Three authentication modes**: Tailscale (recommended), HMAC for public endpoints, SSH tunnel for local development
|
|
21
|
+
- **Own your data**: All code analysis and execution happens on your servers
|
|
22
|
+
- **No vendor lock-in**: Standard HTTP API, works with any client
|
|
23
|
+
- **Secure by default**: WireGuard encryption (Tailscale), request signing (HMAC), or localhost-only (SSH)
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# Deploy to Oracle Cloud free tier
|
|
27
|
+
agentful serve --auth=tailscale
|
|
28
|
+
|
|
29
|
+
# Or run locally with SSH tunnel
|
|
30
|
+
ssh -L 3000:localhost:3000 your-server
|
|
31
|
+
agentful serve --auth=none
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Multi-Platform CI/CD Integration
|
|
35
|
+
|
|
36
|
+
**Not locked to GitHub Actions** - works with any CI/CD platform:
|
|
37
|
+
|
|
38
|
+
- **GitHub Actions**: Native integration with workflow examples
|
|
39
|
+
- **GitLab CI**: Pipeline templates with caching and artifacts
|
|
40
|
+
- **Jenkins**: Groovy pipeline scripts for declarative/scripted pipelines
|
|
41
|
+
- **CircleCI, Bitbucket, Travis**: Use the HTTP API from any platform
|
|
42
|
+
- **Custom platforms**: Standard REST API for any HTTP client
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
# Generate workflow for your CI platform
|
|
46
|
+
agentful ci --generate-workflow
|
|
47
|
+
|
|
48
|
+
# Or integrate via HTTP API from any platform
|
|
49
|
+
curl -X POST http://your-server:3000/agent/orchestrator \
|
|
50
|
+
-H "Content-Type: application/json" \
|
|
51
|
+
-d '{"task": "implement feature X"}'
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Complete Agent Development Toolkit
|
|
55
|
+
|
|
56
|
+
Everything you need for structured AI-driven development:
|
|
57
|
+
|
|
58
|
+
- **8 specialized agents**: orchestrator, architect, backend, frontend, tester, reviewer, fixer, product-analyzer
|
|
59
|
+
- **6 reusable skills**: product-tracking, validation, testing, conversation, product-planning, deployment
|
|
60
|
+
- **6 quality gates**: Type checking, linting, test execution, coverage, security scanning, dead code detection
|
|
61
|
+
- **Interactive product planning**: Smart Q&A to build and validate specifications
|
|
62
|
+
- **State management**: Track progress, decisions, and completion across sessions
|
|
63
|
+
- **Smart updates**: 3-way merge preserves customizations during upgrades
|
|
64
|
+
|
|
65
|
+
### Auto-Generates Domain-Specific Agents
|
|
66
|
+
|
|
67
|
+
Agents that understand **YOUR codebase**, not generic templates:
|
|
68
|
+
|
|
69
|
+
- **Analyzes your patterns**: File organization, coding conventions, import styles, error handling
|
|
70
|
+
- **Detects tech stack**: Framework, language, database, ORM, testing tools
|
|
71
|
+
- **Generates specialized agents**: Real code examples from YOUR project
|
|
72
|
+
- **Confidence scoring**: See how well agents match your architecture (0.4-1.0)
|
|
73
|
+
- **Continuous refinement**: Re-analyzes after implementations to improve accuracy
|
|
74
|
+
|
|
75
|
+
**New projects**: Start with best-practice templates (0.4 confidence), then auto-refine after first feature.
|
|
76
|
+
**Existing projects**: Immediate high-confidence agents (0.8-1.0) from your actual code.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Quick Start
|
|
81
|
+
|
|
82
|
+
### 1. Install agentful
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
npx @itz4blitz/agentful init
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
This installs all components (8 agents, 6 skills, quality gates) and auto-detects your tech stack.
|
|
89
|
+
|
|
90
|
+
### 2. Define your product
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
claude # Start Claude Code
|
|
94
|
+
/agentful-product
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Interactive Q&A creates your product specification with readiness scoring.
|
|
98
|
+
|
|
99
|
+
### 3. Generate domain-specific agents
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
/agentful-analyze
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Analyzes your codebase and generates specialized agents matching your patterns.
|
|
106
|
+
|
|
107
|
+
### 4. Start development
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
/agentful-start
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Orchestrator coordinates agents to implement features with quality gates.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Remote Execution
|
|
118
|
+
|
|
119
|
+
Run agentful agents on remote servers via secure HTTP API.
|
|
120
|
+
|
|
121
|
+
### Authentication Modes
|
|
122
|
+
|
|
123
|
+
#### Tailscale (Recommended)
|
|
124
|
+
|
|
125
|
+
Uses WireGuard encryption for secure remote access:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# Install Tailscale
|
|
129
|
+
curl -fsSL https://tailscale.com/install.sh | sh
|
|
130
|
+
tailscale up
|
|
131
|
+
|
|
132
|
+
# Start server (listens on Tailscale IP only)
|
|
133
|
+
agentful serve --auth=tailscale
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
**Benefits**:
|
|
137
|
+
- End-to-end encrypted (WireGuard)
|
|
138
|
+
- No public IP needed
|
|
139
|
+
- Works across NAT/firewalls
|
|
140
|
+
- Access from anywhere securely
|
|
141
|
+
|
|
142
|
+
#### HMAC (Public Endpoints)
|
|
143
|
+
|
|
144
|
+
Signature-based authentication with replay protection:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
# Generate secret
|
|
148
|
+
export SECRET=$(openssl rand -hex 32)
|
|
149
|
+
|
|
150
|
+
# Start server with HMAC auth and HTTPS
|
|
151
|
+
agentful serve --auth=hmac --secret=$SECRET --https --cert=cert.pem --key=key.pem
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
**Client usage**:
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
# Calculate HMAC signature
|
|
158
|
+
TIMESTAMP=$(date +%s)
|
|
159
|
+
SIGNATURE=$(echo -n "${TIMESTAMP}${PAYLOAD}" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)
|
|
160
|
+
|
|
161
|
+
curl -X POST https://your-server:3000/agent/orchestrator \
|
|
162
|
+
-H "Content-Type: application/json" \
|
|
163
|
+
-H "X-Timestamp: $TIMESTAMP" \
|
|
164
|
+
-H "X-Signature: $SIGNATURE" \
|
|
165
|
+
-d "$PAYLOAD"
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
**Benefits**:
|
|
169
|
+
- Secure for public endpoints
|
|
170
|
+
- Replay attack prevention (timestamp validation)
|
|
171
|
+
- No additional infrastructure needed
|
|
172
|
+
|
|
173
|
+
#### SSH Tunnel (Local Development)
|
|
174
|
+
|
|
175
|
+
Localhost-only access via SSH tunnel:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
# On server
|
|
179
|
+
agentful serve --auth=none
|
|
180
|
+
|
|
181
|
+
# On client
|
|
182
|
+
ssh -L 3000:localhost:3000 your-server
|
|
183
|
+
curl http://localhost:3000/agent/orchestrator -d '{"task": "..."}'
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**Benefits**:
|
|
187
|
+
- Simple setup for development
|
|
188
|
+
- SSH handles authentication
|
|
189
|
+
- No additional configuration
|
|
190
|
+
|
|
191
|
+
### Oracle Cloud Free Tier Deployment
|
|
192
|
+
|
|
193
|
+
Deploy agentful to Oracle Cloud's always-free tier: **4 ARM cores, 24GB RAM, $0/month**.
|
|
194
|
+
|
|
195
|
+
#### 1. Create Oracle Cloud Account
|
|
196
|
+
|
|
197
|
+
1. Sign up at [cloud.oracle.com](https://cloud.oracle.com)
|
|
198
|
+
2. Navigate to **Compute** > **Instances**
|
|
199
|
+
3. Click **Create Instance**
|
|
200
|
+
|
|
201
|
+
#### 2. Configure Instance
|
|
202
|
+
|
|
203
|
+
- **Image**: Ubuntu 22.04 LTS (ARM)
|
|
204
|
+
- **Shape**: VM.Standard.A1.Flex (4 OCPUs, 24GB RAM - always free)
|
|
205
|
+
- **Networking**: Create new VCN with default settings
|
|
206
|
+
- **SSH Keys**: Upload your public key
|
|
207
|
+
|
|
208
|
+
#### 3. Install Dependencies
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
# SSH into instance
|
|
212
|
+
ssh ubuntu@<instance-ip>
|
|
213
|
+
|
|
214
|
+
# Install Node.js 22
|
|
215
|
+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
|
216
|
+
sudo apt-get install -y nodejs
|
|
217
|
+
|
|
218
|
+
# Install Tailscale
|
|
219
|
+
curl -fsSL https://tailscale.com/install.sh | sh
|
|
220
|
+
sudo tailscale up
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
#### 4. Deploy agentful
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
# Clone your repository
|
|
227
|
+
git clone https://github.com/your-org/your-project.git
|
|
228
|
+
cd your-project
|
|
229
|
+
|
|
230
|
+
# Initialize agentful
|
|
231
|
+
npx @itz4blitz/agentful init
|
|
232
|
+
|
|
233
|
+
# Start server (runs in background)
|
|
234
|
+
nohup npx agentful serve --auth=tailscale > agentful.log 2>&1 &
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
#### 5. Configure Systemd (Optional)
|
|
238
|
+
|
|
239
|
+
Create `/etc/systemd/system/agentful.service`:
|
|
240
|
+
|
|
241
|
+
```ini
|
|
242
|
+
[Unit]
|
|
243
|
+
Description=agentful agent server
|
|
244
|
+
After=network.target
|
|
245
|
+
|
|
246
|
+
[Service]
|
|
247
|
+
Type=simple
|
|
248
|
+
User=ubuntu
|
|
249
|
+
WorkingDirectory=/home/ubuntu/your-project
|
|
250
|
+
ExecStart=/usr/bin/npx agentful serve --auth=tailscale
|
|
251
|
+
Restart=always
|
|
252
|
+
RestartSec=10
|
|
253
|
+
|
|
254
|
+
[Install]
|
|
255
|
+
WantedBy=multi-user.target
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Enable and start:
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
sudo systemctl daemon-reload
|
|
262
|
+
sudo systemctl enable agentful
|
|
263
|
+
sudo systemctl start agentful
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
### Configuration
|
|
267
|
+
|
|
268
|
+
Server configuration in `.claude/settings.json`:
|
|
269
|
+
|
|
270
|
+
```json
|
|
271
|
+
{
|
|
272
|
+
"server": {
|
|
273
|
+
"port": 3000,
|
|
274
|
+
"host": "0.0.0.0",
|
|
275
|
+
"auth": "tailscale",
|
|
276
|
+
"https": {
|
|
277
|
+
"enabled": true,
|
|
278
|
+
"cert": "/path/to/cert.pem",
|
|
279
|
+
"key": "/path/to/key.pem"
|
|
280
|
+
},
|
|
281
|
+
"hmac": {
|
|
282
|
+
"secret": "${HMAC_SECRET}",
|
|
283
|
+
"timestampWindow": 300
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## CI/CD Integration
|
|
292
|
+
|
|
293
|
+
Integrate agentful with any CI/CD platform via HTTP API or workflow templates.
|
|
294
|
+
|
|
295
|
+
### GitHub Actions
|
|
296
|
+
|
|
297
|
+
```yaml
|
|
298
|
+
name: agentful CI/CD
|
|
299
|
+
on: [push, pull_request]
|
|
300
|
+
|
|
301
|
+
jobs:
|
|
302
|
+
agentful:
|
|
303
|
+
runs-on: ubuntu-latest
|
|
304
|
+
steps:
|
|
305
|
+
- uses: actions/checkout@v4
|
|
306
|
+
|
|
307
|
+
- name: Setup Node.js
|
|
308
|
+
uses: actions/setup-node@v4
|
|
309
|
+
with:
|
|
310
|
+
node-version: 22
|
|
311
|
+
|
|
312
|
+
- name: Initialize agentful
|
|
313
|
+
run: npx @itz4blitz/agentful init
|
|
314
|
+
|
|
315
|
+
- name: Run orchestrator
|
|
316
|
+
run: |
|
|
317
|
+
npx agentful agent orchestrator \
|
|
318
|
+
--task "implement pending features" \
|
|
319
|
+
--validate
|
|
320
|
+
|
|
321
|
+
- name: Quality gates
|
|
322
|
+
run: npx agentful validate
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
### GitLab CI
|
|
326
|
+
|
|
327
|
+
```yaml
|
|
328
|
+
stages:
|
|
329
|
+
- setup
|
|
330
|
+
- implement
|
|
331
|
+
- validate
|
|
332
|
+
|
|
333
|
+
setup:
|
|
334
|
+
stage: setup
|
|
335
|
+
script:
|
|
336
|
+
- npx @itz4blitz/agentful init
|
|
337
|
+
cache:
|
|
338
|
+
paths:
|
|
339
|
+
- .claude/
|
|
340
|
+
- node_modules/
|
|
341
|
+
|
|
342
|
+
implement:
|
|
343
|
+
stage: implement
|
|
344
|
+
script:
|
|
345
|
+
- npx agentful agent orchestrator --task "implement pending features"
|
|
346
|
+
artifacts:
|
|
347
|
+
paths:
|
|
348
|
+
- .agentful/
|
|
349
|
+
- src/
|
|
350
|
+
|
|
351
|
+
validate:
|
|
352
|
+
stage: validate
|
|
353
|
+
script:
|
|
354
|
+
- npx agentful validate
|
|
355
|
+
dependencies:
|
|
356
|
+
- implement
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
### Jenkins
|
|
360
|
+
|
|
361
|
+
```groovy
|
|
362
|
+
pipeline {
|
|
363
|
+
agent any
|
|
364
|
+
|
|
365
|
+
stages {
|
|
366
|
+
stage('Setup') {
|
|
367
|
+
steps {
|
|
368
|
+
sh 'npx @itz4blitz/agentful init'
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
stage('Implement') {
|
|
373
|
+
steps {
|
|
374
|
+
sh 'npx agentful agent orchestrator --task "implement pending features"'
|
|
375
|
+
}
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
stage('Validate') {
|
|
379
|
+
steps {
|
|
380
|
+
sh 'npx agentful validate'
|
|
381
|
+
}
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
post {
|
|
386
|
+
always {
|
|
387
|
+
archiveArtifacts artifacts: '.agentful/**', allowEmptyArchive: true
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
### HTTP API (Any Platform)
|
|
394
|
+
|
|
395
|
+
Use the REST API from any CI/CD platform:
|
|
396
|
+
|
|
397
|
+
```bash
|
|
398
|
+
# CircleCI, Bitbucket, Travis, etc.
|
|
399
|
+
curl -X POST http://agentful-server:3000/agent/orchestrator \
|
|
400
|
+
-H "Content-Type: application/json" \
|
|
401
|
+
-H "X-Timestamp: $(date +%s)" \
|
|
402
|
+
-H "X-Signature: $SIGNATURE" \
|
|
403
|
+
-d '{
|
|
404
|
+
"task": "implement feature X",
|
|
405
|
+
"context": {
|
|
406
|
+
"branch": "'$CI_BRANCH'",
|
|
407
|
+
"commit": "'$CI_COMMIT'"
|
|
408
|
+
}
|
|
409
|
+
}'
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
**API Endpoints**:
|
|
413
|
+
|
|
414
|
+
- `POST /agent/{agent-name}` - Execute agent task
|
|
415
|
+
- `GET /status` - Get current state
|
|
416
|
+
- `POST /validate` - Run quality gates
|
|
417
|
+
- `GET /health` - Health check
|
|
418
|
+
|
|
419
|
+
---
|
|
420
|
+
|
|
421
|
+
## Domain-Specific Agent Generation
|
|
422
|
+
|
|
423
|
+
agentful generates agents that understand YOUR codebase, not generic templates.
|
|
424
|
+
|
|
425
|
+
### How It Works
|
|
426
|
+
|
|
427
|
+
#### 1. Architecture Analysis
|
|
428
|
+
|
|
429
|
+
The architect agent samples your codebase to detect:
|
|
430
|
+
|
|
431
|
+
- **Language and framework**: TypeScript + React, Python + Django, etc.
|
|
432
|
+
- **File organization**: Feature-based, layer-based, monorepo, etc.
|
|
433
|
+
- **Coding conventions**: Naming patterns, import styles, formatting
|
|
434
|
+
- **Error handling**: Try/catch patterns, error types, logging
|
|
435
|
+
- **Testing patterns**: Framework, test structure, mocking strategies
|
|
436
|
+
|
|
437
|
+
```bash
|
|
438
|
+
/agentful-analyze
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
Analysis output saved to `.agentful/architecture.json`:
|
|
442
|
+
|
|
443
|
+
```json
|
|
444
|
+
{
|
|
445
|
+
"language": "typescript",
|
|
446
|
+
"framework": "react",
|
|
447
|
+
"patterns": {
|
|
448
|
+
"fileOrganization": "feature-based",
|
|
449
|
+
"importStyle": "named-imports",
|
|
450
|
+
"errorHandling": "custom-error-classes",
|
|
451
|
+
"testing": "jest-with-rtl"
|
|
452
|
+
},
|
|
453
|
+
"confidence": 0.85,
|
|
454
|
+
"examples": {
|
|
455
|
+
"componentStructure": "src/features/auth/LoginForm.tsx",
|
|
456
|
+
"apiClient": "src/lib/api/client.ts",
|
|
457
|
+
"errorHandling": "src/lib/errors/ApiError.ts"
|
|
458
|
+
}
|
|
459
|
+
}
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
#### 2. Agent Generation Flow
|
|
463
|
+
|
|
464
|
+
##### New Projects (No Code Yet)
|
|
465
|
+
|
|
466
|
+
1. **Tech stack prompt**: Architect asks about your choices
|
|
467
|
+
```
|
|
468
|
+
Frontend framework: React
|
|
469
|
+
Backend framework: Express
|
|
470
|
+
Database: PostgreSQL
|
|
471
|
+
ORM: Prisma
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
2. **Template-based generation**: Creates agents using best practices
|
|
475
|
+
- Based on official documentation
|
|
476
|
+
- Common patterns and conventions
|
|
477
|
+
- Marked with `confidence: 0.4`
|
|
478
|
+
|
|
479
|
+
3. **First feature implementation**: System builds initial feature
|
|
480
|
+
|
|
481
|
+
4. **Automatic re-analysis**: After completion
|
|
482
|
+
- Analyzes actual code patterns
|
|
483
|
+
- Updates agents with project-specific examples
|
|
484
|
+
- Confidence increases to `0.8+`
|
|
485
|
+
- Remaining features use refined agents
|
|
486
|
+
|
|
487
|
+
##### Existing Projects (With Code)
|
|
488
|
+
|
|
489
|
+
1. **Pattern detection**: Immediate analysis of existing code
|
|
490
|
+
2. **High-confidence agents**: Real examples from your project (`0.8-1.0`)
|
|
491
|
+
3. **Ready to use**: Start implementing features immediately
|
|
492
|
+
|
|
493
|
+
### Generate Specialized Agents
|
|
494
|
+
|
|
495
|
+
After analysis, generate domain-specific agents:
|
|
496
|
+
|
|
497
|
+
```bash
|
|
498
|
+
/agentful-generate
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
This creates/updates agents in `.claude/agents/` with:
|
|
502
|
+
|
|
503
|
+
- **Real code examples** from YOUR project
|
|
504
|
+
- **Specific patterns** matching your conventions
|
|
505
|
+
- **Framework-specific guidance** for your stack
|
|
506
|
+
- **Confidence scores** indicating pattern certainty
|
|
507
|
+
|
|
508
|
+
Example generated agent (`.claude/agents/backend.md`):
|
|
509
|
+
|
|
510
|
+
```markdown
|
|
511
|
+
# Backend Agent
|
|
512
|
+
|
|
513
|
+
You are the backend agent for a TypeScript Express application.
|
|
514
|
+
|
|
515
|
+
## Project Architecture
|
|
516
|
+
|
|
517
|
+
**Framework**: Express with TypeScript
|
|
518
|
+
**Database**: PostgreSQL with Prisma ORM
|
|
519
|
+
**Confidence**: 0.87
|
|
520
|
+
|
|
521
|
+
## Coding Patterns
|
|
522
|
+
|
|
523
|
+
### API Route Structure
|
|
524
|
+
Follow the feature-based organization pattern:
|
|
525
|
+
|
|
526
|
+
\`\`\`typescript
|
|
527
|
+
// src/features/users/routes.ts
|
|
528
|
+
import { Router } from 'express';
|
|
529
|
+
import { UserController } from './controller';
|
|
530
|
+
|
|
531
|
+
export const userRouter = Router();
|
|
532
|
+
userRouter.post('/users', UserController.create);
|
|
533
|
+
\`\`\`
|
|
534
|
+
|
|
535
|
+
### Error Handling
|
|
536
|
+
Use custom error classes with proper HTTP status codes:
|
|
537
|
+
|
|
538
|
+
\`\`\`typescript
|
|
539
|
+
// Example from: src/lib/errors/ApiError.ts
|
|
540
|
+
export class ValidationError extends ApiError {
|
|
541
|
+
constructor(message: string, field?: string) {
|
|
542
|
+
super(message, 400, 'VALIDATION_ERROR', { field });
|
|
543
|
+
}
|
|
544
|
+
}
|
|
545
|
+
\`\`\`
|
|
546
|
+
|
|
547
|
+
### Database Access
|
|
548
|
+
Use Prisma client with transaction patterns:
|
|
549
|
+
|
|
550
|
+
\`\`\`typescript
|
|
551
|
+
// Example from: src/features/orders/service.ts
|
|
552
|
+
await prisma.$transaction(async (tx) => {
|
|
553
|
+
await tx.order.create({ data: orderData });
|
|
554
|
+
await tx.inventory.update({ where: { id }, data: { quantity: { decrement: 1 } } });
|
|
555
|
+
});
|
|
556
|
+
\`\`\`
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
### Confidence Scores
|
|
560
|
+
|
|
561
|
+
Agents include confidence scores indicating pattern detection certainty:
|
|
562
|
+
|
|
563
|
+
- **0.4**: Template-based (new projects before first implementation)
|
|
564
|
+
- **0.6-0.7**: Partial pattern detection (limited code samples)
|
|
565
|
+
- **0.8-0.9**: Strong pattern detection (consistent patterns found)
|
|
566
|
+
- **1.0**: Full confidence (comprehensive pattern analysis)
|
|
567
|
+
|
|
568
|
+
### Continuous Refinement
|
|
569
|
+
|
|
570
|
+
Agents improve over time:
|
|
571
|
+
|
|
572
|
+
1. **After each feature**: Architect can re-analyze to update patterns
|
|
573
|
+
2. **Manual refinement**: Edit generated agents in `.claude/agents/`
|
|
574
|
+
3. **Version control**: Track agent evolution with your codebase
|
|
575
|
+
|
|
576
|
+
---
|
|
577
|
+
|
|
578
|
+
## Installation
|
|
579
|
+
|
|
580
|
+
### Web Configurator
|
|
14
581
|
|
|
15
582
|
Configure your agentful installation with an interactive web interface:
|
|
16
583
|
|
|
@@ -22,8 +589,6 @@ Configure your agentful installation with an interactive web interface:
|
|
|
22
589
|
- Shareable setup URLs
|
|
23
590
|
- No CLI required
|
|
24
591
|
|
|
25
|
-
## Installation
|
|
26
|
-
|
|
27
592
|
### Default Installation (Recommended)
|
|
28
593
|
|
|
29
594
|
Install agentful with all components - works with any tech stack:
|
|
@@ -96,6 +661,8 @@ This command:
|
|
|
96
661
|
|
|
97
662
|
**Important**: Run `npx @itz4blitz/agentful init` only once during initial setup. For all subsequent updates, use `/agentful-update` instead of re-running init.
|
|
98
663
|
|
|
664
|
+
---
|
|
665
|
+
|
|
99
666
|
## Usage
|
|
100
667
|
|
|
101
668
|
### 1. Define Product Specification
|
|
@@ -158,10 +725,10 @@ For brand new projects with no code yet:
|
|
|
158
725
|
- Remaining features use refined, project-specific agents
|
|
159
726
|
|
|
160
727
|
**Benefits**:
|
|
161
|
-
-
|
|
162
|
-
-
|
|
163
|
-
-
|
|
164
|
-
-
|
|
728
|
+
- Start immediately without existing code
|
|
729
|
+
- No blocking on pattern detection
|
|
730
|
+
- Learns and adapts after first implementation
|
|
731
|
+
- Continuously improving agent quality
|
|
165
732
|
|
|
166
733
|
#### Existing Projects (With Code)
|
|
167
734
|
|
|
@@ -185,6 +752,24 @@ For projects with existing code:
|
|
|
185
752
|
- `/agentful-validate` - Run quality checks
|
|
186
753
|
- `/agentful-decide` - Answer blocking questions
|
|
187
754
|
|
|
755
|
+
---
|
|
756
|
+
|
|
757
|
+
## Commands
|
|
758
|
+
|
|
759
|
+
| Command | Description |
|
|
760
|
+
|---------|-------------|
|
|
761
|
+
| `/agentful` | Main agentful command - shows help and available commands |
|
|
762
|
+
| `/agentful-product` | Smart product planning: create, analyze, and refine requirements |
|
|
763
|
+
| `/agentful-start` | Start or resume structured development |
|
|
764
|
+
| `/agentful-status` | Display progress and current state |
|
|
765
|
+
| `/agentful-validate` | Run all quality checks |
|
|
766
|
+
| `/agentful-decide` | Answer pending decisions |
|
|
767
|
+
| `/agentful-update` | Smart update mechanism - fetches latest templates and gracefully migrates changes |
|
|
768
|
+
| `/agentful-analyze` | Analyze architecture and generate specialized agents for your tech stack |
|
|
769
|
+
| `/agentful-generate` | Generate specialized agents from architecture analysis |
|
|
770
|
+
|
|
771
|
+
---
|
|
772
|
+
|
|
188
773
|
## Architecture
|
|
189
774
|
|
|
190
775
|
### Agent System
|
|
@@ -242,50 +827,7 @@ User configuration is stored in `.claude/` (version controlled):
|
|
|
242
827
|
- `deployment/` - Deployment preparation and validation
|
|
243
828
|
- `settings.json` - Project configuration
|
|
244
829
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
| Command | Description |
|
|
248
|
-
|---------|-------------|
|
|
249
|
-
| `/agentful` | Main agentful command - shows help and available commands |
|
|
250
|
-
| `/agentful-product` | Smart product planning: create, analyze, and refine requirements |
|
|
251
|
-
| `/agentful-start` | Start or resume structured development |
|
|
252
|
-
| `/agentful-status` | Display progress and current state |
|
|
253
|
-
| `/agentful-validate` | Run all quality checks |
|
|
254
|
-
| `/agentful-decide` | Answer pending decisions |
|
|
255
|
-
| `/agentful-update` | Smart update mechanism - fetches latest templates and gracefully migrates changes |
|
|
256
|
-
| `/agentful-analyze` | Analyze architecture and generate specialized agents for your tech stack |
|
|
257
|
-
| `/agentful-generate` | Generate specialized agents from architecture analysis |
|
|
258
|
-
|
|
259
|
-
## CI/CD Integration
|
|
260
|
-
|
|
261
|
-
Run agentful agents in GitHub Actions, GitLab CI, Jenkins, or Bitbucket Pipelines.
|
|
262
|
-
|
|
263
|
-
```bash
|
|
264
|
-
# Generate workflow files for your CI platform
|
|
265
|
-
agentful ci --generate-workflow
|
|
266
|
-
|
|
267
|
-
# Or use the interactive command
|
|
268
|
-
agentful ci
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
See `examples/` for sample workflow configurations ([GitHub Actions](examples/github-actions-pipeline.yml), [GitLab CI](examples/gitlab-ci-cd.yml)).
|
|
272
|
-
|
|
273
|
-
## Remote Execution
|
|
274
|
-
|
|
275
|
-
Run agentful agents on remote servers via secure HTTP API.
|
|
276
|
-
|
|
277
|
-
```bash
|
|
278
|
-
# Start server with Tailscale (most secure, recommended)
|
|
279
|
-
agentful serve
|
|
280
|
-
|
|
281
|
-
# Start server with HMAC authentication and HTTPS
|
|
282
|
-
agentful serve --auth=hmac --secret=$SECRET --https --cert=cert.pem --key=key.pem
|
|
283
|
-
|
|
284
|
-
# Start server for local SSH tunnel access
|
|
285
|
-
agentful serve --auth=none
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
Three authentication modes: **Tailscale** (WireGuard encryption), **HMAC** (signature-based with replay protection), **SSH tunnel** (localhost-only).
|
|
830
|
+
---
|
|
289
831
|
|
|
290
832
|
## Technology Support
|
|
291
833
|
|
|
@@ -298,15 +840,15 @@ agentful detects and adapts to your technology stack automatically:
|
|
|
298
840
|
- **ORMs**: Prisma, Drizzle, TypeORM, Mongoose
|
|
299
841
|
- **Testing**: Jest, Vitest, Playwright, Cypress, Pytest, JUnit
|
|
300
842
|
|
|
843
|
+
---
|
|
844
|
+
|
|
301
845
|
## Requirements
|
|
302
846
|
|
|
303
847
|
- Claude Code ([code.anthropic.com](https://code.anthropic.com))
|
|
304
848
|
- Node.js 22 or higher
|
|
305
849
|
- Git
|
|
306
850
|
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
Documentation: [agentful.app](https://agentful.app)
|
|
851
|
+
---
|
|
310
852
|
|
|
311
853
|
## Project Structure
|
|
312
854
|
|
|
@@ -330,10 +872,20 @@ your-project/
|
|
|
330
872
|
└── src/ # Source code
|
|
331
873
|
```
|
|
332
874
|
|
|
875
|
+
---
|
|
876
|
+
|
|
877
|
+
## Documentation
|
|
878
|
+
|
|
879
|
+
Full documentation: [agentful.app](https://agentful.app)
|
|
880
|
+
|
|
881
|
+
---
|
|
882
|
+
|
|
333
883
|
## License
|
|
334
884
|
|
|
335
885
|
MIT
|
|
336
886
|
|
|
887
|
+
---
|
|
888
|
+
|
|
337
889
|
## Links
|
|
338
890
|
|
|
339
891
|
- GitHub: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
|
package/bin/cli.js
CHANGED
|
@@ -1041,13 +1041,19 @@ async function startDaemon(args, config) {
|
|
|
1041
1041
|
// Prepare args for child process (remove --daemon flag)
|
|
1042
1042
|
const childArgs = args.filter(arg => !arg.startsWith('--daemon') && arg !== '-d');
|
|
1043
1043
|
|
|
1044
|
+
// Create log files for daemon output
|
|
1045
|
+
const logFile = path.join(agentfulDir, 'server.log');
|
|
1046
|
+
const errLogFile = path.join(agentfulDir, 'server.err.log');
|
|
1047
|
+
const out = fs.openSync(logFile, 'a');
|
|
1048
|
+
const err = fs.openSync(errLogFile, 'a');
|
|
1049
|
+
|
|
1044
1050
|
// Spawn detached child process
|
|
1045
1051
|
const child = spawn(
|
|
1046
1052
|
process.argv[0], // node executable
|
|
1047
1053
|
[process.argv[1], 'serve', ...childArgs], // script path and args
|
|
1048
1054
|
{
|
|
1049
1055
|
detached: true,
|
|
1050
|
-
stdio: 'ignore',
|
|
1056
|
+
stdio: ['ignore', out, err],
|
|
1051
1057
|
cwd: process.cwd(),
|
|
1052
1058
|
env: {
|
|
1053
1059
|
...process.env,
|
|
@@ -1056,18 +1062,40 @@ async function startDaemon(args, config) {
|
|
|
1056
1062
|
}
|
|
1057
1063
|
);
|
|
1058
1064
|
|
|
1059
|
-
//
|
|
1060
|
-
fs.writeFileSync(pidFile, child.pid.toString(), 'utf-8');
|
|
1061
|
-
|
|
1062
|
-
// Unref to allow parent to exit
|
|
1065
|
+
// Unref immediately to allow parent to exit independently
|
|
1063
1066
|
child.unref();
|
|
1064
1067
|
|
|
1068
|
+
// Wait for server to start (check health endpoint)
|
|
1069
|
+
const maxAttempts = 10;
|
|
1070
|
+
let started = false;
|
|
1071
|
+
for (let i = 0; i < maxAttempts; i++) {
|
|
1072
|
+
await new Promise(resolve => setTimeout(resolve, 500));
|
|
1073
|
+
try {
|
|
1074
|
+
const response = await fetch(`http://localhost:${config.port}/health`);
|
|
1075
|
+
if (response.ok) {
|
|
1076
|
+
started = true;
|
|
1077
|
+
break;
|
|
1078
|
+
}
|
|
1079
|
+
} catch {
|
|
1080
|
+
// Server not ready yet
|
|
1081
|
+
}
|
|
1082
|
+
}
|
|
1083
|
+
|
|
1084
|
+
if (!started) {
|
|
1085
|
+
log(colors.yellow, 'Warning: Server may not have started successfully');
|
|
1086
|
+
log(colors.dim, `Check logs: ${logFile}`);
|
|
1087
|
+
}
|
|
1088
|
+
|
|
1089
|
+
// Write PID file after confirming server started
|
|
1090
|
+
fs.writeFileSync(pidFile, child.pid.toString(), 'utf-8');
|
|
1091
|
+
|
|
1065
1092
|
// Show success message
|
|
1066
1093
|
log(colors.green, `Server started in background (PID: ${child.pid})`);
|
|
1067
1094
|
console.log('');
|
|
1068
1095
|
log(colors.dim, `PID file: ${pidFile}`);
|
|
1069
1096
|
log(colors.dim, `Port: ${config.port}`);
|
|
1070
1097
|
log(colors.dim, `Auth: ${config.auth}`);
|
|
1098
|
+
log(colors.dim, `Logs: ${logFile}`);
|
|
1071
1099
|
console.log('');
|
|
1072
1100
|
log(colors.dim, 'Commands:');
|
|
1073
1101
|
log(colors.dim, ' agentful serve --stop Stop the daemon');
|
package/lib/server/auth.js
CHANGED
|
@@ -194,24 +194,8 @@ export function createAuthMiddleware(mode, config = {}) {
|
|
|
194
194
|
};
|
|
195
195
|
|
|
196
196
|
case 'none':
|
|
197
|
-
// None mode:
|
|
197
|
+
// None mode: Allow all connections (use with SSH tunnel for security)
|
|
198
198
|
return (req, res, next) => {
|
|
199
|
-
const clientIP = req.socket.remoteAddress;
|
|
200
|
-
const isLocalhost =
|
|
201
|
-
clientIP === '127.0.0.1' ||
|
|
202
|
-
clientIP === '::1' ||
|
|
203
|
-
clientIP === '::ffff:127.0.0.1';
|
|
204
|
-
|
|
205
|
-
if (!isLocalhost) {
|
|
206
|
-
res.writeHead(403, { 'Content-Type': 'application/json' });
|
|
207
|
-
return res.end(
|
|
208
|
-
JSON.stringify({
|
|
209
|
-
error: 'Forbidden',
|
|
210
|
-
message: 'Server is in localhost-only mode. Use SSH tunnel or switch to tailscale/hmac mode.',
|
|
211
|
-
})
|
|
212
|
-
);
|
|
213
|
-
}
|
|
214
|
-
|
|
215
199
|
next();
|
|
216
200
|
};
|
|
217
201
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@itz4blitz/agentful",
|
|
3
|
-
"version": "1.0
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
|
+
"description": "Pre-configured AI agent toolkit with self-hosted remote execution. Auto-generates domain specialists, supports all platforms, complete development automation.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"agentful": "bin/cli.js"
|
|
@@ -34,10 +34,17 @@
|
|
|
34
34
|
],
|
|
35
35
|
"keywords": [
|
|
36
36
|
"claude-code",
|
|
37
|
-
"
|
|
38
|
-
"
|
|
39
|
-
"
|
|
40
|
-
"
|
|
37
|
+
"self-hosted",
|
|
38
|
+
"agent-server",
|
|
39
|
+
"autonomous-development",
|
|
40
|
+
"code-generation",
|
|
41
|
+
"multi-platform",
|
|
42
|
+
"ai-agents",
|
|
43
|
+
"development-automation",
|
|
44
|
+
"specialized-agents",
|
|
45
|
+
"orchestrator",
|
|
46
|
+
"ci-cd",
|
|
47
|
+
"remote-execution"
|
|
41
48
|
],
|
|
42
49
|
"author": "agentful",
|
|
43
50
|
"license": "MIT",
|
package/version.json
CHANGED