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.
| 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.
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.
- Human-owned task files for scope, acceptance criteria, architecture, coupling, test intent, verification, and evidence.
- Deterministic reports and a bounded
agent-workset.mdgenerated 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.
Install AI SDLC Harness as an isolated command-line tool:
uv tool install ai-sdlc-harness
ai-sdlc --versionAs 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-handlingEdit 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.
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.
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 allThese 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.
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>.
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.
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.