{"id":50472435,"url":"https://github.com/semcod/planfile","last_synced_at":"2026-06-01T11:03:34.889Z","repository":{"id":347030702,"uuid":"1192599614","full_name":"semcod/planfile","owner":"semcod","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-24T19:24:41.000Z","size":44522,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T20:29:27.454Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/semcod.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T11:29:10.000Z","updated_at":"2026-05-24T19:24:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/semcod/planfile","commit_stats":null,"previous_names":["semcod/strategy"],"tags_count":75,"template":false,"template_full_name":null,"purl":"pkg:github/semcod/planfile","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fplanfile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fplanfile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fplanfile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fplanfile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semcod","download_url":"https://codeload.github.com/semcod/planfile/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fplanfile/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33771630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-01T11:03:34.781Z","updated_at":"2026-06-01T11:03:34.878Z","avatar_url":"https://github.com/semcod.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"now:\n\n![img_1.png](img_1.png)\n\nbefore:\n\n![img.png](img.png)\n\n# Planfile\n\n[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![PyPI version](https://img.shields.io/pypi/v/planfile.svg)](https://pypi.org/project/planfile/)\n[![PyPI Downloads](https://img.shields.io/pypi/dm/planfile)](https://pypi.org/project/planfile/)\n[![CI/CD](https://github.com/semcod/planfile/workflows/CI%2FCD%20with%20Auto%20Bug-Fix%20Loop/badge.svg)](https://github.com/semcod/planfile/actions)\n[![Code Coverage](https://img.shields.io/codecov/c/github/semcod/planfile)](https://codecov.io/gh/semcod/planfile)\n[![Code Quality](https://img.shields.io/badge/CC%CC%84-4.1-brightgreen)](https://github.com/semcod/planfile)\n[![Functions](https://img.shields.io/badge/functions-395-blue)](https://github.com/semcod/planfile)\n[![Modules](https://img.shields.io/badge/modules-56-blue)](https://github.com/semcod/planfile)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![MyPy](https://img.shields.io/badge/mypy-checked-blue)](https://mypy.readthedocs.io/)\n[![Pydantic](https://img.shields.io/badge/pydantic-v2-blue)](https://pydantic.dev)\n[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com)\n[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen)](https://strategy.readthedocs.io)\n[![GitHub Issues](https://img.shields.io/github/issues/semcod/planfile)](https://github.com/semcod/planfile/issues)\n[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/semcod/planfile)](https://github.com/semcod/planfile/pulls)\n[![GitHub Stars](https://img.shields.io/github/stars/semcod/planfile)](https://github.com/semcod/planfile/stargazers)\n[![GitHub Forks](https://img.shields.io/github/forks/semcod/planfile)](https://github.com/semcod/planfile/network)\n[![Last Commit](https://img.shields.io/github/last-commit/semcod/planfile)](https://github.com/semcod/planfile/commits/main)\n[![Release Date](https://img.shields.io/github/release-date/semcod/planfile)](https://github.com/semcod/planfile/releases)\n[![Project Status](https://img.shields.io/badge/status-active-brightgreen)](https://github.com/semcod/planfile)\n\n\n## AI Cost Tracking\n\n![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.102-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)\n![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-52.5h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)\n\n- 🤖 **LLM usage:** $7.5000 (114 commits)\n- 👤 **Human dev:** ~$5248 (52.5h @ $100/h, 30min dedup)\n\nGenerated on 2026-05-24 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)\n\n---\n\n**Planfile** is an SDLC automation platform that provides strategic project management with CI/CD integration and automated bug-fix loops. It manages sprints and strategies across external ticket systems like GitHub, Jira, and GitLab.\n\n## 📊 Project Metrics\n\n- **56 modules** with **395 functions**\n- **Cyclomatic Complexity**: CC̄=4.1 (improved from 4.2)\n- **Critical functions**: 15 (target: ≤4)\n- **Zero circular dependencies**\n- **Languages**: Python (53), Shell (17), JavaScript (3)\n\n## ✨ Features\n\n- 🎯 **Strategy Modeling**: Define strategies and sprints in YAML with task patterns\n- 🔄 **Automated CI/CD Loop**: Test → Ticket → Fix → Retest automation\n- 🔌 **Multi-Backend Support**: Integrates with GitHub Issues, Jira, GitLab, and generic HTTP APIs\n- 🤖 **LLM-Powered**: AI-driven bug reports and auto-fix capabilities\n- 📊 **Progress Tracking**: Review strategy execution with detailed metrics\n- 🚀 **CLI Tool**: Easy-to-use command-line interface for applying and reviewing strategies\n- 🐍 **Python Library**: Use planfile programmatically in your Python applications\n- 🌐 **REST API**: Run as FastAPI server for HTTP access and integrations\n- 🎨 **Rich Output**: Beautiful terminal output with progress bars and tables\n- 🐳 **Docker Support**: Containerized deployment with Ollama integration\n- 🔧 **Extensible**: Easy to add new backends and custom integrations\n- 🔍 **Code Analysis**: Integration with external tools (code2llm, vallm, redup)\n- 🌐 **MCP Server**: Model Context Protocol server integration\n- 🤖 **LLX Integration**: Advanced code analysis and model selection\n- 🌉 **Proxy Routing**: Smart model routing via Proxym API\n- 📈 **Metrics-Driven**: Project metrics analysis for informed planning\n- 🗣️ **DSL (Domain Specific Language)**: Natural language-like commands for planfile operations\n- 🐛 **Bug-First Priority**: Automatic bug prioritization over features for quality assurance\n\n# Basic installation\npip install planfile\n\n# With all backend integrations\npip install planfile[all]\n\n# Or with specific backends\npip install planfile[github,jira]\npip install planfile[gitlab]\n```\n\n### 1. Create a Strategy\n\nCreate a `strategy.yaml` file:\n\n```yaml\nname: \"My Project Strategy\"\nproject_type: \"web\"\ndomain: \"fintech\"\ngoal: \"Launch a secure payment processing platform\"\n\nsprints:\n  - id: 1\n    name: \"Core Infrastructure\"\n    length_days: 14\n    objectives:\n      - Set up project structure\n      - Implement authentication\n    tasks:\n      - type: \"feature\"\n        title: \"Setup project structure\"\n        description: \"Create basic project layout and configuration\"\n        estimate: 2\n        priority: \"high\"\n\n  - id: 2\n    name: \"Payment Processing\"\n    length_days: 21\n    objectives:\n      - Implement payment gateway\n      - Add security measures\n    tasks:\n      - type: \"feature\"\n        title: \"Payment gateway integration\"\n        description: \"Integrate with payment provider API\"\n        estimate: 5\n        priority: \"critical\"\n```\n\n# GitHub\nexport GITHUB_TOKEN=your_token\nexport GITHUB_REPO=owner/repo\n\n# Jira\nexport JIRA_URL=https://company.atlassian.net\nexport JIRA_EMAIL=your@email.com\nexport JIRA_TOKEN=your_token\nexport JIRA_PROJECT=PROJ\n\n# GitLab\nexport GITLAB_TOKEN=your_token\nexport GITLAB_PROJECT_ID=123\n```\n\n# Run automated bug-fix loop\nplanfile auto loop \\\n  --strategy ./strategy.yaml \\\n  --project . \\\n  --backend github \\\n  --max-iterations 5 \\\n  --auto-fix\n\n# Check CI status\nplanfile auto ci-status\n\n# Review strategy progress\nplanfile strategy review \\\n  --strategy ./strategy.yaml \\\n  --project . \\\n  --backend github\n```\n\n## 🐛 Bug-First Priority System\n\nPlanfile automatically prioritizes bugs over features to ensure quality and stability:\n\n### **Automatic Priority Ordering**\nTickets are sorted by:\n1. **Priority Level**: critical \u003e high \u003e normal \u003e low\n2. **Bug Flag**: bugs come before features at the same priority level\n3. **Creation Date**: older tickets first within the same category\n4. **Ticket ID**: final tiebreaker\n\n### **How It Works**\n```python\n# Example sorting behavior\nPriority: critical\n├── Bug tickets (sorted by creation date)\n└── Feature tickets (sorted by creation date)\n\nPriority: normal  \n├── Bug tickets (sorted by creation date)\n└── Feature tickets (sorted by creation date)\n```\n\n### **Label-Based Detection**\n- Tickets with `bug` label are treated as bugs\n- All other tickets are treated as features\n- No manual configuration required\n\n### **Integration with Koru**\n- **Koru** auto-promotes bugs to higher priorities\n- **Planfile** respects bug-first ordering in `next_ticket()`\n- **Consistent behavior** across both systems\n- **Seamless workflow** whether using koru or planfile directly\n\n### **Benefits**\n- 🔧 **Quality First**: Bugs fixed before new features\n- ⚡ **Automatic Triage**: No manual priority adjustments needed\n- 🎯 **Predictable Execution**: Consistent ordering across all operations\n- 🛡️ **Stability Assurance**: Prevents feature development while bugs exist\n- 🔄 **Unified System**: Works with koru's auto-promotion and auto-repair modes\n\n### **Usage Example**\n```python\nfrom planfile import Planfile\n\npf = Planfile.auto_discover()\nnext_ticket = pf.next_ticket()\n\n# Returns highest priority ticket, bugs first\n# Critical bugs \u003e Critical features \u003e High bugs \u003e High features \u003e ...\n```\n\n### 4. Using Python Library\n\n```python\nfrom planfile import Planfile, quick_ticket\n\n# Auto-discover .planfile/ in your project\npf = Planfile.auto_discover(\".\")\n\n# Create tickets programmatically\nticket = pf.create_ticket(\n    name=\"Fix authentication bug\",\n    description=\"Users cannot login with OAuth\",\n    priority=\"high\",\n    labels=[\"bug\", \"backend\"]\n)\n\n# List and filter tickets\ntickets = pf.list_tickets(sprint=\"current\", status=\"open\")\n\n# Quick one-liner for tools\nticket = quick_ticket(\"Production alert\", tool=\"monitoring\", priority=\"critical\")\n```\n\n# Start the FastAPI server\nuvicorn planfile.api.server:app --reload --port 8000\n\n# Use the API\ncurl \"http://localhost:8000/tickets?sprint=current\"\ncurl -X POST \"http://localhost:8000/tickets\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"API fix\", \"priority\": \"high\"}'\n```\n\n### 5. Ticket Management CLI\n\nCreate, update, delete and bulk-manage tickets directly from command line:\n\n```bash\n# Create a new ticket\nplanfile ticket create \"Fix login bug\" -p high -l bug -l backend\n\n# List tickets with filters\nplanfile ticket list --status open\nplanfile ticket list --label bug --format json\n\n# Show the next runnable ticket in a queue-like workflow\nplanfile ticket next\nplanfile ticket next --format json\n\n# Lifecycle for queue-driven execution\nplanfile ticket input PLF-001 --prompt \"Provide OPENROUTER_API_KEY\" --env-key OPENROUTER_API_KEY\nplanfile ticket ready PLF-001\nplanfile ticket claim PLF-001 --assigned-to koru-shell\nplanfile ticket start PLF-001 --assigned-to koru-shell\nplanfile ticket fail PLF-001 --error \"HTTP 502 from upstream\"\nplanfile ticket complete PLF-001 --note \"Bootstrap done\" --artifact reports/bootstrap.json\n\n# Update a single ticket\nplanfile ticket update PLF-001 --status done\nplanfile ticket update PLF-002 --priority critical\n\n# Validate if tickets are still current\nplanfile ticket validate\nplanfile ticket validate Q01 Q02 --issues analyses/issues.yaml --format yaml\nplanfile ticket validate --stale-only --fail-on-stale\n\n# Delete tickets by ID\nplanfile ticket delete PLF-001 PLF-002\n\n# Delete tickets matching filters (with confirmation)\nplanfile ticket delete --status done --force\nplanfile ticket delete --sprint old-sprint --label archive\n\n# Preview deletions without executing\n\n### 6. Queue-Oriented Execution Metadata\n\n`planfile` tickets can also carry lightweight execution metadata for queue-like\nworkflows, which makes them a good control plane for tools like `koru`.\n\nCommon fields:\n\n- `executor.kind` — who should perform the task: `human | shell | mcp | api | llm`\n- `executor.mode` — `interactive` or `automatic`\n- `executor.handler` — script, tool, or adapter name\n- `execution.state` — `pending | ready | running | waiting_input | done | failed | skipped`\n- `inputs.*` — prompt, env keys, script path, API request, MCP tool, model hint\n- `outputs.*` — artifacts, notes, structured result payload\n\nExample:\n\n```yaml\ntickets:\n  PLF-001:\n    name: \"Bootstrap OpenRouter integration\"\n    status: open\n    priority: high\n    executor:\n      kind: shell\n      mode: automatic\n      handler: scripts/bootstrap.sh\n    execution:\n      queue: default\n      state: ready\n      max_attempts: 3\n    inputs:\n      env_keys:\n        - OPENROUTER_API_KEY\n      script: scripts/bootstrap.sh\n      api_endpoint: null\n      api_method: GET\n      api_headers: {}\n      api_body: null\n      api_timeout_seconds: 30\n    outputs:\n      artifacts:\n        - reports/bootstrap.json\n```\n\nFor API-executed tasks, tools such as `koru` can use `executor.kind: api`\nwith `inputs.api_endpoint`, `inputs.api_method`, `inputs.api_headers`,\n`inputs.api_body`, and `inputs.api_timeout_seconds`.\n\n`planfile ticket next` returns the highest-priority runnable open ticket whose\ndependencies in `blocked_by` are already `done` or `canceled`.\n\nExecution changes are also broadcast to WebSocket clients connected to `/ws`.\nThis lets tools such as `koru` or a small dashboard watch the queue without\npolling every endpoint.\n\nExample event:\n\n```json\n{\n  \"type\": \"ticket.execution.changed\",\n  \"action\": \"claim\",\n  \"ticket_id\": \"PLF-001\",\n  \"ticket\": {\n    \"id\": \"PLF-001\",\n    \"name\": \"Bootstrap OpenRouter integration\",\n    \"execution\": {\n      \"state\": \"ready\",\n      \"assigned_to\": \"koru-shell\"\n    }\n  }\n}\n```\nplanfile ticket delete --label old --dry-run\n\n# Bulk update tickets by filters\nplanfile ticket bulk-update --status-filter open --new-status in_progress\nplanfile ticket bulk-update --label todo --new-status done --force\n\n# Change priority for all open bugs\nplanfile ticket bulk-update --status-filter open --label bug --new-priority high\n\n# Add/remove labels in bulk\nplanfile ticket bulk-update --label old --add-label archived --remove-label old\n\n# Move tickets between sprints\nplanfile ticket bulk-update --sprint current --status-filter done --move-to-sprint completed\n\n# Combine multiple updates\nplanfile ticket bulk-update \\\n  --sprint sprint-1 \\\n  --status-filter open \\\n  --new-status in_progress \\\n  --new-priority high \\\n  --add-label urgent\n```\n\n**Auto-sync after changes:**\n```bash\n# Create ticket and sync immediately\nplanfile ticket create \"Fix login bug\" -p high --sync\n\n# Delete tickets and auto-sync\nplanfile ticket delete --status done --sync\n\n# Bulk update with sync\nplanfile ticket bulk-update --label bug --new-status done --sync\n\n# Preview sync (dry-run)\nplanfile ticket update PLF-001 --status done --sync --sync-dry-run\n```\n\n### 6. Sync with External Systems\n\nSynchronize tickets with TODO.md, GitHub, Jira, and GitLab:\n\n```bash\n# Sync with markdown files (TODO.md, CHANGELOG.md)\nplanfile sync markdown\n\n# Preview sync without making changes\nplanfile sync markdown --dry-run\n\n# Sync only to external system (export)\nplanfile sync markdown --direction to\n\n# Sync only from external system (import)\nplanfile sync markdown --direction from\n\n# Sync with GitHub Issues (requires github.planfile.yaml config)\nplanfile sync github\n\n# Sync with all configured integrations\nplanfile sync all\n\n# Example: Export all done tickets to CHANGELOG.md\nplanfile ticket bulk-update --status-filter done --add-label changelog\nplanfile sync markdown --direction to --dry-run\n\n# Watch .planfile/ directory and auto-sync on changes\nplanfile sync watch\n\n# Watch with custom polling interval (seconds)\nplanfile sync watch --interval 10\n\n# Watch specific integrations only\nplanfile sync watch --integration github --integration jira\n\n# One-time sync (no watch loop)\nplanfile sync watch --once\n\n# Watch with sync direction \"from\" (import from external systems)\nplanfile sync watch --direction from\n```\n\n**Sync Configuration:**\n\nCreate `github.planfile.yaml` for GitHub integration:\n```yaml\nintegrations:\n  github:\n    repo: \"owner/repo\"\n    token: \"${GITHUB_TOKEN}\"  # or auto-detected from `gh auth token`\n```\n\nMarkdown sync works out-of-the-box with `TODO.md` and `CHANGELOG.md` files.\n\nTo enable automatic checkbox syncing from `planfile.yaml` task statuses/results\nin tools that reuse planfile APIs (e.g. `llx plan run`), add:\n\n```yaml\nintegrations:\n  markdown:\n    sync_on_plan_run: true\n    todo_file: TODO.md\n```\n\n### 7. DSL (Domain Specific Language)\n\nPlanfile includes a natural language-like DSL for quick operations:\n\n```bash\n# CLI DSL - single command\nplanfile dsl \"list tickets sprint=current status=open\"\nplanfile dsl 'create ticket \"Fix login bug\" priority=high'\nplanfile dsl \"update ticket PLF-001 status=done\"\nplanfile dsl \"move ticket PLF-001 to sprint=2\"\nplanfile dsl \"done ticket PLF-001\"\nplanfile dsl \"validate\"\nplanfile dsl \"sync github\"\n\n# CLI DSL - interactive shell\nplanfile dsl\n# Then type commands like:\n# \u003e list tickets sprint=current\n# \u003e create ticket \"New task\" priority=high\n# \u003e exit\n\n# Format options\nplanfile dsl \"list tickets\" --format json\nplanfile dsl \"list tickets\" --format yaml\n```\n\n**Python API DSL:**\n\n```python\nfrom planfile import DSLExecutor\n\nexecutor = DSLExecutor(project_path=\".\")\nresult = executor.run(\"list tickets sprint=current\")\nprint(result.ok, result.data)\n\n# Parser only\nfrom planfile import DSLParser\nparser = DSLParser()\ncmd = parser.parse('create ticket \"Fix bug\" priority=high')\nprint(cmd.verb, cmd.target, cmd.params)\n```\n\n**REST API DSL:**\n\n```bash\n# Start server\nuvicorn planfile.api.server:app --reload\n\n# Execute DSL via HTTP\ncurl -X POST \"http://localhost:8000/dsl\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"command\": \"list tickets\", \"project_path\": \".\"}'\n\n# WebSocket DSL\nws://localhost:8000/ws?project_path=.\n```\n\n**MCP DSL Tool:**\n\n```bash\n# Start MCP server\npython -m planfile.mcp.server\n\n# MCP tool call (JSON-RPC)\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"planfile_dsl\",\n    \"arguments\": {\n      \"command\": \"list tickets sprint=current\",\n      \"project_path\": \".\"\n    }\n  }\n}\n```\n\n**Supported DSL Commands:**\n- `list tickets` — list with filters (sprint, status, priority, label)\n- `create ticket` — create with name, priority, sprint, labels\n- `show ticket` — show ticket by ID\n- `update ticket` — update status, priority, name, labels\n- `move ticket` — move to another sprint\n- `done ticket` — mark as done\n- `start ticket` — mark as in_progress\n- `block ticket` — mark as blocked\n- `delete ticket` — delete ticket\n- `list sprints` — list all sprints\n- `add sprint` — add new sprint\n- `validate` — validate tickets\n- `sync` — sync to integrations (github, jira, gitlab, all)\n- `query` — query tickets with where clause\n- `export` — export to formats (json, yaml, html)\n- `help` — show command reference\n\n**Aliases:** add/new → create, ls → list, get/show → show, set/edit/patch → update, mv → move, finish/complete → done, begin → start\n\n# Run CI loop with strategy\nmake ci-loop STRATEGY=strategy.yaml BACKENDS=github MAX_ITERATIONS=5\n\n# Run examples\nmake example-github\nmake example-jira\n\n# Full pipeline\nmake pipeline-docker\n```\n\n## 🔄 CI/CD Automation\n\nPlanfile provides complete automation for the bug-fix lifecycle:\n\n1. **Test Execution**: Run your test suite\n2. **Bug Detection**: Identify failing tests and code issues\n3. **AI Analysis**: Generate detailed bug reports using LLM\n4. **Ticket Creation**: Create tickets in your PM system\n5. **Auto-Fix**: Optionally fix bugs automatically with AI\n6. **Verification**: Re-run tests to verify fixes\n7. **Loop**: Repeat until all tests pass\n\n# Run with Docker Compose\ndocker-compose up -d\n\n# Run auto-loop in container\ndocker-compose exec sprintstrat-runner planfile auto loop \\\n  --strategy /app/strategy.yaml \\\n  --project /workspace \\\n  --backend github \\\n  --max-iterations 5\n```\n\n## 📚 Documentation\n\n- [Documentation Navigation](docs/NAVIGATION.md)\n- [CI/CD Integration Guide](docs/CI_CD_INTEGRATION.md)\n- [API Reference](docs/API.md)\n- [CLI Reference](docs/CLI.md)\n- [Examples](examples/)\n- [Architecture Overview](docs/summaries/)\n- [Migration Guide](docs/guides/MIGRATION_GUIDE.md)\n- [Performance Guide](docs/guides/PERFORMANCE.md)\n- [Examples Runner Guide](docs/guides/README_EXAMPLES.md)\n- [Standalone Usage Guide](docs/guides/README_STANDALONE.md)\n- [Changelog](CHANGELOG.md)\n\n### Strategy Schema (v2)\n\nThe `strategy.yaml` file supports:\n\n- **Sprints**: Time-boxed development periods with embedded tasks\n- **Goals**: Project objectives with success criteria\n- **Quality Gates**: Definition of done criteria\n- **Model Hints**: AI model suggestions for different phases\n\n### Example Strategy (v2)\n\n```yaml\nname: \"My Project Strategy\"\nproject_type: \"web\"\ndomain: \"fintech\"\ngoal:\n  title: \"Launch secure payment platform\"\n  description: \"Build and deploy a secure payment processing system\"\n  success_metrics:\n    - \"99.9% uptime\"\n    - \"\u003c100ms response time\"\n\nsprints:\n  - id: 1\n    name: \"Core Infrastructure\"\n    length_days: 14\n    objectives: [\"Set up project structure\", \"Implement authentication\"]\n    tasks:\n      - type: \"feature\"\n        title: \"Setup project structure\"\n        description: \"Create basic project layout and configuration\"\n        estimate: 2\n        priority: \"high\"\n        model_hints:\n          small: \"gpt-5.4-mini\"\n          large: \"gpt-4o\"\n\nquality_gates:\n  - name: \"Code Coverage\"\n    criteria: [\"coverage \u003e= 80%\"]\n    required: true\n```\n\n### Backend Configuration\n\nEach backend requires specific configuration:\n\n```yaml\n# GitHub backend\ngithub:\n  token: ${GITHUB_TOKEN}\n  repo: ${GITHUB_REPO}\n\n# Jira backend\njira:\n  url: ${JIRA_URL}\n  email: ${JIRA_EMAIL}\n  token: ${JIRA_TOKEN}\n  project: ${JIRA_PROJECT}\n```\n\n## 🤖 AI Integration\n\nPlanfile integrates with multiple LLM services:\n\n- **Multiple Providers**: OpenAI, Anthropic, LiteLLM, Local LLMs\n- **Smart Routing**: Automatic model selection via Proxym proxy\n- **Code Analysis**: LLX integration for advanced metrics\n- **Auto-Fix**: Automatic code generation for bug fixes\n- **Strategy Generation**: AI-powered strategy creation\n\n```bash\n# Enable AI features\nexport OPENAI_API_KEY=your_key\nexport ANTHROPIC_API_KEY=your_key\nexport PROXY_API_URL=http://localhost:9999\n\n# Run with auto-fix\nplanfile auto loop --strategy strategy.yaml --auto-fix\n\n# Generate strategy with AI\nplanfile strategy generate ./my-project --model gpt-4o\n```\n\n## 📚 Examples\n\nExplore the `examples/` directory for comprehensive use cases:\n\n# List all available examples\nplanfile examples list\n\n# Run a specific example\nplanfile examples run code2llm\n\n# Run all examples (with timeout protection)\nplanfile examples run --all\n```\n\n### Featured Examples\n\n- **[checkbox-tickets](examples/checkbox-tickets/)** - Native markdown checkbox support (`- [ ]` / `- [x]`)\n- **[code2llm](examples/code2llm/)** - Code analysis with LLM integration\n- **[bash-generation](examples/bash-generation/)** - Generate bash scripts from strategies\n- **[cli-commands](examples/cli-commands/)** - CLI usage patterns\n- **[advanced-usage](examples/advanced-usage/)** - CI/CD integration examples\n- **[interactive-tests](examples/interactive-tests/)** - Interactive mode demonstrations\n- **[ecosystem](examples/ecosystem/)** - MCP, LLX, and proxy routing integrations\n- **[cli](examples/cli/)** - DSL command-line interface examples\n- **[mcp](examples/mcp/)** - MCP DSL tool integration\n- **[python-api](examples/python-api/)** - Python API DSL usage\n- **[rest-api](examples/rest-api/)** - REST API and WebSocket DSL\n\n# examples/quick-start.yaml\nname: \"Quick Start Demo\"\nproject_type: \"web\"\ndomain: \"demo\"\ngoal: \"Demonstrate planfile capabilities\"\n\nsprints:\n  - id: 1\n    name: \"Setup\"\n    length_days: 7\n    tasks:\n      - type: \"feature\"\n        title: \"Initialize project\"\n        description: \"Create basic project structure\"\n        estimate: 1\n        priority: \"high\"\n```\n\nFor more examples, see the [examples directory](examples/).\n\n### Web Project Strategy\n\n```yaml\nname: \"E-commerce MVP\"\nproject_type: \"web\"\ndomain: \"ecommerce\"\ngoal: \"Launch minimum viable e-commerce platform\"\n\nsprints:\n  - id: 1\n    name: \"Foundation\"\n    length_days: 10\n    tasks:\n      - type: \"feature\"\n        title: \"Setup project structure\"\n        estimate: 1\n      - type: \"feature\"\n        title: \"Database schema\"\n        estimate: 3\n```\n\n### Mobile App Strategy\n\n```yaml\nname: \"Mobile App MVP\"\nproject_type: \"mobile\"\ndomain: \"healthcare\"\ngoal: \"Launch health tracking mobile app\"\n\nsprints:\n  - id: 1\n    name: \"Core Features\"\n    length_days: 14\n    tasks:\n      - type: \"feature\"\n        title: \"User authentication\"\n        estimate: 3\n      - type: \"feature\"\n        title: \"Health data tracking\"\n        estimate: 5\n```\n\n### Version Control\n\n- **GitHub**: Issues, Projects, Actions\n- **GitLab**: Issues, CI/CD, Merge Requests\n- **Bitbucket**: Issues, Pipelines\n\n### Project Management\n\n- **Jira**: Issues, Epics, Sprints\n- **Linear**: Issues, Projects, Teams\n- **ClickUp**: Tasks, Lists, Spaces\n- **Asana**: Tasks, Projects, Portfolios\n\n### CI/CD Platforms\n\n- **GitHub Actions**: Workflow automation\n- **GitLab CI**: Pipeline integration\n- **Jenkins**: Build automation\n- **Azure DevOps**: Release management\n\n# Clone repository\ngit clone https://github.com/semcod/planfile\ncd strategy\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run linting\nruff check src/ tests/\nruff format src/ tests/\n\n# Run complete test suite (REST, WebSockets, MCP, CLI, DSL)\npytest\n```\n\n### 🌐 API, WebSocket \u0026 MCP Architecture\n\nPlanfile is built with standard, production-ready interfaces for both humans and AI agents:\n\n1. **REST API**: A robust, fully typed **FastAPI** server exposing comprehensive endpoints for managing tickets, sprints, and system configurations.\n   * Start with: `uvicorn planfile.api.server:app --reload`\n   * API endpoints cover: ticket lifecycle (claim, start, complete, fail), event ingestion, and live configurations.\n\n2. **WebSockets (WS)**: High-performance bidirectional connection manager under `/ws`.\n   * Automatically broadcasts ticket execution changes (`ticket.execution.changed`) and ticket updates (`ticket.changed`) in real-time.\n   * Supports executing DSL commands dynamically in-session.\n\n3. **MCP Server**: Implements the official **Model Context Protocol (MCP)** (version `2024-11-05`) via standard JSON-RPC over `stdio`.\n   * Start with: `python -m planfile.mcp.server`\n   * Registers various tools like `planfile_dsl`, `planfile_list_tickets`, `planfile_yaml_get`, and `planfile_yaml_patch` to allow LLM agents to orchestrate files and tickets directly.\n\n4. **Testing Coverage**:\n   * All API, WebSocket lifecycle events, and state mutations are thoroughly tested.\n   * `tests/test_ticket_api_events.py` verifies FastAPI routes, WebSocket broadcasts, event histories, and queue dashboards.\n   * `tests/test_mcp_server.py` tests JSON-RPC Handlers, stdio lifecycle, and YAML-patch operations of the Model Context Protocol server.\n\n### Project Structure\n\n```\nplanfile/\n├── planfile/              # Main package\n│   ├── analysis/          # Code analysis components\n│   │   ├── external_tools.py    # External tool integrations\n│   │   ├── generator.py         # Strategy generation\n│   │   ├── file_analyzer.py     # File analysis\n│   │   ├── sprint_generator.py  # Sprint generation\n│   │   ├── parsers/             # YAML/JSON/Toon parsers\n│   │   └── generators/          # Metrics extractors\n│   ├── cli/               # CLI commands\n│   │   ├── cmd/           # Core commands (init, generate, apply, etc.)\n│   │   ├── auto_loop.py   # CI/CD automation\n│   │   └── extra_commands.py # Additional utilities\n│   ├── integrations/      # Backend integrations\n│   │   ├── github.py      # GitHub Issues\n│   │   ├── jira.py        # Jira\n│   │   ├── gitlab.py      # GitLab\n│   │   └── generic.py     # Generic HTTP API\n│   ├── llm/               # LLM integrations\n│   │   ├── adapters.py    # Multiple LLM adapters\n│   │   ├── client.py      # LLM client\n│   │   └── generator.py   # Strategy generation\n│   ├── loaders/           # Data loaders\n│   │   ├── yaml_loader.py # YAML loading/saving\n│   │   └── cli_loader.py  # JSON/Markdown export\n│   ├── models.py          # Core data models\n│   ├── models_v2.py       # Simplified models\n│   ├── runner.py          # Strategy execution\n│   ├── ci_runner.py       # CI/CD automation\n│   └── executor_standalone.py # Standalone executor\n├── examples/              # Usage examples\n│   ├── quick-start/       # Basic examples\n│   ├── ecosystem/         # Integration examples\n│   └── advanced-usage/    # Advanced features\n├── tests/                 # Test suite\n├── docs/                  # Documentation\n└── project/               # Project analysis output\n```\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## 📞 Support\n\n- 📖 [Documentation](docs/)\n- 🐛 [Issue Tracker](https://github.com/semcod/planfile/issues)\n- 💬 [Discussions](https://github.com/semcod/planfile/discussions)\n\n## 🏆 Acknowledgments\n\n- Built with [Typer](https://typer.tiangolo.com/) for CLI\n- Styled with [Rich](https://rich.readthedocs.io/) for terminal output\n- Validated with [Pydantic](https://pydantic-docs.helpmanual.io/) for data models\n\n---\n\n**Planfile** - Your strategic partner in SDLC automation. 🚀\n\n## License\n\nLicensed under Apache-2.0.\n## Status\n\n_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 13:42 UTC_\n\n| Metric | Value |\n|---|---|\n| HEAD | `f7a4f3c` |\n| Coverage | — |\n| Failing tests | — |\n| Commits in last cycle | 50 |\n\n\u003e Introduces a configuration management system across goal, examples, and docs; refactors and extends the code analysis engine and test suite to improve coverage. Includes documentation fixes (markdown output), a fix for code quality metrics, and cleanup removing large generated files.\n\n\u003c!-- taskill:status:end --\u003e\n\n\u003c!-- taskill:status:start --\u003e\n\n## Status\n\n_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 18:22 UTC_\n\n| Metric | Value |\n|---|---|\n| HEAD | `849565a` |\n| Coverage | — |\n| Failing tests | — |\n| Commits in last cycle | 9 |\n\n\u003e Implemented a comprehensive configuration management system and CLI interface for the planfile project, including new command groups for backlog, sync, ticket, and validate operations.\n\n\u003c!-- taskill:status:end --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fplanfile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemcod%2Fplanfile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fplanfile/lists"}