@itz4blitz/agentful 0.4.0 → 0.5.1

package/.claude/product/README.md

@@ -1,326 +0,0 @@
-# Product Structure Guide
-
-agentful supports **both** flat and hierarchical product structures with automatic detection. This guide explains how to use each format.
-
-## Quick Start
-
-### Simple Projects (Flat Structure)
-
-Create `.claude/product/index.md` with all your features:
-
-```bash
-your-project/
-├── .claude/
-│   └── product/
-│       └── index.md    # All features in one file
-├── src/
-└── package.json
-```
-
-### Organized Projects (Hierarchical Structure)
-
-Create a hierarchical structure under `.claude/product/domains/`:
-
-```bash
-your-project/
-├── .claude/
-│   └── product/
-│       ├── index.md              # Product overview
-│       └── domains/
-│           ├── authentication/
-│           │   ├── index.md      # Domain overview
-│           │   └── features/
-│           │       ├── login.md
-│           │       └── register.md
-│           └── user-management/
-│               ├── index.md
-│               └── features/
-│                   └── profile.md
-├── src/
-└── package.json
-```
-
-## Auto-Detection
-
-The system automatically detects which format you're using:
-
-1. **Hierarchical**: If `.claude/product/domains/*/index.md` exists
-2. **Flat**: If `.claude/product/index.md` exists (without domains)
-
-### Detection Algorithm
-
-```bash
-if exists(".claude/product/domains/*/index.md"):
-    → Use hierarchical structure
-    → Track at subtask → feature → domain levels
-else if exists(".claude/product/index.md"):
-    → Use flat structure
-    → Track at feature level
-else:
-    → Error: No product specification found
-```
-
-## When to Use Each Format
-
-### Flat Structure
-
-**Use when:**
-- Quick prototype or MVP
-- Small project with 5-10 features
-- Single developer or small team
-- Simple feature list without dependencies
-
-**Example `.claude/product/index.md`:**
-
-```markdown
-# My App
-
-## Features
-
-### 1. User Authentication - CRITICAL
-- Login with email/password
-- JWT token handling
-- Password reset
-
-### 2. User Profile - HIGH
-- Edit profile information
-- Upload avatar
-
-### 3. Dashboard - MEDIUM
-- Display user stats
-- Recent activity
-```
-
-### Hierarchical Structure
-
-**Use when:**
-- Large project with 20+ features
-- Multiple team members working in parallel
-- Complex feature dependencies
-- Need domain-driven organization
-
-**Example structure:**
-
-```markdown
-<!-- .claude/product/index.md -->
-# My App
-
-## Domains
-- Authentication (CRITICAL)
-- User Management (HIGH)
-- Dashboard (MEDIUM)
-
-<!-- .claude/product/domains/authentication/index.md -->
-# Authentication Domain
-
-Handles user identity and access control.
-
-## Features
-- Login
-- Register
-- Password Reset
-
-<!-- .claude/product/domains/authentication/features/login.md -->
-# Feature: Login
-
-Priority: CRITICAL
-
-## Subtasks
-1. Create login UI
-2. Implement login API
-3. Add JWT handling
-4. Write tests
-```
-
-## Completion Tracking
-
-### Flat Structure Tracking
-
-```json
-{
-  "features": {
-    "authentication": {
-      "status": "complete",
-      "score": 100
-    },
-    "user-profile": {
-      "status": "in_progress",
-      "score": 60
-    }
-  },
-  "gates": {
-    "tests_passing": true,
-    "no_type_errors": true
-  },
-  "overall": 72
-}
-```
-
-### Hierarchical Structure Tracking
-
-```json
-{
-  "domains": {
-    "authentication": {
-      "status": "complete",
-      "score": 100,
-      "features": {
-        "login": {
-          "status": "complete",
-          "score": 100,
-          "subtasks": {
-            "login-ui": { "status": "complete" },
-            "login-api": { "status": "complete" }
-          }
-        }
-      }
-    },
-    "user-management": {
-      "status": "in_progress",
-      "score": 60,
-      "features": {
-        "profile": {
-          "status": "in_progress",
-          "score": 60
-        }
-      }
-    }
-  },
-  "gates": {
-    "tests_passing": true,
-    "no_type_errors": true
-  },
-  "overall": 72
-}
-```
-
-## Migration Path
-
-You can start flat and expand to hierarchical as your project grows:
-
-```
-Phase 1: Quick Start
-└── .claude/product/index.md (all features in one file)
-
-Phase 2: Scale Up (when needed)
-└── .claude/product/domains/ (split by domain)
-    ├── authentication/
-    ├── user-management/
-    └── dashboard/
-```
-
-### How to Migrate
-
-1. **Create domain directories:**
-   ```bash
-   mkdir -p .claude/product/domains/authentication/features
-   mkdir -p .claude/product/domains/user-management/features
-   ```
-
-2. **Split features into domain files:**
-   ```bash
-   # Move authentication features
-   # .claude/product/domains/authentication/features/login.md
-   # .claude/product/domains/authentication/features/register.md
-   ```
-
-3. **Create domain index files:**
-   ```bash
-   # .claude/product/domains/authentication/index.md
-   # List overview, goals, and feature summaries
-   ```
-
-4. **Update .claude/product/index.md:**
-   ```bash
-   # Keep only product overview and domain list
-   # Remove detailed feature specs (now in domain files)
-   ```
-
-5. **System auto-detects the change:**
-   - Next agent run will detect hierarchical structure
-   - No configuration changes needed
-
-## Best Practices
-
-### Flat Structure
-
-1. **Keep features focused**: Each feature should be independently testable
-2. **Use priorities**: CRITICAL, HIGH, MEDIUM, LOW
-3. **Clear acceptance criteria**: Specific requirements for each feature
-4. **Track progress**: Update completion.json after validated work
-
-### Hierarchical Structure
-
-1. **Domain boundaries**: Group related features (e.g., authentication, billing)
-2. **Feature independence**: Each feature should be completable independently
-3. **Subtask granularity**: Break features into small, testable subtasks
-4. **Cross-domain dependencies**: Document in feature files, minimize where possible
-
-## Examples
-
-See `.claude/product/index.md` template for a complete flat structure example.
-
-For hierarchical structure examples, check:
-- `.claude/agents/orchestrator.md` - Product structure reading algorithm
-- `.claude/skills/product-tracking/SKILL.md` - Progress tracking for both formats
-
-## Troubleshooting
-
-### "No product specification found"
-
-**Solution**: Create one of:
-- `.claude/product/index.md`
-- `.claude/product/domains/*/index.md`
-
-### "Format mismatch" error
-
-**Cause**: completion.json structure doesn't match product files
-
-**Solution**: Don't mix formats. Choose one:
-- All flat: `.claude/product/index.md` + `completion.json` with `features` object
-- All hierarchical: `.claude/product/domains/` + `completion.json` with `domains` object
-
-### Can I use both formats?
-
-**No**: The system auto-detects ONE format. Choose the format that best fits your project size and complexity.
-
-## Product Analysis File
-
-After running `/agentful-product`, a `product-analysis.json` file is generated:
-
-```bash
-.claude/product/
-├── index.md                    # Your product spec (template)
-└── product-analysis.json       # Generated analysis (created by /agentful-product)
-```
-
-**Key points:**
-- **Not in templates**: This file doesn't exist in the agentful package itself
-- **Generated on demand**: Created when you run `/agentful-product` in your project
-- **Purpose**: Analyzes your product spec for completeness, clarity, feasibility, testability, and consistency
-- **Scores readiness**: 0-100% score with blocking issues and recommendations
-- **Version controlled**: Commit to git to track spec quality improvements over time
-
-**Example content:**
-```json
-{
-  "version": "1.0",
-  "timestamp": "2026-01-20T00:00:00Z",
-  "readiness_score": 75,
-  "dimensions": {
-    "completeness": { "score": 85 },
-    "clarity": { "score": 90 }
-  },
-  "blocking_issues": [],
-  "can_start_development": true
-}
-```
-
-## Summary
-
-| Format | Best For | Tracking | File Structure |
-|--------|----------|----------|----------------|
-| Flat (.claude/product/index.md) | Small projects, MVPs | Feature level | Single file |
-| Hierarchical | Large projects, teams | Subtask/feature/domain level | Multiple files, domain folders |
-
-Choose the format that matches your project needs. The system will auto-detect and adapt!

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

@@ -1,271 +0,0 @@
----
-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/bin/hooks/analyze-trigger.sh

@@ -1,57 +0,0 @@
-#!/bin/bash
-
-# analyze-trigger.sh
-# Checks if changed files warrant an /agentful-analyze suggestion
-
-FILE="${FILE:-}"
-
-# Exit silently if no file specified
-if [ -z "$FILE" ]; then
-  exit 0
-fi
-
-# Normalize the file path to get just the filename
-FILENAME=$(basename "$FILE")
-FILEPATH="$FILE"
-
-# Check for key files that should trigger analysis suggestions
-case "$FILENAME" in
-  package.json)
-    # Only trigger for root package.json, not node_modules
-    if echo "$FILEPATH" | grep -q "node_modules"; then
-      exit 0
-    fi
-    echo "Dependencies changed in package.json. Consider running /agentful-analyze to update architecture understanding."
-    exit 0
-    ;;
-
-  architecture.json)
-    echo "Architecture configuration updated. Run /agentful-analyze to refresh tech stack analysis."
-    exit 0
-    ;;
-
-  tsconfig.json|jsconfig.json)
-    echo "TypeScript/JavaScript configuration changed. Consider running /agentful-analyze to update build settings."
-    exit 0
-    ;;
-
-  vite.config.*|webpack.config.*|rollup.config.*|next.config.*)
-    echo "Build configuration changed. Consider running /agentful-analyze to update bundler settings."
-    exit 0
-    ;;
-
-  .env.example|.env.sample)
-    echo "Environment template changed. Consider running /agentful-analyze to update configuration understanding."
-    exit 0
-    ;;
-
-  docker-compose.yml|Dockerfile)
-    echo "Docker configuration changed. Consider running /agentful-analyze to update deployment setup."
-    exit 0
-    ;;
-
-  *)
-    # No suggestion needed for other files
-    exit 0
-    ;;
-esac

package/bin/hooks/health-check.sh

@@ -1,36 +0,0 @@
-#!/bin/bash
-
-# health-check.sh
-# Lightweight startup health check for agentful
-
-# Exit early on any error
-set -e
-
-# Check if .agentful directory exists
-if [ ! -d ".agentful" ]; then
-  echo "Agentful not initialized. Run: npx @itz4blitz/agentful init"
-  exit 0
-fi
-
-# Check if this is a fresh init (no architecture.json means analysis hasn't run)
-if [ ! -f ".agentful/architecture.json" ]; then
-  echo "Agentful initialized but not analyzed."
-  echo ""
-  echo "Run /agentful-generate to:"
-  echo "  - Detect your tech stack"
-  echo "  - Discover business domains"
-  echo "  - Generate specialized agents and skills"
-  exit 0
-fi
-
-# Check for generated agents
-AGENT_COUNT=$(find .claude/agents -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
-SKILL_COUNT=$(find .claude/skills -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
-
-if [ "$AGENT_COUNT" -lt 3 ] || [ "$SKILL_COUNT" -lt 1 ]; then
-  echo "Agentful ready. Consider running /agentful-generate to generate more agents/skills."
-  exit 0
-fi
-
-echo "Agentful ready."
-exit 0