Skill: killerapp/para-pkm (version 1.0.0)

--- name: para-pkm description: Manage PARA-based personal knowledge management (PKM) systems using Projects, Areas, Resources, and Archives organization method. Use when users need to (1) Create a new PARA knowledge base, (2) Organize or reorganize existing knowledge bases into PARA structure, (3) Decide where content belongs in PARA (Projects vs Areas vs Resources vs Archives), (4) Create AI-friendly navigation files for knowledge bases, (5) Archive completed projects, (6) Validate PARA structure, or (7) Learn PARA organizational patterns for specific use cases (developers, consultants, researchers, etc.) --- # PARA PKM Organize by actionability, not topic. Projects/Areas/Resources/Archives for optimal AI navigation. Monthly review cadence. ## Core Concepts - **Projects** = Time-bound goals with deadlines (completes → Archives); includes `projects/stories/` for job applications - **Areas** = Ongoing responsibilities (use `_overview.md` per area for context) - **Resources** = Reference material; when unsure, put here temporarily - **Archives** = Inactive items from any category ## Decision Tree ``` Has deadline/end state? → Projects Ongoing responsibility? → Areas Reference material? → Resources (default for uncertain items) Completed/inactive? → Archives ``` ## Quick Start 1. `python scripts/init_para_kb.py <name>` - Creates PARA + `projects/stories/` + navigation 2. Identify projects (deadlines) → areas (ongoing) → resources (reference) 3. `python scripts/generate_nav.py` - Generate AI navigation ## Scripts | Script | Purpose | Usage | |--------|---------|-------| | `init_para_kb.py` | Scaffold new KB | `<name> [--path <dir>]` | | `validate_para.py` | Check structure, detect anti-patterns | `[path]` | | `archive_project.py` | Archive with metadata (date, origin) | `<project-file> [--kb-path]` | | `generate_nav.py` | Create AI nav (<100 lines) | `[--kb-path] [--output]` | ## Templates | Template | Purpose | |----------|---------| | `assets/AGENTS.md.template` | AI navigation index | | `assets/project.md.template` | Project file structure | | `assets/area-overview.md.template` | Area `_overview.md` format | | `assets/README.md.template` | Knowledge base README | ## Patterns by Role - **Developers**: `projects/active/` features/bugs, `areas/professional-development/`, `resources/coding-standards/` - **Consultants**: `projects/active/` deliverables + `projects/stories/`, `areas/consulting/clients/`, `resources/templates/` - **Researchers**: `projects/active/` papers/grants, `areas/research-program/`, `resources/literature-review/` - **Product Builders**: `projects/active/` launches, `areas/product-development/{active,research,graduated,legacy}/` ## Complex Scenarios **Client = project + relationship**: `projects/active/client-x.md` (deliverables) + `areas/consulting/clients/client-x.md` (relationship, billing) **Research lifecycle**: `areas/product-development/{research → graduated → active → legacy}` with cross-references ## Anti-Patterns - inbox/ folder (capture directly into PARA; use Resources when uncertain) - Deep nesting (max 2-3 levels; flat > nested) - Topic-based organization ("work/personal" → use actionability) - Todo folders (tasks belong with their projects/areas) - Perfectionism (move freely as understanding evolves; monthly review catches misplacements) ## Content Lifecycle ``` Resources → Projects → Archives (research → active work → completed) Areas → Archives (no longer responsible) Projects ⟺ Areas (goal becomes ongoing or vice versa) ``` ## AI Navigation & Success Tips - Keep nav under 100 lines; point to paths not files; minimize tokens - Start simple ("What am I working on now?"); one home per item (use links) - Monthly review: archive completed, reassess areas; let patterns emerge ## References - [para-principles.md](references/para-principles.md) - Complete PARA method, "actionability not topic" principle - [decision-guide.md](references/decision-guide.md) - Detailed decision tree with edge cases - [common-patterns.md](references/common-patterns.md) - Proven patterns for different roles - [ai-navigation.md](references/ai-navigation.md) - AI-friendly navigation best practices

path: references/ai-navigation.md
content: # AI Navigation Best Practices

## Core Principle

Every token counts. Keep navigation files under 100 lines. Target 30-50 lines.

## Essential Elements

### 1. Purpose Statement (1-2 lines)
`**Purpose**: PARA PKM for John's coding projects and career.`

### 2. Quick Lookup Paths
```
**Active projects**: `projects/active/`
**Consulting ops**: `areas/consulting/operations/`
**Coding standards**: `resources/coding-standards/`
```

### 3. Current Context (optional)
Only if actively relevant: active clients, current projects, job hunt status

### 4. PARA Structure (brief)
```
projects/  = Time-bound goals
areas/     = Ongoing responsibilities
resources/ = Reference material
archives/  = Completed work
```

### 5. Navigation Tips (1 line)
`Use grep for keywords. Use glob for patterns.`

## Anti-Patterns

- **Explaining PARA**: AI knows it; just show structure
- **Listing all files**: Show paths, let AI grep/glob
- **Usage instructions**: Focus on navigation only
- **Duplicate info**: Point to files, don't repeat content
- **Detailed descriptions**: Just list paths

## Progressive Disclosure

Navigation file → grep/glob → read specific files

Navigation provides entry points; agent discovers details through tools.

## Template (~30-50 lines)

```markdown
# AI Agent Navigation Index

**Purpose**: [One line]

## Quick Lookup Paths
**Key area 1**: `path/`
**Key area 2**: `path/`

## Current Context
[Optional: what's active now]

## PARA Structure
projects/  = Time-bound
areas/     = Ongoing
resources/ = Reference
archives/  = Completed

Use grep for keywords.
```

## When to Update

Update for: major structural changes, significant project shifts, new usage patterns
Don't update for: individual file additions, minor tweaks, content updates

## Multiple AI Systems

Option 1: Single `AGENTS.md`, symlink others
Option 2: System-specific files (keep all minimal)


path: references/common-patterns.md
content: # Common PARA Patterns

## By Persona

### Software Developers
- `projects/active/` → features, bugs, migrations with deadlines
- `areas/professional-development/` → skill building, open-source
- `resources/coding-standards/`, `platform-configs/`, `library-preferences/`

### Consultants
- `projects/active/client-x.md` → technical deliverables
- `areas/consulting/operations/` → invoicing, onboarding, CRM
- `areas/consulting/clients/` → relationship notes
- `resources/proposal-templates/`, `contract-templates/`
- Key: Dual tracking (technical in Projects, relationship in Areas)

### Researchers
- `projects/active/` → papers, grants with deadlines
- `areas/teaching/`, `areas/research-program/experiments/`
- `resources/literature-review/`, `methodologies/`

### Product Builders
- `projects/active/` → feature launches, partnerships
- `areas/product-development/active/` → shipping products
- `areas/product-development/research/` → experiments
- `areas/product-development/graduated/` → ready to ship
- `resources/market-research/`, `user-feedback/`

### Career Professionals
- `projects/active/job-hunt-2025.md` → time-bound goal
- `projects/stories/` → full narratives + `fragments/` for atomic pieces
- `areas/career-development/` → ongoing skill building
- `resources/career-materials/` → templates

### Multi-Role
- Don't separate by role (no `work/` vs `consulting/`)
- Organize by actionability across all roles
- Single `projects/active/` with items from any role

## Cross-Cutting Patterns

**Nested Areas**: `areas/business/` with `_overview.md`, `operations/`, `clients/` (max 2-3 levels, nest when >10 files)

**Project Stories**: `projects/stories/` with full narratives + `fragments/` for remixable atomic pieces + `_index.md`

**Research Pipeline**: `areas/research/category/experiment.md` organized by domain → `graduated/` when ready

**AI Navigation**: Root `AGENTS.md` <100 lines, minimal tokens, points to paths for grep/glob

**Graduated Content**: Research → Graduated → Active (or Ideas → Drafts → Graduated for content)

## Guidelines

1. Start simple with basic P/A/R/A
2. Let patterns emerge, don't over-organize
3. Copy proven patterns as templates
4. Adapt as needed; patterns serve you
5. Review and reorganize periodically


path: references/decision-guide.md
content: # PARA Decision Guide

## Decision Tree

- Completed/inactive? → Archives
- Has deadline/end state? → Projects
- Ongoing responsibility? → Areas
- Reference material? → Resources

## Category Examples

### Projects (Time-bound)
- "Launch website by Q2", "Write paper for May conference", "Job hunt 2025"
- NOT: "Career development" (Area), "Python notes" (Resource)

### Areas (Ongoing)
- "Health & fitness", "Business operations", "Product development", "Home maintenance"
- NOT: "Get promoted" (Project), "Coding standards" (Resource)

### Resources (Reference)
- "Coding standards", "Design patterns", "Resume templates", "Platform configs"
- NOT: "Update standards" (Project), "Maintain design system" (Area)

### Archives (Inactive)
- Completed projects, old engagements, deprecated docs

## Common Scenarios

**Consulting**: Technical work → `projects/active/client-x.md` | Relationship → `areas/consulting/clients/client-x.md`

**Research**: Active experiments → `areas/research/` | Specific deadline → `projects/active/` | Published → `resources/`

**Job hunt**: Active applications → `projects/active/job-hunt-2025.md` | Stories → `projects/stories/` | Templates → `resources/career-materials/`

**Learning tech**: For project → include in project | General skill → `areas/professional-development/` | Reference → `resources/`

**Business (LLC)**: Ongoing ops → `areas/business-name/` | Specific goal → `projects/active/`

## Edge Cases

- **Project → Area**: "Build KB" completes → create `areas/knowledge-management/`
- **Split large Areas**: Single file growing → convert to directory with `_overview.md`
- **Tiny tasks** (<1 week): May not need formal project tracking

## When Unsure

Ask: Deadline? → Projects | Ongoing? → Areas | Reference? → Resources | Inactive? → Archives

Default: Put in Resources temporarily, move later as clarity emerges.


path: references/para-principles.md
content: # PARA Method Principles

Source: https://fortelabs.com/blog/para/

## The Four Categories

**Projects**: Tasks linked to a goal with deadline → completes → Archives
**Areas**: Sphere of activity with standard to maintain → never "completed"
**Resources**: Topics of ongoing interest → reference material, no action required
**Archives**: Inactive items from other three categories

## Core Principles

1. **Organize by actionability**: Projects (deadline) > Areas (maintenance) > Resources (reference) > Archives (inactive)
2. **Start with Projects**: Ask "What am I committed to now?" Put rest in Resources temporarily
3. **One home per item**: Use links to connect, avoid duplicating content
4. **Move between categories**: Resources→Projects (activated), Projects→Archives (completed), Projects→Areas (becomes ongoing)
5. **Keep it simple**: Minimal subcategorization, max 2-3 levels depth

## PARA vs Other Systems

- **vs Zettelkasten**: PARA=action-oriented folders, Zettelkasten=connection-oriented notes
- **vs GTD**: GTD=task/context-based, PARA=project/area-based (complementary)
- **vs Topic folders**: Topic=by subject, PARA=by actionability (surfaces what's relevant)

## Common Questions

- **Project or Area?** Does it have an end state? Yes→Project, No→Area
- **Subcategories?** Projects: minimal | Areas: by domain | Resources: by topic
- **Multiple categories?** Choose most actionable, link between them
- **Client work?** Fixed engagement→Projects | Ongoing retainer→Areas | Both valid

## Anti-Patterns

- **Inbox folder**: Capture directly to appropriate category (unsure→Resources)
- **Deep nesting**: Max 2-3 levels (`areas/business/operations/invoicing.md` good, deeper bad)
- **Topic organization**: Organize by action, not `work/personal/hobbies/`
- **Perfectionism**: Wrong location > no organization; refine over time


path: scripts/archive_project.py
content: #!/usr/bin/env python3
"""
Move a completed project from projects/active/ to archives/.

Usage:
    python archive_project.py <project-file> [--kb-path <path>]

Examples:
    python archive_project.py my-project.md
    python archive_project.py projects/active/old-project.md --kb-path ~/my-kb/
"""

import argparse
import sys
from pathlib import Path
from datetime import datetime


def archive_project(project_file: Path, kb_path: Path) -> None:
    """Move project file to archives with metadata."""

    # Resolve paths
    if not project_file.is_absolute():
        project_file = kb_path / project_file

    if not project_file.exists():
        print(f"❌ Project file not found: {project_file}")
        sys.exit(1)

    # Determine source and destination
    archives_path = kb_path / "archives"
    if not archives_path.exists():
        archives_path.mkdir(parents=True)
        print(f"✅ Created archives/ directory")

    # Create archived filename with date
    date_str = datetime.now().strftime("%Y-%m-%d")
    archived_name = f"{project_file.stem}-archived-{date_str}{project_file.suffix}"
    dest_file = archives_path / archived_name

    # Read original content
    content = project_file.read_text()

    # Add archive metadata at top
    archive_note = f"""---
ARCHIVED: {datetime.now().strftime("%Y-%m-%d")}
Original location: {project_file.relative_to(kb_path)}
---

"""

    archived_content = archive_note + content

    # Write to archives
    dest_file.write_text(archived_content)
    print(f"✅ Archived to: {dest_file.relative_to(kb_path)}")

    # Remove original
    project_file.unlink()
    print(f"✅ Removed: {project_file.relative_to(kb_path)}")

    print(f"\n✅ Project successfully archived!")


def main():
    parser = argparse.ArgumentParser(
        description="Archive a completed project"
    )
    parser.add_argument(
        "project_file",
        type=Path,
        help="Path to project file (relative to KB root or absolute)"
    )
    parser.add_argument(
        "--kb-path",
        type=Path,
        default=Path.cwd(),
        help="Path to knowledge base root (default: current directory)"
    )

    args = parser.parse_args()
    archive_project(args.project_file, args.kb_path)


if __name__ == "__main__":
    main()


path: scripts/generate_nav.py
content: #!/usr/bin/env python3
"""
Generate or update AI agent navigation index (AGENTS.md).

Scans PARA structure and creates efficient navigation file for AI agents.

Usage:
    python generate_nav.py [--kb-path <path>] [--output <file>]

Examples:
    python generate_nav.py
    python generate_nav.py --kb-path ~/my-kb/
    python generate_nav.py --output CLAUDE.md
"""

import argparse
from pathlib import Path
from typing import List, Dict


def scan_directory(path: Path, max_depth: int = 2) -> List[str]:
    """Scan directory and return list of subdirectories up to max_depth."""
    if not path.exists():
        return []

    dirs = []
    for item in sorted(path.iterdir()):
        if item.is_dir() and not item.name.startswith('.'):
            dirs.append(item.name)
    return dirs


def generate_navigation(kb_path: Path) -> str:
    """Generate AGENTS.md content based on KB structure."""

    kb_name = kb_path.name

    # Scan structure
    projects_subdirs = scan_directory(kb_path / "projects")
    areas_subdirs = scan_directory(kb_path / "areas")
    resources_subdirs = scan_directory(kb_path / "resources")

    # Build navigation content
    nav_content = f"""# AI Agent Navigation Index

**Purpose**: PARA-based PKM system for {kb_name}.

## Quick Lookup Paths

"""

    # Add paths based on what exists
    if projects_subdirs:
        nav_content += "**Active projects**: `projects/active/`\n"
        if "stories" in projects_subdirs:
            nav_content += "**Project stories**: `projects/stories/` (narratives + fragments)\n"

    if areas_subdirs:
        nav_content += "**Ongoing areas**: `areas/`\n"
        for area in areas_subdirs:
            nav_content += f"  - {area}: `areas/{area}/`\n"

    if resources_subdirs:
        nav_content += "**Reference material**: `resources/`\n"
        for resource in resources_subdirs:
            nav_content += f"  - {resource}: `resources/{resource}/`\n"

    nav_content += "**Archived work**: `archives/`\n"

    nav_content += """
## PARA Structure

```
projects/     = Time-bound goals with deadlines
areas/        = Ongoing responsibilities
resources/    = Reference material
archives/     = Completed/inactive work
```

## Navigation Tips

Use grep to find specific topics. Use glob for file patterns.
"""

    return nav_content


def main():
    parser = argparse.ArgumentParser(
        description="Generate AI agent navigation index"
    )
    parser.add_argument(
        "--kb-path",
        type=Path,
        default=Path.cwd(),
        help="Path to knowledge base (default: current directory)"
    )
    parser.add_argument(
        "--output",
        type=str,
        default="AGENTS.md",
        help="Output filename (default: AGENTS.md)"
    )

    args = parser.parse_args()
    kb_path = args.kb_path

    if not kb_path.exists():
        print(f"❌ Path does not exist: {kb_path}")
        return 1

    print(f"🔍 Scanning PARA structure: {kb_path}")

    # Generate navigation
    nav_content = generate_navigation(kb_path)

    # Write to file
    output_path = kb_path / args.output
    output_path.write_text(nav_content)

    print(f"✅ Generated {args.output}")
    print(f"   Location: {output_path}")


if __name__ == "__main__":
    main()


path: scripts/init_para_kb.py
content: #!/usr/bin/env python3
"""
Initialize a new PARA-based knowledge base structure.

Usage:
    python init_para_kb.py <kb-name> [--path <directory>]

Examples:
    python init_para_kb.py my-kb
    python init_para_kb.py my-kb --path ~/knowledge-bases/
"""

import argparse
import sys
from pathlib import Path


def create_para_structure(kb_name: str, base_path: Path) -> None:
    """Create PARA directory structure."""
    kb_path = base_path / kb_name

    if kb_path.exists():
        print(f"❌ Directory already exists: {kb_path}")
        sys.exit(1)

    # Create main PARA folders
    folders = [
        "projects/active",
        "projects/stories",
        "projects/stories/fragments",
        "areas",
        "resources",
        "archives",
    ]

    print(f"🚀 Creating PARA knowledge base: {kb_name}")
    print(f"   Location: {kb_path}\n")

    for folder in folders:
        (kb_path / folder).mkdir(parents=True, exist_ok=True)
        print(f"✅ Created {folder}/")

    # Create README
    readme_content = f"""# {kb_name}

Personal knowledge base using the PARA method.

## Structure

### projects/
**Time-bound goals with deadlines**
- `active/` - Current projects
- `stories/` - Project narratives (full + fragments)

### areas/
**Ongoing responsibilities** - Long-term commitments

### resources/
**Reference material** - Standards, configs, templates

### archives/
**Completed work** - Inactive projects and areas

## PARA Method

- **Projects**: Time-bound goals (e.g., "Launch product X by Q2")
- **Areas**: Ongoing responsibilities (e.g., "Health", "Career", "Business operations")
- **Resources**: Topics of interest, reference material (e.g., "Coding standards", "Design patterns")
- **Archives**: Completed projects and inactive areas

For more about PARA: https://fortelabs.com/blog/para/
"""

    (kb_path / "README.md").write_text(readme_content)
    print(f"✅ Created README.md")

    # Create basic AGENTS.md
    agents_content = """# AI Agent Navigation Index

**Purpose**: PARA-based knowledge base navigation for AI agents.

## Quick Lookup Paths

**Active projects**: `projects/active/`
**Project stories**: `projects/stories/` (narratives + fragments)
**Ongoing areas**: `areas/`
**Reference material**: `resources/`
**Archived work**: `archives/`

## PARA Structure

```
projects/     = Time-bound goals with deadlines
areas/        = Ongoing responsibilities
resources/    = Reference material
archives/     = Completed/inactive work
```

## Navigation Tips

Use grep to find specific topics. Use glob for file patterns.
"""

    (kb_path / "AGENTS.md").write_text(agents_content)
    print(f"✅ Created AGENTS.md")

    print(f"\n✅ PARA knowledge base '{kb_name}' initialized successfully!")
    print(f"\nNext steps:")
    print(f"1. cd {kb_path}")
    print(f"2. Start adding projects to projects/active/")
    print(f"3. Add areas to areas/")
    print(f"4. Add reference material to resources/")


def main():
    parser = argparse.ArgumentParser(
        description="Initialize a new PARA-based knowledge base"
    )
    parser.add_argument("kb_name", help="Name of the knowledge base")
    parser.add_argument(
        "--path",
        type=Path,
        default=Path.cwd(),
        help="Base path where KB will be created (default: current directory)",
    )

    args = parser.parse_args()
    create_para_structure(args.kb_name, args.path)


if __name__ == "__main__":
    main()


path: scripts/validate_para.py
content: #!/usr/bin/env python3
"""
Validate PARA knowledge base structure and detect common issues.

Usage:
    python validate_para.py [path]

Examples:
    python validate_para.py
    python validate_para.py ~/my-kb/
"""

import argparse
import sys
from pathlib import Path
from typing import List, Tuple


def validate_structure(kb_path: Path) -> List[Tuple[str, str]]:
    """
    Validate PARA structure and return list of (level, message) tuples.
    Levels: 'OK', 'WARN', 'ERROR'
    """
    issues = []

    # Check main PARA folders
    required_folders = ["projects", "areas", "resources", "archives"]
    for folder in required_folders:
        folder_path = kb_path / folder
        if not folder_path.exists():
            issues.append(("ERROR", f"Missing required folder: {folder}/"))
        elif not folder_path.is_dir():
            issues.append(("ERROR", f"{folder} exists but is not a directory"))
        else:
            issues.append(("OK", f"Found {folder}/"))

    # Check for common patterns
    projects_path = kb_path / "projects"
    if projects_path.exists():
        if not (projects_path / "active").exists():
            issues.append(("WARN", "Consider creating projects/active/ for active projects"))

    # Check for navigation file
    if (kb_path / "AGENTS.md").exists():
        issues.append(("OK", "Found AGENTS.md (AI navigation)"))
    elif (kb_path / "CLAUDE.md").exists():
        issues.append(("OK", "Found CLAUDE.md (AI navigation)"))
    else:
        issues.append(("WARN", "No AGENTS.md or CLAUDE.md found - consider creating for AI agents"))

    # Check for README
    if (kb_path / "README.md").exists():
        issues.append(("OK", "Found README.md"))
    else:
        issues.append(("WARN", "No README.md found - consider creating for documentation"))

    # Check for common anti-patterns
    if (kb_path / "inbox").exists():
        issues.append(("WARN", "Found 'inbox/' - PARA doesn't use inbox folders, capture directly into Projects/Areas/Resources"))

    if (kb_path / "todo").exists() or (kb_path / "todos").exists():
        issues.append(("WARN", "Found 'todo/' - tasks should live with their projects/areas, not separately"))

    return issues


def main():
    parser = argparse.ArgumentParser(
        description="Validate PARA knowledge base structure"
    )
    parser.add_argument(
        "path",
        nargs="?",
        type=Path,
        default=Path.cwd(),
        help="Path to knowledge base (default: current directory)",
    )

    args = parser.parse_args()
    kb_path = args.path

    if not kb_path.exists():
        print(f"❌ Path does not exist: {kb_path}")
        sys.exit(1)

    if not kb_path.is_dir():
        print(f"❌ Path is not a directory: {kb_path}")
        sys.exit(1)

    print(f"🔍 Validating PARA structure: {kb_path}\n")

    issues = validate_structure(kb_path)

    # Print results
    errors = [msg for level, msg in issues if level == "ERROR"]
    warnings = [msg for level, msg in issues if level == "WARN"]
    oks = [msg for level, msg in issues if level == "OK"]

    if oks:
        print("✅ Valid:")
        for msg in oks:
            print(f"   {msg}")
        print()

    if warnings:
        print("⚠️  Warnings:")
        for msg in warnings:
            print(f"   {msg}")
        print()

    if errors:
        print("❌ Errors:")
        for msg in errors:
            print(f"   {msg}")
        print()
        sys.exit(1)

    if not errors:
        print("✅ PARA structure is valid!")
        if warnings:
            print("   (with warnings noted above)")


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)