Align workspace templates

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:
 

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

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
 

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
 

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
+

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
+

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
+