AI-Powered Project Knowledge Management with Obsidian

---
name: obsidian-project
description: "Use when setting up a new project for knowledge management, or when syncing a project inbox to its summary. Commands: setup project, update project."
---

# Obsidian Project - Knowledge Management for Ongoing Projects

## Overview

Manages ongoing projects with always-up-to-date summaries, easy input via inbox, weekly syncs, and optional Confluence publishing.

## Commands

| Command | Description |
|---------|-------------|
| `setup project` | Create new project with gathering phase |
| `update project` | Sync inbox to summary (usually via click) |

## Project Structure

my-project/
├── CLAUDE.md          # Agent context (you are here)
├── CLICK.md           # Weekly sync instructions
├── summary.md         # Shareable summary
├── brainstorming.md   # Personal scratchpad (not synced)
└── inbox/
    ├── inbox.md       # Running inbox (timestamped)
    └── [*.md]         # Dropped documents

## Design Principles

| Principle | Behavior |
|-----------|----------|
| Inbox format | Auto-timestamped entries |
| Diagrams | Mermaid only (portable to Confluence) |
| Links | Markdown `[text](url)` - no internal wikilinks |
| Sync | Weekly click, draft + review before applying |
| Agent edits | Can edit summary directly with confirmation |
| Rejection reasoning | Include only if explicitly provided, never fabricate |

---

## Command: `setup project`

### Flow

1. **Gather basic info**
   - Ask: Project name
   - Ask: Location (folder path in vault)
   - Ask: Brief description

2. **Confluence configuration**
   - Ask: Confluence page URL (optional, can be "none")
   - If provided, extract page ID from URL

3. **Create folder structure**
   - Create project folder at specified location
   - Create `inbox/` subfolder
   - Copy templates: CLAUDE.md, CLICK.md, summary.md, inbox/inbox.md
   - Fill in project-specific values in templates

4. **Gather existing inputs**
   - Ask: "What existing documents, links, or context should be included?"
   - User provides: file paths, URLs, paste text
   - Read and analyze all provided inputs

5. **Manual structure phase**
   - Tell user: "Edit summary.md now to add your preferred structure/sections. Say 'continue' when ready."
   - Wait for user to confirm
   - This allows user to scaffold the document before AI fills content

6. **Generate initial summary**
   - Read the current summary.md (with user's structure)
   - Fill in content around user's structure based on gathered inputs
   - Preserve user's custom sections
   - Show proposed summary to user for approval

7. **Clear processed inbox**
   - After summary is approved, clear inbox/inbox.md content (keep file with header)
   - For each document in inbox/, ask user to choose disposition:
     - **Archive** (default): Move to `inbox/processed/`
     - **Delete**: Remove the file
     - **Keep at top level**: Move to project root (for important docs like sub-RFCs)
   - This prevents re-processing during first sync

8. **Register click**
   - Add entry to ~/.clicks.md Active table:
     - Path: /absolute/path/to/project/CLICK.md
     - Frequency: weekly
     - Last Run: -
     - TTL Expires: 6 months from now
     - Status: ok

9. **QuickAdd setup (first time)**
   - If no "Add to Project Inbox" QuickAdd exists, offer to set it up
   - Provide instructions for Obsidian QuickAdd configuration

---

## Command: `update project`

Usually triggered by weekly click, can also run manually.

### Flow

1. **Read inbox**
   - Read `inbox/inbox.md`
   - Read any additional `.md` files in `inbox/` folder
   - Parse timestamped entries

2. **Read current summary**
   - Read `summary.md`
   - Understand current state, planned changes, history

3. **Update epic progress (if configured)**
   - Check CLAUDE.md for `Epic` field
   - If configured, query Jira for epic and child tickets
   - Update ASCII progress bars in Current State section

4. **Analyze changes**
   - Identify new state changes (things that now exist)
   - Identify new planned items (future work)
   - Identify completed items (move from Planned to History)
   - Identify rejected decisions (add to History with reasoning IF provided)

5. **Generate proposed updates**
   - Draft updates to each section as needed
   - Create changelog entries with dates
   - Format: `- YYYY-MM-DD: [description of change]`

6. **Show diff for approval**
   - Present proposed changes clearly
   - Ask user to approve, modify, or reject

7. **Apply changes**
   - Update summary.md with approved changes
   - Clear inbox/inbox.md (keep file with header, remove entries)
   - For each document in inbox/, ask user to choose disposition:
     - **Archive** (default): Move to `inbox/processed/`
     - **Delete**: Remove the file
     - **Keep at top level**: Move to project root (for important docs like sub-RFCs)

8. **Confluence push (if configured)**
   - Check CLAUDE.md for Confluence config
   - If configured, ask: "Push to Confluence?"
   - If yes: use Confluence MCP to update the page with summary.md content
   - Update "Last synced" date in CLAUDE.md

---

## Epic Progress Tracking

When a project has an associated Jira epic, track progress with ASCII progress bars.

### CLAUDE.md Configuration

Add to the project's CLAUDE.md:

| Field | Value |
|-------|-------|
| Key | PROJ-100 |
| Name | Feature Name |

### Progress Calculation

**Tickets with subtasks:**
- Base: `(done subtasks / total subtasks) * 100`
- Minimum 10% if ticket status is "In Progress"
- Minimum 75% if ticket status is "Code Review"

**Tickets without subtasks:**

| Jira Status | Progress |
|-------------|----------|
| Done | 100% |
| Code Review | 75% |
| In Progress | 25% |
| Refined | 0% |
| Backlog | 0% |

### Bar Characters

- Filled: `█` (20 chars = 100%)
- Empty: `░`
- Separator: `─`

# {{PROJECT_NAME}}

{{PROJECT_DESCRIPTION}}

---

## Current State

<!-- What exists now: architecture, APIs, components, configurations -->

### Overview

flowchart TD
    A[Component] --> B[Component]

### APIs / Interfaces

<!-- Document current APIs, endpoints, contracts -->

---

## Planned Changes

<!-- Future work, milestones, roadmap items -->


### Roadmap

| Milestone | Target | Items |
|-----------|--------|-------|

---

## History

<!-- Completed items and rejected decisions -->

### Completed

| Date | Item | Notes |
|------|------|-------|

### Rejected

| Date | Decision | Reason |
|------|----------|--------|

---

## Changelog

<!-- Dated entries of document changes -->

- {{TODAY}}: Initial project setup

---

## References

<!-- External links only - no internal wikilinks -->

| Resource | Link |
|----------|------|

#!/usr/bin/env python3
"""Convert Mermaid diagram to mermaid.ink URL using pako compression."""

import sys
import json
import zlib
import base64

def mermaid_to_url(mermaid_code: str) -> str:
    payload = json.dumps({
        "code": mermaid_code,
        "mermaid": '{"theme": "default"}',
        "updateEditor": True,
        "autoSync": True,
        "updateDiagram": True
    })
    compressed = zlib.compress(payload.encode(), level=9)
    encoded = base64.urlsafe_b64encode(compressed).decode().rstrip('=')
    return f"https://mermaid.ink/img/pako:{encoded}"

if __name__ == "__main__":
    if len(sys.argv) > 1:
        code = sys.argv[1].replace('\\n', '\n')
    else:
        code = sys.stdin.read()
    print(mermaid_to_url(code.strip()))