# Personal Operating System

This workspace is a lightweight system for reducing overwhelm while using Pi as a personal assistant, sysadmin helper, learning assistant, and coding partner.

## Purpose

Keep work visible, scoped, and resumable.

The system separates:

- **Inbox**: quick capture of thoughts and requests
- **Tickets**: actionable units of work
- **Specs**: agreed plan before non-trivial building or infrastructure changes
- **Projects**: collections of related work
- **Runbooks**: repeatable operating procedures
- **Knowledge notes**: durable learning, eventually mirrored into Obsidian

## Core Rules

1. Capture first, organize later.
2. Anything unclear goes into the inbox.
3. Anything bigger than about 30 minutes should get a ticket.
4. Anything involving infrastructure, security, data, or service changes should get a spec before execution.
5. Keep only 1–3 active tickets at a time.
6. Document decisions that affect future work.
7. Turn repeated procedures into runbooks.
8. Prefer safe, reversible changes; take backups/snapshots before risky work.

## Statuses

Use these statuses for tickets and project items:

- `Inbox` — captured but not clarified
- `Planned` — clarified and ready for prioritization
- `In Progress` — currently being worked
- `Blocked` — cannot proceed due to missing dependency/problem
- `Waiting` — waiting on user/external event
- `Done` — completed
- `Archived` — no longer active/relevant

## Item Types

- `Task` — small concrete action
- `Ticket` — actionable work item with context and acceptance criteria
- `Project` — related tickets toward a larger outcome
- `Spec` — planned build/change with requirements and open questions
- `Runbook` — repeatable procedure
- `Decision` — durable choice and reason
- `Note` — learning/reference material

## Workflow

### 1. Capture

Raw ideas go to `inbox/capture.md`.

### 2. Clarify

When an item becomes actionable, create a ticket in `tickets/active/` or add it to `tasks/backlog.md` if it is very small.

### 3. Specify

Before building or changing infrastructure, create or update a spec under the related project, for example:

```text
projects/nextcloud/spec.md
```

The spec should include requirements, assumptions, open questions, risks, and acceptance criteria.

For complex, risky, multi-file, or context-heavy work, use the Nimrod QRSPI adaptation in `docs/qrspi-adaptation.md`. Its phase artifacts live in:

```text
tickets/artifacts/<ticket-id>/
```

The key rule is: each phase writes a markdown artifact, and later phases read only the artifacts listed for that phase unless they explicitly state why more context is needed.

### 4. Execute

Work from `tasks/now.md` and at most 1–3 active tickets.

### 5. Document / Close

After work, update as appropriate:

- ticket status
- project notes
- runbook
- system inventory/status
- decision log
- knowledge notes

For meaningful work, do not mark the ticket done until verification evidence is recorded and a separate review/verifier pass has checked the result against the acceptance criteria. See `docs/autonomous-ticket-execution-model.md` and `docs/verification-and-definition-of-done.md`.

## Pi Assistant Behavior

When the user asks for work that is vague or large, Pi should first help turn it into a ticket/spec rather than immediately executing.

For infrastructure work, Pi should:

1. clarify the desired outcome
2. draft/update the ticket
3. draft/update the spec
4. list missing questions
5. wait for approval before risky execution
6. document the result