ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

docs: agent workflow docs + regular docs (v2.3 surfacing)

Browse Source 
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:
Edward R. Gonzalez
2026-06-12 13:50:40 -04:00
parent d604a63e1f
commit 35c6cca134
15 changed files with 3460 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guide_mma.md
+70
View File
@@ -593,3 +593,73 @@ See [guide_workspace_profiles.md](guide_workspace_profiles.md) (placeholder; wri
- **[guide_discussions.md](guide_discussions.md)** — The Discussion system; MMA worker prompts are built from the active discussion
- **[conductor/tracks/nagent_review_20260608/report.md §9](../conductor/tracks/nagent_review_20260608/report.md)** — Deep-dive on the MMA sub-conversation pattern vs nagent's `<nagent-conversation>` tag; **the highest-priority future-track is to extract MMA's `run_worker_lifecycle` into a reusable `SubConversationRunner` for 1:1 discussions** (per user-flagged want)
- **[conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md §3 and §10](../conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md)** — Actionable patterns for the SubConversationRunner; the design constraint that sub-agents return a *concise artifact* (not a full transcript) is baked into the recommendation
## Addition (2026-06-12) — Delegation as context management, not parallelism
The nagent review (v2.3, §3.12) reframed delegation with a new lens: **the reason to spawn a sub-conversation is to keep the parent's context clean. The fact that the child runs concurrently (sometimes) is incidental.** Per nagent's `bin/nagent:730`: *"Hand off when noisy: if this conversation is mostly stale tool output, distill goal/state/decisions into a sub-conversation prompt, delegate the rest, and tell your caller about the handoff. Never rewrite your own conversation file while running."*
The reframing table:
| Long-lived agent abstractions | Disposable workers |
|---|---|
| Identity is central | Output artifact is central |
| Shared context gets noisy | Child context is isolated |
| Parent absorbs all exploration | Parent gets a concise result |
| Delegation implies personality | Delegation is context management |
### How this applies to MMA
MMA already does this implicitly:
- `src/multi_agent_conductor.py:_spawn_worker` runs each MMA worker as a fresh subprocess with `ai_client.reset_session()` (Context Amnesia)
- The worker returns a `Result[TaskOutput, ErrorInfo]` to the parent (the `ConductorEngine`)
- The parent's `disc_entries` doesn't accumulate the worker's intermediate reads/shell calls
### The product implication for 1:1 discussions
The 1:1 discussion path has no sub-agent primitive today. The user types a prompt, the AI responds, the loop continues. If the user wants the AI to "investigate this file" or "look up this API," the answer has to come from the same conversation.
**The product decision (user-flagged want).** Add a `SubConversationRunner` for 1:1 discussions. Reuse MMA's `mma_exec.py` as the subprocess template. The sub-agent returns a concise artifact (the sub-agent's response) + token usage + exit code. The App inserts the result into the active discussion as a "User" role entry. The next LLM call sees it.
### The SubConversationRunner shape (per the v2.3 §10.2 spec)
```python
@dataclass
class SubConversationResult:
artifact: str # the sub-agent's response
tokens_in: int
tokens_out: int
exit_code: int
errors: list[ErrorInfo] # from the data_oriented_error_handling convention
class SubConversationRunner:
async def spawn(self, prompt: str, *, allowed_tools: list[str] = None, ...) -> SubConversationResult:
# Reuses mma_exec.py as the subprocess template
# Returns the child's <nagent-response> content + token usage
...
```
**The design contract.** The sub-agent's return type is `SubConversationResult`, not the full conversation. The parent gets a concise artifact, not a transcript. The sub-conversation folder is auto-archived after 7 days (consistent with `log_pruner.py`).
## Addition (2026-06-12) — The 4 memory dimensions (the MMA scope)
The MMA tracks operate on `disc_entries` (the Discussion dim) and `manual_slop.toml` (the project config). They do NOT typically touch the Curation dim (per-track ticket specs) or the Knowledge dim (per-track session reports). They MAY touch the RAG dim if the ticket scope includes RAG integration (declared in `metadata.json`).
**The MMA scope, in the 4-dim framework:**
| Dim | MMA scope? | Why |
|---|---|---|
| Curation | per-ticket only | A ticket might add a `FileItem` if the feature touches curation; not a default |
| Discussion | YES (the work) | The MMA worker's prompt is built from the active discussion |
| RAG | per-ticket only | A ticket might use RAG if the feature includes RAG; declared in `metadata.json` |
| Knowledge | per-track only | The track's session synthesis (in `docs/reports/`) is the durable knowledge |
**The implication for MMA workers.** MMA workers are given Context Amnesia (`ai_client.reset_session()` at the start of `run_worker_lifecycle`). The worker sees:
- The ticket's prompt (the scoped work)
- The `manual_slop.toml [agent.context_files]` (the project context)
- The `FileItem` set per the ticket's scope
- *Optionally* a `knowledge/digest.md` excerpt (if the ticket scope includes knowledge injection)
The worker does NOT see:
- The full `disc_entries` history (per the Context Amnesia pattern)
- The full `~/.manual_slop/knowledge/` (only the digest excerpt)
- The RAG index (unless the ticket scope explicitly opts in)