Skip to content

quickstart.md

Latest commit

 

History

History
214 lines (140 loc) · 11.3 KB

quickstart.md

File metadata and controls

214 lines (140 loc) · 11.3 KB
Raw

Quickstart

This walkthrough creates one task, follows the status-guided workflow to implementation, records evidence, and reaches the final human-review boundary.

The optional separate-review walkthrough then shows how to bind reviewer observations to selected code and task inputs, detect later edits, and inspect the result in a local report. Separate verification and the local HTML report require v1.1.0 or later.

1. Install The Released Package

AI SDLC Harness requires Python 3.11 or newer. Install it as an isolated command-line tool with uv:

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

As a secondary option, use pipx install ai-sdlc-harness. If neither tool is available, python -m pip install ai-sdlc-harness is an appropriate fallback inside an explicitly activated virtual environment.

Use these commands when you need to manage the uv installation:

uv tool upgrade ai-sdlc-harness
uv tool install ai-sdlc-harness==1.1.0
uv tool uninstall ai-sdlc-harness

2. Initialize A Repository

Change to the repository where the work will happen, then initialize its repo-local Harness state:

cd path/to/your-project
ai-sdlc init

Initialization creates .harness/. It does not modify root AGENTS.md, CLAUDE.md, or GEMINI.md, and it does not install an agent adapter implicitly.

3. Start A Task

Start with a short human-readable title:

ai-sdlc task start "Add request timeout handling"

The command prints the safe task slug and creates human-owned source files under:

.harness/tasks/add-request-timeout-handling/

Fill in the generated templates. At minimum, make the task scope, acceptance criteria, and planned test and verification intent concrete in task.md, acceptance.md, and test-contract.md. Use the architecture and coupling notes when they are material. A coding agent may help draft these files, but it must not invent or redefine the developer's intent merely to advance the workflow.

The complete human-owned source set is:

  • task.md
  • acceptance.md
  • architecture-notes.md
  • coupling-notes.md
  • test-contract.md
  • verification.md
  • evidence.md

These files remain the authoritative workflow inputs. “Human-owned” describes authority and ownership, not a requirement that a human manually type every line. Do not edit generated reports to change task intent.

4. Let Status Route The Work

The developer may ask the read-only workflow resolver what should happen next:

ai-sdlc status --task add-request-timeout-handling

With a supported repository Agent Skill installed, the more typical operating model is to give the coding agent the task and let it consult structured status repeatedly. For example:

Work on task add-request-timeout-handling using the AI SDLC Harness workflow.
Follow Harness status and continue through routine bounded work without stopping
after every Harness command. Stop when you reach a human decision, need information
from me, encounter consequential ambiguity about scope or intent, or Harness reports
a blocking condition.

The coding agent performs the engineering work; Harness supplies current task state, deterministic next actions, integrity and currentness checks, bounded context, evidence expectations, and authority boundaries. Harness does not call or orchestrate the agent. Routine NEXT steps do not each require separate human approval.

Whether the developer or agent is driving, follow the command or human action shown under next:, then rerun status. Depending on repository state, the sequence routes through:

preflight -> spec -> test-contract -> generate -> implementation
           -> evidence -> validate -> review -> complete

The producer commands are deterministic and task-scoped:

ai-sdlc preflight --task add-request-timeout-handling
ai-sdlc spec --task add-request-timeout-handling
ai-sdlc test-contract --task add-request-timeout-handling
ai-sdlc generate --task add-request-timeout-handling

Do not assume every command should be run immediately. status can stop at a human-review boundary or blocking condition. An agent may continue through routine safe producer actions, implementation, verification, and evidence work, but it cannot approve for the developer or change authoritative intent simply to unblock itself. If a producer refuses to replace a drifted managed output, inspect the mismatch before deciding whether that producer's explicit --force option is appropriate.

If task source files change later, Lineage can mark dependent outputs stale and route you back to the correct producer. Update the human-owned source, not the generated output.

5. Implement From The Bounded Handoff

When status reports the implementation phase, give this file to the human or coding agent implementing the change:

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

The workset packages current task intent, relevant repository context, warnings, secure-engineering guardrails, and evidence expectations. It is a bounded starting point, not permission to ignore repository code that must be inspected for the task.

generate also manages generated/context-manifest.yaml, the machine-readable record of the same context-selection snapshot. Do not edit either generated file directly.

Implementation happens outside Harness execution: Harness does not change the application itself. The coding agent or human implementer changes the application, tests, or configuration normally.

6. Record Evidence And Verification

After implementation, the coding agent or developer updates the human-owned factual records:

  • evidence.md — what changed, why, files affected, requirements addressed, and known gaps.
  • verification.md — commands actually run, observed results, and checks not run with the reason.

Do not claim a command ran when it did not. Then rerun status and follow its next actions, which normally include:

ai-sdlc evidence --task add-request-timeout-handling
ai-sdlc validate --task add-request-timeout-handling

Validation reports workflow consistency and review-readiness signals. It does not run project tests or inspect the implementation deeply.

7. Stop At Human Review

The developer may rerun this directly, or the coding agent may keep using it as the workflow navigator:

ai-sdlc status --task add-request-timeout-handling

The expected agent loop is: consult status, perform allowed work, update or regenerate the appropriate records, and consult status again. The agent need not pause after each routine transition. It must stop for a genuine human authority or approval decision, unavailable required information, consequentially ambiguous intent, or a reported blocker.

Resolve any reported blocker. When validation warnings remain, status stops at REVIEW_REQUIRED: an agent may prepare information or proposed edits, but it cannot accept the warning for the developer. Resolve the warning and rerun validation if you want to reach COMPLETE, or carry its documented acceptance into the normal human delivery decision. When the outcome becomes COMPLETE, Harness workflow automation stops; the implementation still needs the repository's normal review, approval, and delivery process.

You can check protected Harness state independently at any time:

ai-sdlc verify

verify checks structure and manifest-managed hashes. It does not prove correctness, security, compliance, or release readiness.

Optional: Review The Candidate In A Fresh Session

After implementing the change and recording implementation evidence, select the files the reviewer needs. Include relevant source, tests, and configuration; Harness does not infer the complete review scope. Substitute your actual project paths in this example:

ai-sdlc review prepare --task add-request-timeout-handling --file src/client.py --file tests/test_client.py

The command creates a new review folder containing handoff.md, snapshot.json, and result.json. It records an exact-content fingerprint of the selected files and the seven task inputs, including requirements and implementation evidence. No commit is required, and earlier review folders are preserved.

  1. Open the printed handoff.md in a fresh session with your existing coding tool, or give it to a human reviewer. A different model is optional. Harness does not launch the session or authenticate its separation.
  2. Ask the reviewer to inspect the requirements, protected behavior, and selected code, and perform only authorized checks. Treat implementation evidence as claims to evaluate.
  3. Have the reviewer complete the sibling result.json. Each check distinguishes executed, reviewed without rerunning, or not_run, with an outcome and observation or omission reason. Record findings and limitations. The CLI reference contains the complete format and an example.
  4. Inspect the record from the terminal or local report:
ai-sdlc review status --task add-request-timeout-handling
ai-sdlc report --task add-request-timeout-handling

Open the local URL printed by report. Use Needs your attention for review findings and code references, Verification & evidence to compare reviewer observations with implementation claims, and Refresh to reread existing records. The page cannot approve work, execute commands, or modify task files.

If you edit a selected file or any task input afterward, refresh the report or rerun review status: the review becomes stale, and the changed paths are listed. Prepare a new review for the new candidate. Changes to unselected files and external environments are not tracked. The fingerprint identifies the reviewed contents but does not retain a copy of the old code.

A current review means a completed record matches the selected inputs; its verdict may still request changes. executed is a reviewer declaration, not a Harness-captured execution log. Separate review remains optional and advisory: it does not alter the existing status/validate outcome or replace your normal acceptance decision. A COMPLETE workflow does not imply that separate verification occurred.

Optional: Install A Repository Agent Skill

After initialization, install a thin skill for one supported coding agent:

ai-sdlc adapter install codex
ai-sdlc adapter install claude-code
ai-sdlc adapter install gemini-cli

Or preflight and install all three together:

ai-sdlc adapter install all --dry-run
ai-sdlc adapter install all

The managed skill paths are:

  • Codex: .agents/skills/ai-sdlc-harness/SKILL.md
  • Claude Code: .claude/skills/ai-sdlc-harness/SKILL.md
  • Gemini CLI: .gemini/skills/ai-sdlc-harness/SKILL.md

Adapter installation never adopts an existing unmanaged file. --force is only for restoring or refreshing an adapter already managed by the Harness.

Optional: Machine-Readable Status

Coding-agent adapters and other tooling should use structured status:

ai-sdlc status --task add-request-timeout-handling --json

The JSON document exposes the selected task, phase, outcome, next actions, four Lineage states, generated-handoff state, validation currentness, integrity state, and bounded findings. It is read-only and derived from current repository artifacts.