[Feature]: Consolidate all flowspec configuration files into .flowspec directory

[behnamnikbakht]

Problem Statement

Flowspec configuration files are currently scattered across 15+ directories in the project root, making it difficult to:

• Understand what belongs to flowspec vs. project-specific files
• Set up flowspec in new projects (requires copying multiple directories)
• Manage flowspec upgrades (no single location to update)
• Configure gitignore rules for flowspec-generated artifacts

Proposed Solution

Consolidate all flowspec-related files into a single .flowspec directory:

.flowspec/
├── .version # Version manifest
├── workflow.yml # State machine (from flowspec_workflow.yml)
│
├── agents/ # From .github/agents/
│ ├── flow.assess.agent.md
│ ├── flow.specify.agent.md
│ ├── flow.plan.agent.md
│ ├── flow.implement.agent.md
│ ├── flow.validate.agent.md
│ └── flow.submit-n-watch-pr.agent.md
│
├── commands/ # From commands/
│ ├── flow/
│ └── vibe/
│
├── constitutions/ # From constitutions/
│
├── github/ # From github/
│ ├── ISSUE_TEMPLATE/
│ └── workflows/
│
├── github-actions/ # From github-actions/
│
├── hooks/ # Existing
│ ├── hooks.yaml
│ └── *.sh
│
├── logs/ # Merged from .flowspec/logs/ and logs/
│ ├── active-work/
│ ├── decisions/
│ └── events/
│
├── memory/ # From memory/
│ ├── constitution.md
│ └── repo-facts.md
│
├── partials/ # From partials/
│ └── flow/
│
├── pre-commit/ # From pre-commit/
│
├── security-rules/ # From security-rules/
│ ├── javascript/
│ └── python/
│
├── skills/ # From skills/
│ ├── architect/
│ ├── constitution-checker/
│ ├── context-extractor/
│ ├── pm-planner/
│ ├── qa-validator/
│ ├── security-fixer/
│ ├── security-reporter/
│ ├── security-reviewer/
│ └── security-workflow/
│
├── templates/ # From docs/prp/
│ └── prp-base-flowspec.md
│
└── vscode/ # From .vscode/ and vscode/
└── settings.json

Use Cases

1. New Project Setup

Before: Copy 15+ directories and files, hope nothing is missed, manually verify structure.
After: cp -r /path/to/flowspec-template/.flowspec . or flowspec init

2. Gitignore Management

Before: Multiple gitignore entries for different flowspec directories.
After: Single rule like .flowspec/logs/ for generated content

3. Multi-Tool Projects

Before: Flowspec directories mixed with other tooling
After: Clear separation - .flowspec/ is flowspec, everything else is project or other tools

4. Project Cleanup / Removal

Before: Hunt through project to remove all flowspec artifacts.
After: rm -rf .flowspec removes everything

Alternatives Considered

No response

Priority

Medium - Would improve my workflow

Related Backlog Task

No response

Contribution

• I am willing to contribute this feature myself
• I can help test this feature when implemented
• I can help write documentation for this feature

[jpoley]

flowspec can't change where the tools use their commands from. users shouldn't need to change flowspec commands? what are you hoping to change / do?

[behnamnikbakht]

@jpoley Thanks for your reply.

If Flowspec can’t modify the location, it might be possible to avoid generating all files by default. For example, when a user sets up a project with Copilot, it also creates Claude-related files (on Windows PowerShell):

flowspec init my-project-with-flowspec --ai copilot
cd my-project-with-flowspec
ls *claude*

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----          2/5/2026  11:44 AM                .claude
-a----          2/5/2026  11:41 AM            449 claude-md-template.md
-a----          2/5/2026  11:44 AM              0 CLAUDE.md

[jpoley]

yes the fix is only install the ones you want when doing flowspec init . (it should ask you)