Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
44b0f0b
Add design doc for Create Person command
tavva Feb 16, 2026
912e3e1
Add implementation plan for Create Person command
tavva Feb 16, 2026
b9c0227
Add personsFolderPath and personTemplateFilePath settings
tavva Feb 16, 2026
627d460
Add People Folder and Person Template settings to settings tab
tavva Feb 16, 2026
619cd0e
Add FileWriter.createPerson with template support
tavva Feb 16, 2026
ee6ff1e
Add NewPersonModal for creating person notes
tavva Feb 16, 2026
6d7d0dd
Register create-person command in plugin
tavva Feb 16, 2026
bab0e4e
Format code
tavva Feb 16, 2026
ca5feb4
Add Templater integration to createPerson
tavva Feb 16, 2026
e36d124
Auto-select sphere when only one is configured
tavva Feb 16, 2026
73ada3f
Merge pull request #39 from tavva/fix/auto-select-single-sphere
tavva Feb 16, 2026
2cca593
Release v1.2.2
tavva Feb 16, 2026
a5679c0
Preserve scroll position when adding actions to Focus
tavva Feb 17, 2026
d76a294
Preserve scroll via data-before-empty instead of CSS-only updates
tavva Feb 17, 2026
3a9ea46
Wait for async renders before restoring scroll position
tavva Feb 17, 2026
7670d9c
Suppress rerender when focus change originates from sphere view
tavva Feb 17, 2026
4109255
Replace full refresh with targeted updates for focus changes
tavva Feb 17, 2026
15702f4
Update sphere view dynamically when action converts to waiting-for
tavva Feb 17, 2026
328f967
Clean up workspace event refs on re-registration
tavva Feb 17, 2026
e647785
Merge pull request #42 from tavva/fix/preserve-scroll-on-focus-add
tavva Feb 17, 2026
1d04ed8
Release v1.2.3
tavva Feb 17, 2026
24b4994
Update AGENTS.md to reflect current architecture and remove dead code
tavva Feb 17, 2026
b9c8ca5
Add design doc for GTD context tag filtering
tavva Feb 17, 2026
6eeb4d0
Add implementation plan for context tag filtering
tavva Feb 17, 2026
bc9a06a
Merge main into beta
tavva Feb 19, 2026
bb8e19d
Render focus action text as markdown for clickable wikilinks and tags
tavva Feb 19, 2026
c10787c
Handle clicks on rendered links and tags in focus view
tavva Feb 19, 2026
1cb4d7e
Guard against non-HTMLElement click targets in handleRenderedTextClick
tavva Feb 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 36 additions & 15 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ This file provides guidance to Claude Code and other agents when working with co

## Project Overview

Flow is an Obsidian plugin implementing GTD (Getting Things Done) with AI-powered inbox processing. It uses Claude or OpenAI-compatible models to categorise inbox items into projects, next actions, reference material, someday/maybe items, and person notes.
Flow is an Obsidian plugin implementing GTD (Getting Things Done). It provides manual inbox processing, project management with hierarchical spheres, focus lists, waiting-for tracking, and someday/maybe items. LLM integration (via OpenRouter) is used for cover image generation.

## Commands

Expand All @@ -15,7 +15,6 @@ npm run test:watch # Tests in watch mode
npm run test:coverage # Coverage report (80% threshold)
npm run format # Format with Prettier
npm run format:check # Check formatting without modifying
npm run evaluate # Run AI evaluations (requires Anthropic credentials)
npm run release # Interactive production release workflow
npm run release:beta # Interactive beta release workflow
```
Expand All @@ -30,14 +29,32 @@ Before declaring any task complete, always run:

## Architecture

### Core Processing Flow
### Scanners

1. **Flow Scanner** (`src/flow-scanner.ts`) - Scans vault for projects (files with `project/*` tags in frontmatter)
2. **Person Scanner** (`src/person-scanner.ts`) - Scans for person notes (files with `person` tag)
3. **Inbox Scanner** (`src/inbox-scanner.ts`) - Scans inbox folders for items to process
4. **GTD Processor** (`src/gtd-processor.ts`) - AI analysis with context from existing projects/people
5. **LLM Factory** (`src/llm-factory.ts`) - Factory for Anthropic/OpenAI-compatible clients
6. **File Writer** (`src/file-writer.ts`) - Creates/updates project files with Flow frontmatter
- **Flow Scanner** (`src/flow-scanner.ts`) - Scans vault for projects (files with `project/*` tags in frontmatter)
- **Person Scanner** (`src/person-scanner.ts`) - Scans for person notes (files with `person` tag)
- **Inbox Scanner** (`src/inbox-scanner.ts`) - Scans inbox folders for items to process
- **Waiting For Scanner** (`src/waiting-for-scanner.ts`) - Scans for `[w]` items across vault
- **Someday Scanner** (`src/someday-scanner.ts`) - Scans for someday/maybe items
- **GTD Context Scanner** (`src/gtd-context-scanner.ts`) - Scans vault for comprehensive GTD system state

### Inbox Processing

Inbox processing is manual and UI-driven (no AI involvement):

- **InboxProcessingView** (`src/inbox-processing-view.ts`) - Full Obsidian tab view for processing
- **InboxProcessingController** (`src/inbox-processing-controller.ts`) - Coordinates the processing workflow
- **InboxItemPersistence** (`src/inbox-item-persistence.ts`) - Saves processed items to vault
- **File Writer** (`src/file-writer.ts`) - Creates/updates project files with Flow frontmatter

Supporting UI: `src/inbox-modal-state.ts`, `src/inbox-modal-utils.ts`, `src/inbox-modal-views.ts`, `src/inbox-types.ts`

### Project Management

- **Project Hierarchy** (`src/project-hierarchy.ts`) - Builds/manages hierarchical project relationships
- **Project Filters** (`src/project-filters.ts`) - Filtering utilities (live projects, templates)
- **Sphere Data Loader** (`src/sphere-data-loader.ts`) - Loads and filters sphere data
- **System Analyzer** (`src/system-analyzer.ts`) - Detects GTD system issues (stalled projects, large inboxes)

### Key Domain Concepts

Expand Down Expand Up @@ -90,14 +107,17 @@ Project description and context.
- **FocusView** (`src/focus-view.ts`) - Curated action list with pinning and reordering
- **WaitingForView** (`src/waiting-for-view.ts`) - Aggregated `[w]` items across vault
- **SomedayView** (`src/someday-view.ts`) - Someday/maybe items
- **FlowCoachView** (`src/flow-coach-view.ts`) - Chat interface for GTD coaching (incomplete, not currently enabled)
- **InboxProcessingView** (`src/inbox-processing-view.ts`) - Inbox processing interface
- **RefreshingView** (`src/refreshing-view.ts`) - Base class for auto-refreshing views

### Focus System

- Items stored in `flow-focus-data/focus.md` as JSON with: file, lineNumber, lineContent, text, sphere, isPinned, completedAt
- Items stored in `flow-focus-data/focus.md` as JSONL (one JSON object per line, sync-friendly)
- **FocusPersistence** (`src/focus-persistence.ts`) - Reads/writes focus items in JSONL format
- **ActionLineFinder** (`src/action-line-finder.ts`) - Finds exact line numbers for actions
- **FocusValidator** (`src/focus-validator.ts`) - Validates items when source files change
- **FocusAutoClear** (`src/focus-auto-clear.ts`) - Automatic daily clearing at configured time
- **WaitingForValidator** (`src/waiting-for-validator.ts`) - Validates/resolves waiting-for items

### Task Status Cycling

Expand Down Expand Up @@ -150,7 +170,8 @@ All source files start with two ABOUTME lines:

### LLM Integration

- Default provider: OpenAI-compatible (OpenRouter)
- Fallback: Anthropic Claude
- British English for all AI responses
- Structured JSON output from Claude
LLM is used only for cover image generation, not for inbox processing:

- **LLM Factory** (`src/llm-factory.ts`) - Creates LLM clients
- **Cover Image Generator** (`src/cover-image-generator.ts`) - Generates project cover images via OpenRouter
- Provider: OpenAI-compatible (OpenRouter)
49 changes: 49 additions & 0 deletions docs/plans/2026-02-16-create-person-command-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Create Person Command

## Summary

Add a "Create person" command to the Flow plugin so users can scaffold person notes via the command palette, mirroring the existing "Create new project" command pattern.

Prompted by [Discussion #35](https://github.com/tavva/flow/discussions/35).

## Components

### 1. Settings additions

- `personsFolderPath: string` (default `"People"`) — folder where person notes are created
- `personTemplateFilePath: string` (default `"Templates/Person.md"`) — path to person template file

Both configurable in the settings tab.

### 2. Default person template

```markdown
---
creation-date: {{ date }}T{{ time }}
tags: person
---

## Discuss next
```

Template variables: `{{ date }}` (YYYY-MM-DD), `{{ time }}` (HH:MM:00) — same as the project template.

### 3. NewPersonModal

A simple modal with:
- Name text input (required)
- Creates file at `{personsFolderPath}/{sanitizedName}.md`
- Reads template from `personTemplateFilePath`, falls back to hardcoded default if template file missing
- Replaces `{{ name }}`, `{{ date }}`, `{{ time }}` template variables
- Errors if file already exists
- Opens the file after creation

### 4. Command registration

`addCommand` in `main.ts` with id `create-person`, name `Create person`, wired to open `NewPersonModal`. Same pattern as "Create new project".

## What's excluded

- No sphere/priority/status — person notes don't use these
Comment on lines +1 to +47
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add required project frontmatter and sections for markdown compliance.

This doc is missing the required YAML frontmatter and the Title/Description/Next actions sections expected for Flow project markdown files.

✅ Suggested structure
+---
+creation-date: 2026-02-16T00:00:00
+priority: 3
+tags:
+  - project/flow
+status: planning
+---
+
+# Create Person Command
+
+## Description
+Add a "Create person" command to the Flow plugin so users can scaffold person notes via the command palette.
+
+## Next actions
+- [ ] Draft implementation plan and validate with existing create-project flow

As per coding guidelines "Flow projects must follow the project structure with YAML frontmatter including creation-date, priority, tags (project/*), status, and optional parent-project, followed by title, description, and next actions sections".

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/plans/2026-02-16-create-person-command-design.md` around lines 1 - 47,
The person template and modal logic must produce Flow-compliant markdown: update
the default template referenced by personTemplateFilePath and the NewPersonModal
creation flow to include YAML frontmatter with creation-date, priority, tags
(include project/person or project/* as appropriate), status, and optional
parent-project, plus the required Title, Description, and Next actions sections;
ensure NewPersonModal replaces {{name}}, {{date}}, {{time}} and also inserts a
Title line ("# {{name}}"), a Description paragraph placeholder, and a "## Next
actions" section, and add a preflight check in the create-person command flow to
validate/normalize frontmatter fields and error if the target file already
exists.

- No AI integration
- No pre-population of "Discuss next" items
Loading
Loading