workplan-ai 0.3.0

AI-powered weekly planning for professional developers

Workplan AI 👊

Developer-first weekly planning and execution assistant.

Workplan AI is a CLI tool designed for engineers who want to maintain a high-performance corporate rhythm. It turns your weekly goals into structured 6-day roadmaps and automates your reporting by syncing directly with your Git activity.

---

🚀 Installation & Setup

1. Install from PyPI:

   pip install workplan-ai
   

2. Initialize the workspace:

   workplan init
   

   This creates a local .workplan directory and sets up your secure API configuration.

3. Connect your Workplan API key (for cloud sync):

   workplan auth
   

---

📘 Complete Command Guide

1. Planning your Week

• workplan plan "Goal" (Alias: p): Uses 9-stage AI expansion to generate 8-12 high-impact tasks.
• workplan details (Alias: ls): Shows your current goal, task statuses, total points, and Focus Score.
• workplan restore [ID]: Instantly revert to a previous plan from an automatic backup.

2. Daily Execution

• workplan task <ID> (Alias: inspect): View full details, including Daily Microtasks.
• workplan decompose <ID>: Uses AI to break a big task into 3-5 actionable daily steps.
• workplan update <ID> --status <status> (Alias: u): Manually update a task or microtask (use -m for microtasks).
• workplan sync (Alias: s): Auto-scan Git commits for Task IDs (e.g., "TASK-1") to mark done.
• workplan eod: Generates a professional daily summary based on Git activity. Use --sheet to append the summary to a Google Sheet. Use --map "Header=field" to override EOD mappings (e.g., "Daily Update=summary").

3. Automation & Intelligence

• workplan git-hook --install: Inserts a post-commit hook for automatic syncing.
• workplan check: Validates your recent commits for "Task Hygiene".
• Dependency Intelligence: The AI reads pyproject.toml or requirements.txt to recommend library-specific tasks.
• workplan cloud-sync --mode [push|pull]: Syncs your weekly plan with the cloud backend.
• workplan team-sync: Sends your latest status to team workspaces.

4. Multi-Project Management

• workplan dashboard (Alias: ps): Shows a unified view of active plans across all projects.
• workplan details --project <name>: View plan for any registered project.

5. Reporting & Retrospectives

• workplan export --format [csv|json]: Generates a manager-ready status report.
• workplan weekly: Generates a professional weekly summary using tasks and recent Git activity.
• workplan usage: Fetches your current token usage and limits from the backend.
• workplan carryover <ID> --reason "Reason": Marks a task for next week with a professional rationale.
• workplan health: Analyzes historical reliability, velocity, and focus trends.

6. Integrations

• workplan integrations: Shows which integrations are connected in your account.
• workplan slack --mode [eod|weekly]: Posts EOD or weekly summaries to Slack.
• workplan github --repo owner/name: Creates GitHub issues from your weekly tasks.
• workplan sheets --spreadsheet-id SHEET_ID: Exports your plan to Google Sheets (Premium). Accepts a full URL or sheet ID and respects existing headers as the schema.
• workplan sheets-schema --sheet <URL>: Shows the current header schema detected in the Google Sheet.
• workplan jira: Syncs tasks to Jira (managed integration).

7. Growth

• workplan upgrade: Explore the roadmap for Premium features.
• workplan billing: Manage subscription and invoices via the dashboard.

---

🔗 Integration Connection & Sync Workflow

Workplan AI uses a managed integration model so your tools stay in sync without manual token handling on your machine.

Phase 1: One-Time Handshake (Web)

1. Authorize: Click "Connect" on the /integrations page.
2. Consent: Approve permissions in the provider's official OAuth popup.
3. Encrypted Storage: The provider returns a token to the Workplan AI backend, which encrypts it and stores it in your private vault.

Note: We never see your password. Only revocable permission tokens are stored.

Phase 2: Sync-on-Command (CLI)

You run a command in the terminal (examples):

workplan sheets --sheet "https://docs.google.com/spreadsheets/d/.../edit?gid=0#gid=0"
workplan slack --mode eod
workplan github --repo owner/name

The CLI sends your API key and Workplan data to the backend. The backend validates your key, retrieves the encrypted OAuth token, and performs the action as a secure proxy to the provider.

Variable Handling

Variable Type	How it is handled
Secrets (tokens)	Managed via OAuth, never stored locally
Configs (IDs/channels)	Passed as CLI args or stored in your profile

Automatic Syncing

• Token Refreshing: Tokens are refreshed automatically when expired.
• Multi-Device Portability: Integrations work across devices because tokens live in the backend vault.

Last updated: February 2026

---

💎 The "Corporate Rhythm" Philosophy

• High Intent, Low Ceremony: Spend 2 minutes planning on Monday, let the AI and Git hooks handle the tracking, and export your report on Friday.
• Outcome Driven: Every task generated is designed to result in a tangible technical artifact.
• Professional Transparency: Use the Risk and Carryover signals to manage expectations with your team before deadlines hit.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Crafted by Sahil Selokar