Polaris boilerplate: PARA vault, AGENTS.md rulebook, eight polaris skills
This commit is contained in:
Avi
commit
0ca9086de5
39 changed files with 1829 additions and 0 deletions
248
AGENTS.md
Normal file
248
AGENTS.md
Normal file
|
|
@ -0,0 +1,248 @@
|
|||
# Polaris — Operating Manual
|
||||
|
||||
You are operating an **Polaris vault**: a plain-markdown knowledge base, organised by PARA, maintained by an AI agent on behalf of one human — **the owner**. This file is the rulebook. It holds only the rules that change how you behave *by default*. Everything else is one read away:
|
||||
|
||||
| Need | Read |
|
||||
|---|---|
|
||||
| Frontmatter + structure for any page type | `6. Templates/_contracts.md` |
|
||||
| Insertable page skeletons | `6. Templates/*.md` |
|
||||
| Tag taxonomy | `wiki/meta/tags.md` |
|
||||
| How a command executes | `.agents/skills/<name>/SKILL.md` |
|
||||
|
||||
**Thin harness, fat skills.** Before adding anything to this file, ask whether it belongs in a skill. Execution logic is a skill. A page shape is a contract. This file stays small because it is loaded every session.
|
||||
|
||||
---
|
||||
|
||||
## Running a command — works in any agent
|
||||
|
||||
Every command below maps to a skill file. **If your harness loads skills natively, use them. If it does not, read `.agents/skills/<name>/SKILL.md` and follow it exactly** — the file is the spec, not a summary of one.
|
||||
|
||||
| Say this | Skill |
|
||||
|---|---|
|
||||
| `new project:` · `new area:` · `new workstream: [area] / [name]` | `polaris-instantiate` |
|
||||
| `ingest` · `process the inbox` | `polaris-ingest` |
|
||||
| `cascade` | `polaris-cascade` |
|
||||
| `daily note` · `weekly sweep` | `polaris-daily` |
|
||||
| `close workstream: [id]` | `polaris-close` |
|
||||
| `archive: [name]` · `resume [name]` | `polaris-archive` |
|
||||
| `lint` | `polaris-lint` |
|
||||
| `fold the log` | `polaris-fold` |
|
||||
|
||||
**Creates one page** — no skill; copy the matching skeleton in `6. Templates/` and satisfy its contract in `_contracts.md`:
|
||||
|
||||
| Say this | Creates |
|
||||
|---|---|
|
||||
| `new person: [name]` | `3. Resources/People/[Full Name].md` — `tier:` decides whether they can ever flag |
|
||||
| `new decision: [title]` | `4. Decisions/YYYY-MM-DD-[slug].md` |
|
||||
| `new thread: [title]` | `3. Resources/Threads/[slug].md` — ask for `domains:` and `people:` |
|
||||
|
||||
**Read-and-report** — no skill; read the named sources and answer in chat:
|
||||
|
||||
| Say this | Reads |
|
||||
|---|---|
|
||||
| `status` · `what's blocked` · `workstreams` | every `*_hub.md` |
|
||||
| `sends` | `next:` from every live Project hub |
|
||||
| `people` · `follow up: [name]` | person pages |
|
||||
| `threads` | `3. Resources/Threads/` |
|
||||
| `decisions` | `4. Decisions/` |
|
||||
| `log this: [note]` | append a timestamped line to today's note in `0. Inbox/` |
|
||||
|
||||
**Output routines** — read sources, return a document, save to `3. Resources/Outbox/YYYY-MM-DD-[type]-[context].md`:
|
||||
|
||||
| Routine | Shape |
|
||||
|---|---|
|
||||
| `meeting brief: [name]` | context → what's live → what to cover → open questions → recent contact |
|
||||
| `project snapshot: [project]` | what it is → state → moving → blocked → next → key people |
|
||||
| `outbound draft: [name] / [purpose]` | To / Subject / Body |
|
||||
|
||||
**Order of operations:** `ingest` puts new material into the numbered folders. `cascade` syncs `wiki/` with what's already there. **Run cascade at the end of any session that changed something.**
|
||||
|
||||
---
|
||||
|
||||
## How the vault is organised
|
||||
|
||||
**Numbered folders are where knowledge lives.**
|
||||
|
||||
- `0. Inbox/` — daily notes and raw captures. Processed captures move to `0. Inbox/processed/YYYY-MM/`.
|
||||
- `1. Projects/<Area>/<Name>/` — finite work with a written *done-when*. Hub: `<ID>_hub.md`.
|
||||
- `2. Areas/<Area>/` — ongoing responsibilities that are never done. Hub: `<Area>_hub.md`. Each Area has a `knowledge/` folder — its permanent memory.
|
||||
- `3. Resources/` — `People/`, `Threads/` (cross-cutting concerns), `Research/` (reusable knowledge belonging to no single Area), `Outbox/` (generated documents).
|
||||
- `4. Decisions/` — the decision log. Immutable.
|
||||
- `5. Archive/` — finished or retired work. Never deleted.
|
||||
- `6. Templates/` — page skeletons and the contracts they implement.
|
||||
|
||||
**`wiki/` is navigation, not content.**
|
||||
|
||||
- `wiki/hot.md` — **current state.** The one file to read at the start of every session. Rewritten by each cascade. Hard cap 80 lines.
|
||||
- `wiki/index.md` — the inventory: every hub, person, thread and decision, one line each. Rebuilt by cascade when structure changes.
|
||||
- `wiki/log.md` — append-only ledger of every operation. Newest first.
|
||||
- `wiki/folds/` — old log entries rolled up by `polaris-fold`, kept verbatim.
|
||||
- `wiki/meta/` — `tags.md`, `holds.md`, `open-questions.md`, and the one current lint report.
|
||||
|
||||
**Rule:** all knowledge lives in the numbered folders. `wiki/` reflects their state; it never holds content. **`wiki/` must stay smaller than the numbered folders** — if navigation outgrows the territory, it has become content.
|
||||
|
||||
**Start every session by reading `wiki/hot.md`.**
|
||||
|
||||
---
|
||||
|
||||
## Ledgers append. State replaces. Derived expires.
|
||||
|
||||
| Class | Files | Policy |
|
||||
|---|---|---|
|
||||
| **Ledger** | `4. Decisions/`, `wiki/log.md` | **Append only.** Never edit a past entry. |
|
||||
| **State** | hubs, person pages, `wiki/hot.md`, `wiki/index.md` | **Replace in place.** Never stack dated sections. Answers "what's true now." |
|
||||
| **Derived** | lint reports, folds | **Regenerable.** Keep one current lint report; archive the old one. |
|
||||
|
||||
**Appending to state is the defect.** When state changes, replace it — the log already holds what it used to say.
|
||||
|
||||
**One exception to "never edit a ledger":** when a file moves, repoint the *link target* in ledger entries so it resolves again. Change the pointer, never the prose.
|
||||
|
||||
---
|
||||
|
||||
## Attribute, don't assert
|
||||
|
||||
**A fact that entered the vault from a source belongs to that source until the owner confirms it.**
|
||||
|
||||
- ✅ *"The proposal lists Sam as a co-founder."* ❌ *"Sam is a co-founder."*
|
||||
- Every file created from external material records its provenance: file, sender, URL, conversation, date. If unknown, write **"source unrecorded"** — never leave it blank.
|
||||
- **Summary layers speak in the vault's voice.** Hub bullets, `hot.md` and `log.md` carry the attribution or they don't carry the claim.
|
||||
- **Contradiction inside one source beats agreement across copies.** Five files agreeing may be five copies of one wrong line.
|
||||
- **Absence in the vault is not absence in the world.** Say *"not found,"* never *"does not exist."*
|
||||
|
||||
---
|
||||
|
||||
## Repair yourself. Ask before changing.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Repair** | Restores what a file was already trying to say — a dead link, a misspelled name, a rule contradicting itself, a missing required field you can derive. **Do it. Don't ask.** Record it in the log. |
|
||||
| **Change** | Alters what a file claims, or how the vault is shaped. **Never without asking.** |
|
||||
|
||||
**If you cannot tell which one you are about to do, it is a change — ask.** A defect found is a defect fixed: the instance *and*, where you can, the mechanism that produced it.
|
||||
|
||||
**Don't hand the owner work the vault can do.** If an answer is derivable from files you can read, derive it. Questions are for what only the owner knows or decides.
|
||||
|
||||
---
|
||||
|
||||
## Fences
|
||||
|
||||
Paths listed here are **never read, edited, scanned, or summarised** by any skill or session. Links *into* them are checked for existence only. **Only the owner adds or lifts a fence.**
|
||||
|
||||
| Fenced path | Since |
|
||||
|---|---|
|
||||
| *(none)* | |
|
||||
|
||||
---
|
||||
|
||||
## Status vocabulary
|
||||
|
||||
**Projects:**
|
||||
|
||||
| Status | Means |
|
||||
|---|---|
|
||||
| `open` | **The working status.** Real, identified work. No clock, no cap. Needs `done_when:`. `next:` optional. |
|
||||
| `paused` | Deliberately not now. Needs `paused_because:`. **Invisible to every freshness check** — that is the point. |
|
||||
| `closed` | Done. Deliverable migrated to its Area's `knowledge/` via `polaris-close`. |
|
||||
| `archived` | Lives in `5. Archive/`. |
|
||||
|
||||
**Areas** are `standing` or `archived`. A standing Area carries no attention status — never compute freshness or drift on one.
|
||||
|
||||
**A never-started project is `open`, not `paused`.** They are different claims.
|
||||
|
||||
---
|
||||
|
||||
## The `next:` field — what's owed
|
||||
|
||||
A Project hub may carry `next:` — one move per entry, verb first:
|
||||
|
||||
```
|
||||
next: "send → Sam Example — revised quote [since 2026-01-05]"
|
||||
```
|
||||
|
||||
| Verb | Means |
|
||||
|---|---|
|
||||
| `send` | A message to a person is owed. The work is not blocked on effort. |
|
||||
| `wait` | Waiting on someone else's clock. |
|
||||
| `build` | Solo work. |
|
||||
| `decide` | A call only the owner can make. |
|
||||
|
||||
`send` and `wait` name a person. **`[since …]` is the age authority** — without it, fall back to git history, and if neither is trustworthy **render no age at all. A missing age is fine; a wrong one destroys trust in the whole table.**
|
||||
|
||||
---
|
||||
|
||||
## Holds — when life interrupts everything
|
||||
|
||||
A hold is involuntary and cross-cutting (illness, travel, a family event); `paused` is deliberate and per-project. Holds live in `wiki/meta/holds.md`, one line each: start, end, reason, scope. Append-only.
|
||||
|
||||
- **While a hold is open**, covered items render `held` — no age.
|
||||
- **After it closes**, render two clocks: the lead number from the later of `[since]` and the hold's end, the true elapsed time in parentheses — `3d (since 01-05, 11d held)`.
|
||||
- A hold covers an item only if the item predates the hold's start. **`[since]` is never rewritten.**
|
||||
- A hold changes how ages *render*. It never means nothing is owed.
|
||||
|
||||
---
|
||||
|
||||
## A capture gap is not a defect
|
||||
|
||||
Days with no notes are a normal fact about a human. **Report the consequence** (stale data, false flags) **plainly, then re-read reality from the owner and move on.** Don't editorialise, don't build a mechanism to prevent it, don't carry it as an open item.
|
||||
|
||||
---
|
||||
|
||||
## The classification test
|
||||
|
||||
When something new arrives, in this order:
|
||||
|
||||
1. Can you write **"done when ___"** right now, in one sentence? → **Project**
|
||||
2. Is the honest answer "it's never done," and will it hold projects? → **Area**
|
||||
3. Neither, but facts and people attach to it? → **Resource or person page** — not a hub
|
||||
|
||||
**Reference material:** strip any single Area's context from the note. **Claim still holds → `3. Resources/Research/`** (topic tags only). **Claim needs that Area's frame → `2. Areas/<Area>/knowledge/`.**
|
||||
|
||||
**The vault holds knowledge, not files.** Binaries (PDFs, decks, images, spreadsheets) live outside the vault; the vault holds a markdown note of what they say, attributed, with a path to the file.
|
||||
|
||||
---
|
||||
|
||||
## Naming conventions
|
||||
|
||||
- **Folders:** Title Case with spaces.
|
||||
- **Workstream IDs:** `<PREFIX>-<N>` — a short uppercase prefix set once on the Area hub (`id_prefix:`), and a counter (`workstream_counter:`) that is the source of truth. **IDs are never reused.**
|
||||
- **Hub files:** Project → `<ID>_hub.md`. Area → `<Area>_hub.md`. **The `_hub` suffix is load-bearing** — every glob matches the suffix, never the whole name.
|
||||
- **People:** `Full Name.md`.
|
||||
- **Dated files** — decisions, outbox documents, and any ledger/tracker/report filed on a hub — `YYYY-MM-DD-[slug].md`, dated at creation.
|
||||
- **Inbox captures:** `YYYY-MM-DD-HHMM [slug].md`. Daily notes: `YYYY-MM-DD daily.md`. Sweeps: `YYYY-MM-DD weekly-sweep.md`.
|
||||
- **An ID never travels alone in prose.** Write `WEB-3 Pricing Page`, not bare `WEB-3`. Bare IDs are fine in frontmatter, filenames, and folders.
|
||||
- **Links:** `[[wikilinks]]` without the `.md` extension. They render in Obsidian and read fine as plain text anywhere else.
|
||||
- **A label the owner can't read is a defect in the label.**
|
||||
|
||||
---
|
||||
|
||||
## Vocabulary enforcement
|
||||
|
||||
Canonical spellings of names and terms. `polaris-lint` parses this table — keep the two-column shape.
|
||||
|
||||
| Always use | Never use |
|
||||
|---|---|
|
||||
| *(add rows as corrections arise)* | |
|
||||
|
||||
---
|
||||
|
||||
## Log entries classify themselves
|
||||
|
||||
Every `wiki/log.md` heading carries `[build]` or `[vault]`:
|
||||
|
||||
```
|
||||
## 2026-01-05 — [build] Pricing page shipped
|
||||
## 2026-01-05 — [vault] Ingested three captures; two person pages created
|
||||
```
|
||||
|
||||
A `[build]` entry **must** carry a `Shipped:` line naming what exists now that didn't before. **If you can't fill it, it's `[vault]`.**
|
||||
|
||||
---
|
||||
|
||||
## After every session
|
||||
|
||||
1. **`cascade`** — rewrites `hot.md`, appends one log entry, rebuilds `index.md` if structure changed.
|
||||
2. **Commit, if the vault is a git repo.** Stage explicit paths (not `git add -A`), write a message that says *why*. Nothing auto-commits.
|
||||
|
||||
## Delegation (optional)
|
||||
|
||||
`polaris-cascade`, `polaris-lint` and `polaris-fold` are mechanical — glob, parse, compare. If your harness supports subagents, they can run on a cheaper model. **The main session still verifies any count or name before it reaches `hot.md` or `log.md`**; a subagent's claim that it verified something is not verification. `polaris-ingest` and `polaris-daily` require judgment and stay in the main session.
|
||||
Loading…
Add table
Add a link
Reference in a new issue