SpecHarbor: An OpenSpec Generation Tool for Structured Workflows with AI Programming Assistants

SpecHarbor is an open-source command-line tool (CLI) designed to help developers turn vague feature ideas into structured OpenSpec specifications, task lists, and implementation prompts ready for AI agents. It addresses issues that AI programming assistants (such as GitHub Copilot, Claude Code, Cursor, Devin, etc.) face when lacking clear specification guidance—like modifying irrelevant files, ignoring project architecture, skipping tests, etc.—by providing explicit workflow guidance to improve the quality and consistency of AI outputs. Its core values include standardizing AI-assisted development workflows, promoting team collaboration, and accumulating project knowledge.

With the rapid development of AI programming assistants like GitHub Copilot, Claude Code, Cursor, Devin, etc., developers have gained powerful code generation tools but also face new challenges:

• Modifying irrelevant files: Touching files that shouldn't be modified when there are no clear boundaries
• Ignoring project architecture: Generating code inconsistent with existing styles
• Skipping tests: Forgetting to write test cases or ignoring coverage
• Inventing requirements: Making up unnecessary features on their own
• Inconsistent implementation: Discrepancies in code style, naming conventions, etc. The root cause of these issues is that AI lacks a holistic understanding of project background, architectural constraints, and requirements. SpecHarbor was born to solve these problems.

OpenSpec Core Concepts

OpenSpec is the core of SpecHarbor; it is a structured change specification format that includes the following elements:

• Change description: Clearly state what to do and why
• Scope of impact: Explicitly specify affected files/modules
• Task list: Break down into specific executable steps
• Acceptance criteria: Conditions to verify the success of the change
• Architectural constraints: Design principles and technical constraints to follow

SpecHarbor Workflow

Idea → OpenSpec change → Task list → Agent prompt → Implementation → Review → Archive This process ensures AI works under clear guidance, reducing the risk of "free-style" execution.

Supported AI Agents

SpecHarbor is compatible with various mainstream AI programming assistants, including Codex, Claude Code, Cursor, Devin, GitHub Copilot, Gemini CLI, Roo Code, Windsurf, Aider, and general agents (supporting custom configurations).

Generation Modes

• Blank mode: Minimal OpenSpec structure, suitable for teams that want full control over requirements
• Guided mode: Interactive Q&A to generate specifications, suitable for new users
• Template mode: Generate from built-in/custom templates to ensure cross-project consistency
• AI-assisted mode: Use AI to convert high-level requirements into detailed OpenSpec
• Hybrid mode: Combine project scanning, user answers, templates, and AI to generate comprehensive specifications

Command Set

• specharbor init: Initialize a project
• specharbor scan: Scan existing projects to get context
• specharbor generate: Generate OpenSpec based on description (e.g., specharbor generate "Add payment webhook with idempotency")
• specharbor prompt: Generate AI agent prompts for OpenSpec (e.g., specharbor prompt add-payment-webhook --agent codex)
• specharbor validate: Validate the completeness of OpenSpec
• specharbor review: Compare implementation with OpenSpec
• specharbor archive: Archive completed OpenSpec
• specharbor config: Configure tool settings

SpecHarbor is currently in the early development stage; the repository contains the initial project structure and the first OpenSpec change used to guide CLI development. The project is developed in Go language to ensure performance, cross-platform compatibility, and static compilation features (a single binary file without dependencies, easy to distribute and use).

Open Source Significance

• Standardize workflows: Promote the OpenSpec format and establish best practices for AI-assisted development
• Improve AI output quality: Structured specifications reduce post-review repair work
• Promote collaboration: OpenSpec serves as a "contract" between humans and AI, clarifying team collaboration
• Knowledge accumulation: Archived OpenSpec records design decisions and change history, making it easier for new members to learn

Typical Use Cases

1. New feature development: For example, adding a payment webhook, completed via the scan→generate→prompt→implement→review process
2. Code refactoring: Create a detailed OpenSpec, generate prompts in batches, execute step-by-step and verify
3. Team collaboration: Technical leads write/review OpenSpec, developers use it to guide AI implementation, and code reviews compare against the specification

Future Outlook

• IDE integration: Develop plugins for VS Code, JetBrains, etc.
• Template marketplace: Community shares OpenSpec templates for common tasks
• CI/CD integration: Incorporate OpenSpec validation into CI processes
• AI training data: Archived OpenSpec as valuable data for training smarter AI

Participation Methods

SpecHarbor uses the MIT license, allowing free use, modification, and distribution. Community members can contribute in the following ways:

• Submit Issues to report problems or suggest features
• Contribute code to implement planned features
• Share usage experiences and best practices
• Create and share OpenSpec templates