# Pixel Planner
Automate project plans written in Markdown. Generate a clean, gantt-like timeline from your phases and milestones, and keep progress indicators up to date with a single command.
## Features
- Initialize a new plan from a template
- Parse phases and milestones from the plan
- Generate/refresh a gantt-like "Project Timeline (Phases)" section
- Generate/refresh "Milestone Status Overview" graph showing status distribution
- Current-date marker with clamping to last milestone date
- Global and per-phase percentages showing actual vs should-be
- Flexible baseline vs current planning basis selection for timeline comparison
## Installation
### Option 1: Install via pip (Recommended)
```bash
pip install pixel-planner
```
### Option 2: Clone and run (Development)
- Python 3.9+ required
- Clone this repository and use `python3 scripts/pixel_planner.py`
## Quick start
1) Create a plan from the template
```bash
# If installed via pip/brew:
pixel-planner init --out Project-Plan.md --project "My Project"
# If using cloned repository:
python3 scripts/pixel_planner.py init \
--template templates/pixel-planner-phase-template.md \
--out Project-Plan.md \
--project "My Project"
```
2) Edit your plan: fill the phases and milestone tables
3) Generate or refresh the timeline
- In place (recommended):
```bash
# If installed via pip/brew:
pixel-planner timeline --in Project-Plan.md --in-place --basis current
# If using cloned repository:
python3 scripts/pixel_planner.py timeline --in Project-Plan.md --in-place --basis current
```
- Include milestone status overview graph:
```bash
pixel-planner timeline --in Project-Plan.md --in-place --basis current --include-status
```
- To a separate file using baseline dates:
```bash
pixel-planner timeline --in Project-Plan.md --out Project-Plan.out.md --basis baseline --version v1.0
```
- Generate as-of a specific date (for reproducible timelines):
```bash
pixel-planner timeline --in Project-Plan.md --in-place --basis current --date 2025-03-02
```
## Sample project
- A complete example is included: [`Sample-Project-Plan.md`](./Sample-Project-Plan.md)
- Regenerate its timeline anytime:
```bash
# If installed via pip/brew:
pixel-planner timeline --in Sample-Project-Plan.md --in-place --basis current --include-status
# If using cloned repository:
python3 scripts/pixel_planner.py timeline --in Sample-Project-Plan.md --in-place --basis current --include-status
```
## Short history (vibe-coding)
- This project was built using a vibe-coding (AI-assisted pair programming) workflow.
- The only manually created artifact at the start was the first Markdown template; everything else
(the Python CLI, timeline logic, clamping and percentage rules, sample plan, tests, CI, and repo docs)
was iteratively generated and refined in-session.
My take: this approach fits this tool very well. Rapid, iterative edits plus immediate feedback make it
easy to converge on the exact timeline semantics and formatting you want. The added tests and CI balance
speed with correctness and maintainability. For larger systems, I’d complement this with brief design docs
and peer reviews, but for a focused automation like Pixel Planner, vibe-coding was a strong choice.
## Template rules (what the script expects)
- Timeline section
- There must be a heading named exactly `## Project Timeline (Phases)`
- The content under it is a fenced block (```text ... ```). The script fully rewrites this block.
- Phase sections
- Each phase must use a heading of the form: `## Phase 01 – Phase Name` (hyphen `-` also accepted instead of the en dash `–`).
- Milestone table under each phase
- Columns (any alignment/width). Names are matched case-insensitively by meaning:
- Milestone | Description | Status | Baseline Plan | Current Plan | Assignee | Comments
- Dates must be ISO `YYYY-MM-DD`. Values like `N/A`, `NA`, `TBD` are treated as empty.
- A milestone is counted as executed only when `Status` is `Done` (case-insensitive).
## Timeline details
- Bars and weeks
- Each `■` represents one calendar week. Bars are aligned over a global week grid spanning the earliest to latest plan dates (based on `--basis`).
- A vertical `|` marks the effective date week.
- Bars always close with a `]` and are clipped properly at the right edge.
- Effective date (header arrow)
- The header shows: `┌─→ YYYY-MM-DD (X% / Y%)`
- The effective date is today, but if today is beyond the last milestone date (across all phases), it is clamped to that last milestone date.
- Basis (which plan dates are used)
- `--basis current` (default): position bars and compute "should-be" from Current Plan dates. Shows activity evolution percentages.
- `--basis baseline`: use Baseline Plan dates instead. Shows clean timeline bars without activity evolution percentages.
- This separation allows you to maintain both your original baseline and revised current plans, enabling comparison between planned vs actual timeline evolution.
- You can generate timelines using either version independently, making it easy to track scope changes and schedule adjustments over time.
## Percentages (progress logic)
**Note: Activity evolution percentages are only shown for `--basis current` timelines. Baseline timelines show clean bars without percentages.**
- Header percentages (global): `X% / Y%`
- X% = executed/total across all milestones (executed = count of `Done`).
- Y% = planned-by-effective-date/total across all milestones, based on the chosen basis.
- Per-phase percentages: `X% / Y%`
- X% = executed_in_phase / total_in_phase.
- Y% = planned_by_effective_date_in_phase / total_in_phase, using the chosen basis.
- Important rule: "planned-by-effective-date" uses a strict comparison of planned date < effective date. Milestones due today are counted as should-be tomorrow (after the day passes).
- Direction indicator: ▲ if executed ≥ should-be; otherwise ▼ (for current timelines only).
## Milestone Status Overview
When using `--include-status`, a status graph is generated showing milestone distribution:
- Each ■ represents 10% of total milestones
- Status names are automatically aligned for readability
- Sorted by count (descending), then alphabetically
```text
- Backlog : 14 → [■ ■ ■ ■ ■ ■ ■ ■] 82%
- Done : 01 → [■] 6%
- In Progress : 01 → [■] 6%
- Ready for Review : 01 → [■] 6%
```
## Example timelines
### Current timeline (with activity evolution percentages)
```vb
┌─→ 2025-03-02 (33% / 67%)
- Phase 01 – Install Infrastructure ▲ W 05-08 2025-01-31 to 2025-02-20 → [■ ■ ■ ■] 50% / 100%
- Phase 02 – Deploy new App ▼ W 09-09 2025-03-02 to 2025-03-02 → | [■] 0% / 0%
```
### Baseline timeline (clean bars without percentages)
```text
- Phase 01 – Install Infrastructure ▲ W 05-08 2025-01-31 to 2025-02-20 → [■ ■ ■ ■]
- Phase 02 – Deploy new App ▲ W 09-09 2025-03-02 to 2025-03-02 → [■]
```
## Tips and gotchas
- Keep the timeline heading spelled exactly as `## Project Timeline (Phases)`
- Keep the status heading spelled exactly as `## Milestone Status Overview` (when using `--include-status`)
- Use correct phase heading format: `## Phase <number> – <name>` (or `-`)
- Use ISO dates. If a phase has no valid dates for the selected basis, its bar may be empty but the line still renders.
- Only `Done` marks a milestone as executed.
- The `Week` column is deprecated and ignored in parsing; you can safely remove it.
## Troubleshooting
- Timeline didn't update
- Check the heading and code fence (```text) under the timeline section
- Status overview didn't update
- Check the heading and code fence (```text) under the status section
- Ensure you used `--include-status` flag
- A phase didn't show a bar
- Ensure it has at least one valid planned date for the chosen basis
- Percentages look wrong
- Verify `Status` values and planned dates; items due today don't count as should-be yet
## Development & Contributing
### Development Setup
```bash
git clone https://github.com/ivannagy/pixel-planner.git
cd pixel-planner
pip install -r requirements-dev.txt
pip install -e .
```
### Running Tests
```bash
pytest -q # Run all tests
ruff check . # Lint code
mypy pixel_planner # Type check
```
### Releasing
See [RELEASING.md](RELEASING.md) for the automated release process.
### Contributing
Improvements welcome! Please:
- Keep changes small and readable
- Add tests for new functionality
- Follow existing code style
- Submit pull requests for review
## License
Apache-2.0. See `LICENSE`. A `NOTICE` file is included for attribution.
Raw data
{
"_id": null,
"home_page": null,
"name": "pixel-planner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "markdown, project-management, gantt, timeline, planning",
"author": null,
"author_email": "Ivan Nagy <786743+ivannagy@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/a4/13/5c8fc8b2e3dcff494075513ba39d7d061203abe84d0b4886292b1a3977f2/pixel_planner-0.2.2.tar.gz",
"platform": null,
"description": "# Pixel Planner\n\nAutomate project plans written in Markdown. Generate a clean, gantt-like timeline from your phases and milestones, and keep progress indicators up to date with a single command.\n\n## Features\n- Initialize a new plan from a template\n- Parse phases and milestones from the plan\n- Generate/refresh a gantt-like \"Project Timeline (Phases)\" section\n- Generate/refresh \"Milestone Status Overview\" graph showing status distribution\n- Current-date marker with clamping to last milestone date\n- Global and per-phase percentages showing actual vs should-be\n- Flexible baseline vs current planning basis selection for timeline comparison\n\n## Installation\n\n### Option 1: Install via pip (Recommended)\n```bash\npip install pixel-planner\n```\n\n### Option 2: Clone and run (Development)\n- Python 3.9+ required\n- Clone this repository and use `python3 scripts/pixel_planner.py`\n\n## Quick start\n1) Create a plan from the template\n\n```bash\n# If installed via pip/brew:\npixel-planner init --out Project-Plan.md --project \"My Project\"\n\n# If using cloned repository:\npython3 scripts/pixel_planner.py init \\\n --template templates/pixel-planner-phase-template.md \\\n --out Project-Plan.md \\\n --project \"My Project\"\n```\n\n2) Edit your plan: fill the phases and milestone tables\n\n3) Generate or refresh the timeline\n\n- In place (recommended):\n```bash\n# If installed via pip/brew:\npixel-planner timeline --in Project-Plan.md --in-place --basis current\n\n# If using cloned repository:\npython3 scripts/pixel_planner.py timeline --in Project-Plan.md --in-place --basis current\n```\n\n- Include milestone status overview graph:\n```bash\npixel-planner timeline --in Project-Plan.md --in-place --basis current --include-status\n```\n\n- To a separate file using baseline dates:\n```bash\npixel-planner timeline --in Project-Plan.md --out Project-Plan.out.md --basis baseline --version v1.0\n```\n\n- Generate as-of a specific date (for reproducible timelines):\n```bash\npixel-planner timeline --in Project-Plan.md --in-place --basis current --date 2025-03-02\n```\n\n## Sample project\n- A complete example is included: [`Sample-Project-Plan.md`](./Sample-Project-Plan.md)\n- Regenerate its timeline anytime:\n\n```bash\n# If installed via pip/brew:\npixel-planner timeline --in Sample-Project-Plan.md --in-place --basis current --include-status\n\n# If using cloned repository:\npython3 scripts/pixel_planner.py timeline --in Sample-Project-Plan.md --in-place --basis current --include-status\n```\n\n## Short history (vibe-coding)\n- This project was built using a vibe-coding (AI-assisted pair programming) workflow.\n- The only manually created artifact at the start was the first Markdown template; everything else\n (the Python CLI, timeline logic, clamping and percentage rules, sample plan, tests, CI, and repo docs)\n was iteratively generated and refined in-session.\n\nMy take: this approach fits this tool very well. Rapid, iterative edits plus immediate feedback make it\neasy to converge on the exact timeline semantics and formatting you want. The added tests and CI balance\nspeed with correctness and maintainability. For larger systems, I\u2019d complement this with brief design docs\nand peer reviews, but for a focused automation like Pixel Planner, vibe-coding was a strong choice.\n\n## Template rules (what the script expects)\n- Timeline section\n - There must be a heading named exactly `## Project Timeline (Phases)`\n - The content under it is a fenced block (```text ... ```). The script fully rewrites this block.\n\n- Phase sections\n - Each phase must use a heading of the form: `## Phase 01 \u2013 Phase Name` (hyphen `-` also accepted instead of the en dash `\u2013`).\n\n- Milestone table under each phase\n - Columns (any alignment/width). Names are matched case-insensitively by meaning:\n - Milestone | Description | Status | Baseline Plan | Current Plan | Assignee | Comments\n - Dates must be ISO `YYYY-MM-DD`. Values like `N/A`, `NA`, `TBD` are treated as empty.\n - A milestone is counted as executed only when `Status` is `Done` (case-insensitive).\n\n## Timeline details\n- Bars and weeks\n - Each `\u25a0` represents one calendar week. Bars are aligned over a global week grid spanning the earliest to latest plan dates (based on `--basis`).\n - A vertical `|` marks the effective date week.\n - Bars always close with a `]` and are clipped properly at the right edge.\n\n- Effective date (header arrow)\n - The header shows: `\u250c\u2500\u2192 YYYY-MM-DD (X% / Y%)`\n - The effective date is today, but if today is beyond the last milestone date (across all phases), it is clamped to that last milestone date.\n\n- Basis (which plan dates are used)\n - `--basis current` (default): position bars and compute \"should-be\" from Current Plan dates. Shows activity evolution percentages.\n - `--basis baseline`: use Baseline Plan dates instead. Shows clean timeline bars without activity evolution percentages.\n - This separation allows you to maintain both your original baseline and revised current plans, enabling comparison between planned vs actual timeline evolution.\n - You can generate timelines using either version independently, making it easy to track scope changes and schedule adjustments over time.\n\n## Percentages (progress logic)\n**Note: Activity evolution percentages are only shown for `--basis current` timelines. Baseline timelines show clean bars without percentages.**\n\n- Header percentages (global): `X% / Y%`\n - X% = executed/total across all milestones (executed = count of `Done`).\n - Y% = planned-by-effective-date/total across all milestones, based on the chosen basis.\n\n- Per-phase percentages: `X% / Y%`\n - X% = executed_in_phase / total_in_phase.\n - Y% = planned_by_effective_date_in_phase / total_in_phase, using the chosen basis.\n\n- Important rule: \"planned-by-effective-date\" uses a strict comparison of planned date < effective date. Milestones due today are counted as should-be tomorrow (after the day passes).\n\n- Direction indicator: \u25b2 if executed \u2265 should-be; otherwise \u25bc (for current timelines only).\n\n## Milestone Status Overview\nWhen using `--include-status`, a status graph is generated showing milestone distribution:\n\n- Each \u25a0 represents 10% of total milestones\n- Status names are automatically aligned for readability\n- Sorted by count (descending), then alphabetically\n\n```text\n- Backlog : 14 \u2192 [\u25a0 \u25a0 \u25a0 \u25a0 \u25a0 \u25a0 \u25a0 \u25a0] 82%\n- Done : 01 \u2192 [\u25a0] 6%\n- In Progress : 01 \u2192 [\u25a0] 6%\n- Ready for Review : 01 \u2192 [\u25a0] 6%\n```\n\n## Example timelines\n\n### Current timeline (with activity evolution percentages)\n```vb\n \u250c\u2500\u2192 2025-03-02 (33% / 67%)\n- Phase 01 \u2013 Install Infrastructure \u25b2 W 05-08 2025-01-31 to 2025-02-20 \u2192 [\u25a0 \u25a0 \u25a0 \u25a0] 50% / 100%\n- Phase 02 \u2013 Deploy new App \u25bc W 09-09 2025-03-02 to 2025-03-02 \u2192 | [\u25a0] 0% / 0%\n```\n\n### Baseline timeline (clean bars without percentages)\n```text\n- Phase 01 \u2013 Install Infrastructure \u25b2 W 05-08 2025-01-31 to 2025-02-20 \u2192 [\u25a0 \u25a0 \u25a0 \u25a0]\n- Phase 02 \u2013 Deploy new App \u25b2 W 09-09 2025-03-02 to 2025-03-02 \u2192 [\u25a0]\n```\n\n## Tips and gotchas\n- Keep the timeline heading spelled exactly as `## Project Timeline (Phases)`\n- Keep the status heading spelled exactly as `## Milestone Status Overview` (when using `--include-status`)\n- Use correct phase heading format: `## Phase <number> \u2013 <name>` (or `-`)\n- Use ISO dates. If a phase has no valid dates for the selected basis, its bar may be empty but the line still renders.\n- Only `Done` marks a milestone as executed.\n- The `Week` column is deprecated and ignored in parsing; you can safely remove it.\n\n## Troubleshooting\n- Timeline didn't update\n - Check the heading and code fence (```text) under the timeline section\n- Status overview didn't update\n - Check the heading and code fence (```text) under the status section\n - Ensure you used `--include-status` flag\n- A phase didn't show a bar\n - Ensure it has at least one valid planned date for the chosen basis\n- Percentages look wrong\n - Verify `Status` values and planned dates; items due today don't count as should-be yet\n\n## Development & Contributing\n\n### Development Setup\n```bash\ngit clone https://github.com/ivannagy/pixel-planner.git\ncd pixel-planner\npip install -r requirements-dev.txt\npip install -e .\n```\n\n### Running Tests\n```bash\npytest -q # Run all tests\nruff check . # Lint code\nmypy pixel_planner # Type check\n```\n\n### Releasing\nSee [RELEASING.md](RELEASING.md) for the automated release process.\n\n### Contributing\nImprovements welcome! Please:\n- Keep changes small and readable\n- Add tests for new functionality\n- Follow existing code style\n- Submit pull requests for review\n\n## License\nApache-2.0. See `LICENSE`. A `NOTICE` file is included for attribution.\n",
"bugtrack_url": null,
"license": null,
"summary": "Automate project plans written in Markdown",
"version": "0.2.2",
"project_urls": {
"Bug Reports": "https://github.com/ivannagy/pixel-planner/issues",
"Homepage": "https://github.com/ivannagy/pixel-planner",
"Source": "https://github.com/ivannagy/pixel-planner"
},
"split_keywords": [
"markdown",
" project-management",
" gantt",
" timeline",
" planning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a13a1029bc6e6278792eb040f14ca0a55cf5db420b05d1c17162bd794ab4656e",
"md5": "281cd06bd3c881ee888b5441452bc74c",
"sha256": "997098a53c8eda5c3842e839ae7828d0bb0356bdaf1d31f2afd29465c47e5f5d"
},
"downloads": -1,
"filename": "pixel_planner-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "281cd06bd3c881ee888b5441452bc74c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 18270,
"upload_time": "2025-09-04T18:26:55",
"upload_time_iso_8601": "2025-09-04T18:26:55.230233Z",
"url": "https://files.pythonhosted.org/packages/a1/3a/1029bc6e6278792eb040f14ca0a55cf5db420b05d1c17162bd794ab4656e/pixel_planner-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a4135c8fc8b2e3dcff494075513ba39d7d061203abe84d0b4886292b1a3977f2",
"md5": "024378685d333be00e8fb5968697561a",
"sha256": "6173a5473d1ead93d80b1e50f39288e7652d0588168148cf1b51b1ec1c68ec9a"
},
"downloads": -1,
"filename": "pixel_planner-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "024378685d333be00e8fb5968697561a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20699,
"upload_time": "2025-09-04T18:26:56",
"upload_time_iso_8601": "2025-09-04T18:26:56.038215Z",
"url": "https://files.pythonhosted.org/packages/a4/13/5c8fc8b2e3dcff494075513ba39d7d061203abe84d0b4886292b1a3977f2/pixel_planner-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 18:26:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ivannagy",
"github_project": "pixel-planner",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pixel-planner"
}
JSON
