Software Engineering Process

See the maintained capability status for what is implemented, partial, experimental, designed, or deferred.

A technology-neutral Software Engineering Policy and Assurance platform. It resolves what must be true for a change and delegates how to coding assistants, humans, CI, GitHub, and other native mechanisms.

Canonical Policy → Domain Profile → Repository Manifest → Trusted Classification
→ Effective Obligation Set → Skills / Native Controls / Human Boundaries
→ Execution → Exact-Revision Evidence → Readiness → Merge / Deployment

This is not a coding-agent orchestrator. It is a small policy compiler, evidence join, and set of portable specialist procedures.

Install

python -m pip install .
engineering-process --help

Python 3.11+ is supported. The wheel includes the policy, schemas, templates, and Skills, so commands work outside this checkout.

Adopt in a repository

From this process checkout (so the exact Git revision can be pinned):

engineering-process --root ../my-web-app init \
  --profile frontend --repository-name suyog19/my-web-app

Or supply an immutable released revision explicitly with --revision <40-hex-sha>. Initialization creates the manifest and lock, compact AGENTS.md/CLAUDE.md, portable Skills, and a validation workflow. Existing assistant context is never silently overwritten; follow the mature repository migration and use the explicit --adopt-existing-context flow. Add repository differences—validation commands, protected path hints, UX triggers—to .engineering/process.yaml, then re-render/re-lock using a reviewed process upgrade.

Change flow

engineering-process classify \
  --base "$BASE_SHA" --head "$GITHUB_SHA" \
  --declared '{"observable_behavior":true}'

engineering-process evaluate \
  --base "$BASE_SHA" --head "$GITHUB_SHA" \
  --declared '{"observable_behavior":true}'

engineering-process explain \
  --base "$BASE_SHA" --head "$GITHUB_SHA" \
  --declared '{"observable_behavior":true}'

engineering-process run-validation --sha "$GITHUB_SHA" \
  --obligations .engineering/effective-obligations.json \
  --output-dir "$RUNNER_TEMP/objective-evidence"

engineering-process readiness --sha "$GITHUB_SHA"
engineering-process validate
engineering-process metrics --obligations .engineering/effective-obligations.json

Trusted classification derives the complete Git change set from exact --base and --head commits, including deletions and both rename paths. --path is untrusted and diagnostic-only. Classification is monotonic: declarations may strengthen routing but may not defeat deterministic Protected signals. Unknown Protected characteristics fail closed. readiness rejects malformed, failed, contradictory, wrong-repository, wrong-SHA, wrong-process-revision, unauthorized-producer, and invalid fresh-context review evidence. See the authoritative evidence lifecycle.

Phase 2 adds a locked agent-execution security baseline, a complete GitHub reference flow, executable test-result/v2 validation basis, and structured independent-review/v2 evidence. explain reports profile-aware validation categories and the execution boundary. Reference evidence travels through GitHub artifacts and out-of-band provenance rather than source commits.

Phase 3 adds optional privacy-conscious outcome metrics, advisory task-delegation suitability independent of delivery profile, deterministic dependency assurance, and repository-context truth maintenance. See adaptive assurance and delegation examples.

Policy model

• Locked controls cannot be changed locally (fresh-context independent review, fail-closed Protected routing, exact-revision evidence, secrets, traceability, human production boundary).
• The human production boundary requires manual human authorization and promotion. A repository owner may satisfy it; it does not implicitly require a second human. Automation and agents may not authorize or promote production.
• Extensible controls can only be strengthened.
• Overridable mechanics belong to repositories (commands, paths, runtime, framework, environments).
• Profiles describe engineering/risk domains (generic, frontend, backend), never languages or frameworks.
• Specialist procedures are portable SKILL.md packages and are selected only when obligations require them.
• Solution Sufficiency classifies feedback as must-address, worth-now, defer, or reject. It cannot suppress mandatory findings and provides an explicit stopping rule.

See Architecture, Adoption, GitHub enforcement, governance, and the authoritative design.

Development

python -m pip install -e '.[dev]'
pytest
python -m build

Policy changes require tests, compatibility/upgrade notes, and stronger review for locked controls. Apache-2.0 licensed.