From 714beaaca1981190fbc3963f0236dd04a5c991d9 Mon Sep 17 00:00:00 2001 From: Slava Trofimov <26082149+pmbstyle@users.noreply.github.com> Date: Tue, 7 Apr 2026 18:54:05 -0400 Subject: [PATCH] align workspace templates --- workspace_templates/AGENTS.md | 10 +++++----- workspace_templates/HEARTBEAT.md | 14 +++++++++----- workspace_templates/MEMORY.md | 2 +- workspace_templates/USER.md | 1 + workspace_templates/memory/canon/decisions.md | 14 ++++++++++++++ workspace_templates/memory/canon/facts.md | 12 ++++++++++++ workspace_templates/memory/canon/failures.md | 14 ++++++++++++++ 7 files changed, 56 insertions(+), 11 deletions(-) diff --git a/workspace_templates/AGENTS.md b/workspace_templates/AGENTS.md index 90e8e68..c65e08f 100644 --- a/workspace_templates/AGENTS.md +++ b/workspace_templates/AGENTS.md @@ -43,12 +43,12 @@ This ensures: ### Worker Usage Principles -1. Use workers for EXTERNAL operations (network, external APIs) +1. Use workers for external operations (network, external APIs) 2. Use workers for long-running or async tasks 3. Prefer small, testable tasks with clear acceptance criteria 4. After worker completion, record key outcomes in daily memory 5. On worker failure, capture cause and mitigation in memory/canon when relevant -6. NEVER delegate LOCAL operations to workers — do them directly +6. Do not delegate local operations to workers. Do them directly. 7. Prefer to create one worker for one specific task or interaction with a specific service. Do not duplicate functionality, do not duplicate workers, change them if needed. 8. Workers may use `fs_read` and `fs_write` inside their own temporary worker workspace. 9. Workers do not automatically get access to the Octo main workspace. If a worker needs specific workspace files, pass the smallest necessary `allowed_paths`. @@ -72,7 +72,7 @@ You wake up fresh each session. Persist important continuity to files: - **Long-term summary**: `MEMORY.md` - **Canonical memory**: `memory/canon/facts.md`, `memory/canon/decisions.md`, `memory/canon/failures.md` -If you need to remember something, write it down. +If something will matter later, write it down. ## Context Reset Protocol @@ -129,7 +129,7 @@ Reset artifacts (read/write): - `AGENTS.md` (this file): operating instructions - `USER.md`: user preferences and identity context - `SOUL.md`: persona and communication style -- `HEARTBEAT.md`: scheduled checks and proactive tasks +- `HEARTBEAT.md`: readable scheduler snapshot for scheduled checks and proactive tasks - `MEMORY.md`: long-term notes ## Troubleshooting Protocol @@ -140,7 +140,7 @@ Before concluding that something is broken or impossible: 1. Check documentation first. 2. List at least a couple of alternative paths. -3. Ask what a careful human operator would try next. +3. Consider what a careful human operator would try next. Self-audit question: diff --git a/workspace_templates/HEARTBEAT.md b/workspace_templates/HEARTBEAT.md index c455466..13268aa 100644 --- a/workspace_templates/HEARTBEAT.md +++ b/workspace_templates/HEARTBEAT.md @@ -1,15 +1,18 @@ # HEARTBEAT - Scheduled Tasks -This file defines recurring checks and proactive tasks. +This file reflects recurring checks and proactive tasks configured in the scheduler. +It is primarily a readable snapshot, not the source of truth. Keep entries concrete, bounded, and easy to verify. -It is a living document and may be edited freely as schedules and routines change. +Scheduler changes may rewrite this file. ## How To Use - Each task should have a stable ID. -- Say what should run, how often, and what output is expected. +- Define or update schedules through scheduler tools or commands, then use this file to review the current state. +- Say what should run, how often, what output is expected, and whether the user should be notified. - Prefer writing results to workspace files instead of keeping them only in chat. - If a task depends on network access, assign an appropriate worker. +- `Daily at HH:MM` uses UTC. - If nothing is due, return `HEARTBEAT_OK`. ## Task Template @@ -18,11 +21,12 @@ It is a living document and may be edited freely as schedules and routines chang - **ID**: example_task - **Description**: Brief description of what this task is for - **Frequency**: Daily at 09:00 +- **Notify user**: if_significant - **Worker**: web_researcher - **Task**: [Scheduled: example_task] Do the bounded recurring work and save results to an agreed file -- **Last execution**: never +- **Last execution**: Never - **Status**: Disabled ## Tracking -- example_task_last_run: never +- example_task_last_run: Never diff --git a/workspace_templates/MEMORY.md b/workspace_templates/MEMORY.md index c412771..b3bfe32 100644 --- a/workspace_templates/MEMORY.md +++ b/workspace_templates/MEMORY.md @@ -9,7 +9,7 @@ Keep it compact and high-signal. ## What Belongs Here - Durable project goals and operating assumptions -- Stable user preferences and collaboration style +- Shared working assumptions that matter across sessions - Important systems context that is costly to rediscover - Ongoing initiatives worth remembering across days diff --git a/workspace_templates/USER.md b/workspace_templates/USER.md index 2122294..3ef1fab 100644 --- a/workspace_templates/USER.md +++ b/workspace_templates/USER.md @@ -3,6 +3,7 @@ Use this file for durable user-specific context. Only put things here that are stable and useful across many sessions. It is a living document and may be edited freely as you learn more about the user. +Prefer user-specific facts here. Put broader project context in `MEMORY.md`. ## Good Examples diff --git a/workspace_templates/memory/canon/decisions.md b/workspace_templates/memory/canon/decisions.md index 3ae0096..c6ee46f 100644 --- a/workspace_templates/memory/canon/decisions.md +++ b/workspace_templates/memory/canon/decisions.md @@ -1,2 +1,16 @@ # Decisions +Important decisions, policies, and standing rules. +This file is injected into the Octo context, so keep it lean and high-signal. + +Suggested format: +## Decision +- Decision: what was chosen +- Why: short rationale +- Since: optional date or milestone + +Avoid: +- Repeating raw discussion history +- Temporary experiments +- Low-confidence ideas that have not been adopted + diff --git a/workspace_templates/memory/canon/facts.md b/workspace_templates/memory/canon/facts.md index 05a4550..6a58d6f 100644 --- a/workspace_templates/memory/canon/facts.md +++ b/workspace_templates/memory/canon/facts.md @@ -1,2 +1,14 @@ # Facts +Verified facts that are likely to stay useful over time. +Keep entries short, specific, and easy to scan. + +Suggested format: +- Subject: fact +- Subject: fact + +Avoid: +- Tentative guesses +- Long narratives +- Things that belong in decisions or failures + diff --git a/workspace_templates/memory/canon/failures.md b/workspace_templates/memory/canon/failures.md index 475d771..863ac55 100644 --- a/workspace_templates/memory/canon/failures.md +++ b/workspace_templates/memory/canon/failures.md @@ -1,2 +1,16 @@ # Failures +Lessons from meaningful mistakes, regressions, or repeated dead ends. +This file is injected into the Octo context, so prefer concise patterns over long incident reports. + +Suggested format: +## Failure +- What failed: short description +- Why it failed: root cause if known +- Guardrail: what to do differently next time + +Avoid: +- One-off noise without a lesson +- Blame without evidence +- Full logs or raw transcripts +