@fyso/awareness-framework 0.1.0

package/docs/private-state.md

@@ -0,0 +1,157 @@
+# Private State
+
+Private state is the live operational data used by agents during the day. It should not be committed to this repository.
+
+## Recommended Paths
+
+```text
+~/.agents/
+  AGENTS.md
+  awareness/current.md
+  worklog/YYYY-MM-DD.md
+  memory/preferences.md
+  memory/patterns.md
+  memory/personality.md
+  memory/long-term.md
+  memory/users/<user>.md
+  evaluations/YYYY-MM-DD.md
+  runtime/hooks/YYYY-MM-DD.jsonl
+  runtime/schedule/YYYY-MM-DD.jsonl
+  channels/<channel>/
+    awareness/current.md
+    worklog/YYYY-MM-DD.md
+    memory/users/<user>.md
+```
+
+## Awareness Board
+
+The awareness board is mutable. It represents the current operating state.
+
+Use it for:
+
+- current focus
+- active tasks
+- paused tasks
+- blocked tasks
+- waiting-on-user items
+- next actions
+- evidence pointers
+
+Do not use it as:
+
+- a full historical archive
+- a replacement for the worklog
+- a private memory dump
+- a duplicate of all Jira fields
+
+## Daily Worklog
+
+The daily worklog is append-only.
+
+Use it for:
+
+- starts
+- switches
+- concrete progress
+- decisions
+- verification
+- blockers
+- PRs, commits, and deployments
+
+Corrections should be appended as new entries.
+
+## Memory
+
+Memory is optional and private.
+
+Use it for:
+
+- operator preferences
+- recurring working patterns
+- stable project context
+- repeated review guidance
+- durable collaboration rules
+- narrow participant memory such as nicknames, repeated questions, topics, and explicit preferences
+
+Do not use it for:
+
+- secrets
+- tokens
+- sensitive customer data
+- raw chat transcripts
+
+See [Memory Model](memory.md) for the short-term, episodic, and long-term memory lifecycle.
+
+## Channel Scope
+
+Channel-scoped state isolates context for multi-channel integrations.
+
+Use it for:
+
+- per-channel awareness
+- per-channel worklogs
+- per-channel evaluations
+- per-channel user memory
+
+Do not use it to create a full workspace per user. User memory should stay narrow under `memory/users/<user>.md`.
+
+## Evaluation Notes
+
+Evaluation notes are private by default. They are used to decide whether the framework should change.
+
+Only sanitized observations should be copied into framework improvement proposals.
+
+## Runtime Events
+
+Runtime events are local automation records generated by hooks and scheduled maintenance.
+
+Use them for:
+
+- checking whether hooks fired
+- recording scheduler health checks
+- debugging stale or missing private state
+
+Do not use them as:
+
+- task evidence
+- worklog replacement
+- long-term memory
+- external reporting input without review
+
+## Personality Profile
+
+The personality profile is private durable memory for collaboration style.
+
+Use it for:
+
+- preferred tone and language
+- update style
+- formatting preferences
+- recurring collaboration habits
+
+Do not use it for:
+
+- secrets
+- sensitive personal data
+- customer information
+- fictional identity claims
+- rules that override direct user instructions
+
+## Version Control Guardrails
+
+This repository includes `.gitignore` entries for common private-state paths. That does not replace review.
+
+Before committing, check that the diff contains only:
+
+- docs
+- templates
+- sanitized examples
+- governance changes
+
+Never commit:
+
+- real daily worklogs
+- real awareness boards
+- personal memories
+- local credentials
+- customer-specific task details

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@fyso/awareness-framework",
+  "version": "0.1.0",
+  "description": "Methodology and helper CLI for agent awareness, initialization, daily worklogs, handoffs, and evaluation loops.",
+  "type": "module",
+  "author": "Fyso",
+  "homepage": "https://github.com/fyso-dev/awareness-framework#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fyso-dev/awareness-framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fyso-dev/awareness-framework/issues"
+  },
+  "keywords": [
+    "agents",
+    "awareness",
+    "worklog",
+    "memory",
+    "cli",
+    "handoff",
+    "automation"
+  ],
+  "bin": {
+    "awareness": "bin/awareness.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "templates",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "Apache-2.0"
+}