cristiano.hoshikawa/agent_platform_oci
1
2
Fork 0
mirror of https://github.com/hoshikawa2/agent_platform_oci.git synced 2026-09-07 10:13:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation organization

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-08-27 10:28:23 -03:00
parent 472d44074c
commit 42ab000c7b
15 changed files with 6548 additions and 7060 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/developer/en/VALIDATION_README_ALIGNMENT.md
View File

@@ -1,27 +1,39 @@
### Documentation Alignment Validation
### Purpose
### Goal
Record how this version's documentation was reorganized and which sources developers should trust.
Record how the documentation for this version was reorganized and which sources developers should use.
### Structural decision
The root `README_en.md` / `README.md` is the **single end-to-end main tutorial**.
The root `README_en.md` is the **single end-to-end main tutorial**.
The former `01_architecture_and_agent_development.md` was removed because it repeated much of the README but not all of it. That created ambiguity: two documents appeared to teach the same workflow while one was partial.
The former `01_architecture_and_agent_development.md` was removed because it repeated a large part of the README, but not all of it. This created ambiguity: two documents appeared to teach the same thing, but one was partial.
The new structure replaces it with `01_architecture_and_concepts.md`, containing only architecture, concepts, responsibilities and extension criteria.
The new structure replaces that file with `01_architecture_and_concepts.md`, which contains only architecture, concepts, responsibilities, and extension criteria.
### `README_old2.md` validation
### Validation of `README_old2.md`
`Documentacao/README_old2.md` remains useful as historical material but is not the primary development source.
`Documentacao/README_old2.md` remains useful as history, but it is not the primary source for development.
Later evolution found in the current README/code includes SPECs/SDDs, richer `llm_profiles.yaml` guidance, Channel Gateway, canonical contracts, current memory composition, `RuntimeContext`, tool helpers, transaction helpers, direct MCP responses and gateway/RAG/memory/policy evolution.
Later evolutions were found in the current README and code, including:
### Main README correction
- SPECs/SDDs;
- more complete `llm_profiles.yaml` configuration;
- Channel Gateway and canonical contracts;
- `memory` and `summary_memory` in the current agent lifecycle;
- `prepare_memory_context()` and `build_messages()`;
- `RuntimeContext`;
- `normalize_tools_by_intent()`;
- `build_tool_arguments()`;
- `execute_tools_for_intent()`;
- transaction-state helpers;
- direct MCP responses;
- evolution of gateways, RAG, memory, and policies.
The generated package corrects this typo:
### Correction applied to the main README
The following typo was corrected in the generated package:
```python
from app.agents.financeiro_agent import FinanceirotAgent
@@ -33,7 +45,7 @@ to:
from app.agents.financeiro_agent import FinanceiroAgent
```
The correct class is confirmed by code and the rest of the documentation.
The correct class is confirmed by the code and the rest of the documentation.
### APIs confirmed in the current implementation
@@ -52,7 +64,7 @@ AgentRuntimeMixin.build_direct_mcp_answer()
### Trust order
1. version code;
1. code for the version;
2. main README for the same version;
3. SPECs/SDDs;
4. specialized manuals;
@@ -63,9 +75,9 @@ AgentRuntimeMixin.build_direct_mcp_answer()
A feature evolution should update:
1. the main README **only when the normal development path changes**;
2. the feature's specialized manual with technical detail, behavior, configuration and troubleshooting;
3. the SPEC when a contract changes;
4. a release note when historical recording is needed.
1. the main README, **only if it changes the normal development path**;
2. the feature's specialized manual, with technical details, behavior, configuration, and troubleshooting;
3. the SPEC, when there is a contract change;
4. the release note, when it is necessary to record the historical change.
Do not create another “main manual” for a feature. Do not keep functional corrections permanently only in release notes.
Do not create a new “main manual” for a feature. Do not keep functional fixes permanently only in release notes.