"Get started" section doesn't show `specify init .` option for initializing in current directory

[fhemmerrelias]

"Get started" section doesn't show specify init . option for initializing in current directory

Problem (User Journey)

Following the "Get started" section in the README to set up Spec Kit I noticed the following:

In the "1. Install Specify" section, after installing the tool, the example immediately shows:

specify init <PROJECT_NAME>
specify check

This presents only the "create new project directory" syntax. I naturally assume this is the only way to initialize a project and that I must create a new directory.

However, the ability to initialize in the current directory using specify init . (or specify init --here) is an equally important option that many users need, especially when:

• Working with existing projects (brownfield development, which the README explicitly supports)
• Adding Spec Kit to an already-created directory
• Following mono-repo workflows

This alternative syntax is only documented much later in two places:

1. The "🔧 Specify CLI Reference" section (which users may not read if they just want to get started quickly)
2. The expandable "📋 Detailed process" section

By the time users discover this option exists, they may have already created an unnecessary wrapper directory or abandoned trying to use Spec Kit with their existing project.

Current Documentation

"Get started" section currently shows:

Then use the tool directly:

specify init <PROJECT_NAME>
specify check

CLI Reference section (much later) shows:

# Initialize in current directory
specify init . --ai copilot
# or use the --here flag
specify init --here --ai copilot

Suggestion

Update the "Get started" section to show both options upfront, similar to how the detailed section presents them. This would immediately make users aware of their choices at the critical first step.

Proposed change for the "Get started" → "1. Install Specify" section:

Then use the tool directly:

# Create a new project directory
specify init <PROJECT_NAME>

# Or initialize in current directory
specify init .

# Check installed tools
specify check

This small change would:

• ✅ Prevent confusion for users with existing projects
• ✅ Make the brownfield use case more discoverable upfront
• ✅ Align with user expectations (many CLI tools show common usage patterns early)
• ✅ Reduce friction for adoption in existing codebases

Related Context

• Issue Initialize specify within existing project #52 discussed the feature implementation and included requests to make this clearer in documentation
• The README's "Development phases" section explicitly mentions "Iterative Enhancement (Brownfield)" as a supported use case, but this isn't obvious from the quick start

AI Assistance Disclosure

This issue was identified and drafted with assistance from GitHub Copilot, but was validated by manual review of the README structure and comparison with the user experience.

[fsilvaortiz]

Hi! It looks like this issue has already been addressed by commit 236bcb3 ("docs: Add existing project initialization to getting started", Dec 4 2025).

The "Get started" section in the README now shows both options:

# Create new project
specify init <PROJECT_NAME>

# Or initialize in existing project
specify init . --ai claude
# or
specify init --here --ai claude

This matches the proposed change in this issue. This issue can likely be closed.

AI Assistance Disclosure: This comment was drafted with assistance from Claude Code (Anthropic).