@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 CHANGED
@@ -1,16 +1,583 @@
1
1
  # agentful
2
2
 
3
- A carrot on a stick for Claude Code
3
+ Pre-configured AI agent toolkit with self-hosted remote execution
4
4
 
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
6
  [![npm version](https://badge.fury.io/js/%40itz4blitz%2Fagentful.svg)](https://www.npmjs.com/package/@itz4blitz/agentful)
7
7
  [![CI Status](https://github.com/itz4blitz/agentful/actions/workflows/pipeline.yml/badge.svg)](https://github.com/itz4blitz/agentful/actions)
8
8
 
9
- ## Overview
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
- agentful is a Claude Code configuration that provides structured development through specialized AI agents. It coordinates multiple agents to implement features, write tests, and validate code quality according to a defined product specification.
11
+ ---
12
12
 
13
- ## Web Configurator
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
- - Start immediately without existing code
162
- - No blocking on pattern detection
163
- - Learns and adapts after first implementation
164
- - Continuously improving agent quality
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
- ## Commands
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
- ## Documentation
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
- // Write PID file
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');
@@ -194,24 +194,8 @@ export function createAuthMiddleware(mode, config = {}) {
194
194
  };
195
195
 
196
196
  case 'none':
197
- // None mode: Only allow localhost connections
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.1",
4
- "description": "Human-in-the-loop development kit for Claude Code with smart product analysis and natural conversation",
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
- "human-in-the-loop",
38
- "ai-development",
39
- "agent",
40
- "productivity"
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
@@ -1,3 +1,3 @@
1
1
  {
2
- "version": "1.0.0"
2
+ "version": "1.0.2"
3
3
  }