icdev 1.0.0__py3-none-any.whl

icdev/data/docs/dx/companion-guide.md

@@ -0,0 +1,232 @@
+# ICDEV AI Companion Guide
+
+ICDEV works with **10 AI coding tools** — not just Claude Code. One command generates instruction files, MCP configurations, and skill translations for every tool your team uses.
+
+---
+
+## Supported Tools
+
+| Tool | Instruction File | MCP Support | Skills |
+|------|-----------------|-------------|--------|
+| Claude Code | `CLAUDE.md` (manual) | `.mcp.json` | `.claude/skills/` |
+| OpenAI Codex | `AGENTS.md` | TOML config | `.agents/skills/` |
+| Google Gemini | `GEMINI.md` | JSON config | — |
+| GitHub Copilot | `.github/copilot-instructions.md` | — | `.github/prompts/` |
+| Cursor | `.cursor/rules/*.mdc` | IDE settings | `.cursor/rules/` |
+| Windsurf | `.windsurf/rules/*.md` | IDE settings | — |
+| Amazon Q | `.amazonq/rules/*.md` | JSON config | — |
+| JetBrains Junie | `.junie/guidelines.md` | IDE settings | — |
+| Cline | `.clinerules` | JSON config | — |
+| Aider | `CONVENTIONS.md` | — | — |
+
+---
+
+## Quick Start
+
+```bash
+# Auto-detect installed tools and generate everything
+python tools/dx/companion.py --setup --write
+
+# Generate for all 10 tools
+python tools/dx/companion.py --setup --all --write
+
+# Generate for specific tools only
+python tools/dx/companion.py --setup --platforms codex,cursor,gemini --write
+
+# Preview without writing files
+python tools/dx/companion.py --setup --all --dry-run --json
+
+# Detect which AI tools are installed
+python tools/dx/companion.py --detect --json
+
+# List all supported platforms
+python tools/dx/companion.py --list
+```
+
+---
+
+## What Gets Generated
+
+### 1. Instruction Files
+
+Each AI tool gets a project-aware instruction file in its native format:
+
+- **Project context**: name, type, language, impact level, classification
+- **MCP server awareness**: which servers are available and what they do
+- **Compliance rules**: CUI markings, security gates, STIG thresholds
+- **Workflow guidance**: how to use ICDEV tools via the AI coding tool
+- **Dev profile**: coding standards, testing requirements, style rules
+
+### 2. MCP Configurations
+
+Tools with MCP support get config files pointing to ICDEV's **unified MCP server** (`icdev-unified`) — a single server exposing all 225 tools. See the [Unified MCP Setup Guide](unified-mcp-setup.md) for IDE-specific instructions.
+
+| Tool | Config Format | Output Path |
+|------|--------------|-------------|
+| Codex | TOML | `.codex/mcp-config.toml` |
+| Amazon Q | JSON | `.amazonq/mcp.json` |
+| Gemini | JSON | `.gemini/mcp-settings.json` |
+| Cline | JSON | `.cline/mcp_settings.json` |
+| Cursor | Setup guide | `.cursor/mcp-setup.md` |
+| Windsurf | Setup guide | `.windsurf/mcp-setup.md` |
+| JetBrains | Setup guide | `.junie/mcp-setup.md` |
+
+### 3. Skill Translations
+
+Claude Code skills (`.claude/skills/`) are translated to equivalent formats:
+
+| Source | Target | Format |
+|--------|--------|--------|
+| `/skill-name` | `$skill-name` (Codex) | `.agents/skills/*/SKILL.md` |
+| `/skill-name` | `#prompt:skill-name` (Copilot) | `.github/prompts/*.prompt.md` |
+| `/skill-name` | Agent-requested rule (Cursor) | `.cursor/rules/*.mdc` |
+
+---
+
+## Multi-Vendor Coexistence
+
+All vendor instruction files and MCP configs coexist in the project root with zero conflict. Each AI tool reads **only its own** files and ignores everything else — the same way `.gitignore`, `.eslintrc`, and `.prettierrc` coexist today.
+
+### Project Root After Setup
+
+```
+ICDev/
+├── CLAUDE.md                          # Claude Code (source of truth)
+├── AGENTS.md                          # OpenAI Codex
+├── GEMINI.md                          # Google Gemini CLI
+├── CONVENTIONS.md                     # Aider
+├── .mcp.json                          # Claude Code MCP config
+├── .clinerules                        # Cline
+├── .claude/                           # Claude Code commands, hooks, settings
+│   ├── commands/
+│   ├── hooks/
+│   └── settings.json
+├── .codex/                            # Codex MCP config
+│   └── mcp-config.toml
+├── .gemini/                           # Gemini MCP config
+│   └── mcp-settings.json
+├── .amazonq/                          # Amazon Q rules + MCP config
+│   ├── rules/icdev.md
+│   └── mcp.json
+├── .github/                           # Copilot instructions + prompt skills
+│   ├── copilot-instructions.md
+│   └── prompts/
+├── .cursor/                           # Cursor rules + MCP setup guide
+│   └── rules/icdev.mdc
+├── .windsurf/                         # Windsurf rules + MCP setup guide
+│   └── rules/icdev.md
+├── .junie/                            # JetBrains Junie guidelines
+│   └── guidelines.md
+└── ...
+```
+
+### Why This Works
+
+- **No cross-tool interference** — Claude Code never reads `.cursor/`, Codex never reads `.claude/`, Gemini ignores both
+- **Single source of truth** — `CLAUDE.md` is maintained manually; all other files are generated from it
+- **Team flexibility** — Any developer can open the repo with their preferred tool and get full ICDEV context
+- **Git-friendly** — All files commit to the repo, so teammates get configs automatically on `git pull`
+
+### Keeping Files in Sync
+
+After modifying `CLAUDE.md`, `.mcp.json`, or `.claude/commands/`, regenerate all companion files:
+
+```bash
+# Resync all generated files from current CLAUDE.md
+python tools/dx/companion.py --sync --write
+
+# Preview what would change without writing
+python tools/dx/companion.py --sync --dry-run --json
+```
+
+The companion system reads the current state of `CLAUDE.md` and `.mcp.json` on every run — generated files always reflect the latest project configuration.
+
+---
+
+## icdev.yaml Companion Section
+
+Add a `companion:` section to your `icdev.yaml` to control which tools get generated:
+
+```yaml
+companion:
+  tools:
+    - codex
+    - cursor
+    - gemini
+    - copilot
+  auto_sync: false        # Regenerate on icdev.yaml changes
+  instruction_style: full  # full | minimal
+```
+
+If omitted, the companion system auto-detects installed tools.
+
+---
+
+## Individual Tools
+
+### Tool Detector
+
+```bash
+# Detect AI tools from env vars, config directories, and config files
+python tools/dx/tool_detector.py --json
+```
+
+### Instruction Generator
+
+```bash
+# Generate instruction files for specific platforms
+python tools/dx/instruction_generator.py --platform codex --write --json
+
+# Generate for all platforms
+python tools/dx/instruction_generator.py --all --write
+```
+
+### MCP Config Generator
+
+```bash
+# Generate MCP configs from .mcp.json
+python tools/dx/mcp_config_generator.py --all --write --json
+
+# Single platform
+python tools/dx/mcp_config_generator.py --platform amazon_q --write
+```
+
+### Skill Translator
+
+```bash
+# List available Claude Code skills
+python tools/dx/skill_translator.py --list
+
+# Translate to all supported platforms
+python tools/dx/skill_translator.py --all --write --json
+
+# Translate specific skills to specific platform
+python tools/dx/skill_translator.py --platform codex --skills icdev-build,icdev-test --write
+```
+
+---
+
+## Architecture
+
+The companion system follows ICDEV's existing patterns:
+
+- **D194**: Companion registry is declarative YAML — add new tools without code changes
+- **D195**: Instruction files generated from Jinja2 templates (D186 pattern)
+- **D196**: MCP is the primary integration protocol — 9/10 tools support it
+- **D197**: Tool detection is advisory — explicit `--platform` override available
+- **D198**: Skill translation preserves semantic intent, not literal copy
+
+```
+icdev.yaml (companion: section)
+    |
+    v
+args/companion_registry.yaml   <-- Add new tools here
+    |
+    +-- tools/dx/tool_detector.py          (detect installed tools)
+    +-- tools/dx/instruction_generator.py  (generate instruction files)
+    +-- tools/dx/mcp_config_generator.py   (generate MCP configs)
+    +-- tools/dx/skill_translator.py       (translate skills)
+    |
+    v
+tools/dx/companion.py   <-- Single CLI entry point
+```

icdev/data/docs/dx/dev-profiles.md

@@ -0,0 +1,309 @@
+# Dev Profiles & Personalization
+
+Dev profiles let each tenant organization define their coding standards, technology preferences, and compliance requirements once. These standards then automatically flow into every ICDEV operation — code generation, scaffolding, security scanning, and LLM prompt injection — without the developer needing to specify them each time.
+
+---
+
+## The Problem
+
+Without dev profiles, every tenant uses the same global defaults:
+- Python 3.11, 100-char lines, black formatting
+- `python:3.11-slim` base image
+- Generic test coverage thresholds
+- No organization-specific naming conventions
+
+A DoD tenant using Go with 120-char lines and trunk-based development gets the same output as a startup using Python with GitHub Flow. Dev profiles fix this.
+
+---
+
+## How It Works
+
+### 1. Create a Profile
+
+Either use a starter template or define custom standards:
+
+```bash
+# From a starter template
+python tools/builder/dev_profile_manager.py \
+  --scope tenant --scope-id "acme-corp" \
+  --create --template dod_baseline --json
+
+# Or custom
+python tools/builder/dev_profile_manager.py \
+  --scope tenant --scope-id "acme-corp" \
+  --create --data '{
+    "language": {"primary": "go", "secondary": ["python"], "min_version": "1.21"},
+    "style": {"line_length": 120, "indent_size": 4, "naming_convention": "snake_case"},
+    "testing": {"min_coverage": 90, "framework": "godog"}
+  }' --created-by "admin@acme.gov" --json
+```
+
+Or just tell Claude:
+
+> Create a dev profile for our tenant using the DoD baseline template. Override the primary language to Go and set line length to 120.
+
+### 2. ICDEV Auto-Applies It
+
+Once a profile exists, every ICDEV operation respects it automatically:
+
+| Operation | What the Profile Affects |
+|-----------|--------------------------|
+| **Code generation** | Language, naming conventions, import style, type hints, docstring format |
+| **Scaffolding** | Base image, Python version, line length, .gitignore entries, README sections |
+| **Security scanning** | Crypto requirements (FIPS 140-2), secret rotation period, vulnerability thresholds |
+| **Compliance** | Required frameworks, CUI markings, classification headers |
+| **LLM prompts** | Claude receives the relevant profile dimensions for each task type |
+| **Code review** | Review checks against profile standards (coverage, naming, style) |
+| **PROFILE.md** | Auto-generated narrative document of all active standards |
+
+### 3. Developers Don't Think About It
+
+The developer writes:
+
+> Build a REST API for user management
+
+Claude generates Go code (not Python) with 120-char lines, snake_case naming, trunk-based branching guidance, and FIPS 140-2 compliant crypto — because that's what the tenant profile says.
+
+---
+
+## 5-Layer Cascade
+
+Profiles are scoped hierarchically. Each layer can override or extend the layer above:
+
+```
+Platform (ICDEV defaults)
+    └── Tenant (organization standards)
+        └── Program (program-specific overrides)
+            └── Project (project-specific overrides)
+                └── User (personal preferences)
+```
+
+When resolving a profile for a project, ICDEV walks up the tree and merges each layer. The merge behavior depends on the dimension:
+
+| Behavior | Description | Example |
+|----------|-------------|---------|
+| `override` | Child replaces parent entirely | Language: Go replaces Python |
+| `merge` | Deep dict merge | Style: child adds `indent_size` to parent's `line_length` |
+| `union` | Combine lists, deduplicate | Secondary languages: parent [Python] + child [Rust] = [Python, Rust] |
+| `strictest_wins` | Keep the stricter value | Min coverage: parent 80% + child 90% = 90% |
+
+### Cascade Resolution
+
+```bash
+# See the effective profile for a project (all layers merged)
+python tools/builder/dev_profile_manager.py \
+  --scope project --scope-id "proj-123" --resolve --json
+```
+
+The output includes **provenance** — where each value came from:
+
+```json
+{
+  "language": {
+    "primary": {"value": "go", "source": "tenant", "locked": false},
+    "min_version": {"value": "1.21", "source": "project", "locked": false}
+  },
+  "security": {
+    "crypto_standard": {"value": "FIPS 140-2", "source": "tenant", "locked": true}
+  }
+}
+```
+
+---
+
+## Dimension Locks
+
+Certain standards should not be overridden at lower levels. An ISSO can lock security dimensions at the tenant level, preventing any project from weakening them.
+
+```bash
+# ISSO locks the security dimension at tenant scope
+python tools/builder/dev_profile_manager.py \
+  --scope tenant --scope-id "acme-corp" \
+  --lock --dimension-path "security" \
+  --lock-role isso --locked-by "isso@acme.gov" --json
+
+# Project tries to override crypto_standard → BLOCKED
+# The locked value from tenant scope is enforced
+```
+
+Lock governance by role:
+
+| Role | Can Lock | Can Unlock |
+|------|----------|------------|
+| ISSO | security, compliance | security, compliance |
+| Architect | architecture, language | architecture, language |
+| PM | operations, documentation, git | operations, documentation, git |
+| Admin | all dimensions | all dimensions |
+
+---
+
+## Version History
+
+Every profile change creates a new immutable version (ADR D183 — no UPDATE, only INSERT). This provides a full audit trail:
+
+```bash
+# View all versions
+python tools/builder/dev_profile_manager.py \
+  --scope tenant --scope-id "acme-corp" --history --json
+
+# Diff between versions
+python tools/builder/dev_profile_manager.py \
+  --scope tenant --scope-id "acme-corp" --diff --v1 1 --v2 3 --json
+
+# Rollback to a previous version (creates new version with old content)
+python tools/builder/dev_profile_manager.py \
+  --scope tenant --scope-id "acme-corp" \
+  --rollback --target-version 1 --rolled-back-by "admin" --json
+```
+
+---
+
+## Auto-Detection
+
+Point ICDEV at an existing codebase and it will detect coding standards automatically:
+
+```bash
+# Scan a repository
+python tools/builder/profile_detector.py --repo-path /path/to/repo --json
+```
+
+Detection scans:
+- **File extensions** → primary/secondary languages
+- **`.editorconfig`** → indent style, line length, charset
+- **`package.json` / `pyproject.toml`** → dependencies, tools
+- **Git log** → commit format, branch naming patterns
+- **CI/CD configs** → pipeline tools, deployment targets
+- **Python AST analysis** → naming conventions (snake_case vs camelCase)
+
+Detection is **advisory only** (ADR D185) — detected values must be explicitly accepted before they become part of the profile.
+
+---
+
+## PROFILE.md
+
+ICDEV generates a human-readable `PROFILE.md` document from the resolved profile. This is a narrative summary of all active standards, their provenance, and enforcement status.
+
+```bash
+python tools/builder/profile_md_generator.py \
+  --scope project --scope-id "proj-123" \
+  --output PROFILE.md --store --json
+```
+
+Example output:
+
+```markdown
+# PROFILE.md
+
+> Auto-generated from dev profile cascade resolution.
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| Scope | project |
+| Scope ID | proj-123 |
+| Layers | platform → tenant → project |
+
+## Language
+
+- **Primary Language**: Go (source: tenant)
+- **Secondary Languages**: Python (source: platform)
+- **Minimum Version**: 1.21 (source: project)
+
+## Style
+
+- **Line Length**: 120 (source: tenant) 🔒 LOCKED
+- **Indent Size**: 4 (source: platform)
+- **Naming Convention**: snake_case (source: tenant)
+...
+```
+
+PROFILE.md is **read-only** — edit the profile, not the document. Regenerate after changes.
+
+---
+
+## Starter Templates
+
+Six sector-specific templates provide opinionated defaults:
+
+| Template | Key | Sector | Key Standards |
+|----------|-----|--------|---------------|
+| DoD Baseline | `dod_baseline` | DoD/IC | Python/Go, FIPS 140-2, trunk-based, STIG, 100-char lines |
+| FedRAMP Baseline | `fedramp_baseline` | Federal Civilian | Python/Java, FedRAMP Moderate+, squash merge, 120-char lines |
+| Healthcare | `healthcare_baseline` | Healthcare | HIPAA+HITRUST, SOC 2, PHI markings, 90-day key rotation |
+| Financial | `financial_baseline` | Financial Services | PCI DSS v4, SOC 2 Type II, AES-256, 90-day rotation |
+| Law Enforcement | `law_enforcement` | Law Enforcement | CJIS+FIPS, air-gapped, Mattermost only, federal naming conventions |
+| Startup | `startup` | Commercial | Minimal compliance, GitHub Flow, fast iteration, 88-char lines |
+
+Templates are stored in `context/profiles/*.yaml` and can be customized per tenant.
+
+---
+
+## Integration with icdev.yaml
+
+Set the dev profile in your project manifest:
+
+```yaml
+# icdev.yaml
+profile:
+  template: dod_baseline
+  overrides:
+    style:
+      line_length: 120
+    testing:
+      min_coverage: 90
+```
+
+ICDEV loads this on initialization and creates the profile automatically. The developer never needs to run `dev_profile_manager.py` directly.
+
+---
+
+## 10 Dimension Categories
+
+Each profile covers 10 dimension categories with configurable fields:
+
+| Category | Key Fields | Example Values |
+|----------|-----------|----------------|
+| **Language** | primary, secondary, min_version, package_manager | `go`, `[python]`, `1.21`, `go mod` |
+| **Style** | line_length, indent_size, naming_convention, docstring_format | `120`, `4`, `snake_case`, `google` |
+| **Testing** | framework, min_coverage, mutation_testing, property_testing | `godog`, `90`, `false`, `false` |
+| **Architecture** | patterns, max_complexity, dependency_injection | `[hexagonal, cqrs]`, `10`, `true` |
+| **Security** | crypto_standard, secret_rotation_days, sast_tool, min_tls | `FIPS 140-2`, `90`, `gosec`, `1.3` |
+| **Compliance** | required_frameworks, cui_markings, classification_headers | `[fedramp_high]`, `true`, `true` |
+| **Operations** | container_base_image, k8s_resource_limits, health_check | `golang:1.21-alpine`, `true`, `true` |
+| **Documentation** | readme_sections, adr_required, changelog_format | `[overview, api, deploy]`, `true`, `keep-a-changelog` |
+| **Git** | commit_format, branch_strategy, merge_strategy, protected_branches | `conventional`, `trunk_based`, `squash`, `[main]` |
+| **AI** | llm_provider, code_review_model, prefer_local, max_tokens | `bedrock`, `sonnet`, `false`, `4096` |
+
+---
+
+## Common Workflows
+
+### "Our org just adopted ICDEV — set up standards for everyone"
+
+1. Create tenant-level profile from template:
+   > Create a dev profile for our tenant using the FedRAMP baseline
+
+2. Lock security and compliance dimensions:
+   > Lock the security and compliance dimensions at the tenant level. ISSO is the lock owner.
+
+3. Each project inherits tenant standards automatically. Projects can override non-locked dimensions.
+
+### "I want my project to use different standards from the org default"
+
+Create a project-level override:
+> Update our project's dev profile: change primary language to Rust, set line length to 100
+
+The cascade resolution merges your project overrides with the tenant defaults. Locked dimensions stay as-is.
+
+### "Show me what standards apply to my project right now"
+
+> Resolve the dev profile for this project and show me where each value comes from
+
+This shows the effective profile with provenance (which layer set each value) and lock status.
+
+### "We're onboarding a new repo — detect its existing standards"
+
+> Scan the repository at /path/to/repo and create a dev profile from what you find
+
+ICDEV detects language, style, testing, and git conventions from the existing codebase. You review the detection results and accept them to create the profile.