@itz4blitz/agentful 0.4.0 → 1.0.0

package/README.md

@@ -1,21 +1,100 @@
 # 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)
+[![CI Status](https://github.com/itz4blitz/agentful/actions/workflows/pipeline.yml/badge.svg)](https://github.com/itz4blitz/agentful/actions)
 
 ## 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 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.
+
+## Web Configurator
+
+Configure your agentful installation with an interactive web interface:
+
+**[agentful.app](https://agentful.app)**
+
+- Visual component selection
+- 2 optimized presets
+- Custom configurations
+- Shareable setup URLs
+- No CLI required
 
 ## 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
+- **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 the web configurator:
+
+```bash
+npx @itz4blitz/agentful init --config=<shareable-url>
+```
+
+**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)
+- `--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
 
@@ -110,7 +189,7 @@ For projects with existing code:
 
 ### Agent System
 
-agentful uses seven specialized agents:
+agentful uses eight specialized agents:
 
 | Agent | Responsibility |
 |-------|---------------|
@@ -121,15 +200,16 @@ agentful uses seven specialized agents:
 | tester | Writes unit, integration, and end-to-end tests |
 | reviewer | Validates code quality, security, and standards |
 | fixer | Resolves validation failures and test errors |
+| product-analyzer | Analyzes product specs for gaps, ambiguities, and readiness scoring |
 
 ### Quality Gates
 
-Code changes are validated against:
+Code changes are validated against 6 automated quality gates:
 
 - Type checking (TypeScript, Flow, etc.)
 - Linting (ESLint, Biome, etc.)
-- Test execution (all tests must pass)
-- Code coverage (minimum 80%)
+- Test execution
+- Code coverage
 - Security scanning
 - Dead code detection
 
@@ -144,31 +224,68 @@ Runtime state is stored in `.agentful/` (gitignored, managed by npm package):
   - New projects: Starts with declared stack (`confidence: 0.4`)
   - Existing projects: Detected from code (`confidence: 0.8-1.0`)
   - Re-analyzed after first implementation in new projects
-- `last-validation.json` - Latest test/lint results
 - `conversation-history.json` - Session tracking
 
 User configuration is stored in `.claude/` (version controlled):
 
-- `agents/` - Agent definitions (core + custom + ephemeral)
+- `agents/` - Agent definitions
 - `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
+  - `testing/` - Test strategy and coverage
+  - `deployment/` - Deployment preparation and validation
 - `settings.json` - Project configuration
 
-**See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed explanation of file organization.**
-
 ## Commands
 
 | Command | Description |
 |---------|-------------|
+| `/agentful` | Main agentful command - shows help and available commands |
 | `/agentful-product` | Smart product planning: create, analyze, and refine requirements |
 | `/agentful-start` | Start or resume structured development |
 | `/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 |
+| `/agentful-analyze` | Analyze architecture and generate specialized agents for your tech stack |
+| `/agentful-generate` | Generate specialized agents from architecture analysis |
+
+## 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-pipeline.yml), [GitLab CI](examples/gitlab-ci-cd.yml)).
+
+## 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).
 
 ## Technology Support
 
@@ -189,7 +306,7 @@ agentful detects and adapts to your technology stack automatically:
 
 ## Documentation
 
-Full documentation: [agentful.app](https://agentful.app)
+Documentation: [agentful.app](https://agentful.app)
 
 ## Project Structure
 
@@ -209,7 +326,6 @@ your-project/
 │   ├── completion.json
 │   ├── decisions.json
 │   ├── architecture.json
-│   ├── last-validation.json
 │   └── conversation-history.json
 └── src/                            # Source code
 ```
@@ -222,5 +338,4 @@ MIT
 
 - GitHub: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
 - Issues: [github.com/itz4blitz/agentful/issues](https://github.com/itz4blitz/agentful/issues)
-- Documentation: [agentful.app](https://agentful.app)
-- NPM: [npmjs.com/@itz4blitz/agentful](https://www.npmjs.com/package/@itz4blitz/agentful)
+- NPM: [npmjs.com/package/@itz4blitz/agentful](https://www.npmjs.com/package/@itz4blitz/agentful)