Workflow Examples

Real-world scenarios showing how to use Arial effectively.

Example 1: Building a New Feature

Scenario: Add user authentication and user management to an Express.js API.

Step 1: Create Specs

Create two focused spec files:

specs/auth.md:

# User Authentication

## Goal
Add JWT-based authentication with registration and login.

## Requirements
- POST /auth/register - Create new user (email, password, name)
- POST /auth/login - Authenticate and return JWT
- Password hashing with bcrypt
- Token expiry: 24 hours

## Technical Notes
- Use jsonwebtoken package
- Store JWT secret in JWT_SECRET env var
- Follow existing controller patterns

specs/users.md:

# User Management API

## Goal
Create REST endpoints for user CRUD operations.

## Requirements
- GET /users - List all users (paginated)
- GET /users/:id - Get user by ID
- PUT /users/:id - Update user
- DELETE /users/:id - Delete user
- Auth middleware to protect all routes

## Technical Notes
- Follow existing controller patterns
- Add input validation with Joi
- Return proper HTTP status codes

Step 2: Run Arial

arial init
arial plan --specs ./specs
arial run

Step 3: Monitor Progress

Watch the TUI or check status:

arial status

Both workstreams run in parallel. When complete, changes merge to your branch.

Example 2: Handling Failed Workstreams

Scenario: A workstream fails during execution.

Identify the Problem

arial status

Output:

Workstreams:

✓ auth - User Authentication
  Completed in 3m 12s

✗ users - User Management API
  Error: Could not find UserService class

Investigate

Check what happened:

# Look at the workstream's branch
git log arial/users --oneline -5
git diff main..arial/users

Fix and Retry

Option 1: Update the spec and re-run:

# Edit specs/users.md to clarify the issue
# Then re-plan
arial plan --specs ./specs -y
arial run

Option 2: Fix manually and mark as done:

# Checkout the branch
git checkout arial/users

# Make fixes
# ...

# Commit and merge manually
git checkout main
git merge arial/users

Example 3: Verbose Mode for Debugging

Scenario: You want to see what the agents are doing.

Run with Verbose Output

arial run --verbose

This shows all agent output in real-time:

• Tool calls (file reads, writes, searches)
• Agent reasoning
• Errors and warnings

When to Use Verbose Mode

• Debugging failed workstreams
• Understanding agent behavior
• Learning how agents approach problems
• Checking if agents are on the right track

Example 4: Refactoring Across Multiple Areas

Scenario: Refactor a monolithic file into modules.

Create Parallel Specs

specs/string-utils.md:

# Extract String Utilities

## Goal
Move string utilities from src/utils.js to src/utils/string.js

## Requirements
- Create src/utils/string.js with:
  - capitalize()
  - truncate()
  - slugify()
  - All string-related functions from utils.js
- Update all imports across codebase
- Export from src/utils/index.js for backwards compatibility

specs/date-utils.md:

# Extract Date Utilities

## Goal
Move date utilities from src/utils.js to src/utils/date.js

## Requirements
- Create src/utils/date.js with:
  - formatDate()
  - parseDate()
  - getRelativeTime()
  - All date-related functions from utils.js
- Update all imports across codebase
- Export from src/utils/index.js for backwards compatibility

specs/validation-utils.md:

# Extract Validation Utilities

## Goal
Move validation utilities from src/utils.js to src/utils/validation.js

## Requirements
- Create src/utils/validation.js with:
  - isEmail()
  - isPhone()
  - validatePassword()
  - All validation functions from utils.js
- Update all imports across codebase
- Export from src/utils/index.js for backwards compatibility

Execute

arial plan --specs ./specs
arial run

All three refactorings run in parallel. Since they touch different files (mostly), merges should be clean.

Example 5: Adding Tests

Scenario: Add comprehensive tests to existing code.

Spec for Test Coverage

specs/auth-tests.md:

# Auth Service Tests

## Goal
Add comprehensive unit tests for src/services/AuthService.ts

## Requirements
- Test register() - success, validation errors, duplicate email
- Test login() - success, wrong password, user not found
- Test verifyToken() - valid token, expired token, invalid token
- Test refreshToken() - success, invalid refresh token

## Technical Notes
- Use existing Vitest setup
- Mock database calls
- Follow patterns from src/services/__tests__/
- Aim for 90%+ coverage

specs/api-tests.md:

# API Integration Tests

## Goal
Add integration tests for user API endpoints

## Requirements
- Test all CRUD endpoints
- Test authentication middleware
- Test error responses
- Test pagination

## Technical Notes
- Use supertest for HTTP testing
- Set up test database
- Clean up between tests

Execute

arial plan --specs ./specs
arial run

Example 6: CI/CD Integration

Scenario: Run Arial in a CI pipeline.

GitHub Actions Example

name: Arial Build

on:
  workflow_dispatch:
    inputs:
      specs_dir:
        description: 'Path to specs directory'
        required: true
        default: './specs'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Arial
        run: npm install -g arial

      - name: Initialize
        run: arial init

      - name: Plan
        run: arial plan --specs ${{ inputs.specs_dir }} -y --skip-suggestions

      - name: Execute
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: arial run --no-tui

      - name: Check Status
        run: arial status --json > status.json

      - name: Upload Status
        uses: actions/upload-artifact@v4
        with:
          name: arial-status
          path: status.json

Key CI/CD Flags

Example 7: Quick Single Spec

Scenario: You just want to run one spec quickly.

Direct Approach

mkdir -p specs
cat > specs/fix.md << 'EOF'
# Fix Login Bug

## Goal
Fix the bug where login fails for emails with plus signs.

## Requirements
- Update email validation to allow + character
- Add test case for plus-sign emails
- Test existing login flows still work
EOF

arial init
arial plan --specs ./specs -y
arial run

Common Patterns

Check Before Execute

Review what Arial will do:

arial plan --specs ./specs    # See workstream preview
# Review, then:
arial run

Resume After Interrupt

arial run       # Running...
# Ctrl+C
arial run       # Resumes from where it stopped

Monitor in Another Terminal

# Terminal 1
arial run

# Terminal 2
watch -n 5 arial status --json

Tips for Success

1. Keep specs focused: One concern per spec file
2. Be specific: Vague specs lead to unexpected results
3. Include context: Reference existing patterns and files
4. Use verbose mode: Add --verbose when debugging
5. Review branches: Check git branches before merge if unsure
6. Start small: Test with 1-2 workstreams before scaling up