feat-forge 1.0.1

package/README.md

@@ -0,0 +1,350 @@
+# FeatForge
+
+**FeatForge** is a feature-first workflow and CLI (`forge`) to help you build software at scale, with (or without) AI agents.
+
+Its 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.
+
+With **FeatForge** you will be able to :
+
+- Parallelize work on multiple features:
+    - across multiple repositories.
+    - accross multiple agents.
+    - while keeping track of everything.
+- Come back to any feature after days/weeks and immediately understand its initial specifications.
+- Change agent configurations and prompts on a per-feature basis.
+- Switch between agents whenever you want, without losing any context or work.
+
+**FeatForge** is :
+
+- 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!
+- 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.
+- 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.
+
+**_This is an expirement, 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 accross multiple agents and repositories._**
+
+## Key Concepts
+
+- A **branch** is a self-contained unit with its own spec (`SPEC.md`) and tasks (`TODO.md`).
+- You always work inside one **active spec** (`.active-spec`) per git worktree, which can span multiple repositories.
+- Multiple modes are available per branch (see [Modes](#modes)).
+- Agents goals are always scoped to a branch, never global.
+- You can launch multiple agents per branch and work on multiple branches in parallel.
+- Finished branches are archived in `.specs/.archives/`.
+- Branch types: `anything` `feature/`, `fix/`, `release/` (each with their own customizable prefix).
+
+---
+
+## Installation
+
+```bash
+npm install -g feat-forge-cli
+forge --version
+```
+
+---
+
+## Quick Start
+
+```bash
+# Initialize FeatForge in your project
+forge init
+
+# Create a new feature (branch: feature/my-feature (customizable prefix))
+forge feature create my-feature
+
+# Start working on a feature (creates worktrees)
+forge feature start my-feature
+
+# Switch mode (updates agent files with the templates for this mode)
+forge mode code
+
+# Stop working on a feature (cleanup worktrees)
+forge feature stop my-feature
+
+# Archive a completed feature
+forge feature archive my-feature
+```
+
+---
+
+## Recommended Folder Structure
+
+Here is a typical FeatForge project layout (forge creates most folders/files automatically):
+
+```
+forge-project-root/
+  .feat-forge.json            # Configuration file for the project (per user)
+  repo1/
+    .git/                     # Git repository for repo1
+  repo2/                      # Main repo (contains .specs/)
+    .git/                     # Git repository for repo2
+    .specs/                   # All branch spec directories (created on first branch creation)
+      .archives/              # Archived branch folders (moved here when archived)
+      .template/              # Template for new branches
+        agent/                # Agent configuration templates
+          CONTEXT.spec.md     # Legacy spec mode context template
+          CONTEXT.code.md     # Legacy code mode context template
+      <branch-slug>/          # Active branch
+        SPEC.md               # Branch specification (required)
+        TODO.md               # Implementation tasks (required)
+        .forge-mode           # Current mode
+  repo3/
+    .git/                     # Git repository for repo3
+  worktrees/
+    001-bootstrap/            # Example active branch directory (created on branch start)
+      repo1/                  # git worktree for repo1 (created on branch start)
+        .active-spec -> ../repo2/.active-spec  # symlink to active spec in main repo
+      repo2/                  # git worktree for repo2 (created on branch start)
+        .active-spec -> ../.specs/001-bootstrap  # symlink to active spec in this repo
+        .specs/
+          001-bootstrap/      # actual branch folder with spec and agent context
+            .forge-mode       # current mode
+            SPEC.md           # branch specification
+            TODO.md           # implementation tasks
+      repo3/                  # git worktree for repo3 (created on branch start)
+        .active-spec -> ../repo2/.active-spec  # symlink to active spec in main repo
+```
+
+---
+
+## Modes
+
+Each branch has a mode stored in `.specs/<slug>/.forge-mode`. Switching modes updates agent adapter files with the corresponding templates.
+Agent name are useful when calling subagent
+
+Built-in modes:
+
+| Mode            | Agent                | Description                         |
+| --------------- | -------------------- | ----------------------------------- |
+| `general`       | Omnibus              | General-purpose agent               |
+| `discovery`     | Inventorius          | Explore and understand the codebase |
+| `design`        | Architecturius       | Design architecture and specs       |
+| `plan`          | Strategos            | Plan implementation strategy        |
+| `tdd`           | TestDrivenCodificius | Test-driven development             |
+| `code`          | Codificius           | Implement according to the spec     |
+| `simplify`      | Consolidarius        | Simplify and consolidate code       |
+| `review`        | Auditorix            | Review code                         |
+| `test-writer`   | TestScriptor         | Write tests                         |
+| `test-executor` | TestExecutor         | Execute tests                       |
+| `commit`        | Scribus              | Commit changes                      |
+
+Switch modes at any time:
+
+```bash
+forge mode <mode>
+```
+
+---
+
+## Command Reference
+
+### `forge init`
+
+Initialize FeatForge in your project. Interactively creates `.feat-forge.json`, scans for git repos and asks for options.
+
+**Usage:**
+
+```bash
+forge init
+```
+
+**Options:**
+
+- `--yes` / `-y` : Accept all defaults
+- `--force` / `-f` : Overwrite config (with backup)
+- `--repositories <paths>` : Comma-separated repo paths
+- `--agents <names>` : Comma-separated agent names
+- `--ides <names>` : Comma-separated IDE names
+
+---
+
+### `forge feature create <slug>`
+
+Create a new feature branch folder and initialize its spec.
+
+**Usage:**
+
+```bash
+forge feature create my-feature
+```
+
+**Options:**
+
+- `--yes` : Skip confirmation
+- `--no-branch` : Do not create a branch
+
+---
+
+### `forge feature start <slug>`
+
+Create git worktrees for all repos and set the feature as active.
+
+**Usage:**
+
+```bash
+forge feature start my-feature
+```
+
+**Options:**
+
+- `--ide <name>` : Open in specified IDE
+
+---
+
+### `forge feature list`
+
+List all active feature branches and their worktrees.
+
+**Usage:**
+
+```bash
+forge feature list
+```
+
+---
+
+### `forge feature stop <slug>`
+
+Clean up worktrees and remove the active spec symlink.
+
+**Usage:**
+
+```bash
+forge feature stop my-feature
+```
+
+---
+
+### `forge feature archive <slug>`
+
+Move a completed feature to `.specs/.archives/`.
+
+**Usage:**
+
+```bash
+forge feature archive my-feature
+```
+
+**Options:**
+
+- `--force` : Skip confirmation
+
+---
+
+### `forge feature merge <slug>`
+
+Merge a feature branch into a target branch (across all repos).
+
+---
+
+### `forge feature rebase <slug>`
+
+Rebase a feature branch onto a base branch (across all repos).
+
+---
+
+### `forge feature open [slug]`
+
+Open a feature branch in the configured IDE.
+
+---
+
+### `forge feature resync <slug>`
+
+Resync all repos to the expected branch.
+
+---
+
+### `forge fix` / `forge release` / `forge <command> branch`
+
+Same commands as `forge feature`, but with automatic `fix/` or `release/` prefix for branch names, or just plain branch names if you prefer.
+
+```bash
+forge fix create my-bugfix
+forge release create v1.2.0
+forge start dev
+```
+
+---
+
+### `forge merge <slug>` / `forge rebase <slug>`
+
+Top-level shortcuts for merge and rebase operations (across all repos).
+
+---
+
+### `forge mode <mode>`
+
+Switch agents to the given mode (updates agent files with the templates for this mode).
+
+**Usage:**
+
+```bash
+forge mode code
+forge mode review
+```
+
+---
+
+### `forge agent refresh`
+
+Refresh agent adapter files for the nearest branch.
+
+---
+
+### `forge services scan [branch]`
+
+Scan repositories for service declarations and generate configuration with allocated ports.
+
+---
+
+### `forge services list [branch]`
+
+List discovered services with their allocated ports.
+
+---
+
+### `forge env update [branch]`
+
+Generate `.envrc` from `generated.services.json`.
+
+---
+
+### `forge env show [branch]`
+
+Display current `.envrc` and port allocation information.
+
+---
+
+### `forge proxy`
+
+Start a reverse-proxy server routing branches via subdomains.
+
+---
+
+### `forge maintenance rewrite-agent-files <slug>`
+
+Rewrite all agent template files from built-in templates (overwrite).
+
+---
+
+### `forge completion <shell>`
+
+Generate shell completion script (bash, zsh, fish, powershell).
+
+**Usage:**
+
+```bash
+forge completion bash
+forge completion zsh
+```
+
+---
+
+## Help
+
+For all commands and options:
+
+```bash
+forge --help
+```

package/dist/cli.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+import 'reflect-metadata';
+// -----------
+import { Command } from 'commander';
+import { AgentCommands } from './commands/AgentCommands.js';
+import { MaintenanceCommands } from './commands/MaintenanceCommands.js';
+import { CompletionCommands } from './commands/CompletionCommands.js';
+import { FeatureCommands } from './commands/FeatureCommands.js';
+import { InitCommands } from './commands/InitCommands.js';
+import { ModeCommands } from './commands/ModeCommands.js';
+import { ForgeContext } from './foundation/ForgeContext.js';
+import { loadForgeContext } from './lib/config.js';
+import { ForgeConfig } from './foundation/ForgeConfig.js';
+import { ShellName } from './foundation/types/ShellName.js';
+import { FixCommands } from './commands/FixCommands.js';
+import { ReleaseCommands } from './commands/ReleaseCommands.js';
+import { BranchCommands } from './commands/BranchCommands.js';
+import { ForgeConfigFile } from './foundation/ForgeConfigFile.js';
+import { plainToInstance } from 'class-transformer';
+import { ServicesCommands } from './commands/ServicesCommands.js';
+import { EnvCommands } from './commands/EnvCommands.js';
+import { ProxyCommands } from './commands/ProxyCommands.js';
+// @ts-ignore
+import packageJson from '../package.json' with { type: 'json' };
+/**
+ * Register the init command on the main CLI program.
+ */
+function registerInitCommands(program) {
+    const handlers = new InitCommands();
+    program
+        .command('init')
+        .description('Create a .feat-forge.json in the current folder')
+        .option('-y, --yes', 'Accept defaults and write configuration without prompting')
+        .option('-f, --force', 'Force overwrite existing config (creates timestamped backup)')
+        .option('--non-interactive', 'Require all values via flags, no interactive prompts')
+        .option('-q, --quiet', 'Minimize console output')
+        .option('--path <dir>', 'Target directory for config file (defaults to current directory)')
+        .option('--root-dir <dir>', 'Set explicit rootDir value in config')
+        .option('--repositories <paths>', 'Repository paths (comma-separated or JSON array)')
+        .option('--agents <names>', 'Agent names (comma-separated or JSON array)')
+        .option('--ides <names>', 'IDE names (comma-separated or JSON array)')
+        .action(async (options) => {
+        await handlers.init({
+            yes: options.yes,
+            force: options.force,
+            nonInteractive: options.nonInteractive,
+            quiet: options.quiet,
+            path: options.path,
+            rootDir: options.rootDir,
+            repositories: options.repositories,
+            agents: options.agents,
+            ides: options.ides,
+        });
+    });
+}
+function genericBranchTypeCommands(baseCommand, handlers, subType = null) {
+    const argName = subType ? `${subType}` : 'branch-name';
+    const argDesc = subType ? `${subType} name (without prefix)` : 'Branch name';
+    baseCommand
+        .command('create')
+        .argument(`<${argName}>`, argDesc)
+        .description(`Create a new ${subType ? subType + ' ' : ''}branch folder and initialize its spec`)
+        .action(handlers.create.bind(handlers));
+    baseCommand
+        .command('start')
+        .argument(`<${argName}>`, argDesc)
+        .description(`Start working on a ${subType ? subType + ' ' : ''}branch : create the worktrees and necessary spec files`)
+        .action(handlers.start.bind(handlers));
+    baseCommand
+        .command('stop')
+        .argument(`<${argName}>`, argDesc)
+        .description(`Stop working on a ${subType ? subType + ' ' : ''}branch and remove its worktrees`)
+        .action(handlers.stop.bind(handlers));
+    baseCommand
+        .command('list')
+        .argument(`[prefix]`, 'Optional prefix to filter branches (e.g. "feat/")')
+        .description(`List all active ${subType ? subType + ' ' : ''}branches worktrees`)
+        .action(handlers.list.bind(handlers));
+    baseCommand
+        .command('resync')
+        .argument(`<${argName}>`, argDesc)
+        .description(`Ensure all repos in a ${subType ? subType + ' ' : ''}branch are on the correct branch (useful if user manually switched branches in a worktree)`)
+        .action(handlers.resync.bind(handlers));
+    baseCommand
+        .command('archive')
+        .argument(`<${argName}>`, argDesc)
+        .description(`Archive a ${subType ? subType + ' ' : ''}branch by moving it to .specs/.archives/`)
+        .action(handlers.archive.bind(handlers));
+    baseCommand
+        .command('open')
+        .argument(`[${argName}]`, argDesc)
+        .description(`Open the given ${subType ? subType + ' ' : ''}branch in the configured IDE (if no ${subType ? subType + ' ' : ''}branch is given, opens the nearest ${subType ? subType + ' ' : ''}branch)`)
+        .action(handlers.open.bind(handlers));
+    baseCommand
+        .command('merge')
+        .argument(`<${argName}>`, argDesc)
+        .description(`Merge a ${subType ? subType + ' ' : ''}branch into a target branch (accross all repos). It will also ask for next actions to potentially delete the branch after merge.`)
+        .action(handlers.merge.bind(handlers));
+    baseCommand
+        .command('rebase')
+        .argument(`<${argName}>`, argDesc)
+        .description(`Rebase a ${subType ? subType + ' ' : ''}branch onto a base branch (accross all repos)`)
+        .action(handlers.rebase.bind(handlers));
+}
+/**
+ * Register feature subcommands on the main CLI program.
+ */
+function registerBranchCommands(program, context) {
+    return genericBranchTypeCommands(program, new BranchCommands(context));
+}
+/**
+ * Register fix subcommands on the main CLI program.
+ */
+function registerFixCommands(program, context) {
+    const fix = program
+        .command('fix')
+        .description(`Same base commands, but with automatic "${context.options.git.fixBranchPrefix}" prefix for branch names`);
+    const handlers = new FixCommands(context);
+    return genericBranchTypeCommands(fix, handlers, 'fix');
+}
+/**
+ * Register release subcommands on the main CLI program.
+ */
+function registerReleaseCommands(program, context) {
+    const release = program
+        .command('release')
+        .description(`Same base commands, but with automatic "${context.options.git.releaseBranchPrefix}" prefix for branch names`);
+    const handlers = new ReleaseCommands(context);
+    return genericBranchTypeCommands(release, handlers, 'release');
+}
+/**
+ * Register feature subcommands on the main CLI program.
+ */
+function registerFeatureCommands(program, context) {
+    const feature = program
+        .command('feature')
+        .description(`Same base commands, but with automatic "${context.options.git.featureBranchPrefix}" prefix for branch names`);
+    const handlers = new FeatureCommands(context);
+    return genericBranchTypeCommands(feature, handlers, 'feature');
+}
+/**
+ * Register the mode commands on the main CLI program.
+ */
+function registerModeCommands(program, context) {
+    const handlers = new ModeCommands(context);
+    program
+        .command('mode')
+        .argument('<mode>', 'Mode to switch to (as defined in the config)')
+        .description('Switch agents to this mode (updates agent files with the templates for this mode)')
+        .action(handlers.setMode.bind(handlers));
+}
+/**
+ * Register agent commands on the main CLI program.
+ */
+function registerAgentCommands(program, context) {
+    const handlers = new AgentCommands(context);
+    const agent = program.command('agent').description('Manage agent adapters');
+    agent.command('refresh').description('Refresh agent adapter files for the nearest branch').action(handlers.refresh.bind(handlers));
+}
+/**
+ * Register maintenance commands on the main CLI program.
+ */
+function registerMaintenanceCommands(program, context) {
+    const handlers = new MaintenanceCommands(context);
+    const maintenance = program.command('maintenance').description('Maintenance utilities');
+    maintenance
+        .command('rewrite-agent-files <slug>')
+        .description('Rewrite all agent template files from built-in templates (overwrite)')
+        .option('--dry-run', 'Simulate changes without writing files')
+        .option('--commit', 'Commit changes if files are written')
+        .action(async (slug, opts) => {
+        await handlers.installAgentTemplateLocally({ dryRun: opts.dryRun, commit: opts.commit });
+    });
+}
+/**
+ * Register services commands on the main CLI program.
+ */
+function registerServicesCommands(program, context) {
+    const handlers = new ServicesCommands(context);
+    const services = program.command('services').description('Manage service declarations and configurations');
+    services
+        .command('scan')
+        .argument('[branch-name]', 'Optional branch name (defaults to current branch)')
+        .description('Scan repositories for .forge/services.json and generate configuration with allocated ports')
+        .action(handlers.scan.bind(handlers));
+    services
+        .command('list')
+        .option('--json', 'Output as JSON')
+        .argument('[branch-name]', 'Optional branch name (defaults to current branch)')
+        .description('List discovered services with their allocated ports')
+        .action((branch, options) => {
+        const format = options.json ? 'json' : 'default';
+        handlers.list(format);
+    });
+}
+/**
+ * Register environment commands on the main CLI program.
+ */
+function registerEnvCommands(program, context) {
+    const handlers = new EnvCommands(context);
+    const env = program.command('env').description('Manage environment configuration');
+    env.command('update')
+        .argument('[branch-name]', 'Optional branch name (defaults to current branch)')
+        .description('Generate .envrc from generated.services.json')
+        .action(handlers.update.bind(handlers));
+    env.command('show')
+        .argument('[branch-name]', 'Optional branch name (defaults to current branch)')
+        .description('Display current .envrc and port allocation information')
+        .action(handlers.show.bind(handlers));
+}
+/**
+ * Register proxy commands on the main CLI program.
+ */
+function registerProxyCommands(program, context) {
+    const handlers = new ProxyCommands(context);
+    program
+        .command('proxy')
+        .description('Start a reverse-proxy server routing branches via subdomains')
+        .option('--port <port>', 'Override proxy port')
+        .action(async (options) => {
+        await handlers.start(options);
+    });
+}
+/*
+ * Register completion commands with the CLI.
+ * This command works both with and without config.
+ */
+function registerCompletionCommands(program, context) {
+    const handlers = context ? new CompletionCommands(context, program) : null;
+    const validShells = [ShellName.Bash, ShellName.Zsh, ShellName.Fish, ShellName.PowerShell, ShellName.Pwsh];
+    function isValidShellName(value) {
+        return validShells.includes(value);
+    }
+    program
+        .command('completion <shell>')
+        .description(`Generate shell completion script (${validShells.join(', ')})`)
+        .action(async (shell) => {
+        // Validate shell type
+        if (!isValidShellName(shell)) {
+            console.error(`Error: Unsupported shell type "${shell}". Supported shells: ${validShells.join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        // For completion command, we need config to get worktrees path
+        // If no config, we'll use a fallback implementation
+        if (!handlers) {
+            const cwd = process.cwd();
+            const fallbackConfigFile = plainToInstance(ForgeConfigFile, { repositories: ['dummy'] });
+            const fallbackContext = new ForgeContext(cwd, new ForgeConfig(cwd, fallbackConfigFile));
+            const fallbackHandlers = new CompletionCommands(fallbackContext, program);
+            await fallbackHandlers.generate(shell);
+        }
+        else {
+            await handlers.generate(shell);
+        }
+    });
+}
+/**
+ * Entry point for the forge CLI.
+ */
+async function main() {
+    const program = new Command();
+    program.name('forge').description('Feat-Forge workflow CLI').version(packageJson.version);
+    // Init command doesn't need config
+    registerInitCommands(program);
+    // Completion command should work with or without config
+    // Register it early so it's available even without .feat-forge.json
+    let context;
+    // Load config for other commands
+    const isInitCommand = process.argv[2] === 'init';
+    const isCompletionCommand = process.argv[2] === 'completion';
+    if (!isInitCommand) {
+        try {
+            context = await loadForgeContext();
+        }
+        catch (error) {
+            // Config not found
+            if (isCompletionCommand) {
+                // Allow completion to work without config (using fallback)
+                registerCompletionCommands(program);
+            }
+            else {
+                throw error;
+            }
+        }
+        if (context) {
+            // Register commands that require config
+            registerBranchCommands(program, context);
+            registerFeatureCommands(program, context);
+            registerFixCommands(program, context);
+            registerReleaseCommands(program, context);
+            registerModeCommands(program, context);
+            registerAgentCommands(program, context);
+            registerMaintenanceCommands(program, context);
+            registerServicesCommands(program, context);
+            registerEnvCommands(program, context);
+            registerProxyCommands(program, context);
+            registerCompletionCommands(program, context);
+        }
+    }
+    await program.parseAsync(process.argv);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+});

package/dist/commands/AbstractCommands.js

@@ -0,0 +1,16 @@
+/**
+ * Base class for command handlers with required configuration.
+ */
+export class AbstractCommands {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    async verifyCleanBranch(branchContext) {
+        const dirtyRepos = await branchContext.getDirtyRepositories();
+        if (dirtyRepos.length > 0) {
+            const repoNames = dirtyRepos.map((repo) => repo.name).join(', ');
+            throw new Error(`Worktree is not clean in: ${repoNames}.\n` + `Please commit or stash your changes before proceeding.`);
+        }
+    }
+}

package/dist/commands/AgentCommands.js

@@ -0,0 +1,14 @@
+import { BranchContext } from '../foundation/BranchContext.js';
+import { AbstractCommands } from './AbstractCommands.js';
+export class AgentCommands extends AbstractCommands {
+    // ============================================================================
+    // PUBLIC COMMAND METHODS
+    // ============================================================================
+    /**
+     * Refresh agent adapter files for the active branch using current mode.
+     */
+    async refresh() {
+        const branchContext = await BranchContext.findNearestBranchContext(this.context);
+        await branchContext.refreshAgentContextFiles();
+    }
+}