SpecFact CLI Directory Structure

This document defines the canonical directory structure for SpecFact CLI artifacts.

This page covers runtime and workspace artifact layout under .specfact/. Source-repository ownership is now split:

• specfact-cli: lean runtime, registry, shared contracts, adapters, docs site
• specfact-cli-modules: official workflow bundle source packages and registry publishing automation

Use this document for repository-local artifact placement. Use Module Development and Publishing modules for source/package layout.

Primary Use Case: SpecFact CLI is designed for brownfield code modernization - reverse-engineering existing codebases into documented specs with runtime contract enforcement. The directory structure reflects this brownfield-first approach.

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

Overview

All SpecFact artifacts are stored under .specfact/ in the repository root. This ensures:

• Consistency: All artifacts in one predictable location
• Multiple plans: Support for multiple plan bundles in a single repository
• Gitignore-friendly: Easy to exclude reports from version control
• Clear separation: Plans (versioned) vs reports (ephemeral)
• CLI-first: All artifacts are local, no cloud storage required

User-level debug logs: When you run with --debug, the CLI also writes a rotating debug log under your home directory: ~/.specfact/logs/specfact-debug.log. This is separate from repo-level .specfact/ and is used only for global debug output. See Debug Logging.

User-level registry (v0.27+): After you run specfact init, the CLI creates ~/.specfact/registry/ with:

• commands.json – Command names and help text used for fast root specfact --help without loading every command module.
• modules.json – Per-module state (id, version, enabled) for optional module packages.
  • Managed by specfact module ... commands (init, list, install, enable, disable, uninstall, upgrade)
  • Supports dependency-safe lifecycle operations with optional --force cascading behavior

specfact init is bootstrap-focused; module lifecycle is canonical under specfact module. IDE prompt/template setup is handled by specfact init ide.

Module artifact roots:

• Canonical per-user module root: <user-home>/.specfact/modules
• Optional workspace-local module root: <repo>/.specfact/modules
• Module denylist file: <user-home>/.specfact/module-denylist.txt (override with SPECFACT_MODULE_DENYLIST_FILE)
• Trusted non-official publisher decisions are stored in <user-home>/.specfact/metadata.json
• SpecFact does not auto-discover <repo>/modules to avoid assuming ownership of non-.specfact repository paths.
• In repository context, <repo>/.specfact/modules has higher discovery precedence than <user-home>/.specfact/modules.

For how the CLI discovers and loads commands from module packages (registry, module-package.yaml, lazy loading), see Architecture – Command Registry and Module System.

Source repository layout

Post-migration, implementation is split across two repositories:

specfact-cli/
  src/specfact_cli/
  docs/
  openspec/
  tests/

specfact-cli-modules/
  packages/specfact-project/
  packages/specfact-backlog/
  packages/specfact-codebase/
  packages/specfact-spec/
  packages/specfact-govern/
  registry/

The runtime loads bundle packages through manifests and registry metadata; it does not treat the source repositories themselves as runtime module roots.

Canonical Structure

.specfact/
├── config.yaml              # SpecFact configuration (optional)
├── config/                  # Global configuration (optional)
│   ├── bridge.yaml          # Bridge configuration for external tools
│   └── ...
├── cache/                   # Shared cache (gitignored, global for performance)
│   ├── dependency-graph.json
│   └── commit-history.json
├── projects/                # Modular project bundles (versioned in git)
│   ├── <bundle-name>/       # Project bundle directory
│   │   ├── bundle.manifest.yaml  # Bundle metadata, versioning, and checksums
│   │   ├── idea.yaml             # Product vision (optional)
│   │   ├── business.yaml         # Business context (optional)
│   │   ├── product.yaml          # Releases, themes (required)
│   │   ├── clarifications.yaml   # Clarification sessions (optional)
│   │   ├── sdd.yaml              # SDD manifest (bundle-specific, Phase 8.5)
│   │   ├── tasks.yaml            # Task breakdown (bundle-specific, Phase 8.5)
│   │   ├── features/             # Individual feature files
│   │   │   ├── FEATURE-001.yaml
│   │   │   ├── FEATURE-002.yaml
│   │   │   └── ...
│   │   ├── contracts/            # OpenAPI contracts (bundle-specific)
│   │   │   └── ...
│   │   ├── protocols/            # FSM protocols (bundle-specific)
│   │   │   └── ...
│   │   ├── reports/              # Bundle-specific reports (gitignored, Phase 8.5)
│   │   │   ├── brownfield/
│   │   │   │   └── analysis-2025-10-31T14-30-00.md
│   │   │   ├── comparison/
│   │   │   │   └── report-2025-10-31T14-30-00.md
│   │   │   ├── enrichment/
│   │   │   │   └── <bundle-name>-2025-10-31T14-30-00.enrichment.md
│   │   │   └── enforcement/
│   │   │       └── report-2025-10-31T14-30-00.yaml
│   │   ├── logs/                 # Bundle-specific logs (gitignored, Phase 8.5)
│   │   │   └── 2025-10-31T14-30-00.log
│   │   └── prompts/              # AI IDE contract enhancement prompts (optional)
│   │       └── enhance-<filename>-<contracts>.md
│   ├── legacy-api/         # Example: Brownfield-derived bundle
│   │   ├── bundle.manifest.yaml
│   │   ├── product.yaml
│   │   ├── sdd.yaml
│   │   ├── tasks.yaml
│   │   ├── features/
│   │   ├── reports/
│   │   └── logs/
│   └── my-project/          # Example: Main project bundle
│       ├── bundle.manifest.yaml
│       ├── idea.yaml
│       ├── business.yaml
│       ├── product.yaml
│       ├── sdd.yaml
│       ├── tasks.yaml
│       ├── features/
│       ├── reports/
│       └── logs/
└── gates/                   # Enforcement configuration (global)
    └── config.yaml          # Enforcement settings (versioned)

Directory Purposes

.specfact/projects/ (Versioned)

Purpose: Store modular project bundles that define the contract for the project.

Guidelines:

• Each project bundle is stored in its own directory: .specfact/projects/<bundle-name>/
• Each bundle directory contains multiple aspect files:
  • bundle.manifest.yaml - Bundle metadata, versioning, checksums, and feature index (required)
    • Schema Versioning: Set schema_metadata.schema_version to "1.1" to enable change tracking (v0.21.1+)
    • Change Tracking (v1.1+): Optional change_tracking and change_archive fields are loaded via bridge adapters (not stored in bundle directory)
      • change_tracking: Active change proposals and feature deltas (loaded from external tools like OpenSpec)
      • change_archive: Completed changes with audit trail (loaded from external tools)
      • Both fields are optional and backward compatible - v1.0 bundles work without them
    • See Schema Versioning for details
  • product.yaml - Product definition with themes and releases (required)
  • idea.yaml - Product vision and intent (optional)
  • business.yaml - Business context and market segments (optional)
  • clarifications.yaml - Clarification sessions and Q&A (optional)
  • sdd.yaml - SDD manifest (bundle-specific, Phase 8.5, versioned)
  • tasks.yaml - Task breakdown (bundle-specific, Phase 8.5, versioned)
  • features/ - Directory containing individual feature files:
    • FEATURE-001.yaml - Individual feature with stories
    • FEATURE-002.yaml - Individual feature with stories
    • Each feature file is self-contained with its stories, acceptance criteria, etc.
  • contracts/ - OpenAPI contract files (bundle-specific, versioned)
  • protocols/ - FSM protocol definitions (bundle-specific, versioned)
  • reports/ - Bundle-specific analysis reports (gitignored, Phase 8.5)
  • logs/ - Bundle-specific execution logs (gitignored, Phase 8.5)
• Always committed to git - these are the source of truth (except reports/ and logs/)
• Phase 8.5: All bundle-specific artifacts are stored within bundle folders for better isolation
• Use descriptive bundle names: legacy-api, my-project, feature-auth
• Supports multiple bundles per repository for brownfield modernization, monorepos, or feature branches
• Aspect files are YAML format (JSON support may be added in future)

Plan Bundle Structure:

Plan bundles are YAML (or JSON) files with the following structure:

version: "1.1"  # Schema version (current: 1.1)

metadata:
  stage: "draft"  # draft, review, approved, released
  summary:  # Summary metadata for fast access (added in v1.1)
    features_count: 5
    stories_count: 12
    themes_count: 2
    releases_count: 1
    content_hash: "abc123def456..."  # SHA256 hash for integrity
    computed_at: "2025-01-15T10:30:00"

idea:
  title: "Project Title"
  narrative: "Project description"
  # ... other idea fields

product:
  themes: ["Theme1", "Theme2"]
  releases: [...]

features:
  - key: "FEATURE-001"
    title: "Feature Title"
    stories: [...]
    # ... other feature fields

Bundle Manifest Structure (bundle.manifest.yaml):

The bundle.manifest.yaml file contains bundle metadata and (in v1.1+) optional change tracking fields:

schema_metadata:
  schema_version: "1.1"  # Set to "1.1" to enable change tracking (v0.21.1+)
  project_version: "0.1.0"

# ... other manifest fields (checksums, feature index, etc.)

# Optional change tracking fields (v1.1+, loaded via bridge adapters)
change_tracking: null  # Optional - loaded via bridge adapters (not stored in bundle directory)
change_archive: []     # Optional - list of archived changes (not stored in bundle directory)

Note: The change_tracking and change_archive fields are optional and loaded dynamically via bridge adapters (e.g., OpenSpec adapter) rather than being stored directly in the bundle directory. This allows change tracking to be managed by external tools while keeping bundles tool-agnostic. See Schema Versioning for details.

Summary Metadata (v1.1+):

Plan bundles version 1.1 and later include summary metadata in the metadata.summary section. This provides:

• Fast access: Read plan counts without parsing entire file (44% faster performance)
• Integrity verification: Content hash detects plan modifications
• Performance optimization: Only reads first 50KB for large files (>10MB)

Upgrading Plan Bundles:

Use specfact project regenerate to re-derive project state from the current bundle:

# Re-derive project state
specfact project regenerate --bundle <bundle-name>

See the Command Reference for details.

Example:

.specfact/projects/
├── my-project/                    # Primary project bundle
│   ├── bundle.manifest.yaml       # Metadata, checksums, feature index
│   ├── idea.yaml                  # Product vision
│   ├── business.yaml              # Business context
│   ├── product.yaml               # Themes and releases
│   ├── features/                  # Individual feature files
│   │   ├── FEATURE-001.yaml
│   │   ├── FEATURE-002.yaml
│   │   └── FEATURE-003.yaml
│   └── prompts/                   # AI IDE contract enhancement prompts (optional)
│       └── enhance-<filename>-<contracts>.md
├── legacy-api/                    # ⭐ Reverse-engineered from existing API (brownfield)
│   ├── bundle.manifest.yaml
│   ├── product.yaml
│   ├── features/
│   │   ├── FEATURE-AUTH.yaml
│   │   └── FEATURE-PAYMENT.yaml
│   └── prompts/                   # Bundle-specific prompts (avoids conflicts)
│       └── enhance-<filename>-<contracts>.md
├── legacy-payment/                 # ⭐ Reverse-engineered from existing payment system (brownfield)
│   ├── bundle.manifest.yaml
│   ├── product.yaml
│   └── features/
│       └── FEATURE-PAYMENT.yaml
└── feature-auth/                   # Auth feature bundle
    ├── bundle.manifest.yaml
    ├── product.yaml
    └── features/
        └── FEATURE-AUTH.yaml

.specfact/protocols/ (Versioned)

Purpose: Store FSM (Finite State Machine) protocol definitions.

Guidelines:

• Define valid states and transitions
• Always committed to git
• Used for workflow validation

Example:

.specfact/protocols/
├── development-workflow.protocol.yaml
└── deployment-pipeline.protocol.yaml

Bundle-Specific Artifacts (Phase 8.5)

Phase 8.5 Update: All bundle-specific artifacts are now stored within .specfact/projects/<bundle-name>/ folders for better isolation and organization.

Bundle-Specific Artifacts:

• Reports: .specfact/projects/<bundle-name>/reports/ (gitignored)
  • brownfield/ - Brownfield analysis reports
  • comparison/ - Plan comparison reports
  • enrichment/ - LLM enrichment reports
  • enforcement/ - SDD enforcement validation reports
• SDD Manifests: .specfact/projects/<bundle-name>/sdd.yaml (versioned)
• Tasks: .specfact/projects/<bundle-name>/tasks.yaml (versioned)
• Logs: .specfact/projects/<bundle-name>/logs/ (gitignored)

Migration: Use specfact project migrate artifacts to move existing artifacts from global locations to bundle-specific folders.

Example:

.specfact/projects/legacy-api/
├── bundle.manifest.yaml
├── product.yaml
├── sdd.yaml                    # Bundle-specific SDD manifest
├── tasks.yaml                  # Bundle-specific task breakdown
├── reports/                    # Bundle-specific reports (gitignored)
│   ├── brownfield/
│   │   └── analysis-2025-10-31T14-30-00.md
│   ├── comparison/
│   │   └── report-2025-10-31T14-30-00.md
│   ├── enrichment/
│   │   └── legacy-api-2025-10-31T14-30-00.enrichment.md
│   └── enforcement/
│       └── report-2025-10-31T14-30-00.yaml
└── logs/                       # Bundle-specific logs (gitignored)
    └── 2025-10-31T14-30-00.log

Legacy Global Locations (Removed)

Note: The following global locations have been removed (Phase 8.5):

• ❌ .specfact/plans/ - Removed (active bundle config migrated to .specfact/config.yaml)
• ❌ .specfact/gates/results/ - Removed (enforcement reports are bundle-specific)
• ❌ .specfact/reports/ - Removed (reports are bundle-specific)
• ❌ .specfact/sdd/ - Removed (SDD manifests are bundle-specific)
• ❌ .specfact/tasks/ - Removed (task files are bundle-specific)

Migration: Use specfact project migrate cleanup-legacy to remove empty legacy directories, and specfact project migrate artifacts to migrate existing artifacts to bundle-specific locations.

.specfact/gates/ (Versioned)

Purpose: Global enforcement configuration.

Guidelines:

• config.yaml is versioned (defines enforcement policy)
• Enforcement reports are bundle-specific (stored in .specfact/projects/<bundle-name>/reports/enforcement/)

Example:

.specfact/gates/
└── config.yaml              # Versioned: enforcement policy

Note: Enforcement execution reports are stored in bundle-specific locations (Phase 8.5):

• .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.yaml

.specfact/cache/ (Gitignored)

Purpose: Tool caches for faster execution.

Guidelines:

• Gitignored - optimization only
• Safe to delete anytime
• Automatically regenerated

Default Command Paths

specfact code import ⭐ PRIMARY

Primary use case: Reverse-engineer existing codebases into project bundles.

# Command syntax
specfact code import <bundle-name> --repo . [OPTIONS]

# Creates modular bundle at:
.specfact/projects/<bundle-name>/
├── bundle.manifest.yaml  # Bundle metadata, versioning, checksums, feature index
├── product.yaml          # Product definition (required)
├── idea.yaml            # Product vision (if provided)
├── business.yaml        # Business context (if provided)
└── features/            # Individual feature files
    ├── FEATURE-001.yaml
    ├── FEATURE-002.yaml
    └── ...

# Analysis report (bundle-specific, gitignored, Phase 8.5)
.specfact/projects/<bundle-name>/reports/brownfield/analysis-<timestamp>.md

Example (brownfield modernization):

# Analyze legacy codebase
specfact code import legacy-api --repo . --confidence 0.7

# Creates:
# - .specfact/projects/legacy-api/bundle.manifest.yaml (versioned)
# - .specfact/projects/legacy-api/product.yaml (versioned)
# - .specfact/projects/legacy-api/features/FEATURE-*.yaml (versioned, one per feature)
# - .specfact/reports/brownfield/analysis-2025-10-31T14-30-00.md (gitignored)

Creating Project Bundles (Greenfield)

For greenfield projects, use code import with your source, or create a bundle structure manually:

# Analyze a new codebase and create a bundle
specfact code import <bundle-name> --repo .

# Creates modular bundle at:
.specfact/projects/<bundle-name>/
├── bundle.manifest.yaml  # Bundle metadata and versioning
├── product.yaml         # Product definition
└── features/           # Features directory

# Snapshot current state
specfact project snapshot --bundle <bundle-name>

specfact project sync bridge

# Sync with external tools (Spec-Kit, Linear, Jira, etc.)
specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional

# Watch mode
specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5

# Sync files are tracked in .specfact/reports/sync/

specfact project sync repository

# Sync code changes
specfact project sync repository --repo . --target .specfact

# Watch mode
specfact project sync repository --repo . --watch --interval 5

# Sync reports in .specfact/reports/sync/

specfact govern enforce stage

# Reads/writes
.specfact/gates/config.yaml

specfact init

Bootstraps local module lifecycle state (without IDE template copy side effects):

# Bootstrap and discover modules
specfact init

# Canonical lifecycle commands
specfact module list
specfact module install nold-ai/specfact-backlog
specfact module uninstall backlog

specfact init ide

Initializes IDE integration by copying prompt templates to IDE-specific locations:

# Auto-detect IDE
specfact init ide

# Specify IDE explicitly
specfact init ide --ide cursor
specfact init ide --ide vscode
specfact init ide --ide copilot

Creates/updates IDE-specific directories:

• Cursor: .cursor/commands/ (markdown files)
• VS Code / Copilot: .github/prompts/ (.prompt.md files) + .vscode/settings.json
• Claude Code: .claude/commands/ (markdown files)
• Gemini: .gemini/commands/ (TOML files)
• Qwen: .qwen/commands/ (TOML files)
• Other IDEs: See IDE Integration Guide

See IDE Integration Guide for complete setup instructions.

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via IDE integrations

Configuration File

.specfact/config.yaml (optional):

version: "1.0"

# Default bundle to use (optional)
default_bundle: my-project

# Analysis settings
analysis:
  confidence_threshold: 0.7
  exclude_patterns:
    - "**/__pycache__/**"
    - "**/node_modules/**"
    - "**/venv/**"

# Enforcement settings
enforcement:
  preset: balanced  # strict, balanced, minimal, shadow
  budget_seconds: 120
  fail_fast: false

# Repro settings
repro:
  parallel: true
  timeout: 300

IDE Integration Directories

When you run specfact init, prompt templates are copied to IDE-specific locations for slash command integration.

IDE-Specific Locations

Example Structure (Cursor)

.cursor/
└── commands/
    ├── specfact.01-import.md
    ├── specfact.02-plan.md
    ├── specfact.03-review.md
    ├── specfact.04-sdd.md
    ├── specfact.05-enforce.md
    ├── specfact.06-sync.md
    ├── specfact.compare.md
    └── specfact.validate.md

Example Structure (VS Code / Copilot)

.github/
└── prompts/
    ├── specfact.01-import.prompt.md
    ├── specfact.02-plan.prompt.md
    ├── specfact.03-review.prompt.md
    ├── specfact.04-sdd.prompt.md
    ├── specfact.05-enforce.prompt.md
    ├── specfact.06-sync.prompt.md
    ├── specfact.compare.prompt.md
    └── specfact.validate.prompt.md
.vscode/
└── settings.json  # Updated with promptFilesRecommendations

Guidelines:

• Versioned - IDE directories are typically committed to git (team-shared configuration)
• Templates - Prompt templates are read-only for the IDE, not modified by users
• Settings - VS Code settings.json is merged (not overwritten) to preserve existing settings
• Auto-discovery - IDEs automatically discover and register templates as slash commands
• CLI-first - Works offline, no account required, no vendor lock-in

See IDE Integration Guide for detailed setup and usage.

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via IDE integrations

SpecFact CLI Package Structure

The SpecFact CLI package includes prompt templates that are copied to IDE locations:

specfact-cli/
└── resources/
    └── prompts/              # Prompt templates (in package)
        ├── specfact.01-import.md
        ├── specfact.02-plan.md
        ├── specfact.03-review.md
        ├── specfact.04-sdd.md
        ├── specfact.05-enforce.md
        ├── specfact.06-sync.md
        ├── specfact.compare.md
        ├── specfact.validate.md
        └── shared/
            └── cli-enforcement.md

These templates are:

• Packaged with SpecFact CLI
• Copied to IDE locations by specfact init
• Not modified by users (read-only templates)

.gitignore Recommendations

Add to .gitignore:

# SpecFact ephemeral artifacts
.specfact/projects/*/reports/
.specfact/projects/*/logs/
.specfact/cache/

# Keep these versioned
!.specfact/projects/
!.specfact/config.yaml
!.specfact/gates/config.yaml

# IDE integration directories (optional - typically versioned)
# Uncomment if you don't want to commit IDE integration files
# .cursor/commands/
# .github/prompts/
# .vscode/settings.json
# .claude/commands/
# .gemini/commands/
# .qwen/commands/

Note: IDE integration directories are typically versioned (committed to git) so team members share the same slash commands. However, you can gitignore them if preferred.

Migration from Old Structure

If you have existing artifacts in other locations:

# Old structure (monolithic bundles, deprecated)
.specfact/plans/<name>.bundle.<format>
.specfact/reports/analysis.md

# New structure (modular bundles)
.specfact/projects/my-project/
├── bundle.manifest.yaml
└── bundle.yaml
.specfact/reports/brownfield/analysis.md

# Migration
mkdir -p .specfact/projects/my-project .specfact/reports/brownfield
# Convert monolithic bundle to modular bundle structure
# (Use 'specfact project regenerate' or manual conversion)
mv reports/analysis.md .specfact/reports/brownfield/

Multiple Plans in One Repository

SpecFact supports multiple plan bundles for:

• Brownfield modernization ⭐ PRIMARY: Separate plans for legacy components vs modernized code
• Monorepos: One plan per service
• Feature branches: Feature-specific plans

Example (Brownfield Modernization):

.specfact/projects/
├── my-project/                      # Overall project bundle
│   ├── bundle.manifest.yaml
│   ├── product.yaml
│   └── features/
│       └── ...
├── legacy-api/                      # ⭐ Reverse-engineered from existing API (brownfield)
│   ├── bundle.manifest.yaml
│   ├── product.yaml
│   └── features/
│       ├── FEATURE-AUTH.yaml
│       └── FEATURE-API.yaml
├── legacy-payment/                  # ⭐ Reverse-engineered from existing payment system (brownfield)
│   ├── bundle.manifest.yaml
│   ├── product.yaml
│   └── features/
│       └── FEATURE-PAYMENT.yaml
├── modernized-api/                  # New API bundle (after modernization)
│   ├── bundle.manifest.yaml
│   ├── product.yaml
│   └── features/
│       └── ...
└── feature-new-auth/                # Experimental feature bundle
    ├── bundle.manifest.yaml
    ├── product.yaml
    └── features/
        └── FEATURE-AUTH.yaml

Usage (Brownfield Workflow):

# Step 1: Reverse-engineer legacy codebase
specfact code import legacy-api \
  --repo src/legacy-api \
  --confidence 0.7

# Step 2: Snapshot and regenerate project state
specfact project snapshot --bundle legacy-api
specfact project regenerate --bundle legacy-api

# Step 3: Analyze specific legacy component
specfact code import legacy-payment \
  --repo src/legacy-payment \
  --confidence 0.7

Summary

SpecFact Artifacts

• .specfact/ - All SpecFact artifacts live here
• projects/ and protocols/ - Versioned (git)
• reports/, gates/results/, cache/ - Gitignored (ephemeral)
• Modular bundles - Each bundle in its own directory with manifest and content files
• Use descriptive bundle names - Supports multiple bundles per repo
• Default paths always start with .specfact/ - Consistent and predictable
• Timestamped reports - Auto-generated reports include timestamps for tracking
• Bridge architecture - Bidirectional sync with external tools (Spec-Kit, Linear, Jira, etc.) via bridge adapters

IDE Integration

• IDE directories - Created by specfact init (e.g., .cursor/commands/, .github/prompts/)
• Prompt templates - Copied from resources/prompts/ in SpecFact CLI package
• Typically versioned - IDE directories are usually committed to git for team sharing
• Auto-discovery - IDEs automatically discover and register templates as slash commands
• Settings files - VS Code settings.json is merged (not overwritten)

Quick Reference