https://github.com/semcod/goal

pip install goal - Automated git push with smart commit messages, changelog updates, version tagging, and interactive workflow.
https://github.com/semcod/goal

Last synced: 8 days ago
JSON representation

pip install goal - Automated git push with smart commit messages, changelog updates, version tagging, and interactive workflow.

• Host: GitHub
• URL: https://github.com/semcod/goal
• Owner: semcod
• License: apache-2.0
• Created: 2026-01-29T08:35:39.000Z (4 months ago)
• Default Branch: main
• Last Pushed: 2026-05-26T17:49:11.000Z (13 days ago)
• Last Synced: 2026-05-26T18:25:58.697Z (13 days ago)
• Language: Python
• Homepage: https://wronai.github.io/goal/
• Size: 99.3 MB
• Stars: 3
• Watchers: 1
• Forks: 2
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

          

[claude-taking-longer-than-usual.webm](claude-taking-longer-than-usual.webm)

# Goal



  

  

  

  

  

  

  

  

  

  

  

  

  

  



## AI Cost Tracking

![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)

![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)

- 🤖 **LLM usage:** $17.5199 (271 commits)

- 👤 **Human dev:** ~$8675 (86.8h @ $100/h, 30min dedup)

Generated on 2026-05-26 using [openrouter/x-ai/grok-code-fast-1](https://openrouter.ai/x-ai/grok-code-fast-1)

---

Goal 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.

### Why you might need Goal

- **Solo dev finishing a feature** → run one command, get a polished commit, synced versions, and a tagged release without memorizing git plumbing.

- **Team ready for a patch fix** → ensure the changelog, VERSION file, and package registry stay in lockstep, even when multiple people touch the repo.

- **CI/CD pipeline** → same command powers nightly builds, preview releases, or fully automated publishing.

### What you get out of the box

1. 🔍 **Context-aware diagnostics** – detects repo state, project types, missing remotes, config drift.

2. 🧠 **Commit intelligence** – auto-scoped conventional messages that explain what changed, what was tested, and the scale of work.

3. 🏷️ **Release hygiene** – synchronized VERSION files, changelog updates, git tags, and optional registry publish.

4. ⚙️ **Multi-language support** – Python, Node.js, Rust, Go, Java, .NET, PHP, Ruby, and hybrid repos.

5. 🤖 **Prompted or headless** – run interactively (`goal`) or fire-and-forget in CI with `goal --all`.

### Three real-life flows

```bash

# 1. First-time setup in a folder without git

goal           # Goal offers to init git, add a remote, then re-run the workflow.

# 2. Everyday feature release

goal push      # Runs tests, suggests a commit, bumps patch, updates changelog, pushes, tags.

# 3. CI/CD or cron-driven release

goal --all --bump minor   # Non-interactive; perfect for nightly builds or release pipelines.

```

## 🆕 What's New in v2.2.1

> **Intelligent Package Manager Broker** — Automatic detection and selection of the fastest available package manager (uv, pdm, poetry, pip)

### ✨ New Features

**📦 PackageManagerBroker**

- Automatic detection of available package managers (uv, pdm, poetry, pip)

- Lockfile-aware installation (uv.lock → uv sync, poetry.lock → poetry install)

- Priority-based selection (uv fastest, pip as fallback)

- Auto-installation of uv when missing and pip is available

- Smart dependency installation with timing and reporting

```bash

# Doctor shows available managers

goal doctor

📦 Available package managers:

   ✓ uv       ⚡ fast   

     poetry   ⚡ fast   🔒

     pip      🐢 slow

# Force specific manager

goal doctor --manager uv

```

**⚡ Faster Python Installs**

- uv integration: 5-30s installs vs 2-10min with pip

- Automatic uv installation: `pip install uv` when uv missing

- Lockfile-first strategy: sync from lock when available

- Detailed timing reports: "✅ uv (12.3s) | fallback: pip"

### 🔧 Architecture Improvements

**Refactored Bootstrap System**

- Split `project_bootstrap.py` (1265L) → `goal/bootstrap/` module

- `goal/installers/` - new package manager abstraction layer

- `goal/bootstrap/installer.py` - unified installation interface

- Full backward compatibility maintained

---

## 🆕 What's New in v2.2.0

> **Wizard Setup, License Management & Multi-Author Support** — Complete project initialization, professional license handling, and team collaboration features

### ✨ New Features

**🧙‍♂️ Interactive Setup Wizard**

- One-command project initialization with `goal wizard`

- Guided git repository setup and remote configuration

- Interactive user configuration (name, email, license)

- Project configuration with versioning and commit strategies

- Complete setup summary with next steps

```bash

# New project setup in one command

goal wizard

```

**📄 Professional License Management**

- Create and update LICENSE files with 8 common license templates

- Custom license template support for proprietary licenses

- SPDX license ID validation with helpful error messages

- License compatibility checking between different licenses

- Automatic template variable substitution ({year}, {fullname})

```bash

# Create MIT license

goal license create MIT --fullname "Your Name"

# Check license compatibility

goal license check MIT Apache-2.0

```

**👥 Multi-Author Project Support**

- Team-based author management stored in project configuration

- Import authors from git history automatically

- Co-author support in commit messages with `--co-author` flag

- Export team list to CONTRIBUTORS.md

- Find authors by name, email, or alias

```bash

# Add team members

goal authors add "Jane Doe" jane@example.com --role "Developer"

# Commit with co-authors

goal commit --co-author "Jane Doe "

```

### 🛠️ Enhanced Commands

All new commands integrate seamlessly with existing Goal workflows:

```bash

# Complete workflow with co-authors

goal push --co-author "Jane Doe "

# Automated release with team attribution

goal --all --co-author "Team "

```

## 🆕 What's New in v2.1.99

> **Security Validation & Proactive .gitignore Management** — Automatic protection against large files, API tokens, and unwanted dot folders

### ✨ New Security Features

**🔒 File Size Validation**

- Automatically blocks files larger than 10MB (configurable)

- Prevents GitHub push failures due to file size limits

- Clear error messages with file size information

**🔑 API Token Detection**

- Scans for exposed API tokens before commit

- Supports GitHub, AWS, Slack, Stripe, GitLab patterns

- Detects private keys and sensitive credentials

- Blocks commit with location details

**📁 Proactive .gitignore Management**

- Automatically detects dot folders (.idea, .vscode, etc.)

- Adds problematic folders to .gitignore before commit

- Unstages files that should be ignored

- Respects existing whitelist patterns (!.vscode)

- Safe dot files are never ignored: `.gitignore`, `.github/`, `.editorconfig`, `.gitattributes`

### 🛡️ Security Validation in Action

```bash

# Before commit, Goal automatically checks:

goal push

# Also works with automation modes:

goal -a          # Full automation with validation

goal --all       # All stages with validation

goal --yes       # Auto-confirm with validation

# Output examples:

✅ Added 2 dot folder(s)/file(s) to .gitignore: .idea, .DS_Store

  → Unstaged: .idea

  → Unstaged: .DS_Store

# Or blocks dangerous commits:

❌ Validation Error: File secrets.db is 15.2MB, which exceeds the limit of 10MB

❌ Validation Error: Potential GitHub Personal Access token detected in .env:5

```

### ⚙️ Configuration Options

```yaml

# goal.yaml

advanced:

  file_validation:

    max_file_size_mb: 10          # File size limit

    block_large_files: true       # Block or just warn

    detect_api_tokens: true       # Enable token detection

    auto_manage_gitignore: true   # Auto-update .gitignore

    auto_add_dot_folders: true    # Auto-add dot folders

    known_dot_folders:           # Custom list of folders to ignore

      - .idea

      - .vscode

      - .DS_Store

      - .code2llm_cache

      - .llm

```

### 🚀 Bypass Options

```bash

# Force commit (not recommended for security)

goal push --force

# Dry run to check what would be blocked

goal push --dry-run

```

## 🆕 What's New in v2.1.65

> **TODO Management & Publishing Fixes** — Automatic issue tracking and reliable PyPI publishing

### ✨ New Features

**🎫 Automatic TODO Management**

- `goal doctor --todo` adds detected issues to `TODO.md`

- Unique ticket IDs prevent duplicates

- Rich formatting with severity icons

- Timestamped sections for tracking

**🔧 Publishing Improvements**

- Fixed "cannot access local variable 'Path'" error

- Better handling of `~/.pypirc` authentication

- Improved error messages and debugging

- Support for both token and config-based auth

**🛠️ Enhanced Diagnostics**

- Better error detection in project configuration

- More reliable build process

- Improved artifact management

### 📋 Example Usage

```bash

# Check version

goal -v

# Diagnose and track issues

goal doctor --todo

goal doctor -t

# Full workflow with TODO tracking

goal --all --todo

goal -a -t

# Standard workflow

goal --all

# Check project health

goal doctor

```

```

## 📚 Previous Features (v2.1)

> **Smart Commit Intelligence** — commit bodies that answer *what changed, what was tested, and at what scale*

❌ BEFORE: refactor(core): add testing, logging, validation

✅ AFTER:  feat(goal): intelligent code analysis pipeline

changes:

  - file: cli.py

    area: cli

    added: [ensure_git_repository, ensure_remote, _run_git_verbose]

    modified: [push]

  - file: test_clone_repo.py

    area: test

    new_tests: 3

testing:

  new_tests: 3

  scenarios:

    - auto_mode_skips

    - init_and_add_remote

    - clone_option_with_valid_url

stats:

  lines: "+210/-45 (net +165)"

  files: 2

  complexity: "Stable complexity"

```

> **Interactive Git Setup** — `goal` now guides you through repository configuration when no git repo is found

```

⚠  Not a git repository.

What would you like to do?

  [1] Initialize git here and connect to a remote  (keeps local files in 'myproject/')

  [2] Clone a remote repository into this directory  (downloads remote files)

  [3] Initialize a local-only git repository        (no remote)

  [4] Exit

```

📖 [Full Documentation](docs/enhanced-summary.md) | 📂 [Examples](examples/enhanced-summary/)

---

## Features

- 🚀 **Interactive workflow** - Confirms each stage (test, commit, push, publish) with Y/n prompts

- 🧠 **Smart commit messages** - Generates conventional commits based on diff analysis

- 🎯 **Enhanced Summary** - Business-value focused messages with capabilities, metrics, relations

- 👤 **User configuration** - Auto-detects git user info and license preferences (stored in `~/.goal`)

- 📄 **Smart metadata management** - Automatically updates author and license in project files

- 📝 **README automation** - Updates license badges and author sections automatically

- 🔍 **Version validation** - Checks registry versions and README badge consistency

- 📦 **Multi-language support** - Python, Node.js, Rust, Go, Ruby, PHP, .NET, Java

- 🏷️ **Version management** - Automatic version bumping and synchronization across project files

- 📝 **Changelog updates** - Maintains CHANGELOG.md with version history

- 🐳 **CI/CD ready** - `--yes` flag for automated workflows

- 🧪 **Test integration** - Runs project-specific test commands before committing

- 📦 **Publish support** - Publishes to package managers (PyPI, npm, crates.io, etc.)

- 🔒 **Security validation** - Blocks large files, detects API tokens, manages .gitignore automatically

## Installation

```bash

pip install goal

```

## Quick Start

### 1. Install Goal

```bash

pip install goal

```

### 2. Run `goal` in any project directory

```bash

cd my-project/

goal

```

Goal detects your situation and guides you interactively:

#### Scenario A: No git repository yet

```

⚠  Not a git repository.

What would you like to do?

  [1] Initialize git here and connect to a remote  (keeps local files in 'my-project/')

  [2] Clone a remote repository into this directory  (downloads remote files)

  [3] Initialize a local-only git repository        (no remote)

  [4] Exit

Choose [1]: 1

  → git init

✓ Initialized git repository.

Enter repository URL:

  SSH   example: git@github.com:user/repo.git

  HTTP  example: https://github.com/user/repo.git

URL: git@github.com:wronai/my-project.git

  → git remote add origin git@github.com:wronai/my-project.git

✓ Remote 'origin' → git@github.com:wronai/my-project.git

Fetching remote branches...

  → git fetch origin

  Remote is empty (no branches yet). Your local files will be the first push.

✓ Ready. Run 'goal' again to commit and push.

```

#### Scenario B: Git repo exists, no remote configured

```

⚠  No git remote configured.

Would you like to add a remote?

  [1] Add remote origin (connect to GitHub/GitLab/etc.)

  [2] Skip — commit locally without pushing

Choose [1]: 1

  → git remote add origin git@github.com:wronai/my-project.git

  Verifying connection...

  ✓ Remote is reachable.

✓ Remote 'origin' → git@github.com:wronai/my-project.git

```

#### Scenario C: Everything configured — the normal workflow

```

Detected project types: python

Will commit 5 files (+120/-15 lines, NET 105, 11% churn deletions)

Commit message: feat(api): add user authentication endpoint

Run tests? [Y/n]

Commit changes? [Y/n]

Push to remote? [Y/n]

Publish version 1.2.3? [Y/n]

```

Every git command is shown transparently (lines starting with `→`) so you always know what goal is doing.

### 3. Automation modes

```bash

# Full automation — tests, commit, push, publish (skips if no repo/remote)

goal -a

# Skip prompts but don't auto-publish

goal --yes

# Preview what would happen

goal --dry-run

```

> **Note:** `goal -a` in a directory without a git repository will **skip gracefully** instead of failing. This is safe for CI/CD pipelines.

### Running from a local clone

If you're working with the goal source code:

```bash

git clone https://github.com/wronai/goal.git

cd goal

# Use the local version without installing

python3 -m goal

# Or install in development mode

pip install -e .

```

## Documentation

📚 **Complete Documentation**: [docs/README.md](docs/README.md)

### Key Topics

- [Installation Guide](docs/installation.md) - Detailed installation instructions

- [Quick Start](docs/quickstart.md) - Get started in 5 minutes

- [Configuration Guide](docs/configuration.md) - Complete goal.yaml reference

- [Examples](docs/examples.md) - Real-world examples and use cases

- [CI/CD Integration](docs/ci-cd.md) - Use Goal in pipelines

- [Command Reference](docs/commands.md) - All commands and options

## Usage Examples

### Basic interactive workflow

```bash

# Run full interactive workflow with default patch bump

goal

# Run with minor version bump

goal --bump minor

# Run without prompts (for CI/CD)

goal --yes

# Automate ALL stages without any prompts

goal --all

```

### Real-world examples

#### 1. Python project with pytest

```bash

# Make changes to your Python code

git add .

# Run the full workflow

goal

# Output:

# ✓ Detected project types: python

# ✓ Running tests: pytest tests/ -v

# ✓ Tests passed (23/23)

# ✓ Generated commit: feat(api): add user authentication endpoint

# ✓ Updated VERSION to 1.2.3

# ✓ Updated CHANGELOG.md

# ✓ Created tag v1.2.3

# ✓ Pushed to origin

# ? Publish to PyPI? [Y/n]: Y

# ✓ Published version 1.2.3

```

#### 2. Node.js project with npm

```bash

# Quick patch release for bug fix

goal push --yes -m "fix: resolve memory leak in parser"

# Output:

# ✓ Detected project types: nodejs

# ✓ Running tests: npm test

# ✓ Tests passed

# ✓ Committed: fix: resolve memory leak in parser

# ✓ Updated package.json to 1.0.1

# ✓ Updated CHANGELOG.md

# ✓ Created tag v1.0.1

# ✓ Pushed to origin

```

#### 3. Rust project with cargo

```bash

# Major release with breaking changes

goal push --bump major --yes

# Output:

# ✓ Detected project types: rust

# ✓ Running tests: cargo test

# ✓ All tests passed

# ✓ Generated commit: feat!: change public API structure

# ✓ Updated Cargo.toml to 2.0.0

# ✓ Updated CHANGELOG.md

# ✓ Created tag v2.0.0

# ✓ Pushed to origin

# ? Publish to crates.io? [Y/n]: Y

# ✓ Published crate v2.0.0

```

#### 4. Publishing packages

```bash

# Publish only (after committing)

goal publish

# Or include publishing in the full workflow

goal --all  # Will publish automatically

```

**Important**: Goal automatically filters artifacts to upload only the current version, avoiding "File already exists" errors on PyPI.

If you see a "File already exists" error:

1. Clean and rebuild: `rm -rf dist build && python -m build`

2. Or bump version again: `goal --bump patch`

3. Check you're using the latest goal: `python3 -m goal` (in goal repo)

#### 4. Multi-language project

```bash

# Project with both Python backend and Node.js frontend

goal info

# Output:

# === Project Information ===

# Project types: python, nodejs

# Current version: 1.5.0

# 

# Version files:

#   ✓ VERSION: 1.5.0

#   ✓ package.json: 1.5.0

#   ✓ pyproject.toml: 1.5.0

# Run release - updates both package.json and pyproject.toml

goal push --yes

```

#### 5. Documentation updates

```bash

# Skip tests for docs-only changes

goal push --no-test -m "docs: update API documentation"

# Or let goal detect it's docs only

git add README.md docs/

goal push --yes

# Output:

# ✓ Detected project types: python

# ✓ Generated commit: docs: update API documentation

# ✓ Updated VERSION to 1.5.1

# ✓ Updated CHANGELOG.md

# ✓ Created tag v1.5.1

# ✓ Pushed to origin

```

#### 6. CI/CD automation

```yaml

# .github/workflows/release.yml

name: Release

on:

  push:

    branches: [main]

jobs:

  release:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v3

      - uses: actions/setup-python@v4

        with:

          python-version: '3.11'

      - name: Install Goal

        run: pip install goal

      - name: Configure PyPI token

        run: echo "__token__=${{ secrets.PYPI_TOKEN }}" > ~/.pypirc

      - name: Release

        run: goal --all --bump patch

```

#### 7. Dry run for preview

```bash

# Preview what will happen

goal push --dry-run --bump minor

# Output:

# === DRY RUN ===

# Project types: python

# Files to commit: 12 (+342/-15 lines)

#   - src/auth.py (+120/-5)

#   - tests/test_auth.py (+85/-0)

#   - docs/api.md (+137/-10)

# Commit message: feat(auth): add OAuth2 integration

# Version: 1.5.0 -> 1.6.0

# Version sync: VERSION, pyproject.toml

# Tag: v1.6.0

```

#### 8. Custom commit message

```bash

# Override auto-generated message

goal push -m "feat: implement real-time notifications"

# Or use conventional commit format

goal push -m "fix(auth): resolve JWT token expiration issue"

```

#### 9. Split commits for large changes

```bash

# Split changes into logical commits

goal push --split --yes

# Output:

# ✓ Committed docs: update README and API docs

# ✓ Committed feat: add user authentication system

# ✓ Committed test: add comprehensive test coverage

# ✓ Committed chore: update dependencies and CI config

# ✓ Committed release: v2.0.0

```

#### 11. Security Validation Examples

```bash

# Goal automatically protects against security issues

goal push

# Example 1: Large file detected

# ❌ Validation Error: File database.dump is 15.2MB, which exceeds the limit of 10MB

# For security reasons, the commit has been blocked.

# To bypass this check, you can:

# 1. Remove the sensitive/large file(s)

# 2. Add the file(s) to .gitignore

# 3. Use --force to bypass validation (not recommended)

# Example 2: API token detected

# ❌ Validation Error: Potential GitHub Personal Access token detected in .env:5

# For security reasons, the commit has been blocked.

# Example 3: Dot folder auto-management

# ✅ Added 3 dot folder(s)/file(s) to .gitignore: .idea, .vscode, .DS_Store

#   → Unstaged: .idea

#   → Unstaged: .vscode

#   → Unstaged: .DS_Store

```

#### 12. Skip specific steps

```bash

# Skip version bump for hotfix

goal push --yes --no-version-sync -m "hotfix: critical security patch"

# Skip changelog for minor tweak

goal push --yes --no-changelog -m "style: fix linting issues"

# Skip tag creation for experimental feature

goal push --yes --no-tag -m "feat: experimental AI integration"

```

### Using the push command directly

```bash

# Interactive push with prompts

goal push

# Automatic push without prompts

goal push --yes

# Dry run to see what would happen

goal push --dry-run

# Custom commit message

goal push -m "feat: add new authentication system"

# Skip specific steps

goal push --no-tag --no-changelog

# With version bump

goal push --bump minor

# Markdown output for CI/CD logs

goal push --markdown

```

### Version management

```bash

# Check current version

goal version

# Bump specific version type

goal version --bump minor

goal version --bump major

# Check repository status

goal status

```

## Supported Project Types

Goal automatically detects your project type and uses appropriate commands:

| Language | Test Command | Publish Command | Version Files |

|----------|--------------|-----------------|---------------|

| **Python** | `pytest` | `python -m build && twine upload dist/*` | pyproject.toml, setup.py |

| **Node.js** | `npm test` | `npm publish` | package.json |

| **Rust** | `cargo test` | `cargo publish` | Cargo.toml |

| **Go** | `go test ./...` | `git push origin --tags` | go.mod (uses git tags) |

| **Ruby** | `bundle exec rspec` | `gem build *.gemspec && gem push *.gem` | *.gemspec |

| **PHP** | `composer test` | `composer publish` | composer.json |

| **.NET** | `dotnet test` | `dotnet pack && dotnet nuget push *.nupkg` | *.csproj |

| **Java** | `mvn test` | `mvn deploy` | pom.xml, build.gradle |

## Markdown Output

Goal outputs structured markdown by default (perfect for LLM consumption and CI/CD logs). Use `--ascii` to get the legacy console output.

```bash

# Default: markdown output

goal push

goal status

# Force legacy output

goal push --ascii

goal status --ascii

# Use with automation

goal --all > release.log

```

The markdown output includes:

- Front matter with metadata (command, version, file count)

- Structured sections for overview, files, and test results

- Code blocks for command outputs

- Summary with actions taken and next steps

Example output:

```markdown

---

command: goal push

project_types: ["python"]

version_bump: "1.0.1 -> 1.0.2"

file_count: 7

---

# Goal Push Result

## Overview

**Project Type:** python

**Files Changed:** 7 (+1140/-99 lines)

**Version:** 1.0.1 → 1.0.2

...

```

See [docs/markdown-output.md](docs/markdown-output.md) for detailed examples.

## Command Reference

### `goal` or `goal push`

Main command for the complete workflow.

**Options:**

- `-v, --version`: Show version and exit

- `--bump, -b`: Version bump type [patch|minor|major] (default: patch)

- `--yes, -y`: Skip all prompts (run automatically)

- `--all, -a`: Automate all stages including tests, commit, push, and publish

- `--todo/--no-todo, -t`: Add unfixed issues to TODO.md during doctor phase (default: no)

- `--markdown/--ascii`: Output format (default: markdown)

- `--split`: Create separate commits per change type (docs/code/ci/examples)

- `--ticket`: Ticket prefix to include in commit titles (overrides TICKERT)

- `--no-tag`: Skip creating git tag

- `--no-changelog`: Skip updating changelog

- `--no-version-sync`: Skip syncing version to project files

- `--message, -m`: Custom commit message

- `--dry-run`: Show what would be done without doing it

### `goal doctor`

Diagnose and auto-fix common project configuration issues.

**Options:**

- `--fix/--no-fix`: Auto-fix issues (default: yes)

- `--path, -p`: Root directory to scan (default: .)

- `--todo/--no-todo, -t`: Add unfixed issues to TODO.md (default: no)

**Examples:**

```bash

goal doctor              # Diagnose and auto-fix

goal doctor --no-fix     # Diagnose only

goal doctor --todo       # Add issues to TODO.md

goal doctor -t           # Add issues to TODO.md (short form)

```

## Split commits (per type)

When `--split` is enabled, Goal will create multiple commits:

- **code**: changes in `goal/`, `src/`, `lib/`, `*.py`

- **docs**: `docs/*`, `README.md`, `*.md`

- **ci**: `.github/*`, `.gitlab/*`, `*.yml`/`*.yaml`

- **examples**: `examples/*`

- **other**: everything else

Then it will create a final **release metadata** commit with version bump + changelog (unless disabled).

## Ticket prefixing (TICKET)

Create a `TICKET` file in repository root:

```ini

prefix=ABC-123

format=[{ticket}] {title}

```

You can override it per run:

```bash

goal push --ticket ABC-123

goal push --split --ticket ABC-123

goal commit --ticket ABC-123

```

### `goal init`

Initialize goal in current repository.

Creates:

- `VERSION` file with initial version 1.0.0

- `CHANGELOG.md` with standard template

### `goal status`

Show current git status and version info.

Displays:

- Current version

- Current branch

- Staged files

- Unstaged/untracked files

### `goal version`

Show or bump version.

**Options:**

- `--type, -t`: Version bump type [patch|minor|major] (default: patch)

### `goal wizard`

Interactive guided setup for new projects.

Walks you through:

- Git repository initialization and remote configuration

- User configuration (name, email, license)

- Project configuration (name, description, versioning strategy)

- Complete setup summary with next steps

**Options:**

- `--reset`: Reset and reconfigure everything

- `--skip-git`: Skip git repository setup

- `--skip-user`: Skip user configuration

- `--skip-project`: Skip project configuration

### `goal license`

Manage project licenses.

**Subcommands:**

- `create `: Create LICENSE file

- `update`: Update existing LICENSE file

- `validate`: Validate LICENSE file

- `info `: Show license information

- `check  `: Check compatibility

- `list`: List available templates

- `template `: Add/show custom templates

**Examples:**

```bash

goal license create MIT --fullname "Your Name"

goal license check MIT Apache-2.0

goal license list

```

### `goal authors`

Manage project authors and team members.

**Subcommands:**

- `list`: List all project authors

- `add  `: Add an author

- `remove `: Remove an author

- `update `: Update author info

- `import`: Import from git history

- `export`: Export to CONTRIBUTORS.md

- `find `: Find author by name/email/alias

- `current`: Show current user info

**Examples:**

```bash

goal authors add "Jane Doe" jane@example.com --role "Developer"

goal authors list

goal authors import

```

### Co-author Support

Add co-authors to commits:

```bash

goal commit --co-author "Jane Doe "

goal commit --co-author "Jane " --co-author "Bob "

```

## Examples by Use Case

### New Project Setup

```bash

# Interactive guided setup

goal wizard

```

📖 [Full Wizard Example](examples/wizard-setup/)

### License

Licensed under Apache-2.0.

Licensed under Apache-2.0.

Licensed under Apache-2.0.

Licensed under Apache-2.0.

# Check license compatibility

goal license check MIT Apache-2.0

```

📖 [License Management Examples](examples/license-management/)

### Team Collaboration

```bash

# Add team members

goal authors add "Jane Doe" jane@example.com --role "Developer"

# Commit with co-authors

goal commit --co-author "Jane Doe "

```

📖 [Multi-Author Project Examples](examples/multi-author/)

### Development Workflow

```bash

# Make your changes...

git add some/files

# Run goal with interactive prompts

goal

# Prompts will appear:

# Run tests? [Y/n] - Runs pytest for Python projects

# Commit changes? [Y/n] - Creates smart commit message

# Push to remote? [Y/n] - Pushes to origin with tags

# Publish version 1.2.3? [Y/n] - Publishes to PyPI/npm/etc

```

### Full Automation

```bash

# Automate everything - tests, commit, push, publish

goal --all

# Short form

goal -a

# With specific version bump

goal --all --bump minor

```

### CI/CD Pipeline

```yaml

# GitHub Actions example

- name: Deploy with Goal

  run: |

    goal push --yes --bump minor

    

# Or with --all flag

- name: Full release

  run: |

    goal --all --bump patch

```

### Skip Testing in Quick Fixes

```bash

# Skip tests for documentation changes

goal push --yes -m "docs: update README"

```

### Pre-release Workflow

```bash

# Check what will be done

goal push --dry-run --bump minor

# Run with specific version bump

goal push --bump minor

# Or skip publishing for internal releases

goal push --yes --no-tag

```

### Working with Multiple Projects

```bash

# Monorepo with frontend and backend

# Structure:

# /backend (Python)

# /frontend (Node.js)

# /docs

# From root directory

goal info

# Output:

# Project types: python, nodejs

# Version files:

#   ✓ VERSION: 2.1.0

#   ✓ backend/pyproject.toml: 2.1.0

#   ✓ frontend/package.json: 2.1.0

# Release updates all projects

goal push --yes

```

### Hotfix Workflow

```bash

# Critical fix - skip tests and version bump

goal push --yes --no-test --no-version-sync -m "hotfix: security patch"

# Then create proper release

goal push --bump patch -m "release: v1.2.1 with security fix"

```

### Feature Branch Workflow

```bash

# On feature branch

goal push --yes --no-tag --no-publish

# After merge to main

goal push --bump minor --yes

```

### Release Candidate

```bash

# Create RC version

goal push --bump patch -m "release: v2.0.0-rc1"

# After testing, promote to stable

goal push --bump patch -m "release: v2.0.0 stable"

```

## Configuration

Goal uses `goal.yaml` for configuration. Run `goal init` to create it automatically with detected settings.

### goal.yaml Structure

```yaml

# goal.yaml - Goal configuration file

version: "1.0"

project:

  name: "my-project"           # Auto-detected from pyproject.toml/package.json

  type: ["python"]             # Auto-detected project types

  description: "My project"    # Auto-detected description

versioning:

  strategy: "semver"           # semver, calver, or date

  files:                       # Files to sync version to

    - "VERSION"

    - "pyproject.toml:version"

    - "package.json:version"

  bump_rules:                  # Auto-bump thresholds

    patch: 10                  # Files changed

    minor: 50                  # Lines added

    major: 200                 # Large changes

git:

  commit:

    strategy: "conventional"   # conventional, semantic, custom

    scope: "my-project"        # Default scope for commits

    templates:                 # Custom commit templates

      feat: "feat({scope}): {description}"

      fix: "fix({scope}): {description}"

      docs: "docs({scope}): {description}"

    classify_by:               # Classification methods

      - "file_extensions"

      - "directory_paths"

      - "line_stats"

      - "keywords_diff"

  changelog:

    enabled: true

    template: "keep-a-changelog"

    output: "CHANGELOG.md"

    sections: ["Added", "Changed", "Fixed", "Deprecated"]

  tag:

    enabled: true

    prefix: "v"

    format: "{prefix}{version}"

strategies:

  python:

    test: "pytest tests/ -v"

    build: "python -m build"

    publish: "twine upload dist/*"

  nodejs:

    test: "npm test"

    build: "npm run build"

    publish: "npm publish"

registries:

  pypi:

    url: "https://pypi.org/simple/"

    token_env: "PYPI_TOKEN"

  npm:

    url: "https://registry.npmjs.org/"

    token_env: "NPM_TOKEN"

hooks:

  pre_commit: ""               # Command to run before commit

  post_commit: ""              # Command to run after commit

  pre_push: ""                 # Command to run before push

  post_push: ""                # Command to run after push

advanced:

  auto_update_config: true     # Auto-update config on detection changes

  performance:

    max_files: 50              # Split commits if > N files

    timeout_test: 300          # Test timeout in seconds

  file_validation:

    max_file_size_mb: 10       # File size limit (default: 10MB)

    block_large_files: true    # Block large files or just warn

    detect_api_tokens: true    # Scan for API tokens

    auto_manage_gitignore: true  # Auto-update .gitignore

    auto_add_dot_folders: true   # Auto-add dot folders to .gitignore

    known_dot_folders:         # Custom dot folders to ignore

      - .idea

      - .vscode

      - .DS_Store

      - .pytest_cache

      - .code2llm_cache

      - .llm

    token_patterns: []         # Custom regex patterns for token detection

```

### Config Commands

```bash

# Show full configuration

goal config show

# Show specific key (dot notation)

goal config show -k git.commit.strategy

# Get a value

goal config get project.name

# Set a value

goal config set git.commit.scope "my-app"

# Validate configuration

goal config validate

# Update config based on project detection

goal config update

```

### Custom Config File

```bash

# Use a custom config file

goal --config custom-goal.yaml push

# Or in CI/CD

goal -c .goal/ci.yaml --all

```

### Conventions (without goal.yaml)

Goal also works without configuration based on conventions:

1. **Version detection**: Looks for `VERSION` file first, then project-specific files

2. **Project detection**: Automatically detects project type from files

3. **Commit messages**: Uses conventional commit format based on diff analysis

4. **Changelog**: Updates CHANGELOG.md in Keep a Changelog format

## Integration Examples

### Makefile

```makefile

.PHONY: release patch minor major

# Interactive release

release:

	goal

# Automatic patch release

patch:

	goal push --yes

# Full automation release

all:

	goal --all

# Automatic minor release

minor:

	goal push --yes --bump minor

# Automatic major release

major:

	goal push --yes --bump major

# Dry run

dry-run:

	goal push --dry-run

# Release with custom message

release-message:

	goal push --yes -m "$(MSG)"

# Release from specific branch

release-branch:

	git checkout main

	git pull

	goal --all --bump $(BUMP)

```

### package.json scripts

```json

{

  "scripts": {

    "release": "goal",

    "release:patch": "goal push --yes",

    "release:all": "goal --all",

    "release:minor": "goal push --yes --bump minor",

    "release:major": "goal push --yes --bump major",

    "release:dry": "goal push --dry-run",

    "release:docs": "goal push --yes -m 'docs: update documentation'"

  }

}

```

### pre-commit hook

```bash

#!/bin/sh

# .git/hooks/pre-commit

echo "Running goal pre-commit check..."

goal push --dry-run

if [ $? -eq 0 ]; then

    echo "✅ Ready to commit!"

else

    echo "❌ Issues found. Fix them before committing."

    exit 1

fi

```

### Docker integration

```dockerfile

# Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install dependencies

COPY requirements.txt .

RUN pip install -r requirements.txt

# Install goal

RUN pip install goal

# Copy source code

COPY . .

# Run tests and release

CMD ["sh", "-c", "goal --all"]

```

## Smart Commit Messages

Goal analyzes your changes to generate appropriate commit messages:

- **feat**: New features, additions

- **fix**: Bug fixes, patches

- **docs**: Documentation changes

- **style**: Formatting, linting

- **refactor**: Code restructuring

- **perf**: Performance improvements

- **test**: Test additions/changes

- **build**: Build system, CI/CD

- **chore**: Dependencies, maintenance

Examples:

- `feat: add user authentication`

- `fix: resolve memory leak in parser`

- `docs: update API documentation`

- `test: add coverage for payment module`

## Troubleshooting

### Security Validation Blocks Commit

Goal automatically protects against security issues:

```bash

# Large file detected

❌ Validation Error: File database.dump is 15.2MB, which exceeds the limit of 10MB

# API token detected  

❌ Validation Error: Potential GitHub Personal Access token detected in .env:5

# Solutions:

1. Remove the sensitive/large file

2. Add the file to .gitignore

3. Use --force to bypass (not recommended)

```

### Configure Security Validation

```yaml

# goal.yaml

advanced:

  file_validation:

    max_file_size_mb: 10        # Adjust limit

    block_large_files: false    # Only warn instead of block

    detect_api_tokens: true     # Enable/disable token detection

    auto_manage_gitignore: false # Disable auto .gitignore updates

```

### Tests fail but I want to continue

The interactive workflow will ask if you want to continue when tests fail:

```

Tests failed. Continue anyway? [y/N]

```

### Custom test/publish commands

If Goal doesn't detect your test command correctly, you can run them manually before using `goal push --yes`.

### TODO Management

Goal can automatically add detected issues to `TODO.md` without duplicates:

```bash

# Diagnose and add unfixed issues to TODO.md

goal doctor --todo

goal doctor -t

# Diagnose without auto-fix but add to TODO.md

goal doctor --todo --no-fix

goal doctor -t --no-fix

# Full workflow with TODO tracking

goal --all --todo

goal -a -t

```

**Features:**

- 🎫 **Unique ticket IDs** - Format `[CODE-identifier]` for each issue

- 🚫 **No duplicates** - Checks existing tickets before adding

- 🎨 **Rich formatting** - Icons, severity levels, file references

- 📅 **Timestamped sections** - Groups issues by detection date

**Example TODO.md entry:**

```markdown

## Issues Found - 2026-02-24

- [PY002-missingbuildsysteminpyprojecttoml] 🔴 **Missing [build-system] in pyproject.toml** (`pyproject.toml`)

  - pyproject.toml has no [build-system] section.

  - pip and build tools need this to know how to build your package.

  - Adding a default setuptools build-system.

```

### Publishing fails

Ensure you're authenticated with the appropriate package manager:

**PyPI Authentication Options:**

- **Recommended**: Configure `~/.pypirc` file (development)

- **CI/CD**: Set `PYPI_TOKEN` environment variable

- **Interactive**: Run `twine configure`

**~/.pypirc setup (recommended for development):**

```ini

[pypi]

  username = __token__

  password = pypi-AgEIcHlwaS5vcmcC...

```

**Environment variable setup (for CI/CD):**

```bash

export PYPI_TOKEN=your_token_here

```

**Other package managers:**

- npm: `npm login`

- crates.io: `cargo login`

### Common Issues

#### Goal doesn't detect my project type

```bash

# Check what's detected

goal info

# Manually specify in goal.yaml

project:

  type: ["python", "nodejs"]

```

#### Version sync not working

```bash

# Check version files

goal info

# Manually configure in goal.yaml

versioning:

  files:

    - "VERSION"

    - "my-app/__init__.py:__version__"

```

#### Tests timing out

```yaml

# In goal.yaml

advanced:

  performance:

    timeout_test: 600  # 10 minutes

```

#### Commit message not accurate

```bash

# Use custom message

goal push -m "your custom message"

# Or configure templates in goal.yaml

git:

  commit:

    templates:

      feat: "feat({scope}): {description}"

```

## User Configuration

Goal automatically manages your project metadata using your git configuration and license preferences.

### First-time Setup

On first run, Goal will:

1. **Auto-detect** your git `user.name` and `user.email`

2. **Ask for license preference** (8 popular open source licenses)

3. **Save to** `~/.goal` for future use

```bash

$ goal

======================================================================

  🎯 Goal - First Time Setup

======================================================================

✓ Detected git user.name: Tom Sapletta

✓ Detected git user.email: info@softreck.com

======================================================================

  📄 License Selection

======================================================================

  1. Apache License 2.0

  2. MIT License

  3. GNU General Public License v3.0

  4. BSD 3-Clause License

  5. GNU General Public License v2.0

  6. GNU Lesser General Public License v3.0

  7. GNU Affero General Public License v3.0

  8. Mozilla Public License 2.0

Enter your choice [1]: 1

✓ Configuration saved to ~/.goal

```

### What Gets Updated Automatically

Every time you run `goal`, it updates:

**Project Files:**

- `pyproject.toml` - authors, license, classifier

- `package.json` - author, license, contributors

- `Cargo.toml` - authors, license

- `VERSION` - version number

- `__init__.py` - `__version__` variable (in all packages)

**README.md:**

- License badges (Apache-2.0, MIT, GPL, etc.)

- `## License

Licensed under Apache-2.0.

Licensed under Apache-2.0.

Licensed under Apache-2.0.

Licensed under Apache-2.0.

### Smart Author Management

Goal **adds** authors instead of replacing them:

```python

# Before (existing author)

authors = [{name = "Original Author", email = "original@example.com"}]

# After (Goal adds you)

authors = [

    {name = "Original Author", email = "original@example.com"},

    {name = "Tom Sapletta", email = "info@softreck.com"},

]

```

### Managing Your Configuration

```bash

# View current configuration

goal config

# Reset and reconfigure

goal config --reset

# Configuration file location

~/.goal

```

### Example Output

```bash

$ goal config

======================================================================

  📋 Goal User Configuration

======================================================================

Config file: /home/tom/.goal

Current settings:

  Author name:  Tom Sapletta

  Author email: info@softreck.com

  License:      Apache License 2.0 (Apache-2.0)

💡 Tip: Run 'goal config --reset' to reconfigure

```

## Tips & Tricks

### 1. Use with aliases

```bash

# Add to ~/.bashrc or ~/.zshrc

alias g='goal'

alias gp='goal push --yes'

alias ga='goal --all'

alias gd='goal push --dry-run'

```

### 2. Team workflow

```bash

# For team development, use ticket prefixes

echo "prefix=PROJ-123" > TICKET

goal push --split  # Creates commits like "PROJ-123: feat: add feature"

```

### 3. Release checklist

```bash

# Before release

goal status      # Check status

goal push --dry-run  # Preview changes

# Release

goal --all       # Full automation

```

### 4. Working with feature flags

```bash

# Commit feature flag changes

goal push -m "feat: enable beta feature flag"

# Later, remove the flag

goal push -m "feat: launch feature to all users"

```

### 5. Automated releases on schedule

```yaml

# .github/workflows/scheduled-release.yml

name: Scheduled Release

on:

  schedule:

    - cron: '0 9 * * 1'  # Every Monday at 9 AM

jobs:

  release:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v3

      - name: Install Goal

        run: pip install goal

      - name: Weekly Release

        run: goal --all --bump patch

```

## License

Licensed under Apache-2.0.

## Author

Tom Sapletta

## Status

_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 13:38 UTC_

| Metric | Value |

|---|---|

| HEAD | `7edd05b` |

| Coverage | — |

| Failing tests | — |

| Commits in last cycle | 50 |

> 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.