Metadata-Version: 2.4
Name: workplan-ai
Version: 0.3.0
Summary: AI-powered weekly planning for professional developers
Author-email: Sahil Selokar <sahilselokar03@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/SahilSelokar/workplan-ai
Project-URL: Bug Tracker, https://github.com/SahilSelokar/workplan-ai/issues
Project-URL: Repository, https://github.com/SahilSelokar/workplan-ai
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]
Requires-Dist: pydantic
Requires-Dist: rich
Requires-Dist: python-dotenv
Requires-Dist: groq
Requires-Dist: keyring
Requires-Dist: requests
Requires-Dist: slack_sdk
Requires-Dist: PyGithub
Dynamic: license-file

# Workplan AI 👊

[![PyPI version](https://badge.fury.io/py/workplan-ai.svg)](https://badge.fury.io/py/workplan-ai)
[![Downloads](https://img.shields.io/pypi/dm/workplan-ai)](https://pypi.org/project/workplan-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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**:
   ```bash
   pip install workplan-ai
   ```

2. **Initialize the workspace**:
   ```bash
   workplan init
   ```
   *This creates a local `.workplan` directory and sets up your secure API configuration.*

3. **Connect your Workplan API key (for cloud sync)**:
    ```bash
    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):

```bash
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](LICENSE) file for details.

**Crafted by Sahil Selokar**
 
 
