Private
Public Access
docs: agent workflow docs + regular docs (v2.3 surfacing)
Per user request 'use your remaining context to update agent workflow
docs and then regular docs based on what was discussed in this report',
this commit creates/updates 15 files derived from the v2.3 nagent
review (the 12 new nagent additions + the 4 memory dimensions
reframing + the cache strategy + the RAG discipline + the knowledge
harvest pattern).
Agent workflow docs (4 files):
- AGENTS.md (UPDATE): add @import line to canonical DOD + 'Code
Styleguides' section pointing to the 6 new styleguides + new
'Human-Facing Documentation' section pointing to ./docs/AGENTS.md
- conductor/workflow.md (UPDATE): new section 'Additions (2026-06-12)
- the 12 patterns from the latest nagent corpus' with TDD
protocols for knowledge harvest, cache ordering, compaction, RAG
discipline
- conductor/product-guidelines.md (UPDATE): new sections 'Memory
Dimensions (added 2026-06-12)' + 'See Also - Updated' with the
6-styleguide catalog
- docs/AGENTS.md (NEW): the agent-facing mirror of docs/Readme.md
(per the nagent CLAUDE.md pattern). 10 sections + the per-tier
reading path + the 4 memory dimensions + the caching strategy +
the knowledge harvest + the RAG discipline + the feature flags
Regular docs (11 files):
- 6 new styleguides (the convention catalog):
* data_oriented_design.md: the canonical DOD reference (Tier
0/1/2; 3 defaults to reject; 8 core defaults; 7-question
simplification pass; 10-question self-check; 4 memory
dimensions in Manual Slop context)
* agent_memory_dimensions.md: the 4 memory dims (curation /
discussion / RAG / knowledge) + when to use each + the
boundaries
* rag_integration_discipline.md: the conservative-RAG rule
(opt-in, complement, provenance, no mutation, feature-gated,
graceful failure)
* cache_friendly_context.md: stable-to-volatile context
ordering + the cache TTL GUI contract + the byte-comparison
test
* knowledge_artifacts.md: the knowledge harvest pattern
(category files, provenance, sha256 ledger, digest
regeneration, 'delete to turn off')
* feature_flags.md: file presence vs config flags vs CLI flags
- 3 new project docs (the cross-cutting guides):
* guide_agent_memory_dimensions.md: the cross-cutting guide on
the 4 dims + the decision tree
* guide_caching_strategy.md: caching across providers +
stable-to-volatile ordering + cache TTL GUI + the byte-
comparison test + the 5th provider (claude-code)
* guide_knowledge_curation.md: the knowledge memory guide (4th
dim) + the 5 category files + per-file notes + the digest +
the ledger + the harvest workflow
- 2 existing doc updates:
* guide_mma.md: new sections 'Delegation as context management'
+ 'The 4 memory dimensions (the MMA scope)'
* guide_ai_client.md: new section 'Cache strategy and the 12-
layer model' + the 5th provider (claude-code)
All files use the same style as the v2.3 review (the user's preferred
format): 7-column tables, no JSON, SSDL shape tags, forth/array
notation, file:line citations, ASCII sketches where useful. The
human Readme files (Readme.md, docs/Readme.md) are NOT modified
(per repeated user instruction).
The 5th provider (claude-code) is documented in guide_ai_client.md
+ the data_oriented_design.md references the nagent pattern as the
source of the canonical rules.
The cross-references are bidirectional: the 6 styleguides reference
the 3 project docs; the 3 project docs reference the 6 styleguides;
the 2 doc updates reference both; AGENTS.md + ./docs/AGENTS.md
provide the entry points.
This commit is contained in:
@@ -111,3 +111,43 @@ The product guidelines are best understood alongside the per-source-file guides
|
||||
- **[docs/guide_models.md](../docs/guide_models.md):** §"Design Principles" + §"SDM Tags" — centralized registry, pydantic validation, `[C: ...]` / `[M: ...]` tags in docstrings.
|
||||
- **[docs/guide_testing.md](../docs/guide_testing.md):** §"Structural Testing Contract" — Ban on Arbitrary Core Mocking, `live_gui` Standard, Artifact Isolation.
|
||||
- **[code_styleguides/config_state_owner.md](code_styleguides/config_state_owner.md):** Config I/O state ownership — `AppController` is the single source of truth; direct calls to `models.save_config`/`models.load_config` in `src/` are forbidden (enforced by `scripts/audit_no_models_config_io.py`).
|
||||
## Memory Dimensions (added 2026-06-12)
|
||||
|
||||
The conversation data has 4 distinct memory dimensions. Features touch 1-2 typically; some touch 3. The dimensions are not interchangeable.
|
||||
|
||||
| Dim | Where | What it stores | User-editable | Status |
|
||||
|---|---|---|---|---|
|
||||
| Curation | `FileItem` + `ContextPreset` | *How to render a file* | Structural File Editor | Existing, strong |
|
||||
| Discussion | `disc_entries` + branching + UISnapshot | *What was said* | GUI `[Edit]` mode; undo/redo | Existing, strong |
|
||||
| RAG | `src/rag_engine.py` (ChromaDB) | *Semantic fingerprints* | (opaque) | Opt-in |
|
||||
| Knowledge | `~/.manual_slop/knowledge/*.md` + per-file + digest | *Durable learnings* | Plain markdown | Proposed (Candidate 8) |
|
||||
|
||||
**The product decision.** When scoping a new feature, identify which dimension(s) the feature touches. Pick the matching dimension; don't reach for the wrong shape. The full cross-cutting guide is `docs/guide_agent_memory_dimensions.md`. The canonical styleguide is `conductor/code_styleguides/agent_memory_dimensions.md`.
|
||||
|
||||
**The 6 design rules (the product implications).**
|
||||
|
||||
1. **Curation is structural.** Per-file schema; AST-aware; user-edited. Not conversational.
|
||||
2. **Discussion is conversational.** Per-discussion, multi-turn. Not per-file. Not semantic.
|
||||
3. **RAG is opt-in, fuzzy, semantic.** Default-off in new projects. Complements; never replaces. Provenance required. No mutation.
|
||||
4. **Knowledge is durable, user-editable, provenance-aware.** The category files are the source of truth; the digest is a projection. "Delete to turn off": `rm digest.md`.
|
||||
5. **Cache hits only on the stable prefix** (layers 1-7 of the 12-layer model). The volatile suffix (layers 8-12) is never cached.
|
||||
6. **Feature flags are data, not config.** File presence ("delete to turn off") for side artifacts; config flags for persistent preferences; CLI flags for one-shot overrides.
|
||||
|
||||
## See Also — Updated (2026-06-12)
|
||||
|
||||
The canonical styleguide catalog (per the nagent_review v2.3 + intent_dsl_survey cross-references):
|
||||
|
||||
- **[conductor/code_styleguides/data_oriented_design.md](code_styleguides/data_oriented_design.md)** — The canonical DOD reference (Tier 0/1/2; 3 defaults to reject; 7-question simplification pass; 10-question self-check)
|
||||
- **[conductor/code_styleguides/agent_memory_dimensions.md](code_styleguides/agent_memory_dimensions.md)** — The 4 memory dimensions and when to use each
|
||||
- **[conductor/code_styleguides/rag_integration_discipline.md](code_styleguides/rag_integration_discipline.md)** — The conservative-RAG rule
|
||||
- **[conductor/code_styleguides/cache_friendly_context.md](code_styleguides/cache_friendly_context.md)** — Stable-to-volatile context ordering + the cache TTL GUI contract
|
||||
- **[conductor/code_styleguides/knowledge_artifacts.md](code_styleguides/knowledge_artifacts.md)** — The knowledge harvest pattern
|
||||
- **[conductor/code_styleguides/feature_flags.md](code_styleguides/feature_flags.md)** — File presence vs config flags vs CLI flags
|
||||
|
||||
And the user-facing deep-dives (the cross-cutting guides):
|
||||
|
||||
- **[docs/guide_agent_memory_dimensions.md](../docs/guide_agent_memory_dimensions.md)** — Cross-cutting: the 4 memory dimensions
|
||||
- **[docs/guide_knowledge_curation.md](../docs/guide_knowledge_curation.md)** — The knowledge memory guide (4th dim)
|
||||
- **[docs/guide_caching_strategy.md](../docs/guide_caching_strategy.md)** — Caching across providers
|
||||
- **[./docs/AGENTS.md](../docs/AGENTS.md)** — The agent-facing mirror of `docs/Readme.md`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user