Adopt an existing project

Adoption connects TCAF to a repository that already contains code, decisions and working behaviour. Its purpose is to establish reliable project evidence before any development task is authorized.

Adoption observes the project. It does not improve, modernize or rewrite it.

Run the adoption workflow

From any directory, target the repository explicitly:

tcaf adopt --target <existing-project>

The command produces a Run Envelope for the selected adapter. Give that envelope to the host tool and review the proposed adoption scope before allowing files to be written.

What the adoption agent inspects

The agent should inspect only enough evidence to describe the project accurately, including where relevant:

• repository structure and application boundaries;
• package and dependency manifests;
• build, test, lint and validation capabilities that actually exist;
• frameworks, languages, state management and persistence patterns;
• CI configuration and deployment evidence;
• existing documentation, backlog and issue sources;
• local implementation conventions and known limitations.

Absence is evidence. The agent must not invent a test framework, architecture, database, validation layer or delivery process that the project does not contain.

Expected project documents

Adoption normally creates or reconciles the canonical documents required by the project profile, such as:

• project manifest;
• capability baseline;
• architecture or technical baseline;
• backlog and task-source mapping;
• estimation or decision records where applicable;
• status and validation notes.

The exact set depends on the project. Documents must describe the repository as found, not an idealized future version.

Adoption boundary

Unless the developer explicitly opens a separate task, adoption must not:

• change application code;
• refactor working areas;
• add or update dependencies;
• reformat unrelated files;
• introduce tests or infrastructure that are not already available;
• mark uncertain information as fact;
• commit, tag, push or open a pull request.

Review the result

Before accepting adoption, confirm that:

1. paths in the documents match the repository;
2. implemented capabilities are separated from planned capabilities;
3. limitations and unknowns remain visible;
4. backlog sources are mapped without silently replacing them;
5. no application files changed;
6. the target validates successfully.

Run:

tcaf validate --target <existing-project>

A passing validation confirms structural consistency. It does not prove that every architectural statement is correct; the developer still reviews the evidence.

After adoption

Once accepted, the canonical documents become the starting context for bounded development tasks. They do not remove the need to inspect the local implementation relevant to each task.

Continue with Run a development task or choose a specific task source such as an existing backlog or GitHub Issue.