Project documents
Understand the canonical project evidence TCAF uses to preserve context, architecture, capabilities, rules and task sources across tools and sessions.
TCAF does not rely on one chat session to remember how a project works. It uses project-owned documentation as persistent evidence that different models and tools can inspect again.
These documents are not framework copies. They describe the target project and remain inside the project because they are part of its current engineering state.
Framework instructions live in the installed TCAF runtime. Project truth lives in the target project.
Why canonical roles matter
A project may already contain a README, architecture notes, ADRs, issue trackers, runbooks and product documents. TCAF should not duplicate them blindly.
The project manifest maps canonical roles to the actual authoritative paths. A role says what information TCAF needs; the manifest says where that information lives in this project.
For example, the official backlog may be:
- a repository Markdown file;
- GitHub Issues;
- another external tracker;
- direct developer requests for a lightweight project.
TCAF records the source rather than forcing a second backlog.
Common project-document roles
The exact filenames can vary, but an adopted or bootstrapped project commonly needs the following roles.
Project brief
Describes the project’s purpose, users, current goals, boundaries and important context.
It should distinguish confirmed facts from aspirations and avoid turning a short brief into an invented product specification.
Architecture
Describes the architecture that actually exists:
- applications and services;
- major modules;
- data flow and integrations;
- technologies in use;
- deployment or runtime boundaries;
- important architectural constraints.
It should not replace the current system with an ideal architecture unless the document explicitly labels that as a proposal.
Capability baseline
Records what the software can currently do, what is limited and what is only planned.
A useful baseline distinguishes:
- implemented and evidenced capability;
- implemented with known limitations;
- unavailable capability;
- proposed or planned capability;
- uncertain capability requiring validation.
This prevents filenames, mockups or roadmap text from being mistaken for working features.
Project rules
Captures repository-specific engineering rules that an agent must follow.
Examples include:
- preservation-first expectations;
- local architecture and naming conventions;
- required reuse of utilities, guards and services;
- prohibited dependency or infrastructure changes;
- testing expectations;
- handling of generated files;
- Git safety and review boundaries.
These rules should be concise and project-specific. General TCAF instructions remain in the framework runtime.
AI workflow
Explains how AI-assisted work is transported and reviewed in the project.
It may identify:
- active adapter or supported tools;
- review gates;
- how contracts are approved;
- who runs manual checks;
- how developer edits are preserved;
- whether commits or tracker updates require separate approval;
- tool-specific limitations.
Task naming or task-source rules
Defines how tasks are identified and where authoritative work comes from.
It may describe backlog identifiers, issue references, direct-request conventions and how follow-up tasks are recorded.
Project manifest
Maps canonical roles to actual project paths and operational facts.
A manifest can record:
- application roots;
- frontend, backend and shared paths;
- canonical documents;
- task source;
- relevant test, typecheck or build commands;
- unavailable commands;
- adapter or workflow notes;
- project-specific target rules.
The manifest should reflect existing paths and tools, not desired ones.
Existing documents should be reused
Adoption begins by observing what is already present.
When an existing document is authoritative and adequate, the manifest should reference it. TCAF should create a new canonical document only when the required role is missing, fragmented or unsafe to infer from existing sources.
Do not rewrite historical documents merely to normalize formatting.
Documents are evidence, not decoration
A generated document is not correct because it is detailed. The developer must review whether it represents the project truthfully.
During adoption review, check:
- Do listed paths exist?
- Do commands actually exist and run in the stated context?
- Does architecture describe the current system?
- Are planned features separated from implemented ones?
- Are limitations and unknowns visible?
- Is the official task source correct?
- Were existing documents and developer edits preserved?
- Did adoption avoid changing application code?
Structural validation can confirm the document roles and paths satisfy the schema. It cannot prove every sentence is factually correct.
Keep current state and desired state separate
Many project documents mix what exists with what the team wants to build. TCAF should label the distinction clearly.
Useful categories include:
- current state;
- desired state;
- confirmed decision;
- proposal;
- open question;
- historical context.
This is especially important during greenfield bootstrap and when planning from an analysis or roadmap.
Updating project documents
Implementation does not automatically authorize documentation updates.
After the developer accepts work, a reconciliation step may update:
- capability baseline;
- backlog or issue status;
- architecture when a real architectural change was accepted;
- project manifest when paths or commands changed;
- project rules when a new rule was explicitly adopted.
The update should describe accepted reality. It should not mark unrelated work complete or rewrite history.
Documents and model independence
Because the project evidence is stored in ordinary files or declared external sources, a new model or tool can resume by inspecting the same state.
This reduces dependence on:
- private chat memory;
- one vendor’s rules format;
- one editor workspace;
- one agent’s previous summary;
- assumptions reconstructed from code alone.
Model independence is therefore not only an adapter feature. It depends on maintaining durable, truthful project evidence.
When a project uses a lighter mode
Small or existing projects may not need a large documentation set. TCAF can map existing sources and create only the minimum missing evidence needed for safe work.
Minimum-first still requires enough information to answer:
- What is the target?
- What currently exists?
- Which rules must be preserved?
- Where does work come from?
- How is the result verified and reviewed?
The goal is not documentation volume. The goal is reliable continuity.