Skip to content

AGENTS.md

Latest commit

 

History

History
289 lines (208 loc) · 10.7 KB

AGENTS.md

File metadata and controls

289 lines (208 loc) · 10.7 KB

AGENTS.md

This file provides guidance to AI coding agents when working with the Quick PARA Plugin for Obsidian.

Repository Purpose

obsidian-quick-para is an Obsidian plugin that provides comprehensive PARA (Projects, Areas, Resources, Archive) method support. The plugin combines folder provisioning, automatic tagging, weekly agenda generation, template management, and task cancellation into a single cohesive experience.

Key Features:

  • Quick Setup Wizard for PARA folder structure provisioning
  • Automatic property-based PARA tagging with persistent subfolder tags
  • Weekly agenda generation from Project Dashboard kanban boards
  • Template management with embedded PARA templates
  • Task cancellation for archived notes
  • Dependency checking for required plugins (Templater, Tasks)

Target Users: Obsidian users implementing the PARA method for personal knowledge management.

Development Commands

Build & Development

# Install dependencies
npm install

# Production build (generates main.js)
npm run build

# Development mode with watch (auto-rebuild on changes)
npm run dev

Testing in Obsidian

  1. Build the plugin: npm run build
  2. Copy build artifacts to test vault: 
    cp main.js manifest.json styles.css /path/to/vault/.obsidian/plugins/quick-para/
  3. Reload Obsidian or toggle plugin off/on in Settings → Community Plugins

Deployment

# Deploy to production vault (requires deploy.sh script)
./deploy.sh

The deploy.sh script handles copying build artifacts to configured vault locations.

Architecture Overview

Project Structure

obsidian-quick-para/
├── src/
│   ├── index.js              # Main plugin entry point, settings, ribbon UI
│   ├── tagging.js            # PARA tagging logic (auto-tag on create/move)
│   ├── settings.js           # Settings UI tab
│   ├── agenda.js             # Weekly agenda generation from kanban
│   ├── provisioning.js       # PARA folder setup wizard
│   ├── templates.js          # Template deployment and management
│   ├── dependencies.js       # Plugin dependency checking
│   ├── tasks.js              # Task cancellation for Archive
│   └── performance-profiler.js # Diagnostic profiling tool
├── main.js                   # Compiled bundle (generated by esbuild)
├── manifest.json             # Plugin metadata (version, name, minAppVersion)
├── styles.css                # Plugin-specific CSS
├── esbuild.config.mjs        # Build configuration
├── package.json
└── docs/                     # Feature documentation and design notes

Component Responsibilities

index.js - Main plugin class

  • Plugin lifecycle (onload, onunload)
  • Settings management and defaults
  • Ribbon icon and command registration
  • Event handlers (file create, modify, rename, delete)
  • Integration point for all modules

tagging.js - Automatic PARA tagging

  • Detects PARA folder location (inbox, projects, areas, resources, archive)
  • Sets para property in frontmatter
  • Adds subfolder tags (persistent historical breadcrumbs)
  • Includes universal all tag for filtering
  • Bulk update operations for existing files

agenda.js - Weekly agenda generation

  • Parses Project Dashboard kanban board (## sections)
  • Extracts project wikilinks from configured folders
  • Updates weekly 1-on-1 meeting notes
  • Preserves manual content between <!-- AUTO-MANAGED --> tags
  • Identifies active, blocked, and completed tasks

provisioning.js - PARA folder setup

  • First-run wizard for folder structure creation
  • Respects existing vault structure (never overwrites)
  • Guided UI for folder mapping configuration
  • Template deployment integration

templates.js - Template management

  • Embedded PARA templates (no external files needed)
  • One-click deployment to TEMPLATES folder
  • Automatic backup before overwrite
  • Templater integration

tasks.js - Task cancellation

  • Converts open tasks [ ] to cancelled [-] in Archive
  • Preview mode (dry-run)
  • Works on current file or entire Archive folder
  • Prevents task orphaning in archived notes

dependencies.js - Plugin verification

  • Checks for required plugins (Templater, Tasks)
  • User-friendly warnings with installation links
  • Validates plugin availability and enablement

performance-profiler.js - Diagnostics

  • Performance tracking for slow operations
  • Configurable thresholds and logging
  • Summary reports on plugin unload

Data Flow

  1. File Events → index.js event handlers → tagging.js → Frontmatter update
  2. Setup Wizard → provisioning.js → Folder creation → templates.js → Template deployment
  3. Agenda Command → agenda.js → Kanban parsing → Weekly note update
  4. Settings UI → settings.js → index.js → Save to .obsidian/plugins/quick-para/data.json

Key Patterns

  • Modular Design: Each feature is isolated in its own module for maintainability
  • Settings-Driven: All behavior is configurable via plugin settings
  • Non-Destructive: Respects existing content, uses AUTO-MANAGED markers
  • Defensive Coding: Extensive null checks, error handling, user confirmations
  • Performance Conscious: Profiler tracks slow operations, bulk updates are batched

Coding Conventions

JavaScript Style

  • ES6+ Features: Use modern JavaScript (const/let, arrow functions, async/await)
  • Obsidian API: Follow Obsidian plugin conventions (Plugin class, PluginSettingTab, Modal)
  • Error Handling: Wrap async operations in try/catch, use Notice for user feedback
  • Null Safety: Always check for null/undefined before accessing properties
  • Comments: Document non-obvious logic, include section headers

File Organization

  • One Module Per Feature: Keep modules focused and single-purpose
  • Clear Exports: Export only what's needed by index.js
  • Require Statements: Use CommonJS require() for consistency with Obsidian API
  • Constants at Top: Define defaults and constants before implementation

Settings Pattern

const DEFAULT_SETTINGS = {
    feature: {
        option: defaultValue,
        anotherOption: defaultValue
    }
};

// Access in code
const value = this.settings.feature.option;

Event Handlers

Always clean up event handlers in onunload():

onload() {
    this.registerEvent(this.app.vault.on('create', this.onFileCreated));
}

onunload() {
    // Obsidian automatically unregisters events
}

User Feedback

  • Notice: Quick status messages (new Notice('Done!'))
  • Modal: Confirmations, wizards, complex UI
  • Console: Debug logging for developer troubleshooting

Testing Considerations

  • Test in multiple vaults (empty, existing PARA structure, non-PARA)
  • Verify backward compatibility with older Obsidian versions (check manifest minAppVersion)
  • Test with/without required plugins (Templater, Tasks)
  • Validate frontmatter handling (YAML edge cases)

Commit Conventions

IMPORTANT: All commits must follow the workspace-wide commit message format with agent attribution.

See: /Users/mriechers/Developer/the-lodge/conventions/COMMIT_CONVENTIONS.md

Quick Reference:

<type>: <subject line in imperative mood>

[Agent: <agent-name>]

<detailed description of what changed and why>

Types: feat, fix, docs, style, refactor, test, chore

Example:

feat: Add task cancellation preview mode

[Agent: Main Assistant]

Added --dry-run functionality to task cancellation feature.
Shows affected tasks without modifying files, allowing users
to review changes before committing.

Agent attribution is recommended for tracking purposes (not enforced by git hook).

Notes for AI Agents

  1. Obsidian API Knowledge Required: Familiarity with Obsidian plugin API is essential. Reference Obsidian API docs when unsure.

  2. Build Before Testing: Always run npm run build before testing changes in Obsidian. The plugin runs from compiled main.js, not source files.

  3. Settings Schema: Changing DEFAULT_SETTINGS structure requires migration logic to preserve user settings.

  4. Frontmatter Handling: Use app.fileManager.processFrontMatter() for safe YAML updates. Never manipulate frontmatter with regex.

  5. Auto-Managed Sections: When modifying agenda generation, preserve content outside <!-- AUTO-MANAGED --> markers.

  6. Dependency Awareness: Code that relies on Templater or Tasks must gracefully degrade if plugins are missing.

  7. Performance: Large vaults may have thousands of files. Optimize bulk operations, avoid synchronous file reads in loops.

  8. Plugin Manifest: manifest.json version must match package.json version. Update both when releasing.

  9. Breaking Changes: This plugin is pre-1.0 (beta). Breaking changes are acceptable but should be documented in CHANGELOG.md.

  10. User Data Safety: Never modify user notes without explicit confirmation. Use preview/dry-run modes for destructive operations.

  11. Git Hooks: This repository does not yet have git hooks configured. Consider adding .githooks/commit-msg pointing to /Users/mriechers/Developer/the-lodge/conventions/git-hooks/commit-msg for commit message validation.

Feature Development Workflow

When adding new features:

  1. Check feature_list.json: Verify feature is tracked and status is current
  2. Create module: Add new file in src/ if feature is substantial
  3. Register command: Add command in index.js onload()
  4. Add settings: Extend DEFAULT_SETTINGS and settings.js UI if configurable
  5. Update docs: Add to README.md and create doc in docs/ if complex
  6. Test thoroughly: Multiple vault scenarios, edge cases
  7. Update CHANGELOG.md: Document changes for users
  8. Version bump: Update manifest.json and package.json versions

Known Issues & Considerations

  • Beta Status: Plugin is in testing phase before community plugin submission
  • Templater Dependency: Required for template variable substitution
  • Tasks Plugin Dependency: Required for task queries and management
  • PARA Folder Assumptions: Plugin assumes specific folder structure (configurable)
  • Kanban Format: Agenda generation expects specific kanban board section format

See BUGS.md for known bugs and workarounds.

Resources

Status: Beta - Testing before community plugin submission Maintainer: Mark Riechers License: MIT