How to Suggest a New Feature for Freebuff: The Complete Contributor Workflow

Freebuff accepts feature suggestions through GitHub Issues using the Feature Request template, but code contributions must remain within scoped directories like cli/, sdk/, agents/, packages/agent-runtime/, packages/code-map/, and scripts/tmux/, with PRs undergoing automated structural validation before maintainers port changes to the private upstream repository.

Freebuff is an open-source project hosted at CodebuffAI/freebuff that welcomes community feature ideas, though it operates as a public mirror of a private upstream repository. To suggest a new feature for Freebuff effectively, contributors must follow a specific workflow that ensures proposals are properly documented, scoped correctly, and compatible with the automated porting system that syncs changes between repositories.

Phase 1: Proposal and Discovery

Search Existing Issues

Before creating a new request, browse the open issues in the CodebuffAI/freebuff repository to verify your idea has not been proposed. Filter the issue tracker by the feature label to identify existing suggestions that match your concept.

Create a Feature Request Issue

If your idea is novel, open a new issue and select the Feature Request template. According to the CONTRIBUTING.md guidelines, your description must include:

• A concise, descriptive title stating the feature clearly.
• Detailed motivation explaining why the feature is needed and who benefits.
• A high-level design sketch or example usage, with optional code snippets.
• Analysis of potential impact on existing functionality, particularly if modifying core areas such as cli/, sdk/, or agents/.

Phase 2: Development Preparation

Verify Contribution Scope

Freebuff restricts public contributions to specific directories to maintain the integrity of the private upstream system. You may only modify files within:

• cli/
• sdk/
• common/
• agents/
• packages/agent-runtime/
• packages/code-map/
• scripts/tmux/

Contributions adding new backend services, database schemas, billing logic, or secret-management code are explicitly prohibited in the public mirror. Consult the Public Contributions section of CONTRIBUTING.md for the complete list of permissible paths.

Set Up Local Development Environment

Clone the repository and install dependencies using the Bun runtime:

bun install

After making changes, compile the project using the provided build scripts:

bun run build:sdk
bun run build:freebuff

Phase 3: Implementation and Testing

Write Code and Tests

Develop your feature within the scoped directories. For example, when adding a new CLI flag like --dry-run, you would extend cli/src/commands/* to accept the option. The implementation must handle the flag appropriately:

diff --git a/cli/src/commands/deploy.ts b/cli/src/commands/deploy.ts
@@ -5,6 +5,7 @@ import { Command } from 'commander';
 
 export const deploy = new Command('deploy')
   .description('Deploy agents to the cloud')
+  .option('--dry-run', 'Show actions without executing')
   .action(async (opts) => {
-    await performDeployment();
+    if (opts.dryRun) {
+      console.log('[dry-run] Would perform deployment');
+      return;
+    }
+    await performDeployment();
   });

Write unit tests for any new public APIs or CLI commands. Freebuff's test suite runs automatically on pull-request creation. Place tests appropriately, such as in cli/src/__tests__/dry-run.test.ts for CLI functionality. Consult docs/testing.md for detailed instructions on running the test suite locally.

Phase 4: Submission and Review

Submit a Pull Request

Submit your change as a PR against the public repository. Your PR must:

• Stick to the scoped paths listed above.
• Include a clear title and description that repeats the motivation from the issue.
• Provide a brief summary of the implementation approach.

Navigate Automated Checks

A bot runs three automated structural checks (title, description, and scope) a few seconds after the PR is opened. These checks validate that your contribution adheres to formatting rules and directory restrictions. If any check fails, edit the PR until they succeed; failing checks block merging.

Maintainer Review and Porting

Since the public repository is a read-only mirror, maintainers do not merge PRs directly into it. Instead, they port accepted changes into the private source tree. The next export sync will bring the updated code back into the public view.

Handle Revisions and Follow-up

If a maintainer closes your PR, they will leave a comment explaining the reasoning. Closed PRs are not final rejections. You can reply to address concerns and request the PR be reopened after clarification.

Summary

• Freebuff accepts feature suggestions via GitHub Issues using the Feature Request template, requiring detailed motivation and design sketches.
• Contributions must remain within scoped directories: cli/, sdk/, common/, agents/, packages/agent-runtime/, packages/code-map/, and scripts/tmux/.
• Local development requires bun install and build commands bun run build:sdk and bun run build:freebuff.
• All PRs must pass three automated structural checks (title, description, scope) before maintainer review.
• Accepted changes are ported to the private upstream repository rather than merged directly in the public mirror.

Frequently Asked Questions

What directories can I contribute to in Freebuff?

According to the CONTRIBUTING.md source file, public contributions are limited to cli/, sdk/, common/, agents/, packages/agent-runtime/, packages/code-map/, and scripts/tmux/. These directories contain the CLI tooling, SDK libraries, and agent runtime code that are safe for community modification. Adding backend services or database schemas is not permitted.

Why won't my PR be merged directly into the public repository?

The CodebuffAI/freebuff repository operates as a public mirror of a private upstream repository. Because of this architecture, maintainers port accepted changes into the private source tree rather than merging PRs directly. The changes then appear in the public mirror during the next scheduled sync.

What are the three automated structural checks for PRs?

The automated validation system checks three specific structural elements: the PR title format, the description completeness, and whether the changed files remain within the permitted contribution scope (directories). These checks run automatically seconds after PR creation and block merging until all criteria pass.

Can I suggest features that require new backend services?

No. The source code analysis explicitly prohibits contributions that add new backend services, database schemas, billing logic, or secret-management code in the public mirror. While you can suggest these features via Issues, the implementation must be handled by internal maintainers due to security and architectural constraints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}