@itz4blitz/agentful 1.0.2 → 1.2.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,341 +1,134 @@
1
1
  # agentful
2
2
 
3
- A carrot on a stick for Claude Code
3
+ <div align="center">
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
+ [![Node Version](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
9
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/itz4blitz/agentful/pulls)
10
+ [![JavaScript](https://img.shields.io/badge/JavaScript-ES2024-yellow)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
8
11
 
9
- ## Overview
12
+ [![Downloads](https://img.shields.io/npm/dm/@itz4blitz/agentful.svg)](https://www.npmjs.com/package/@itz4blitz/agentful)
13
+ [![GitHub Stars](https://img.shields.io/github/stars/itz4blitz/agentful?style=social)](https://github.com/itz4blitz/agentful)
14
+ [![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289da)](https://discord.gg/SMDvJXUe)
15
+ [![Documentation](https://img.shields.io/badge/docs-agentful.app-blue)](https://agentful.app)
10
16
 
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.
17
+ **AI agent toolkit for autonomous product development with Claude Code**
12
18
 
13
- ## Web Configurator
19
+ [Quick Start](#quick-start) • [Documentation](https://agentful.app) • [Discord](https://discord.gg/SMDvJXUe)
14
20
 
15
- Configure your agentful installation with an interactive web interface:
21
+ </div>
16
22
 
17
- **[agentful.app](https://agentful.app)**
23
+ **The Swiss Army Knife of AI Agents** - Works with any LLM (Claude, GLM, DeepSeek, Ollama), any tech stack, any platform. Self-hosted or cloud.
18
24
 
19
- - Visual component selection
20
- - 2 optimized presets
21
- - Custom configurations
22
- - Shareable setup URLs
23
- - No CLI required
25
+ ## Features
24
26
 
25
- ## Installation
27
+ - **8 specialized agents** - orchestrator, architect, backend, frontend, tester, reviewer, fixer, product-analyzer
28
+ - **6 quality gates** - types, tests, coverage, lint, security, dead code
29
+ - **Auto-generated domain agents** - learns your codebase patterns and conventions
30
+ - **Self-hosted execution** - run agents on your infrastructure (optional)
31
+ - **Multi-platform CI/CD** - GitHub Actions, GitLab, Jenkins, or any HTTP client
32
+ - **Product-driven workflow** - define specs, agents build features
26
33
 
27
- ### Default Installation (Recommended)
28
-
29
- Install agentful with all components - works with any tech stack:
34
+ ## Quick Start
30
35
 
31
36
  ```bash
37
+ # 1. Install
32
38
  npx @itz4blitz/agentful init
33
- ```
34
-
35
- This installs:
36
- - **8 agents**: orchestrator, architect, backend, frontend, tester, reviewer, fixer, product-analyzer
37
- - **6 skills**: product-tracking, validation, testing, conversation, product-planning, deployment
38
- - **Quality gates**: types, tests, coverage, lint, security, dead-code
39
-
40
- **Tech stack is auto-detected** on first run (TypeScript, Python, React, etc.) - no need to specify.
41
-
42
- ### Minimal Installation
43
-
44
- For simple scripts/CLIs that only need backend code:
45
-
46
- ```bash
47
- npx @itz4blitz/agentful init --preset=minimal
48
- ```
49
-
50
- This installs only:
51
- - **2 agents**: orchestrator, backend
52
- - **1 skill**: validation
53
-
54
- ### Custom Installation
55
-
56
- Specify exactly what you want:
57
-
58
- ```bash
59
- # Custom agents and skills
60
- npx @itz4blitz/agentful init --agents=orchestrator,backend,frontend --skills=validation,testing
61
-
62
- # View installation options
63
- npx @itz4blitz/agentful presets
64
- ```
65
-
66
- ### Shareable Configurations
67
-
68
- Use a configuration from the web configurator:
69
-
70
- ```bash
71
- npx @itz4blitz/agentful init --config=<shareable-url>
72
- ```
73
-
74
- **Available Flags:**
75
- - `--preset=<name>` - Use a preset configuration
76
- - `--agents=<list>` - Comma-separated list of agents (orchestrator, backend, frontend, tester, reviewer, fixer, architect, product-analyzer)
77
- - `--skills=<list>` - Comma-separated list of skills (validation, testing, product-tracking, conversation, product-planning, deployment)
78
- - `--gates=<list>` - Comma-separated list of quality gates (types, tests, coverage, lint, security, dead-code)
79
-
80
- Flags override preset values when both are specified.
81
39
 
82
- ### Updating
40
+ # 2. Start Claude Code
41
+ claude
83
42
 
84
- After initial installation, use the `/agentful-update` command to update your configuration:
43
+ # 3. Define product spec (interactive)
44
+ /agentful-product
85
45
 
86
- ```bash
87
- claude # Start Claude Code
88
- /agentful-update
46
+ # 4. Start development
47
+ /agentful-start
89
48
  ```
90
49
 
91
- This command:
92
- - Fetches the latest templates from the current agentful version
93
- - Performs a 3-way merge to preserve your customizations
94
- - Creates backups before applying changes
95
- - Gracefully handles conflicts and reports issues
96
-
97
- **Important**: Run `npx @itz4blitz/agentful init` only once during initial setup. For all subsequent updates, use `/agentful-update` instead of re-running init.
98
-
99
- ## Usage
100
-
101
- ### 1. Define Product Specification
102
-
103
- After initialization, define your product requirements:
104
-
105
- #### Option A: Interactive Planning (Recommended)
50
+ ## Installation Options
106
51
 
107
52
  ```bash
108
- claude # Start Claude Code
109
- ```
110
-
111
- Use `/agentful-product` for guided product planning:
112
- - **New projects**: Interactive Q&A creates your product spec
113
- - **Existing specs**: Analyzes for gaps, ambiguities, blocking issues
114
- - **Readiness scoring**: Get a score (0-100) before development
115
- - **Issue resolution**: Walk through blocking issues with smart suggestions
116
- - **Q&A mode**: Ask planning questions in context
117
-
118
- #### Option B: Manual Creation
119
-
120
- Create your specification manually in `.claude/product/`:
121
-
122
- **Flat structure** (single file):
123
- - `.claude/product/index.md` - All features in one file
53
+ # Default: All components (recommended)
54
+ npx @itz4blitz/agentful init
124
55
 
125
- **Hierarchical structure** (organized by domain):
126
- - `.claude/product/index.md` - Product overview
127
- - `.claude/product/domains/*/features/` - Feature definitions organized by domain
56
+ # Minimal: Simple scripts/CLIs
57
+ npx @itz4blitz/agentful init --preset=minimal
128
58
 
129
- ### 2. Start Development
59
+ # Custom: Choose components
60
+ npx @itz4blitz/agentful init --agents=orchestrator,backend --skills=validation
130
61
 
131
- ```bash
132
- claude # Start Claude Code
62
+ # Web configurator
63
+ https://agentful.app/configure
133
64
  ```
134
65
 
135
- Then use the `/agentful-start` command to begin structured development.
136
-
137
- #### New Projects (No Existing Code)
138
-
139
- For brand new projects with no code yet:
140
-
141
- 1. **Tech Stack Selection**: On first run, the architect agent will ask about your tech stack:
142
- - Frontend framework (React, Vue, Next.js, etc.)
143
- - Backend framework (Express, Django, Spring Boot, etc.)
144
- - Database (PostgreSQL, MongoDB, MySQL, etc.)
145
- - Additional tools (ORM, testing framework, styling)
146
-
147
- 2. **Initial Agent Generation**: Specialized agents are generated using **best practices** for your chosen stack:
148
- - Based on official framework documentation
149
- - Using common patterns and conventions
150
- - Marked with `confidence: 0.4` (template-based)
151
-
152
- 3. **First Feature Implementation**: The system builds your first feature using these template agents
153
-
154
- 4. **Automatic Re-Analysis**: After the first feature is complete:
155
- - Architect re-analyzes your **actual code**
156
- - Updates agents with **your project's specific patterns**
157
- - Confidence increases (`0.4 → 0.8+`)
158
- - Remaining features use refined, project-specific agents
159
-
160
- **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
165
-
166
- #### Existing Projects (With Code)
167
-
168
- For projects with existing code:
169
-
170
- 1. **Pattern Detection**: Architect samples your codebase to detect:
171
- - Language and framework
172
- - File organization patterns
173
- - Coding conventions
174
- - Import/export styles
175
- - Error handling patterns
176
-
177
- 2. **Agent Generation**: Creates specialized agents matching **your exact conventions**
178
- - Real code examples from your project
179
- - Your specific patterns and styles
180
- - High confidence (`0.8-1.0`)
181
-
182
- ### 3. Monitor Progress
183
-
184
- - `/agentful-status` - View completion percentage and current work
185
- - `/agentful-validate` - Run quality checks
186
- - `/agentful-decide` - Answer blocking questions
187
-
188
- ## Architecture
189
-
190
- ### Agent System
191
-
192
- agentful uses eight specialized agents:
193
-
194
- | Agent | Responsibility |
195
- |-------|---------------|
196
- | orchestrator | Coordinates work, routes tasks, tracks state |
197
- | architect | Analyzes project structure and generates specialized agents<br/>• New projects: Prompts for tech stack, generates template agents<br/>• Existing projects: Detects patterns from code<br/>• Re-analyzes after first implementation in new projects |
198
- | backend | Implements server-side logic, APIs, database schemas |
199
- | frontend | Implements UI components, pages, state management |
200
- | tester | Writes unit, integration, and end-to-end tests |
201
- | reviewer | Validates code quality, security, and standards |
202
- | fixer | Resolves validation failures and test errors |
203
- | product-analyzer | Analyzes product specs for gaps, ambiguities, and readiness scoring |
204
-
205
- ### Quality Gates
206
-
207
- Code changes are validated against 6 automated quality gates:
208
-
209
- - Type checking (TypeScript, Flow, etc.)
210
- - Linting (ESLint, Biome, etc.)
211
- - Test execution
212
- - Code coverage
213
- - Security scanning
214
- - Dead code detection
215
-
216
- ### State Tracking
217
-
218
- Runtime state is stored in `.agentful/` (gitignored, managed by npm package):
219
-
220
- - `state.json` - Current task and phase
221
- - `completion.json` - Feature completion status
222
- - `decisions.json` - Pending and resolved decisions
223
- - `architecture.json` - Technology stack (declared or detected)
224
- - New projects: Starts with declared stack (`confidence: 0.4`)
225
- - Existing projects: Detected from code (`confidence: 0.8-1.0`)
226
- - Re-analyzed after first implementation in new projects
227
- - `conversation-history.json` - Session tracking
228
-
229
- User configuration is stored in `.claude/` (version controlled):
230
-
231
- - `agents/` - Agent definitions
232
- - `commands/` - Slash commands
233
- - `product/` - Product specifications
234
- - `index.md` - Main product spec (user editable)
235
- - `domains/` - Optional hierarchical structure
236
- - `skills/` - Reusable skill modules
237
- - `conversation/` - Intent classification and context management
238
- - `product-tracking/` - Progress calculation and state tracking
239
- - `product-planning/` - Product specification guidance
240
- - `validation/` - Quality gate checks and tool detection
241
- - `testing/` - Test strategy and coverage
242
- - `deployment/` - Deployment preparation and validation
243
- - `settings.json` - Project configuration
244
-
245
66
  ## Commands
246
67
 
247
68
  | Command | Description |
248
69
  |---------|-------------|
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 |
70
+ | `/agentful-product` | Create and analyze product specifications |
71
+ | `/agentful-start` | Start autonomous development |
72
+ | `/agentful-status` | View completion % and current work |
73
+ | `/agentful-validate` | Run quality checks |
74
+ | `/agentful-decide` | Answer blocking decisions |
75
+ | `/agentful-analyze` | Generate domain-specific agents |
258
76
 
259
- ## CI/CD Integration
77
+ ## Self-Hosted Remote Execution
260
78
 
261
- Run agentful agents in GitHub Actions, GitLab CI, Jenkins, or Bitbucket Pipelines.
79
+ Run agents on your infrastructure:
262
80
 
263
81
  ```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)).
82
+ # Deploy to Oracle Cloud free tier ($0/month)
83
+ agentful serve --auth=tailscale
272
84
 
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)
85
+ # Or use SSH tunnel for local dev
86
+ ssh -L 3000:localhost:3000 your-server
279
87
  agentful serve
88
+ ```
280
89
 
281
- # Start server with HMAC authentication and HTTPS
282
- agentful serve --auth=hmac --secret=$SECRET --https --cert=cert.pem --key=key.pem
90
+ See [deployment docs](https://agentful.app/remote-execution) for Tailscale, HMAC auth, and Oracle Cloud setup.
283
91
 
284
- # Start server for local SSH tunnel access
285
- agentful serve --auth=none
286
- ```
92
+ ## CI/CD Integration
287
93
 
288
- Three authentication modes: **Tailscale** (WireGuard encryption), **HMAC** (signature-based with replay protection), **SSH tunnel** (localhost-only).
94
+ Works with any platform via HTTP API or templates:
289
95
 
290
- ## Technology Support
96
+ - [GitHub Actions](https://agentful.app/ci-integration#github-actions)
97
+ - [GitLab CI](https://agentful.app/ci-integration#gitlab-ci)
98
+ - [Jenkins](https://agentful.app/ci-integration#jenkins)
99
+ - [HTTP API](https://agentful.app/ci-integration#http-api) (CircleCI, Bitbucket, Travis, etc.)
291
100
 
292
- agentful detects and adapts to your technology stack automatically:
101
+ ## Documentation
293
102
 
294
- - **Languages**: TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, Elixir
295
- - **Frontend**: React, Vue, Angular, Svelte, Next.js, Astro, SolidJS
296
- - **Backend**: Express, Fastify, NestJS, Hono, Next.js API Routes
297
- - **Databases**: PostgreSQL, MySQL, SQLite, MongoDB
298
- - **ORMs**: Prisma, Drizzle, TypeORM, Mongoose
299
- - **Testing**: Jest, Vitest, Playwright, Cypress, Pytest, JUnit
103
+ - **Full docs**: [agentful.app](https://agentful.app)
104
+ - **Architecture**: [Agent system](https://agentful.app/concepts/architecture)
105
+ - **Agents**: [Orchestrator](https://agentful.app/agents/orchestrator), [Backend](https://agentful.app/agents/backend), [Frontend](https://agentful.app/agents/frontend), etc.
106
+ - **Skills**: [Product tracking](https://agentful.app/skills/product-tracking), [Validation](https://agentful.app/skills/validation), etc.
300
107
 
301
108
  ## Requirements
302
109
 
303
110
  - Claude Code ([code.anthropic.com](https://code.anthropic.com))
304
- - Node.js 22 or higher
111
+ - Node.js 22+
305
112
  - Git
306
113
 
307
- ## Documentation
114
+ ## Tech Stack Support
308
115
 
309
- Documentation: [agentful.app](https://agentful.app)
116
+ Auto-detects and adapts to your stack:
310
117
 
311
- ## Project Structure
118
+ - **Languages**: JavaScript, TypeScript, Python, Go, Rust, Java, C#, PHP, Ruby, etc.
119
+ - **Frontend**: React, Vue, Angular, Svelte, Next.js, Astro, SolidJS, etc.
120
+ - **Backend**: Express, Fastify, NestJS, Django, Flask, Spring Boot, etc.
121
+ - **Databases**: PostgreSQL, MySQL, MongoDB, SQLite, etc.
122
+ - **Testing**: Jest, Vitest, Playwright, Cypress, Pytest, JUnit, etc.
312
123
 
313
- ```
314
- your-project/
315
- ├── CLAUDE.md # Project instructions
316
- ├── .claude/
317
- │ ├── product/ # Product specification
318
- │ │ ├── index.md # Product spec (flat or hierarchical)
319
- │ │ └── domains/ # Optional: hierarchical structure
320
- │ ├── agents/ # Agent definitions
321
- │ ├── commands/ # Slash commands
322
- │ ├── skills/ # Reusable skills
323
- │ └── settings.json # Configuration
324
- ├── .agentful/ # Runtime state (gitignored)
325
- │ ├── state.json
326
- │ ├── completion.json
327
- │ ├── decisions.json
328
- │ ├── architecture.json
329
- │ └── conversation-history.json
330
- └── src/ # Source code
331
- ```
124
+ ## Links
125
+
126
+ - **Docs**: [agentful.app](https://agentful.app)
127
+ - **GitHub**: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
128
+ - **Discord**: [discord.gg/SMDvJXUe](https://discord.gg/SMDvJXUe)
129
+ - **Issues**: [github.com/itz4blitz/agentful/issues](https://github.com/itz4blitz/agentful/issues)
130
+ - **NPM**: [npmjs.com/package/@itz4blitz/agentful](https://www.npmjs.com/package/@itz4blitz/agentful)
332
131
 
333
132
  ## License
334
133
 
335
134
  MIT
336
-
337
- ## Links
338
-
339
- - GitHub: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
340
- - Issues: [github.com/itz4blitz/agentful/issues](https://github.com/itz4blitz/agentful/issues)
341
- - NPM: [npmjs.com/package/@itz4blitz/agentful](https://www.npmjs.com/package/@itz4blitz/agentful)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@itz4blitz/agentful",
3
- "version": "1.0.2",
4
- "description": "Human-in-the-loop development kit for Claude Code with smart product analysis and natural conversation",
3
+ "version": "1.2.0",
4
+ "description": "Pre-configured AI agent toolkit with self-hosted remote execution. The Swiss Army Knife of AI Agents - works with any LLM, any tech stack, any platform.",
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",
@@ -128,6 +128,9 @@ The `reviewer` agent runs these checks automatically. The `fixer` agent resolves
128
128
  **"Need to rollback or restart a feature"**
129
129
  → Edit completion % in `.agentful/completion.json` for specific feature, then run `/agentful-start`.
130
130
 
131
+ **"Want to work on multiple features in parallel?"**
132
+ → Use git worktrees for branch-based parallel development, or `agentful serve` for coordinated remote execution.
133
+
131
134
  ## Getting Help
132
135
 
133
136
  **Documentation**: See `.claude/commands/` for detailed command documentation
package/version.json CHANGED
@@ -1,3 +1,3 @@
1
1
  {
2
- "version": "1.0.1"
2
+ "version": "1.1.0"
3
3
  }