8.3 KiB
type, status, updated, tags
| type | status | updated | tags | |||
|---|---|---|---|---|---|---|
| agent-behavior | active | 2026-04-21 |
|
Agent Memory Rules
Goal
Make workspace memory maintenance part of the agent's normal job, not a separate optional workflow.
Default Agent Behavior
For any meaningful prompt, the agent should decide whether the interaction changes project memory.
This applies to:
- direct user prompts
- Mattermost sync results
- translated notes
- standup generation
- manager-update drafting
- debugging discussions
- corrections to previous understanding
The agent should not wait for a separate promotion command when the right update is already clear.
- When editing
project-knowledge/, write as a human engineer maintaining shared project documentation. - Keep agent-operating logic out of
project-knowledge/; store that logic in prompts, commands, skills, agents, oragent-memory/.
Learning Sessions
The agent should support incremental self-learning sessions.
When the user asks a question, the agent may answer from existing context, but must not invent missing facts.
Learning sessions should improve durable project understanding. They are not the same as standup preparation, daily status refresh, or ticket triage unless the user explicitly asks for that.
The agent should:
- say what is known from the workspace
- say what is unclear or not available
- label assumptions and inferences explicitly
- ask a concise clarification question when the missing context materially changes the answer
- focus clarification questions on architecture, process, ownership, debugging patterns, domain concepts, release mechanics, and decision rules
- avoid asking mostly about transient ticket state unless the answer would clarify a durable project rule
- learn from user corrections or confirmations by updating the smallest correct canonical file
- avoid promoting unconfirmed exploration as durable truth
Good learning behavior:
- If the answer is clear from stored context, answer directly and update nothing unless the interaction adds durable context.
- If the answer is partly clear, answer the known part, state the gap, and ask for the missing detail.
- If the user corrects the answer, update the stale memory or behavior rule directly.
- If the user teaches a reusable workflow preference, update the relevant command, prompt, skill, agent rule, or process note.
- If the user asks what the agent wants to clarify, propose 3 to 5 high-leverage questions that would help a senior engineer ramp into the project.
Do not ask for clarification just to avoid work. Ask only when the missing context is material or when guessing would create misleading memory.
Avoid low-value learning-session questions such as:
- whether a specific PR was approved today
- whether a ticket moved columns today
- what the next standup line should be
- temporary sequencing questions that belong in
project-knowledge/01-current/orproject-knowledge/06-daily/
Prefer high-value questions such as:
- what determines ownership between SDK, adapter, feature module, app, and backend configuration
- how release propagation works across SDK, adapter, consuming app, and validation environment
- what invariants define REST vs GraphQL parity
- how authenticated and non-authenticated flows differ operationally
- what evidence is required before classifying an external issue as a regression
What Counts As Memory-Worthy
Capture information automatically when it is:
- project-relevant
- explicit enough to preserve safely
- likely to matter in a future session
- useful for standups, debugging, or supervisor communication
Examples:
- confirmed story creation, points, scope, or priority
- confirmed reproduction constraints
- newly clarified root cause framing
- approved manager guidance that changes work direction
- confirmed version, dependency, or rollout facts tied to current work
- corrections to previously stored project context
- corrections to the agent's answer quality, uncertainty handling, or learning behavior
- repeated named people with stable roles or communication relevance
- repeated named people with multi-channel, multi-year, or high-signal technical/process involvement even when the exact formal role is still unknown
What The Agent Must Do
When new memory-worthy information appears, the agent should:
- decide whether it is daily, current-state, durable, or decision-level context
- update the smallest correct set of files
- correct stale or conflicting existing statements
- answer the user using the refreshed context
Do not ask the user what to promote unless the ambiguity is real and material.
Tooling Self-Maintenance
User corrections about how the workspace should behave are memory-worthy when they affect future output.
If a correction applies to a command, prompt, skill, agent, or reusable rule, update the linked tool directly instead of only logging the correction.
Examples:
- A standup formatting correction should update
prompts/standup.mdand the shared workflow in.agents/workflows/standup.md. - A Mattermost freshness correction should update the Mattermost command/plugin instructions.
- A Copilot prompt-structure correction should update
prompts/copilot-prompt.md,.agents/workflows/copilot-prompt.md, or the shared skill/rule source. - A Swift answer-quality correction should update the relevant iOS skill or
project-knowledge/03-context/ios/guidance.
Keep the daily log as evidence of what happened, but make the reusable behavior live in the file that controls that behavior.
File Selection
project-knowledge/06-daily/YYYY-MM-DD.md
Default destination for:
- same-day progress
- same-day findings
- scoped reproduction notes
- story and approval movement
- context that is important now but may evolve later
project-knowledge/01-current/current-work.md
Use when the fact changes the active work window, including:
- current priorities
- currently active story scope
- current blockers or debugging constraints
- manager direction that changes the next few days of work
project-knowledge/02-work-items/*.md and project-knowledge/01-current/work-items.md
Use project-knowledge/02-work-items/*.md as the canonical memory for current Jira-linked work that should remain easy to reference across sessions, especially:
- Jira IDs
- approved or explicit titles
- currently relevant status notes
- current points or scope notes
Use project-knowledge/01-current/work-items.md as the summary view of what is active now.
These files should help standups and manager updates mention work items precisely.
project-knowledge/03-context/project.md
Use for durable project knowledge that should survive beyond the current work window.
project-knowledge/04-people/manager.md
Use only when a communication preference or manager expectation becomes stable enough to reuse repeatedly.
project-knowledge/04-people/index.md and project-knowledge/04-people/*.md
Use these files for:
- mapping roles to actual people
- keeping named stakeholders recognizable across sessions
- storing stable communication or responsibility context per person
When the role is not explicit, store:
- where the person tends to appear
- what kinds of topics they influence
- how they affect approvals, scope, debugging, or communication
project-knowledge/05-decisions/*.md
Use for explicit confirmed decisions with ongoing impact.
.agents/workflows/, .agents/rules/, .agents/skills/, .opencode/, prompts/, and agent-memory/
Use these when the new information changes how the workspace should operate:
- command invocation behavior
- reusable output format
- default agent behavior
- specialized skill workflow
- persistent process or memory rules
Do not create a separate note when an existing command, prompt, agent, or skill is the source of truth.
What Not To Store
Do not store:
- tool failures
- sync attempts
- generic urgency messages
- duplicate paraphrases of the same fact
- weak guesses
- operational chatter that does not change project understanding
Correction Rule
If new information supersedes old memory:
- update the existing canonical file
- do not leave stale and corrected versions side by side
- preserve qualifiers if the fact is only partially confirmed
The agent should behave like a senior engineer maintaining project notes, not like a chat assistant accumulating transcripts.