# Workflow recipes > Copy-paste file-first patterns: kanban (todo/doing/done + mv), knowledge base, session context, from skills/tigerfs/recipes.md. - Repository: timescale/tigerfs - GitHub: https://github.com/timescale/tigerfs - Human docs: https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3 - Complete Markdown: https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/llms-full.txt ## Source Files - `skills/tigerfs/recipes.md` - `skills/tigerfs/files.md` - `docs/file-first.md` - `README.md` - `test/integration/fs_operations_test.go` --- --- title: "Workflow recipes" description: "Copy-paste file-first patterns: kanban (todo/doing/done + mv), knowledge base, session context, from skills/tigerfs/recipes.md." --- TigerFS file-first workflows are defined in `skills/tigerfs/recipes.md` and implemented as synthesized markdown workspaces: write a format string to `mount/.build/`, use normal file tools (`Write`, `Glob`, `Grep`, `mv`, `rm`, `mkdir`), and optionally enable `history` for `.history/`, `.log/`, `.savepoint/`, and `.undo/`. Kanban and similar apps treat **directories as state** and **`mv` as transitions** (updating the backing `filename` column); savepoint/undo recipes use the same dot-directories documented in the file-first skill pack. ## Prerequisites | Requirement | Detail | |-------------|--------| | Mount | `tigerfs mount CONNECTION MOUNTPOINT` (see CLI reference) | | Workspace creation | `echo '' > mount/.build/` | | History (optional) | Append `,history` to the format (e.g. `markdown,history`) | | Multi-agent identity | `--user-id ` or `TIGERFS_USER_ID` at mount; runtime: `echo 'agent-7' > mount/.info/user` | Examples below use `mount/` as the mount root. Shell users can substitute `/mnt/db/` or your actual mountpoint. Agent examples use tool-style paths (`Write`, `Glob`, `Bash`) from the bundled skill pack. ## Recipe map | # | Name | Format | Primary tools | |---|------|--------|---------------| | 1 | Safe agent exploration | `markdown,history` | `.savepoint/`, `.undo/to-savepoint/` | | 2 | Compare approaches | `markdown,history` | Savepoint + undo-to-savepoint | | 3 | Multi-agent selective undo | `markdown,history` | `--user-id`, `.log/.by/user_id/`, per-user `.apply` | | 4 | Task board (kanban) | `markdown,history` | `mkdir`, `mv`, `Glob`, `Grep` | | 5 | Knowledge base | `markdown,history` | Topic dirs, `Grep`, `.history/` | | 6 | Session context | `markdown` | Dated `.md` files, `status` frontmatter | | 7 | Activity log | `markdown` | Append-only timestamped files | Workflow patterns (1–3) cover safe editing; application patterns (4–7) cover durable workspaces agents build on mounts. --- ## Workflow patterns ### Recipe 1: Safe agent exploration Create a named savepoint before uncertain work, explore, preview, then keep or revert. ```bash echo '{"description":"Before investigating bug #42"}' > mount/notes/.savepoint/before-investigation.json ``` Savepoint files need a format suffix (`.json` preferred). With `--user-id` set, `user_id` is injected automatically. Edit, create, or delete files under the workspace as usual. ```bash cat mount/notes/.undo/to-savepoint/before-investigation/.info/summary cd mount/notes && diff -ru .undo/to-savepoint/before-investigation . -x '.*' ``` Keep: do nothing (changes are already committed). Revert (destructive — confirm with the user first): ```bash touch mount/notes/.undo/to-savepoint/before-investigation/.apply ``` **Auto-savepoints:** After an inactivity gap (default **30 minutes**), the next write creates `auto--` (or `auto-` without user id). List with `Glob "mount/notes/.savepoint/auto-*"`. Disable with `--auto-savepoint-interval 0`; override default with e.g. `--auto-savepoint-interval 15m`. ### Recipe 2: Compare approaches with savepoints Branch implementations without losing either result. ```bash # Baseline echo '{"description":"Clean baseline"}' > mount/app/.savepoint/baseline.json # Implement approach A, then bookmark echo '{"description":"DFS implementation complete"}' > mount/app/.savepoint/after-dfs.json # Reset to baseline for approach B touch mount/app/.undo/to-savepoint/baseline/.apply # Implement B (now current) # Compare: read summary for A's bookmarked state # mount/app/.undo/to-savepoint/after-dfs/.info/summary # Keep B: no action. Keep A instead: touch mount/app/.undo/to-savepoint/after-dfs/.apply ``` Undo-to-savepoint restores the tree **as of that savepoint**, including work done after it (e.g. approach B), so you can switch winners without manual file surgery. ### Recipe 3: Multi-agent selective undo Separate mounts or identities tag operations in `.log/`; undo can filter by `user_id`. ```bash # Distinct identities (same database, different mounts) tigerfs mount --user-id agent-research postgres://... /mnt/research tigerfs mount --user-id agent-implement postgres://... /mnt/implement # Shared sprint bookmark echo '{"description":"Sprint start"}' > mount/notes/.savepoint/sprint-start.json # Inspect one agent's recent ops # Read mount/notes/.log/.by/user_id/agent-research/.last/10/.export/json # Undo only that agent's changes since the savepoint touch mount/notes/.undo/to-savepoint/sprint-start/.by/user_id/agent-research/.apply ``` If two agents edit the **same file**, per-user undo reverts the file to its state before that agent's **first** edit on it — which can also remove the other agent's interleaved edits on that file. Use separate files or savepoints when agents share paths. --- ## Application patterns ### Recipe 4: Task board (kanban) Use for todo lists, kanban, project trackers, and shared queues. **Directories are states; files are items; `mv` is the transition; `author` tracks ownership.** Do **not** model column state with a `status` frontmatter field. State lives in the directory path (`todo/`, `doing/`, `done/`). The bundled `skills/tigerfs/SKILL.md` enforces this for agents building boards. #### Setup ```bash echo 'markdown,history' > mount/.build/tasks mkdir mount/tasks/todo mount/tasks/doing mount/tasks/done ``` #### Lifecycle ```text mount/tasks/ ├── todo/ ← pending ├── doing/ ← in progress (claim via mv) └── done/ ← completed ``` ```mermaid stateDiagram-v2 [*] --> todo: Write new .md todo --> doing: mv (claim) doing --> done: mv (complete) done --> [*] ``` Renaming a markdown file updates the `filename` column in the backing `tigerfs` table (same as `mv` on disk). #### Add a task ```markdown --- title: Fix Auth Bug priority: high --- The login endpoint returns 500 when session cookie is expired. ``` Path: `mount/tasks/todo/fix-auth-bug.md` #### Claim and complete ```bash mv mount/tasks/todo/fix-auth-bug.md mount/tasks/doing/fix-auth-bug.md # optional: set author: your-name in frontmatter mv mount/tasks/doing/fix-auth-bug.md mount/tasks/done/fix-auth-bug.md ``` #### Inspect the board ```bash ls mount/tasks/todo/*.md ls mount/tasks/doing/*.md ls mount/tasks/done/*.md grep -r "author:" mount/tasks/doing/*.md ``` #### Custom columns Any directory name works: `backlog/`, `sprint/`, `review/`, `shipped/`. Add columns with `mkdir`; move cards with `mv`. #### History ```bash ls mount/tasks/.history/doing/fix-auth-bug.md/ ``` Shows moves and edits when `history` was enabled at workspace creation. ### Recipe 5: Knowledge base with history Topic directories replace tags-as-state; moving a file recategorizes it. #### Setup ```bash echo 'markdown,history' > mount/.build/kb mkdir mount/kb/architecture mount/kb/debugging mount/kb/conventions ``` #### Store a decision ```markdown --- title: Chose JWT Over Server Sessions author: alice confidence: high --- ## Decision Use JWT tokens instead of server-side sessions. ## Reasoning - Stateless -- no session store - Works across multiple server instances ``` Path: `mount/kb/architecture/chose-jwt.md` #### Recategorize ```bash mv mount/kb/debugging/null-bytes.md mount/kb/conventions/null-bytes.md ``` #### Search ```bash grep -r "authentication" mount/kb/ grep -r "confidence: high" mount/kb/*.md ``` #### Suggested frontmatter (extra headers / columns) | Key | Example values | Purpose | |-----|------------------|---------| | `confidence` | `high`, `medium`, `low` | Certainty | | `source` | free text | Provenance | | `supersedes` | filename | Replaces an older note | Keys without dedicated columns are stored in the `headers` JSONB column (full-replace on each write). Known columns like `title` and `author` keep old values when omitted. #### Track evolution ```bash ls mount/kb/.history/architecture/chose-jwt.md/ ``` ### Recipe 6: Session context (resuming work) Lightweight continuity across agent sessions — uses **`status` frontmatter** here (unlike kanban). #### Setup ```bash echo 'markdown' > mount/.build/sessions ``` #### End of session ```markdown --- title: Auth Refactor status: in-progress --- ## Completed - Migrated to JWT - Updated /src/auth/middleware.ts ## Next Steps - Implement refresh token rotation ``` Path: `mount/sessions/2026-02-24-auth-refactor.md` (date + topic naming). #### Start of next session ```bash ls mount/sessions/*.md grep -r "status: in-progress" mount/sessions/*.md cat mount/sessions/2026-02-24-auth-refactor.md ``` History is optional for session notes; add `,history` to the build format if you need versioned session files. ### Recipe 7: Activity log Append-only, one file per event; safe for concurrent writers. #### Setup ```bash echo 'markdown' > mount/.build/activity ``` #### Log an event Filename pattern: `YYYY-MM-DDTHHMMSS.mmmZ-short-description.md` ```markdown --- author: agent-a type: fix --- Fixed the auth bug in login endpoint. Changed session cookie handling to check expiry before validating. ``` Path example: `mount/activity/2026-03-21T150000.000Z-fixed-auth-bug.md` #### Review ```bash ls mount/activity/*.md ls mount/activity/2026-03-21* grep -r "author: agent-a" mount/activity/ grep -r "type: fix" mount/activity/ ``` --- ## Format strings reference | Build command | Workspace behavior | |---------------|-------------------| | `echo 'markdown' > mount/.build/name` | YAML frontmatter + body | | `echo 'markdown,history' > mount/.build/name` | Above + `.history/`, `.log/`, `.savepoint/`, `.undo/` | | `echo 'plaintext' > mount/.build/name` | Body only, no frontmatter | | `echo 'history' > mount/.build/name` | Add history to existing workspace | Backing tables live under `mount/.tables//` for data-first export, indexes, and schema inspection. --- ## Agent vs shell command styles The skill pack documents two equivalent styles: | Action | Agent (skill pack) | Shell | |--------|-------------------|-------| | Create workspace | `Bash "echo 'markdown,history' > mount/.build/tasks"` | `echo "markdown,history" > /mnt/db/.build/tasks` | | List pending | `Glob "mount/tasks/todo/*.md"` | `ls /mnt/db/tasks/todo/` | | Transition card | `Bash "mv mount/tasks/todo/x.md mount/tasks/doing/x.md"` | `mv /mnt/db/tasks/todo/x.md /mnt/db/tasks/doing/x.md` | | Revert workspace | `Bash "touch mount/notes/.undo/to-savepoint/name/.apply"` | `touch /mnt/db/notes/.undo/to-savepoint/name/.apply` | Natural-language requests ("set up a kanban with todo/doing/done") map to Recipe 4 via the bundled `skills/tigerfs/SKILL.md` routing table — no need to memorize paths if the agent has TigerFS skills installed at mount time. --- ## Verification signals | Check | Expected | |-------|----------| | Workspace exists | `ls mount/tasks/` shows `todo/`, `doing/`, `done/` | | Card moved | File only under new column directory; `mv` preserves frontmatter and body | | Savepoint listed | `ls mount/notes/.savepoint/` includes your `.json` name | | Undo preview | `.undo/to-savepoint//.info/summary` describes affected files | | Per-user log | `.log/.by/user_id//.last/N/.export/json` returns JSON rows | | Auto-savepoint | After gap + write, `auto-*` entry appears under `.savepoint/` | On failure, TigerFS logs structured hints to stderr (errno alone is often insufficient). Use `tigerfs mount --debug` for full operation traces. --- ## Related pages Create workspaces, frontmatter semantics, directories as state, and `.tables/` access. `.history/`, `.log/`, savepoint JSON, preview/apply undo, and per-user filters. Bundled `skills/tigerfs` pack, SKILL.md routing to recipes, mount-time install. `.build/` formats, backing tables in `tigerfs` schema, and column mapping. First mount, `ls`/`cat`, and demo workflows.