Frequently Asked Questions (FAQ)

Version: 1.1.0

This document answers common questions about the AD-SDLC system. For detailed troubleshooting procedures, see the Troubleshooting Guide.

General Questions
Setup & Configuration
Usage & Workflow
Documents & Output
Agents & Customization
Troubleshooting
Advanced Topics
Enterprise & Security

General Questions

What is AD-SDLC?

AD-SDLC (Agent-Driven Software Development Lifecycle) is an automated pipeline that uses Claude-powered agents to transform natural language requirements into production-ready code. It handles the entire software development process: requirements gathering, documentation, issue tracking, implementation, and code review.

How long does a typical project take?

Project Type	Estimated Time
Simple feature	15-20 minutes
Medium complexity	30-45 minutes
Complex feature	45-90 minutes
Full application	2-4 hours

Times depend on:

Complexity of requirements
Number of issues generated
API response times
Code review iterations

What languages/frameworks are supported?

AD-SDLC is language-agnostic. It can generate code in any language Claude supports, including:

TypeScript/JavaScript
Python
Java
Go
Rust
C/C++
Ruby
PHP

Do I need a GitHub account?

GitHub is optional but recommended. Without GitHub:

Documents are still generated locally
Issues are saved to .ad-sdlc/scratchpad/issues/
PRs are simulated as local branches

With GitHub:

Issues are created on your repository
PRs are opened automatically
Full automation of the development workflow

How much does it cost?

AD-SDLC uses Claude API tokens. Costs depend on:

Model used (Sonnet, Opus, Haiku)
Complexity of tasks
Number of iterations

Typical costs:

Task	Estimated Cost
Simple feature	$0.50 - $2.00
Medium feature	$2.00 - $5.00
Complex feature	$5.00 - $15.00

Use ad-sdlc status to view token usage during execution.

Setup & Configuration

How do I set my API key?

Option 1: Environment Variable (Recommended)

# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."

Option 2: Claude CLI Login

claude login

Option 3: Project-specific

# Create .env file (add to .gitignore!)
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Can I use a different model?

Yes. Configure in .ad-sdlc/config/agents.yaml:

agents:
  prd-writer:
    model: opus    # Use opus for complex reasoning
  worker:
    model: sonnet  # sonnet is good for most tasks
  validator:
    model: haiku   # haiku for simple validation tasks

How do I configure GitHub integration?

Authenticate GitHub CLI:
```
gh auth login
```

Configure repository in project:

# .ad-sdlc/config/workflow.yaml
github:
  repository: owner/repo-name
  default_branch: main
  create_issues: true
  create_prs: true

Can I use this in a corporate environment?

Yes. For corporate environments:

Proxy configuration:

export http_proxy=http://proxy.company.com:8080
export https_proxy=http://proxy.company.com:8080

Cloud provider integration:

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1

Air-gapped environments: Contact sales for enterprise deployment options.

Usage & Workflow

Can I intervene in the process?

Yes! The system supports intervention at multiple points:

Document Approval: Add to workflow.yaml:

stages:
  prd:
    require_approval: true

Pause Pipeline: Press Ctrl+C to pause. Resume with:
```
ad-sdlc resume
```
Manual Edits: Edit documents in .ad-sdlc/scratchpad/documents/ before proceeding.

What if something goes wrong?

Check status:

ad-sdlc status

View logs:

# All logs
cat .ad-sdlc/logs/pipeline.log

# Specific agent
cat .ad-sdlc/logs/agent-logs/worker.log

Resume from checkpoint:

ad-sdlc resume

Reset and start over:

ad-sdlc reset

Can I customize the agents?

Yes. Agent definitions are in .claude/agents/:

Modify prompts: Edit the markdown content in agent files.

Change tools:

---
name: worker
tools: Read, Write, Edit, Bash, Grep
---

Add new agents: Create a new .md file in .claude/agents/.

See Agent Customization Guide for details.

How do I customize document templates?

Templates are in .ad-sdlc/templates/:

PRD Template: prd-template.md
SRS Template: srs-template.md
SDS Template: sds-template.md
Issue Template: issue-template.md

Modify these files to change document structure.

Can agents work in parallel?

Yes. The Controller agent manages parallel execution:

# .ad-sdlc/config/workflow.yaml
execution:
  max_parallel_workers: 3  # Run up to 3 workers
  dependency_check: true   # Respect issue dependencies

Document generation is sequential, but issue implementation can be parallel.

Documents & Output

What documents are generated?

AD-SDLC generates three core documents following software engineering best practices:

Document	Purpose	Contains
PRD (Product Requirements Document)	Define WHAT to build	Features, user stories, acceptance criteria
SRS (Software Requirements Specification)	Define HOW it should work	Functional requirements, data models, interfaces
SDS (Software Design Specification)	Define HOW to build it	Architecture, components, APIs, database schema

Can I customize document templates?

Yes. Templates are in .ad-sdlc/templates/:

# List available templates
ls .ad-sdlc/templates/

# Customize PRD template
vim .ad-sdlc/templates/prd-template.md

Template variables available:

{{project_name}} - Project name
{{timestamp}} - Generation timestamp
{{requirements}} - Extracted requirements
{{version}} - Document version

How do I export documents to other formats?

# Export to Markdown files
ad-sdlc export --format markdown --output ./docs

# Export to PDF (requires pandoc)
ad-sdlc export --format pdf --output ./docs

# Export to Confluence (requires configuration)
ad-sdlc export --format confluence --space MYSPACE

Can I use existing documents instead of generating new ones?

Yes. Skip generation stages and provide your own:

# Use existing PRD
ad-sdlc run --prd docs/existing-prd.md

# Use existing PRD and SRS
ad-sdlc run --prd docs/prd.md --srs docs/srs.md

# Skip document generation entirely
ad-sdlc run --skip-stages prd,srs,sds --issues docs/issues.yaml

Where are the generated files saved?

All outputs are saved to the scratchpad directory:

.ad-sdlc/scratchpad/
├── documents/         # PRD, SRS, SDS
│   ├── prd.yaml
│   ├── srs.yaml
│   └── sds.yaml
├── issues/            # Generated issues
│   └── issues.yaml
├── progress/          # Implementation results
│   ├── checkpoint.yaml
│   └── results/
└── logs/              # Execution logs

Agents & Customization

What agents are available?

Agent	Purpose	Stage
Collector	Extract requirements from user input	Input Processing
PRD Writer	Generate Product Requirements Document	Documentation
SRS Writer	Generate Software Requirements Specification	Documentation
SDS Writer	Generate Software Design Specification	Documentation
Issue Generator	Create GitHub issues from SDS	Issue Management
Controller	Orchestrate worker execution	Execution
Worker	Implement issues (write code)	Implementation
PR Reviewer	Review and merge PRs	Quality Assurance
Regression Tester	Test for regressions	Testing

How do I create a custom agent?

Define agent metadata in .ad-sdlc/config/agents.yaml:

agents:
  my-agent:
    id: "my-agent"
    name: "My Agent"
    definition_file: ".claude/agents/my-agent.md"
    category: "custom"

Create agent definition in .claude/agents/my-agent.md
Add to workflow in .ad-sdlc/config/workflow.yaml

See the Agent Customization Guide for details.

Can agents use external tools?

Yes, via MCP (Model Context Protocol):

# .ad-sdlc/config/workflow.yaml
mcp:
  servers:
    my-tools:
      command: "node"
      args: ["tools/server.js"]

How do I change which model an agent uses?

# .ad-sdlc/config/workflow.yaml
agents:
  prd-writer:
    model: "opus"     # For complex reasoning
  worker:
    model: "sonnet"   # Default for most tasks
  collector:
    model: "haiku"    # For quick, simple tasks

Can I disable specific agents?

Yes. Skip agents or entire stages:

# Skip specific stages
ad-sdlc run --skip-stages srs,sds

# Disable worker verification
ad-sdlc run --no-verify

# Disable PR creation
ad-sdlc run --no-pr

Troubleshooting

For detailed troubleshooting procedures, see the Troubleshooting Guide.

Error: API Rate Limit Exceeded

Symptom:

Error: GitHub API rate limit exceeded. Retry after: 3600s

Cause: Too many GitHub API calls.

Solutions:

Wait for rate limit reset
Authenticate with GitHub CLI for higher limits:
```
gh auth login
```
Reduce parallelism:
```
execution:
  max_parallel_workers: 2
```

Error: Agent Timeout

Symptom:

Error: Agent 'worker' timed out after 600000ms

Cause: Task too complex or slow API response.

Solutions:

Increase timeout:

agents:
  worker:
    timeout_ms: 900000  # 15 minutes

Break down into smaller tasks
Check network connectivity

Error: Invalid Configuration

Symptom:

Error: Invalid configuration in workflow.yaml

Solution:

Validate configuration:
```
ad-sdlc validate
```
Check YAML syntax
Ensure all required fields are present

Error: Scratchpad Corruption

Symptom:

Error: Invalid YAML in .ad-sdlc/scratchpad/documents/output.yaml

Solutions:

Backup current state:

cp -r .ad-sdlc/scratchpad .ad-sdlc/scratchpad.bak

Validate YAML:

npx js-yaml .ad-sdlc/scratchpad/documents/output.yaml

Fix syntax errors or restore from backup
Resume:
```
ad-sdlc resume
```

Error: Permission Denied

Symptom:

Error: EACCES: permission denied

Solutions:

Check file permissions
Don't run as root

For global npm:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Error: Git Authentication Failed

Symptom:

Error: Authentication failed for repository

Solutions:

Check GitHub CLI authentication:
```
gh auth status
```
Re-authenticate:
```
gh auth login
```
Check SSH keys if using SSH URLs

Pipeline Stuck - No Progress

Symptom: Pipeline shows no progress for extended time.

Diagnostic Steps:

Check status:
```
ad-sdlc status
```
Check logs for errors:
```
tail -f .ad-sdlc/logs/pipeline.log
```

Check API connectivity:

curl https://api.anthropic.com/v1/messages

Solutions:

Resume if checkpoint available: ad-sdlc resume
Reset specific stage: ad-sdlc reset --stage <stage-name>
Full reset: ad-sdlc reset --all

Advanced Topics

Can I use AD-SDLC in CI/CD?

Yes. Example GitHub Actions workflow:

name: AD-SDLC Implementation
on:
  issues:
    types: [labeled]

jobs:
  implement:
    if: github.event.label.name == 'auto-implement'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install AD-SDLC
        run: npm install -g ad-sdlc
      - name: Run Implementation
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          ad-sdlc implement --issue ${{ github.event.issue.number }}

How do I extend with custom tools?

Use MCP (Model Context Protocol) to add custom tools:

Create MCP server:

// tools/my-tool.js
module.exports = {
  name: 'my-tool',
  description: 'Custom tool description',
  execute: async (params) => {
    // Implementation
    return result;
  }
};

Register in configuration:

mcp:
  servers:
    my-tools:
      command: node
      args: [tools/server.js]

How do I integrate with my existing workflow?

AD-SDLC is flexible:

Skip stages:
```
ad-sdlc run --skip-stages prd,srs
```
Use existing documents:
```
ad-sdlc run --prd docs/existing-prd.md
```

Output only:

ad-sdlc run --output-only  # Generate docs without implementation

Is there an API for programmatic access?

Yes. Use the SDK:

import { AdSdlc } from 'ad-sdlc';

const pipeline = new AdSdlc({
  apiKey: process.env.ANTHROPIC_API_KEY,
  github: { repo: 'owner/repo' }
});

// Run pipeline
const result = await pipeline.run({
  requirements: 'Implement user authentication'
});

console.log(result.documents.prd);
console.log(result.issues);

Enterprise & Security

Is my data sent to external servers?

Your data is processed through:

Claude API (Anthropic) - For AI reasoning
GitHub API - For issue/PR management (if enabled)

Data NOT sent externally:

Source code (unless explicitly included in prompts)
Environment variables
Credentials

Can I use AD-SDLC offline?

No. AD-SDLC requires:

Internet connection for Claude API
GitHub API access (optional but recommended)

For air-gapped environments, contact for enterprise deployment options.

How do I use AD-SDLC with SSO/SAML?

For enterprise SSO:

# .ad-sdlc/config/workflow.yaml
authentication:
  type: "sso"
  provider: "okta"  # or azure-ad, google, etc.
  client_id: "${SSO_CLIENT_ID}"

Is there an audit log?

Yes. All operations are logged:

# View audit log
cat .ad-sdlc/logs/audit.log

# Export audit log
ad-sdlc export-audit --format json --output audit-export.json

Audit log includes:

Timestamp
User/Agent
Action type
Input/Output hashes
API calls made

How do I prevent secrets from being committed?

AD-SDLC includes safeguards:

Automatic detection:
- Scans for API keys, passwords, tokens
- Warns before committing .env files

Configuration:

# .ad-sdlc/config/workflow.yaml
security:
  secret_detection: true
  block_secrets_in_pr: true
  allowed_secret_patterns: []  # Exceptions

Pre-commit hooks:
```
ad-sdlc setup-hooks
```

Can I run AD-SDLC in a Docker container?

Yes:

# Using official image
docker run -it \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  ad-sdlc/ad-sdlc:latest \
  "Implement user authentication"

How do I integrate with my CI/CD pipeline?

GitHub Actions:

- uses: ad-sdlc/action@v1
  with:
    api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    command: "implement"
    issue: ${{ github.event.issue.number }}

GitLab CI:

implement:
  image: ad-sdlc/ad-sdlc:latest
  script:
    - ad-sdlc implement --issue $CI_ISSUE_ID

What compliance certifications does AD-SDLC support?

AD-SDLC can be configured to support:

SOC 2 Type II
GDPR
HIPAA (with enterprise configuration)
ISO 27001

See enterprise documentation for compliance setup.

How do I rotate API keys?

# Update environment
export ANTHROPIC_API_KEY="sk-ant-new-key..."

# Or update .env
echo "ANTHROPIC_API_KEY=sk-ant-new-key..." > .env

# Verify new key works
ad-sdlc verify-auth

Getting More Help

If your question isn't answered here:

Check documentation:
Search issues: GitHub Issues
Open new issue: New Issue
Community: Join discussions in the repository.

Part of AD-SDLC Documentation

FilesExpand file tree

faq.md

Latest commit

History

faq.md

File metadata and controls

Frequently Asked Questions (FAQ)

Table of Contents

General Questions

What is AD-SDLC?

How long does a typical project take?

What languages/frameworks are supported?

Do I need a GitHub account?

How much does it cost?

Setup & Configuration

How do I set my API key?

Can I use a different model?

How do I configure GitHub integration?

Can I use this in a corporate environment?

Usage & Workflow

Can I intervene in the process?

What if something goes wrong?

Can I customize the agents?

How do I customize document templates?

Can agents work in parallel?

Documents & Output

What documents are generated?

Can I customize document templates?

How do I export documents to other formats?

Can I use existing documents instead of generating new ones?

Where are the generated files saved?

Agents & Customization

What agents are available?

How do I create a custom agent?

Can agents use external tools?

How do I change which model an agent uses?

Can I disable specific agents?

Troubleshooting

Error: API Rate Limit Exceeded

Error: Agent Timeout

Error: Invalid Configuration

Error: Scratchpad Corruption

Error: Permission Denied

Error: Git Authentication Failed

Pipeline Stuck - No Progress

Advanced Topics

Can I use AD-SDLC in CI/CD?

How do I extend with custom tools?

How do I integrate with my existing workflow?

Is there an API for programmatic access?

Enterprise & Security

Is my data sent to external servers?

Can I use AD-SDLC offline?

How do I use AD-SDLC with SSO/SAML?

Is there an audit log?

How do I prevent secrets from being committed?

Can I run AD-SDLC in a Docker container?

How do I integrate with my CI/CD pipeline?

What compliance certifications does AD-SDLC support?

How do I rotate API keys?

Getting More Help