POS -- Personal Operating System for AI-Assisted Development

A file-based workflow system for managing multiple professional contexts through AI-powered agents. POS coordinates work across jobs, side projects, freelance clients, and personal goals from a single repository. It works with any AI coding tool that reads markdown files -- Claude Code, Cursor, Windsurf, Copilot, Goose, OpenCode, or a plain LLM session.

Quick Start

git clone https://github.com/abuango/pos-template my-workflow
cd my-workflow
cp pos.yaml.example pos.yaml   # Edit with your details
./scripts/pos-init.sh           # Interactive setup

The setup script asks for your name, timezone, and your first work context. It creates pos.yaml, generates AGENTS.md and CLAUDE.md, and scaffolds your directory structure.

After setup, any AI tool dropped into the repo reads AGENTS.md and knows what the system is, what is currently active, how to register itself, where to find work, and how to hand off when done.

Features

• Multi-context management -- Switch between your day job, freelance clients, side projects, and personal goals without losing state
• Cross-tool AI coordination -- Works with Claude Code, Cursor, Windsurf, Copilot, Goose, OpenCode, and any tool that reads AGENTS.md
• Session tracking -- Every AI session is registered, tracked, and handed off cleanly. No lost context between conversations
• Task queue -- A global queue lets any AI model pick up work matched to its capability level
• Config-driven -- One pos.yaml file defines your entire setup. Everything else is generated
• Skill template system -- Shared partials injected at build time prevent drift across skills
• Cross-skill artifacts -- Skills write artifacts that downstream skills discover automatically
• Self-improving feedback loop -- Skills self-rate on completion, surfacing friction points
• Static validation -- Automated checks catch broken skills before they reach users
• Multi-model coordination -- Different AI models handle different tasks based on capability level

How It Works

The Config File

pos.yaml is the single source of truth for your instance. It defines your identity, your work contexts, and schedule defaults. Run ./scripts/pos-generate.sh after editing to regenerate AGENTS.md and CLAUDE.md.

See pos.yaml.example for a starter configuration.

The Session Lifecycle

Every AI session follows three steps:

1. REGISTER  ->  ./scripts/session-register.sh "tool-name" "context" "level"
2. WORK      ->  Update session file as you go
3. CLOSE     ->  ./scripts/session-close.sh "tool-name" "summary"

Tools that cannot run scripts write YAML files directly instead. Both paths produce the same result: a tracked session with a handoff record.

Capability Levels

AI models self-assess their capability when registering:

Level	Examples	Suited For
basic	Haiku, Flash, 4o-mini	Status checks, docs, formatting
standard	Sonnet, GPT-4o, Gemini Pro	Features, bugs, code review
advanced	Sonnet+, advanced models	Architecture, refactoring
reasoning	Opus, o3, deep reasoning	Planning, root cause analysis

The task queue filters work by capability so models only see tasks they can handle.

Cross-Tool Compatibility

POS uses the AGENTS.md standard for cross-tool compatibility:

Tool	Context Loading	Session Management
Claude Code	AGENTS.md + CLAUDE.md (auto-loaded)	Automatic (SessionStart hook)
Cursor	AGENTS.md via .cursorrules	Manual (script or YAML)
Windsurf	AGENTS.md via workspace rules	Manual (write YAML)
Copilot	.github/copilot-instructions.md	Manual (write YAML)
Goose	AGENTS.md (native)	Manual (run script)
OpenCode	AGENTS.md (native)	Manual (run script)
Any LLM	Paste AGENTS.md as system prompt	Manual (write YAML)

Directory Structure

pos.yaml                         # Your config
AGENTS.md                        # AI entry point (generated)
CLAUDE.md                        # Claude Code memory (generated)
.state/snapshot.yaml             # System state (generated)
.rules/universal.md              # Universal rules (single source of truth)
.handoff/
  queue.yaml                     # Task queue
  sessions/                      # Active sessions
  handoffs/                      # Handoff records
  artifacts/                     # Cross-skill state persistence
  feedback/                      # Skill self-rating feedback
  QUICK-START.md                 # Agent onboarding
  templates/                     # YAML templates
.skills/                         # Portable Skill Definitions
  registry.yaml                  # All skills
  *.md                           # Portable skill docs
.claude/
  skills/                        # Claude Code skill definitions
    {skill-name}/
      SKILL.md.tmpl              # Source template (human-editable)
      SKILL.md                   # Generated (do not edit directly)
  rules/                         # Auto-loaded rule reminders
scripts/                         # 21 shell scripts
  pos-config.sh                  # Shared config reader
  pos-init.sh                    # Set up a new instance
  pos-generate.sh                # Regenerate AGENTS.md/CLAUDE.md
  generate-skills.sh             # Generate SKILL.md from templates
  validate-skills.sh             # Static validation for all skills
  repo-manager.sh                # Git repo management
  sync-state.sh                  # Refresh .state/snapshot.yaml
  session-register.sh            # Start a session
  session-close.sh               # End a session with handoff
  ...                            # + 12 more (see Scripts section)
templates/
  skills/partials/               # Shared skill template partials
contexts/
  {your-contexts}/               # Work contexts (jobs, projects, personal)
    status.yaml                  # Current state
    projects/                    # Code repos
    plans/                       # Sprint plans
    docs/                        # Architecture, decisions

Scripts

21 shell scripts power the system. Key scripts by category:

Setup and Generation

Script	Purpose
pos-init.sh	Interactive setup (first time only)
pos-generate.sh	Regenerate AGENTS.md/CLAUDE.md from pos.yaml
pos-config.sh	Shared config reader (sourced by other scripts)

Skills

Script	Purpose
generate-skills.sh	Generate SKILL.md from .tmpl templates
generate-portable-skills.sh	Create portable .skills/*.md for non-Claude tools
validate-skills.sh	Static validation for all skill files

Sessions and Handoffs

Script	Purpose
session-register.sh	Register an AI session
session-close.sh	Close session and create handoff record
create-task.sh	Create a task in the queue
task-start.sh	Mark a task as started
task-complete.sh	Mark a task as complete

State and Health

Script	Purpose
sync-state.sh	Aggregate all status into .state/snapshot.yaml
sync-queue.sh	Populate task queue from context status
check-health.sh	System health checks (includes skill validation)
daily-sync.sh	Cron-compatible daily sync
archive-status.sh	Prune bloated status.yaml files
aggregate-feedback.sh	Summarize skill self-rating feedback
lib-artifacts.sh	Cross-skill artifact persistence helpers

Workflow

Script	Purpose
plan-gate.sh	Enforce Plan-Approve-Execute workflow
approve-plan.sh	Approve a pending plan
repo-manager.sh	Git repository management across contexts

Requirements

• Bash 3.2+ (ships with macOS and most Linux distributions)
• Git
• Any AI coding tool (Claude Code, Cursor, Windsurf, Copilot, Goose, OpenCode, or a plain LLM)

No external dependencies. No databases. No cloud services. Everything is files.

Customization

Adding a Context

1. Add to pos.yaml under contexts:
2. Create contexts/{id}/status.yaml
3. Run ./scripts/pos-generate.sh

Adding Skills

1. Create a skill template in .claude/skills/{name}/SKILL.md.tmpl
2. Run ./scripts/generate-skills.sh to build SKILL.md
3. Restart your AI tool to pick up the new skill

Contributing

Contributions are welcome. Please open an issue before submitting large changes so the approach can be discussed first.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes
4. Run ./scripts/validate-skills.sh if you modified skills
5. Submit a pull request

Documentation

Comprehensive guides are in the docs/ directory:

Guide	What You Will Learn
Getting Started	Clone, configure, initialize, and run your first session end-to-end
Architecture	System design: config-driven generation, file categories, session lifecycle, tiered context loading
Skills Guide	How skills work: structure, tool restrictions, templates, validation, creating your own
Prompting Guide	How to prompt AI tools effectively — script commands AND equivalent prompts for tools that cannot run scripts
Cross-Tool Setup	Setup instructions for Claude Code, Cursor, Windsurf, Copilot, Goose, and raw LLMs
Scripts Reference	Full reference for all 21 scripts with usage examples
Common Workflows	Step-by-step guides: adding contexts, switching, planning, handing off, health checks
Troubleshooting	14 common issues with symptoms, causes, and fixes

Where to Start

• New to POS? Start with Getting Started
• Setting up a non-Claude tool? Go to Cross-Tool Setup
• Want to create a skill? Read Skills Guide
• Need the right prompt? Check the Prompting Guide
• Something broken? See Troubleshooting

Blog Series

This project is also documented in a multi-part blog series at abuango.me covering design philosophy, architecture decisions, and practical patterns.

Disclaimer

This software is provided "as is" without warranty of any kind. POS is a workflow coordination tool — it does not execute code on your behalf, but it does instruct AI tools that may modify files, run commands, and interact with external services.

You are responsible for:

• Reviewing all AI-generated code and plans before accepting them
• Ensuring AI tools operate within appropriate permission boundaries
• Protecting sensitive data (API keys, credentials, secrets) from being committed or exposed
• Validating that scripts behave correctly in your environment before relying on them
• Backing up your work — POS uses git, but you should verify your backup strategy

POS does not:

• Send data to any external service (everything is local files)
• Require any cloud account or subscription
• Collect telemetry, analytics, or usage data
• Access any system outside your repository unless you configure it to (e.g., MCP integrations)

The AI tools you use with POS (Claude Code, Cursor, Copilot, etc.) have their own terms of service, privacy policies, and data handling practices. Review those independently.

See LICENSE for the full legal terms.

License

MIT -- see LICENSE for details.