From 260b9b27e998ebb8dee5fabe076615eec5aadfed Mon Sep 17 00:00:00 2001 From: Bernd Worsch Date: Wed, 18 Mar 2026 23:33:14 +0000 Subject: [PATCH] feat(agency): add session protocols to agents and memory field to schema - CONTRIBUTING.md: add Session Start/Close protocol reference with YAML frontmatter schema (including new memory: enabled|disabled field) - agents: add ## Session Start / ## Session Close blocks to project-management, tdd-workflow, requirements-engineering, scope-analyst - registry.py: add AgentCategory.META; add memory field to AgentDefinition (parsed from frontmatter, default None = enabled); add coach/meta keyword detection and sys-medic/medic to infrastructure detection WP-0002 T09, T10, T11 done. Co-Authored-By: Claude Sonnet 4.6 --- CONTRIBUTING.md | 34 +++++++++++++++++++ agents/agent-project-management.md | 14 ++++++++ agents/agent-requirements-engineering.md | 15 ++++++++ agents/agent-scope-analyst.md | 14 ++++++++ agents/agent-tdd-workflow.md | 15 ++++++++ src/kaizen_agentic/registry.py | 9 ++++- ...kaizen-agentic-WP-0002-agency-framework.md | 6 ++-- 7 files changed, 103 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8be06a5..07e6739 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,6 +71,40 @@ For contributing new agents or improving existing ones: - Define explicit scope and authority boundaries - Follow existing agent patterns in `agents/` directory +#### YAML frontmatter schema + +```yaml +--- +name: +description: +category: testing | quality | process | infrastructure | release | docs | support | meta +memory: enabled # optional; default enabled. Set to disabled for stateless utility agents +--- +``` + +#### Session-start protocol (for session-bound agents) + +Agents that do ongoing work across sessions should include a session-start block: + +1. Check for `.kaizen/agents//memory.md` in the project root +2. If present, read it and acknowledge relevant context in the opening brief +3. Optionally invoke `kaizen-agentic memory brief ` for cross-agent orientation + +Include this block in the agent prompt under a `## Session Start` heading. + +#### Session-close protocol (for session-bound agents) + +At the end of each session the agent should: + +1. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` as needed +2. Append one line to `## Session Log` (format: `YYYY-MM-DD · · `) +3. Bump `last_updated` and `session_count` in the frontmatter + +Include this block in the agent prompt under a `## Session Close` heading. + +Agents for which session state is irrelevant (e.g. `keepaTodofile`, `keepaChangelog`) +should set `memory: disabled` in their frontmatter and omit these sections. + ## Types of Contributions We welcome various types of contributions: diff --git a/agents/agent-project-management.md b/agents/agent-project-management.md index eb2e109..b404e81 100644 --- a/agents/agent-project-management.md +++ b/agents/agent-project-management.md @@ -181,3 +181,17 @@ Generate issues for relevantly expensive or risky stuff and in direct feedback w Controled in-scope-work does not need the costly issue capture, refinement, selection roundtrip. Remember: Your role is to help developers quickly understand "where we are" and "what should we do next" when picking up work on the MarkiTect project, and to ensure proper session wrap-up for continuity. + +--- + +## Session Start + +1. Check for `.kaizen/agents/project-management/memory.md` in the project root. +2. If present, read it and surface relevant context (last session summary, open threads, watch points) in your opening brief. +3. If absent, offer to initialise with `kaizen-agentic memory init project-management`. + +## Session Close + +1. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` based on this session. +2. Append one line to `## Session Log`: `YYYY-MM-DD · · `. +3. Bump `last_updated` to today and increment `session_count`. diff --git a/agents/agent-requirements-engineering.md b/agents/agent-requirements-engineering.md index ecfae0e..0a337bd 100644 --- a/agents/agent-requirements-engineering.md +++ b/agents/agent-requirements-engineering.md @@ -484,4 +484,19 @@ The agent directly addresses the root causes: --- +## Session Start + +1. Check for `.kaizen/agents/requirements-engineering/memory.md` in the project root. +2. If present, read it — pay attention to `## Watch Points` (recurring interface pitfalls) and `## Accumulated Findings` (known domain model patterns). +3. If absent, offer to initialise with `kaizen-agentic memory init requirements-engineering`. + +## Session Close + +1. Update `## Accumulated Findings` with any new interface contracts, domain model patterns, or mock alignment lessons from this session. +2. Update `## Watch Points` with any newly discovered incompatibility risks. +3. Append one line to `## Session Log`: `YYYY-MM-DD · · `. +4. Bump `last_updated` to today and increment `session_count`. + +--- + *This agent provides systematic foundation analysis and interface contract verification based on lessons learned from Issue #59 to prevent compatibility issues and ensure solid architectural foundations before implementation.* \ No newline at end of file diff --git a/agents/agent-scope-analyst.md b/agents/agent-scope-analyst.md index b8d491c..ec4c703 100644 --- a/agents/agent-scope-analyst.md +++ b/agents/agent-scope-analyst.md @@ -353,3 +353,17 @@ A good result allows a reader to quickly answer: - Is it overlapping something else? If those are clear, the task is successful. + +--- + +## Session Start + +1. Check for `.kaizen/agents/scope-analyst/memory.md` in the project root. +2. If present, read it — prior SCOPE.md analyses and boundary decisions may be useful context. +3. If absent, this is typically fine for a first-run analysis. + +## Session Close + +1. If a SCOPE.md was produced or meaningfully revised, note the key boundary decisions in `## Accumulated Findings`. +2. Append one line to `## Session Log`: `YYYY-MM-DD · · `. +3. Bump `last_updated` to today and increment `session_count`. diff --git a/agents/agent-tdd-workflow.md b/agents/agent-tdd-workflow.md index f3cce24..e7591e3 100644 --- a/agents/agent-tdd-workflow.md +++ b/agents/agent-tdd-workflow.md @@ -357,3 +357,18 @@ Remember: The goal is to build software incrementally using the proven TDD8 cycl **ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH** The comprehensive 8-step development methodology that transforms requirements into production-ready, well-tested, documented functionality while maintaining code quality and project momentum through intelligent sidequest management. + +--- + +## Session Start + +1. Check for `.kaizen/agents/tdd-workflow/memory.md` in the project root. +2. If present, read it — pay attention to `## Watch Points` (recurring test pitfalls) and `## What Worked` (effective patterns for this project). +3. If absent, offer to initialise with `kaizen-agentic memory init tdd-workflow`. + +## Session Close + +1. Update `## Accumulated Findings` with any new TDD patterns or recurring failure modes observed. +2. Update `## What Worked` and `## Watch Points` as needed. +3. Append one line to `## Session Log`: `YYYY-MM-DD · · `. +4. Bump `last_updated` to today and increment `session_count`. diff --git a/src/kaizen_agentic/registry.py b/src/kaizen_agentic/registry.py index 4479ba5..93d9d22 100644 --- a/src/kaizen_agentic/registry.py +++ b/src/kaizen_agentic/registry.py @@ -17,6 +17,7 @@ class AgentCategory(Enum): INFRASTRUCTURE = "infrastructure" TESTING = "testing" DOCUMENTATION = "documentation" + META = "meta" @dataclass @@ -29,6 +30,7 @@ class AgentDefinition: category: AgentCategory dependencies: Set[str] model: Optional[str] = None + memory: Optional[str] = None # "enabled" (default) | "disabled" @classmethod def from_file(cls, file_path: Path) -> "AgentDefinition": @@ -56,6 +58,7 @@ class AgentDefinition: category=category, dependencies=dependencies, model=frontmatter.get("model"), + memory=frontmatter.get("memory"), ) @staticmethod @@ -127,8 +130,12 @@ class AgentDefinition: if any(keyword in name_lower for keyword in ["documentation", "claude"]): return AgentCategory.DOCUMENTATION + # Meta agents (coaching, cross-agent orchestration) + if any(keyword in name_lower for keyword in ["coach", "meta"]): + return AgentCategory.META + # Infrastructure agents - if any(keyword in name_lower for keyword in ["setup", "repository", "tooling"]): + if any(keyword in name_lower for keyword in ["setup", "repository", "tooling", "sys-medic", "medic"]): return AgentCategory.INFRASTRUCTURE # Development process agents diff --git a/workplans/kaizen-agentic-WP-0002-agency-framework.md b/workplans/kaizen-agentic-WP-0002-agency-framework.md index 6126531..f388e61 100644 --- a/workplans/kaizen-agentic-WP-0002-agency-framework.md +++ b/workplans/kaizen-agentic-WP-0002-agency-framework.md @@ -140,14 +140,14 @@ kaizen-agentic memory clear # Wipe memory (with confirmation) **Memory convention and tooling** - [x] T07 — Write ADR: project memory convention (file location, structure, lifecycle) - [x] T08 — Implement `memory` CLI command group (show, init, brief, clear) -- [ ] T09 — Add session-start and session-close protocol sections to agent template / +- [x] T09 — Add session-start and session-close protocol sections to agent template / contributor guide **Agent definition updates** -- [ ] T10 — Add session-start and session-close protocol blocks to all existing +- [x] T10 — Add session-start and session-close protocol blocks to all existing agents that do session-bound work (project-management, tdd-workflow, requirements-engineering, scope-analyst, sys-medic) -- [ ] T11 — Update agent YAML frontmatter schema to include optional +- [x] T11 — Update agent YAML frontmatter schema to include optional `memory: enabled|disabled` field (default: enabled) **Coaching meta-agent**