Running AD-SDLC in Headless Mode

Version: 1.0.0 Last Updated: 2025-01-01

This guide explains how to run AD-SDLC pipelines in non-interactive (headless) mode for automation, CI/CD integration, and scripting.

Overview
Quick Start
CLI Flags Reference
Convenience Scripts
Environment Variables
CI/CD Integration
Best Practices
Troubleshooting

Overview

By default, the Claude CLI runs in interactive mode, waiting for user input and confirmation. For automated pipelines, you need headless mode which:

Exits automatically after task completion
Pre-approves specific tool permissions
Limits execution turns
Provides structured output for parsing

Approval mode in non-interactive environments: When the pipeline's approval_mode is set to manual, it requires an interactive TTY to prompt the user. If no TTY is available (CI/CD runners, Docker containers, cron jobs), manual mode denies approval by default and the pipeline will not proceed past approval gates. Always use --approval-mode auto (or set approval_mode: "auto" in workflow.yaml) when running without a terminal.

Interactive vs Headless

Aspect	Interactive	Headless
User Input	Required	None
Tool Permissions	Prompted	Pre-approved
Exit Behavior	Stays open	Auto-exits
Output	Rich console	Text/JSON
Use Case	Development	Automation

Quick Start

Basic Headless Command

# Use -p flag for non-interactive execution
claude -p "Initialize AD-SDLC" \
  --allowedTools "Read,Write,Edit,Glob,Grep,Bash(mkdir:*)" \
  --output-format text

Using Convenience Scripts

# Initialize project
./.ad-sdlc/scripts/ad-sdlc-init.sh

# Generate issues from SDS
./.ad-sdlc/scripts/ad-sdlc-generate-issues.sh

# Run full pipeline
./.ad-sdlc/scripts/ad-sdlc-full-pipeline.sh

CLI Flags Reference

Essential Flags

Flag	Alias	Purpose	Example
`--print`	`-p`	Non-interactive mode (auto-exit)	`claude -p "task"`
`--allowedTools`		Pre-approve specific tools	`--allowedTools "Read,Write"`
`--output-format`		Output format (text/json)	`--output-format json`

Additional Flags

Flag	Purpose	Example
`--continue` / `-c`	Continue previous session	`claude -p -c "continue"`
`--dangerously-skip-permissions`	Approve all permissions	Use in trusted environments only
`--model`	Specify Claude model	`--model claude-sonnet-4-20250514`
`--resume`	Resume specific session	`--resume session-id`

Tool Permission Patterns

The --allowedTools flag supports patterns:

# Specific tools
--allowedTools "Read,Write,Edit"

# Bash with wildcards
--allowedTools "Bash(git:*)"           # All git commands
--allowedTools "Bash(npm:*)"           # All npm commands
--allowedTools "Bash(mkdir:*),Bash(cp:*)"  # Multiple bash patterns

# All tools (dangerous)
--allowedTools "*"

Convenience Scripts

AD-SDLC provides ready-to-use scripts in .ad-sdlc/scripts/:

Script Overview

Script	Purpose
`ad-sdlc-init.sh`	Initialize AD-SDLC for a project
`ad-sdlc-analyze-docs.sh`	Analyze existing documents
`ad-sdlc-generate-issues.sh`	Generate GitHub issues from SDS
`ad-sdlc-implement.sh`	Implement specific or all issues
`ad-sdlc-full-pipeline.sh`	Run complete pipeline

Usage Examples

Initialize a Project

# Current directory
./.ad-sdlc/scripts/ad-sdlc-init.sh

# Specific path
./.ad-sdlc/scripts/ad-sdlc-init.sh /path/to/project

Analyze Documents

./.ad-sdlc/scripts/ad-sdlc-analyze-docs.sh

# Output: .ad-sdlc/scratchpad/documents/current_state.yaml

Generate Issues

# Preview (dry run)
./.ad-sdlc/scripts/ad-sdlc-generate-issues.sh . --dry-run

# Create issues on GitHub
./.ad-sdlc/scripts/ad-sdlc-generate-issues.sh

Implement Issues

# Single issue
./.ad-sdlc/scripts/ad-sdlc-implement.sh . 42

# All pending issues (P0 first)
./.ad-sdlc/scripts/ad-sdlc-implement.sh

Full Pipeline

# Auto-detect mode
./.ad-sdlc/scripts/ad-sdlc-full-pipeline.sh

# Specific mode
./.ad-sdlc/scripts/ad-sdlc-full-pipeline.sh . greenfield
./.ad-sdlc/scripts/ad-sdlc-full-pipeline.sh . enhancement
./.ad-sdlc/scripts/ad-sdlc-full-pipeline.sh . import

Environment Variables

Required

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Optional

# Skip test execution during implementation
export SKIP_TESTS=true

# Skip confirmation prompts
export SKIP_CONFIRMATION=true

# Bypass all permission checks (DANGEROUS)
export DANGEROUSLY_SKIP_PERMISSIONS=true

# GitHub token (if not using gh auth)
export GH_TOKEN="ghp_..."

CI/CD Integration

CI/CD environments do not have an interactive TTY. Set --approval-mode auto on the command line or approval_mode: "auto" in workflow.yaml so the pipeline never blocks waiting for user input. Using manual mode in CI will cause all approval gates to be denied by default.

GitHub Actions

name: AD-SDLC Pipeline

on:
  workflow_dispatch:
    inputs:
      task:
        description: 'Task to execute'
        required: true
        type: string
      mode:
        description: 'Pipeline mode'
        required: false
        default: 'auto'
        type: choice
        options:
          - auto
          - greenfield
          - enhancement
          - import

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

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

      - name: Install Claude CLI
        run: npm install -g @anthropic-ai/claude-code

      - name: Run AD-SDLC
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          chmod +x .ad-sdlc/scripts/*.sh
          ./.ad-sdlc/scripts/ad-sdlc-full-pipeline.sh . ${{ github.event.inputs.mode }}

      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: ad-sdlc-output
          path: |
            docs/*.md
            .ad-sdlc/logs/
            .ad-sdlc/scratchpad/

GitLab CI

ad-sdlc-pipeline:
  image: node:22
  stage: build
  script:
    - npm install -g @anthropic-ai/claude-code
    - chmod +x .ad-sdlc/scripts/*.sh
    - ./.ad-sdlc/scripts/ad-sdlc-full-pipeline.sh . auto
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
    SKIP_CONFIRMATION: 'true'
  artifacts:
    paths:
      - docs/
      - .ad-sdlc/logs/
    expire_in: 1 week
  when: manual

Jenkins Pipeline

pipeline {
    agent any

    environment {
        ANTHROPIC_API_KEY = credentials('anthropic-api-key')
        SKIP_CONFIRMATION = 'true'
    }

    stages {
        stage('Setup') {
            steps {
                sh 'npm install -g @anthropic-ai/claude-code'
                sh 'chmod +x .ad-sdlc/scripts/*.sh'
            }
        }

        stage('Run Pipeline') {
            steps {
                sh './.ad-sdlc/scripts/ad-sdlc-full-pipeline.sh . auto'
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: 'docs/*.md, .ad-sdlc/logs/**/*'
        }
    }
}

Best Practices

1. Start with Dry Runs

Always preview before creating resources:

# Preview issues
./.ad-sdlc/scripts/ad-sdlc-generate-issues.sh . --dry-run

# Review output
cat .ad-sdlc/scratchpad/issues/generated_issues.yaml

2. Limit Tool Permissions

Only allow necessary tools:

# Read-only analysis
--allowedTools "Read,Glob,Grep"

# Document generation
--allowedTools "Read,Write,Edit,Glob,Grep"

# Full development
--allowedTools "Read,Write,Edit,Glob,Grep,Bash,Task"

3. Capture Output for Debugging

# Save output to file
./.ad-sdlc/scripts/ad-sdlc-full-pipeline.sh 2>&1 | tee pipeline.log

# JSON output for parsing
claude -p "task" --output-format json > result.json

4. Handle Interruptions

# Resume interrupted session
claude --continue

# Or resume specific session
claude --resume "session-id"

Troubleshooting

Script Not Executing

# Check permissions
ls -la .ad-sdlc/scripts/

# Fix permissions
chmod +x .ad-sdlc/scripts/*.sh

API Key Issues

# Verify key is set
echo $ANTHROPIC_API_KEY | head -c 15

# Should show: sk-ant-api03-...

Claude CLI Not Found

# Install globally
npm install -g @anthropic-ai/claude-code

# Or use npx
npx @anthropic-ai/claude-code -p "task"

Pipeline Timeout

Break into smaller tasks if timeout occurs:

# Run stages separately
./.ad-sdlc/scripts/ad-sdlc-analyze-docs.sh
./.ad-sdlc/scripts/ad-sdlc-generate-issues.sh
./.ad-sdlc/scripts/ad-sdlc-implement.sh

Permission Denied Errors

# Check which tool needs permission
# Add to --allowedTools or use pattern

# For git operations
--allowedTools "Bash(git:*)"

# For npm/yarn
--allowedTools "Bash(npm:*),Bash(yarn:*)"

Session State Issues

# Clear session and restart
rm -rf .ad-sdlc/scratchpad/progress/*

# Or use fresh session
claude -p "task" --no-resume

Security Considerations

Production Environments

Never commit API keys - Use environment variables or secrets management
Limit tool permissions - Only allow what's necessary
Review before merge - Generated code should be reviewed
Use isolated environments - Run in containers or VMs
Audit logs - Keep .ad-sdlc/logs/ for audit trails

CI/CD Security

# GitHub Actions - use secrets
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

# Never print secrets
run: |
  echo "Key length: ${#ANTHROPIC_API_KEY}"  # OK
  # echo $ANTHROPIC_API_KEY                 # NEVER do this

FilesExpand file tree

headless-execution.md

Latest commit

History