@amoree-code/ocean 0.0.0-stage → 1.2.0

package/skills/core/graft/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: graft
+description: This repo is indexed by graft/. For ANY task here, whether
+  understanding how something works, finding where code lives, tracing what
+  calls a symbol or what a change breaks, or scoping an edit, get your context
+  from graft before grepping or reading source files.
+---
+
+# graft
+
+`graft/` holds a graph of this repo: small markdown nodes that each explain one
+part in prose and name the exact `file:line` spans they cover, plus a wiring
+graph of who-calls-what. Querying a node costs a few hundred tokens; rebuilding
+that understanding by reading source costs thousands, and misses the edges.
+
+Every command below is `$0`, needs no API key, and returns in under a second.
+There are six of them. **Pick the one that fits the task, run it, act on the
+answer; don't chain tools hoping for more. Most tasks need one call.**
+
+## The tools
+
+### 1 · `graft ask "<question>" --source`: locate + understand (the default)
+Ranked retrieval over the graph, routed automatically between prose nodes and
+the wiring graph, returning the top hits with exact `file:line`.
+- `--source` inlines the code at each hit, the ≤8-line **crux** of each
+  definition, so the result IS the code you need, no follow-up file read. Add
+  `--full` only when the crux is too small to act on.
+- `--in <path>` narrows to a subtree before ranking; `-n N` caps results (default 8).
+- **Use it when** the question is conceptual or locational: "how does auth
+  work", "where is rate-limiting handled", "what assembles the request pipeline".
+- One ask usually answers. A genuinely multi-part question needs one ask per
+  distinct sub-aspect, never the same question reworded. Few or weak hits mean
+  switch tool (grep / skeleton / callers), don't re-ask.
+
+### 2 · `graft grep "<pattern>"`: exhaustive find
+Regex (or `--fixed` for a literal) over every indexed file, hits **grouped by
+enclosing symbol** and ranked by coupling; it also reports files it couldn't read.
+- **Use it when** you need every occurrence: all call sites, all uses of a
+  constant, all providers. `ask` is ranked top-N and *will* miss instances;
+  grep won't. One grep replaces a spray of asks.
+- Search a **short symbol name or literal**, not a full guessed signature: an
+  over-specific regex (`func (s *Server) GenerateHandler`) returns nothing even
+  when the code is indexed. If a grep misses, **loosen it** (drop the receiver
+  and signature, keep the bare name) and retry `graft grep` — do NOT switch to
+  raw `grep -rn`, which is slower and unranked.
+- `-i` case-insensitive; `--in <path>` scopes to a subtree. Raw `grep -rn` is
+  only for files graft genuinely doesn't index (docs, configs, brand-new files).
+
+### 3 · `graft skeleton <file>`: a file's API at a glance
+Signatures-only view of one file (every function / method / type with its span)
+in ~200 tokens, ~10x cheaper than reading the file.
+- **Use it when** you need "what's in this file / what can I call here" before
+  editing or wiring into it. One skeleton is the whole answer for a file; don't
+  re-skeleton the same file, and don't skeleton every file `map` already named.
+
+### 4 · `graft callers <symbol>`: the exact edges
+Precomputed call/reference edges, not a text search. Symbol can be bare
+(`Foo`), qualified (`Class.method`), or package-qualified (`pkg.Fn`).
+- default `--direction in`: **who calls/references** this; run before you
+  rename, delete, or change its signature.
+- `--direction out`: **what this symbol itself calls/depends on** (the old `callees`).
+- `--depth N`: walk transitively N hops for the **full blast radius** (the old
+  `impact`); `--depth 2` is the usual "what breaks if I touch this".
+- `--depth all`: the **entire connected closure** — every source reachable
+  through the edges. Reach for this before a **refactor, rename, or any
+  multi-file change**: it surfaces the sibling and downstream files (platform
+  variants, a module you must split out) that a single-file edit would miss.
+
+### 5 · `graft map`: orientation for an unfamiliar repo or area
+A token-budgeted tour: directory clusters, per-directory hubs, and global
+hotspots, straight from the wiring graph.
+- **Use it when** you land in a repo cold or are asked for "the architecture".
+  `map` alone is the answer: read the hub cards it names; do NOT then skeleton
+  or ask your way through every subsystem it lists. `--max-dirs N` widens it.
+
+### 6 · Lifecycle: `graft build` / `graft check`
+Every tool above refreshes the graph itself before answering, so what those tools
+return always describes the code as it is right now — including edits you just made
+and have not committed. You do **not** need to run `build` after editing.
+
+One caveat, if you `grep` the markdown under `graft/` directly: those cards are a
+projection, rebuilt at the end of the turn rather than on each query, so after an edit
+they can lag. The tools above never do — prefer them, and treat a card's spans as
+stale if you have edited that file this turn.
+
+`build` is for the LLM layer (`--deep` adds a concept map; skip unless asked);
+`check` fails when `graft/` is stale, for CI.
+
+## Scenarios: the shortest path through a coding task
+
+| When you're… | Reach for | Calls |
+|---|---|---|
+| Onboarding / "explain this codebase" | `graft map`, then read the named hub cards | 1 |
+| Understanding a flow ("how does X work") | `graft ask "<flow>" --source` | 1 |
+| Finding where a change belongs | `graft ask "where is <behavior>" --source` | 1 |
+| Editing a symbol you can already name | `graft grep "<symbol>"`, edit at the `file:line` (skip `ask` — you know where it is) | 1 |
+| Renaming / deleting / changing a signature | `graft callers <sym> --depth 2` first | 1 |
+| Refactor / multi-file change (before editing) | `graft callers <sym> --depth all` — map every connected file, don't stop at the first | 1 |
+| "What does this depend on?" | `graft callers <sym> --direction out` | 1 |
+| Finding every occurrence of a pattern | `graft grep "<literal>"` | 1 |
+| "What's the API of this file?" | `graft skeleton <file>` | 1 |
+| Debugging a failure in area X | `graft ask "<symptom>" --source`, then `callers` on the suspect | 1–2 |
+| Judging a diff's risk before merge | `graft callers <changed sym> --depth 2` | 1 / symbol |
+| Working inside one repo of a monorepo | add `--in <scope>/` to ask / grep / callers | n/a |
+
+In a multi-repo workspace, graft ranks fairly so the biggest repo can't drown
+the rest, and every hit carries a `[scope/]` label naming its sub-project; when
+you already know where you're working, narrow with `graft ask "<task>" --in <scope>/`.
+
+## Spend the fewest calls
+- A node's `covers:` list already gives exact `file:line` for every symbol, so
+  cite straight from it. The spans are generated from source and authoritative;
+  don't re-open or re-grep files to "double-check".
+- When the task already names the file or symbol to change, go straight there:
+  `graft grep "<symbol>"` for the exact `file:line`, then edit. Reserve
+  `graft ask` for when you don't yet know where the code lives — an `ask`
+  round-trip is wasted on a target you can already name.
+- Trust the answer and act. Reach for a second tool only when the first genuinely
+  fell short: weak hits, a truncated span, or a need to be exhaustive.
+- If graft names a path that isn't on disk, its index is ahead of your checkout
+  (a branch switch or unpulled move). Don't read the missing file — `graft grep`
+  the symbol to find where it lives now, or run `graft build` to refresh.
+
+## Report what graft saved, every turn
+Each retrieval tool **opens** its output with a `[graft] tokens saved ≈ N` line:
+the estimated tokens that call saved versus reading the files it covers whole.
+Whenever you used any graft tool in a turn, close your reply with a one-line
+tally summing those numbers across every graft call you made, e.g.
+`🌱 graft saved ~12,400 tokens this turn (3 calls)`. A call with no such line
+(tiny files, where the pointers cost as much as the source) saved nothing, so
+skip it. This is the per-turn figure; the statusline carries the running
+session total.
+
+Once a turn has been billed, each line also states what that call was worth in
+dollars, at the rate this session is actually paying for input tokens — include
+that total alongside the tokens, e.g. `🌱 graft saved ~12,400 tokens (~$0.04)
+this turn`. When a line carries no dollar figure, report tokens alone rather
+than pricing them yourself.
+
+**Never pipe a graft command through `head`, `tail`, or `sed -n`.** Every tool
+is already capped and states what it dropped; clipping it costs you hits you
+asked for, and it silently drops the savings line the statusline's running
+total is parsed from.
+
+## When graft isn't enough
+- Span truncated ("+N more lines"): open the file at that exact range.
+- A node lacks a detail: ask a more specific question; only then read source at
+  the exact `file:line`, never a whole file to rebuild understanding graft gives.
+- You may also grep / ls / cat inside `graft/` directly (plain markdown;
+  `graft/INDEX.md` indexes the nodes), but the tools above are faster and
+  exhaustive where it matters, so reach for them first.
+
+When the graft MCP server is connected, these are exposed as tools too:
+`graft_find_code`, `graft_find_all`, `graft_file_api`, `graft_trace_calls` (with
+`direction` / `depth`), `graft_repo_map`, `graft_check_freshness`. Use whichever surface is
+available; the guidance is identical.

package/skills/core/loop/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: loop
+description: Continue a bounded task across runs with checkpoints, verification, retries, and explicit stop conditions.
+version: 1.0.0
+category: core
+---
+
+# Loop
+
+Use when a task must continue across time or while the owner is unavailable.
+
+Before starting, require a task id, profile, scope, finite budget, maximum iterations, retry policy, and success condition. Each iteration must:
+
+1. Read the task state and latest checkpoint.
+2. Do one bounded unit of work.
+3. Verify the unit with a real check.
+4. Write a concise checkpoint with the next action.
+5. Stop on success, budget exhaustion, repeated failure, missing input, authentication, or a consequential action requiring approval.
+
+Never loop blindly over irreversible actions. Preserve the session and task state so a later run resumes from the checkpoint. Report completed work, evidence, remaining work, and the stop reason.

package/skills/core/session-handoff/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: session-handoff
+description: Produce a compact continuation packet with the next action and verification commands.
+version: 1.0.0
+category: core
+---
+
+# Session handoff
+
+Create a portable continuation packet, not a transcript.
+
+Include the project and task, one-line objective, verified results, important decisions,
+changed paths, blockers, the next concrete action, and exact verification commands. Point to
+durable files instead of copying their contents. Never include credentials, tokens, cookies,
+private documents, or unnecessary session identifiers.

package/skills/core/use-browser/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: use-browser
+description: Open a supplied URL, understand the user's requested outcome from the live page, complete the browser task, and verify the result.
+version: 1.0.0
+category: core
+---
+
+# Use Browser
+
+Use when the user gives a URL and asks the agent to complete, fill, test, submit, or otherwise operate the page.
+
+The skill defines the task and verification contract. When the user asks for their own
+signed-in Chrome or a shared MCP connection, the routes are in `docs/browser-clients.md`:
+the marketplace `dev.ocean/chrome-devtools` entry, the browser bridge, or Playwright MCP.
+Ocean's `ocean browser` capability remains the deterministic local backend for repeatable
+JSON task files.
+
+Use Ocean's `ocean browser` capability through the terminal as the default browser backend. Do not switch to `claude-in-chrome`, an extension, or another browser connector unless the user explicitly asks for that backend. If Ocean cannot detect or open a browser, report the exact command result and stop; do not ask the user to install a different browser extension as the first workaround.
+
+## Cost-aware execution
+
+Keep browser work bounded and token-efficient. Use one `observe` and one targeted `read` before acting, prefer `extract` over rereading the whole page, and keep page text bounded. Do not run exploratory shell scripts or repeated reload/undo cycles when a deterministic browser operation is unavailable. Use at most one retry for a reversible step and no automatic retry for submit, upload, purchase, message, or other consequential actions. If the live state is ambiguous after the bounded attempt, stop and report the blocker instead of spending more tokens guessing.
+
+## Workflow
+
+1. Treat the URL as the starting location, not as permission to perform every possible action on the site.
+2. Open or reconnect to an Ocean browser session with a persistent profile. Navigate to the URL.
+3. Inspect the live page with `observe`, `read`, and targeted `extract`. Identify the page's current state, the user's intended outcome, required fields, available controls, and a concrete success signal.
+4. Build the smallest step sequence that reaches the requested outcome. Prefer stable labels, roles, names, ids, and visible text. Use editor selectors for `contenteditable`, CodeMirror/Monaco containers, and `frame >>> editor` for same-origin iframe editors.
+5. For code-editor changes, use `ocean browser replace-text <session-id> <selector> <old-text> <new-text> --occurrence <n>` when replacing a specific token. Never simulate a precise replacement by clicking and typing into the middle of a Monaco/CodeMirror line. Verify the returned editor value and then re-read the page.
+6. Execute through Ocean browser operations or a bounded browser task file. Keep the task file small, cap retries at 0–1, and cap total steps to the minimum needed. After every state-changing step, verify the live post-condition. Stop if the page state contradicts the plan.
+7. For forms, tests, purchases, uploads, messages, or other externally visible mutations, keep the existing Ocean approval gate. Ask for confirmation only at the final consequential action when approval is not already present.
+8. If a field is ambiguous, required data is missing, authentication is needed, or the page reports failure, stop with the exact blocker. Do not invent personal, financial, legal, academic, or credential data.
+9. Report the outcome, the verified success signal, and any unverified or blocked step. Close the browser session only if the user requested cleanup; otherwise preserve it for continuation.
+
+## Client-neutral task prompt
+
+Normalize browser requests to:
+
+```text
+url: <starting URL>
+task: <human-readable outcome>
+continue: true
+verify: <observable success signal>
+```
+
+Use one bounded loop, verify every state-changing action, and stop when the
+success signal is present or a required human decision is reached.
+
+## Ocean execution shape
+
+Use the browser capability's session lifecycle and task runner:
+
+```text
+ocean browser detect
+ocean browser open --profile <profile>
+ocean browser approve <session-id>
+ocean browser navigate <session-id> <URL> --approve
+ocean browser observe <session-id>
+ocean browser read <session-id>
+ocean browser replace-text <session-id> <selector> <old-text> <new-text> --occurrence <n>
+ocean browser run <session-id> <task-file> --approve
+```
+
+Use direct operations for discovery and a bounded JSON task for repeatable execution. Keep task files small, set `retries` to 0–2, and never use retries to repeat an irreversible action blindly. The runner caps retries at three and stops on failed verification.
+
+## Completion contract
+
+A task is complete only when the requested outcome is visible in live page state: a success message, changed status, expected navigation, submitted result, or another explicit post-condition. A click or lack of error is not proof by itself.

package/skills/core/verification/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: verification
+description: Turn implementation claims into focused, repeatable verification checks.
+version: 1.0.0
+category: core
+---
+
+# Verification
+
+For every non-trivial change, define the smallest runnable check that proves behavior,
+then report proven facts separately from assumptions and limitations.

package/skills/index.json

@@ -0,0 +1,56 @@
+[
+  {
+    "name": "business-logic",
+    "description": "Convert a product request into explicit rules, states, permissions, exceptions, and verifiable acceptance criteria.",
+    "version": "1.0.0",
+    "category": "core"
+  },
+  {
+    "name": "catch-up",
+    "description": "Reconstruct the current project state, completed work, blockers, and next action.",
+    "version": "1.0.0",
+    "category": "core"
+  },
+  {
+    "name": "core-thinking",
+    "description": "Analyze goals, constraints, risks, and evidence before execution.",
+    "version": "1.0.0",
+    "category": "core"
+  },
+  {
+    "name": "design-thinking",
+    "description": "Frame a problem, clarify the desired outcome, compare simple solutions, and define success before implementation.",
+    "version": "1.0.0",
+    "category": "core"
+  },
+  {
+    "name": "graft",
+    "description": "This repo is indexed by graft/. For ANY task here, whether understanding how something works, finding where code lives, tracing what calls a symbol or what a change breaks, or scoping an edit, get your context from graft before grepping or reading source files.",
+    "version": "1.0.0",
+    "category": "core"
+  },
+  {
+    "name": "loop",
+    "description": "Continue a bounded task across runs with checkpoints, verification, retries, and explicit stop conditions.",
+    "version": "1.0.0",
+    "category": "core"
+  },
+  {
+    "name": "session-handoff",
+    "description": "Produce a compact continuation packet with the next action and verification commands.",
+    "version": "1.0.0",
+    "category": "core"
+  },
+  {
+    "name": "use-browser",
+    "description": "Open a supplied URL, understand the user's requested outcome from the live page, complete the browser task, and verify the result.",
+    "version": "1.0.0",
+    "category": "core"
+  },
+  {
+    "name": "verification",
+    "description": "Turn implementation claims into focused, repeatable verification checks.",
+    "version": "1.0.0",
+    "category": "core"
+  }
+]

package/templates/README.md

@@ -0,0 +1,4 @@
+# Ocean templates
+
+Templates are copied by `ocean setup` into the local workspace folders. They contain
+placeholders only and never personal data.

package/templates/profiles/default.json

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": 2,
+  "name": "default",
+  "description": "General-purpose assistant profile for ad-hoc work across the active workspace.",
+  "version": "1.0.0",
+  "role": "general assistant",
+  "skills": [],
+  "contextSources": [],
+  "defaultClient": "claude",
+  "clients": {
+    "claude": {
+      "enabled": true,
+      "model": "sonnet",
+      "transport": "cli"
+    },
+    "codex": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "gemini": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "antigravity": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "hermes": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    }
+  },
+  "governance": {
+    "allowedPaths": ["."],
+    "allowedCommands": [],
+    "writePolicy": "workspace"
+  },
+  "memory": {
+    "enabled": true,
+    "scope": "profile"
+  },
+  "verification": {
+    "commands": []
+  },
+  "contextCompression": "none",
+  "instructions": "Handle ad-hoc work carefully. Preserve unrelated changes and report what was verified."
+}

package/templates/profiles/developer.json

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": 2,
+  "name": "developer",
+  "description": "Implementation profile: reads and writes within the workspace to build and fix code.",
+  "version": "1.0.0",
+  "role": "developer",
+  "skills": [],
+  "contextSources": [],
+  "defaultClient": "claude",
+  "clients": {
+    "claude": {
+      "enabled": true,
+      "model": "sonnet",
+      "transport": "cli"
+    },
+    "codex": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "gemini": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "antigravity": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "hermes": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    }
+  },
+  "governance": {
+    "allowedPaths": ["."],
+    "allowedCommands": [],
+    "writePolicy": "workspace"
+  },
+  "memory": {
+    "enabled": true,
+    "scope": "profile"
+  },
+  "verification": {
+    "commands": ["pnpm test"]
+  },
+  "contextCompression": "none",
+  "instructions": "Inspect before editing. Preserve unrelated work. Run focused tests and report proven results."
+}

package/templates/profiles/reviewer.json

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": 2,
+  "name": "reviewer",
+  "description": "Read-only profile: reviews changes and reports findings without writing to the workspace.",
+  "version": "1.0.0",
+  "role": "code reviewer",
+  "skills": [],
+  "contextSources": [],
+  "defaultClient": "claude",
+  "clients": {
+    "claude": {
+      "enabled": true,
+      "model": "sonnet",
+      "transport": "cli"
+    },
+    "codex": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "gemini": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "antigravity": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "hermes": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    }
+  },
+  "governance": {
+    "allowedPaths": ["."],
+    "allowedCommands": [],
+    "writePolicy": "none"
+  },
+  "memory": {
+    "enabled": true,
+    "scope": "profile"
+  },
+  "verification": {
+    "commands": []
+  },
+  "contextCompression": "none",
+  "instructions": "Review changes without editing files. Separate findings from assumptions and identify missing evidence."
+}

package/templates/profiles/strategist.json

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": 2,
+  "name": "strategist",
+  "description": "Planning-only profile: reasons about approach and risk without writing to the workspace.",
+  "version": "1.0.0",
+  "role": "strategist",
+  "skills": [],
+  "contextSources": [],
+  "defaultClient": "claude",
+  "clients": {
+    "claude": {
+      "enabled": true,
+      "model": "sonnet",
+      "transport": "cli"
+    },
+    "codex": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "gemini": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "antigravity": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    },
+    "hermes": {
+      "enabled": true,
+      "transport": "cli",
+      "model": "provider-managed"
+    }
+  },
+  "governance": {
+    "allowedPaths": ["."],
+    "allowedCommands": [],
+    "writePolicy": "none"
+  },
+  "memory": {
+    "enabled": true,
+    "scope": "profile"
+  },
+  "verification": {
+    "commands": []
+  },
+  "contextCompression": "none",
+  "instructions": "Plan and reason about approach and risk without writing to the workspace."
+}

package/templates/workspace/00-inbox/INBOX.md

@@ -0,0 +1,7 @@
+# Inbox
+
+Unprocessed incoming information, waiting for explicit triage into its real home. Empty is the
+healthy steady state.
+
+- `candidates/` — proposed memory records (inferred, imported or harvested), awaiting review.
+- `native/` — staging for clients' own memory stores; never searched as truth.

package/templates/workspace/02-personal/CONFLICTS.md

@@ -0,0 +1,7 @@
+# Conflicts
+
+<!-- A fact that contradicts a record waits here until the owner says which version is current. -->
+
+## <date> — <topic>
+
+| <record path> | <recorded value> | <new value> |

package/templates/workspace/02-personal/MEMORY.md

@@ -0,0 +1,15 @@
+# Memory index
+
+The router for personal facts. Start here, then open only the one record a task needs; the
+records below are canonical, this list only points at them.
+
+**Memory holds what is true about the owner and their world**, for years. When unsure, ask:
+does it stay true even if they stop coding? Yes → a memory record. No → `05-knowledge/`.
+
+## Retrieval rules
+
+- Every fact lives in one record; anything else that needs it links there.
+- New information that disagrees with a record goes to `CONFLICTS.md` until resolved.
+- Inferred or imported facts are proposed as candidates (`00-inbox/candidates/`) for review.
+
+## Records (generated)

package/templates/workspace/04-projects/PROJECTS.md

@@ -0,0 +1,5 @@
+# Projects
+
+One folder per project: `<project>/project.json`, `tasks/<ID>/` (the task record is
+authoritative), `memory/` (lessons about this project) and `docs/` (its references). Copy
+`_template/` to start a project, or let `ocean tasks new --project <id>` create it.

package/templates/workspace/05-knowledge/KNOWLEDGE.md

@@ -0,0 +1,8 @@
+# Knowledge index
+
+What work taught us, kept so the next task can reuse it instead of rediscovering it. Memory is
+about the person; this is about the work: decisions, lessons, solutions, research.
+
+Look in `decisions/` before suggesting something that reverses an earlier decision.
+
+## Records (generated)

package/templates/workspace/06-templates/TEMPLATES.md

@@ -0,0 +1,25 @@
+# personal/templates/
+
+Reusable document templates. **Never publishable** (templates themselves are generic, but the directory is private workspace).
+
+Standardized templates for common document types used across Ocean workflows.
+
+## Available templates
+
+| Template | Purpose |
+|---|---|
+| **decision.md** | Structured decision record — context, options, chosen, reason, consequences |
+| **intelligence.md** | Intelligence gathering template — source, findings, assessment, open questions |
+| **project-claude.md** | Claude-specific project template — for project context and instructions |
+| **session.md** | Session record template — what happened, what was decided, what's next |
+| **task.md** | Task record template — scope, goal, constraints, artifacts, verification |
+
+## Usage
+
+Copy the template to the target location and fill in the frontmatter and content. Templates are starting points, not rigid forms — adapt them to the specific context.
+
+## Privacy
+
+The templates themselves are generic and could be published, but this directory is private workspace state. The templates may reference workspace-specific conventions. Keep them private.
+
+See: `personal/README.md`