Start with your real project.

1. Prepare your tools and context

The kit uses Python 3.11+, Bash, Git, grep, awk and standard Unix tools. Use macOS/Linux, or a compatible environment such as WSL on Windows. The model does not require a paid AI plan, plugin or cloud service.

A coding assistant is optional. It must be able to read project files and follow the agreed rules. A team can also use the workflow without AI.

2. Download and review the kit

Extract it into a new folder to review its structure. Do not overwrite your repository. Read README.md, PATHS.toml and the execution rules before adoption.

unzip -n modelo-projetos-1.0.0.zip
cd modelo-projetos
# Read README.md and PATHS.toml before adoption.

3. Understand the existing structure

Identify the root, branch and local changes. Review manifests, modules, contracts, data, tests and current commands. In a new project, record what exists and keep the rest as planned.

• Single project: one app or service with a main set of checks.
• Product monorepo: several physical modules with shared contracts and governance.
• Independent products: do not merge their scopes just because they share a folder.

4. Configure the project map

Edit PATHS.toml with the name, root, official documents, real modules, runtime folders and reproducible checks. The example below is only part of the file. Keep the other kit sections.

[project]
name = "MY_PROJECT"
root = "/absolute/path/to/project"

[modules]
app.root = "src"

[quality]
runtime_dirs = ["src"]

5. Describe the real product

Replace PRD.md and ESCOPO.md with your product’s problems, requirements, users and limits. Merge existing decisions and rules with the model. Keep valid content. Set prd.template_mode=false after replacing the placeholders.

Also adapt AGENTS.md and QUALITY_ROADMAP.md. Branch, SQL and naming rules are project choices. They must fit your team. Record any change to a rule and its impact.

6. Review requirements and evidence

The bootstrap discovers items and suggests states. It does not approve the implementation. Review code, contracts, screens, data and tests before accepting each state. Then generate the matrix and run the checks.

python3 scripts/prd_inventory.py --bootstrap-classifications
# Review docs/prd-classifications.json manually.
python3 scripts/prd_inventory.py --update
python3 scripts/prd_inventory.py --check
./check.sh

7. Make one small delivery

Choose a change with clear acceptance criteria. Inspect, implement, test the scope, update the affected documents and review the diff. Adoption works when the documents help you make decisions about real code.

Check failures are expected before configuration and review. Do not weaken validation or mark work as complete just to get a passing result.