specfact-cli 0.15.3__tar.gz → 0.16.1__tar.gz

{specfact_cli-0.15.3 → specfact_cli-0.16.1}/.gitignore

@@ -117,4 +117,10 @@ reports/
 
 # Jekyll bundle
 vendor/
-_site/
+_site/
+
+# specfact-cli artifacts (note: these should be generated in /tmp/)
+findings.json
+answers.json
+questions.json
+docs/project-plans/

{specfact_cli-0.15.3 → specfact_cli-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.15.3
+Version: 0.16.1
 Summary: Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git
@@ -332,6 +332,16 @@ A brownfield-first CLI that **reverse engineers your legacy code** into document
 
 **For teams that can't afford production bugs during migration.**
 
+### 🎯 Built for Real-World Agile Teams
+
+SpecFact isn't just a technical tool—it's designed for **real-world agile/scrum teams** with role-based workflows:
+
+- 👤 **Product Owners** → Export backlog with DoR checklists, prioritization, dependencies, and sprint planning
+- 🏗️ **Architects** → Export technical constraints, protocols, contracts, architectural decisions, and risk assessments
+- 💻 **Developers** → Export implementation tasks, code mappings, test scenarios, and Definition of Done criteria
+
+**Each role works in their own Markdown files** (no YAML editing), and SpecFact syncs everything together automatically. Perfect for teams using agile/scrum practices with clear role separation.
+
 ---
 
 ## Why SpecFact?
@@ -360,6 +370,8 @@ A brownfield-first CLI that **reverse engineers your legacy code** into document
 
 ## 💡 Key Capabilities
 
+### Technical Capabilities
+
 - ✅ **Reverse engineer legacy code** → Extract specs automatically from existing code
 - ✅ **Runtime contract enforcement** → Prevent regressions during modernization
 - ✅ **Symbolic execution** → Discover hidden edge cases with CrossHair
@@ -367,6 +379,47 @@ A brownfield-first CLI that **reverse engineers your legacy code** into document
 - ✅ **Works offline** → No cloud required, fully local
 - ✅ **CLI integrations** → Works seamlessly with VS Code, Cursor, GitHub Actions, and any agentic workflow
 
+### Team Collaboration Capabilities
+
+- ✅ **Persona-based workflows** → Product Owners, Architects, and Developers work in parallel on their own sections
+- ✅ **Agile/scrum alignment** → Definition of Ready (DoR), story points, dependencies, prioritization, sprint planning
+- ✅ **Role-specific exports** → Each persona gets a tailored Markdown view with only what they need
+- ✅ **Git-native collaboration** → Conflicts resolved in human-readable Markdown, not brittle YAML
+- ✅ **Real-world templates** → Templates designed by agile coaches to match actual team expectations
+
+---
+
+## 👥 Team Collaboration: Persona-Based Workflows
+
+SpecFact enables **real-world agile/scrum teams** to work together seamlessly with role-based workflows:
+
+```bash
+# Product Owner: Export backlog for sprint planning
+specfact project export --bundle legacy-api --persona product-owner
+# → Exports: DoR checklists, prioritization, dependencies, business value, sprint planning
+
+# Architect: Export technical design
+specfact project export --bundle legacy-api --persona architect
+# → Exports: Technical constraints, protocols, contracts, architectural decisions, NFRs
+
+# Developer: Export implementation details
+specfact project export --bundle legacy-api --persona developer
+# → Exports: Tasks, code mappings, test scenarios, Definition of Done
+
+# Each role edits their Markdown, then imports back
+specfact project import --bundle legacy-api --persona product-owner --source backlog.md
+```
+
+**Why this matters:**
+
+- ✅ **No YAML editing** → Everyone works in familiar Markdown
+- ✅ **Parallel workflows** → Product Owners, Architects, and Developers work simultaneously
+- ✅ **Git-native** → Conflicts resolved in Markdown (human-readable), not YAML
+- ✅ **Agile/scrum ready** → Built-in DoR validation, dependency tracking, sprint planning
+- ✅ **Real-world templates** → Designed by agile coaches to match actual team expectations
+
+👉 **[Agile/Scrum Workflows Guide](docs/guides/agile-scrum-workflows.md)** - Complete guide to persona-based team collaboration
+
 ---
 
 ## 🔌 CLI Integrations
@@ -403,6 +456,8 @@ We ran SpecFact CLI **on itself** to prove it works with legacy code:
 
 **New to SpecFact?** Start with the [Getting Started Guide](docs/getting-started/README.md)
 
+**Working with a team?** See [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md) - Persona-based team collaboration with Product Owners, Architects, and Developers
+
 **Want to see integrations?** Check out [Integration Showcases](docs/examples/integration-showcases/) - Real bugs fixed via VS Code, Cursor, GitHub Actions
 
 **Tried Spec-Kit?** See [How SpecFact Compares to Spec-Kit](docs/guides/speckit-comparison.md) and [The Journey: From Spec-Kit to SpecFact](docs/guides/speckit-journey.md)

{specfact_cli-0.15.3 → specfact_cli-0.16.1}/README.md

@@ -57,6 +57,16 @@ A brownfield-first CLI that **reverse engineers your legacy code** into document
 
 **For teams that can't afford production bugs during migration.**
 
+### 🎯 Built for Real-World Agile Teams
+
+SpecFact isn't just a technical tool—it's designed for **real-world agile/scrum teams** with role-based workflows:
+
+- 👤 **Product Owners** → Export backlog with DoR checklists, prioritization, dependencies, and sprint planning
+- 🏗️ **Architects** → Export technical constraints, protocols, contracts, architectural decisions, and risk assessments
+- 💻 **Developers** → Export implementation tasks, code mappings, test scenarios, and Definition of Done criteria
+
+**Each role works in their own Markdown files** (no YAML editing), and SpecFact syncs everything together automatically. Perfect for teams using agile/scrum practices with clear role separation.
+
 ---
 
 ## Why SpecFact?
@@ -85,6 +95,8 @@ A brownfield-first CLI that **reverse engineers your legacy code** into document
 
 ## 💡 Key Capabilities
 
+### Technical Capabilities
+
 - ✅ **Reverse engineer legacy code** → Extract specs automatically from existing code
 - ✅ **Runtime contract enforcement** → Prevent regressions during modernization
 - ✅ **Symbolic execution** → Discover hidden edge cases with CrossHair
@@ -92,6 +104,47 @@ A brownfield-first CLI that **reverse engineers your legacy code** into document
 - ✅ **Works offline** → No cloud required, fully local
 - ✅ **CLI integrations** → Works seamlessly with VS Code, Cursor, GitHub Actions, and any agentic workflow
 
+### Team Collaboration Capabilities
+
+- ✅ **Persona-based workflows** → Product Owners, Architects, and Developers work in parallel on their own sections
+- ✅ **Agile/scrum alignment** → Definition of Ready (DoR), story points, dependencies, prioritization, sprint planning
+- ✅ **Role-specific exports** → Each persona gets a tailored Markdown view with only what they need
+- ✅ **Git-native collaboration** → Conflicts resolved in human-readable Markdown, not brittle YAML
+- ✅ **Real-world templates** → Templates designed by agile coaches to match actual team expectations
+
+---
+
+## 👥 Team Collaboration: Persona-Based Workflows
+
+SpecFact enables **real-world agile/scrum teams** to work together seamlessly with role-based workflows:
+
+```bash
+# Product Owner: Export backlog for sprint planning
+specfact project export --bundle legacy-api --persona product-owner
+# → Exports: DoR checklists, prioritization, dependencies, business value, sprint planning
+
+# Architect: Export technical design
+specfact project export --bundle legacy-api --persona architect
+# → Exports: Technical constraints, protocols, contracts, architectural decisions, NFRs
+
+# Developer: Export implementation details
+specfact project export --bundle legacy-api --persona developer
+# → Exports: Tasks, code mappings, test scenarios, Definition of Done
+
+# Each role edits their Markdown, then imports back
+specfact project import --bundle legacy-api --persona product-owner --source backlog.md
+```
+
+**Why this matters:**
+
+- ✅ **No YAML editing** → Everyone works in familiar Markdown
+- ✅ **Parallel workflows** → Product Owners, Architects, and Developers work simultaneously
+- ✅ **Git-native** → Conflicts resolved in Markdown (human-readable), not YAML
+- ✅ **Agile/scrum ready** → Built-in DoR validation, dependency tracking, sprint planning
+- ✅ **Real-world templates** → Designed by agile coaches to match actual team expectations
+
+👉 **[Agile/Scrum Workflows Guide](docs/guides/agile-scrum-workflows.md)** - Complete guide to persona-based team collaboration
+
 ---
 
 ## 🔌 CLI Integrations
@@ -128,6 +181,8 @@ We ran SpecFact CLI **on itself** to prove it works with legacy code:
 
 **New to SpecFact?** Start with the [Getting Started Guide](docs/getting-started/README.md)
 
+**Working with a team?** See [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md) - Persona-based team collaboration with Product Owners, Architects, and Developers
+
 **Want to see integrations?** Check out [Integration Showcases](docs/examples/integration-showcases/) - Real bugs fixed via VS Code, Cursor, GitHub Actions
 
 **Tried Spec-Kit?** See [How SpecFact Compares to Spec-Kit](docs/guides/speckit-comparison.md) and [The Journey: From Spec-Kit to SpecFact](docs/guides/speckit-journey.md)

{specfact_cli-0.15.3 → specfact_cli-0.16.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.15.3"
+version = "0.16.1"
 description = "Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions."
 readme = "README.md"
 requires-python = ">=3.11"

specfact_cli-0.16.1/resources/templates/persona/architect.md.j2

@@ -0,0 +1,211 @@
+# Project Plan: {{ bundle_name }} - Architect View
+
+**Persona**: Architect  
+**Bundle**: `{{ bundle_name }}`  
+**Created**: {{ created_at }}  
+**Status**: {{ status }}  
+**Last Updated**: {{ updated_at }}
+
+{% if features %}
+## Technical Constraints & Requirements *(mandatory)*
+
+{% for feature_key, feature in features.items() %}
+### {{ feature.key }}: {{ feature.title }}
+
+{% if feature.constraints %}
+#### Technical Constraints - {{ feature.key }}
+
+{% for constraint in feature.constraints %}
+- {{ constraint }}
+{% endfor %}
+{% else %}
+*[ACTION REQUIRED: Define technical constraints for this feature]*
+{%- endif %}
+{% if feature.contract %}
+#### API Contract
+
+**Contract Path**: `{{ feature.contract }}`
+
+{% if contracts and feature.key in contracts %}
+**Contract Details**: See Contracts section below.
+{%- endif %}
+{%- endif %}
+{% if feature.protocol %}
+#### State Machine Protocol
+
+**Protocol Path**: `{{ feature.protocol }}`
+
+{% if protocols and feature.key in protocols %}
+**Protocol Details**: See Protocols & State Machines section below.
+{%- endif %}
+{%- endif %}
+{% if feature.priority or feature.rank or feature.business_value_score %}
+#### Feature Prioritization
+
+{% if feature.priority %}
+- **Priority**: {{ feature.priority }}
+{% endif %}
+{% if feature.rank %}
+- **Backlog Rank**: {{ feature.rank }} (1 = highest priority)
+{% endif %}
+{% if feature.business_value_score %}
+- **Business Value Score**: {{ feature.business_value_score }}/100
+{% endif %}
+{% if feature.target_release %}
+- **Target Release**: {{ feature.target_release }}
+{%- endif %}
+{%- endif %}
+{% if feature.depends_on_features or feature.blocks_features %}
+#### Feature Dependencies
+
+{% if feature.depends_on_features %}
+- **Depends On**: {{ feature.depends_on_features | join(', ') }}
+{% endif %}
+{% if feature.blocks_features %}
+- **Blocks**: {{ feature.blocks_features | join(', ') }}
+{%- endif %}
+{%- endif %}
+{% if feature.estimated_story_points %}
+#### Story Point Estimation
+
+- **Total Estimated Story Points**: {{ feature.estimated_story_points }}
+{%- endif %}
+
+{%- endfor %}
+{% else %}
+## Technical Constraints & Requirements *(mandatory)*
+
+*[ACTION REQUIRED: Define technical constraints and requirements for features]*
+{%- endif %}
+
+{% if protocols %}
+## Protocols & State Machines *(mandatory)*
+
+{% for protocol_name, protocol_data in protocols.items() %}
+### {{ protocol_name }}
+
+{% if protocol_data.states %}
+**States**: {{ protocol_data.states | join(', ') }}
+{%- endif %}
+
+{%- if protocol_data.transitions %}
+**Transitions**:
+
+{% for transition in protocol_data.transitions %}
+- `{{ transition.from_state }}` → `{{ transition.to_state }}`{% if transition.event %} (on: `{{ transition.event }}`){% endif %}
+{% endfor %}
+{%- endif %}
+
+{%- if protocol_data.initial_state %}
+**Initial State**: `{{ protocol_data.initial_state }}`
+{%- endif %}
+
+{%- if protocol_data.final_states %}
+**Final States**: {{ protocol_data.final_states | join(', ') }}
+{%- endif %}
+
+{%- if protocol_data.validation_rules %}
+**Validation Rules**:
+
+{% for rule in protocol_data.validation_rules %}
+- {{ rule }}
+{% endfor %}
+{%- endif %}
+
+---
+
+{% endfor %}
+{% else %}
+## Protocols & State Machines *(mandatory)*
+
+*[ACTION REQUIRED: Define protocols and state machines]*
+
+**Note**: Protocols should be defined in `.specfact/projects/{{ bundle_name }}/protocols/*.protocol.yaml` files.
+{% endif %}
+
+{% if contracts %}
+## Contracts *(mandatory)*
+
+{% for contract_name, contract_data in contracts.items() %}
+### {{ contract_name }}
+
+{% if contract_data.info %}
+**Info**:
+
+- **Title**: {{ contract_data.info.title if contract_data.info.title else 'N/A' }}
+- **Version**: {{ contract_data.info.version if contract_data.info.version else 'N/A' }}
+- **Description**: {{ contract_data.info.description if contract_data.info.description else 'N/A' }}
+{%- endif %}
+
+{%- if contract_data.openapi %}
+**OpenAPI Version**: {{ contract_data.openapi }}
+{%- endif %}
+
+{%- if contract_data.asyncapi %}
+**AsyncAPI Version**: {{ contract_data.asyncapi }}
+{%- endif %}
+
+{%- if contract_data.servers %}
+**Servers**:
+
+{% for server in contract_data.servers %}
+- {{ server.url }}{% if server.description %} - {{ server.description }}{% endif %}
+{% endfor %}
+{%- endif %}
+
+{%- if contract_data.paths %}
+**Endpoints**:
+
+{% for path, methods in contract_data.paths.items() %}
+- `{{ path }}`:
+{% for method, details in methods.items() %}
+  - `{{ method.upper() }}`: {{ details.summary if details.summary else 'N/A' }}
+{% endfor %}
+{% endfor %}
+{%- endif %}
+
+{%- if contract_data.components and contract_data.components.schemas %}
+**Schemas**:
+
+{% for schema_name, schema_def in contract_data.components.schemas.items() %}
+- `{{ schema_name }}`: {{ schema_def.type if schema_def.type else 'object' }}
+{% endfor %}
+{%- endif %}
+
+---
+
+{%- endfor %}
+{% else %}
+## Contracts *(mandatory)*
+
+*[ACTION REQUIRED: Define contracts (OpenAPI, AsyncAPI, etc.)]*
+
+**Note**: Contracts should be defined in `.specfact/projects/{{ bundle_name }}/contracts/*.openapi.yaml` or `*.asyncapi.yaml` files.
+{%- endif %}
+
+## Ownership & Locks
+
+{% if locks %}
+**Locked Sections**:
+
+{% for lock in locks %}
+- `{{ lock.section }}` - Locked by {{ lock.owner }} ({{ lock.locked_at }})
+{% endfor %}
+{% else %}
+No sections currently locked
+{% endif %}
+
+## Validation Checklist
+
+- [ ] All features have technical constraints defined
+- [ ] Protocols/state machines are documented
+- [ ] Contracts are defined and validated
+- [ ] Architecture decisions are documented
+- [ ] Non-functional requirements are specified
+- [ ] Risk assessment is complete
+- [ ] Deployment architecture is documented
+
+## Notes
+
+*Use this section for architectural decisions, trade-offs, or technical clarifications.*
+

specfact_cli-0.16.1/resources/templates/persona/developer.md.j2

@@ -0,0 +1,240 @@
+# Project Plan: {{ bundle_name }} - Developer View
+
+**Persona**: Developer  
+**Bundle**: `{{ bundle_name }}`  
+**Created**: {{ created_at }}  
+**Status**: {{ status }}  
+**Last Updated**: {{ updated_at }}
+
+{% if features %}
+## Acceptance Criteria & Implementation Details *(mandatory)*
+
+{%- for feature_key, feature in features.items() -%}
+### {{ feature.key }}: {{ feature.title }}
+
+{% if feature.acceptance %}
+#### Acceptance Criteria - {{ feature.key }}
+
+{%- for criterion in feature.acceptance %}
+{% set criterion_clean = criterion.replace('\r\n', '\n').replace('\r', '\n').strip() %}
+{% if '\n' in criterion_clean %}
+{% set criterion_lines = criterion_clean.split('\n') %}
+{% for line in criterion_lines %}
+{% if line.strip() %}
+- [ ] {{ line.strip() }}
+{% endif %}
+{% endfor %}
+{% else %}
+- [ ] {{ criterion_clean }}
+{%- endif -%}
+{%- endfor -%}
+{% else %}
+*[ACTION REQUIRED: Define acceptance criteria for this feature]*
+{%- endif %}
+{% if feature.stories %}
+#### User Stories
+
+{% for story in feature.stories %}
+**{{ story.key }}**: {{ story.title }}
+
+{% if story.story_points or story.value_points or story.priority or story.target_sprint or story.target_release or story.depends_on_stories or story.blocks_stories %}
+**Sprint Context**:
+
+{% if story.story_points %}
+- **Story Points**: {{ story.story_points }} (complexity)
+{% endif %}
+{% if story.value_points %}
+- **Value Points**: {{ story.value_points }} (business value)
+{% endif %}
+{% if story.priority %}
+- **Priority**: {{ story.priority }}
+{% endif %}
+{% if story.rank %}
+- **Backlog Rank**: {{ story.rank }} (1 = highest priority)
+{% endif %}
+{% if story.target_sprint %}
+- **Target Sprint**: {{ story.target_sprint }}
+{% endif %}
+{% if story.target_release %}
+- **Target Release**: {{ story.target_release }}
+{% endif %}
+{% if story.due_date %}
+- **Due Date**: {{ story.due_date }}
+{% endif %}
+{% if story.depends_on_stories %}
+- **Depends On**: {{ story.depends_on_stories | join(', ') }}
+{% endif %}
+{% if story.blocks_stories %}
+- **Blocks**: {{ story.blocks_stories | join(', ') }}
+{%- endif %}
+{%- endif %}
+{% if story.acceptance %}
+**Acceptance Criteria**:
+
+{% for criterion in story.acceptance %}
+{% set criterion_clean = criterion.replace('\r\n', '\n').replace('\r', '\n').strip() %}
+{% if '\n' in criterion_clean %}
+{% set criterion_lines = criterion_clean.split('\n') %}
+{% for line in criterion_lines %}
+{% if line.strip() %}
+- [ ] {{ line.strip() }}
+{% endif %}
+{% endfor %}
+{% else %}
+- [ ] {{ criterion_clean }}
+{% endif %}
+{% endfor %}
+{%- endif %}
+{% if story.tasks %}
+**Implementation Tasks**:
+
+{% for task in story.tasks %}
+- [ ] {{ task }}
+{% endfor %}
+{%- endif %}
+{% if story.contracts %}
+**API Contracts**:
+
+{% for contract_type, contract_data in story.contracts.items() %}
+**{{ contract_type }}**:
+
+{% if contract_data is mapping %}
+{% if contract_data.parameters %}
+**Parameters**:
+{% for param_name, param_info in contract_data.parameters.items() %}
+- `{{ param_name }}`: {{ param_info.type if param_info.type else 'Any' }}{% if param_info.description %} - {{ param_info.description }}{% endif %}
+{% endfor %}
+{% endif %}
+{% if contract_data.return_type %}
+**Return Type**: `{{ contract_data.return_type }}`
+{% endif %}
+{% if contract_data.preconditions %}
+**Preconditions**:
+{% for precondition in contract_data.preconditions %}
+- {{ precondition }}
+{% endfor %}
+{% endif %}
+{% if contract_data.postconditions %}
+**Postconditions**:
+{% for postcondition in contract_data.postconditions %}
+- {{ postcondition }}
+{% endfor %}
+{% endif %}
+{% if contract_data.error_contracts %}
+**Error Contracts**:
+{% for error_type, error_info in contract_data.error_contracts.items() %}
+- `{{ error_type }}`: {{ error_info.description if error_info.description else error_info }}
+{% endfor %}
+{% endif %}
+{% else %}
+```python
+{{ contract_data }}
+```
+{% endif %}
+{% endfor %}
+{%- endif %}
+{% if story.scenarios %}
+**Test Scenarios**:
+
+{% if story.scenarios.primary %}
+**Primary**:
+{% for scenario in story.scenarios.primary %}
+- {{ scenario }}
+{% endfor %}
+{% endif %}
+{% if story.scenarios.alternate %}
+**Alternate**:
+{% for scenario in story.scenarios.alternate %}
+- {{ scenario }}
+{% endfor %}
+{% endif %}
+{% if story.scenarios.exception %}
+**Exception**:
+{% for scenario in story.scenarios.exception %}
+- {{ scenario }}
+{% endfor %}
+{% endif %}
+{% if story.scenarios.recovery %}
+**Recovery**:
+{% for scenario in story.scenarios.recovery %}
+- {{ scenario }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+{% if story.source_functions or story.test_functions %}
+**Code Mappings**:
+
+{% if story.source_functions %}
+**Source Functions**:
+{% for func in story.source_functions %}
+- `{{ func }}`
+{% endfor %}
+{% endif %}
+{% if story.test_functions %}
+**Test Functions**:
+{% for func in story.test_functions %}
+- `{{ func }}`
+{% endfor %}
+{%- endif %}
+{%- endif %}
+{% if story.definition_of_ready %}
+**Definition of Ready Status**:
+
+{% for item, status in story.definition_of_ready.items() %}
+- [{% if status %}x{% else %} {% endif %}] {{ item.replace('_', ' ').title() }}
+{% endfor %}
+{%- endif %}
+
+**Definition of Done**:
+
+- [ ] Code implemented and reviewed
+- [ ] Unit tests written (100% coverage for critical paths)
+- [ ] Integration tests passing
+- [ ] API documentation updated
+- [ ] Performance requirements met
+- [ ] Security requirements met
+
+---
+
+{% endfor %}
+{%- endif %}
+{% if feature.implementation %}
+#### Implementation Notes
+
+{{ feature.implementation }}
+{%- endif -%}
+{%- endfor -%}
+{% else %}
+## Acceptance Criteria & Implementation Details *(mandatory)*
+
+*[ACTION REQUIRED: Define acceptance criteria and implementation details for features]*
+{%- endif -%}
+
+## Ownership & Locks
+
+{% if locks %}
+**Locked Sections**:
+
+{% for lock in locks %}
+- `{{ lock.section }}` - Locked by {{ lock.owner }} ({{ lock.locked_at }})
+{% endfor %}
+{% else %}
+No sections currently locked
+{% endif %}
+
+## Validation Checklist
+
+- [ ] All features have acceptance criteria defined
+- [ ] Acceptance criteria are testable
+- [ ] Implementation tasks are documented
+- [ ] API contracts are defined
+- [ ] Test scenarios are documented
+- [ ] Code mappings are complete
+- [ ] Edge cases are considered
+- [ ] Testing strategy is defined
+- [ ] Definition of Done criteria are met
+
+## Notes
+
+*Use this section for implementation questions, technical notes, or development clarifications.*
+