git-forge: Plan-First Git Workflow

Stop wrestling with branches. Start building features.

git-forge is a structured, stateful developer workflow CLI built on top of Git. It adds a plan-first layer to your development process, giving you a themed terminal control surface and guided flow for managing features—all while keeping Git as the absolute source of truth.

🚀 Key Features

• 🗺️ Plan-First Architecture: Define your roadmap with plan before you write a single line of code.
• 🛠️ Automated Context Switching: Use smelt to instantly jump into a feature's context without manual branch juggling.
• 🎯 Atomic File Attribution: quench guides you to assign files to features, ensuring clean and logical commits.
• ⚡ Reversible History (The Vault): Powerful unweld and weld commands allow you to remove and restore features at the history level.
• 🖥️ Anvil Dashboard: A rich Ink-based TUI for a visual, real-time overview of your project's state.
• 🤖 CI/CD Ready: First-class --json support for all non-interactive commands.

📦 Installation

# Install globally
npm install -g @jayepcore/git-forge

# Or run via npx
npx @jayepcore/git-forge --help

🛠️ The Forge Workflow

1. Initialize your Forge

git-forge heat

Initializes the .forge directory to track state, templates, and your vault.

2. Plan your Work

git-forge plan auth

Launch the interactive builder to define root features and sub-features. It generates a YAML template and a flattened state file.

3. Activate a Feature

git-forge smelt login --template auth

Creates the template branch (if needed), checks it out, and marks the "login" feature as active.

4. Commit with Attribution

git-forge quench login

quench ensures that only files belonging to the specified feature are committed, preventing "oops" files from leaking into your feature commits.

5. Manage the Vault

git-forge unweld login
git-forge weld login --message "restore login flow"

unweld performs a revert-style removal, storing the restoration metadata in the vault. weld brings it back whenever you're ready.

🖥️ The Anvil Dashboard

git-forge anvil

The Anvil is your mission control. It provides:

• Visual feature tree and focus tracking.
• Progress indicators and status badges.
• Strike Suggestions: Intelligent prompts for what to work on next.
• Hotkeys for quick actions (smelt, quench, weld, unweld).

⚙️ Configuration

git-forge is highly configurable via forge.toml. Customize your Git prefix, auto-checkout behavior, and commit templates to match your team's style.

🤝 Contributing

Contributions are welcome! Please see the Verification section for details on running tests and building the project locally.

Verification

npm install
npm run check
npm test
npm run build

📄 License

Distributed under the MIT License. See LICENSE for more information.

Built with ❤️ by JEP Labs