{"id":50472452,"url":"https://github.com/semcod/goal","last_synced_at":"2026-06-01T11:03:39.318Z","repository":{"id":335259974,"uuid":"1144950976","full_name":"semcod/goal","owner":"semcod","description":"pip install goal - Automated git push with smart commit messages, changelog updates, version tagging, and interactive workflow.","archived":false,"fork":false,"pushed_at":"2026-05-26T17:49:11.000Z","size":104138,"stargazers_count":3,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-26T18:25:58.697Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://wronai.github.io/goal/","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-01-29T08:35:39.000Z","updated_at":"2026-05-26T17:47:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/semcod/goal","commit_stats":null,"previous_names":["wronai/goal","semcod/goal"],"tags_count":212,"template":false,"template_full_name":null,"purl":"pkg:github/semcod/goal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fgoal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fgoal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fgoal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fgoal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semcod","download_url":"https://codeload.github.com/semcod/goal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fgoal/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:39.229Z","updated_at":"2026-06-01T11:03:39.309Z","avatar_url":"https://github.com/semcod.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n[claude-taking-longer-than-usual.webm](claude-taking-longer-than-usual.webm)\n\n# Goal\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-2.1.239-blue.svg\" alt=\"Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.8+-blue.svg\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/pypi-goal-orange.svg\" alt=\"PyPI\"\u003e\n  \u003ca href=\"https://github.com/wronai/goal/actions\"\u003e\u003cimg src=\"https://github.com/wronai/goal/workflows/CI/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/wronai/goal\"\u003e\u003cimg src=\"https://coveralls.io/repos/github/wronai/goal/badge.svg\" alt=\"Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/wronai/goal/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/wronai/goal?style=social\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/wronai/goal/network/members\"\u003e\u003cimg src=\"https://img.shields.io/github/forks/wronai/goal?style=social\" alt=\"Forks\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/wronai/goal/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/wronai/goal\" alt=\"Issues\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/wronai/goal/pulls\"\u003e\u003cimg src=\"https://img.shields.io/github/issues-pr/wronai/goal\" alt=\"Pull Requests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"Code Style\"\u003e\u003c/a\u003e\n  \u003ca href=\"http://mypy-lang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/type%20checking-mypy-blue.svg\" alt=\"Type Checking\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/wronai/goal\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey\" alt=\"Platform\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/wronai/goal\"\u003e\u003cimg src=\"https://img.shields.io/badge/dependencies-git%20%7C%20click-blue\" alt=\"Dependencies\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## AI Cost Tracking\n\n![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-2.1.239-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-$17.52-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-86.8h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fx--ai%2Fgrok--code--fast--1-lightgrey)\n\n- 🤖 **LLM usage:** $17.5199 (271 commits)\n- 👤 **Human dev:** ~$8675 (86.8h @ $100/h, 30min dedup)\n\nGenerated on 2026-05-26 using [openrouter/x-ai/grok-code-fast-1](https://openrouter.ai/x-ai/grok-code-fast-1)\n\n---\n\nGoal is your **release autopilot**: a CLI that runs tests, writes conventional commits, updates changelogs, bumps versions, and publishes packages for you—while keeping you in control with clear prompts or full automation.\n\n### Why you might need Goal\n- **Solo dev finishing a feature** → run one command, get a polished commit, synced versions, and a tagged release without memorizing git plumbing.\n- **Team ready for a patch fix** → ensure the changelog, VERSION file, and package registry stay in lockstep, even when multiple people touch the repo.\n- **CI/CD pipeline** → same command powers nightly builds, preview releases, or fully automated publishing.\n\n### What you get out of the box\n1. 🔍 **Context-aware diagnostics** – detects repo state, project types, missing remotes, config drift.\n2. 🧠 **Commit intelligence** – auto-scoped conventional messages that explain what changed, what was tested, and the scale of work.\n3. 🏷️ **Release hygiene** – synchronized VERSION files, changelog updates, git tags, and optional registry publish.\n4. ⚙️ **Multi-language support** – Python, Node.js, Rust, Go, Java, .NET, PHP, Ruby, and hybrid repos.\n5. 🤖 **Prompted or headless** – run interactively (`goal`) or fire-and-forget in CI with `goal --all`.\n\n### Three real-life flows\n```bash\n# 1. First-time setup in a folder without git\ngoal           # Goal offers to init git, add a remote, then re-run the workflow.\n\n# 2. Everyday feature release\ngoal push      # Runs tests, suggests a commit, bumps patch, updates changelog, pushes, tags.\n\n# 3. CI/CD or cron-driven release\ngoal --all --bump minor   # Non-interactive; perfect for nightly builds or release pipelines.\n```\n\n## 🆕 What's New in v2.2.1\n\n\u003e **Intelligent Package Manager Broker** — Automatic detection and selection of the fastest available package manager (uv, pdm, poetry, pip)\n\n### ✨ New Features\n\n**📦 PackageManagerBroker**\n- Automatic detection of available package managers (uv, pdm, poetry, pip)\n- Lockfile-aware installation (uv.lock → uv sync, poetry.lock → poetry install)\n- Priority-based selection (uv fastest, pip as fallback)\n- Auto-installation of uv when missing and pip is available\n- Smart dependency installation with timing and reporting\n\n```bash\n# Doctor shows available managers\ngoal doctor\n📦 Available package managers:\n   ✓ uv       ⚡ fast   \n     poetry   ⚡ fast   🔒\n     pip      🐢 slow\n\n# Force specific manager\ngoal doctor --manager uv\n```\n\n**⚡ Faster Python Installs**\n- uv integration: 5-30s installs vs 2-10min with pip\n- Automatic uv installation: `pip install uv` when uv missing\n- Lockfile-first strategy: sync from lock when available\n- Detailed timing reports: \"✅ uv (12.3s) | fallback: pip\"\n\n### 🔧 Architecture Improvements\n\n**Refactored Bootstrap System**\n- Split `project_bootstrap.py` (1265L) → `goal/bootstrap/` module\n- `goal/installers/` - new package manager abstraction layer\n- `goal/bootstrap/installer.py` - unified installation interface\n- Full backward compatibility maintained\n\n---\n\n## 🆕 What's New in v2.2.0\n\n\u003e **Wizard Setup, License Management \u0026 Multi-Author Support** — Complete project initialization, professional license handling, and team collaboration features\n\n### ✨ New Features\n\n**🧙‍♂️ Interactive Setup Wizard**\n- One-command project initialization with `goal wizard`\n- Guided git repository setup and remote configuration\n- Interactive user configuration (name, email, license)\n- Project configuration with versioning and commit strategies\n- Complete setup summary with next steps\n\n```bash\n# New project setup in one command\ngoal wizard\n```\n\n**📄 Professional License Management**\n- Create and update LICENSE files with 8 common license templates\n- Custom license template support for proprietary licenses\n- SPDX license ID validation with helpful error messages\n- License compatibility checking between different licenses\n- Automatic template variable substitution ({year}, {fullname})\n\n```bash\n# Create MIT license\ngoal license create MIT --fullname \"Your Name\"\n\n# Check license compatibility\ngoal license check MIT Apache-2.0\n```\n\n**👥 Multi-Author Project Support**\n- Team-based author management stored in project configuration\n- Import authors from git history automatically\n- Co-author support in commit messages with `--co-author` flag\n- Export team list to CONTRIBUTORS.md\n- Find authors by name, email, or alias\n\n```bash\n# Add team members\ngoal authors add \"Jane Doe\" jane@example.com --role \"Developer\"\n\n# Commit with co-authors\ngoal commit --co-author \"Jane Doe \u003cjane@example.com\u003e\"\n```\n\n### 🛠️ Enhanced Commands\n\nAll new commands integrate seamlessly with existing Goal workflows:\n\n```bash\n# Complete workflow with co-authors\ngoal push --co-author \"Jane Doe \u003cjane@example.com\u003e\"\n\n# Automated release with team attribution\ngoal --all --co-author \"Team \u003cteam@example.com\u003e\"\n```\n\n## 🆕 What's New in v2.1.99\n\n\u003e **Security Validation \u0026 Proactive .gitignore Management** — Automatic protection against large files, API tokens, and unwanted dot folders\n\n### ✨ New Security Features\n\n**🔒 File Size Validation**\n- Automatically blocks files larger than 10MB (configurable)\n- Prevents GitHub push failures due to file size limits\n- Clear error messages with file size information\n\n**🔑 API Token Detection**\n- Scans for exposed API tokens before commit\n- Supports GitHub, AWS, Slack, Stripe, GitLab patterns\n- Detects private keys and sensitive credentials\n- Blocks commit with location details\n\n**📁 Proactive .gitignore Management**\n- Automatically detects dot folders (.idea, .vscode, etc.)\n- Adds problematic folders to .gitignore before commit\n- Unstages files that should be ignored\n- Respects existing whitelist patterns (!.vscode)\n- Safe dot files are never ignored: `.gitignore`, `.github/`, `.editorconfig`, `.gitattributes`\n\n### 🛡️ Security Validation in Action\n\n```bash\n# Before commit, Goal automatically checks:\ngoal push\n\n# Also works with automation modes:\ngoal -a          # Full automation with validation\ngoal --all       # All stages with validation\ngoal --yes       # Auto-confirm with validation\n\n# Output examples:\n✅ Added 2 dot folder(s)/file(s) to .gitignore: .idea, .DS_Store\n  → Unstaged: .idea\n  → Unstaged: .DS_Store\n\n# Or blocks dangerous commits:\n❌ Validation Error: File secrets.db is 15.2MB, which exceeds the limit of 10MB\n❌ Validation Error: Potential GitHub Personal Access token detected in .env:5\n```\n\n### ⚙️ Configuration Options\n\n```yaml\n# goal.yaml\nadvanced:\n  file_validation:\n    max_file_size_mb: 10          # File size limit\n    block_large_files: true       # Block or just warn\n    detect_api_tokens: true       # Enable token detection\n    auto_manage_gitignore: true   # Auto-update .gitignore\n    auto_add_dot_folders: true    # Auto-add dot folders\n    known_dot_folders:           # Custom list of folders to ignore\n      - .idea\n      - .vscode\n      - .DS_Store\n      - .code2llm_cache\n      - .llm\n```\n\n### 🚀 Bypass Options\n\n```bash\n# Force commit (not recommended for security)\ngoal push --force\n\n# Dry run to check what would be blocked\ngoal push --dry-run\n```\n\n## 🆕 What's New in v2.1.65\n\n\u003e **TODO Management \u0026 Publishing Fixes** — Automatic issue tracking and reliable PyPI publishing\n\n### ✨ New Features\n\n**🎫 Automatic TODO Management**\n- `goal doctor --todo` adds detected issues to `TODO.md`\n- Unique ticket IDs prevent duplicates\n- Rich formatting with severity icons\n- Timestamped sections for tracking\n\n**🔧 Publishing Improvements**\n- Fixed \"cannot access local variable 'Path'\" error\n- Better handling of `~/.pypirc` authentication\n- Improved error messages and debugging\n- Support for both token and config-based auth\n\n**🛠️ Enhanced Diagnostics**\n- Better error detection in project configuration\n- More reliable build process\n- Improved artifact management\n\n### 📋 Example Usage\n\n```bash\n# Check version\ngoal -v\n\n# Diagnose and track issues\ngoal doctor --todo\ngoal doctor -t\n\n# Full workflow with TODO tracking\ngoal --all --todo\ngoal -a -t\n\n# Standard workflow\ngoal --all\n\n# Check project health\ngoal doctor\n```\n\n```\n\n## 📚 Previous Features (v2.1)\n\n\u003e **Smart Commit Intelligence** — commit bodies that answer *what changed, what was tested, and at what scale*\n\n❌ BEFORE: refactor(core): add testing, logging, validation\n✅ AFTER:  feat(goal): intelligent code analysis pipeline\n\nchanges:\n  - file: cli.py\n    area: cli\n    added: [ensure_git_repository, ensure_remote, _run_git_verbose]\n    modified: [push]\n  - file: test_clone_repo.py\n    area: test\n    new_tests: 3\n\ntesting:\n  new_tests: 3\n  scenarios:\n    - auto_mode_skips\n    - init_and_add_remote\n    - clone_option_with_valid_url\n\nstats:\n  lines: \"+210/-45 (net +165)\"\n  files: 2\n  complexity: \"Stable complexity\"\n```\n\n\u003e **Interactive Git Setup** — `goal` now guides you through repository configuration when no git repo is found\n\n```\n⚠  Not a git repository.\n\nWhat would you like to do?\n  [1] Initialize git here and connect to a remote  (keeps local files in 'myproject/')\n  [2] Clone a remote repository into this directory  (downloads remote files)\n  [3] Initialize a local-only git repository        (no remote)\n  [4] Exit\n```\n\n📖 [Full Documentation](docs/enhanced-summary.md) | 📂 [Examples](examples/enhanced-summary/)\n\n---\n\n## Features\n\n- 🚀 **Interactive workflow** - Confirms each stage (test, commit, push, publish) with Y/n prompts\n- 🧠 **Smart commit messages** - Generates conventional commits based on diff analysis\n- 🎯 **Enhanced Summary** - Business-value focused messages with capabilities, metrics, relations\n- 👤 **User configuration** - Auto-detects git user info and license preferences (stored in `~/.goal`)\n- 📄 **Smart metadata management** - Automatically updates author and license in project files\n- 📝 **README automation** - Updates license badges and author sections automatically\n- 🔍 **Version validation** - Checks registry versions and README badge consistency\n- 📦 **Multi-language support** - Python, Node.js, Rust, Go, Ruby, PHP, .NET, Java\n- 🏷️ **Version management** - Automatic version bumping and synchronization across project files\n- 📝 **Changelog updates** - Maintains CHANGELOG.md with version history\n- 🐳 **CI/CD ready** - `--yes` flag for automated workflows\n- 🧪 **Test integration** - Runs project-specific test commands before committing\n- 📦 **Publish support** - Publishes to package managers (PyPI, npm, crates.io, etc.)\n- 🔒 **Security validation** - Blocks large files, detects API tokens, manages .gitignore automatically\n\n## Installation\n\n```bash\npip install goal\n```\n\n## Quick Start\n\n### 1. Install Goal\n\n```bash\npip install goal\n```\n\n### 2. Run `goal` in any project directory\n\n```bash\ncd my-project/\ngoal\n```\n\nGoal detects your situation and guides you interactively:\n\n#### Scenario A: No git repository yet\n\n```\n⚠  Not a git repository.\n\nWhat would you like to do?\n  [1] Initialize git here and connect to a remote  (keeps local files in 'my-project/')\n  [2] Clone a remote repository into this directory  (downloads remote files)\n  [3] Initialize a local-only git repository        (no remote)\n  [4] Exit\nChoose [1]: 1\n\n  → git init\n✓ Initialized git repository.\n\nEnter repository URL:\n  SSH   example: git@github.com:user/repo.git\n  HTTP  example: https://github.com/user/repo.git\nURL: git@github.com:wronai/my-project.git\n\n  → git remote add origin git@github.com:wronai/my-project.git\n✓ Remote 'origin' → git@github.com:wronai/my-project.git\n\nFetching remote branches...\n  → git fetch origin\n  Remote is empty (no branches yet). Your local files will be the first push.\n\n✓ Ready. Run 'goal' again to commit and push.\n```\n\n#### Scenario B: Git repo exists, no remote configured\n\n```\n⚠  No git remote configured.\n\nWould you like to add a remote?\n  [1] Add remote origin (connect to GitHub/GitLab/etc.)\n  [2] Skip — commit locally without pushing\nChoose [1]: 1\n\n  → git remote add origin git@github.com:wronai/my-project.git\n  Verifying connection...\n  ✓ Remote is reachable.\n✓ Remote 'origin' → git@github.com:wronai/my-project.git\n```\n\n#### Scenario C: Everything configured — the normal workflow\n\n```\nDetected project types: python\nWill commit 5 files (+120/-15 lines, NET 105, 11% churn deletions)\nCommit message: feat(api): add user authentication endpoint\n\nRun tests? [Y/n]\nCommit changes? [Y/n]\nPush to remote? [Y/n]\nPublish version 1.2.3? [Y/n]\n```\n\nEvery git command is shown transparently (lines starting with `→`) so you always know what goal is doing.\n\n### 3. Automation modes\n\n```bash\n# Full automation — tests, commit, push, publish (skips if no repo/remote)\ngoal -a\n\n# Skip prompts but don't auto-publish\ngoal --yes\n\n# Preview what would happen\ngoal --dry-run\n```\n\n\u003e **Note:** `goal -a` in a directory without a git repository will **skip gracefully** instead of failing. This is safe for CI/CD pipelines.\n\n### Running from a local clone\n\nIf you're working with the goal source code:\n\n```bash\ngit clone https://github.com/wronai/goal.git\ncd goal\n\n# Use the local version without installing\npython3 -m goal\n\n# Or install in development mode\npip install -e .\n```\n\n## Documentation\n\n📚 **Complete Documentation**: [docs/README.md](docs/README.md)\n\n### Key Topics\n- [Installation Guide](docs/installation.md) - Detailed installation instructions\n- [Quick Start](docs/quickstart.md) - Get started in 5 minutes\n- [Configuration Guide](docs/configuration.md) - Complete goal.yaml reference\n- [Examples](docs/examples.md) - Real-world examples and use cases\n- [CI/CD Integration](docs/ci-cd.md) - Use Goal in pipelines\n- [Command Reference](docs/commands.md) - All commands and options\n\n## Usage Examples\n\n### Basic interactive workflow\n\n```bash\n# Run full interactive workflow with default patch bump\ngoal\n\n# Run with minor version bump\ngoal --bump minor\n\n# Run without prompts (for CI/CD)\ngoal --yes\n\n# Automate ALL stages without any prompts\ngoal --all\n```\n\n### Real-world examples\n\n#### 1. Python project with pytest\n\n```bash\n# Make changes to your Python code\ngit add .\n\n# Run the full workflow\ngoal\n\n# Output:\n# ✓ Detected project types: python\n# ✓ Running tests: pytest tests/ -v\n# ✓ Tests passed (23/23)\n# ✓ Generated commit: feat(api): add user authentication endpoint\n# ✓ Updated VERSION to 1.2.3\n# ✓ Updated CHANGELOG.md\n# ✓ Created tag v1.2.3\n# ✓ Pushed to origin\n# ? Publish to PyPI? [Y/n]: Y\n# ✓ Published version 1.2.3\n```\n\n#### 2. Node.js project with npm\n\n```bash\n# Quick patch release for bug fix\ngoal push --yes -m \"fix: resolve memory leak in parser\"\n\n# Output:\n# ✓ Detected project types: nodejs\n# ✓ Running tests: npm test\n# ✓ Tests passed\n# ✓ Committed: fix: resolve memory leak in parser\n# ✓ Updated package.json to 1.0.1\n# ✓ Updated CHANGELOG.md\n# ✓ Created tag v1.0.1\n# ✓ Pushed to origin\n```\n\n#### 3. Rust project with cargo\n\n```bash\n# Major release with breaking changes\ngoal push --bump major --yes\n\n# Output:\n# ✓ Detected project types: rust\n# ✓ Running tests: cargo test\n# ✓ All tests passed\n# ✓ Generated commit: feat!: change public API structure\n# ✓ Updated Cargo.toml to 2.0.0\n# ✓ Updated CHANGELOG.md\n# ✓ Created tag v2.0.0\n# ✓ Pushed to origin\n# ? Publish to crates.io? [Y/n]: Y\n# ✓ Published crate v2.0.0\n```\n\n#### 4. Publishing packages\n\n```bash\n# Publish only (after committing)\ngoal publish\n\n# Or include publishing in the full workflow\ngoal --all  # Will publish automatically\n```\n\n**Important**: Goal automatically filters artifacts to upload only the current version, avoiding \"File already exists\" errors on PyPI.\n\nIf you see a \"File already exists\" error:\n1. Clean and rebuild: `rm -rf dist build \u0026\u0026 python -m build`\n2. Or bump version again: `goal --bump patch`\n3. Check you're using the latest goal: `python3 -m goal` (in goal repo)\n\n#### 4. Multi-language project\n\n```bash\n# Project with both Python backend and Node.js frontend\ngoal info\n\n# Output:\n# === Project Information ===\n# Project types: python, nodejs\n# Current version: 1.5.0\n# \n# Version files:\n#   ✓ VERSION: 1.5.0\n#   ✓ package.json: 1.5.0\n#   ✓ pyproject.toml: 1.5.0\n\n# Run release - updates both package.json and pyproject.toml\ngoal push --yes\n```\n\n#### 5. Documentation updates\n\n```bash\n# Skip tests for docs-only changes\ngoal push --no-test -m \"docs: update API documentation\"\n\n# Or let goal detect it's docs only\ngit add README.md docs/\ngoal push --yes\n\n# Output:\n# ✓ Detected project types: python\n# ✓ Generated commit: docs: update API documentation\n# ✓ Updated VERSION to 1.5.1\n# ✓ Updated CHANGELOG.md\n# ✓ Created tag v1.5.1\n# ✓ Pushed to origin\n```\n\n#### 6. CI/CD automation\n\n```yaml\n# .github/workflows/release.yml\nname: Release\non:\n  push:\n    branches: [main]\njobs:\n  release:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-python@v4\n        with:\n          python-version: '3.11'\n      - name: Install Goal\n        run: pip install goal\n      - name: Configure PyPI token\n        run: echo \"__token__=${{ secrets.PYPI_TOKEN }}\" \u003e ~/.pypirc\n      - name: Release\n        run: goal --all --bump patch\n```\n\n#### 7. Dry run for preview\n\n```bash\n# Preview what will happen\ngoal push --dry-run --bump minor\n\n# Output:\n# === DRY RUN ===\n# Project types: python\n# Files to commit: 12 (+342/-15 lines)\n#   - src/auth.py (+120/-5)\n#   - tests/test_auth.py (+85/-0)\n#   - docs/api.md (+137/-10)\n# Commit message: feat(auth): add OAuth2 integration\n# Version: 1.5.0 -\u003e 1.6.0\n# Version sync: VERSION, pyproject.toml\n# Tag: v1.6.0\n```\n\n#### 8. Custom commit message\n\n```bash\n# Override auto-generated message\ngoal push -m \"feat: implement real-time notifications\"\n\n# Or use conventional commit format\ngoal push -m \"fix(auth): resolve JWT token expiration issue\"\n```\n\n#### 9. Split commits for large changes\n\n```bash\n# Split changes into logical commits\ngoal push --split --yes\n\n# Output:\n# ✓ Committed docs: update README and API docs\n# ✓ Committed feat: add user authentication system\n# ✓ Committed test: add comprehensive test coverage\n# ✓ Committed chore: update dependencies and CI config\n# ✓ Committed release: v2.0.0\n```\n\n#### 11. Security Validation Examples\n\n```bash\n# Goal automatically protects against security issues\ngoal push\n\n# Example 1: Large file detected\n# ❌ Validation Error: File database.dump is 15.2MB, which exceeds the limit of 10MB\n# For security reasons, the commit has been blocked.\n# To bypass this check, you can:\n# 1. Remove the sensitive/large file(s)\n# 2. Add the file(s) to .gitignore\n# 3. Use --force to bypass validation (not recommended)\n\n# Example 2: API token detected\n# ❌ Validation Error: Potential GitHub Personal Access token detected in .env:5\n# For security reasons, the commit has been blocked.\n\n# Example 3: Dot folder auto-management\n# ✅ Added 3 dot folder(s)/file(s) to .gitignore: .idea, .vscode, .DS_Store\n#   → Unstaged: .idea\n#   → Unstaged: .vscode\n#   → Unstaged: .DS_Store\n```\n\n#### 12. Skip specific steps\n\n```bash\n# Skip version bump for hotfix\ngoal push --yes --no-version-sync -m \"hotfix: critical security patch\"\n\n# Skip changelog for minor tweak\ngoal push --yes --no-changelog -m \"style: fix linting issues\"\n\n# Skip tag creation for experimental feature\ngoal push --yes --no-tag -m \"feat: experimental AI integration\"\n```\n\n### Using the push command directly\n\n```bash\n# Interactive push with prompts\ngoal push\n\n# Automatic push without prompts\ngoal push --yes\n\n# Dry run to see what would happen\ngoal push --dry-run\n\n# Custom commit message\ngoal push -m \"feat: add new authentication system\"\n\n# Skip specific steps\ngoal push --no-tag --no-changelog\n\n# With version bump\ngoal push --bump minor\n\n# Markdown output for CI/CD logs\ngoal push --markdown\n```\n\n### Version management\n\n```bash\n# Check current version\ngoal version\n\n# Bump specific version type\ngoal version --bump minor\ngoal version --bump major\n\n# Check repository status\ngoal status\n```\n\n## Supported Project Types\n\nGoal automatically detects your project type and uses appropriate commands:\n\n| Language | Test Command | Publish Command | Version Files |\n|----------|--------------|-----------------|---------------|\n| **Python** | `pytest` | `python -m build \u0026\u0026 twine upload dist/*` | pyproject.toml, setup.py |\n| **Node.js** | `npm test` | `npm publish` | package.json |\n| **Rust** | `cargo test` | `cargo publish` | Cargo.toml |\n| **Go** | `go test ./...` | `git push origin --tags` | go.mod (uses git tags) |\n| **Ruby** | `bundle exec rspec` | `gem build *.gemspec \u0026\u0026 gem push *.gem` | *.gemspec |\n| **PHP** | `composer test` | `composer publish` | composer.json |\n| **.NET** | `dotnet test` | `dotnet pack \u0026\u0026 dotnet nuget push *.nupkg` | *.csproj |\n| **Java** | `mvn test` | `mvn deploy` | pom.xml, build.gradle |\n\n## Markdown Output\n\nGoal outputs structured markdown by default (perfect for LLM consumption and CI/CD logs). Use `--ascii` to get the legacy console output.\n\n```bash\n# Default: markdown output\ngoal push\ngoal status\n\n# Force legacy output\ngoal push --ascii\ngoal status --ascii\n\n# Use with automation\ngoal --all \u003e release.log\n```\n\nThe markdown output includes:\n- Front matter with metadata (command, version, file count)\n- Structured sections for overview, files, and test results\n- Code blocks for command outputs\n- Summary with actions taken and next steps\n\nExample output:\n```markdown\n---\ncommand: goal push\nproject_types: [\"python\"]\nversion_bump: \"1.0.1 -\u003e 1.0.2\"\nfile_count: 7\n---\n\n# Goal Push Result\n\n## Overview\n**Project Type:** python\n**Files Changed:** 7 (+1140/-99 lines)\n**Version:** 1.0.1 → 1.0.2\n...\n```\n\nSee [docs/markdown-output.md](docs/markdown-output.md) for detailed examples.\n\n## Command Reference\n\n### `goal` or `goal push`\n\nMain command for the complete workflow.\n\n**Options:**\n- `-v, --version`: Show version and exit\n- `--bump, -b`: Version bump type [patch|minor|major] (default: patch)\n- `--yes, -y`: Skip all prompts (run automatically)\n- `--all, -a`: Automate all stages including tests, commit, push, and publish\n- `--todo/--no-todo, -t`: Add unfixed issues to TODO.md during doctor phase (default: no)\n- `--markdown/--ascii`: Output format (default: markdown)\n- `--split`: Create separate commits per change type (docs/code/ci/examples)\n- `--ticket`: Ticket prefix to include in commit titles (overrides TICKERT)\n- `--no-tag`: Skip creating git tag\n- `--no-changelog`: Skip updating changelog\n- `--no-version-sync`: Skip syncing version to project files\n- `--message, -m`: Custom commit message\n- `--dry-run`: Show what would be done without doing it\n\n### `goal doctor`\n\nDiagnose and auto-fix common project configuration issues.\n\n**Options:**\n- `--fix/--no-fix`: Auto-fix issues (default: yes)\n- `--path, -p`: Root directory to scan (default: .)\n- `--todo/--no-todo, -t`: Add unfixed issues to TODO.md (default: no)\n\n**Examples:**\n```bash\ngoal doctor              # Diagnose and auto-fix\ngoal doctor --no-fix     # Diagnose only\ngoal doctor --todo       # Add issues to TODO.md\ngoal doctor -t           # Add issues to TODO.md (short form)\n```\n\n## Split commits (per type)\n\nWhen `--split` is enabled, Goal will create multiple commits:\n\n- **code**: changes in `goal/`, `src/`, `lib/`, `*.py`\n- **docs**: `docs/*`, `README.md`, `*.md`\n- **ci**: `.github/*`, `.gitlab/*`, `*.yml`/`*.yaml`\n- **examples**: `examples/*`\n- **other**: everything else\n\nThen it will create a final **release metadata** commit with version bump + changelog (unless disabled).\n\n## Ticket prefixing (TICKET)\n\nCreate a `TICKET` file in repository root:\n\n```ini\nprefix=ABC-123\nformat=[{ticket}] {title}\n```\n\nYou can override it per run:\n\n```bash\ngoal push --ticket ABC-123\ngoal push --split --ticket ABC-123\ngoal commit --ticket ABC-123\n```\n\n### `goal init`\n\nInitialize goal in current repository.\n\nCreates:\n- `VERSION` file with initial version 1.0.0\n- `CHANGELOG.md` with standard template\n\n### `goal status`\n\nShow current git status and version info.\n\nDisplays:\n- Current version\n- Current branch\n- Staged files\n- Unstaged/untracked files\n\n### `goal version`\n\nShow or bump version.\n\n**Options:**\n- `--type, -t`: Version bump type [patch|minor|major] (default: patch)\n\n### `goal wizard`\n\nInteractive guided setup for new projects.\n\nWalks you through:\n- Git repository initialization and remote configuration\n- User configuration (name, email, license)\n- Project configuration (name, description, versioning strategy)\n- Complete setup summary with next steps\n\n**Options:**\n- `--reset`: Reset and reconfigure everything\n- `--skip-git`: Skip git repository setup\n- `--skip-user`: Skip user configuration\n- `--skip-project`: Skip project configuration\n\n### `goal license`\n\nManage project licenses.\n\n**Subcommands:**\n- `create \u003clicense_id\u003e`: Create LICENSE file\n- `update`: Update existing LICENSE file\n- `validate`: Validate LICENSE file\n- `info \u003clicense_id\u003e`: Show license information\n- `check \u003clicense1\u003e \u003clicense2\u003e`: Check compatibility\n- `list`: List available templates\n- `template \u003clicense_id\u003e`: Add/show custom templates\n\n**Examples:**\n```bash\ngoal license create MIT --fullname \"Your Name\"\ngoal license check MIT Apache-2.0\ngoal license list\n```\n\n### `goal authors`\n\nManage project authors and team members.\n\n**Subcommands:**\n- `list`: List all project authors\n- `add \u003cname\u003e \u003cemail\u003e`: Add an author\n- `remove \u003cemail\u003e`: Remove an author\n- `update \u003cemail\u003e`: Update author info\n- `import`: Import from git history\n- `export`: Export to CONTRIBUTORS.md\n- `find \u003cidentifier\u003e`: Find author by name/email/alias\n- `current`: Show current user info\n\n**Examples:**\n```bash\ngoal authors add \"Jane Doe\" jane@example.com --role \"Developer\"\ngoal authors list\ngoal authors import\n```\n\n### Co-author Support\n\nAdd co-authors to commits:\n\n```bash\ngoal commit --co-author \"Jane Doe \u003cjane@example.com\u003e\"\ngoal commit --co-author \"Jane \u003cjane@example.com\u003e\" --co-author \"Bob \u003cbob@example.com\u003e\"\n```\n\n## Examples by Use Case\n\n### New Project Setup\n```bash\n# Interactive guided setup\ngoal wizard\n```\n📖 [Full Wizard Example](examples/wizard-setup/)\n\n### License\n\nLicensed under Apache-2.0.\n\n\nLicensed under Apache-2.0.\n\n\nLicensed under Apache-2.0.\n\n\nLicensed under Apache-2.0.\n\n\n# Check license compatibility\ngoal license check MIT Apache-2.0\n```\n📖 [License Management Examples](examples/license-management/)\n\n### Team Collaboration\n```bash\n# Add team members\ngoal authors add \"Jane Doe\" jane@example.com --role \"Developer\"\n\n# Commit with co-authors\ngoal commit --co-author \"Jane Doe \u003cjane@example.com\u003e\"\n```\n📖 [Multi-Author Project Examples](examples/multi-author/)\n\n### Development Workflow\n\n```bash\n# Make your changes...\ngit add some/files\n\n# Run goal with interactive prompts\ngoal\n\n# Prompts will appear:\n# Run tests? [Y/n] - Runs pytest for Python projects\n# Commit changes? [Y/n] - Creates smart commit message\n# Push to remote? [Y/n] - Pushes to origin with tags\n# Publish version 1.2.3? [Y/n] - Publishes to PyPI/npm/etc\n```\n\n### Full Automation\n\n```bash\n# Automate everything - tests, commit, push, publish\ngoal --all\n\n# Short form\ngoal -a\n\n# With specific version bump\ngoal --all --bump minor\n```\n\n### CI/CD Pipeline\n\n```yaml\n# GitHub Actions example\n- name: Deploy with Goal\n  run: |\n    goal push --yes --bump minor\n    \n# Or with --all flag\n- name: Full release\n  run: |\n    goal --all --bump patch\n```\n\n### Skip Testing in Quick Fixes\n\n```bash\n# Skip tests for documentation changes\ngoal push --yes -m \"docs: update README\"\n```\n\n### Pre-release Workflow\n\n```bash\n# Check what will be done\ngoal push --dry-run --bump minor\n\n# Run with specific version bump\ngoal push --bump minor\n\n# Or skip publishing for internal releases\ngoal push --yes --no-tag\n```\n\n### Working with Multiple Projects\n\n```bash\n# Monorepo with frontend and backend\n# Structure:\n# /backend (Python)\n# /frontend (Node.js)\n# /docs\n\n# From root directory\ngoal info\n\n# Output:\n# Project types: python, nodejs\n# Version files:\n#   ✓ VERSION: 2.1.0\n#   ✓ backend/pyproject.toml: 2.1.0\n#   ✓ frontend/package.json: 2.1.0\n\n# Release updates all projects\ngoal push --yes\n```\n\n### Hotfix Workflow\n\n```bash\n# Critical fix - skip tests and version bump\ngoal push --yes --no-test --no-version-sync -m \"hotfix: security patch\"\n\n# Then create proper release\ngoal push --bump patch -m \"release: v1.2.1 with security fix\"\n```\n\n### Feature Branch Workflow\n\n```bash\n# On feature branch\ngoal push --yes --no-tag --no-publish\n\n# After merge to main\ngoal push --bump minor --yes\n```\n\n### Release Candidate\n\n```bash\n# Create RC version\ngoal push --bump patch -m \"release: v2.0.0-rc1\"\n\n# After testing, promote to stable\ngoal push --bump patch -m \"release: v2.0.0 stable\"\n```\n\n## Configuration\n\nGoal uses `goal.yaml` for configuration. Run `goal init` to create it automatically with detected settings.\n\n### goal.yaml Structure\n\n```yaml\n# goal.yaml - Goal configuration file\nversion: \"1.0\"\n\nproject:\n  name: \"my-project\"           # Auto-detected from pyproject.toml/package.json\n  type: [\"python\"]             # Auto-detected project types\n  description: \"My project\"    # Auto-detected description\n\nversioning:\n  strategy: \"semver\"           # semver, calver, or date\n  files:                       # Files to sync version to\n    - \"VERSION\"\n    - \"pyproject.toml:version\"\n    - \"package.json:version\"\n  bump_rules:                  # Auto-bump thresholds\n    patch: 10                  # Files changed\n    minor: 50                  # Lines added\n    major: 200                 # Large changes\n\ngit:\n  commit:\n    strategy: \"conventional\"   # conventional, semantic, custom\n    scope: \"my-project\"        # Default scope for commits\n    templates:                 # Custom commit templates\n      feat: \"feat({scope}): {description}\"\n      fix: \"fix({scope}): {description}\"\n      docs: \"docs({scope}): {description}\"\n    classify_by:               # Classification methods\n      - \"file_extensions\"\n      - \"directory_paths\"\n      - \"line_stats\"\n      - \"keywords_diff\"\n  changelog:\n    enabled: true\n    template: \"keep-a-changelog\"\n    output: \"CHANGELOG.md\"\n    sections: [\"Added\", \"Changed\", \"Fixed\", \"Deprecated\"]\n  tag:\n    enabled: true\n    prefix: \"v\"\n    format: \"{prefix}{version}\"\n\nstrategies:\n  python:\n    test: \"pytest tests/ -v\"\n    build: \"python -m build\"\n    publish: \"twine upload dist/*\"\n  nodejs:\n    test: \"npm test\"\n    build: \"npm run build\"\n    publish: \"npm publish\"\n\nregistries:\n  pypi:\n    url: \"https://pypi.org/simple/\"\n    token_env: \"PYPI_TOKEN\"\n  npm:\n    url: \"https://registry.npmjs.org/\"\n    token_env: \"NPM_TOKEN\"\n\nhooks:\n  pre_commit: \"\"               # Command to run before commit\n  post_commit: \"\"              # Command to run after commit\n  pre_push: \"\"                 # Command to run before push\n  post_push: \"\"                # Command to run after push\n\nadvanced:\n  auto_update_config: true     # Auto-update config on detection changes\n  performance:\n    max_files: 50              # Split commits if \u003e N files\n    timeout_test: 300          # Test timeout in seconds\n  file_validation:\n    max_file_size_mb: 10       # File size limit (default: 10MB)\n    block_large_files: true    # Block large files or just warn\n    detect_api_tokens: true    # Scan for API tokens\n    auto_manage_gitignore: true  # Auto-update .gitignore\n    auto_add_dot_folders: true   # Auto-add dot folders to .gitignore\n    known_dot_folders:         # Custom dot folders to ignore\n      - .idea\n      - .vscode\n      - .DS_Store\n      - .pytest_cache\n      - .code2llm_cache\n      - .llm\n    token_patterns: []         # Custom regex patterns for token detection\n```\n\n### Config Commands\n\n```bash\n# Show full configuration\ngoal config show\n\n# Show specific key (dot notation)\ngoal config show -k git.commit.strategy\n\n# Get a value\ngoal config get project.name\n\n# Set a value\ngoal config set git.commit.scope \"my-app\"\n\n# Validate configuration\ngoal config validate\n\n# Update config based on project detection\ngoal config update\n```\n\n### Custom Config File\n\n```bash\n# Use a custom config file\ngoal --config custom-goal.yaml push\n\n# Or in CI/CD\ngoal -c .goal/ci.yaml --all\n```\n\n### Conventions (without goal.yaml)\n\nGoal also works without configuration based on conventions:\n\n1. **Version detection**: Looks for `VERSION` file first, then project-specific files\n2. **Project detection**: Automatically detects project type from files\n3. **Commit messages**: Uses conventional commit format based on diff analysis\n4. **Changelog**: Updates CHANGELOG.md in Keep a Changelog format\n\n## Integration Examples\n\n### Makefile\n\n```makefile\n.PHONY: release patch minor major\n\n# Interactive release\nrelease:\n\tgoal\n\n# Automatic patch release\npatch:\n\tgoal push --yes\n\n# Full automation release\nall:\n\tgoal --all\n\n# Automatic minor release\nminor:\n\tgoal push --yes --bump minor\n\n# Automatic major release\nmajor:\n\tgoal push --yes --bump major\n\n# Dry run\ndry-run:\n\tgoal push --dry-run\n\n# Release with custom message\nrelease-message:\n\tgoal push --yes -m \"$(MSG)\"\n\n# Release from specific branch\nrelease-branch:\n\tgit checkout main\n\tgit pull\n\tgoal --all --bump $(BUMP)\n```\n\n### package.json scripts\n\n```json\n{\n  \"scripts\": {\n    \"release\": \"goal\",\n    \"release:patch\": \"goal push --yes\",\n    \"release:all\": \"goal --all\",\n    \"release:minor\": \"goal push --yes --bump minor\",\n    \"release:major\": \"goal push --yes --bump major\",\n    \"release:dry\": \"goal push --dry-run\",\n    \"release:docs\": \"goal push --yes -m 'docs: update documentation'\"\n  }\n}\n```\n\n### pre-commit hook\n\n```bash\n#!/bin/sh\n# .git/hooks/pre-commit\necho \"Running goal pre-commit check...\"\ngoal push --dry-run\nif [ $? -eq 0 ]; then\n    echo \"✅ Ready to commit!\"\nelse\n    echo \"❌ Issues found. Fix them before committing.\"\n    exit 1\nfi\n```\n\n### Docker integration\n\n```dockerfile\n# Dockerfile\nFROM python:3.11-slim\n\nWORKDIR /app\n\n# Install dependencies\nCOPY requirements.txt .\nRUN pip install -r requirements.txt\n\n# Install goal\nRUN pip install goal\n\n# Copy source code\nCOPY . .\n\n# Run tests and release\nCMD [\"sh\", \"-c\", \"goal --all\"]\n```\n\n## Smart Commit Messages\n\nGoal analyzes your changes to generate appropriate commit messages:\n\n- **feat**: New features, additions\n- **fix**: Bug fixes, patches\n- **docs**: Documentation changes\n- **style**: Formatting, linting\n- **refactor**: Code restructuring\n- **perf**: Performance improvements\n- **test**: Test additions/changes\n- **build**: Build system, CI/CD\n- **chore**: Dependencies, maintenance\n\nExamples:\n- `feat: add user authentication`\n- `fix: resolve memory leak in parser`\n- `docs: update API documentation`\n- `test: add coverage for payment module`\n\n## Troubleshooting\n\n### Security Validation Blocks Commit\n\nGoal automatically protects against security issues:\n\n```bash\n# Large file detected\n❌ Validation Error: File database.dump is 15.2MB, which exceeds the limit of 10MB\n\n# API token detected  \n❌ Validation Error: Potential GitHub Personal Access token detected in .env:5\n\n# Solutions:\n1. Remove the sensitive/large file\n2. Add the file to .gitignore\n3. Use --force to bypass (not recommended)\n```\n\n### Configure Security Validation\n\n```yaml\n# goal.yaml\nadvanced:\n  file_validation:\n    max_file_size_mb: 10        # Adjust limit\n    block_large_files: false    # Only warn instead of block\n    detect_api_tokens: true     # Enable/disable token detection\n    auto_manage_gitignore: false # Disable auto .gitignore updates\n```\n\n### Tests fail but I want to continue\n\nThe interactive workflow will ask if you want to continue when tests fail:\n\n```\nTests failed. Continue anyway? [y/N]\n```\n\n### Custom test/publish commands\n\nIf Goal doesn't detect your test command correctly, you can run them manually before using `goal push --yes`.\n\n### TODO Management\n\nGoal can automatically add detected issues to `TODO.md` without duplicates:\n\n```bash\n# Diagnose and add unfixed issues to TODO.md\ngoal doctor --todo\ngoal doctor -t\n\n# Diagnose without auto-fix but add to TODO.md\ngoal doctor --todo --no-fix\ngoal doctor -t --no-fix\n\n# Full workflow with TODO tracking\ngoal --all --todo\ngoal -a -t\n```\n\n**Features:**\n- 🎫 **Unique ticket IDs** - Format `[CODE-identifier]` for each issue\n- 🚫 **No duplicates** - Checks existing tickets before adding\n- 🎨 **Rich formatting** - Icons, severity levels, file references\n- 📅 **Timestamped sections** - Groups issues by detection date\n\n**Example TODO.md entry:**\n```markdown\n## Issues Found - 2026-02-24\n\n- [PY002-missingbuildsysteminpyprojecttoml] 🔴 **Missing [build-system] in pyproject.toml** (`pyproject.toml`)\n  - pyproject.toml has no [build-system] section.\n  - pip and build tools need this to know how to build your package.\n  - Adding a default setuptools build-system.\n```\n\n### Publishing fails\n\nEnsure you're authenticated with the appropriate package manager:\n\n**PyPI Authentication Options:**\n- **Recommended**: Configure `~/.pypirc` file (development)\n- **CI/CD**: Set `PYPI_TOKEN` environment variable\n- **Interactive**: Run `twine configure`\n\n**~/.pypirc setup (recommended for development):**\n```ini\n[pypi]\n  username = __token__\n  password = pypi-AgEIcHlwaS5vcmcC...\n```\n\n**Environment variable setup (for CI/CD):**\n```bash\nexport PYPI_TOKEN=your_token_here\n```\n\n**Other package managers:**\n- npm: `npm login`\n- crates.io: `cargo login`\n\n### Common Issues\n\n#### Goal doesn't detect my project type\n```bash\n# Check what's detected\ngoal info\n\n# Manually specify in goal.yaml\nproject:\n  type: [\"python\", \"nodejs\"]\n```\n\n#### Version sync not working\n```bash\n# Check version files\ngoal info\n\n# Manually configure in goal.yaml\nversioning:\n  files:\n    - \"VERSION\"\n    - \"my-app/__init__.py:__version__\"\n```\n\n#### Tests timing out\n```yaml\n# In goal.yaml\nadvanced:\n  performance:\n    timeout_test: 600  # 10 minutes\n```\n\n#### Commit message not accurate\n```bash\n# Use custom message\ngoal push -m \"your custom message\"\n\n# Or configure templates in goal.yaml\ngit:\n  commit:\n    templates:\n      feat: \"feat({scope}): {description}\"\n```\n\n## User Configuration\n\nGoal automatically manages your project metadata using your git configuration and license preferences.\n\n### First-time Setup\n\nOn first run, Goal will:\n1. **Auto-detect** your git `user.name` and `user.email`\n2. **Ask for license preference** (8 popular open source licenses)\n3. **Save to** `~/.goal` for future use\n\n```bash\n$ goal\n\n======================================================================\n  🎯 Goal - First Time Setup\n======================================================================\n\n✓ Detected git user.name: Tom Sapletta\n✓ Detected git user.email: info@softreck.com\n\n======================================================================\n  📄 License Selection\n======================================================================\n\n  1. Apache License 2.0\n  2. MIT License\n  3. GNU General Public License v3.0\n  4. BSD 3-Clause License\n  5. GNU General Public License v2.0\n  6. GNU Lesser General Public License v3.0\n  7. GNU Affero General Public License v3.0\n  8. Mozilla Public License 2.0\n\nEnter your choice [1]: 1\n\n✓ Configuration saved to ~/.goal\n```\n\n### What Gets Updated Automatically\n\nEvery time you run `goal`, it updates:\n\n**Project Files:**\n- `pyproject.toml` - authors, license, classifier\n- `package.json` - author, license, contributors\n- `Cargo.toml` - authors, license\n- `VERSION` - version number\n- `__init__.py` - `__version__` variable (in all packages)\n\n**README.md:**\n- License badges (Apache-2.0, MIT, GPL, etc.)\n- `## License\n\nLicensed under Apache-2.0.\n\n\nLicensed under Apache-2.0.\n\n\nLicensed under Apache-2.0.\n\n\nLicensed under Apache-2.0.\n\n\n### Smart Author Management\n\nGoal **adds** authors instead of replacing them:\n\n```python\n# Before (existing author)\nauthors = [{name = \"Original Author\", email = \"original@example.com\"}]\n\n# After (Goal adds you)\nauthors = [\n    {name = \"Original Author\", email = \"original@example.com\"},\n    {name = \"Tom Sapletta\", email = \"info@softreck.com\"},\n]\n```\n\n### Managing Your Configuration\n\n```bash\n# View current configuration\ngoal config\n\n# Reset and reconfigure\ngoal config --reset\n\n# Configuration file location\n~/.goal\n```\n\n### Example Output\n\n```bash\n$ goal config\n\n======================================================================\n  📋 Goal User Configuration\n======================================================================\n\nConfig file: /home/tom/.goal\n\nCurrent settings:\n  Author name:  Tom Sapletta\n  Author email: info@softreck.com\n  License:      Apache License 2.0 (Apache-2.0)\n\n💡 Tip: Run 'goal config --reset' to reconfigure\n```\n\n## Tips \u0026 Tricks\n\n### 1. Use with aliases\n```bash\n# Add to ~/.bashrc or ~/.zshrc\nalias g='goal'\nalias gp='goal push --yes'\nalias ga='goal --all'\nalias gd='goal push --dry-run'\n```\n\n### 2. Team workflow\n```bash\n# For team development, use ticket prefixes\necho \"prefix=PROJ-123\" \u003e TICKET\ngoal push --split  # Creates commits like \"PROJ-123: feat: add feature\"\n```\n\n### 3. Release checklist\n```bash\n# Before release\ngoal status      # Check status\ngoal push --dry-run  # Preview changes\n\n# Release\ngoal --all       # Full automation\n```\n\n### 4. Working with feature flags\n```bash\n# Commit feature flag changes\ngoal push -m \"feat: enable beta feature flag\"\n\n# Later, remove the flag\ngoal push -m \"feat: launch feature to all users\"\n```\n\n### 5. Automated releases on schedule\n```yaml\n# .github/workflows/scheduled-release.yml\nname: Scheduled Release\non:\n  schedule:\n    - cron: '0 9 * * 1'  # Every Monday at 9 AM\njobs:\n  release:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - name: Install Goal\n        run: pip install goal\n      - name: Weekly Release\n        run: goal --all --bump patch\n```\n\n## License\n\nLicensed under Apache-2.0.\n## Author\n\nTom Sapletta\n## Status\n\n_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 13:38 UTC_\n\n| Metric | Value |\n|---|---|\n| HEAD | `7edd05b` |\n| Coverage | — |\n| Failing tests | — |\n| Commits in last cycle | 50 |\n\n\u003e Introduces a configuration management system, improves the code analysis engine and commit message generation, expands CLI functionality and markdown output support, and applies bulk TODO fixes and documentation updates.\n\n\u003c!-- taskill:status:end --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fgoal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemcod%2Fgoal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fgoal/lists"}