---
guide_version: "1.0"
specification_version: "1.0"
software_profile_version: "0.8"
audience: "AI Executors working on software"
author: "Franz Bruckhoff"
---
# Framework Adoption and Execution Guide for AI Agents

**Domain:** software projects.

Apply the Framework for Keeping Complex Work Coherent Across Time to a software Project with this procedure. First assess the Project and propose an adoption Plan. After approval, set up the required records and controls. Use the same procedure for later Work Units, verification, and handover.

The Governing Principles and Normative Structural Specification govern. This guide explains their use. Software methods and storage choices remain recommendations.

Follow the user's instructions and your runtime's permissions. Report conflicts with the Framework before the affected work. This guide does not approve a Production Plan. It does not extend your access.

## Load the sources

- [Governing Principles](https://think-bigger.org/framework/guides/v1.0/principles.md)
- [Normative Structural Specification v1.0](https://think-bigger.org/framework/guides/v1.0/specification.md)
- [Software Profile v0.8](https://think-bigger.org/framework/guides/v0.8/software-profile.md)

Read the complete principles and Specification before the first adoption assessment. Use the profile for storage choices. A search summary is insufficient. If you cannot retrieve a complete source, report which source is missing and request its contents.

For an adopting Project, retain these exact sources and this guide as versioned references in its Project Record. Declare their local bindings. After adoption, use the local edition. Propose an edition change for human review; do not silently replace it.

## Understand the working model

| Principle | Action |
| --- | --- |
| Component-Oriented Decomposition | Divide by responsibility. Give each Component a Contract, owner, and explicit relationships. |
| Layered System Architecture | Keep purpose and Invariants stable. Dependencies point toward equal or higher Stability. |
| Integrated Modularity First | Keep internal modules together until a concrete need justifies separation. |
| Verification-First Engineering | Define completion checks before work. Keep evidence and obtain independent verification. |
| Specifications as Contracts | Work within accepted commitments. Propose changes to those commitments for human authorization. |

The **Project Record** holds durable descriptions, decisions, work, and evidence. The **Realization** is the software and its implementation material. A **Work Unit** is one bounded assignment. Its **Plan Document** states scope, Acceptance Criteria, progress, and decisions. A **Verification Artifact** records what was checked and what happened.

## First contact with a Project

1. Read the applicable project instructions. Inspect permitted files to find the Project Record and its `INDEX`. Preserve current work. Identify the named human owner and your authorized scope.
2. If `INDEX` exists, resolve the local Path Map. Read the Work Record, applicable decisions, approvals, and risks. Use your Component's full Specification and related Components' Contracts. Keep other Components' private Design outside your access (§6.3).
3. Check whether the human asked for adoption, an assessment, or execution of an existing approved Work Unit. Reuse recorded authorization that covers the current work. Do not request the same approval again.
4. For adoption, compare the permitted records with the full Specification and Appendix A. Record missing content, ambiguous bindings, absent checks, and scope controls that are only written instructions. Distinguish planned structure from verified structure.
5. Give the human a brief assessment of sources, current structure, gaps, proposed changes, and required decisions. Name the first bounded Work Unit. Link evidence. Mark unknowns. Keep canonical software and governing records unchanged until the relevant Production Plan is approved (§6.13).

## Prepare adoption

Draft the proposed setup in a separate workspace. Use the existing layout where it can satisfy the Specification. The Software Profile is an optional starting point. `INDEX` at the Project Record root is the only fixed location (§14.3).

The setup Plan must cover these items:

- Human-authored Vision, principles, Invariants, and Acceptance Criteria. You can propose text; the human supplies or accepts the authoritative content (§§1.3, 3.1, 14.1, 15.2).
- Component Contracts with **Rationale**, **Required Behaviors**, **Acceptance Criteria**, **Constraints**, and **Dependencies & Interfaces**. Keep private Design separate. Preserve all Obligation attributes, Constraint provenance, interface authority, and trace links (§§6.2–6.12, 10.2).
- Every required Entity and multiplicity in Appendix A. Complete the local Path Map and format definitions. An empty file does not establish the required content. Lower risk permits less detail; omission requires an explicit human-accepted deviation (§§1.5–1.6, 14.8).
- Stability order, decision significance test, Baseline levels and lock Gates, and change classification dimensions in `INDEX`. Record criticality and tailoring. Declare the Phase sequence and Verification Plan, including Reference Realization decisions (§§7.9–7.10, 7.17, 8.1, 9.1, 14.3).
- Enforced Executor access, independent verification, reusable procedures, and continuously run Normative Checks with retained results (§§5.10, 7.11, 13, 16).

Present the editable Plan for human approval. Record approval before canonical changes. Apply the approved setup as bounded Production Work Units. Report unresolved requirements. Claim Project conformance only when all applicable clauses are satisfied, including human reviews, or have valid deviations.

For future sessions, propose a short entry in the project's existing agent instructions. It must direct the agent to this local guide and local `INDEX`. Let the human control that entry. Confirm that the selected agent actually loads it. Keep changing task state in the Work Record and Plan Documents (§§4.5–4.9, 14.2–14.4).

## Execute an approved Work Unit

1. Resolve the unit, current Plan, Contract, approval, and blocking relations. Confirm the input versions and enforced access. Record unresolved prerequisites. Split work that exceeds one bounded assignment (§§4.5–4.7, 5.5–5.9).
2. Establish the Verification Reference State before changing existing software. Run current checks and retain every pre-existing failure. Record absent verification and assign work to close that gap (§7.5).
3. Use the completion procedures authored before the Work Unit. Establish their failing result before completion. Keep the approved criteria fixed; propose corrections for human authorization (§§7.4, 7.12).
4. Implement within scope and keep the Contract and Realization aligned. Run checks, identify specific defects, correct them, and repeat within the approved limits. Keep structural and behavioral changes separate (§§6.15, 7.2, 9.5).
5. Obtain verification from an independent Executor or context that did not produce the work. Your development checks do not establish independent verification. If no verifier is available, hand over the result as awaiting verification (§7.11).
6. Retain procedure versions, criteria, exact inputs, results, verifier identity, and evidence. Report checks not run. Preserve regression procedures. Record acceptance under the declared human authority or its approved procedure (§§7.4, 7.18–7.19, 10.3).
7. Mark the unit complete only after required verification and acceptance. Update work status, discoveries, risks, and significant numbered decisions before dependent work starts. Generate indexes from canonical records. For locked Baselines, use the controlled change Gate and Status Ledger. Record Phase Gate closure and discrepancy disposition (§§4.3–4.7, 8.4, 9.2–9.3, 11–12).

For software, include applicable interface, security, dependency, migration, and recovery checks in the Verification Plan. Link release descriptions to exact code, configuration, dependencies, and evidence. Treat deployment and other external commitments under the human's declared authority (§§6.17, 7.9, 10.3, 15.2).

## When progress is blocked

Stop the affected work when its Contract, approval, evidence, or enforced scope is missing. Report the condition and the smallest action that can resolve it. Continue separate authorized work only when it does not depend on that condition.

- For unknown design parameters, propose bounded exploratory work. Keep the canonical Project Record read-only and production assets isolated. Record findings through a controlled process; obtain production approval before ingestion (§§5.7, 6.13).
- For changed purpose, Invariants, Contracts, criteria, or risk acceptance, present a proposal with consequences and request the named human's decision (§§1.3, 9.2, 15.2).
- For unexpected failures, preserve the failure and its cause. Follow failure closure requirements before progression. Never disable a criterion to obtain a pass (§§7.12, 12.2).
- For exhausted resource limits, report progress and remaining work. A human controls an increase (§15.2).

After a restart or context loss, reconstruct state from `INDEX`, the Work Record, current Plan, approvals, and evidence. Check whether inputs changed. A chat summary cannot replace those records.

## Return a checkable result

Report the Work Unit and scope, changed artifact identifiers, checks and exact inputs, outcomes and evidence links, acceptance state, and remaining blockers. Distinguish implementation complete, awaiting independent verification, and accepted. Use the project's declared statuses.

Do not invent an owner, approval, test run, or evidence. Keep proposals separate from accepted records. A passing filename check alone cannot establish Project conformance.