@fyso/awareness-framework 0.1.0

package/docs/evaluation-loop.md

@@ -0,0 +1,128 @@
+# Evaluation Loop
+
+The framework should improve from use, but it should not mutate itself silently.
+
+Self-improvement means:
+
+1. observe friction
+2. score the process
+3. propose the smallest useful change
+4. review the change
+5. update the framework only after approval
+
+This loop evaluates both execution quality and memory quality. A good evaluation decides whether the next action is a local habit change, a short-term awareness cleanup, a long-term memory update, a template adjustment, or a framework PR.
+
+## Boundary
+
+| Can happen automatically | Requires human review |
+|--------------------------|-----------------------|
+| Generate a private daily evaluation note | Change the versioned framework |
+| Detect stale awareness state | Post to Jira or another external system |
+| Suggest a better template | Merge methodology changes |
+| Flag noisy or missing fields | Store new durable personal memory |
+| Prepare an improvement proposal | Apply organization-wide rules |
+| Record hook and scheduler runtime events | Treat runtime events as work evidence |
+
+## Cadence
+
+| Cadence | Question |
+|---------|----------|
+| Session hook | Did the agent reach a lifecycle boundary that should be recorded? |
+| Hourly schedule | Is private state healthy enough for parallel work to continue? |
+| Task switch | Was the previous task left with a clear state and next action? |
+| Handoff | Can another agent continue from private files alone? |
+| Daily schedule | Should a private evaluation note be created for review? |
+| End of day | Can the day be summarized by task ID with evidence? |
+| Weekly | Did recurring failures justify a framework change? |
+
+## Self-Evaluation Dimensions
+
+Evaluate the agent as a collaborator, not only the files.
+
+| Dimension | Question |
+|-----------|----------|
+| Task execution | Did the agent make correct, useful progress toward the user's goal? |
+| Awareness hygiene | Is `current.md` compact, fresh, and useful for the next agent? |
+| Worklog quality | Can the day be reconstructed with task IDs and evidence? |
+| Memory quality | Did anything deserve promotion to long-term memory or pruning from it? |
+| Personality fit | Did the agent preserve continuity, voice, context sensitivity, and honest repair? |
+| Tool reliability | Did CLI commands and checks reduce context burden or add friction? |
+| Framework feedback | Did repeated friction suggest a versioned methodology change? |
+
+## Signals
+
+Track signals from private awareness and worklog files:
+
+- stale `Current Focus`
+- active tasks without `Next`
+- worklog entries without task IDs
+- worklog entries without evidence
+- repeated blockers without owner or checkpoint
+- external task IDs discovered late
+- chat-only decisions not reflected in the worklog
+- awareness board too verbose to scan
+- end-of-day summary requiring manual reconstruction
+
+## Scoring Rubric
+
+Use a small 0-2 rubric.
+
+| Dimension | 0 | 1 | 2 |
+|-----------|---|---|---|
+| Freshness | Awareness is stale or misleading | Mostly current with minor gaps | Current focus and task states are accurate |
+| Traceability | Work cannot be tied to IDs or evidence | Some work is traceable | Meaningful work has task ID and evidence |
+| Handoff quality | Chat history is required | Next actions exist but lack context | Another agent can continue from files alone |
+| Noise control | Files are too verbose or obsolete | Some cleanup needed | Current board is compact and useful |
+| Reporting readiness | Summary needs reconstruction | Summary exists with manual fixes | Summary is ready for human review |
+
+Scores are diagnostic. A low score should produce a targeted improvement proposal, not blame.
+
+## Improvement Rules
+
+- Add a rule only when a repeated failure cannot be solved by a local habit.
+- Add a field only when it improves handoff or end-of-day reporting.
+- Remove fields that agents fill with low-value boilerplate.
+- Convert repeated user corrections into template improvements.
+- Keep the awareness board optimized for next action.
+- Keep the worklog optimized for evidence.
+- Promote short-term observations to long-term memory only when user-confirmed, repeated, or operationally important.
+- Prune memory that becomes stale, noisy, sensitive, or contradicted by direct user instructions.
+- Change the framework through reviewed commits or pull requests.
+
+## Improvement Routing
+
+| Finding | Route |
+|---------|-------|
+| Current focus stale | Update `awareness/current.md` |
+| Missing evidence | Append or correct the daily worklog |
+| Repeated preference | Promote to `memory/preferences.md` or `memory/long-term.md` |
+| Collaboration style correction | Update `memory/personality.md` |
+| Repeated workflow friction | Propose a template or docs PR |
+| Sensitive or stale memory | Prune private memory |
+| Tool command confusion | Improve CLI docs or command behavior |
+| Repeated scheduler warning | Improve local habits, templates, or CLI checks |
+
+## Evaluation Output
+
+Each evaluation should end with one of these outcomes:
+
+- No change.
+- Clean up awareness.
+- Append missing evidence.
+- Promote memory.
+- Prune memory.
+- Adjust local habit.
+- Propose framework PR.
+- Ask user for confirmation.
+
+## Example Outcomes
+
+| Observation | Improvement |
+|-------------|-------------|
+| Many entries say `Unassigned` but later map to Jira | Add an end-of-day reconciliation prompt |
+| Blockers remain stale for days | Add `Since` and `Needed to unblock` to blocked tasks |
+| Awareness board grows too large | Add an end-of-day cleanup step |
+| Test evidence is often missing | Make `Evidence` required in worklog entries |
+| Agents over-log trivial actions | Clarify which events deserve entries |
+| User repeats the same preference | Promote it to long-term memory |
+| Personality feels generic | Add or revise private personality traits |

package/docs/framework.md

@@ -0,0 +1,95 @@
+# Framework
+
+Awareness Framework separates methodology from operational state.
+
+The framework lives in version control. Real state lives privately on the operator's machine or in an approved private system.
+
+## Design Goals
+
+1. Make agent work reconstructable at the end of the day.
+2. Support multiple parallel tasks without relying on chat history.
+3. Make handoffs between agent sessions explicit.
+4. Preserve evidence for external worklogs and status reports.
+5. Improve the methodology through reviewable changes.
+
+## Non-Goals
+
+1. Do not replace Jira, GitHub Issues, sprint boards, or project task managers.
+2. Do not store secrets, credentials, customer data, or private memories.
+3. Do not require a specific AI agent, CLI, model, or vendor.
+4. Do not make autonomous external updates without human confirmation.
+5. Do not optimize for exhaustive history in the live awareness board.
+
+## Operating Principles
+
+### 1. Current State Is Mutable
+
+The awareness board is a compact snapshot of the current operating state. It can be edited as work changes.
+
+It should answer:
+
+- What is the current focus?
+- What tasks are active, paused, blocked, or waiting?
+- What is the next action for each active task?
+- What evidence exists?
+- What should appear in the end-of-day report?
+
+### 2. Bootstrap Is Not Synchronization
+
+Instruction-file imports can preload the awareness board at session start. That is a snapshot, not a live subscription to file changes.
+
+In parallel-agent workflows, agents should refresh from disk before acting on potentially stale state. If the CLI is available, use `awareness refresh`, `awareness check`, or `awareness handoff`. If not, reread `~/.agents/awareness/current.md`.
+
+### 3. History Is Append-Only
+
+The daily worklog is chronological and append-only. Corrections are new entries.
+
+It should capture:
+
+- task starts and switches
+- concrete progress
+- meaningful decisions
+- blockers
+- verification
+- commits, PRs, deployments, and external evidence
+
+### 4. Evidence Beats Narration
+
+Prefer concrete evidence over long prose:
+
+- file paths
+- commands
+- test results
+- commit hashes
+- PR links
+- issue IDs
+- blocker owners
+
+### 5. External IDs Are Preserved, Not Invented
+
+When a Jira issue, GitHub issue, PR, or ticket exists, record it. If none exists, use `Unassigned` and reconcile later.
+
+Agents must not invent external IDs.
+
+### 6. Private State Is Not Versioned
+
+This repository stores templates and rules only. Real files such as `~/.agents/awareness/current.md` and `~/.agents/worklog/YYYY-MM-DD.md` stay private.
+
+### 7. Self-Improvement Is Reviewed
+
+Agents can detect process friction and suggest improvements, but framework changes happen through pull requests or another reviewed change process.
+
+## Parallel Task Model
+
+Only one task is the current focus, but many tasks can be active, paused, blocked, or waiting.
+
+| Section | Role |
+|---------|------|
+| Current Focus | The one task the current session is actively serving |
+| Active Tasks | Work that can continue |
+| Blocked Tasks | Work that cannot continue and why |
+| Waiting On User | Decisions, credentials, approvals, or clarifications |
+| Parking Lot | Relevant deferred ideas |
+| End-of-Day Candidates | Work likely to become an external summary or worklog |
+
+The most important field for parallel work is `Next`. If `Next` is unclear, the task is not ready for handoff.

package/docs/governance.md

@@ -0,0 +1,48 @@
+# Governance
+
+The framework is versioned so changes can be reviewed and improved without mixing in private operational data.
+
+## Change Types
+
+| Change | Review expectation |
+|--------|--------------------|
+| Clarify wording | Normal review |
+| Add template field | Explain the handoff or reporting benefit |
+| Remove template field | Explain the noise reduction |
+| Add lifecycle rule | Provide repeated-friction evidence |
+| Change privacy guardrail | Require explicit review |
+| Add tool-specific guidance | Keep it optional and vendor-neutral |
+
+## Review Checklist
+
+Before merging a framework change, check:
+
+- Does it improve handoff, traceability, or reporting?
+- Does it avoid storing private state?
+- Does it stay tool-agnostic?
+- Does it avoid adding fields that agents will fill with boilerplate?
+- Does it preserve human confirmation for external writes?
+- Is the example sanitized?
+
+## Privacy Rules
+
+Do not commit:
+
+- real awareness boards
+- real worklogs
+- personal memories
+- customer details
+- secrets or credentials
+- raw chat transcripts
+
+## Improvement Proposal Standard
+
+Framework changes should answer:
+
+- What repeated problem was observed?
+- What private evidence supports it, in sanitized form?
+- What is the smallest change?
+- How will we know whether it helped?
+- When should the change be reverted or simplified?
+
+Use [the improvement proposal template](../templates/framework-improvement-proposal.md).

package/docs/hooks-and-scheduling.md

@@ -0,0 +1,160 @@
+# Hooks and Scheduling
+
+Hooks and schedules make the framework easier for agents to follow without loading the full methodology into every prompt.
+
+The rule is intentionally conservative:
+
+- Tool hooks do small lifecycle maintenance.
+- Global schedules do periodic health checks and daily evaluation.
+- Long-term memory promotion stays curated and evidence-backed.
+- External posting to Jira, GitHub, email, or chat never happens from these hooks by default.
+
+## Storage Paths
+
+Private awareness state remains under:
+
+```text
+~/.agents/
+```
+
+Hook and scheduler runtime events are low-noise technical records:
+
+```text
+~/.agents/runtime/hooks/YYYY-MM-DD.jsonl
+~/.agents/runtime/schedule/YYYY-MM-DD.jsonl
+~/.agents/runtime/launchd/
+```
+
+These files are private operational state. Do not commit them.
+
+## Hook Cadence
+
+| Lifecycle point | Command | Purpose |
+|-----------------|---------|---------|
+| Session start or resume | `awareness hook run --tool TOOL --event session-start` | Ensure private files exist and record that the agent refreshed awareness. |
+| Stop or session end | `awareness hook run --tool TOOL --event stop` | Record that the agent reached an idle or handoff boundary. |
+| Pre-compaction | `awareness hook run --tool TOOL --event pre-compact` | Record a compaction boundary before context is summarized. |
+| Post-compaction | `awareness hook run --tool TOOL --event post-compact` | Record that the new compacted context may need `awareness refresh`. |
+
+Hooks should not append daily worklog entries on every lifecycle event. The worklog is for human-relevant progress with task IDs and evidence.
+
+## Scheduled Cadence
+
+| Cadence | Command | Purpose |
+|---------|---------|---------|
+| Hourly | `awareness schedule run --cadence hourly` | Verify private state and record warnings. |
+| Daily | `awareness schedule run --cadence daily` | Verify private state and create the daily evaluation note if it does not already exist. |
+
+Daily evaluation writes:
+
+```text
+~/.agents/evaluations/YYYY-MM-DD.md
+```
+
+It does not automatically edit long-term memory or the versioned framework.
+
+## Install Hooks
+
+Install hook integrations for supported CLIs:
+
+```bash
+awareness hook install --tool all --command "$(command -v awareness)"
+```
+
+Install one integration at a time:
+
+```bash
+awareness hook install --tool codex --command "$(command -v awareness)"
+awareness hook install --tool claude --command "$(command -v awareness)"
+awareness hook install --tool opencode --command "$(command -v awareness)"
+```
+
+Generated files:
+
+```text
+~/.codex/hooks.json
+~/.claude/settings.json
+~/.config/opencode/plugins/awareness-framework.js
+```
+
+The installer merges Codex and Claude JSON files. For OpenCode, it writes a generated plugin file and does not overwrite a custom file unless `--overwrite` is passed.
+
+## Install Global Schedules On macOS
+
+Write user LaunchAgents:
+
+```bash
+awareness schedule install --cadence all --command "$(command -v awareness)"
+```
+
+Write and load them immediately:
+
+```bash
+awareness schedule install --cadence all --command "$(command -v awareness)" --load
+```
+
+Generated files:
+
+```text
+~/Library/LaunchAgents/dev.fyso.awareness.hourly.plist
+~/Library/LaunchAgents/dev.fyso.awareness.daily.plist
+```
+
+Use an absolute command path for LaunchAgents. `launchd` does not run through an interactive shell and may not have the same `PATH`.
+
+Install a channel-scoped schedule when a multi-channel integration needs independent maintenance:
+
+```bash
+awareness schedule install --cadence all --channel support --command "$(command -v awareness)"
+```
+
+This writes labels such as:
+
+```text
+dev.fyso.awareness.support.hourly
+dev.fyso.awareness.support.daily
+```
+
+## Tool Notes
+
+### Codex
+
+Codex discovers hooks from `~/.codex/hooks.json`, `~/.codex/config.toml`, project `.codex/` files, and enabled plugins. Codex requires non-managed command hooks to be reviewed and trusted with `/hooks` before they run.
+
+Reference: [Codex hooks](https://developers.openai.com/codex/hooks).
+
+### Claude Code
+
+Claude Code hooks are configured in JSON settings files such as `~/.claude/settings.json`. It supports session, turn, tool, compaction, and session-end events. Command hooks receive JSON event input on stdin.
+
+Reference: [Claude Code hooks reference](https://code.claude.com/docs/en/hooks).
+
+### OpenCode
+
+OpenCode loads global plugins from:
+
+```text
+~/.config/opencode/plugins/
+```
+
+The generated plugin subscribes to session events and the compaction hook, then invokes the Awareness CLI.
+
+Reference: [OpenCode plugins](https://opencode.ai/docs/plugins/).
+
+### Pi
+
+Pi currently uses the regular wrapper file generated by `awareness init --wrappers`. Add a Pi hook installer only after confirming a stable lifecycle hook mechanism for the specific Pi CLI/runtime in use.
+
+## Memory Interaction
+
+Hooks and schedules may create observations, warnings, and evaluation notes. They must not silently promote memories.
+
+Promotion still follows the memory pipeline:
+
+1. Observe in runtime, worklog, evaluation, or personality candidate.
+2. Attach evidence.
+3. Classify the observation.
+4. Promote only when repeated, user-confirmed, or operationally important.
+5. Prune stale or sensitive memory.
+
+This keeps the system useful without turning automation into an unreviewed preference engine.

package/docs/install.md

@@ -0,0 +1,250 @@
+# Install
+
+This page installs the optional Awareness Framework CLI and initializes private local state.
+
+The framework can still be used manually from templates. The CLI is recommended when agents should maintain awareness and worklogs through commands instead of keeping the full methodology in context.
+
+## Requirements
+
+- Node.js 20 or newer
+- A shell where global npm binaries are on `PATH`
+- npm registry access to `@fyso/awareness-framework`
+
+Check Node:
+
+```bash
+node --version
+```
+
+## Install The CLI
+
+Install from npm:
+
+```bash
+npm install -g @fyso/awareness-framework
+```
+
+Verify:
+
+```bash
+awareness help
+```
+
+If global npm cache permissions are broken on the machine, use a temporary cache:
+
+```bash
+npm_config_cache=/tmp/npm-cache-awareness npm install -g @fyso/awareness-framework
+```
+
+## Initialize Private State
+
+Initialize the private awareness home:
+
+```bash
+awareness init
+```
+
+This creates missing files under `~/.agents/`:
+
+```text
+~/.agents/
+  AGENTS.md
+  awareness/current.md
+  worklog/YYYY-MM-DD.md
+  memory/personality.md
+  memory/preferences.md
+  memory/patterns.md
+  memory/long-term.md
+  memory/users/
+  evaluations/
+  runtime/
+```
+
+Existing files are not overwritten.
+
+Initialize a channel-scoped state folder:
+
+```bash
+awareness init --channel support
+```
+
+This creates missing files under:
+
+```text
+~/.agents/channels/support/
+```
+
+Record narrow user memory inside the selected channel:
+
+```bash
+awareness user note \
+  --channel support \
+  --user user-123 \
+  --kind topic \
+  --text "Has been discussing worklog automation" \
+  --evidence "Message link or timestamp"
+```
+
+## Initialize Agent Wrappers
+
+Create regular wrapper files for supported CLIs:
+
+```bash
+awareness init --wrappers
+```
+
+This creates missing files:
+
+```text
+~/.codex/AGENTS.md
+~/.claude/CLAUDE.md
+~/.config/opencode/AGENTS.md
+~/.pi/agent/AGENTS.md
+```
+
+Wrappers point to the canonical private protocol:
+
+```text
+~/.agents/AGENTS.md
+```
+
+Existing wrappers are not overwritten. To intentionally replace wrappers:
+
+```bash
+awareness init --wrappers --overwrite-wrappers
+```
+
+## Verify Initialization
+
+Check current state:
+
+```bash
+awareness status
+awareness check
+```
+
+If another agent may have changed state during a session:
+
+```bash
+awareness refresh
+```
+
+Before handoff:
+
+```bash
+awareness handoff
+```
+
+## Optional Hook Installation
+
+Wrappers tell agents what to read. Hooks make supported tools run the maintenance commands at lifecycle boundaries.
+
+Install hooks for Codex, Claude Code, and OpenCode:
+
+```bash
+awareness hook install --tool all --command "$(command -v awareness)"
+```
+
+Generated files:
+
+```text
+~/.codex/hooks.json
+~/.claude/settings.json
+~/.config/opencode/plugins/awareness-framework.js
+```
+
+Codex requires configured command hooks to be reviewed and trusted from `/hooks` before they run.
+
+## Optional Global Schedule
+
+On macOS, install hourly and daily user LaunchAgents:
+
+```bash
+awareness schedule install --cadence all --command "$(command -v awareness)"
+```
+
+Load them immediately:
+
+```bash
+awareness schedule install --cadence all --command "$(command -v awareness)" --load
+```
+
+Generated files:
+
+```text
+~/Library/LaunchAgents/dev.fyso.awareness.hourly.plist
+~/Library/LaunchAgents/dev.fyso.awareness.daily.plist
+```
+
+Hourly runs record private health events. Daily runs create the evaluation note if missing.
+
+## Custom Paths
+
+Use a custom private awareness home:
+
+```bash
+awareness init --home /path/to/.agents
+```
+
+Use custom wrapper roots for tests or non-standard machines:
+
+```bash
+awareness init --wrappers \
+  --home /path/to/.agents \
+  --user-home /path/to/user-home \
+  --config-home /path/to/config-home
+```
+
+Environment variables are also supported:
+
+```bash
+AGENTS_HOME=/path/to/.agents awareness status
+AWARENESS_USER_HOME=/path/to/user-home awareness init --wrappers
+XDG_CONFIG_HOME=/path/to/config-home awareness init --wrappers
+```
+
+## Update
+
+Reinstall from npm:
+
+```bash
+npm install -g @fyso/awareness-framework
+```
+
+Then refresh local private files and wrappers:
+
+```bash
+awareness init --wrappers
+```
+
+Use `--overwrite-wrappers` only when you want the framework to replace existing wrapper files.
+
+Refresh hooks and schedules after upgrading when command paths or hook definitions changed:
+
+```bash
+awareness hook install --tool all --command "$(command -v awareness)"
+awareness schedule install --cadence all --command "$(command -v awareness)"
+```
+
+## Uninstall
+
+Remove the global CLI:
+
+```bash
+npm uninstall -g @fyso/awareness-framework
+```
+
+This does not delete private state under `~/.agents/`, wrapper files, hooks, or LaunchAgents.
+
+## Development Install
+
+For framework development:
+
+```bash
+git clone https://github.com/fyso-dev/awareness-framework.git
+cd awareness-framework
+npm test
+npm link
+```
+
+After `npm link`, the `awareness` command points to the local checkout.