Skip to main content

AI SDLC Harness

AI SDLC Harness helps developers review AI-assisted changes: understand what was reported as checked, which code and requirements were reviewed, and what needs checking again after an edit. It keeps task intent, implementation evidence, and optional separate-review records in your repository, alongside your existing coding tools.

Separate verification and the local HTML report require v1.1.0 or later.

Review Evidence That Stays Tied To The Change

Question at review time What Harness shows
What was checked? Reviewer-recorded checks, outcomes, observations, and omissions, distinguishing checks reported as executed from existing evidence merely reviewed.
Which version was reviewed? An exact-content fingerprint of explicitly selected code, tests, and configuration plus the seven task inputs. Uncommitted changes are supported.
Does that review still apply? Whether those inputs still match the recorded candidate; relevant edits mark the review outdated and list changed files.

For example, a reviewer records a check against src/client.py and its tests. If the implementation or acceptance criteria change afterward, Harness marks that review outdated. An old finding's line reference is no longer presented as a current code location. The developer can prepare a new handoff for the changed candidate.

Reviewer identity, session separation, and check execution are self-reported. Harness does not yet execute checks or capture their output. Its content fingerprint covers the selected files and task inputs, not every dependency or the execution environment; it identifies content but does not archive the old source bytes. A current record is evidence to inspect, not approval.

Use the optional review walkthrough with your existing human reviewer or coding tools. A different model is optional. The read-only local report brings the workflow, attention items, reviewer observations, and code references together.

Selected code and task inputs are fingerprinted for review; relevant edits make the review outdated and require a new candidate

A Workflow Around Your Coding Tools

The existing task workflow turns a rough request into explicit task artifacts, a task-scoped implementation handoff, recorded evidence, and deterministic workflow status that humans and coding agents can follow.

The coding agent does the work. Harness structures, guides, and records the workflow. The developer remains the authority over intent, consequential decisions, and acceptance.

Coding agent = executor
Harness = control layer
Developer = authority

AI SDLC Harness provides first-party, repository-scoped integrations for Codex, Claude Code, and Gemini CLI while remaining agent-neutral. See Compatibility for detailed support and validation status.

The Harness does not call an AI model or implement the task. It supplies the control layer around that work: scope, acceptance criteria, test intent, current generated context, integrity checks, and visible human-review boundaries.

AI SDLC Harness is a control layer, not a security sandbox. Harness boundaries are not security boundaries. It structures intent, context, workflow state, verification, and human decision points so coding agents have explicit workflow and authority boundaries. Those boundaries guide the intended development process but do not provide hard runtime enforcement. Use platform controls such as permissions, sandboxing, branch protections, CI/CD policy, and execution isolation where technical prevention is required.

The two layers are complementary: the agent runtime determines what execution is technically possible; the Harness makes explicit what work is intended, current, and reviewable.

With a repository Agent Skill installed, a coding agent can use Harness status as its workflow navigator, work from the current bounded handoff, record factual evidence and verification, and continue through routine safe steps without asking for approval after every command. It should stop when a real human decision is required, necessary information is unavailable, scope or intent is consequentially ambiguous, or Harness reports a blocking condition.

The diagram below describes the implementation workflow. “Autonomously” means this bounded, status-guided continuation, not guaranteed uninterrupted completion. Harness does not invoke or orchestrate the agent. The optional separate-review handoff adds another review step after implementation; “one handoff” does not describe that additional step, and “review-ready” does not mean approved or independently verified.

Developer defines intent, Harness prepares bounded work, the coding agent executes, and the developer reviews structured results

What It Provides

  • Human-owned task files for scope, acceptance criteria, architecture, coupling, test intent, verification, and evidence.
  • Deterministic reports and a bounded agent-workset.md generated from those task files.
  • ai-sdlc status, which derives the current phase and the next valid action from repository state.
  • Lineage checks that identify missing, stale, fresh, or unknown generated planning artifacts.
  • Validation-currentness and manifest-integrity signals without claiming correctness, security, or approval.
  • Optional repository Agent Skills for Codex, Claude Code, and Gemini CLI.
  • Optional separate-verification handoffs bound to selected code and task inputs, with reviewer observations kept separate from implementation claims.
  • A read-only local HTML report with manual refresh, human attention items, verification details, and scoped code references.

Harness task and control state lives in the repository under .harness/, so the task record can be reviewed alongside the change instead of existing only in chat history. Optional agent adapters live at agent-specific paths in the same repository.

Quick Start

Install AI SDLC Harness as an isolated command-line tool:

uv tool install ai-sdlc-harness
ai-sdlc --version

As a secondary option, use pipx install ai-sdlc-harness.

Then run the first three commands in the repository you want to govern:

ai-sdlc init
ai-sdlc task start "Add request timeout handling"
ai-sdlc status --task add-request-timeout-handling

Edit the new human-owned files under .harness/tasks/add-request-timeout-handling/, especially task.md, acceptance.md, and test-contract.md. A coding agent may help draft these files within the developer's stated intent; human-owned means the developer retains authority, not that every line must be typed manually. Rerun status and follow the command or human action shown under next:. The Harness routes the recorded workflow through readiness, specification, test-contract review, implementation handoff, evidence, validation, and final human review; it does not launch or orchestrate the agent.

When the phase reaches implementation, use:

.harness/tasks/add-request-timeout-handling/generated/agent-workset.md

as the bounded handoff for the human or coding agent doing the change. Record only factual results in evidence.md and the commands actually run in verification.md, then rerun status.

See the Quickstart for the complete walkthrough.

Review the work locally

Run ai-sdlc report --task <task-slug> from your project and open the local URL printed by the command. The page reads existing task records; use Refresh to see updates. Its four views cover workflow progress, human attention items, verification and evidence, and code/artifact excerpts.

For an optional review in a fresh session, prepare a handoff with ai-sdlc review prepare --task <task-slug> --file src/example.py --file tests/test_example.py, using your own relevant paths. Open the printed handoff in your existing review tool and record observations in its sibling result.json. Harness distinguishes checks reported as executed, evidence merely reviewed, and checks not run. Relevant edits mark the review outdated. Context separation is self-reported, and only explicitly selected files and the seven task inputs are covered.

See the CLI reference for the result format, limits, and local report controls. These commands require v1.1.0 or later.

Optional Agent Skills

After ai-sdlc init, install one repository-scoped adapter or all three:

ai-sdlc adapter install codex
ai-sdlc adapter install claude-code
ai-sdlc adapter install gemini-cli
# or: ai-sdlc adapter install all

These commands install a thin Harness skill at the supported repository path for each agent. They do not modify root AGENTS.md, CLAUDE.md, or GEMINI.md. Existing unmanaged files at the adapter paths are not adopted or overwritten.

Workflow Outcomes

ai-sdlc status reports one of four outcomes:

  • NEXT — run the displayed Harness command.
  • REVIEW_REQUIRED — a person must edit, review, resolve, or accept the indicated material.
  • BLOCKED — correct the reported integrity, safety, or workflow problem before continuing.
  • COMPLETE — the Harness workflow record is complete; normal human review and delivery still remain.

Use ai-sdlc status --json for deterministic machine-readable navigation. If more than one task exists, select one explicitly with --task <task-slug>.

Source Of Truth And Integrity

Human-owned task files are the authoritative inputs. Generated reports, projections, and worksets are managed outputs; do not edit them directly. If task intent changes, edit the source task files and follow status to regenerate anything stale.

ai-sdlc verify checks Harness structure and protected-file hashes. ai-sdlc validate --task <task-slug> evaluates workflow consistency and recorded review-readiness signals. Neither command runs project tests or proves that an implementation is correct, secure, compliant, approved, or ready to release.

Current Limits

AI SDLC Harness does not:

  • call AI models or launch or orchestrate coding agents
  • autonomously monitor the repository or implement application code
  • generate or run project tests
  • deeply inspect application code
  • scan for vulnerabilities or validate compliance
  • prove correctness, approve work, or determine release readiness
  • enforce optional packs

It gives humans and coding agents a smaller, current, inspectable workflow record; it does not replace engineering judgment or normal delivery controls.

Learn More

Metadata

Release files for ai-sdlc-harness 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-sdlc-harness 1.1.0
File Size Uploaded Provenance Actions
ai_sdlc_harness-1.1.0.tar.gz 139.0 kB With provenance Details for ai_sdlc_harness-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-sdlc-harness 1.1.0
File Interpreter ABI Platform Actions
ai_sdlc_harness-1.1.0-py3-none-any.whl Python 3 none any Details for ai_sdlc_harness-1.1.0-py3-none-any.whl

Total release size: 293.2 kB

Release files / ai_sdlc_harness-1.1.0.tar.gz

Download URL ai_sdlc_harness-1.1.0.tar.gz
Size 139.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f03778ec3e7e489b320268fd38b49f031eeac90265dd920b4a6d3703c6ee2647
BLAKE2b-256 checksum
How to use checksums
3a7b401d57fefa7deaa68093f407e298c24abe2cb38afc51a24ccc481b2ce7af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.

Transparency log

Release files / ai_sdlc_harness-1.1.0-py3-none-any.whl

Download URL ai_sdlc_harness-1.1.0-py3-none-any.whl
Size 154.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ed8b562510678c9b806af5830d2b09011650d72b9c08f63021d730b6a293ab57
BLAKE2b-256 checksum
How to use checksums
74984019a9eb36b58dbf72e452c52da919fda73be9d62079ebdb8f7bbece07cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.

Transparency log

Security for ai-sdlc-harness 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ai_sdlc_harness-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page