Skip to content
BranchesTags

Repository files navigation

Personal AI Employee - Bronze Tier Foundation

Status Tier Verification

Building a Personal AI Employee using Claude Code, Obsidian, and SpecifyPlus methodology

A foundational implementation of an autonomous AI Employee that monitors files, processes tasks, and maintains operational state using local-first architecture. This Bronze tier establishes the core infrastructure for personal and business automation.

🎯 What is This?

This project implements the Bronze Tier of the Personal AI Employee Hackathon - a challenge to build an AI-powered assistant that can autonomously manage personal and business tasks.

Bronze Tier Goal: Create the foundational infrastructure with automatic file detection, AI-powered processing, and human-readable state management.

✨ Features

Core Capabilities

  • ✅ Obsidian Vault - Centralized workspace with Dashboard and Company Handbook
  • ✅ File System Watcher - Automatic detection of new files (< 10 seconds)
  • ✅ Claude Code Integration - AI-powered task processing and reasoning
  • ✅ Agent Skills - Reusable automation capabilities (3 skills documented)
  • ✅ Human-in-the-Loop - Approval workflow structure for sensitive actions
  • ✅ Audit Logging - Complete activity trail in Logs folder

Architecture Highlights

  • Local-First: All data stays on your machine (privacy-focused)
  • Markdown-First: Human-readable files, version-controllable
  • Event-Driven: Automatic detection and processing
  • Extensible: Ready for Silver tier enhancements

📊 Project Statistics

Metric Value
SpecifyPlus Documentation 1,526 lines
Implementation Files 25 files
Agent Skills 3 documented
Functional Requirements 20 (all met)
Success Criteria 12 (all verified)
Verification Status 5/5 checks passed ✅

🚀 Quick Start

Prerequisites

Installation

  1. Clone the repository

    git clone https://github.com/Tahaimran56/personalAIEmployee_bronze_level.git
cd personalAIEmployee_bronze_level

  2. Install Python dependencies

    cd AI_Employee_Vault
pip install -r requirements.txt

  3. Open vault in Obsidian

    • Launch Obsidian
    • Click "Open folder as vault"
    • Select AI_Employee_Vault directory

  4. Verify installation

    python verify_bronze.py .

    Expected output: 🎉 BRONZE TIER: COMPLETE ✅

📖 Usage

Start the File System Watcher

cd AI_Employee_Vault
python filesystem_watcher.py .

The watcher will monitor the Inbox/ folder and automatically create action items for new files.

Test the Workflow

  1. Drop a file in AI_Employee_Vault/Inbox/

    echo "Test task" > AI_Employee_Vault/Inbox/test.txt

  2. Watch it process - Action file appears in Needs_Action/ within 10 seconds

  3. Process with Claude Code - Read, add notes, move to Done/

  4. Check Dashboard - Open Dashboard.md in Obsidian to see updated status

Agent Skills

Three automation skills are available:

  • /process-actions - Process all pending items in Needs_Action/
  • /update-dashboard - Refresh Dashboard with current metrics
  • /start-watcher - Start the File System Watcher

See .claude/skills/ for detailed documentation.

📁 Project Structure

personalAIEmployee_bronze_level/
├── .specify/
│   └── memory/
│       └── constitution.md          # Project principles (7 core principles)
├── specs/
│   └── 001-bronze-tier-foundation/
│       ├── spec.md                  # Requirements (4 user stories, 20 FRs)
│       ├── plan.md                  # Architecture (594 lines)
│       ├── tasks.md                 # Implementation (49 tasks)
│       └── checklists/
│           └── requirements.md      # Quality validation (14/14 passed)
├── history/
│   └── prompts/
│       └── bronze-tier-foundation/
│           └── 001-bronze-tier-spec-documentation.spec.prompt.md
├── AI_Employee_Vault/               # Obsidian vault (main workspace)
│   ├── .claude/skills/              # Agent Skills documentation
│   ├── .obsidian/                   # Obsidian configuration
│   ├── Inbox/                       # Entry point for new files
│   ├── Needs_Action/                # Tasks awaiting processing
│   ├── Done/                        # Completed tasks
│   ├── Pending_Approval/            # Awaiting human approval
│   ├── Approved/                    # Ready for execution
│   ├── Plans/                       # Multi-step strategies
│   ├── Logs/                        # Activity audit trail
│   ├── Dashboard.md                 # Command center
│   ├── Company_Handbook.md          # Operating rules
│   ├── base_watcher.py              # Base watcher class
│   ├── filesystem_watcher.py        # File monitoring
│   ├── verify_bronze.py             # Verification script
│   ├── BRONZE_TIER_README.md        # Complete usage guide
│   └── BRONZE_TIER_COMPLETE.md      # Achievement report
├── hackathonread.md                 # Hackathon requirements
├── CLAUDE.md                        # Claude Code configuration
└── README.md                        # This file

🎓 SpecifyPlus Methodology

This project follows the SpecifyPlus software development methodology:

Workflow: Constitution → Spec → Plan → Tasks → Implement → Verify → Document

Artifacts Created

  1. Constitution (248 lines)

    • 7 core principles (Local-First, HITL Safety, Markdown-First, Agent Skills, Tiered Complexity, Fail-Safe Errors, Spec-Driven Development)
    • Security & privacy standards
    • Development workflow
    • Governance rules

  2. Specification (197 lines)

    • 4 user stories with acceptance scenarios
    • 20 functional requirements
    • 12 success criteria (measurable, technology-agnostic)
    • Edge cases, assumptions, dependencies

  3. Implementation Plan (594 lines)

    • Technical context and architecture decisions
    • 8 major design decisions with rationale
    • Implementation strategy and build order
    • Risk analysis and mitigation

  4. Tasks Document (437 lines)

    • 49 tasks organized by user story
    • Clear acceptance criteria for each task
    • Dependency tracking and parallel opportunities

All artifacts available in specs/001-bronze-tier-foundation/

🔧 Technical Details

Technology Stack

  • Vault: Obsidian (Markdown editor)
  • AI: Claude Code 2.1.30 (reasoning engine)
  • Watchers: Python 3.13+ (file monitoring)
  • Libraries: watchdog 6.0.0, python-dotenv 1.2.1
  • Version Control: Git

Architecture

Pattern: Event-Driven Architecture with File-Based State

[File Drop] → [Watcher Detects] → [Action File Created] →
[Claude Processes] → [Task Completed] → [Dashboard Updated]

Key Design Decisions:

  • Object-oriented watcher design (base class + inheritance)
  • Markdown with YAML frontmatter for action files
  • Keyword-based priority detection
  • Single Dashboard file for status overview
  • File-based approval workflow (HITL safety)

See Implementation Plan for detailed architecture.

✅ Verification

Run the automated verification script:

cd AI_Employee_Vault
python verify_bronze.py .

Checks Performed:

  • ✅ Folder Structure (9 folders)
  • ✅ Core Files (Dashboard, Handbook, README)
  • ✅ Watcher Scripts (base + filesystem)
  • ✅ Agent Skills (3 skills documented)
  • ✅ Test Workflow (end-to-end tested)

Result: 5/5 checks passed ✅

📚 Documentation

For Users

For Developers

For Hackathon Judges

🎯 Bronze Tier Requirements (All Met)

From hackathonread.md lines 118-130:

  • ✅ Obsidian vault with Dashboard.md and Company_Handbook.md
  • ✅ One working Watcher (File System Watcher operational)
  • ✅ Claude Code integration (read/write verified)
  • ✅ Folder structure (/Inbox, /Needs_Action, /Done + extras)
  • ✅ Agent Skills (3 skills documented)

Status: 5/5 requirements complete ✅

🚀 Next Steps: Silver Tier

Bronze tier is complete! Ready to advance to Silver Tier: Functional Assistant

Silver Tier Requirements

  1. Two or more Watcher scripts (Gmail + WhatsApp/LinkedIn)
  2. Automatically post on LinkedIn about business
  3. Claude reasoning loop that creates Plan.md files
  4. One working MCP server for external action (email sending)
  5. Human-in-the-loop approval workflow for sensitive actions
  6. Basic scheduling via cron or Task Scheduler
  7. All functionality as Agent Skills

Estimated Time: 20-30 hours

🤝 Contributing

This is a hackathon project for the Personal AI Employee challenge. While this repository represents the Bronze tier completion, contributions and suggestions are welcome!

How to Contribute

  1. Fork the repository
  2. Create a feature branch
  3. Follow the SpecifyPlus methodology (Constitution → Spec → Plan → Tasks → Implement)
  4. Submit a pull request

📄 License

This project is part of the Personal AI Employee Hackathon. See hackathon guidelines for usage terms.

🙏 Acknowledgments

  • Hackathon Organizers - For the comprehensive challenge and guidelines
  • Claude Code - AI-powered development tool
  • Obsidian - Markdown-based knowledge management
  • SpecifyPlus - Systematic development methodology

📞 Contact & Support

🏆 Achievement Summary

Bronze Tier: Foundation ✅ COMPLETE

  • Implementation: Fully functional AI Employee foundation
  • Documentation: 1,526 lines of SpecifyPlus artifacts
  • Verification: 5/5 automated checks passed
  • Quality: 14/14 specification quality checks passed
  • Architecture: Event-driven, local-first, extensible
  • Ready For: Silver Tier implementation

Built with: Claude Code, Obsidian, Python, SpecifyPlus Methodology Version: 1.0 (Bronze Tier) Last Updated: 2026-02-03 Status: ✅ Complete & Verified

This project demonstrates systematic software development using the SpecifyPlus methodology, combining AI-powered automation with human-readable documentation and local-first architecture.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages