Features
Attachments

Attachments

Rich documentation and visual diagrams attached directly to your work units.

During discovery and Example Mapping, you often need to attach supporting materials—architecture diagrams, mockups, research documents, or design specifications. fspec's attachment system lets you attach any file type to a work unit and view it with full markdown and Mermaid diagram rendering.

What Are Attachments?

Attachments are files you link to work units for context and documentation. Think of them as a work unit's reference library—everything needed to understand and implement the work.

Supported File Types:

  • Markdown files (.md, .markdown) with full Mermaid diagram support
  • Images (PNG, JPG, JPEG, GIF, SVG)
  • PDFs for specifications and documentation
  • Mermaid diagrams (.mmd) with syntax validation
  • Any file type (stored as binary)

Why Use Attachments?

Attachments serve multiple purposes:

  1. Architecture Context - Attach system diagrams before implementing
  2. Design Mockups - Visual references for UI work
  3. Research Notes - Document discovery findings
  4. API Specifications - Reference external APIs
  5. Requirements - Link to original requirement documents

How Attachments Work

File Storage

When you attach a file, fspec:

  1. Creates spec/attachments/<work-unit-id>/ directory
  2. Copies the file to this directory
  3. Records the relative path in the work unit
  4. Validates Mermaid syntax (if .mmd file)

Directory Structure:

spec/
  attachments/
    AUTH-001/
      auth-flow.mmd
      login-mockup.png
      requirements.md
    API-002/
      api-spec.pdf
      sequence-diagram.mmd

Viewing Attachments

fspec provides two ways to view attachments:

1. Interactive TUI (Terminal UI)

  • Launch: Press A key in the fspec TUI
  • Keyboard navigation with ↑↓ arrows
  • Select with Enter
  • Web server automatically starts for rendering

2. Command Line

fspec list-attachments <work-unit-id>

Shows all attachments with file size and modification date.

Natural Language Workflow

Scenario 1: Attaching Architecture Diagrams

YOU: "I'm working on user authentication. Let me create an architecture diagram first."

AI: "I'll create a Mermaid diagram for the auth flow and attach it to AUTH-001."

AI creates diagram in: diagrams/auth-flow.mmd

AI runs: fspec add-attachment AUTH-001 diagrams/auth-flow.mmd

AI: "Diagram attached! The auth flow shows OAuth integration with token refresh.
     You can view it in the TUI by pressing 'A'."

YOU: "Great! Now let's add the login mockup too."

AI: "I'll attach the mockup."

AI runs: fspec add-attachment AUTH-001 mockups/login-screen.png \
  --description "Login screen v1 mockup"

AI: "Both attachments are now linked to AUTH-001. Ready to start Example Mapping?"

Scenario 2: Research Documentation

YOU: "Before implementing the payment system, research Stripe's API and document it."

AI: "I'll research Stripe's payment flow and create documentation."

AI creates: research/stripe-integration.md

AI runs: fspec add-attachment PAY-001 research/stripe-integration.md

AI: "I've documented Stripe's API:
     - Payment Intent flow
     - Webhook handling
     - Error scenarios

     The markdown includes code examples and a sequence diagram.
     Attached to PAY-001 for reference during implementation."

YOU: "Perfect! Now we can start Example Mapping with this context."

Scenario 3: Attaching External Specifications

YOU: "Attach the API specification PDF to the work unit."

AI runs: fspec add-attachment API-005 specs/user-api-v2.pdf

AI: "PDF specification attached to API-005.
     The spec covers endpoints, authentication, and rate limiting."

YOU: "List all attachments for this work unit."

AI runs: fspec list-attachments API-005

Output:
  spec/attachments/API-005/user-api-v2.pdf (245 KB, modified 2025-11-09)
  spec/attachments/API-005/auth-flow.mmd (1.2 KB, modified 2025-11-08)

AI: "Two attachments found: the PDF spec and an auth flow diagram."

Commands Reference

Add Attachment

fspec add-attachment <work-unit-id> <file-path> [--description "text"]

Examples:

# Attach diagram
fspec add-attachment AUTH-001 diagrams/auth-flow.mmd
 
# Attach with description
fspec add-attachment UI-002 mockups/dashboard.png \
  --description "Dashboard v2 mockup"
 
# Attach PDF
fspec add-attachment API-001 specs/api-v2.pdf

What happens:

  1. Validates work unit exists
  2. Validates source file exists
  3. Validates Mermaid syntax (if .mmd file)
  4. Creates attachment directory
  5. Copies file
  6. Updates work unit metadata

List Attachments

fspec list-attachments <work-unit-id>

Output:

Attachments for AUTH-001:
  spec/attachments/AUTH-001/auth-flow.mmd (1.2 KB, 2025-11-09)
  spec/attachments/AUTH-001/login-mockup.png (45 KB, 2025-11-09)
  spec/attachments/AUTH-001/requirements.md (3.5 KB, 2025-11-08)

Remove Attachment

# Remove file and tracking
fspec remove-attachment <work-unit-id> <filename>
 
# Remove tracking but keep file
fspec remove-attachment <work-unit-id> <filename> --keep-file

Examples:

# Delete file and remove from work unit
fspec remove-attachment AUTH-001 old-diagram.mmd
 
# Keep file but unlink from work unit
fspec remove-attachment AUTH-001 draft-mockup.png --keep-file

Integration with ACDD

Attachments in the ACDD Workflow:

  1. Backlog Phase - Attach research findings and requirements
  2. Specifying Phase - Attach architecture diagrams and mockups
  3. Testing Phase - Reference attachments when writing tests
  4. Implementing Phase - Use diagrams and specs as implementation guide
  5. Validating Phase - Compare implementation to original specs

Web Viewer

fspec runs a local web server when the TUI is active, rendering markdown and Mermaid diagrams.

Features:

  • Full markdown rendering
  • Mermaid diagram support with syntax highlighting
  • Image display
  • PDF viewing
  • Automatic server lifecycle (starts with TUI, stops when TUI exits)

How to Access:

  1. Launch fspec TUI: fspec
  2. Press A key
  3. Navigate with ↑↓ arrows
  4. Press Enter to open in web viewer
  5. Press Esc to close

Common Patterns

Pattern 1: Architecture-First Approach

# 1. Create work unit
fspec create-story AUTH "OAuth Integration"
 
# 2. Research and document
AI creates: research/oauth-flow.md
AI creates: diagrams/oauth-sequence.mmd
 
# 3. Attach documentation
fspec add-attachment AUTH-001 research/oauth-flow.md
fspec add-attachment AUTH-001 diagrams/oauth-sequence.mmd
 
# 4. Begin Example Mapping with full context
fspec add-rule AUTH-001 "OAuth tokens expire after 1 hour"
fspec add-example AUTH-001 "User logs in with Google OAuth"

Pattern 2: Design Mockup Integration

# 1. Attach mockups during specifying
fspec add-attachment UI-001 mockups/dashboard-v2.png
fspec add-attachment UI-001 mockups/mobile-view.png
 
# 2. Reference mockups in scenarios
fspec generate-scenarios UI-001
 
# 3. Implement with visual reference
# AI reads mockups to understand exact layout

Pattern 3: API Specification Workflow

# 1. Attach external API spec
fspec add-attachment API-001 specs/stripe-api.pdf
 
# 2. Create integration diagram
AI creates: diagrams/stripe-integration.mmd
 
# 3. Attach diagram
fspec add-attachment API-001 diagrams/stripe-integration.mmd
 
# 4. Document in markdown
AI creates: docs/stripe-integration-notes.md
fspec add-attachment API-001 docs/stripe-integration-notes.md
 
# 5. All context in one place for implementation
fspec list-attachments API-001

Validation and Errors

Mermaid Validation

Mermaid files are validated before attachment:

fspec add-attachment AUTH-001 diagrams/invalid.mmd
 
# Error: Invalid Mermaid syntax
#   Line 5: Unexpected token 'invalid'
#
# Fix the diagram and try again.

Common Errors

Work Unit Not Found:

Error: Work unit 'INVALID-001' does not exist

Source File Missing:

Error: Source file 'diagrams/missing.mmd' does not exist

Duplicate Attachment:

Error: Attachment 'auth-flow.mmd' already exists for AUTH-001

Best Practices

✅ DO

  • Attach early - Add diagrams and docs during specifying phase
  • Use Mermaid - Prefer Mermaid diagrams over static images (easier to update)
  • Descriptive filenames - Use clear names like oauth-sequence-diagram.mmd
  • Version mockups - Name files like dashboard-v2.png for iteration tracking
  • Document research - Create markdown files summarizing findings

❌ DON'T

  • Attach binaries - Avoid large binary files (use external hosting for videos)
  • Skip validation - Always validate Mermaid syntax before attaching
  • Duplicate files - Don't attach the same file multiple times
  • Forget to review - Use fspec list-attachments to verify attachments
  • Leave orphaned files - Remove attachments when no longer needed

Decision Flow

Summary

Attachments provide rich context for work units:

Key Benefits:

  • Document architecture decisions with diagrams
  • Attach design mockups for visual reference
  • Link research findings and external specs
  • Full Mermaid diagram support with validation
  • Web viewer for easy navigation

Integration:

  • Attach during backlog and specifying phases
  • Reference during testing and implementation
  • Part of comprehensive work unit documentation

Use attachments to create a complete picture of each work unit—combining Example Mapping with visual diagrams, mockups, and documentation.

Coverage TrackingFoundation Document