{"id":45607262,"url":"https://github.com/lixus3d/feat-forge-cli","last_synced_at":"2026-02-23T16:11:01.577Z","repository":{"id":338320033,"uuid":"1149295472","full_name":"lixus3d/feat-forge-cli","owner":"lixus3d","description":"Feature-first CLI workflow tool for building software at scale with AI agents. Organize specs, parallelize work across repos and agents, and switch contexts without losing track.","archived":false,"fork":false,"pushed_at":"2026-02-14T01:32:18.000Z","size":467,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-14T04:33:11.486Z","etag":null,"topics":["ai","ai-agents","cli","code-generation","devops","feature-management","forge","git-worktree","multi-repo","specification","tdd","workflow"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lixus3d.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-02-04T00:23:50.000Z","updated_at":"2026-02-14T01:32:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lixus3d/feat-forge-cli","commit_stats":null,"previous_names":["lixus3d/feat-forge-cli"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/lixus3d/feat-forge-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lixus3d%2Ffeat-forge-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lixus3d%2Ffeat-forge-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lixus3d%2Ffeat-forge-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lixus3d%2Ffeat-forge-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lixus3d","download_url":"https://codeload.github.com/lixus3d/feat-forge-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lixus3d%2Ffeat-forge-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29747979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-23T07:44:07.782Z","status":"ssl_error","status_checked_at":"2026-02-23T07:44:07.432Z","response_time":90,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","ai-agents","cli","code-generation","devops","feature-management","forge","git-worktree","multi-repo","specification","tdd","workflow"],"created_at":"2026-02-23T16:11:01.125Z","updated_at":"2026-02-23T16:11:01.571Z","avatar_url":"https://github.com/lixus3d.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FeatForge\n\n[![CI](https://github.com/lixus3d/feat-forge-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/lixus3d/feat-forge-cli/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/feat-forge)](https://www.npmjs.com/package/feat-forge)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Vitest](https://img.shields.io/badge/tested%20with-Vitest-6E9F18?logo=vitest\u0026logoColor=white)](https://vitest.dev/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/lixus3d/feat-forge-cli/pulls)\n\n**FeatForge** is a feature-first workflow and CLI (`forge`) to help you build software at scale, with (or without) AI agents.\n\nIts goal is to make the specification of features explicit and separate the thinking/specifying phase from the coding/implementation phase, across multiple agents and repositories, while keeping everything organized and traceable.\n\nWith **FeatForge** you will be able to:\n\n- Parallelize work on multiple features:\n    - across multiple repositories.\n    - across multiple agents.\n    - while keeping track of everything.\n- Come back to any feature after days/weeks and immediately understand its initial specifications.\n- Change agent configurations and prompts on a per-feature basis.\n- Switch between agents whenever you want, without losing any context or work.\n\n**FeatForge** is :\n\n- Developed using FeatForge itself from the start. You can look at the `.specs/` folder to see how features are specified and implemented, and how agents are configured. Test and Learn by example!\n- Not opinionated about how you specify features, how you implement them, or how you use agents. It just provides a structure (yet customizable) and a workflow to keep everything organized and traceable.\n- Partially tested with : Copilot, Codex, Claude code (+Ollama, LM-Studio). But it should work with any agent that can be configured to read/write files in the `.active-spec` folders.\n\n**_This is an experiment, trying to mix between classic development and vibe-coding in large project with quality and sustainability in mind by making specification explicit and separating thinking from coding across multiple agents and repositories._**\n\n## Key Concepts\n\n- A **branch** is a self-contained unit with its own spec (`SPEC.md`) and tasks (`TODO.md`).\n- You always work inside one **active spec** (`.active-spec`) per git worktree, which can span multiple repositories.\n- Multiple modes are available per branch (see [Modes](#modes)).\n- Agents goals are always scoped to a branch, never global.\n- You can launch multiple agents per branch and work on multiple branches in parallel.\n- Finished branches are archived in `.specs/.archives/`.\n- Branch types: `anything` `feature/`, `fix/`, `release/` (each with their own customizable prefix).\n\n---\n\n## Installation\n\n```bash\nnpm install -g feat-forge\nforge --version\n```\n\n---\n\n## Quick Start\n\n```bash\n# Initialize FeatForge in your project\nforge init\n\n# Create a new feature (branch: feature/my-feature (customizable prefix))\nforge feature create my-feature\n\n# Start working on a feature (creates worktrees)\nforge feature start my-feature\n\n# Switch mode (updates agent files with the templates for this mode)\nforge mode code\n\n# Stop working on a feature (cleanup worktrees)\nforge feature stop my-feature\n\n# Archive a completed feature\nforge feature archive my-feature\n```\n\n---\n\n## Recommended Folder Structure\n\nHere is a typical FeatForge project layout (forge creates most folders/files automatically):\n\n```\nforge-project-root/\n  .feat-forge.json            # Configuration file for the project (per user)\n  repo1/\n    .git/                     # Git repository for repo1\n  repo2/                      # Main repo (contains .specs/)\n    .git/                     # Git repository for repo2\n    .specs/                   # All branch spec directories (created on first branch creation)\n      .archives/              # Archived branch folders (moved here when archived)\n      .template/              # Template for new branches\n        agent/                # Agent configuration templates\n          CONTEXT.spec.md     # Legacy spec mode context template\n          CONTEXT.code.md     # Legacy code mode context template\n      \u003cbranch-slug\u003e/          # Active branch\n        SPEC.md               # Branch specification (required)\n        TODO.md               # Implementation tasks (required)\n        .forge-mode           # Current mode\n  repo3/\n    .git/                     # Git repository for repo3\n  worktrees/\n    001-bootstrap/            # Example active branch directory (created on branch start)\n      repo1/                  # git worktree for repo1 (created on branch start)\n        .active-spec -\u003e ../repo2/.active-spec  # symlink to active spec in main repo\n      repo2/                  # git worktree for repo2 (created on branch start)\n        .active-spec -\u003e ../.specs/001-bootstrap  # symlink to active spec in this repo\n        .specs/\n          001-bootstrap/      # actual branch folder with spec and agent context\n            .forge-mode       # current mode\n            SPEC.md           # branch specification\n            TODO.md           # implementation tasks\n      repo3/                  # git worktree for repo3 (created on branch start)\n        .active-spec -\u003e ../repo2/.active-spec  # symlink to active spec in main repo\n```\n\n---\n\n## Modes\n\nEach branch has a mode stored in `.specs/\u003cslug\u003e/.forge-mode`. Switching modes updates agent adapter files with the corresponding templates.\nAgent names are useful when calling subagents.\n\nBuilt-in modes:\n\n| Mode            | Agent                | Description                         |\n| --------------- | -------------------- | ----------------------------------- |\n| `general`       | Omnibus              | General-purpose agent               |\n| `discovery`     | Inventorius          | Explore and understand the codebase |\n| `design`        | Architecturius       | Design architecture and specs       |\n| `plan`          | Strategos            | Plan implementation strategy        |\n| `tdd`           | TestDrivenCodificius | Test-driven development             |\n| `code`          | Codificius           | Implement according to the spec     |\n| `simplify`      | Consolidarius        | Simplify and consolidate code       |\n| `review`        | Auditorix            | Review code                         |\n| `test-writer`   | TestScriptor         | Write tests                         |\n| `test-executor` | TestExecutor         | Execute tests                       |\n| `commit`        | Scribus              | Commit changes                      |\n\nSwitch modes at any time:\n\n```bash\nforge mode \u003cmode\u003e\n```\n\n---\n\n## Command Reference\n\n### `forge init`\n\nInitialize FeatForge in your project. Interactively creates `.feat-forge.json`, scans for git repos and asks for options.\n\n**Usage:**\n\n```bash\nforge init\n```\n\n**Options:**\n\n- `--yes` / `-y` : Accept all defaults\n- `--force` / `-f` : Overwrite config (with backup)\n- `--repositories \u003cpaths\u003e` : Comma-separated repo paths\n- `--agents \u003cnames\u003e` : Comma-separated agent names\n- `--ides \u003cnames\u003e` : Comma-separated IDE names\n\n---\n\n### `forge feature create \u003cslug\u003e`\n\nCreate a new feature branch folder and initialize its spec.\n\n**Usage:**\n\n```bash\nforge feature create my-feature\n```\n\n**Options:**\n\n- `--yes` : Skip confirmation\n- `--no-branch` : Do not create a branch\n\n---\n\n### `forge feature start \u003cslug\u003e`\n\nCreate git worktrees for all repos and set the feature as active.\n\n**Usage:**\n\n```bash\nforge feature start my-feature\n```\n\n**Options:**\n\n- `--ide \u003cname\u003e` : Open in specified IDE\n\n---\n\n### `forge feature list`\n\nList all active feature branches and their worktrees.\n\n**Usage:**\n\n```bash\nforge feature list\n```\n\n---\n\n### `forge feature stop \u003cslug\u003e`\n\nClean up worktrees and remove the active spec symlink.\n\n**Usage:**\n\n```bash\nforge feature stop my-feature\n```\n\n---\n\n### `forge feature archive \u003cslug\u003e`\n\nMove a completed feature to `.specs/.archives/`.\n\n**Usage:**\n\n```bash\nforge feature archive my-feature\n```\n\n**Options:**\n\n- `--force` : Skip confirmation\n\n---\n\n### `forge feature merge \u003cslug\u003e`\n\nMerge a feature branch into a target branch (across all repos).\n\n---\n\n### `forge feature rebase \u003cslug\u003e`\n\nRebase a feature branch onto a base branch (across all repos).\n\n---\n\n### `forge feature open [slug]`\n\nOpen a feature branch in the configured IDE.\n\n---\n\n### `forge feature resync \u003cslug\u003e`\n\nResync all repos to the expected branch.\n\n---\n\n### `forge fix` / `forge release` / `forge \u003ccommand\u003e branch`\n\nSame commands as `forge feature`, but with automatic `fix/` or `release/` prefix for branch names, or just plain branch names if you prefer.\n\n```bash\nforge fix create my-bugfix\nforge release create v1.2.0\nforge start dev\n```\n\n---\n\n### `forge merge \u003cslug\u003e` / `forge rebase \u003cslug\u003e`\n\nTop-level shortcuts for merge and rebase operations (across all repos).\n\n---\n\n### `forge mode \u003cmode\u003e`\n\nSwitch agents to the given mode (updates agent files with the templates for this mode).\n\n**Usage:**\n\n```bash\nforge mode code\nforge mode review\n```\n\n---\n\n### `forge agent refresh`\n\nRefresh agent adapter files for the nearest branch.\n\n---\n\n### `forge services scan [branch]`\n\nScan repositories for service declarations and generate configuration with allocated ports.\n\nService declarations are read from `.forge/services.json` in each repository. You can define an optional dedicated health endpoint per service:\n\n```json\n{\n  \"services\": [\n    {\n      \"name\": \"api\",\n      \"type\": \"http\",\n      \"path\": \"/api\",\n      \"healthCheckPath\": \"/health\"\n    }\n  ]\n}\n```\n\nIf `healthCheckPath` is omitted, proxy health checks fallback to `path`, then `/`.\n\n---\n\n### `forge services list [branch]`\n\nList discovered services with their allocated ports.\n\n---\n\n### `forge env update [branch]`\n\nGenerate `.envrc` from `generated.services.json`.\n\n---\n\n### `forge env show [branch]`\n\nDisplay current `.envrc` and port allocation information.\n\n---\n\n### `forge proxy`\n\nStart a reverse-proxy server routing branches via subdomains.\n\n---\n\n### `forge maintenance rewrite-agent-files \u003cslug\u003e`\n\nRewrite all agent template files from built-in templates (overwrite).\n\n---\n\n### `forge completion \u003cshell\u003e`\n\nGenerate shell completion script (bash, zsh, fish, powershell).\n\n**Usage:**\n\n```bash\nforge completion bash\nforge completion zsh\n```\n\n---\n\n## Help\n\nFor all commands and options:\n\n```bash\nforge --help\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and contribution workflow.\n\n# License\n\n[![License: AGPL-3.0](https://img.shields.io/npm/l/feat-forge)](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flixus3d%2Ffeat-forge-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flixus3d%2Ffeat-forge-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flixus3d%2Ffeat-forge-cli/lists"}