PRD: AI-SDLC Native Claude Code Integration

query({
  prompt: "Fix the bug described in issue #42",
  options: {
    model: "claude-sonnet-4-6",
    maxTurns: 50,
    maxBudgetUsd: 2.00,
    systemPrompt: undefined,        // keep defaults
    appendSystemPrompt: governanceRules,  // inject governance
    allowedTools: ["Bash(git:*)", "Read", "Edit", "Grep", "Glob"],
    disallowedTools: ["WebFetch", "WebSearch"],
    permissionMode: "acceptEdits",
    mcpConfig: ["/path/to/ai-sdlc-mcp.json"],
  }
})

┌─────────────────────────────────────────────────────────────┐
│                    AI-SDLC Plugin                            │
│  (installed via claude plugin install ai-sdlc)              │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  Hooks   │  │ Commands │  │  Skills  │  │   Agents   │  │
│  │          │  │          │  │          │  │            │  │
│  │ PreTool  │  │ /review  │  │ govern-  │  │ code-      │  │
│  │ PostTool │  │ /triage  │  │ ance     │  │ reviewer   │  │
│  │ Session  │  │ /detect  │  │ review   │  │ security-  │  │
│  │ Stop     │  │ /fix-pr  │  │ develop  │  │ reviewer   │  │
│  │ Perm.Req │  │ /admit   │  │          │  │ test-      │  │
│  └──────────┘  └──────────┘  └──────────┘  │ reviewer   │  │
│                                             └────────────┘  │
│  ┌──────────────┐  ┌─────────────────┐                      │
│  │  MCP Server  │  │  User Config    │                      │
│  │              │  │                 │                      │
│  │ check-pr     │  │ github_token    │                      │
│  │ check-issue  │  │ slack_token     │                      │
│  │ get-context  │  │ anthropic_key   │                      │
│  │ list-patterns│  │ project_root    │                      │
│  └──────────────┘  └─────────────────┘                      │
└─────────────────────────────────────────────────────────────┘
         │                                     │
         ▼                                     ▼
┌─────────────┐                     ┌──────────────────┐
│ Orchestrator│                     │ Telemetry        │
│ SDK Runner  │                     │ Pipeline         │
│             │                     │                  │
│ Uses SDK    │                     │ PostToolUse →    │
│ query() for │                     │ JSONL → n-gram   │
│ fine-grained│                     │ mining →         │
│ agent ctrl  │                     │ proposals        │
└─────────────┘                     └──────────────────┘

{
  "name": "ai-sdlc",
  "version": "0.7.0",
  "description": "AI-SDLC governance framework for Claude Code",
  "author": { "name": "AI-SDLC Framework", "url": "https://ai-sdlc.io" },
  "homepage": "https://ai-sdlc.io",
  "repository": "https://github.com/ai-sdlc-framework/ai-sdlc",
  "license": "Apache-2.0",
  "keywords": ["governance", "sdlc", "security", "quality-gates"],

  "hooks": "./hooks/hooks.json",
  "commands": "./commands/",
  "skills": "./skills/",
  "agents": "./agents/",
  "mcpServers": {
    "ai-sdlc": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/index.js"],
      "env": {
        "GITHUB_TOKEN": "${user_config.github_token}",
        "AI_SDLC_PROJECT_ROOT": "${CLAUDE_PLUGIN_DATA}"
      }
    }
  },
  "userConfig": {
    "github_token": {
      "type": "string",
      "title": "GitHub Token",
      "description": "Personal access token for GitHub API (label management, PR operations)",
      "required": false,
      "sensitive": true
    },
    "slack_webhook": {
      "type": "string",
      "title": "Slack Webhook URL",
      "description": "Webhook for pipeline visibility notifications",
      "required": false
    }
  }
}

{
  "SessionStart": [{
    "hooks": [{
      "type": "command",
      "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js",
      "statusMessage": "Loading AI-SDLC governance..."
    }]
  }],

  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/enforce-blocked-actions.js",
      "if": "Bash(*)",
      "statusMessage": "Checking action policy..."
    }]
  }],

  "PostToolUse": [{
    "hooks": [{
      "type": "command",
      "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/collect-telemetry.js",
      "async": true
    }]
  }],

  "Stop": [{
    "hooks": [{
      "type": "agent",
      "prompt": "You are a governance verification agent. Read the session transcript at $ARGUMENTS and verify: 1) No blocked actions were executed. 2) If code was modified, tests exist. 3) No secrets were committed. Return ok:true if all checks pass, ok:false with specific violations if not.",
      "model": "claude-haiku-4-5-20251001",
      "timeout": 30,
      "statusMessage": "Verifying governance compliance..."
    }]
  }],

  "PermissionRequest": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/permission-check.js",
      "if": "Bash(gh pr merge*)"
    }]
  }]
}

---
name: ai-sdlc:code-reviewer
description: Reviews code for bugs, logic errors, security vulnerabilities
tools: [Read, Grep, Glob, Bash]
disallowedTools: [Edit, Write, AgentTool]
model: sonnet
---
Review the code changes for this PR. Focus on...

---
name: ai-sdlc:security-reviewer
description: Reviews code for security vulnerabilities and OWASP top 10
tools: [Read, Grep, Glob]
disallowedTools: [Bash, Edit, Write, AgentTool]
model: sonnet
---
Analyze the code changes for security issues...

---
name: ai-sdlc:test-reviewer
description: Reviews test coverage and test quality
tools: [Read, Grep, Glob, Bash]
disallowedTools: [Edit, Write, AgentTool]
model: sonnet
---
Analyze test coverage for the changed files...

import { query } from '@anthropic-ai/claude-agent-sdk';

class ClaudeCodeSDKRunner implements AgentRunner {
  async execute(task: AgentTask, constraints: AgentConstraints): Promise<AgentResult> {
    const result = query({
      prompt: this.buildPrompt(task),
      options: {
        model: constraints.model ?? 'claude-sonnet-4-6',
        maxTurns: constraints.maxTurns ?? 100,
        maxBudgetUsd: constraints.maxBudgetUsd ?? 5.00,
        appendSystemPrompt: this.buildGovernancePrompt(constraints),
        allowedTools: this.buildToolAllowlist(constraints),
        disallowedTools: this.buildToolDenylist(constraints),
        permissionMode: 'acceptEdits',
        mcpConfig: [this.getMcpConfigPath()],
      }
    });

    for await (const message of result) {
      if (message.type === 'assistant') {
        this.onProgress?.(message);
      }
      if (message.type === 'result') {
        return this.parseResult(message);
      }
    }
  }
}

# agent-role.yaml
spec:
  tools:
    - code-editor    → allowedTools: ["Edit(/src/**)", "Write(/src/**)"]
    - terminal       → allowedTools: ["Bash(pnpm:*)", "Bash(git:*)"]
    - test-runner    → allowedTools: ["Bash(pnpm test*)", "Bash(pnpm build*)"]
    - file-search    → allowedTools: ["Read", "Grep", "Glob"]

# agent-role.yaml (new fields)
spec:
  constraints:
    maxBudgetUsd: 5.00    # → options.maxBudgetUsd
    maxTurns: 100          # → options.maxTurns
    maxFilesPerChange: 15  # → enforced via PostToolUse hook

{
  "Stop": [{
    "hooks": [{
      "type": "agent",
      "prompt": "You are an AI-SDLC governance verifier. The session transcript is at $ARGUMENTS. Read it and verify:\n1. If code was modified, `pnpm build` was run and passed\n2. If code was modified, `pnpm test` was run and passed\n3. If code was modified, `pnpm lint` was run and passed\n4. No files in blockedPaths (.github/workflows/**, .ai-sdlc/**) were modified\n5. No secrets or API keys appear in committed code\n\nReturn ok:true only if ALL checks pass. Return ok:false with specific violations.",
      "model": "claude-haiku-4-5-20251001",
      "timeout": 45,
      "statusMessage": "Running governance quality gates..."
    }]
  }]
}

{
  "Stop": [{
    "hooks": [{
      "type": "command",
      "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/deferred-coverage-check.js",
      "asyncRewake": true,
      "statusMessage": "Checking coverage..."
    }]
  }]
}

const reviews = await Promise.all([
  query({
    prompt: buildReviewPrompt('testing', diff, reviewPolicy),
    options: {
      model: 'claude-sonnet-4-6',
      maxTurns: 20,
      maxBudgetUsd: 0.50,
      allowedTools: ['Read', 'Grep', 'Glob', 'Bash(pnpm test*)'],
      disallowedTools: ['Edit', 'Write', 'AgentTool'],
      appendSystemPrompt: reviewPolicy,
    }
  }),
  query({
    prompt: buildReviewPrompt('security', diff, reviewPolicy),
    options: {
      model: 'claude-sonnet-4-6',
      maxTurns: 20,
      maxBudgetUsd: 0.50,
      allowedTools: ['Read', 'Grep', 'Glob'],
      disallowedTools: ['Bash', 'Edit', 'Write', 'AgentTool'],
      appendSystemPrompt: reviewPolicy,
    }
  }),
  query({
    prompt: buildReviewPrompt('quality', diff, reviewPolicy),
    options: {
      model: 'claude-sonnet-4-6',
      maxTurns: 20,
      maxBudgetUsd: 0.50,
      allowedTools: ['Read', 'Grep', 'Glob', 'Bash(pnpm lint*)'],
      disallowedTools: ['Edit', 'Write', 'AgentTool'],
      appendSystemPrompt: reviewPolicy,
    }
  }),
]);

ai-sdlc-plugin/
├── plugin.json                          # Plugin manifest
├── hooks/
│   ├── hooks.json                       # Hook configuration
│   ├── session-start.js                 # SessionStart: load governance context
│   ├── enforce-blocked-actions.js       # PreToolUse: block dangerous actions
│   ├── collect-telemetry.js             # PostToolUse: workflow pattern telemetry
│   ├── permission-check.js              # PermissionRequest: hard deny
│   └── deferred-coverage-check.js       # Stop (asyncRewake): coverage verification
├── commands/
│   ├── review.md                        # /ai-sdlc:review
│   ├── triage.md                        # /ai-sdlc:triage
│   ├── detect-patterns.md               # /ai-sdlc:detect-patterns
│   ├── fix-pr.md                        # /ai-sdlc:fix-pr
│   └── status.md                        # /ai-sdlc:status
├── skills/
│   ├── governance/SKILL.md              # Governance rules
│   ├── develop/SKILL.md                 # Implement-test-commit workflow
│   └── review/SKILL.md                  # Code review workflow
├── agents/
│   ├── code-reviewer.md                 # Read-only code reviewer
│   ├── security-reviewer.md             # Security-focused reviewer
│   └── test-reviewer.md                 # Test coverage reviewer
└── mcp-server/
    └── index.js                         # MCP server with governance tools

orchestrator/src/runners/claude-code-sdk.ts  # New SDK-based runner
orchestrator/src/runners/index.ts            # Export new runner