aidlc-harness

Get started · Your AI tool, step by step · Documentation · Reference · The method in practice (in Portuguese) · Português (Brasil)

aidlc-harness takes a one-sentence request to approved requirements and then to code that only counts as done with evidence, inside the AI tool your team already uses. The AI drafts everything with its own recommendations and asks only what it cannot decide, in the tool's own question window; a person approves each phase; and a gate refuses "done" without the raw test output. It works in 15 AI tools (Claude Code, GitHub Copilot, Cursor, Kiro, OpenCode, Codex, Gemini CLI, Antigravity and more) and in 10 technology stacks, from Node to Java, .NET and Go.

[!NOTE]
Version 0.2, pre-release. Everything described here exists and has tests, and CI runs on Linux, macOS and Windows. Which AI tools were exercised on a real machine is stated tool by tool in Project status. This project is a practical interpretation of AI-DLC; it is not AWS documentation or an AWS product (docs/AIDLC.md).

Contents

• Get started in one minute
• Your AI tool
• An Inception that does not feel like a phone menu
• Why it exists
• How it works
• What ships in the kit
• Security: any platform, including RoqueShield
• Project status
• Known limits
• Documentation
• Contributing, security and license
• Languages

Get started in one minute

Prerequisites: Node 20.19 or newer and git. In your project's folder:

npx github:roqueribeiro/aidlc-harness init

In a terminal it asks which AI tools the team uses (the ones it finds in the folder come already checked) and creates, for each one, the commands in that tool's own format. Then open your tool and run the Inception with one sentence about what you want, for example /aidlc-inception I want a customer registry with search and change history. The exact command for each tool is in the table below and in .aidlc/COMANDOS.md in your project.

To keep every aidlc-* command on your PATH (needed by the hooks of Copilot, Cursor and Codex):

npm install -g github:roqueribeiro/aidlc-harness

In Claude Code, install the plugin as well: claude plugin marketplace add roqueribeiro/aidlc-harness and claude plugin install aidlc-harness@aidlc. The full path, with what to expect at each step, is in docs/GETTING-STARTED.md.

Your AI tool

Each tool receives the Inception and Construction commands in its own folder and format, and each command names that tool's question window. Where the tool allows hooks, the kit also holds a "done" that has no green gate behind it.

This table is generated from the same adapters that aidlc-init applies, and CI fails if it drifts. Where the kit has no hook, CI enforces the evidence: the aidlc-gate.yml workflow that aidlc-init creates runs on every push in every tool.

An Inception that does not feel like a phone menu

The slow way to gather requirements is twenty questions before anything is written. The kit does the opposite:

1. Reads first. AGENTS.md, the product context, the decisions already made, the code, and whatever you put in aidlc/inception/insumos/ (a meeting transcript, a brief, a screenshot). What is already answered there does not become a question.
2. Drafts everything. Requirements, stories with verifiable acceptance criteria and units of work, filled in with the AI's recommendations. Every choice it made alone is listed under Premissas (assumptions), with the reason.
3. Asks only what it cannot decide. At most five questions, only on what is irreversible, business, scope, compliance, cost or naming, in the tool's own question window, with the recommended option first. "Accept all recommendations" is always one click (or one "ok" where there is no window).
4. A person approves. aidlc-phase check inception fails with more than five open questions, with assumptions nobody reviewed, or with an approval signed by an AI.

The method lives in one place, the aidlc-inception skill, which every tool reads. The full text is in plugins/aidlc-harness/skills/aidlc-inception/SKILL.md.

Why it exists

An agent delivers, a person reviews, and finds the same kind of problem for the fifth time. Not because the model is bad, but because every session starts over without knowing what the team has already decided and without anything that enforces "done". The bottleneck becomes review.

The kit answers with four decisions that are not about prompts:

1. Acceptance criteria are data, not prose. A JSON file per technology says which command runs, which output fails and whether it blocks.
2. Determinism beats the model when the task is mechanical. If a check can be a script, it is a script.
3. Evidence before "done". The gate's raw output, not a summary.
4. A person approves the phase. The kit checks that the approval exists and was not filled in by an AI.

One rule runs through everything: a rule without a mechanism is decoration. Every norm in this repository points to the hook, gate or manifest that enforces it (OPERATING-MODEL.md).

How it works

The team decides, the AI tool executes and the kit enforces what was agreed: instructions every tool reads (AGENTS.md), one command per phase in each tool, aidlc-* executables that cost no tokens, per-stack quality manifests and, where the tool allows, hooks. aidlc/decisions.md keeps what was decided and is not reopened. The design, with diagrams, is in docs/ARCHITECTURE.md.

What ships in the kit

The full list, with options, fields and variables, is in docs/REFERENCE.md. A repository check fails if something exists on disk and is not listed there.

Security: any platform, including RoqueShield

The kit does not embed a scanner: it enforces the result of one, with a rule that does not change: a scan that did not run is not a clean scan. SARIF 2.1.0 (Semgrep, CodeQL, Trivy and others), the kit's neutral format and the AI Fix Bundle of RoqueShield enter through the same contract.

$ aidlc-scan docs/exemplos/scan/neutro-nao-rodou.json; echo "exit $?"
aidlc-scan  docs/exemplos/scan/neutro-nao-rodou.json  (neutro; scanners: semgrep)
NAO RODOU: cobertura incompleta: algum scanner nao rodou ou falhou
exit 2

The list of findings in that report is empty, and the result is still not clean (NAO RODOU means "did not run"). Exit 0 is clean, 1 failed, 2 did not run. Details in docs/INTEGRATIONS.md.

Project status

There is no compatibility promise between minor versions yet.

Known limits

• AI tools change every month. What each page says was checked on 2026-11-06 against the tool's documentation. A tool is marked verified only with a print of a real session.
• Hooks exist in Claude Code, GitHub Copilot, Cursor and Codex. In the other tools, what holds an unproven "done" is CI and human review.
• Kiro, Augment and Zed have no question window: the Inception asks in short text with lettered options, the recommended one marked.
• The identity scanner finds formats, not names. The name of a person, customer or internal system is only caught if it is in your denylist, which lives outside the repository.
• aidlc-phase checks form, not truth. It guarantees that the approval exists and is not from an AI; whether the name belongs to whoever really approved is human review.
• The kit's own messages are in Brazilian Portuguese (executables, hooks, prompts). The documentation is in English and Brazilian Portuguese.

Documentation

Start with docs/GETTING-STARTED.md and docs/TOOLS.md. The full map is in docs/INDEX.md:

The method behind the kit, in plain language, is at levelhard.com.br/aidlc (in Portuguese).

Contributing, security and license

• Contributing: CONTRIBUTING.md. Every new check comes with a mutant, and commits are signed off with git commit -s (DCO). Reports from real sessions in each AI tool are the most useful contribution right now.
• Security: report vulnerabilities privately, as SECURITY.md says.
• Conduct: CODE_OF_CONDUCT.md.
• License: MIT.

Languages

English is the primary language of this repository, and every document has a Brazilian Portuguese pair: README.pt-BR.md and docs/pt-BR/. If the two differ, the English one wins, and check-i18n fails CI when a pair falls behind. The kit itself speaks Brazilian Portuguese (executable messages, hooks, prompts and commands).