Workflow Configuration

---
name: command-name
description: What this command does
---
 
# Command Name
 
Detailed instructions...

---
name: agentful-start
description: Start or resume autonomous development with custom workflow
---
 
# agentful Start
 
## Custom Startup Sequence
 
### 1. Pre-Flight Checks
- [ ] Check if git working directory is clean
- [ ] Verify all dependencies installed
- [ ] Confirm database is running
- [ ] Validate environment variables
 
### 2. Load State
Read in order:
1. `PRODUCT.md` - Product requirements
2. `.agentful/state.json` - Current state
3. `.agentful/completion.json` - Progress
4. `.agentful/decisions.json` - Pending decisions
 
### 3. Custom Initialization
 
If state.json doesn't exist:
```bash
# Run custom setup
npm run setup:dev
 
# Seed database if needed
npm run db:seed
 
# Run initial validation
npx tsc --noEmit

 
### Custom Status Display
 
Edit `.claude/commands/agentful-status.md`:
 
```markdown
---
name: agentful-status
description: Display detailed project status with custom metrics
---
 
# agentful Status
 
## Display Format
 
### Progress Overview

 
### Custom Metrics
 
Add project-specific metrics:

---
name: deploy
description: Deploy application to production with safety checks
---
 
# Deploy Command
 
## Pre-Deployment Checklist
 
1. **Run all tests**
```bash
npm test

npx tsc --noEmit

npm run build

npm audit --production

npm run test:e2e

 
Usage: `/deploy`
 
### Database Migration Command
 
Create `.claude/commands/migrate.md`:
 
```markdown
---
name: migrate
description: Run database migrations with safety checks
---
 
# Database Migration
 
## Safety Checks
 
1. **Backup database**
```bash
npm run db:backup

npm run db:status

# Read migration files to validate safety

npx prisma migrate dev --name migration_name

npx prisma migrate deploy

 
Usage: `/migrate`
 
### Code Review Command
 
Create `.claude/commands/review.md`:
 
```markdown
---
name: review
description: Perform comprehensive code review of changes
---
 
# Code Review
 
## Review Scope
 
1. **Git Changes**
```bash
git diff main...HEAD

Task("reviewer", "Perform comprehensive review of recent changes")

Task("fixer", "Fix issues found during review")

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
              Code Review Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Files Changed: 7
Lines Added: +342
Lines Removed: -89
 
Issues Found:
  🔴 Critical: 0
  🟡 Warning: 3
  🔵 Info: 5
 
Recommendations:
  1. Add error handling to AuthService.login
  2. Extract magic strings to constants
  3. Add JSDoc comments to public APIs
 
Status: ✅ Approved (with minor suggestions)

 
Usage: `/review`
 
### Documentation Generation Command
 
Create `.claude/commands/docs.md`:
 
```markdown
---
name: docs
description: Generate API documentation from code
---
 
# Generate Documentation
 
## API Documentation
 
1. **Scan for API routes**
```bash
find src/app/api -name "route.ts"

npm run docs:generate

find src/components -name "*.tsx" -o -name "*.jsx"

 
Usage: `/docs`
 
## Workflow Automation
 
### Pre-Commit Workflow
 
Create `.claude/commands/pre-commit.md`:
 
```markdown
---
name: pre-commit
description: Run all checks before committing code
---
 
# Pre-Commit Checks
 
## Sequence
 
1. **Type Check**
```bash
npx tsc --noEmit

npm run lint

npm test

npm test -- --coverage

npx knip

npm audit --production

✅ All checks passed - Ready to commit

❌ Pre-commit checks failed:
  - TypeScript: 3 errors
  - Lint: 7 warnings
  - Coverage: 72% (needs 80%)
 
Run /fix to auto-fix issues

 
### Integration with Git Hooks
 
Add to `package.json`:
 
```json
{
  "scripts": {
    "prepare": "husky install",
    "pre-commit": "echo 'Running agentful pre-commit checks' && claude /pre-commit || exit 1"
  }
}

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
 
# Run agentful pre-commit checks
npx agentful pre-commit
 
# Exit on failure
if [ $? -ne 0 ]; then
  echo "❌ Pre-commit checks failed. Commit aborted."
  exit 1
fi

name: agentful Validation
 
on:
  pull_request:
    branches: [main]
 
jobs:
  validate:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v3
 
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Run agentful validation
        run: |
          npx @itz4blitz/agentful init --bare
          npx agentful validate
 
      - name: Upload validation report
        uses: actions/upload-artifact@v3
        with:
          name: validation-report
          path: .agentful/last-validation.json

stages:
  - validate
 
agentful-validation:
  stage: validate
  image: node:18
 
  script:
    - npm ci
    - npx @itz4blitz/agentful init --bare
    - npx agentful validate
 
  artifacts:
    paths:
      - .agentful/last-validation.json
    reports:
      junit: .agentful/validation-report.xml

---
name: feature
description: Complete workflow for implementing a new feature
---
 
# Feature Development
 
## Inputs
 
Feature name from user input or PRODUCT.md
 
## Workflow
 
### 1. Planning Phase
- Read PRODUCT.md for feature requirements
- Create feature branch
- Document implementation plan
 
### 2. Design Phase
Task("architect", "Design database schema and API endpoints for feature")
 
### 3. Backend Phase
Task("backend", "Implement backend services and API routes")
 
### 4. Frontend Phase
Task("frontend", "Implement UI components and pages")
 
### 5. Testing Phase
Task("tester", "Write comprehensive tests")
 
### 6. Review Phase
Task("reviewer", "Review implementation")
 
### 7. Fix Phase (if needed)
Task("fixer", "Fix any issues found in review")
 
### 8. Documentation Phase
Task("docs", "Generate API documentation")
 
### 9. Validation Phase
Run all quality checks
 
### 10. Completion
- Update completion.json
- Mark feature as complete
- Report summary
 
## Example Usage
 
User: `/feature user-profile`
 
agentful:
1. Reads user-profile from PRODUCT.md
2. Creates feature branch feature/user-profile
3. Implements all requirements
4. Validates quality
5. Reports completion

---
name: refactor
description: Safe refactoring workflow with automated testing
---
 
# Refactor Workflow
 
## Pre-Refactor
 
1. **Baseline tests**
```bash
npm test

git checkout -b refactor/backup-$(date +%s)

# All tests must pass
npm test
 
# No regressions
npm run test:e2e
 
# Performance maintained
npm run benchmark

Task("reviewer", "Review refactored code")

 
### Hotfix Workflow
 
Create `.claude/commands/hotfix.md`:
 
```markdown
---
name: hotfix
description: Emergency fix workflow for production issues
---
 
# Hotfix Workflow
 
## Priority: CRITICAL
 
This workflow bypasses normal process for urgent fixes.
 
## Process
 
1. **Create hotfix branch**
```bash
git checkout -b hotfix/$(date +%s)

# Type check only
npx tsc --noEmit
 
# Critical tests only
npm test -- --testNamePattern="critical"

npm run deploy:staging

npm run test:smoke

npm run deploy:prod

 
## Environment-Specific Workflows
 
### Development Workflow
 
`.claude/commands/dev.md`:
 
```markdown
---
name: dev
description: Start development environment with watchers
---
 
# Development Mode
 
## Start Services
 
1. **Database**
```bash
npm run db:start

npm run dev:api

npm run dev

# TypeScript watcher
npx tsc --watch
 
# Test watcher
npm test -- --watch
 
# Lint watcher
npm run lint -- --watch

 
### Staging Workflow
 
`.claude/commands/staging.md`:
 
```markdown
---
name: staging
description: Deploy to staging environment for testing
---
 
# Staging Deployment
 
## Pre-Deploy
 
1. **Run full test suite**
```bash
npm test
npm run test:e2e

npm run build:staging

npm audit --production

npm run deploy:staging

npm run test:smoke:staging

✅ Deployed to staging
URL: https://staging.example.com
Commit: abc123
Tests: ✅ All passing

 
### Production Workflow
 
`.claude/commands/production.md`:
 
```markdown
---
name: production
description: Deploy to production with full validation
---
 
# Production Deployment
 
## Pre-Deploy Checklist
 
- [ ] All tests passing (100%)
- [ ] Coverage ≥ 80%
- [ ] No type errors (adapts to stack)
- [ ] No lint errors
- [ ] No dead code
- [ ] No security vulnerabilities
- [ ] Staging tests passed
- [ ] Performance benchmarks met
- [ ] Documentation updated
- [ ] CHANGELOG updated
- [ ] Migration plan tested
- [ ] Rollback plan ready
 
## Deployment Steps
 
1. **Create release tag**
```bash
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

npm run db:migrate:prod

npm run deploy:prod

npm run test:smoke:prod

npm run rollback:prod
git revert HEAD
npm run deploy:prod

 
## Workflow Best Practices
 
### 1. Keep Workflows Simple
- One purpose per workflow
- Clear success criteria
- Handle failures gracefully
 
### 2. Always Validate
- Type check before committing
- Test before deploying
- Monitor after deploying
 
### 3. Provide Feedback
- Show progress clearly
- Report errors helpfully
- Suggest next actions
 
### 4. Enable Automation
- Integrate with CI/CD
- Use git hooks
- Automate repetitive tasks
 
### 5. Document Everything
- Comment complex logic
- Provide examples
- Maintain CHANGELOG
 
## Workflow Examples Repository
 
See `.claude/workflows/` for more examples:
 
- `feature.mdx` - Feature development
- `bugfix.mdx` - Bug fixing workflow
- `release.mdx` - Release management
- `performance.mdx` - Performance optimization
- `security.mdx` - Security audit workflow
 
## Next Steps
 
- [Configuration Overview](./index) - Back to configuration overview
- [Project Structure](./project-structure) - File and directory requirements