Team Collaboration Workflow

Complete guide to using SpecFact CLI for team collaboration with persona-based workflows

Overview

SpecFact CLI supports team collaboration through persona-based workflows where different roles (Product Owner, Architect, Developer) work on different aspects of the project using Markdown files. This guide explains when and how to use the team collaboration commands.

Related: Agile/Scrum Workflows - Complete persona-based collaboration guide

When to Use Team Collaboration Commands

Use these commands when:

  • Multiple team members need to work on the same project bundle
  • Different roles (Product Owner, Architect, Developer) need to edit different sections
  • Concurrent editing needs to be managed safely
  • Version control integration is needed for team workflows

Core Commands

project init-personas

Initialize persona definitions for a project bundle.

When to use: First-time setup for team collaboration.

Example:

specfact project init-personas --bundle my-project

Related: Agile/Scrum Workflows - Persona Setup

project export

Export persona-specific Markdown artifacts for editing.

When to use: When a team member needs to edit their role-specific sections.

Example:

# Export Product Owner view
specfact project export --bundle my-project --persona product-owner

# Export Developer view
specfact project export --bundle my-project --persona developer

# Export Architect view
specfact project export --bundle my-project --persona architect

Workflow: Export → Edit in Markdown → Import back

Related: Agile/Scrum Workflows - Exporting Persona Artifacts

project import

Import persona edits from Markdown files back into the project bundle.

When to use: After editing exported Markdown files.

Example:

# Import Product Owner edits
specfact project import --bundle my-project --persona product-owner --source docs/backlog.md

# Dry-run to validate without applying
specfact project import --bundle my-project --persona product-owner --source docs/backlog.md --dry-run

Workflow: Export → Edit → Import → Validate

Related: Agile/Scrum Workflows - Importing Persona Edits

project lock / project unlock

Lock sections to prevent concurrent edits.

When to use: When multiple team members might edit the same section simultaneously.

Example:

# Lock a section for editing
specfact project lock --bundle my-project --section idea --persona product-owner

# Edit and import
specfact project export --bundle my-project --persona product-owner
# ... edit exported file ...
specfact project import --bundle my-project --persona product-owner --source backlog.md

# Unlock when done
specfact project unlock --bundle my-project --section idea

Workflow: Lock → Export → Edit → Import → Unlock

Related: Agile/Scrum Workflows - Section Locking

project locks

List all locked sections.

When to use: Before starting work to see what’s locked.

Example:

specfact project locks --bundle my-project

Related: Agile/Scrum Workflows - Checking Locks

Complete Workflow Example

Scenario: Product Owner Updates Backlog

# 1. Check what's locked
specfact project locks --bundle my-project

# 2. Lock the section you need
specfact project lock --bundle my-project --section idea --persona product-owner

# 3. Export your view
specfact project export --bundle my-project --persona product-owner --output backlog.md

# 4. Edit backlog.md in your preferred editor

# 5. Import changes back
specfact project import --bundle my-project --persona product-owner --source backlog.md

# 6. Unlock the section
specfact project unlock --bundle my-project --section idea

Integration with Version Management

Team collaboration integrates with version management:

# After importing changes, check if version bump is needed
specfact project version check --bundle my-project

# If needed, bump version
specfact project version bump --bundle my-project --type minor

Related: Project Version Management

Integration with Command Chains

Team collaboration commands are part of the Plan Promotion & Release Chain:

  1. Export persona views
  2. Edit in Markdown
  3. Import back
  4. Review plan
  5. Enforce SDD
  6. Promote plan
  7. Bump version

Related: Plan Promotion & Release Chain

See Also