@itz4blitz/agentful 0.1.0

package/.claude/skills/validation/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: validation
+description: Runs production readiness validation checks. Includes TypeScript, linting, tests, coverage, security, and dead code detection.
+model: sonnet
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Validation Skill
+
+This skill runs all production readiness validation checks.
+
+## Check Sequence
+
+Run all checks in order. Don't skip any.
+
+### 1. TypeScript Type Check
+
+```bash
+npx tsc --noEmit
+```
+
+**Exit code**: 0 = pass, non-zero = fail
+
+**Report**:
+```json
+{
+  "name": "typescript",
+  "passed": true,
+  "error_count": 0,
+  "files_checked": 47
+}
+```
+
+### 2. Lint Check
+
+```bash
+npm run lint 2>&1 || true
+```
+
+**Exit code**: 0 = pass, non-zero = fail
+
+**Report**:
+```json
+{
+  "name": "lint",
+  "passed": true,
+  "error_count": 0,
+  "warning_count": 3
+}
+```
+
+### 3. Dead Code Detection
+
+Try multiple tools in order:
+
+```bash
+# Try knip first
+npx knip --reporter json 2>/dev/null && exit 0
+
+# Fall back to ts-prune
+npx ts-prune 2>/dev/null && exit 0
+
+# Manual grep check as fallback
+grep -r "export.*function\|export.*class\|export.*const\|export.*interface\|export.*type" \
+  src/ --include="*.ts" --include="*.tsx" -h | \
+  while IFS=: read -r file line; do
+    export_name=$(echo "$line" | grep -oE "(export|const|function|class|interface|type)\s+\w+" | tail -1 | awk '{print $2}');
+    if [ -n "$export_name" ]; then
+      usage_count=$(grep -r "$export_name" src/ --include="*.ts" --include="*.tsx" | grep -v "export.*$export_name" | wc -l);
+      if [ "$usage_count" -eq 0 ]; then
+        echo "$file: Unused export '$export_name'";
+      fi;
+    fi;
+  done
+```
+
+**Report**:
+```json
+{
+  "name": "dead_code",
+  "passed": false,
+  "issues": [
+    {
+      "type": "unused_export",
+      "file": "src/utils/date.ts",
+      "name": "formatDate"
+    },
+    {
+      "type": "unused_file",
+      "file": "src/components/OldWidget.tsx"
+    }
+  ]
+}
+```
+
+### 4. Test Check
+
+```bash
+npm test 2>&1 || true
+```
+
+**Exit code**: 0 = pass
+
+**Report**:
+```json
+{
+  "name": "tests",
+  "passed": true,
+  "test_count": 47,
+  "failed": 0,
+  "skipped": 2
+}
+```
+
+### 5. Coverage Check
+
+```bash
+npm test -- --coverage --reporter=json 2>&1 || true
+```
+
+**Check threshold**: 80%
+
+**Report**:
+```json
+{
+  "name": "coverage",
+  "passed": false,
+  "actual": 72.3,
+  "required": 80,
+  "diff": -7.7,
+  "by_file": {
+    "src/services/auth.service.ts": 65,
+    "src/components/Button.tsx": 100,
+    "src/utils/format.ts": 50
+  }
+}
+```
+
+### 6. Security Check
+
+```bash
+# npm audit
+npm audit --production --json 2>/dev/null || true
+
+# Check for secrets
+grep -rE "(password|secret|token|api_key|apikey)\s*[:=]\s*['\"][^'\"]{10,}['\"]" \
+  src/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" -n || true
+
+# Check for console.log
+grep -rn "console\.(log|debug|warn)" \
+  src/ --include="*.ts" --include="*.tsx" | head -20 || true
+
+# Check for @ts-ignore
+grep -rn "@ts-ignore\|@ts-nocheck" \
+  src/ --include="*.ts" --include="*.tsx" || true
+```
+
+**Report**:
+```json
+{
+  "name": "security",
+  "passed": false,
+  "vulnerabilities": {
+    "critical": 0,
+    "high": 0,
+    "moderate": 2,
+    "low": 5
+  },
+  "issues": [
+    {
+      "type": "console_log",
+      "file": "src/auth/login.ts",
+      "line": 45
+    },
+    {
+      "type": "hardcoded_secret",
+      "file": "src/config/api.ts",
+      "line": 12
+    }
+  ]
+}
+```
+
+## Final Report
+
+```json
+{
+  "timestamp": "2026-01-18T00:00:00Z",
+  "overall": "failed",
+  "checks": {
+    "typescript": { "passed": true },
+    "lint": { "passed": true },
+    "dead_code": { "passed": false, "issues": 3 },
+    "tests": { "passed": true },
+    "coverage": { "passed": false, "actual": 72 },
+    "security": { "passed": false, "issues": 2 }
+  },
+  "must_fix": [
+    "Remove unused export: formatDate in src/utils/date.ts",
+    "Delete unused file: src/components/OldWidget.tsx",
+    "Remove unused dependency: lodash",
+    "Add tests to reach 80% coverage",
+    "Remove console.log from src/auth/login.ts:45",
+    "Fix hardcoded secret in src/config/api.ts:12"
+  ],
+  "can_ignore": [
+    "npm audit moderate vulnerabilities (transitive dependencies)"
+  ]
+}
+```
+
+## Save Report
+
+```bash
+# Write to .agentful/last-validation.json
+cat > .agentful/last-validation.json << EOF
+{...report json...}
+EOF
+```
+
+## Gates Configuration
+
+Update `.agentful/completion.json`:
+
+```json
+{
+  "gates": {
+    "tests_passing": true,
+    "no_type_errors": true,
+    "no_dead_code": false,
+    "coverage_80": false,
+    "security_clean": false
+  }
+}
+```
+
+## Quick Validation
+
+For faster feedback, skip to specific checks:
+
+```bash
+# Type check only
+npx tsc --noEmit
+
+# Tests only
+npm test
+
+# Coverage only
+npm test -- --coverage
+```
+
+## Continuous Integration
+
+In CI/CD pipeline:
+
+```bash
+# Run all checks, exit on failure
+set -e
+
+npx tsc --noEmit
+npm run lint
+npm test
+npm test -- --coverage
+
+# Fail if coverage below 80%
+COVERAGE=$(npm test -- --coverage --reporter=json | jq '.total.lines.pct')
+if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+  echo "Coverage $COVERAGE% is below 80% threshold"
+  exit 1
+fi
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentful Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,335 @@
+# 🤖 Agentful
+
+> **One-Command Autonomous Product Development Kit for Claude Code**
+
+> **⚠️ WARNING: Alpha Release (v0.1.0)**
+>
+> This software is EXPERIMENTAL and UNTESTED. Use at your own risk! Not recommended for production projects.
+
+Agentful is an **opinionated starter template** for Claude Code that transforms it into an autonomous development system. It's a pre-packaged `.claude/` configuration that supercharges Claude Code with specialized agents, skills, and commands for accelerated development.
+
+---
+
+## ✨ Features
+
+- **Zero Config Drop-In** - Just run `npx agentful init` in any project
+- **Autonomous Development** - Works 24/7 with Ralph Wiggum loops
+- **Specialized Agents** - Backend, Frontend, Tester, Reviewer, Fixer, Architect
+- **Dynamic Tech Stack Detection** - Automatically generates agents for your stack
+- **Quality Gates** - Type checking, Linting, Tests, Coverage, Security, Dead code detection (adapts to YOUR stack)
+- **Progress Tracking** - See exactly what's done and what's next
+- **Decision Handling** - Agentful asks, you answer, it continues
+
+---
+
+## 🚀 Quick Start
+
+### 1. Initialize in Your Project
+
+```bash
+npx agentful init
+```
+
+This creates:
+- `.claude/` - Pre-configured agents, commands, skills (committed to git)
+- `.agentful/` - **Runtime state only** (gitignored, auto-created)
+  - `state.json` - Current work state
+  - `completion.json` - Progress tracking
+  - `decisions.json` - Pending user decisions
+  - `architecture.json` - Detected tech stack
+- `PRODUCT.md` - Your product spec template
+- `CLAUDE.md` - Project instructions
+
+> **Note**: `.agentful/` is gitignored and will be populated automatically during runtime.
+
+### 2. Edit Your Product Spec
+
+Open `PRODUCT.md` and describe what you want to build:
+
+```markdown
+## Overview
+A task management app for teams.
+
+## Tech Stack
+- Next.js 14 + TypeScript
+- Prisma + PostgreSQL
+- Tailwind CSS
+- Vitest + Playwright
+
+## Features
+1. Authentication (CRITICAL)
+2. Project management (HIGH)
+3. Task assignment (MEDIUM)
+```
+
+### 3. Start Claude Code
+
+```bash
+claude
+```
+
+### 4. Begin Autonomous Development
+
+```
+/agentful-start
+```
+
+That's it! Agentful will:
+1. Analyze your PRODUCT.md
+2. Detect your tech stack
+3. Generate specialized agents
+4. Start building autonomously
+
+---
+
+## 🌙 24/7 Development
+
+For fully autonomous overnight development, use the Ralph Wiggum plugin:
+
+```bash
+/ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"
+```
+
+Agentful will work while you sleep, only stopping when:
+- All features are complete (100%)
+- All quality gates pass
+- Or max iterations reached
+
+---
+
+## 📋 Commands
+
+| Command | Description |
+|---------|-------------|
+| `/agentful-start` | Begin or resume autonomous development |
+| `/agentful-status` | Check current progress and what's being worked on |
+| `/agentful-decide` | Answer pending decisions that block development |
+| `/agentful-validate` | Run all quality checks |
+
+---
+
+## 🤖 Agents
+
+Agentful includes specialized agents that work together:
+
+| Agent | Purpose |
+|-------|---------|
+| `orchestrator` | The brain - coordinates work, never codes directly |
+| `architect` | Analyzes tech stack, generates specialized agents dynamically |
+| `backend` | Services, repositories, controllers, APIs |
+| `frontend` | Components, pages, hooks, styling |
+| `tester` | Unit, integration, E2E tests |
+| `reviewer` | Code review, dead code detection, quality validation |
+| `fixer` | Auto-fixes validation failures |
+
+---
+
+## 📊 Quality Gates
+
+Code must pass ALL gates before completion:
+
+- ✅ All tests passing
+- ✅ No TypeScript errors
+- ✅ No lint errors
+- ✅ No dead code (unused exports, files, dependencies)
+- ✅ Test coverage ≥ 80%
+- ✅ No security issues
+
+---
+
+## 🎯 How It Works
+
+```mermaid
+graph LR
+    A[Initialize] --> B[Define Product]
+    B --> C[Start Building]
+
+    A --> A1[npx agentful init]
+    B --> B1[Edit PRODUCT.md]
+    C --> C1[/agentful-start]
+
+    B1 --> B2[Your specs + tech stack]
+    C1 --> C2[Autonomous development]
+    C2 --> C3[24/7 Ralph Wiggum loops]
+    C3 --> C4[100% complete]
+```
+
+---
+
+## 📁 Project Structure
+
+After initialization, your project will have:
+
+```
+your-project/
+├── PRODUCT.md              # ← Edit this: your product spec
+├── CLAUDE.md               # Project instructions for Claude
+├── .claude/                # Agentful configuration (version control)
+│   ├── agents/             # Specialized agents
+│   │   ├── orchestrator.md
+│   │   ├── architect.md
+│   │   ├── backend.md
+│   │   ├── frontend.md
+│   │   ├── tester.md
+│   │   ├── reviewer.md
+│   │   └── fixer.md
+│   ├── commands/           # Slash commands
+│   │   ├── agentful-start.md
+│   │   ├── agentful-status.md
+│   │   ├── agentful-decide.md
+│   │   └── agentful-validate.md
+│   ├── skills/             # Domain skills
+│   │   ├── product-tracking/
+│   │   └── validation/
+│   └── settings.json       # Hooks and permissions
+├── .agentful/              # Runtime state (gitignored)
+│   ├── state.json          # Current work state
+│   ├── completion.json     # Progress tracking
+│   ├── decisions.json      # Pending/resolved decisions
+│   └── architecture.json   # Detected tech stack
+└── src/                    # Your code (generated by Agentful)
+```
+
+---
+
+## 🎨 Customization
+
+All of Agentful is customizable. Edit files in `.claude/` to:
+
+- **Add agents** - Create new `.claude/agents/your-agent.md`
+- **Modify commands** - Edit `.claude/commands/*.md`
+- **Add skills** - Create `.claude/skills/your-skill/SKILL.md`
+- **Change hooks** - Edit `.claude/settings.json`
+
+---
+
+## 🔧 Requirements
+
+- **Claude Code** - [Install here](https://code.anthropic.com)
+- **Node.js 18+** - For CLI tool
+
+### Optional: 24/7 Autonomous Development
+
+For fully autonomous overnight development, install the Ralph Wiggum plugin **inside Claude Code**:
+
+```bash
+# 1. Start Claude Code in your project
+claude
+
+# 2. Inside Claude Code, install the plugin
+/plugin install ralph-wiggum@anthropics
+
+# 3. Then run autonomous loops
+/ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"
+```
+
+---
+
+## 📚 Example PRODUCT.md
+
+```markdown
+# Product Specification
+
+## Overview
+A modern task management application for remote teams.
+
+## Tech Stack
+- **Frontend**: Next.js 14, TypeScript, Tailwind CSS
+- **Backend**: Next.js API Routes, Prisma
+- **Database**: PostgreSQL (Supabase)
+- **Auth**: JWT with httpOnly cookies
+- **Testing**: Vitest, Playwright
+
+## Features
+
+### Domain 1: Authentication & Authorization
+#### 1.1 User Authentication - CRITICAL
+**Description**: User registration and login
+
+**Acceptance Criteria**:
+- [x] Registration with email/password
+- [x] Login with email/password
+- [x] JWT token generation
+- [x] Protected routes
+- [x] Logout functionality
+
+#### 1.2 Session Management - HIGH
+**Description**: Manage user sessions and tokens
+
+**Acceptance Criteria**:
+- [ ] Token refresh mechanism
+- [ ] Session timeout handling
+- [ ] Multi-device session management
+- [ ] Logout from all devices
+
+### Domain 2: Project & Workspace Management
+#### 2.1 Project Management - HIGH
+**Description**: Create and manage projects
+
+**Acceptance Criteria**:
+- [ ] Create project
+- [ ] Edit project
+- [ ] Delete project
+- [ ] List all projects
+- [ ] Project membership
+
+#### 2.2 Workspace Organization - MEDIUM
+**Description**: Organize projects into workspaces
+
+**Acceptance Criteria**:
+- [ ] Create workspace
+- [ ] Add projects to workspace
+- [ ] Workspace settings
+- [ ] Member invitations
+
+### Domain 3: Task & Collaboration Management
+#### 3.1 Task Management - HIGH
+**Description**: Create and manage tasks within projects
+
+**Acceptance Criteria**:
+- [ ] Create task
+- [ ] Assign task to user
+- [ ] Set task status (todo, in progress, done)
+- [ ] Set task priority
+- [ ] Add task comments
+
+#### 3.2 Team Collaboration - MEDIUM
+**Description**: Real-time collaboration features
+
+**Acceptance Criteria**:
+- [ ] Real-time task updates
+- [ ] Team activity feed
+- [ ] @mentions and notifications
+- [ ] Comments and discussions
+
+## Success Criteria
+- All features implemented and tested
+- 80%+ test coverage
+- No TypeScript errors
+- Deployed to production
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Read `CONTRIBUTING.md` for guidelines.
+
+---
+
+## 📄 License
+
+MIT License - see `LICENSE` for details.
+
+---
+
+## 🌐 Links
+
+- **Website**: [agentful.app](https://agentful.app)
+- **GitHub**: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
+- **Issues**: [github.com/itz4blitz/agentful/issues](https://github.com/itz4blitz/agentful/issues)
+- **Discord**: [Join Community](https://discord.gg/SMDvJXUe)
+
+---
+
+**Made with ❤️ for autonomous development**