Work

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:

- [ ] [[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

Frontmatter

Every document has YAML frontmatter:

---
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:

---
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:

---
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):

jira: <atlassian-org>/<TICKET-ID>    # e.g., acme-corp/PROJ-1234
github: <owner>/<repo>#<number>       # e.g., acme-corp/my-app#456

Inline references in markdown body (prefix with jira: or github:):

- [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):

---
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.