ed
77141363bc
- v2 (nagent_review_v2_20260612.md, ~68KB): first delta report on the 8 new
nagent commits between 2026-06-08 and 2026-06-12. Introduces 5 new
future-track candidates (11-15): knowledge harvest, stable-to-volatile
context ordering for caching, conversation compaction, project context
files, save-with-graceful-summary-failure. Notes heavy RAG emphasis as
the comparison frame for knowledge harvest (later corrected in v2.1).
- v2.1 (nagent_review_v2_1_20260612.md, ~59KB): user-driven revision of v2.
Five corrections applied:
1. CLAUDE.md -> AGENTS.md swap (Manual Slop has AGENTS.md, not CLAUDE.md)
2. Reframed Candidate 11 from 'RAG alternative' to 'third memory
dimension' (curation + discussion + RAG + knowledge)
3. Cache TTL GUI controls added (sub-candidate 12b) per user request
4. RAG integration discipline added (new sub-section 2.10) per user's
'be conservative' rule
5. v2 preserved as draft; v2.1 is non-destructive new file
v2.1 also proposes new agent-facing artifacts (canonical DOD file,
AGENTS.md update, new ./docs/AGENTS.md) and 8 new styleguides/docs.
v2.1 source-citations grounded in 18 nagent source files read in full.
- state.toml and metadata.json updated with v2.1 tasks and a v2.1_review
block; v1 artifacts preserved per original user instruction.
Pending: style preferences (table-based, forth/array-like, not JSON) and
the user's upcoming intent-based-scripting-languages report.
234 lines
13 KiB
JSON
234 lines
13 KiB
JSON
{
|
|
"track_id": "nagent_review_20260608",
|
|
"name": "nagent Review (Mike Acton's data-oriented LLM agent reference)",
|
|
"initialized": "2026-06-08",
|
|
"owner": "tier2-tech-lead",
|
|
"priority": "medium",
|
|
"status": "active",
|
|
"type": "reference + analysis + future-track scoping",
|
|
"scope": {
|
|
"new_files": [
|
|
"conductor/tracks/nagent_review_20260608/spec.md",
|
|
"conductor/tracks/nagent_review_20260608/report.md",
|
|
"conductor/tracks/nagent_review_20260608/comparison_table.md",
|
|
"conductor/tracks/nagent_review_20260608/decisions.md",
|
|
"conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md"
|
|
],
|
|
"modified_files": [],
|
|
"external_resources": [
|
|
"nagent README: https://github.com/macton/nagent/blob/main/README.md",
|
|
"nagent source: https://github.com/macton/nagent (all 11 source files read in full)"
|
|
]
|
|
},
|
|
"blocked_by": [],
|
|
"blocks": [
|
|
"sub_conversation_runner_app_1to1_20260608_PLACEHOLDER",
|
|
"rag_pre_staging_sub_convo_20260608_PLACEHOLDER",
|
|
"llm_client_stateless_class_20260608_PLACEHOLDER",
|
|
"intent_dsl_for_meta_tooling_20260608_PLACEHOLDER",
|
|
"git_history_injection_20260608_PLACEHOLDER",
|
|
"per_file_conversation_log_20260608_PLACEHOLDER",
|
|
"py_coedited_files_tool_20260608_PLACEHOLDER",
|
|
"ts_c_coedited_files_tool_20260608_PLACEHOLDER",
|
|
"split_patch_lib_20260608_PLACEHOLDER",
|
|
"raw_transcript_persistence_per_take_20260608_PLACEHOLDER"
|
|
],
|
|
"estimated_phases": 0,
|
|
"spec": "spec.md",
|
|
"plan": null,
|
|
"v2_review": {
|
|
"date": "2026-06-12",
|
|
"report": "nagent_review_v2_20260612.md",
|
|
"nagent_commits_reviewed": [
|
|
"2c3c78b (2026-06-11 03:32:50) Add conversation compaction and restore initial context on load",
|
|
"67a3ea5 (2026-06-11 23:09:57) Add knowledge harvest, tag parser, and claude-code provider",
|
|
"5e269ca (2026-06-12 00:17:34) Add project context, prompt caching, and conversation direction",
|
|
"ee72cb4 (2026-06-11 23:10:12) Rewrite README prompt around a teaching arc and regenerate README"
|
|
],
|
|
"nagent_pushed_at_review": "2026-06-12T00:25:52Z",
|
|
"nagent_head_at_review": "eb6be32a",
|
|
"new_patterns_identified": [
|
|
"Knowledge harvest (nagent-gc) - new Candidate 11, HIGH priority",
|
|
"Stable-to-volatile context ordering for prompt caching - new Candidate 12, MEDIUM priority",
|
|
"Conversation compaction (--compact) - new Candidate 13, MEDIUM priority",
|
|
"Project context files (context.yaml) - new Candidate 14, LOW priority",
|
|
"Save-with-graceful-summary-failure - new Candidate 15, TBD pending source read",
|
|
"claude-code provider (subscription auth) - existing Gemini CLI analog, no new track",
|
|
"Per-file knowledge notes (knowledge/files/{file_id}.md) - bundle with Candidate 11",
|
|
"Delete-to-turn-off feature flags - design pattern, not a track",
|
|
"Delegation reframed as context management (not parallelism) - design pattern, not a track"
|
|
],
|
|
"v1_artifacts_staleness": {
|
|
"report_md": "9 of 16 sections need updates; new sub-sections on knowledge harvest, compaction, caching, project context, claude-code",
|
|
"comparison_table_md": "4 existing rows need updates; 4 new rows needed (knowledge harvest, prompt caching strategy, compaction, per-file notes)",
|
|
"decisions_md": "4 existing candidates need updates; 5 new candidates (11-15) needed",
|
|
"nagent_takeaways_20260608_md": "6 of 10 takeaways need updates; 3 new takeaways needed",
|
|
"spec_md": "Still correct; no change needed",
|
|
"state_toml_and_metadata_json": "Updated to reflect v2 review (this file)"
|
|
},
|
|
"v1_artifacts_preserved": "All v1 files preserved per user instruction ('don't delete the old report'). v2 is additive.",
|
|
"user_signal_recorded_for_v2": "User has not yet seen v2 findings; primary surface is Candidate 11 (knowledge harvest) and verification of Candidate 15 (save-with-graceful-failure).",
|
|
"next_steps_recommended": [
|
|
"User review of v2 report",
|
|
"If user approves: update v1 decisions.md / comparison_table.md / nagent_takeaways_20260608.md to integrate v2 findings",
|
|
"Update agent workflow docs (AGENTS.md, conductor/workflow.md, conductor/product-guidelines.md) with v2 design principles",
|
|
"Tier 2 source-read: verify 8 items in v2 report §8 before any new candidate is scoped",
|
|
"After integration: consider whether to mark v1 track as completed (preserved in archive/) or leave active for further iterations"
|
|
]
|
|
},
|
|
"v2_1_review": {
|
|
"date": "2026-06-12",
|
|
"report": "nagent_review_v2_1_20260612.md",
|
|
"status": "v2.1 is the user-revised version; v2 is preserved as the draft per user instruction",
|
|
"user_corrections_applied": [
|
|
"CLAUDE.md → AGENTS.md swap throughout (Manual Slop has AGENTS.md, not CLAUDE.md)",
|
|
"Reframed Candidate 11 from 'RAG alternative' to 'third memory dimension' (curation + discussion + RAG + knowledge); removed heavy RAG emphasis",
|
|
"Added new sub-section 2.10 'RAG integration discipline' (conservative RAG wiring; where RAG fits; where it does not)",
|
|
"Expanded Candidate 12 with cache TTL GUI controls (sub-candidate 12b) per user's explicit 'how long the caches are available for (gemini has a limit for example)'",
|
|
"Preserved v2 as the draft (NON-DESTRUCTIVE write to nagent_review_v2_1_20260612.md)",
|
|
"Preserved Readme.md and docs/Readme.md as human-facing; proposed new agent-facing files (AGENTS.md @import update; new ./docs/AGENTS.md) instead"
|
|
],
|
|
"nagent_source_reads_in_full": [
|
|
"bin/nagent (2524 lines) — main loop, build_initial_context at 606-745, conversation_cache_boundaries at 970-987, call_llm at 990-1019, compact_conversation at 1975-2019, --save-conversation at 2147, --branch-conversation at 2157, --compact at 2178",
|
|
"bin/helpers/nagent_gc_lib.py (~700 lines, 27KB) — the knowledge harvest library",
|
|
"bin/helpers/nagent_tags.py — the new explicit tag parser (replaces regex)",
|
|
"bin/helpers/nagent_llm.py — 5+1 providers, cache_prefix_blocks, claude-code provider",
|
|
"bin/nagent-gc — the GC CLI wrapper",
|
|
"prompts/compact-conversation.md — compaction guidance prompt",
|
|
"prompts/harvest-conversation.md — strict-JSON harvest prompt",
|
|
"context/data-oriented-design.md (13084 bytes) — the canonical DOD reference (Tier 0/1/2, simplification pass, enforceable deliverables)",
|
|
"CLAUDE.md (5832 bytes) — the agent-facing rules file with @import pattern"
|
|
],
|
|
"new_candidates_proposed": [
|
|
"Candidate 11 REFRAMED (HIGH) — third memory dimension (not RAG alternative)",
|
|
"Candidate 12 EXPANDED (MEDIUM) — 12a stable-to-volatile ordering + 12b cache TTL GUI controls",
|
|
"Candidate 16 NEW (HIGH) — AGENTS.md @import pattern + canonical DOD file (foundation for other styleguides)"
|
|
],
|
|
"new_artifacts_proposed_for_next_turn": {
|
|
"new_agent_facing_files": [
|
|
"conductor/code_styleguides/data_oriented_design.md (NEW canonical DOD file)",
|
|
"AGENTS.md (UPDATE — add @import line)",
|
|
"./docs/AGENTS.md (NEW — agent-facing mirror of docs/Readme.md)"
|
|
],
|
|
"new_styleguides": [
|
|
"conductor/code_styleguides/agent_memory_dimensions.md",
|
|
"conductor/code_styleguides/rag_integration_discipline.md",
|
|
"conductor/code_styleguides/cache_friendly_context.md",
|
|
"conductor/code_styleguides/knowledge_artifacts.md",
|
|
"conductor/code_styleguides/feature_flags.md"
|
|
],
|
|
"new_project_docs": [
|
|
"docs/guide_knowledge_curation.md",
|
|
"docs/guide_caching_strategy.md",
|
|
"docs/guide_agent_memory_dimensions.md"
|
|
],
|
|
"updates_to_existing_workflow_docs": [
|
|
"conductor/workflow.md (TDD protocol additions)",
|
|
"conductor/product-guidelines.md (memory dimensions section)",
|
|
"docs/guide_mma.md (context management framing)",
|
|
"docs/guide_ai_client.md (cache TTL section)"
|
|
]
|
|
},
|
|
"preserved_files_NOT_modified": [
|
|
"nagent_review_v2_20260612.md (v2 draft, per user instruction)",
|
|
"report.md, comparison_table.md, decisions.md, nagent_takeaways_20260608.md (v1 review artifacts)",
|
|
"spec.md, state.toml (original), metadata.json (pre-v2.1)",
|
|
"Readme.md (project root, human-facing)",
|
|
"docs/Readme.md (docs index, human-facing)"
|
|
]
|
|
},
|
|
"nagent_principles_covered": [
|
|
"Durable work, disposable workers",
|
|
"Text in, text out",
|
|
"Conversations are editable state",
|
|
"Visible output protocol",
|
|
"The loop",
|
|
"Per-file memory",
|
|
"Repository history as data",
|
|
"Historical coupling & artifact neighborhoods",
|
|
"Disposable sub-conversations",
|
|
"Controlled writes",
|
|
"Large files as explicit artifacts",
|
|
"Tool discovery",
|
|
"Differences from frameworks",
|
|
"Build your own"
|
|
],
|
|
"manual_slop_features_audited": [
|
|
"Context composition (FileItem + ContextPreset + custom_slices + ast_mask)",
|
|
"Discussion Takes + branching (project_manager.branch_discussion + promote_take)",
|
|
"UI Snapshot history (HistoryManager + UISnapshot)",
|
|
"Personas (Persona + PersonaManager)",
|
|
"RAG (RAGEngine + ChromaDB + summarization)",
|
|
"Multi-provider AI client (ai_client + 5 providers)",
|
|
"MMA conductor (mma_exec.py + ConductorEngine + WorkerPool)",
|
|
"MCP tools (45 tools + 3-layer security)",
|
|
"Hook API (api_hooks + api_hook_client)",
|
|
"GUI App/Controller state delegation"
|
|
],
|
|
"user_corrections_applied": [
|
|
"Editable discussions: PARTIAL -> PARITY (DIFFERENT FOCUS)",
|
|
"Per-file memory: DOMAIN MISMATCH -> MANUAL SLOP IS STRONGER IN CURATION DIMENSION",
|
|
"Sub-conversations: removed 'PARITY stronger' claim; added 'GAP for 1:1 discussions'",
|
|
"RAG: clarified as opt-in, not gap; user wants pre-staging via sub-conversation",
|
|
"Personas: reframed as config bundling (not gap; can opt out via AI settings)",
|
|
"Tool discovery: downgraded to 'intentional, low priority'; user has deferred DSL idea",
|
|
"Editable discussions (second pass): report §3 now enumerates the full per-entry (A1-A7) + discussion-level (B1-B11) + undo/redo (C1-C5) operation matrix. Verdict remains PARITY (DIFFERENT FOCUS) but the gap is more precisely scoped: Manual Slop's editing is more granular at the typed-entry layer; nagent's is deeper at the raw-transcript layer."
|
|
],
|
|
"domain_classification": {
|
|
"Application_domain_pitfalls": [
|
|
"Provider-specific history in process globals",
|
|
"AI client is a stateful singleton with module-level globals",
|
|
"No non-MMA disposable sub-conversations (1:1 gap)",
|
|
"RAG is not 'history as data' (fuzzy vs exact)",
|
|
"Optional raw-transcript persistence (niche)"
|
|
],
|
|
"Meta_Tooling_domain_pitfalls": [
|
|
"No structured output protocol (opaque function calling)",
|
|
"Hard-coded tool discovery"
|
|
],
|
|
"Application_features": [
|
|
"Context composition with FileItem-level curation memory",
|
|
"Discussion Takes + branching (project_manager.branch_discussion + promote_take)",
|
|
"UI Snapshot history (HistoryManager + UISnapshot)",
|
|
"Personas as config bundling",
|
|
"RAG as opt-in semantic search",
|
|
"3-layer MCP security model + Execution Clutch"
|
|
],
|
|
"Meta_Tooling_features_to_borrow": [
|
|
"nagent-style --description self-describing executables",
|
|
"Intent-based DSL for compact tool calls"
|
|
]
|
|
},
|
|
"verification_criteria": [
|
|
"spec.md exists and covers the 14 nagent principles",
|
|
"report.md exists and is the primary deliverable",
|
|
"comparison_table.md exists as flat side-by-side reference",
|
|
"decisions.md exists with 10 future-track candidates",
|
|
"nagent_takeaways_20260608.md exists with 10 actionable patterns (companion to report.md)",
|
|
"Every pitfall is tagged with Application / Meta-Tooling / Both",
|
|
"Pitfall #3 (conversations are editable) verdict is corrected to PARITY (DIFFERENT FOCUS) per user feedback",
|
|
"Pitfall #6 (per-file memory) verdict is corrected to 'Manual Slop is stronger in curation dimension' per user feedback",
|
|
"Pitfall #9 (sub-conversations) verdict notes MMA vs 1:1 distinction per user feedback",
|
|
"Report §3 enumerates the per-entry (A1-A7) + discussion-level (B1-B11) + undo/redo (C1-C5) operation matrix for Manual Slop's editable-discussion system, with file:line citations into gui_2.py and history.py",
|
|
"nagent_takeaways_20260608.md grounds each pattern in actual code with file:line references into both nagent source and Manual Slop source",
|
|
"No code was modified by this track (reference/analysis only)"
|
|
],
|
|
"links": {
|
|
"report": "report.md",
|
|
"comparison_table": "comparison_table.md",
|
|
"decisions": "decisions.md",
|
|
"takeaways": "nagent_takeaways_20260608.md",
|
|
"user_signal_recorded": "User explicitly flagged SubConversationRunner + RAG pre-staging as wants during review",
|
|
"related_tracks": [
|
|
"data_oriented_error_handling_20260606 (Fleury/Acton alignment)",
|
|
"qwen_llama_grok_integration_20260606 (OpenAI-compatible helper)",
|
|
"mcp_architecture_refactor_20260606 (sub-MCP extraction)",
|
|
"data_structure_strengthening_20260606 (type aliases)"
|
|
],
|
|
"external": [
|
|
"https://github.com/macton/nagent (nagent source code)",
|
|
"https://github.com/macton/nagent/blob/main/README.md (nagent README)"
|
|
]
|
|
}
|
|
}
|