icdev 1.0.0__py3-none-any.whl

icdev/data/docs/dx/README.md

@@ -0,0 +1,106 @@
+# ICDEV Developer Experience (DX)
+
+ICDEV is a meta-builder that autonomously builds Gov/DoD applications with full SDLC compliance. Under the hood it has 15 agents, 14 MCP servers, 146 database tables, and dozens of Python tools. **You don't need to know any of that.**
+
+This guide explains how to integrate ICDEV into your workflow so it works invisibly, letting you focus on building software while ICDEV handles compliance, security, testing, and deployment.
+
+---
+
+## How Developers Interact with ICDEV
+
+ICDEV offers three integration tiers. Pick the one that matches your team's workflow — or combine them.
+
+| Tier | Interaction Model | Developer Effort | Best For |
+|------|-------------------|------------------|----------|
+| **[Tier 1: Invisible](integration-tiers.md#tier-1-invisible)** | Git-native pipeline | Zero (push code, ICDEV runs automatically) | Teams that want compliance-as-infrastructure |
+| **[Tier 2: Conversational](integration-tiers.md#tier-2-conversational)** | Claude Code + 9 AI tools | Minimal (talk to your AI tool, it orchestrates) | Day-to-day development, feature building |
+| **[Tier 3: Programmatic](integration-tiers.md#tier-3-programmatic)** | REST API / MCP / SDK | Explicit (call APIs directly) | Custom tooling, CI scripts, integrations |
+
+Most teams use **Tier 1 + Tier 2**: the pipeline runs automatically, and developers talk to their AI coding tool when they need to build something new. ICDEV supports 10 AI coding tools out of the box — see the [AI Companion Guide](companion-guide.md).
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Quickstart](quickstart.md) | Get running in 5 minutes |
+| [Integration Tiers](integration-tiers.md) | Detailed guide to all three abstraction layers |
+| [icdev.yaml Specification](icdev-yaml-spec.md) | Project manifest reference — one file configures everything |
+| [Claude Code Guide](claude-code-guide.md) | Using natural language to drive ICDEV workflows |
+| [CI/CD Integration](ci-cd-integration.md) | Pipeline auto-attach for GitHub Actions and GitLab CI |
+| [Dev Profiles](dev-profiles.md) | Tenant coding standards, style enforcement, and personalization |
+| [AI Companion Guide](companion-guide.md) | Multi-tool setup — Claude Code, Codex, Gemini, Copilot, Cursor, and 5 more |
+| [LLM Routing Guide](llm-routing-guide.md) | Per-task LLM provider selection — assign Claude, GPT, Gemini, or local models to specific functions |
+| [SDK Reference](sdk-reference.md) | Programmatic API for custom tooling |
+| [Unified MCP Setup](unified-mcp-setup.md) | Single MCP server setup for VS Code, Cursor, Codex, Gemini, JetBrains, and 5 more IDEs |
+
+---
+
+## The Core Principle
+
+> **Developers write code. ICDEV handles everything else.**
+
+Compliance artifacts (SSP, POAM, STIG, SBOM), security scanning (SAST, secrets, dependencies, containers), testing (unit, BDD, E2E), CUI markings, ATO boundary management, deployment pipelines — all of it is automated. The developer's job is to describe what they want to build and write the application logic. ICDEV does the rest.
+
+---
+
+## Quick Comparison: Before and After ICDEV
+
+### Before (Manual Compliance)
+
+```
+1. Write code
+2. Manually run bandit, pip-audit, detect-secrets
+3. Write STIG checklist by hand (200+ controls)
+4. Generate SSP document (50+ pages)
+5. Create POAM for findings
+6. Generate SBOM manually
+7. Apply CUI markings to every file
+8. Submit for ATO review
+9. Fix findings, repeat steps 2-8
+10. Wait 6-18 months for ATO
+```
+
+### After (ICDEV)
+
+```
+1. Drop icdev.yaml in your repo
+2. Write code and push
+3. ICDEV auto-generates everything on every push
+4. ATO artifacts stay current continuously (cATO)
+```
+
+---
+
+## Architecture at a Glance
+
+```
+Developer
+    |
+    |-- pushes code
+    |-- talks to Claude Code
+    |-- (optional) calls REST API
+    |
+    v
++---------------------------+
+|       icdev.yaml          |  <-- One config file
++---------------------------+
+    |
+    v
++---------------------------+
+|    ICDEV Orchestration     |  <-- You never see this
+|  (GOTCHA Framework)       |
+|                           |
+|  Goals -> Tools -> Args   |
+|  Context -> Hard Prompts  |
++---------------------------+
+    |
+    +-- Compliance artifacts (SSP, POAM, STIG, SBOM)
+    +-- Security scan results (SAST, deps, secrets)
+    +-- Test suites (pytest, behave, Playwright)
+    +-- CUI/classification markings
+    +-- Deployment manifests (Terraform, K8s, Helm)
+    +-- Dev profile enforcement (coding standards)
+    +-- ATO boundary tracking
+```

icdev/data/docs/dx/__init__.py

@@ -0,0 +1 @@
+# Package marker for PyPI distribution

icdev/data/docs/dx/ci-cd-integration.md

@@ -0,0 +1,378 @@
+# CI/CD Integration
+
+ICDEV integrates with both GitHub Actions and GitLab CI/CD. The pipeline auto-attaches based on your `icdev.yaml` configuration and runs compliance, security, and testing checks on every push.
+
+---
+
+## How It Works
+
+```
+Developer pushes code
+        |
+        v
+  Platform auto-detected (GitHub / GitLab)
+        |
+        v
+  icdev.yaml loaded → pipeline stages determined
+        |
+        v
+  +-- PR Checks (on_pr) ──────────────────+
+  |  SAST, deps, secrets, CUI, STIG,      |
+  |  unit tests, BDD, lint, format         |
+  +────────────────────────────────────────+
+        |
+        v (on merge)
+  +-- Merge Actions (on_merge) ────────────+
+  |  SSP regen, POAM update, SBOM,         |
+  |  staging deploy, cATO refresh          |
+  +────────────────────────────────────────+
+        |
+        v (scheduled)
+  +-- Periodic Checks (on_schedule) ───────+
+  |  CVE triage, ISA expiry, dependency    |
+  |  freshness, cATO evidence              |
+  +────────────────────────────────────────+
+```
+
+---
+
+## GitHub Actions
+
+### Quick Setup
+
+Add this workflow file to your repository:
+
+```yaml
+# .github/workflows/icdev.yml
+name: ICDEV Compliance Pipeline
+
+on:
+  pull_request:
+    branches: [main, master]
+  push:
+    branches: [main, master]
+  schedule:
+    - cron: '0 6 * * *'  # Daily at 6 AM UTC
+
+jobs:
+  icdev-pr-checks:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install ICDEV dependencies
+        run: pip install -r requirements.txt
+
+      - name: Initialize ICDEV database
+        run: python tools/db/init_icdev_db.py
+
+      - name: SAST Scan
+        run: python tools/security/sast_runner.py --project-dir . --json > .tmp/sast.json
+
+      - name: Dependency Audit
+        run: python tools/security/dependency_auditor.py --project-dir . --json > .tmp/deps.json
+
+      - name: Secret Detection
+        run: python tools/security/secret_detector.py --project-dir . --json > .tmp/secrets.json
+
+      - name: CUI Marking Validation
+        run: python tools/compliance/cui_marker.py --validate --project-dir . --json > .tmp/cui.json
+
+      - name: STIG Compliance Check
+        run: python tools/compliance/stig_checker.py --project-id "${{ github.repository }}" --json > .tmp/stig.json
+
+      - name: Unit Tests
+        run: pytest tests/ -v --tb=short --junitxml=.tmp/test-results.xml
+
+      - name: BDD Tests
+        run: behave features/ --format json -o .tmp/bdd-results.json || true
+
+      - name: Gate Evaluation
+        run: |
+          python -c "
+          import json, sys
+          stig = json.load(open('.tmp/stig.json'))
+          cat1 = stig.get('summary', {}).get('cat1_count', 0)
+          if cat1 > 0:
+              print(f'BLOCKED: {cat1} CAT1 STIG findings')
+              sys.exit(1)
+          print('All gates passed')
+          "
+
+  icdev-merge-artifacts:
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install ICDEV dependencies
+        run: pip install -r requirements.txt
+
+      - name: Initialize ICDEV
+        run: python tools/db/init_icdev_db.py
+
+      - name: Generate SSP
+        run: python tools/compliance/ssp_generator.py --project-id "${{ github.repository }}" --json
+
+      - name: Generate SBOM
+        run: python tools/compliance/sbom_generator.py --project-dir . --json
+
+      - name: Upload Compliance Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: compliance-artifacts
+          path: artifacts/
+
+  icdev-scheduled:
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install ICDEV dependencies
+        run: pip install -r requirements.txt
+
+      - name: CVE Triage
+        run: python tools/supply_chain/cve_triager.py --project-id "${{ github.repository }}" --sla-check --json
+
+      - name: Dependency Freshness
+        run: python tools/maintenance/dependency_scanner.py --project-id "${{ github.repository }}" --json
+```
+
+### Webhook Integration (Advanced)
+
+For real-time issue-driven workflows, configure the ICDEV webhook server:
+
+1. Deploy the webhook server:
+   ```bash
+   python tools/ci/triggers/webhook_server.py
+   ```
+
+2. Configure GitHub webhook:
+   - URL: `https://your-icdev-instance/gh-webhook`
+   - Events: Issues, Pull Requests, Issue Comments
+   - Content type: `application/json`
+
+3. Use workflow commands in issue bodies:
+   ```
+   /icdev_sdlc           # Full lifecycle: Plan → Build → Test → Review
+   /icdev_plan           # Planning only
+   /icdev_build run_id:abc12345   # Build (requires prior plan)
+   ```
+
+---
+
+## GitLab CI/CD
+
+### Quick Setup
+
+Add this to your `.gitlab-ci.yml`:
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - security
+  - compliance
+  - test
+  - artifacts
+  - deploy
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+cache:
+  paths:
+    - .cache/pip/
+
+.icdev-setup: &icdev-setup
+  image: python:3.11-slim
+  before_script:
+    - pip install -r requirements.txt
+    - python tools/db/init_icdev_db.py
+
+# ── Security Stage ──────────────────────────────────────
+sast:
+  <<: *icdev-setup
+  stage: security
+  script:
+    - python tools/security/sast_runner.py --project-dir . --json > sast.json
+  artifacts:
+    reports:
+      sast: sast.json
+
+dependency_audit:
+  <<: *icdev-setup
+  stage: security
+  script:
+    - python tools/security/dependency_auditor.py --project-dir . --json > deps.json
+
+secret_detection:
+  <<: *icdev-setup
+  stage: security
+  script:
+    - python tools/security/secret_detector.py --project-dir . --json > secrets.json
+
+# ── Compliance Stage ────────────────────────────────────
+stig_check:
+  <<: *icdev-setup
+  stage: compliance
+  script:
+    - python tools/compliance/stig_checker.py --project-id "$CI_PROJECT_ID" --json > stig.json
+    - |
+      python -c "
+      import json, sys
+      stig = json.load(open('stig.json'))
+      cat1 = stig.get('summary', {}).get('cat1_count', 0)
+      if cat1 > 0:
+          print(f'BLOCKED: {cat1} CAT1 STIG findings')
+          sys.exit(1)
+      "
+
+cui_check:
+  <<: *icdev-setup
+  stage: compliance
+  script:
+    - python tools/compliance/cui_marker.py --validate --project-dir . --json
+
+# ── Test Stage ──────────────────────────────────────────
+unit_tests:
+  <<: *icdev-setup
+  stage: test
+  script:
+    - pytest tests/ -v --tb=short --cov --cov-report=xml
+  coverage: '/TOTAL.*\s+(\d+%)/'
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+
+bdd_tests:
+  <<: *icdev-setup
+  stage: test
+  script:
+    - behave features/ --format json -o bdd-results.json
+  allow_failure: true
+
+# ── Artifact Generation (main branch only) ──────────────
+generate_ssp:
+  <<: *icdev-setup
+  stage: artifacts
+  script:
+    - python tools/compliance/ssp_generator.py --project-id "$CI_PROJECT_ID" --json
+  only:
+    - main
+    - master
+
+generate_sbom:
+  <<: *icdev-setup
+  stage: artifacts
+  script:
+    - python tools/compliance/sbom_generator.py --project-dir . --json
+  only:
+    - main
+    - master
+  artifacts:
+    paths:
+      - artifacts/
+
+# ── Deploy (main branch only) ──────────────────────────
+deploy_staging:
+  <<: *icdev-setup
+  stage: deploy
+  script:
+    - python tools/infra/pipeline_generator.py --project-id "$CI_PROJECT_ID" --json
+  only:
+    - main
+    - master
+  when: manual
+```
+
+### GitLab Task Board Integration
+
+ICDEV can monitor GitLab issues for workflow commands:
+
+```bash
+# Start the GitLab task monitor (polls every 20s)
+python tools/ci/triggers/gitlab_task_monitor.py
+
+# Tag issues with workflow commands:
+# Add tag: {{icdev: icdev_sdlc}} → triggers full SDLC pipeline
+# Add tag: {{icdev: icdev_plan}} → triggers planning only
+```
+
+---
+
+## Pipeline Customization via icdev.yaml
+
+The `pipeline` section of `icdev.yaml` controls which checks run and when:
+
+```yaml
+pipeline:
+  # Only run these checks on PRs (remove any you don't need)
+  on_pr:
+    - sast
+    - dependency_audit
+    - secret_detection
+    - cui_check
+    - stig_check
+    - unit_tests
+    # - bdd_tests        # Commented out = disabled
+    # - lint
+    # - format_check
+
+  # Only run these on merge to main
+  on_merge:
+    - ssp_generate
+    - sbom_generate
+    # - deploy_staging    # Manual deploy instead
+
+  # Override gate thresholds
+  gates:
+    stig_max_cat1: 0      # Always block on CAT1
+    stig_max_cat2: 3      # Allow up to 3 CAT2 in dev (tighten for prod)
+    min_coverage: 80
+    max_critical_vulns: 0
+```
+
+---
+
+## Platform Auto-Detection
+
+ICDEV auto-detects whether you're using GitHub or GitLab by inspecting `git remote get-url origin`:
+
+| Remote URL Pattern | Detected Platform |
+|-------------------|-------------------|
+| `github.com/...` | GitHub |
+| `gitlab.com/...` or `gitlab.*.mil/...` | GitLab |
+
+Override with:
+```yaml
+pipeline:
+  platform: gitlab  # Force GitLab even if remote is GitHub
+```
+
+---
+
+## Security Considerations
+
+- **Secrets**: Never store ICDEV API keys in pipeline YAML. Use GitHub Secrets or GitLab CI/CD Variables.
+- **CUI markings**: The pipeline validates CUI markings are present but doesn't generate them. CUI generation happens at code-write time.
+- **Air-gapped environments**: For IL5/IL6, use GitLab CI runners within the classified network. ICDEV tools work offline (all stdlib dependencies).
+- **Audit trail**: All pipeline actions are logged to the ICDEV audit trail (append-only, NIST AU compliant).

icdev/data/docs/dx/claude-code-guide.md

@@ -0,0 +1,213 @@
+# Claude Code Guide
+
+Claude Code is the primary interface for developers working with ICDEV. You talk in natural language, and Claude orchestrates the right tools, applies your dev profile, and handles compliance automatically.
+
+---
+
+## Setup
+
+1. Install Claude Code:
+   ```bash
+   npm install -g @anthropic-ai/claude-code
+   ```
+
+2. Open your project (must have `icdev.yaml` or be an initialized ICDEV project):
+   ```bash
+   cd my-project
+   claude
+   ```
+
+3. Claude automatically reads:
+   - `icdev.yaml` — project configuration
+   - `CLAUDE.md` — orchestration instructions (ICDEV provides this)
+   - Dev profile — your tenant/project coding standards (via cascade resolution)
+   - Memory — previous session context
+
+---
+
+## Conversation Patterns
+
+### Building Features
+
+Talk about what you want to build. Claude follows the ATLAS workflow (Architect, Trace, Link, Assemble, Stress-test) automatically.
+
+> Build a REST API endpoint for user profile management. It should support GET, PUT, and DELETE with role-based access control.
+
+Claude will:
+1. Write failing tests first (TDD RED)
+2. Generate implementation (GREEN)
+3. Refactor for quality (REFACTOR)
+4. Apply your dev profile's coding standards (line length, naming conventions, imports)
+5. Add CUI markings if required
+6. Map to relevant NIST 800-53 controls
+7. Run security scans
+
+### Compliance Queries
+
+Ask about compliance status in plain English:
+
+> What's our FedRAMP status?
+> Which STIG controls are failing?
+> Show me our open POAM items.
+> Are we ready for our ATO review?
+
+### Fixing Issues
+
+Point Claude at a problem and it fixes it:
+
+> Fix the CAT1 STIG finding in the auth module.
+> The dependency audit found a critical vuln in requests 2.28. Upgrade it.
+> Our CUI markings are missing from the new files. Add them.
+
+### Requirements Intake
+
+Start a structured conversation with stakeholders:
+
+> We need a mission planning tool for special operations. Start the intake.
+
+Claude guides a multi-turn conversation extracting requirements, detecting gaps, and scoring readiness. When ready, it decomposes into SAFe hierarchy (Epic > Feature > Story) with BDD acceptance criteria.
+
+### Deployment
+
+> Deploy the staging build to GovCloud.
+> Generate Terraform for our database infrastructure.
+> Create the K8s manifests for production.
+
+### Security
+
+> Run a full security scan.
+> Check for hardcoded secrets in the codebase.
+> Generate our SBOM.
+
+---
+
+## Slash Commands Reference
+
+Slash commands are shortcuts for common workflows. They're optional — you can always use natural language instead.
+
+### Build & Test
+| Command | Purpose |
+|---------|---------|
+| `/icdev-build` | Build using TDD (RED-GREEN-REFACTOR) |
+| `/icdev-test` | Run full test suite (unit + BDD + coverage) |
+
+### Compliance & Security
+| Command | Purpose |
+|---------|---------|
+| `/icdev-comply` | Generate ATO artifacts (SSP, POAM, STIG, SBOM) |
+| `/icdev-secure` | Full security scan (SAST, deps, secrets, containers) |
+| `/icdev-devsecops` | DevSecOps maturity assessment and pipeline security |
+| `/icdev-zta` | Zero Trust Architecture scoring and configuration |
+| `/icdev-mosa` | DoD MOSA modularity analysis and ICD generation |
+
+### Project Management
+| Command | Purpose |
+|---------|---------|
+| `/icdev-init` | Initialize new project with compliance scaffolding |
+| `/icdev-status` | Project status dashboard |
+| `/icdev-intake` | AI-driven requirements intake session |
+| `/icdev-simulate` | Digital Program Twin simulation and COA generation |
+
+### Infrastructure
+| Command | Purpose |
+|---------|---------|
+| `/icdev-deploy` | Generate IaC and deployment pipeline |
+| `/icdev-review` | Enforce code review gates |
+| `/icdev-maintain` | Dependency audit, CVE check, remediation |
+
+### Knowledge & Integration
+| Command | Purpose |
+|---------|---------|
+| `/icdev-knowledge` | Query/update learning knowledge base |
+| `/icdev-integrate` | Sync with Jira, ServiceNow, GitLab, DOORS NG |
+| `/icdev-mbse` | MBSE integration (SysML, digital thread) |
+| `/icdev-monitor` | Production monitoring and self-healing |
+| `/icdev-market` | GOTCHA asset marketplace |
+| `/icdev-agentic` | Generate agentic child application |
+| `/icdev-boundary` | ATO boundary impact and supply chain risk |
+
+### Language-Specific Build Plans
+| Command | Language |
+|---------|----------|
+| `/plan_python` | Python (Flask/FastAPI, pytest, bandit) |
+| `/plan_java` | Java (Spring Boot, Cucumber, SpotBugs) |
+| `/plan_go` | Go (Gin, godog, gosec) |
+| `/plan_rust` | Rust (Actix-web, clippy, cargo-audit) |
+| `/plan_csharp` | C# (ASP.NET, SpecFlow, SecurityCodeScan) |
+| `/plan_typescript` | TypeScript (Express, cucumber-js, eslint) |
+
+---
+
+## How Dev Profiles Affect Claude's Output
+
+When your project has a dev profile (either from a template or custom), Claude automatically applies those standards to all generated code. You don't need to tell Claude about your coding standards — it already knows.
+
+**Example: Without dev profile**
+Claude generates Python with its own defaults (4 spaces, 88-char lines, black formatting).
+
+**Example: With DoD baseline profile**
+Claude generates Python matching the profile: 4 spaces, 100-char lines, snake_case, type hints required, Google-style docstrings, FIPS 140-2 compliant crypto, CUI markings.
+
+The dev profile is injected into Claude's context per task type:
+- **Code generation**: language, style, testing, security dimensions
+- **Code review**: testing, security, compliance, documentation dimensions
+- **Architecture**: architecture, operations, security dimensions
+- **Documentation**: documentation, compliance dimensions
+
+See [Dev Profiles](dev-profiles.md) for full details.
+
+---
+
+## Tips for Effective Conversations
+
+### Be Specific About Scope
+> **Good**: "Build a JWT authentication middleware for the Flask API"
+> **Vague**: "Add auth"
+
+### Reference Impact Level When Relevant
+> "We need to handle PII at IL5 — generate the appropriate data classification markings"
+
+### Let Claude Handle the Workflow
+Don't tell Claude which tools to use. Describe the outcome you want:
+> **Good**: "Make sure our code is secure and compliant before we merge"
+> **Unnecessary**: "Run bandit, then pip-audit, then detect-secrets, then stig-checker"
+
+### Use Follow-up Questions
+Claude maintains context across turns:
+> "Build the auth module"
+> *(Claude builds it)*
+> "Now add rate limiting to it"
+> *(Claude adds rate limiting to the same module)*
+> "What NIST controls does this satisfy?"
+> *(Claude shows control mappings)*
+
+### Ask About Trade-offs
+> "Should we use JWT or session-based auth for this IL5 system? What are the compliance implications?"
+
+Claude considers your project's impact level, compliance frameworks, and dev profile when advising.
+
+---
+
+## Troubleshooting
+
+### Claude doesn't know about my project's settings
+Make sure `icdev.yaml` exists in your project root and the ICDEV database has been initialized:
+```bash
+python tools/db/init_icdev_db.py
+```
+
+### Claude generates code that doesn't match our standards
+Check that your dev profile is loaded:
+> Show me the resolved dev profile for this project
+
+If no profile exists, create one:
+> Create a dev profile for this project using the DoD baseline template
+
+### Claude can't find the right tool
+ICDEV tools are registered as MCP servers. Verify they're configured in `.mcp.json`:
+```bash
+cat .mcp.json
+```
+
+### Claude gives generic answers instead of ICDEV-specific ones
+Make sure you're in an ICDEV project directory with `CLAUDE.md` present. The `CLAUDE.md` file contains all orchestration instructions.