git:20261003.cac07b7 to git:20261009.f1fd8a6

# workhub vault

This Obsidian vault is the data store of the workhub app and the owner's

personal knowledge base. Humans and AI agents read and write the same Markdown

files; it is the single source of truth for tasks and shared knowledge.

This file is loaded in every session, so it holds only what applies to every

session. Format details live in `.claude/rules/` and load when a matching path

is touched: `tasks.md`, `projects.md`, `backlog.md`, `schedules.md`,

## Structure

| Folder | Zone | Role |

|--------|------|------|

| `tasks/` | human + AI | one task = one Markdown file; archived ones in `tasks/archive/` |

| `projects/` | human + AI | `NNNN-<slug>/` per project, one backlog item per unit of work |

| `knowledge/` | human + AI | the owner's reference material, one topic folder per theme; nothing injects it |

| `memory/` | human + AI | everything durable an agent knows (see Working agreement) |

| `strategy/` | human + AI | `north-star/` (where they head), `current/` (where they are), `bottlenecks/` (what blocks them); `/strategist` reads it |

| `inbox/` | human + AI | raw input; classify with `/kb-ingest` |

| `journal/` | human | agents read it, and leave it where it is |

| `archive/` | human + AI | completed or inactive material |

| `templates/` | human | note templates, including the `project/` scaffold |

| `_ai/` | **AI only** | working data: `index/`, `logs/` (agent reports, `kb-log.md`), `comms/`, `state/`. Knowledge belongs in `memory/` |

| `.workhub/` | **app only** | `settings.json`, the settings that describe this vault; change them in the app's Settings dialog |

Folder names are lowercase kebab-case, topic folders under `knowledge/`

included.

## Working agreement

How agents and the owner work together here, on top of the task prompt.

**Owner context.** `memory/identity/` holds who the owner is

(`about-me.md`) and how they decide (`decision-policy.md`: what you may settle

alone, what comes back to them, and the `## Preferences` and

`## Promoted rules` you build a recommendation from). Read it before work that

depends on any of that. The calls already settled are `type: decision` notes in

`memory/notes/`; search them when the policy leaves a question open.

**Memory.** `identity/` is read in full every session, so it stays capped.

`notes/` is searched, so each note carries a `type:`. `episodes/` decays and is

promoted from. A constraint about particular code goes in a `.claude/rules/`

file, which fires on a path.

**Recommend, don't ask openly.** Present every open choice with the answer the

owner would most likely give, derived from `## Preferences` and

`## Promoted rules`, and the reason. When they settle it, append the rule to

`decision-log.md`'s `## Decisions` (a standing leaning goes to `## Preferences`;

a second question settled by the same reasoning goes to `## Promoted rules`).

**Plan first.** Write the plan before the implementation, and get it approved

when the task is plan-first. Reuse an existing note, module or convention.

Take the goal (what, for whom, why) and work out the *how*; ask for the goal

when it is unclear.

**Follow-up tasks.** A task filed mid-session runs in a fresh session. Recommend

continuing here only for a small change that leans on context no note records,

and let the owner decide. The `task-handoff` skill carries the criteria.

**Collaborate.** Ask about anything ambiguous, and say so when a request looks

wrong, costlier than needed, or solvable a better way. Give the reasons, then

follow the owner's decision.

**Record.** Write down what a future session would otherwise rediscover:

decisions with their reasoning, rejected options, parked ideas, and the cause

of any failure with what to do differently. Session working notes go to

`_ai/state/`, design decisions to the project's `dev-notes/`.

**Safety.** Confirm with the owner before anything irreversible or outward

facing: deleting or overwriting files, force-pushing, rewriting history,

sending, publishing, spending. Prefer the reversible form (append, copy, new

file, draft). Approval for one action covers that action only.

The app's **Settings → Agents → Custom prompt** is appended to every task launch

prompt with whitespace collapsed, so it is a short personal delta. Longer

guidance goes in this file or `memory/identity/about-me.md`.

## Knowledge workflow

Humans drop raw notes into `inbox/`; `/kb-ingest` classifies them into

`projects/` / `knowledge/` / `archive/`, proposes tasks for actionable items,

and maintains the zone `_index.md` files. `/kb-query` searches and synthesizes,

`/kb-lint` health-checks, `/kb-index` repairs indexes. The activity log is

`_ai/logs/kb-log.md`.

## Tasks

A task is `tasks/<id> <title>.md` with YAML frontmatter (`id`, `title`,

`status`, `assignee`, `project`, `backlog`, `priority`, `confirm`, `worktree`,

`depends_on`, ...). The full schema loads from `.claude/rules/tasks.md` when you

open a task file; `task-cli` and the app write it.

Body sections, in order: `## Description` (human: the spec), `## Plan` (AI,

approved by human), `## Results` (AI, on completion). Description and Plan are

inputs, Results is the output. A non-empty `## Plan` is already approved: follow

it, and append to it when it genuinely changes.

## Projects and backlog items

A project is `projects/NNNN-<slug>/`. `NNNN` only orders the folder; the slug is

what `project:` keys use. Find a folder with the glob `projects/*-<slug>/` (or

`archive/projects/*-<slug>/`). Open its `README.md` first: it states the status

and points to everything else.

**Every task with a project has a backlog item.** A task without a `project` is

vault housekeeping: its output goes to `_ai/logs/` or `knowledge/`. An empty

`backlog` means "not chosen yet", and `task-start` settles it:

- Compare each item's `## What` with the task's `## Description`.

- Attach the task to an overlapping item. Start a new item only when none

overlaps (or the project has none yet): a misfiled note is one move to fix,

while a duplicate item splits a subject unnoticed.

- Write `backlog: B-NNN` onto the task and name the chosen item in your first

message.

A recurring task keeps no item: it is a habit, and leaves nothing durable. The

item format loads from `.claude/rules/backlog.md`, and the layout from

`.claude/rules/projects.md`, when you work under `projects/`.

## Agent harness

This vault is the default working directory for AI agent sessions

(Claude Code / OpenCode). Development work targets external repositories

registered in `.claude/project-context.json`; the vault holds tasks, knowledge

and configuration.

- Skills, hooks and agents come from Claude Code plugins. `.claude/settings.json`

declares the `workhub-marketplace`; plugins are switched on per machine from

the app's **Plugins** tab or `/plugin`, and only `workhub` is required. The

catalog and scope policy are in `docs/plugins.md` in the workhub repo.

- Personal skills live at `.claude/skills/<name>/SKILL.md` and agents at

`.claude/agents/<name>.md`; template updates leave them alone. A skill someone

else would use is promoted to a plugin in the workhub repo's `plugins/`.

- `.opencode/skills/` is generated from the enabled plugins and the vault's own

skills; edit the source and re-sync.

- Respond in the workhub **Language** setting (⚙ Settings → Agents); the app

injects a reminder every turn. The same setting governs a task's `## Plan` and

`## Results`. Code, comments, commit messages and repository documentation are

English.

### Session names

A session is named so the session list reads at a glance:

```text

[<label>] <task-id> <title> a session working a task, e.g. [sbr] T-0541 Session naming convention

<task-id> <title> when the task has no `project`

[<label>] <title> no task, but the project is settled (e.g. via `project-start`)

```

- `<label>` is the project's `alias` (optional README frontmatter key, see

`.claude/rules/projects.md`), or the `project` slug as written, without the

folder number, when there is none. `project:` keys always stay the slug.

- Truncate only the title, to 40 characters; keep the label whole.

- A session with neither task nor project is left unnamed.

- Brackets, not `|`, `:` or `/`: those are special in shells and Windows paths,

and a session name ends up in workspace labels and transcript file names.

- The app's herdr launch and the `task-handoff` chip use this form.

`task-start` (task sessions) and `project-start` (no task) rename a session

that does not follow it when the host allows

(Claude Desktop's `set_session_title`); OpenCode and a bare terminal cannot be

renamed, so there the convention only applies to what the app launches.

### Worktrees

Work in the repository's main working tree. A task with `worktree: true` works

in `<worktree-root>/<task-id>/<repo-name>` on branch `task/<task-id>`; the

launch prompt names the root (the app's **Worktree root** setting), and

`task-start` step 5 has the commands. Create a worktree only for such a task,

and ask the owner first in any other case, including to keep clear of parallel

work. Remove one with `git worktree remove`, so git's metadata stays consistent.

### Capturing knowledge

Propose capturing reusable, non-obvious knowledge (gotchas, build quirks,

design invariants, the "why" behind a decision) at the moment you find it. The

`capture-rule` skill picks the home and writes it: a target repo's

`.claude/rules/` for repo-specific technical knowledge, the vault's

`.claude/rules-ex/` for cross-cutting knowledge that must reach repo files,

`knowledge/` for reference humans also read, auto-memory for personal

preferences.

## Rules for AI agents

- Move a task's status `todo → doing → review`; the owner sets `done` in the

app.

- Start a task only when its `depends_on` predecessors are `done`. `task-cli

start` refuses otherwise and lists them: tell the owner, and leave `--force`

to them.

- Change only `status`, `updated`, `## Plan` (plan-first tasks, before

implementation) and `## Results` in a task file; preserve the rest.

- Append to an approved `## Plan` and say so; it is the owner's approval

record.

- Raw work reports go to `_ai/logs/`. Polished summaries and deliverables go to

the task's backlog item or `knowledge/`, linked from `## Results`.

- Find tasks through `_ai/index/tasks.json`, falling back to `tasks/`

frontmatter if the index is missing.

- Append to or create-and-link human-zone notes. `_ai/` is yours to manage.

## Local instructions

`CLAUDE.local.md` at the vault root holds the owner's own instructions. The app

seeds it once and never updates it, and it takes precedence over this file; no

file, or an empty one, means there are none. This file is app-managed and

re-applied on every update, so anything an agent is asked to remember

permanently goes in `CLAUDE.local.md`. The full list of app-managed files is in

`.claude/rules/app-managed-files.md`.

<important>

- Confirm with the owner before irreversible or outward-facing actions

(deleting, overwriting, force-pushing, sending, publishing, spending).

- Never set a task's `status` to `done`; the owner does that in the app.

- Remove a worktree with `git worktree remove`; deleting its folder leaves

stale git metadata.

- Respond in the workhub **Language** setting; write repository artifacts in

English.

- Record instructions in `CLAUDE.local.md`. This file, `AGENTS.md`,

`opencode.json` and the `.claude/**` / `.opencode/**` paths listed in

`_ai/template-manifest.json` are app-managed. Unlisted paths such as

`.claude/skills/` are yours.

</important>