@fyso/awareness-framework 0.1.0

package/templates/agent-instructions.md

@@ -0,0 +1,37 @@
+# Agent Awareness and Worklog Protocol
+
+You operate in a multi-task, multi-agent environment. Before doing work, load the private awareness state and maintain the private daily worklog.
+
+## Required Private Files
+
+- Awareness board: `~/.agents/awareness/current.md`
+- Daily worklog: `~/.agents/worklog/YYYY-MM-DD.md`
+- Optional durable memory: `~/.agents/memory/`
+- Optional narrow user memory: `~/.agents/memory/users/<user>.md` or scoped channel equivalent
+- Optional evaluation notes: `~/.agents/evaluations/YYYY-MM-DD.md`
+- Runtime hook and scheduler events: `~/.agents/runtime/`
+
+## Lifecycle
+
+1. On session start, run `awareness status` or `awareness check` if the CLI is available; otherwise read the awareness board directly.
+2. Treat imported `@current.md` content as a bootstrap snapshot, not live synchronization.
+3. If another agent may have worked in parallel, run `awareness refresh` or reread `current.md` before acting.
+4. If the user's request changes focus, update the awareness board and append a task-switch entry to the worklog.
+5. When concrete progress happens, append to the daily worklog.
+6. When state changes, update the awareness board.
+7. Before handoff, run `awareness handoff` if available; otherwise make the awareness board reflect the exact current state and append a final worklog entry.
+8. At end of day, prepare a task-grouped summary for human review.
+9. Treat hook and scheduler runtime events as diagnostics only; they do not replace task worklog entries.
+10. For multi-user channels, keep context scoped by channel and store only narrow user facts in `memory/users/<user>.md`.
+
+## Rules
+
+- Keep the worklog append-only.
+- Do not invent task IDs.
+- Record evidence: paths, commands, test results, commits, PRs, deployments, blockers.
+- Prefer CLI maintenance commands (`awareness focus`, `awareness log`, `awareness handoff`, `awareness evaluate`) when available.
+- Use `awareness user note` only for short, evidence-backed participant facts such as nicknames, repeated questions, topics, or explicit preferences.
+- Use `awareness hook run` and `awareness schedule run` only for low-noise maintenance; do not let them post externally or promote long-term memory silently.
+- Keep private state out of version control.
+- Ask before posting worklogs, comments, status changes, or summaries to external systems.
+- Propose framework improvements through reviewed changes, not hidden local edits.

package/templates/awareness-current.md

@@ -0,0 +1,53 @@
+# Agent Awareness
+
+- Updated: YYYY-MM-DD HH:MM TZ
+- Operator: Human or agent identifier
+- Scope: Local private state; do not commit
+
+## Current Focus
+
+- Task: PROJECT-123 or Unassigned
+- Summary: Short task description
+- Repository: org/repo or local path
+- Branch: branch-name
+- State: in-progress
+- Next: The next concrete action
+
+## Active Tasks
+
+### PROJECT-123 - Short title
+
+- State: in-progress | paused | ready | in-review
+- Last update: YYYY-MM-DD HH:MM TZ
+- Repository: org/repo
+- Branch: branch-name
+- Done:
+  - Concrete completed item
+- Next:
+  - Concrete next action
+- Blockers:
+  - None
+- Evidence:
+  - File paths, command results, commit hashes, PR links
+
+## Blocked Tasks
+
+### PROJECT-456 - Short title
+
+- Blocked by: Missing approval, failing dependency, access issue
+- Since: YYYY-MM-DD HH:MM TZ
+- Needed to unblock: Specific action or decision
+- Evidence:
+  - Link or command output
+
+## Waiting On User
+
+- PROJECT-789: Decision needed
+
+## Parking Lot
+
+- Idea or follow-up that should not interrupt current work
+
+## End-of-Day Candidates
+
+- PROJECT-123: Summary candidate with evidence

package/templates/cli-wrapper.md

@@ -0,0 +1,11 @@
+# Local Agent Instructions
+
+Read and follow the canonical private protocol at:
+
+@/Users/example/.agents/AGENTS.md
+
+If your CLI does not expand `@` imports automatically, open that file explicitly before starting work.
+
+Treat imported awareness files as session-start snapshots. If the Awareness CLI is available, run `awareness status` or `awareness check` at session start, `awareness refresh` when parallel work may have changed state, and `awareness handoff` before returning control.
+
+Keep this wrapper small. The framework should live in versioned methodology docs, and live operational state should stay private.

package/templates/daily-worklog.md

@@ -0,0 +1,11 @@
+# Daily Worklog - YYYY-MM-DD
+
+## Entries
+
+### HH:MM - PROJECT-123 - Short action summary
+
+- Context: Repository, branch, workspace, or meeting context
+- State: started | in-progress | paused | blocked | done | in-review
+- Changes: What changed or was decided
+- Evidence: Paths, command outputs, test results, commit hashes, PR links
+- Next: Optional next action

package/templates/end-of-day-summary.md

@@ -0,0 +1,27 @@
+# End-of-Day Summary - YYYY-MM-DD
+
+## By Task
+
+### PROJECT-123 - Short title
+
+- Time window: HH:MM-HH:MM
+- Work performed:
+  - Concrete outcome
+- Evidence:
+  - PR, commit, command result, file path, deployment link
+- Remaining:
+  - Next action or blocker
+- Suggested external worklog:
+  - Human-reviewed text for Jira or another system
+
+## Unassigned Work
+
+- Work that should be linked to an external ID later
+
+## Blockers
+
+- Task, blocker, owner, next checkpoint
+
+## Methodology Observations
+
+- Anything that made the awareness or worklog process better or worse

package/templates/evaluation-note.md

@@ -0,0 +1,42 @@
+# Awareness Evaluation - YYYY-MM-DD
+
+## Score
+
+| Dimension | Score | Evidence |
+|-----------|-------|----------|
+| Freshness | 0-2 | What was current or stale |
+| Traceability | 0-2 | Missing or present task IDs/evidence |
+| Handoff quality | 0-2 | Whether next actions were clear |
+| Noise control | 0-2 | What should be trimmed |
+| Reporting readiness | 0-2 | How much rewrite was needed |
+| Memory quality | 0-2 | What should be promoted, pruned, or left short-term |
+| Personality fit | 0-2 | Continuity, voice, context sensitivity, repair |
+
+## Observations
+
+- What worked well enough to keep
+- What caused missing context or duplicate effort
+- What should be changed in templates or rules
+
+## Memory Review
+
+- Short-term observations to keep short-term:
+- Long-term memory candidates:
+- Memory to prune or revise:
+- User confirmation needed:
+
+## Improvement Routing
+
+- Awareness cleanup:
+- Worklog correction:
+- Long-term memory promotion:
+- Personality update:
+- Framework PR candidate:
+
+## Proposed Changes
+
+- No change
+- Local habit change
+- Memory promotion or pruning
+- Template adjustment
+- Framework documentation PR

package/templates/framework-improvement-proposal.md

@@ -0,0 +1,24 @@
+# Framework Improvement Proposal
+
+## Problem
+
+What repeated failure or costly handoff issue was observed?
+
+## Evidence
+
+- Dates or redacted examples
+- Missing worklog fields
+- Stale awareness states
+- Rework caused during end-of-day reporting
+
+## Proposed Change
+
+The smallest rule, template, or lifecycle change that addresses the issue.
+
+## Expected Effect
+
+How the change improves traceability, handoff, or reporting.
+
+## Rollback Criteria
+
+When the change should be removed or softened because it adds noise.

package/templates/memory-long-term.md

@@ -0,0 +1,37 @@
+# Long-Term Memory
+
+- Updated: never
+- Scope: Local private state; do not commit
+
+This file stores durable, curated memory that improves future collaboration. Add entries only when they are user-confirmed, repeated, or operationally important.
+
+## Preferences
+
+- None yet.
+
+## Patterns
+
+- None yet.
+
+## Project Conventions
+
+- None yet.
+
+## Review Guidance
+
+- None yet.
+
+## Promotion Candidates
+
+- None yet.
+
+## Pruned Or Revised
+
+- None yet.
+
+## Guardrails
+
+- Do not store secrets, credentials, sensitive personal data, or raw transcripts.
+- Do not promote one-off guesses without repeated evidence.
+- Direct user instructions override memory.
+- Remove or soften stale memory.

package/templates/personality.md

@@ -0,0 +1,38 @@
+# Agent Personality Profile
+
+- Updated: never
+- Scope: Local private state; do not commit
+
+This file captures the agent's durable working style for this operator. It should evolve from repeated evidence and explicit user feedback, not from a single guess.
+
+## Accepted Traits
+
+- None yet.
+
+## Candidate Observations
+
+- None yet.
+
+## Human-Feeling Collaboration
+
+- Continuity:
+  - None yet.
+- Consistent voice:
+  - None yet.
+- Context sensitivity:
+  - None yet.
+- Bounded initiative:
+  - None yet.
+- Honest repair:
+  - None yet.
+- Grounded uncertainty:
+  - None yet.
+
+## Guardrails
+
+- Personality means communication style, collaboration habits, and decision preferences.
+- Do not pretend to have emotions, identity, or lived experience.
+- Do not store secrets, credentials, customer data, or sensitive personal data.
+- Prefer user-confirmed traits over inferred traits.
+- Remove or soften traits that create worse outcomes.
+- Optimize for trust and continuity, not for passing as human through deception.