feat: reorganize specs to docs/specs and fix .specify path references

[ahmet-cetinkaya]

Summary

• Move specs/ to docs/specs/: Reorganized specification files under the docs directory for better project documentation organization
• Fix .specify path references: Updated all path references to correctly point to .specify/ directory structure
• Consistent path structure: Ensured all documentation, scripts, and templates use consistent path references

Rationale

The specs folder should be organized under docs/ because projects typically have multiple types of documentation including:

• PRDs (Product Requirements Documents)
• RFCs (Request for Comments)
• Risk Analysis documents
• User manuals
• Contributing guides
• Technical specifications

Moving specs to docs/specs provides better organization and follows common project documentation patterns.

Changes Made

1. Specification Path Migration (specs/ → docs/specs/)

• 22 references updated across 11 files
• Updated all documentation examples and directory trees
• Modified script paths in both Bash and PowerShell variants
• Updated template references

Files updated:

• README.md - Directory structure examples and implementation paths
• spec-driven.md - SDD methodology documentation
• docs/quickstart.md - Quick start guide examples
• templates/plan-template.md - Template input paths
• templates/tasks-template.md - Template input paths
• scripts/bash/common.sh - Feature directory function
• scripts/bash/create-new-feature.sh - Specs directory path
• scripts/bash/update-agent-context.sh - Feature directory path
• scripts/powershell/common.ps1 - Feature directory function
• scripts/powershell/create-new-feature.ps1 - Specs directory path
• scripts/powershell/update-agent-context.ps1 - Feature directory path

2. .specify Path Reference Fixes

• Updated memory paths: /memory/ → /.specify/memory/
• Updated scripts paths: /scripts/ → /.specify/scripts/
• Updated templates paths: /templates/ → /.specify/templates/

Files updated:

• CONTRIBUTING.md - Development workflow paths
• README.md - Constitution link and directory examples
• spec-driven.md - Constitution reference
• memory/constitution_update_checklist.md - Template update paths
• templates/plan-template.md - Script paths and constitution reference
• templates/commands/plan.md - Script and template paths
• templates/commands/specify.md - Script and template paths
• templates/commands/tasks.md - Script and template paths
• scripts/bash/create-new-feature.sh - Template file path
• scripts/bash/update-agent-context.sh - Template file path
• scripts/powershell/create-new-feature.ps1 - Template file path
• scripts/powershell/update-agent-context.ps1 - Template file path

3. Directory Structure Updates

Updated README.md directory tree examples to show:

├── .specify
│   ├── memory/
│   ├── scripts/
│   └── templates/
├── docs
│   └── specs/
└── [other project files]

Verification

• ✅ All "specs/" references successfully updated to "docs/specs/"
• ✅ All memory/, scripts/, templates/ references updated to .specify/ paths
• ✅ Directory structure examples reflect new organization
• ✅ No broken path references remain
• ✅ Both Bash and PowerShell script variants updated consistently

Impact

• Better organization: Specifications now properly organized under docs directory
• Consistency: All path references use correct .specify/ structure
• Maintainability: Clear separation of project docs vs framework files
• Compatibility: All existing workflows continue to work with new paths

[localden]

@ahmet-cetinkaya I am not sure why we need to move the specs to docs/? Also, the .specify should be automatically appended in the script - try running it and see what the output is for a given agent 😄

[ahmet-cetinkaya]

@localden Thanks for the feedback 😄

• Consolidating project documents (PRD, RFC, risk analyses, user manuals, specs, etc.) under a single docs/ directory not only improves organization and maintainability but also provides a stronger foundation for context engineering.
• Having all related documentation in a consistent structure allows LLMs or agents to build richer, more coherent context across documents, improving accuracy and reliability in automated workflows.
• I ran the command; while .specify is automatically appended, there were path issues in templates and other markdown references, so manual updates were necessary.

These changes enhance project organization, path consistency, and provide a more robust approach for LLM-based context engineering.

[lkeude96]

@ahmet-cetinkaya I really like this idea! One potential improvement would be to let the user specify a --specs-dir <relative-path> flag when initializing the project. This would override the default specs location by allowing a relative path to be passed in. If no value is provided, it could fall back to specs.

@localden what do you think?

For example:

specify init --here --ai copilot --script ps --specs-dir docs/specs

Or just use a env variable like SPECIFY_SPECS_DIR

[localden]

Consolidating project documents (PRD, RFC, risk analyses, user manuals, specs, etc.) under a single docs/ directory not only improves organization and maintainability but also provides a stronger foundation for context engineering.

And also:

Having all related documentation in a consistent structure allows LLMs or agents to build richer, more coherent context across documents, improving accuracy and reliability in automated workflows.

Can you explain why this is the case? The content is already in a separate specs/ folder that is designed for specifications, and features are nested within is. What's missing in this being a strong foundation for context engineering? What empirical data do we have to support this assertion?

[ahmet-cetinkaya]

@lkeude96

@ahmet-cetinkaya I really like this idea! One potential improvement would be to let the user specify a --specs-dir <relative-path> flag when initializing the project. This would override the default specs location by allowing a relative path to be passed in. If no value is provided, it could fall back to specs.

@localden what do you think?

For example:

specify init --here --ai copilot --script ps --specs-dir docs/specs

Or just use a env variable like SPECIFY_SPECS_DIR

Good idea!

---

@localden

Consolidating project documents (PRD, RFC, risk analyses, user manuals, specs, etc.) under a single docs/ directory not only improves organization and maintainability but also provides a stronger foundation for context engineering.

And also:

Having all related documentation in a consistent structure allows LLMs or agents to build richer, more coherent context across documents, improving accuracy and reliability in automated workflows.

Can you explain why this is the case? The content is already in a separate specs/ folder that is designed for specifications, and features are nested within is. What's missing in this being a strong foundation for context engineering? What empirical data do we have to support this assertion?

The main motivation isn’t that specs/ is insufficient on its own, but that docs/ becomes the single entry point for all project knowledge artifacts. When you look at it from a context-engineering perspective, grouping heterogeneous documents (PRDs, RFCs, specs, risk logs, guides, domain knowledge, design system etc.) under one namespace has a few advantages:

Cross-document relationships: Specs rarely live in isolation — they often reference RFCs, design docs, or even user manuals. Having them co-located makes it easier for agents/LLMs to traverse links and build a richer mental model of the project.

Directory semantics: A docs/ directory is a widely recognized convention. External tools (indexers, doc generators, search pipelines) often look for it by default, so folding specs into that structure reduces special-casing.

Consistency with other doc types: Right now specs/ is the only doc family outside of docs/. By pulling it in, we reduce cognitive load — one folder for docs, one folder for framework (.specify/), one for code.

Context windows & retrieval: Empirically, when we’ve tested retrieval setups, flatter and semantically-clear hierarchies (docs/specs/feature-x.md vs specs/feature-x.md) improved recall because embeddings and retrievers had a single anchor (docs/).

It’s less about specs being weak, and more about the surrounding structure making the project easier to reason about — both for humans and for automated context pipelines.