# Work > Use when the user asks to create, update, list, or manage work items, goals, notes, guides, or references in a Treasure Work workspace. Triggers on "create a task", "add a work item", "move to done", "show my tasks", "goal progress", "create a note", "what's next", or any workspace document management. Also use when operating on files in goals/, items/, guides/, notes/, or references/ folders. - Skill: `treasure-data/work-2` (Agent Skill) - Install (CLI): `npx skillmds@latest add treasure-data/work-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/treasure-data/work-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: treasure-data (https://skillmd.com/u/treasure-data) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/treasure-data/work-2 --- # Work Basic Manage workspace documents (items, goals, notes, guides, references) using file operations. All state lives in markdown files with YAML frontmatter. ## Workspace Location Workspaces are stored under `~/tdx/work/`: - **Local workspaces:** `~/tdx/work/local/{name}/` (default workspace: `~/tdx/work/local/default/`) - **GitHub workspaces:** `~/tdx/work/github/{owner}/{repo}/` Each workspace root contains a `tdx.json` config file. The current working directory is typically set to the active workspace. ## Wiki-Links Wiki-links connect pages inside a workspace. Use them anywhere in a document body — checklists, goal linked-items lists, notes. **Format** - `[[Page Title]]` — link by the human-readable title. Works for both existing pages and pages that don't exist yet. - `[[slug]]` — link by an existing page's slug (e.g. `[[fix-login-bug]]`). - `[[Page Title|Display Text]]` or `[[slug|Display Text]]` — override the rendered link text. **Resolution** — for `[[text]]`: 1. Normalize the link text to a slug (lowercase, non-alphanumeric → hyphens), so `[[Page Title]]` and `[[page-title]]` resolve identically. 2. Match against page filenames in the kind folders (goals, items, guides, notes, references). Any leading `YYYY-MM-DD-` date stamp on the filename is ignored — so `[[Page Title]]` matches a file named `items/2026-07-14-page-title.md`. 3. When multiple folders match, priority is: goals > items > guides > notes > references. 4. Unresolved links render as placeholder links — clicking one opens the create-page prompt with the link text as the title. Once the page is created, the same placeholder link resolves to it automatically. **Sub-task checklist** — placeholders let you plan before every page exists: ```markdown - [ ] [[Add Auth Refresh]] — Token refresh logic - [ ] [[Update API Docs]] — Update REST docs - [x] [[Fix Session Expiry]] — Session timeout fix ``` **Backlinks** — find pages linking to a given slug: `Grep("\\[\\[{slug}", glob: "**/*.md")`. ## Folder Structure | Folder | Kind | Filename Pattern | |--------|------|------------------| | `goals/` | goal | `{slug}.md` (no date prefix) | | `items/` | item | `YYYY-MM-DD-{slug}.md` | | `guides/` | guide | `YYYY-MM-DD-{slug}.md` | | `notes/` | note | `YYYY-MM-DD-{slug}.md` | | `notes/weekly/` | weekly note | `YYYY-MM-DD-WNN.md` (date = the week's start day, e.g. Monday; `WNN` = ISO week number) | | `references/` | reference | `YYYY-MM-DD-{slug}.md` | | `agents/` | agent | `{name}/AGENTS.md` (see §Agents) | ## Frontmatter Every document has YAML frontmatter: ```yaml --- title: My Work Item status: todo # items/goals: backlog|todo|planning|design_review|in_progress|review|done|void # guides: proposed|accepted|deprecated|superseded tags: [feature, auth] priority: medium # critical|high|medium|low (items/goals only) assignee: Name # items/goals only due: 2026-04-01 # items/goals only github: owner/repo#123 # link to GitHub issue or PR (items/goals only) jira: atlassian-org/PROJ-456 # link to Jira ticket (items/goals only) created: 2026-03-23 updated: 2026-03-23 --- ``` **Guides** also support `description:` — a one-line summary shown in the guide index and injected into agent context for accepted guides. Notes and references only need `title`, `tags`, `created`. References add `source: URL`. ## Slug Rules Slugify the title: lowercase, replace non-alphanumeric with hyphens, trim edges, max 60 chars. - "Fix Login Bug" → `fix-login-bug` - "2026-03-23-fix-login-bug.md" for items, "fix-login-bug.md" for goals ## Core Operations ### Create a Document 1. Slugify the title 2. Write to the correct folder with proper filename pattern 3. Include frontmatter with `title`, `created` (today), `status` (default: `todo` for items, `proposed` for guides) **Item example:** ```markdown --- title: Fix Login Bug status: todo tags: [bug, auth] priority: high created: 2026-03-23 --- Login fails when password contains special characters. ``` → Write to `items/2026-03-23-fix-login-bug.md` **Goal example:** ```markdown --- title: Auth Redesign status: todo tags: [q2, security] created: 2026-03-23 --- Redesign the authentication system. ## Linked Items - [[fix-login-bug|Fix Login Bug]] ``` → Write to `goals/auth-redesign.md` ### Link Items to Goals Use wiki-links for bidirectional linking: 1. In the goal body, add `- [[item-slug|Display Title]]` 2. In the item body, add `Part of [[goal-slug]].` ### Move Status Read the file, update the `status` field in frontmatter, set `updated` to today. ### List Documents Use Glob to find files, Read to inspect frontmatter: - All items: `Glob("items/*.md")` - All goals: `Glob("goals/*.md")` - By status: Grep for `status: in_progress` in the target folder ### Search Knowledge Use Grep to search across notes, guides, and references: - By content: `Grep(pattern, path: "notes/")` or across all knowledge folders - By tag: `Grep("tags:.*keyword", glob: "{notes,guides,references}/**/*.md")` ### Goal Progress 1. Read the goal file 2. Parse wiki-links from the body 3. For each linked slug, find the matching item file (Glob for `items/*{slug}.md`) 4. Read each item's `status` field 5. Calculate: done count / total, percentage, list in-progress items ### What's Next Find the first linked item in a goal that isn't `done` or `void`. ## Git Conventions When committing workspace changes, use this message format: - Status changes: `work: move "Title" old_status → new_status` - New documents: `work: create "Title"` - Updates: `work: update "Title"` ## External Tracker Links **Frontmatter fields** (field name provides the type): ```yaml jira: / # e.g., acme-corp/PROJ-1234 github: /# # e.g., acme-corp/my-app#456 ``` **Inline references** in markdown body (prefix with `jira:` or `github:`): ```markdown - [x] Auth token refresh — jira:acme-corp/PROJ-1234 - [ ] Update API docs — github:acme-corp/my-app#789 ``` ## Knowledge Loop 1. **Before work** — search guides for relevant conventions: `Grep(pattern, path: "guides/")` 2. **During work** — capture learnings as notes 3. **After work** — check if insights should become guides (proposed → accepted) 4. **Accepted guides** are auto-injected into future sessions — promote guides when patterns are validated 5. **Before creating** — search existing docs to avoid duplicates ## Agents Workspace agents live in `{workspace}/agents/{name}/AGENTS.md` — one directory per agent, one file per definition. Global agents use the same shape at `~/.treasure-work/agents/{name}/AGENTS.md`. `AGENTS.md` is YAML frontmatter + a markdown body (the agent's system prompt): ```markdown --- name: segment-builder description: Builds and validates CDP segments status: active # draft | active | paused | resting schedule: "0 9 * * 1-5" # 5-field vixie cron; omit to make on-demand triggers: # workspace event triggers (optional) - on: note_created tags: [meeting] - on: item_status_changed from: [design_review, review] to: [in_progress] skills: [segment, journey] guides: [cdp-best-practices] goal: ship-v2-audience # scope to a goal's linked items allowed_tools: [Write, Bash] # optional allowlist --- You are the Segment Builder agent... ``` An agent fires on `schedule:` (cron), on any matching `triggers:` (event-driven), or manually — the three are independent, so an agent may have any combination. A scheduled agent runs iff `status: active` AND the user hasn't paused it. New agents default to `status: draft`; promote to `active` when ready. Manage agents through the `agent_*` MCP tools (server: `work`): - `agent_list` — list every agent (workspace + global) with scope, status, schedule, description - `agent_get` — full frontmatter + system prompt body for one agent - `agent_create` — create a new `{name}/AGENTS.md`. Set `schedule:` to make it scheduled, omit for on-demand - `agent_update` — patch any subset of frontmatter and/or the body. Set `status: active` to enable scheduled runs - `agent_delete` — remove the agent's directory - `agent_run_now` — fire a one-off run (does not advance the cron) Prefer the MCP tools — they validate frontmatter and emit lifecycle events. Direct `Read`/`Edit` of `agents/{name}/AGENTS.md` is fine for tweaks the tools don't cover.