@itz4blitz/agentful 0.4.0 → 0.5.1

package/README.md

@@ -1,21 +1,107 @@
 # agentful
 
-Human-in-the-loop development framework for Claude Code.
+A carrot on a stick for Claude Code
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/%40itz4blitz%2Fagentful.svg)](https://www.npmjs.com/package/@itz4blitz/agentful)
+[![Tests](https://img.shields.io/badge/tests-370%20passing-brightgreen)](https://github.com/itz4blitz/agentful)
+[![Coverage](https://img.shields.io/badge/coverage-98.26%25-brightgreen)](https://github.com/itz4blitz/agentful)
 
 ## Overview
 
-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, with human checkpoints for key decisions.
+agentful is a production-ready 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, with human checkpoints for key decisions.
+
+**Production Quality**: Enterprise-grade testing (370 tests), 98.26% code coverage, comprehensive error handling, and lifecycle hooks for validation and metrics.
+
+## Web Configurator
+
+Configure your agentful installation with an interactive web interface:
+
+**[agentful.app/configure](https://agentful.app/configure)**
+
+- Visual component selection
+- 5 optimized presets
+- Custom configurations
+- Shareable setup URLs
+- No CLI required
+
+See the [Web Configurator Guide](https://agentful.app/getting-started/configurator) for details.
 
 ## Installation
 
+### Default Installation (Recommended)
+
+Install agentful with all components - works with any tech stack:
+
 ```bash
 npx @itz4blitz/agentful init
 ```
 
-This command creates the necessary directory structure and configuration files in your project.
+This installs:
+- **8 agents**: orchestrator, architect, backend, frontend, tester, reviewer, fixer, product-analyzer
+- **6 skills**: product-tracking, validation, testing, conversation, product-planning, deployment
+- **Hooks**: health-check (configurable)
+- **Quality gates**: types, tests, coverage, lint, security, dead-code
+
+**Tech stack is auto-detected** on first run (TypeScript, Python, React, etc.) - no need to specify.
+
+### Minimal Installation
+
+For simple scripts/CLIs that only need backend code:
+
+```bash
+npx @itz4blitz/agentful init --preset=minimal
+```
+
+This installs only:
+- **2 agents**: orchestrator, backend
+- **1 skill**: validation
+
+### Custom Installation
+
+Specify exactly what you want:
+
+```bash
+# Custom agents and skills
+npx @itz4blitz/agentful init --agents=orchestrator,backend,frontend --skills=validation,testing
+
+# View installation options
+npx @itz4blitz/agentful presets
+```
+
+### Shareable Configurations
+
+Use a configuration from [agentful.app/configure](https://agentful.app/configure):
+
+```bash
+npx @itz4blitz/agentful init --config=https://agentful.app/c/abc12345
+```
+
+**Available Flags:**
+- `--preset=<name>` - Use a preset configuration
+- `--agents=<list>` - Comma-separated list of agents (orchestrator, backend, frontend, tester, reviewer, fixer, architect, product-analyzer)
+- `--skills=<list>` - Comma-separated list of skills (validation, testing, product-tracking, conversation, product-planning, deployment)
+- `--hooks=<list>` - Comma-separated list of hooks (health-check, typescript-validation, notifications, format-on-save)
+- `--gates=<list>` - Comma-separated list of quality gates (types, tests, coverage, lint, security, dead-code)
+
+Flags override preset values when both are specified.
+
+### Updating
+
+After initial installation, use the `/agentful-update` command to update your configuration:
+
+```bash
+claude  # Start Claude Code
+/agentful-update
+```
+
+This command:
+- Fetches the latest templates from the current agentful version
+- Performs a 3-way merge to preserve your customizations
+- Creates backups before applying changes
+- Gracefully handles conflicts and reports issues
+
+**Important**: Run `npx @itz4blitz/agentful init` only once during initial setup. For all subsequent updates, use `/agentful-update` instead of re-running init.
 
 ## Usage
 
@@ -124,7 +210,7 @@ agentful uses seven specialized agents:
 
 ### Quality Gates
 
-Code changes are validated against:
+Code changes are validated against 6 core automated quality gates:
 
 - Type checking (TypeScript, Flow, etc.)
 - Linting (ESLint, Biome, etc.)
@@ -146,6 +232,7 @@ Runtime state is stored in `.agentful/` (gitignored, managed by npm package):
   - Re-analyzed after first implementation in new projects
 - `last-validation.json` - Latest test/lint results
 - `conversation-history.json` - Session tracking
+- `product-analysis.json` - Readiness analysis (generated by `/agentful-product`)
 
 User configuration is stored in `.claude/` (version controlled):
 
@@ -153,9 +240,12 @@ User configuration is stored in `.claude/` (version controlled):
 - `commands/` - Slash commands
 - `product/` - Product specifications
   - `index.md` - Main product spec (user editable)
-  - `product-analysis.json` - Readiness analysis (generated by `/agentful-product`)
   - `domains/` - Optional hierarchical structure
 - `skills/` - Reusable skill modules
+  - `conversation/` - Intent classification and context management
+  - `product-tracking/` - Progress calculation and state tracking
+  - `product-planning/` - Product specification guidance
+  - `validation/` - Quality gate checks and tool detection
 - `settings.json` - Project configuration
 
 **See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed explanation of file organization.**
@@ -169,6 +259,38 @@ User configuration is stored in `.claude/` (version controlled):
 | `/agentful-status` | Display progress and current state |
 | `/agentful-validate` | Run all quality checks |
 | `/agentful-decide` | Answer pending decisions |
+| `/agentful-update` | Smart update mechanism - fetches latest templates and gracefully migrates changes |
+
+## CI/CD Integration
+
+Run agentful agents in GitHub Actions, GitLab CI, Jenkins, or Bitbucket Pipelines.
+
+```bash
+# Generate workflow files for your CI platform
+agentful ci --generate-workflow
+
+# Or use the interactive command
+agentful ci
+```
+
+See `examples/` for sample workflow configurations ([GitHub Actions](examples/github-actions.yml), [GitLab CI](examples/gitlab-ci.yml), [Jenkins](examples/jenkins.groovy)).
+
+## Remote Execution
+
+Run agentful agents on remote servers via secure HTTP API.
+
+```bash
+# Start server with Tailscale (most secure, recommended)
+agentful serve
+
+# Start server with HMAC authentication and HTTPS
+agentful serve --auth=hmac --secret=$SECRET --https --cert=cert.pem --key=key.pem
+
+# Start server for local SSH tunnel access
+agentful serve --auth=none
+```
+
+Three authentication modes: **Tailscale** (WireGuard encryption), **HMAC** (signature-based with replay protection), **SSH tunnel** (localhost-only). See `examples/server-deployment.sh` for complete deployment examples including Oracle Cloud Free Tier, Let's Encrypt SSL, and systemd service configuration.
 
 ## Technology Support
 
@@ -191,6 +313,12 @@ agentful detects and adapts to your technology stack automatically:
 
 Full documentation: [agentful.app](https://agentful.app)
 
+Key guides:
+- [CI/CD Integration](https://agentful.app/ci-integration) - Deploy agents to production
+- [Quick Start](https://agentful.app/getting-started/quick-start) - Get started in 5 minutes
+- [Agent Architecture](https://agentful.app/concepts/architecture) - How agents work
+- [Commands Reference](https://agentful.app/commands) - All available commands
+
 ## Project Structure
 
 ```