Skip to content
/
Tier B A4 Markdown scaffold

Personal OS (itseffi)

agentic-os-effi · itseffi/personal-os · ★ 33 · last commit 2026-04-14

Provides a file-based personal operating system that grounds AI agent execution in explicit goals, backlogs, and 47 cross-domain skills spanning engineering, product strategy, and stakeholder management.

Best whenPersonal productivity automation for knowledge workers requires breadth across management and strategy skills, not just coding skills — and every skill must …
Skip ifCompletion claims without fresh verification evidence, Production code written before a failing test
vs seeds
superpowersit targets four runtimes via per-runtime wrapper files and follows the AgentSkills open standard format with openai.yaml…
Primitive shape 48 total
Skills 47 MCP tools 1
00

Summary

agentic-os-effi — Personal OS (itseffi/personal-os)

Personal OS is an agentic personal operating system designed to automate high-leverage workflows across Claude Code, Codex, Pi, OpenClaw, and other coding agent runtimes. Its central organizing metaphor is a personal productivity machine: a structured backlog of tasks tied to explicit goals, processed and prioritized by any compatible AI agent. The repo ships 47+ canonical skills following the AgentSkills open standard, with each skill exposed as a progressive-disclosure SKILL.md plus an OpenAI-compatible agents/openai.yaml metadata sidecar. Workflow automation is handled through 12 reusable workflow guides in Workflows/, covering everything from daily standups to stakeholder politics. Multi-agent support is optional and runtime-dependent; the repo itself ships no orchestration primitives but documents subagent delegation patterns. A companion System/mcp/server.py bundles custom MCP tooling for Jira, Granola, and Linear integrations.

Compared to the seeds, Personal OS is closest to agent-os (Archetype 4 — markdown scaffold) in that its core value is file-based state and behavioral guidance rather than commands or hooks. The key delta is scope: where agent-os focuses on codebase standards, Personal OS extends into full personal productivity (goals, backlog, evals, stakeholder management, product strategy) and explicitly targets multiple runtimes with per-runtime wrapper files (CLAUDE.md, CODEX.md, PI.md, OPENCLAW.md).

01

Overview

Overview — Personal OS (itseffi/personal-os)

Origin

Personal OS was created by itseffi as an agentic personal operating system to automate high-leverage personal and professional workflows. It was designed to be runtime-agnostic from the start — the repo explicitly maintains per-agent wrapper files for Claude Code, Codex, Pi, and OpenClaw. Skills in the repo follow the Agent Skills open standard, an emerging cross-runtime skill specification.

Philosophy

The project describes itself as:

"An agentic personal operating system built to automate high-leverage workflows across Claude Code, Codex, Pi, OpenClaw, and other coding agents/runtime platforms."

The core philosophy is progressive disclosure for context efficiency: agents begin with each skill's metadata (name, description, file path, plus agents/openai.yaml), and load full SKILL.md instructions only when a skill is selected. The repo is organized so that humans can read it as a productivity system and agents can read it as a behavioral specification.

Manifesto-Style Quotes

From AGENTS.md:

"You are a personal productivity assistant that keeps tasks organized, ties work to goals, and guides daily focus. You operate through whichever coding agent is running this workspace (Claude Code, Codex, or similar) using native file operations."

From the TDD skill:

"NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. Write code before the test? Delete it. Start over."

From the Verification skill:

"NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. If you haven't run the verification command in this message, you cannot claim it passes."

Target Problem

Personal OS targets the gap between raw AI capability and personal productivity discipline: without explicit structure, AI agents skip steps, hallucinate completion, and fail to tie work to strategic goals. The repo provides the scaffolding — task files, GOALS.md, BACKLOG.md, evals — that grounds AI execution in personal priorities.

02

Architecture

Architecture — Personal OS (itseffi/personal-os)

Distribution

  • Type: Standalone repository (clone-and-configure)
  • Install: git clone https://github.com/itseffi/personal-os.git && cd personal-os && chmod +x setup.sh && ./setup.sh
  • Runtime: No mandatory runtime — runs via any AI agent that can read/write files (Claude Code, Codex, Pi, OpenClaw)

Directory Tree

personal-os/
├── AGENTS.md           # AI agent instructions (shared across all runtimes)
├── CLAUDE.md           # Claude Code wrapper
├── CODEX.md            # Codex/OpenAI wrapper
├── PI.md               # Pi wrapper
├── OPENCLAW.md         # OpenClaw wrapper
├── GOALS.md            # User goals and priorities
├── BACKLOG.md          # Quick capture inbox
├── Tasks/              # Individual task files (YAML frontmatter)
├── Knowledge/          # Reference docs, research, notes
├── Resources/          # Templates, voice samples, assets
├── .agents/
│   └── skills/         # 47+ canonical skills in SKILL.md format
│       └── <skill>/
│           ├── SKILL.md          # Full skill instructions
│           └── agents/
│               └── openai.yaml  # OpenAI-compatible metadata
├── Workflows/          # 12 reusable workflow guides
├── Evals/              # Session reviews + skill evaluation harness
├── System/
│   ├── mcp/            # MCP server (server.py)
│   ├── integrations/   # External service connectors
│   └── templates/      # Document templates
├── scripts/
│   └── run_skill_evals.py  # Skill evaluation runner
└── setup.sh            # Bootstrap script

Runtime Bridges

The repo creates symlinks at setup time to bridge skills into each runtime's expected location:

  • Claude bridge: .claude/skills -> ../.agents/skills (symlink)
  • Pi bridge: configure Pi to point .agents/skills/
  • OpenClaw bridge: skills -> .agents/skills symlink

Required Runtime

  • Minimum: Any AI agent that reads/writes files (Claude Code, Codex, Pi, OpenClaw)
  • Recommended: Python 3.x for scripts/run_skill_evals.py
  • Optional: MCP-compatible runtime for System/mcp/server.py

Target AI Tools

Claude Code, Codex (OpenAI), Pi (Pi AI), OpenClaw — via dedicated wrapper AGENTS files. Cross-runtime portability is a first-class design constraint.

03

Components

Components — Personal OS (itseffi/personal-os)

Skills (47+, in .agents/skills/)

Each skill is a directory with SKILL.md (instructions) and agents/openai.yaml (metadata sidecar).

Skill Directory Purpose
assumption-mapping Map assumptions underlying a decision or plan
assumption-prioritization Rank assumptions by risk and testability
atlassian-jira-sync Sync tasks with Jira
backend-design Backend architecture guidance
brainstorming Structured ideation workflows
challenging-stakeholder-questions Prepare for difficult stakeholder conversations
competitor-analysis Competitive landscape analysis
crux-diagnosis Identify the root crux of a problem
davci DAVCI decision framework
decision-journal Record and review decisions
decision-reversibility Assess decision reversibility
difficult-conversations Guide difficult conversation planning
executive-update-review Review and craft executive updates
experiment-design Design and plan experiments
frontend-design Frontend architecture guidance
google-calendar-schedule-check Check calendar for scheduling
granola-meeting-sync Sync meeting notes from Granola
hidden-agendas Detect and navigate hidden agendas
hypothesis-design Design testable hypotheses
ideas-summary Summarize and cluster ideas
influence-strategies Plan influence and persuasion strategies
interview-cleanup Clean up and structure interview notes
jtbd-clustering Cluster jobs-to-be-done
jtbd-extraction Extract jobs-to-be-done from data
limit-based-strategy Strategy based on constraints
linear-issue-sync Sync tasks with Linear
llm-coding-guardrails LLM-specific coding guardrails
mece-analysis MECE analysis framework
meeting-power-dynamics Understand power dynamics in meetings
message-framing-comms Frame communications effectively
opportunity-solution-tree Build OST for product decisions
ost-intake Intake new opportunities into OST
ost-target-selection Select OST targets
power-map Map stakeholder power relationships
prd-writing Write product requirements documents
problem-structuring Structure ambiguous problems
root-cause-analysis Root cause analysis workflows
signal-identification Identify signals vs noise
slack-message-check Check and draft Slack messages
spec-writing Write technical specifications
stakeholder-risk-review Review stakeholder risks
structured-product-strategy Build structured product strategies
systematic-debugging Systematic debugging workflow
tdd Test-driven development (Iron Law: test first, always)
value-chain-mapping Map value chains
verification Verification before completion (Iron Law: no claims without fresh evidence)
writing-plans Write structured implementation plans

Workflows (12, in Workflows/)

File Purpose
assumption-validation-pipeline.md Pipeline for validating assumptions
backlog-processing.md Process BACKLOG.md into tasks
core-strategy-development.md Develop core strategy
daily-standup.md Daily standup workflow
decision-quality-pipeline.md Decision quality review pipeline
meeting-prep-and-recap.md Meeting preparation and recap
opportunity-mapping-pipeline.md Map opportunities end-to-end
research-to-feature-pipeline.md Convert research to feature specs
stakeholder-politics-copilot.md Navigate stakeholder politics
weekly-review.md Weekly review workflow
wrap-up-protocol.md Session wrap-up protocol

State Files

File Purpose
GOALS.md User goals and priorities
BACKLOG.md Quick capture inbox
Tasks/*.md Individual task files with YAML frontmatter
Evals/ Session reviews for continuous improvement
Knowledge/ Reference documents and research

Scripts

Script Purpose
setup.sh Bootstrap: creates symlinks, installs dependencies
scripts/run_skill_evals.py Run skill evaluations against test cases

MCP Server

  • System/mcp/server.py — Custom MCP server for integration tools (Jira, Granola, Linear, Google Calendar)

Hooks

None (zero Claude Code lifecycle hooks configured).

05

Prompts

Prompts — Personal OS (itseffi/personal-os)

Excerpt 1: TDD Skill — Iron Law Pattern

Source: .agents/skills/tdd/SKILL.md Technique: Iron Law (unconditional prohibition + mandatory verification steps)

## The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST


Write code before the test? Delete it. Start over.

**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Delete means delete

## Red-Green-Refactor

### RED - Write Failing Test
Write one minimal test showing what should happen.
- One behavior
- Clear name
- Real code (no mocks unless unavoidable)

### Verify RED - Watch It Fail
**MANDATORY. Never skip.**
- Run the test, confirm it fails (not errors)
- Failure message is expected
- Test passes? You're testing existing behavior. Fix test.

## Red Flags - STOP and Start Over

- Code before test
- Test after implementation
- Test passes immediately
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "This is different because..."

**All mean: Delete code. Start over with TDD.**

Excerpt 2: Verification Skill — Evidence Gate Pattern

Source: .agents/skills/verification/SKILL.md Technique: Evidence-gated completion — all claims require freshly-run verification commands

## The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE


If you haven't run the verification command in this message, you cannot claim it passes.

## The Gate Function

Before claiming any status or completion:

1. **IDENTIFY** - What command proves this claim?
2. **RUN** - Execute the FULL command (fresh, complete)
3. **READ** - Full output, check exit code, count failures
4. **VERIFY** - Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. **ONLY THEN** - Make the claim

Skip any step = lying, not verifying.

## What Requires Verification

| Claim | Requires | Not Sufficient |
|-------|----------|----------------|
| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
| Linter clean | Linter output: 0 errors | Partial check |
| Build succeeds | Build command: exit 0 | Linter passing |
| Bug fixed | Test original symptom: passes | Code changed |
| Phase complete | All objectives verified | Tests passing |
| Task done | Checklist items verified | "I did everything" |

Excerpt 3: AGENTS.md — Backlog Processing Workflow

Source: AGENTS.md Technique: Step-by-step structured workflow with explicit clarification gate

## Backlog Processing Workflow

When user says "clear my backlog", "process backlog", or similar:

### Step 4: Clarify Ambiguous Items
If an item lacks context, priority, or clear next step, STOP and ask the user:
- "What specifically needs to happen for [item]?"
- "What priority is this? P0-P3?"
- "Does this relate to a goal in GOALS.md?"

### Step 6: Present Summary and Clear Backlog
Show user:
- New tasks created
- Any duplicates found
- Any items needing clarification

Then clear `BACKLOG.md` (replace content with `# Backlog\n\n`).
09

Uniqueness

Uniqueness — Personal OS (itseffi/personal-os)

Differs From Seeds

Personal OS is closest to agent-os (Archetype 4 — markdown scaffold) in that it delivers its value through structured markdown files read passively by agents rather than through commands, hooks, or MCP tools. The key deltas are: (1) scope — Personal OS extends far beyond codebase standards into personal productivity, product strategy, stakeholder management, and meeting workflows; (2) runtime portability — it ships explicit per-runtime wrapper files for four AI agents rather than targeting Claude Code exclusively; (3) skill catalog breadth — 47+ skills covering management, strategy, and soft skills that no other framework in the seed set addresses; (4) AgentSkills standard compliance — each skill ships an agents/openai.yaml sidecar for OpenAI-compatible routing metadata, a pattern borrowed from cross-runtime skill registries.

Positioning

The repo occupies a unique niche as a "personal CTO brain" rather than a coding-workflow harness. It targets individual knowledge workers (PMs, founders, engineers) who want AI to handle the full stack of their professional life — not just code. This makes it the only framework in this batch that explicitly covers non-engineering workflows.

Observable Failure Modes

  1. Skill overload: 47 skills means the agent must select the right skill without prompting; progressive disclosure helps but skill selection ambiguity remains
  2. No guardrails without runtime support: The TDD and verification Iron Laws are stated in skill files but enforced only by model compliance — no hooks, no post-task validators
  3. Backlog drift: No automated backlog grooming; BACKLOG.md grows unless user actively processes it
  4. Multi-agent delegation is a stub: The repo documents that subagents are "optional and runtime-dependent" but ships no delegation primitives, leaving users to figure out orchestration per-runtime
04

Workflow

Workflow — Personal OS (itseffi/personal-os)

Core Workflow Phases

1. Backlog Processing

Trigger: User says "clear my backlog", "process backlog" Steps:

  1. Read BACKLOG.md, extract all actionable items
  2. Read Knowledge/ for relevant context
  3. Check existing Tasks/*.md for duplicates (>60% similarity threshold triggers flag)
  4. Clarify ambiguous items (ask for priority, context, goal alignment)
  5. Create Tasks/[descriptive-name].md for each confirmed item
  6. Present summary and clear BACKLOG.md

Artifact: New task files in Tasks/ with YAML frontmatter

2. Daily Guidance

Trigger: User asks "What should I work on today?" Steps:

  1. Read all Tasks/*.md (via glob)
  2. Filter by status: n or s and priority P0/P1
  3. Check GOALS.md for alignment
  4. Propose top 3 tasks with required verification evidence

Artifact: Prioritized daily focus list

3. Skill Execution

Trigger: Agent selects relevant skill for task context Steps:

  1. Agent reads skill metadata from SKILL.md frontmatter
  2. Loads full SKILL.md on cache miss
  3. Executes skill workflow

Artifact: Skill-specific output (analysis, plan, implementation)

4. Session Evaluation

Trigger: End of session Steps:

  1. Run scripts/run_skill_evals.py to assess skill usage quality
  2. Write eval results to Evals/ directory

Artifact: Eval report in Evals/

Phase-to-Artifact Map

Phase Artifact
Backlog Processing Tasks/<descriptive-name>.md
Daily Guidance Prioritized task list (in-session)
Skill Execution Skill-specific output files
Session Evaluation Evals/<session-id>.md

Approval Gates

  1. Ambiguous backlog item: Agent asks user for priority, context, goal alignment before creating task
  2. Duplicate detection: Agent flags >60% similar tasks before creating new one
  3. Goal alignment check: Agent checks GOALS.md before proposing daily focus

Task File Format

---
title: [Actionable task name]
category: [technical|outreach|research|writing|admin|personal|other]
priority: [P0|P1|P2|P3]
status: n  # n=not_started, s=started, b=blocked, d=done
created_date: [YYYY-MM-DD]
due_date: [YYYY-MM-DD]  # optional
estimated_time: [minutes]  # optional
resource_refs:
  - Knowledge/example.md
---
06

Memory Context

Memory & Context — Personal OS (itseffi/personal-os)

State Storage

All state is file-based. No database, no vector store, no external service required for core operation.

File/Directory Contains Persistence
GOALS.md User goals and priorities Project-level, human-maintained
BACKLOG.md Quick capture inbox Project-level, cleared after processing
Tasks/*.md Individual task files with YAML frontmatter Project-level, per-task lifetime
Knowledge/ Reference docs, research, notes Project-level, cumulative
Evals/ Session review records Project-level, cumulative
Resources/ Templates, voice samples Project-level, static

Skill Context Loading (Progressive Disclosure)

Skills use a two-stage loading pattern to conserve context:

  1. Stage 1: Agent reads skill metadata only (name, description, path, agents/openai.yaml — ~200 tokens)
  2. Stage 2: Agent loads full SKILL.md only when skill is selected for a task

This pattern prevents context pollution when many skills are registered.

Cross-Session Handoff

Yes — state persists across sessions through file-based task files. The agent pattern from AGENTS.md:

  • Read Tasks/*.md to resume in-progress work
  • Check status: s (started) tasks on session open
  • Read Progress Log section within each task file for context continuity

Compaction Handling

No explicit compaction mechanism. The Evals/ directory accumulates session reviews; no pruning or summarization is automated.

MCP Memory (Optional)

System/mcp/server.py provides optional MCP integrations for:

  • Google Calendar (schedule awareness)
  • Granola (meeting notes sync)
  • Linear (issue sync)
  • Jira (task sync)

These are optional extensions; core state management works without them.

07

Orchestration

Orchestration — Personal OS (itseffi/personal-os)

Multi-Agent Support

Optional and runtime-dependent. The README notes:

"Optional subagents are supported when the runtime provides agent delegation features (not required for core repo operation)."

No orchestration primitives are shipped in the repo itself.

Orchestration Pattern

None (single-agent sequential execution). The repo is organized around a single agent processing tasks from BACKLOG through to completion.

Isolation Mechanism

None — the agent edits files in-place within the cloned repo.

Multi-Model Support

No — Personal OS is model-agnostic by design but ships no multi-model routing. The model is determined entirely by which runtime the user invokes (Claude Code uses Claude, Codex uses GPT, etc.).

Execution Mode

Interactive-loop — the agent is invoked by the user to process backlog, propose daily focus, or execute specific workflows. There is no continuous daemon or scheduled execution mode in the repo itself (though users could add cron triggers).

Consensus Mechanism

None.

Prompt Chaining

Yes — the backlog processing workflow chains: read BACKLOG → create tasks → update GOALS alignment. The daily guidance workflow chains: read tasks → filter by priority → cross-reference GOALS → propose focus list.

Cross-Tool Portability

High — dedicated wrapper files for Claude Code (CLAUDE.md), Codex (CODEX.md), Pi (PI.md), and OpenClaw (OPENCLAW.md). The core AGENTS.md is runtime-agnostic.

08

Ui Cli Surface

UI & CLI Surface — Personal OS (itseffi/personal-os)

Dedicated CLI Binary

No dedicated CLI binary. Interaction is entirely through the AI agent's native interface (Claude Code chat, Codex prompts, etc.).

Local Web Dashboard

None.

IDE Integration

Runtime-dependent — works wherever the user's chosen AI agent runs (Claude Code, Codex, Pi, OpenClaw). No dedicated IDE extension or plugin.

Observability

  • Skill evaluations: scripts/run_skill_evals.py + Evals/ directory provide a lightweight quality-tracking loop
  • Task progress logs: Each Tasks/*.md file contains a ## Progress Log section for human-readable audit
  • No structured logging, no JSONL audit trail, no replay capability

Setup Script Output

setup.sh creates required symlinks and prints status to stdout. No interactive TUI.

Agent Access Pattern

Users interact with Personal OS by opening the repo in their AI agent and issuing natural language instructions referencing the documented workflows:

1) "Process my backlog from BACKLOG.md into Tasks/**/*.md using AGENTS.md rules."
2) "Show my P0/P1 unblocked tasks aligned to GOALS.md."
3) "Propose today's top 3 with required verification evidence and commands."

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k
A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k
A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367
A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25
A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k
A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k
A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…