Personal Os Framework

Build a second brain that AI can understand and maintain. This framework provides decision logging with follow-up tracking, periodic review generation, routi...

Security Scan

The skill is an instruction-only framework for an AI-backed personal knowledge system; its requested actions (reading/updating workspace markdown files and generating reviews) align with its stated purpose and it does not demand unrelated credentials or installs.

Purpose & Capability

Name/description match the instructions: the skill's runtime guidance is limited to building and maintaining a 'personal-os' (STATE.md, TODO.md, DECISIONS.md, Inbox/Knowledge/, etc.). There are no unrelated requirements (no cloud creds, no binaries, no external services).

Instruction Scope

The SKILL.md explicitly tells an AI collaborator to read and update local workspace files after conversations, generate periodic reviews, and perform routing/distillation. This stays within the claimed domain, but the guidance to 'not wait for commands' and to act proactively grants broad discretionary behavior to an agent (within the personal-os file set). There are no instructions to access unrelated system paths or external endpoints.

Install Mechanism

Instruction-only skill with no install spec and no code files — nothing is downloaded or written by an installer. Lowest install risk.

Credentials

The skill requests no environment variables, credentials, or config paths. All required inputs are local markdown files, which is proportional to the stated functionality.

Persistence & Privilege

The skill does not set always:true and has no installer, but its content recommends autonomous, periodic behavior (cron jobs optional) and encourages the AI to act proactively. Autonomous invocation is the platform default; combined with the proactive guidance this increases the chance the agent will read/write the workspace frequently — this is consistent with purpose but worth noting from a policy/operational perspective.

Assessment

This skill is internally coherent and does what it says: it asks an AI collaborator to read and update files in a workspace to implement a 'personal OS'. Before installing or enabling autonomous use, consider: 1) Only point the skill at a directory you control and that does not contain secrets or sensitive credentials (the skill will read/write markdown files). 2) Decide whether you want the agent to act proactively — if not, restrict autonomous invocation or require manual triggers. 3) Monitor the files the agent writes (HEARTBEAT-LOG.md, reviews) and keep backups. 4) If you plan to run periodic jobs (cron), ensure they run with minimal privileges and under a controlled account. If you need more assurance, ask the skill author for explicit boundaries (exact file paths, a dry-run mode, and a clear list of files the skill will modify).

A methodology and toolset for building a second brain that AI can understand and maintain.

The Core Idea

The human does the work. The AI records it. The AI reads the records. The AI understands the human. The AI helps more effectively.

This is not a standalone tool. It requires an AI collaborator that reads, updates, and maintains the system through ongoing conversation.

What This Framework Provides

Decision Log

Record important decisions with rationale and follow-up actions. Every significant judgment gets a permanent record.

Review Operator

Generate daily, weekly, and monthly reviews from project state. Surface stale projects, identify blockers, generate follow-up actions.

Routing Assistant

Classify incoming information by type and destination. Every piece of information has a canonical home.

Task Layer

Define what a task looks like. Track status, ownership, and aging.

Execution Layer

Record when work begins. Identify started tasks that have gone stale.

Decision Support Layer

Monitor decision follow-ups and task health. Proactive monitoring without manual recounting.

Memory Distiller

Convert accumulated raw captures into structured knowledge. Raw notes become permanent knowledge after a 7-day aging period.

Workflow

Capture → Structure → Execute → Reflect

Information enters the system. It gets classified. Work happens. Regular reviews keep everything current.

How It Works

Human does something
    ↓
AI observes or is told
    ↓
AI records in personal-os
    ↓
AI reads personal-os
    ↓
AI understands the human
    ↓
AI provides better help

Key Principles

The AI does not wait for commands. The AI reads the system, understands the human, and acts proactively.

Reviews keep the system alive. Without regular reviews, the system becomes stale.

Decisions are the most valuable content. Log them with context.

Files

Every personal-os has these core files:

• STATE.md — current project states
• TODO.md — active tasks
• DECISIONS.md — decision log
• PENDING-DECISIONS.md — blocked decisions
• HEARTBEAT-LOG.md — system activity log

For AI Collaborators

Read the personal-os after each conversation. Update relevant files. The system stays current because the AI keeps it current.

When to Use This Framework

Use when:

• You want to build a personal OS that AI can understand and maintain
• You want decisions logged with context
• You want regular reviews that surface stale projects
• You want clear routing rules for information
• You want AI to collaborate proactively

Do not use when:

• The work is too small to benefit from structure
• There is no commitment to regular reviews
• The human is not willing to work with an AI collaborator

Success Metrics

The framework is working when:

• You can answer "what was the reasoning behind X decision?"
• Reviews surface real stale items
• Decisions have follow-up actions that get done
• The AI understands your context
• The system stays current without constant maintenance