Slash Commands

Slash commands are your control interface for agentful - simple, human-readable commands that trigger complex autonomous workflows. Think of them as the steering wheel, accelerator, and dashboard for autonomous development.

What Are Slash Commands?

Slash commands are defined in .claude/commands/ as markdown files with frontmatter:

---
name: agentful-start
description: Start or resume autonomous product development loop
---
 
# agentful Start
 
This command initiates the autonomous product development loop.

When you type /agentful-start, Claude Code reads the command definition and executes the workflow described within it.

Why Slash Commands?

The Problem with "Just Talk to AI"

Without structured commands:

You: "Start working on my project"
 
AI: "What should I build?"
You: "It's in PRODUCT.md"
AI: "Ok, what should I do first?"
You: "I don't know, you decide"
AI: "Should I build the frontend or backend?"
You: "I don't care, just start"
[...conversation continues for 10 minutes...]

The agentful Solution

With slash commands:

You: /agentful-start
 
agentful: [Immediately reads state, picks task, delegates, validates]
         → No questions
         → No ambiguity
         → Immediate action

Benefits

Benefit	Description
Consistency	Same command, same behavior, every time
Speed	No conversational overhead
Discoverable	Tab-completion shows all commands
Composable	Commands can call other commands
Traceable	Clear audit trail of what was run
Parameterizable	Pass flags and options

The Four Core Commands

agentful has four primary commands for autonomous development:

1. `/agentful-start` - The Engine Starter

Purpose: Start or resume autonomous product development loop

What it does:

1. Load State
   - Read PRODUCT.md (what we're building)
   - Read .agentful/state.json (current work state)
   - Read .agentful/completion.json (progress)
   - Read .agentful/decisions.json (pending decisions)
 
2. Check Blockers
   - If decisions pending → Warn user
   - Continue with unblocked work
 
3. Initialize State (if needed)
   - Create .agentful/state.json if missing
   - Set current_phase = "idle"
 
4. Delegate to Orchestrator
   - Task("orchestrator", "Run autonomous development loop")
   - Orchestrator picks next task
   - Delegates to specialists
   - Validates results
   - Updates progress
   - Loops until complete

Usage:

# Manual mode (one task at a time)
/agentful-start
 
# Continuous mode (24/7 development)
/ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"

When to use:

First time starting development
After resolving decisions
After manual intervention
To check progress while continuing

Output:

agentful: Starting autonomous development loop...
 
  → Detected Next.js + TypeScript + Prisma + Tailwind
  → Reading state: auth = 30% complete
  → Next task: Complete auth frontend
  → Delegating to @frontend agent...
 
[Agent completes work]
 
  → Validating changes...
     TypeScript: ✅
     Lint: ✅
     Tests: ✅
     Coverage: 85% ✅
  → Auth = 100% complete
  → Next: User profile feature

2. `/agentful-status` - The Dashboard

Purpose: Show current progress, completion percentage, and what's being worked on

What it does:

1. Read state files
   - state.json (current work, phase, iterations)
   - completion.json (features, gates)
   - decisions.json (pending decisions)
   - PRODUCT.md (product name)
 
2. Format output beautifully
   - ASCII art tables
   - Progress bars
   - Status indicators
   - Quick action suggestions
 
3. Display:
   - Overall completion percentage
   - Feature-by-feature status
   - Quality gate status
   - Pending decisions
   - Current work

Usage:

/agentful-status

Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
           agentful Development Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Product: Task Management App
Overall Progress: ████████░░░░░░░░░░░░ 48%
Phase: implementing
Iterations: 12
 
┌─────────────────────┬──────────┬─────────┬────────────────┐
│ Feature             │ Status   │ Score   │ Notes          │
├─────────────────────┼──────────┼─────────┼────────────────┤
│ Authentication      │ ✅ Done  │ 100%    │                │
│ User Profile        │ 🔄 Active│ 45%     │ Backend done   │
│ Dashboard           │ ⏸ Pending│ 0%      │ Blocked on UX  │
│ Settings            │ ⏸ Pending│ 0%      │                │
└─────────────────────┴──────────┴─────────┴────────────────┘
 
┌─────────────────────┬────────┐
│ Quality Gate        │ Status │
├─────────────────────┼────────┤
│ Tests Passing       │ ✅     │
│ No Type Errors      │ ✅     │
│ No Dead Code        │ ❌     │
│ Coverage ≥ 80%      │ ⚠️ 72% │
└─────────────────────┴────────┘
 
⚠️  Decisions Needed:
 
1. "Should dashboard use grid or list layout?"
   Blocking: dashboard-feature
   → Run /agentful-decide to resolve
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Next Actions:
  • /agentful-start    - Continue development
  • /agentful-decide  - Answer pending decisions
  • /agentful-validate- Run quality checks

When to use:

Check progress without continuing work
See what's blocking development
Get a quick overview
Before making decisions

3. `/agentful-decide` - The Decision Resolver

Purpose: Answer pending decisions that are blocking development progress

What it does:

1. Read decisions.json
   - Get list of pending decisions
   - Each has: question, options, context, blocking
 
2. Present to user interactively
   - Use AskUserQuestion tool
   - Show question, options, context
   - Accept user selection
 
3. Record decision
   - Move from pending to resolved
   - Store answer with timestamp
 
4. Update state
   - Remove from state.json blocked_on array
   - Allow blocked features to proceed
 
5. Show summary
   - What was resolved
   - What's now unblocked

Usage:

/agentful-decide

Output:

⚠️  You have 2 pending decisions:
 
[1/2] Should auth use JWT or session cookies?
 
    Context: Building authentication system
    Blocking: auth-feature, user-profile-feature
 
    Options:
      [1] JWT (stateless, scalable)
      [2] Sessions (simpler, built-in)
      [3] Clerk (managed service)
 
    Your choice: > 1
 
[2/2] Which database provider?
 
    Context: Need database for user data
    Blocking: database-setup
 
    Options:
      [1] PostgreSQL (robust, scalable)
      [2] MySQL (widely supported)
      [3] SQLite (simple, file-based)
      [4] MongoDB (NoSQL, flexible)
 
    Your choice: > 1
 
✅ All decisions resolved!
 
Unblocked features:
  - auth-feature (can now proceed)
  - user-profile-feature (can now proceed)
  - database-setup (can now proceed)
 
Run /agentful-start to continue development.

When to use:

When status shows pending decisions
Before continuing development
To unblock features
To provide technical direction

4. `/agentful-validate` - The Quality Check

Purpose: Run all quality checks and validation gates

What it does:

1. Delegate to reviewer agent
   - Task("reviewer", "Run all validation checks")
 
2. Reviewer runs 8 checks:
   - TypeScript (npx tsc --noEmit)
   - Lint (npm run lint)
   - Dead code detection
   - Tests (npm test)
   - Coverage (≥ 80%)
   - Security (secrets, vulnerabilities, logs)
   - Manual code review
   - Console log check
 
3. Display results
   - Pass/fail for each check
   - List of issues found
   - Suggestions for fixing
 
4. Update completion.json
   - Set gate statuses
   - Track what's passing/failing
 
5. Offer auto-fix
   - Ask if user wants to run fixer

Usage:

# Full validation
/agentful-validate
 
# Quick checks (with flags)
/agentful-validate --type-check
/agentful-validate --tests
/agentful-validate --security

Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
              Validation Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
TypeScript      ✅ PASS - No type errors
Lint            ✅ PASS - No lint errors
Dead Code       ❌ FAIL - 3 issues found
Tests           ✅ PASS - 47 tests passed
Coverage        ⚠️  WARN - 72% (needs 80%)
Security        ⚠️  WARN - 2 issues found
 
Overall: ❌ FAILED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Issues that must be fixed:
 
1. [Dead Code] Unused export: formatDate in src/utils/date.ts
2. [Dead Code] Unused file: src/components/OldWidget.tsx
3. [Dead Code] Unused dependency: lodash in package.json
4. [Coverage] 8 percentage points below threshold (72% vs 80%)
5. [Security] console.log in src/auth/login.ts:45
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Would you like to auto-fix these issues? [y/N]: > y
 
Delegating to @fixer agent...
 
[Fixer removes dead code, adds tests, removes console.log]
 
Re-validating...
TypeScript      ✅ PASS
Lint            ✅ PASS
Dead Code       ✅ PASS
Tests           ✅ PASS
Coverage        ✅ PASS - 82%
Security        ✅ PASS
 
Overall: ✅ ALL CHECKS PASSED

When to use:

After manual code changes
Before committing
To check code quality
To see what needs fixing
In CI/CD pipelines

Command Architecture

Command Structure

Each command is a markdown file with:

---
name: command-name
description: Human-readable description
---
 
# Command Name
 
This command does X, Y, Z.
 
## Process
 
Step-by-step instructions...
 
## Implementation
 
Detailed steps...
 
## Example Flow
 
Example usage...

Command Communication

Commands communicate through:

State files - Read .agentful/*.json
Agent delegation - Use Task tool to spawn agents
Tool execution - Run Bash, Read, Write, etc.

Example command that delegates:

## Process
 
### 1. Run Reviewer

Task("reviewer", "Run all validation checks on the current codebase and report results.")

 
### 2. Display Results
After reviewer completes, display formatted output...

Command Composition

Commands can call other commands:

# In agentful-start.md
 
## Process
 
### If pending decisions found

User needs to resolve decisions first.

→ Run: /agentful-decide

Command Best Practices

DO ✅

Be specific - Clear descriptions of what command does
Check state - Always read state files first
Delegate appropriately - Use Task tool for agents
Format output - Make it readable (tables, progress bars)
Handle errors - Graceful failure with helpful messages
Suggest next actions - Guide user on what to do next

DON'T ❌

Don't implement directly - Delegate to agents
Don't skip state checks - Always read state files
Don't hardcode paths - Use relative or detected paths
Don't assume - Check files exist before reading
Don't be silent - Always provide feedback

Creating Custom Commands

You can add your own commands in .claude/commands/:

---
name: agentful-deploy
description: Deploy to production after all validations pass
---
 
# agentful Deploy
 
This command deploys your application to production.
 
## Preconditions
 
Check all gates first:
```bash
# Delegate to validate
Task("reviewer", "Run all validation checks")

If any checks fail:

❌ Cannot deploy: Quality gates not passing
Run /agentful-validate to see issues

Deployment Process

Run tests
Build application
Deploy to production (Vercel/Netlify/etc.)
Verify deployment
Tag release

 
Then use it:
```bash
/agentful-deploy

Command Reference Summary

Command	Purpose	When to Use
`/agentful-start`	Start/resume autonomous development	Always (primary command)
`/agentful-status`	Show progress and state	Checking progress
`/agentful-decide`	Resolve pending decisions	When blocked
`/agentful-validate`	Run quality checks	After manual changes

Command Flow Examples

Typical Development Session

# Start development
/agentful-start
 
[Works for 30 minutes, completes 3 features]
 
# Check progress
/agentful-status
 
# See a decision is needed, resolve it
/agentful-decide
 
# Continue development
/agentful-start
 
[Works for 20 minutes, then blocked by decision]
 
[You make some manual code changes]
 
# Validate your changes
/agentful-validate
 
# Continue autonomous development
/agentful-start

24/7 Development

# Start continuous mode
/ralph-loop "/agentful-start" --max-iterations 50
 
# Check in anytime
/agentful-status
 
# If stuck on decisions
/agentful-decide
 
# Loop resumes automatically

Summary

Slash commands are your interface to agentful:

Simple - One command triggers complex workflows
Consistent - Same behavior every time
Composable - Commands can call other commands
Traceable - Clear audit trail
Extensible - Add your own commands

They transform autonomous development from a conversation into a controlled, observable process.

Next: Learn about skills

What Are Slash Commands?

Why Slash Commands?

The Problem with "Just Talk to AI"

The agentful Solution

Benefits

The Four Core Commands

1. /agentful-start - The Engine Starter

2. /agentful-status - The Dashboard

3. /agentful-decide - The Decision Resolver

4. /agentful-validate - The Quality Check

Command Architecture

Command Structure

Command Communication

Command Composition

Command Best Practices

DO ✅

DON'T ❌

Creating Custom Commands

Deployment Process

Command Reference Summary

Command Flow Examples

Typical Development Session

24/7 Development

Summary

1. `/agentful-start` - The Engine Starter

2. `/agentful-status` - The Dashboard

3. `/agentful-decide` - The Decision Resolver

4. `/agentful-validate` - The Quality Check