ai-native-sdlc-example

Implementation language

• intentc is implemented in Python.
• Use uv for environment management, dependency resolution, and command execution.

Python setup

• Runtime manager: uv
• Pinned Python: 3.14.2
• Install or refresh the environment: uv sync --dev
• Run commands inside the environment: uv run <command>

Core libraries:

• PyYAML for intent authoring input
• jsonschema for schema validation
• typer for the intentc CLI
• pytest and ruff for test and lint workflows

Python practices

• Keep modules small and organized around one compiler concern each.
• Use type hints on public functions and prefer explicit return types.
• Favor pure functions for normalization, validation, and artifact generation.
• Use pathlib for filesystem paths and keep I/O at the edges of the codebase.
• Represent structured compiler data with dataclasses or typed mappings instead of loose dict mutation.
• Raise explicit, domain-specific errors for schema, normalization, and compile failures.
• Keep output deterministic by sorting keys and normalizing ordering before serialization.
• Cover behavior with pytest and keep ruff clean before committing.

Structured planning artifacts

• Intent example: docs/intents/webhook-idempotency.intent.yaml
• Implementation plan: planning/intentc/implementation-plan.md
• Execution backlog: planning/intentc/backlog.yaml
• Enforcement plan: planning/intentc/enforcement-implementation-plan.md
• Enforcement backlog: planning/intentc/enforcement-backlog.yaml
• Enforcement prompt: prompts/02-intentc-enforcement.prompt.md
• Traceability template: planning/intentc/traceability-matrix-template.yaml
• Risk/decisions: planning/intentc/risk-and-decisions.md
• Enforcement risks/decisions: planning/intentc/enforcement-risk-and-decisions.md
• Intent schema: tools/intentc/schema/intent-package-v1alpha1.schema.json
• Compiler spec: tools/intentc/spec/compiler-pipeline.md
• Generation manifest schema: tools/intentc/spec/generation-manifest.schema.json

intentc example usage

Use the sample intent in docs/intents/webhook-idempotency.intent.yaml.

Validate the raw intent package against the schema:

uv run python -m intentc validate docs/intents/webhook-idempotency.intent.yaml

Compile the intent into normalized artifacts:

uv run python -m intentc compile docs/intents/webhook-idempotency.intent.yaml --out /tmp/intentc-build

This writes:

• /tmp/intentc-build/normalized.intent.json
• /tmp/intentc-build/traceability.graph.json
• /tmp/intentc-build/clauses.index.json
• /tmp/intentc-build/reports/coverage-map.json
• /tmp/intentc-build/reports/missing-coverage.json
• /tmp/intentc-build/tests/*.feature
• /tmp/intentc-build/tests/test_inv_*.py
• /tmp/intentc-build/policies/**
• /tmp/intentc-build/runtime/**
• /tmp/intentc-build/generation-manifest.json

Regenerate just the manifest from an existing normalized build:

uv run python -m intentc generation-manifest /tmp/intentc-build/normalized.intent.json

Run the full executable enforcement stack:

uv run python -m intentc verify docs/intents/webhook-idempotency.intent.yaml --out /tmp/intentc-verify

intentc verify is the canonical local and CI entry point. It validates the intent, compiles deterministic artifacts, executes the generated pytest-bdd scenarios and invariant tests, runs OPA and Semgrep policy gates, enforces clause traceability and coverage thresholds, and writes the machine-readable verification result into /tmp/intentc-verify/generation-manifest.json.

The manifest verification block is the source of truth for enforcement status:

{
  "verification": {
    "status": "pass",
    "stages": [
      {"name": "bdd", "status": "pass"},
      {"name": "invariants", "status": "pass"},
      {"name": "policies", "status": "pass"},
      {"name": "semgrep", "status": "pass"},
      {"name": "traceability", "status": "pass"},
      {"name": "coverage", "status": "pass"}
    ]
  }
}

Common local workflow:

• uv sync --dev
• uv run python -m intentc validate docs/intents/webhook-idempotency.intent.yaml
• uv run python -m intentc compile docs/intents/webhook-idempotency.intent.yaml --out /tmp/intentc-build
• uv run python -m intentc verify docs/intents/webhook-idempotency.intent.yaml --out /tmp/intentc-verify
• uv run python tools/intentc/scripts/ci_compile_gate.py
• uv run pytest
• uv run ruff check intentc tests tools

Failure stage summaries are printed in a stable format such as bdd: fail - ... or coverage: fail - ..., and intentc verify exits non-zero whenever any enforcement stage fails.

Operator guidance and troubleshooting live in docs/intentc-enforcement-workflow.md, with pilot evidence in planning/intentc/webhook-idempotency-pilot.md and captured logs under logs/intentc/.

Run the repository smoke test for the full validate/compile/manifest flow:

uv run python tools/intentc/scripts/ci_compile_gate.py