@pennyfarthing/core 7.5.0 → 7.6.1

package/pennyfarthing-dist/workflows/architecture/steps/step-03-patterns.md

@@ -0,0 +1,133 @@
+# Step 3: Pattern Selection
+
+<step-meta>
+number: 3
+name: pattern-selection
+gate: false
+</step-meta>
+
+## Mandatory Execution Rules
+
+- READ the complete step file before taking any action
+- SEARCH the web to verify current technology versions - NEVER trust hardcoded versions
+- ALWAYS treat this as collaborative discovery between architectural peers
+- FOCUS on evaluating patterns with up-to-date information
+
+## Execution Protocols
+
+- Show your analysis before taking any action
+- Search the web to verify current versions and options
+- Present A/P/C menu after generating pattern analysis
+- ONLY save when user chooses [C] Continue
+- Update frontmatter `stepsCompleted: [1, 2, 3]` before loading next step
+- FORBIDDEN to load next step until [C] is selected
+
+## Purpose
+
+Identify and evaluate architectural patterns that could address the identified concerns, with current technology verification.
+
+## Instructions
+
+1. **Survey Applicable Patterns**:
+   Based on the context analysis, identify patterns that address the key concerns:
+   - For scalability: microservices, event-driven, CQRS
+   - For reliability: circuit breakers, bulkheads, retries
+   - For maintainability: clean architecture, hexagonal, modular monolith
+   - For integration: API gateway, message broker, service mesh
+
+2. **Verify Current Versions** (web search):
+   For any frameworks or technologies being considered:
+   - What is the current stable version?
+   - What are the recommended starter templates?
+   - Are there breaking changes in recent releases?
+
+3. **Evaluate Trade-offs**:
+   For each candidate pattern, consider:
+   - Complexity cost vs. benefit
+   - Team familiarity
+   - Operational overhead
+   - Fit with existing systems
+
+4. **Select Primary Pattern(s)**:
+   Choose 1-3 patterns that best address the requirements.
+
+## Actions
+
+- Review: Architecture pattern references
+- Search: Web for current framework versions and best practices
+- Compare: Pattern fit against constraints from Step 2
+- Document: Trade-off analysis
+
+## Output
+
+Add to session file:
+
+```markdown
+## Pattern Analysis
+
+### Technology Versions (as of {date})
+| Technology | Current Version | Notes |
+|------------|-----------------|-------|
+| [Tech 1] | [version] | [stability, LTS status] |
+| [Tech 2] | [version] | [stability, LTS status] |
+
+### Candidate Patterns
+
+| Pattern | Addresses | Trade-offs | Fit Score |
+|---------|-----------|------------|-----------|
+| [Pattern 1] | [concerns] | [pros/cons] | [1-5] |
+| [Pattern 2] | [concerns] | [pros/cons] | [1-5] |
+| [Pattern 3] | [concerns] | [pros/cons] | [1-5] |
+
+### Selected Pattern(s)
+1. **[Primary pattern]**: [Why this fits best]
+2. **[Secondary pattern]** (if needed): [Why]
+
+### Rejected Alternatives
+- [Pattern]: [Why not suitable]
+```
+
+## Collaboration Menu (A/P/C)
+
+After generating pattern analysis, present choices:
+
+- **[A] Advanced Elicitation** - Use discovery protocols to explore unconventional patterns or custom approaches
+- **[P] Party Mode** - Bring multiple perspectives to evaluate pattern trade-offs for different use cases
+- **[C] Continue** - Save the content and proceed to component design
+- **[R] Revise** - Need to reconsider patterns or gather more information
+
+## Advanced Elicitation Mode
+
+When user selects [A]:
+1. Explore hybrid patterns combining multiple approaches
+2. Investigate emerging patterns not yet mainstream
+3. Consider domain-specific architectural patterns
+4. Question assumptions about pattern applicability
+
+## Party Mode
+
+When user selects [P]:
+1. Present pattern evaluation from multiple viewpoints:
+   - **Pragmatist**: What's the simplest thing that works?
+   - **Futurist**: What if requirements change significantly?
+   - **Skeptic**: What could go wrong with this pattern?
+   - **Operator**: How will this pattern affect day-to-day operations?
+2. Synthesize perspectives into pattern recommendation
+
+## Success Metrics
+
+- Patterns evaluated against context constraints
+- Current technology versions verified via web search
+- Trade-offs clearly documented
+- User confirmed pattern selection before proceeding
+
+## Failure Modes
+
+- Using outdated technology versions
+- Not considering team familiarity
+- Selecting overly complex patterns for simple problems
+- Proceeding without user confirmation
+
+## Next Step
+
+After user selects [C], proceed to Component Design to define the system structure.

package/pennyfarthing-dist/workflows/architecture/steps/step-04-components.md

@@ -0,0 +1,138 @@
+# Step 4: Component Design
+
+<step-meta>
+number: 4
+name: component-design
+gate: true
+</step-meta>
+
+## Mandatory Execution Rules
+
+- READ the complete step file before taking any action
+- FOCUS on components that prevent AI agent implementation conflicts
+- EMPHASIZE what agents could decide DIFFERENTLY if not specified
+- ALWAYS treat this as collaborative discovery between architectural peers
+
+## Execution Protocols
+
+- Show your analysis before taking any action
+- Present A/P/C menu after generating component design
+- ONLY save when user chooses [C] Continue
+- Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step
+- FORBIDDEN to load next step until [C] is selected
+
+## Purpose
+
+Define the major components of the system and their responsibilities based on the selected patterns. Focus on clarity that prevents implementation ambiguity.
+
+## Instructions
+
+1. **Identify Components**:
+   Based on the selected pattern(s), define the major building blocks:
+   - What are the primary components/services?
+   - What is each component responsible for?
+   - What data does each component own?
+
+2. **Define Boundaries**:
+   - Where are the component boundaries?
+   - What crosses each boundary?
+   - How do components communicate?
+
+3. **Map Dependencies**:
+   - Which components depend on others?
+   - Are there circular dependencies to avoid?
+   - What is the deployment topology?
+
+4. **Specify for Agent Consistency** (BMAD pattern):
+   - What decisions must be consistent across implementations?
+   - Where could two different AI agents make conflicting choices?
+   - Document explicit rules to prevent divergence
+
+## Actions
+
+- Design: Component diagram (can be ASCII or Mermaid)
+- Document: Component responsibilities
+- Validate: Boundaries align with domain concepts
+- Specify: Consistency rules for AI implementation
+
+## Output
+
+Add to session file:
+
+```markdown
+## Component Design
+
+### Component Diagram
+
+\`\`\`
+┌─────────────┐     ┌─────────────┐
+│ Component A │────▶│ Component B │
+└─────────────┘     └─────────────┘
+       │                   │
+       ▼                   ▼
+┌─────────────┐     ┌─────────────┐
+│ Component C │     │ Component D │
+└─────────────┘     └─────────────┘
+\`\`\`
+
+### Component Responsibilities
+
+| Component | Responsibility | Data Owned | Dependencies |
+|-----------|---------------|------------|--------------|
+| [A] | [what it does] | [data] | [deps] |
+| [B] | [what it does] | [data] | [deps] |
+
+### Boundary Decisions
+- [Boundary 1]: [What crosses, protocol]
+- [Boundary 2]: [What crosses, protocol]
+
+### Implementation Consistency Rules
+> These rules prevent AI agents from making conflicting implementation choices
+
+- [Rule 1]: [Why this must be consistent]
+- [Rule 2]: [Why this must be consistent]
+```
+
+<!-- GATE -->
+
+## Collaboration Menu (A/P/C)
+
+After generating component design, present choices:
+
+- **[A] Advanced Elicitation** - Use discovery protocols to explore alternative component structures or hidden dependencies
+- **[P] Party Mode** - Bring multiple perspectives to evaluate component boundaries from different angles
+- **[C] Continue** - Save the content and proceed to interface definition
+- **[R] Revise** - Need to reconsider component structure or boundaries
+
+## Advanced Elicitation Mode
+
+When user selects [A]:
+1. Challenge component boundaries with edge cases
+2. Explore alternative decomposition strategies
+3. Identify hidden coupling between components
+4. Question data ownership decisions
+
+## Party Mode
+
+When user selects [P]:
+1. Present component design from multiple viewpoints:
+   - **Domain expert**: Do boundaries align with business concepts?
+   - **Data architect**: Is data ownership clear and consistent?
+   - **DevOps engineer**: How will this deploy and scale?
+   - **New team member**: Can someone understand this quickly?
+2. Synthesize perspectives into refined design
+
+## Success Metrics
+
+- Components clearly defined with single responsibilities
+- Boundaries align with domain concepts
+- Dependencies mapped without cycles
+- Implementation consistency rules documented
+- User confirmed design before proceeding
+
+## Failure Modes
+
+- Ambiguous component responsibilities
+- Unclear boundary decisions
+- Missing consistency rules for AI implementation
+- Proceeding without user confirmation

package/pennyfarthing-dist/workflows/architecture/steps/step-05-interfaces.md

@@ -0,0 +1,133 @@
+# Step 5: Interface Definition
+
+<step-meta>
+number: 5
+name: interface-definition
+gate: false
+</step-meta>
+
+## Mandatory Execution Rules
+
+- READ the complete step file before taking any action
+- DEFINE explicit contracts that prevent implementation ambiguity
+- ALWAYS treat this as collaborative discovery between architectural peers
+- FOCUS on conventions that ensure consistent implementations
+
+## Execution Protocols
+
+- Show your analysis before taking any action
+- Present A/P/C menu after generating interface definitions
+- ONLY save when user chooses [C] Continue
+- Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before loading next step
+- FORBIDDEN to load next step until [C] is selected
+
+## Purpose
+
+Define the APIs, contracts, and communication patterns between components. Establish conventions that ensure consistent implementation across different agents or developers.
+
+## Instructions
+
+1. **Define External APIs**:
+   - What APIs does the system expose?
+   - What authentication/authorization is needed?
+   - What are the request/response formats?
+
+2. **Define Internal Contracts**:
+   - How do components communicate?
+   - Synchronous (HTTP, gRPC) or asynchronous (events, queues)?
+   - What are the message formats?
+
+3. **Establish Conventions**:
+   - Naming conventions
+   - Error handling patterns
+   - Versioning strategy
+
+4. **Document for Consistency**:
+   - Explicit enough that two implementations would be compatible
+   - No room for interpretation on critical contracts
+
+## Actions
+
+- Design: API contracts (OpenAPI, protobuf, or pseudocode)
+- Document: Event schemas if using async
+- Define: Error codes and handling
+- Specify: Conventions that must be followed
+
+## Output
+
+Add to session file:
+
+```markdown
+## Interface Definitions
+
+### External APIs
+
+| Endpoint | Method | Purpose | Auth |
+|----------|--------|---------|------|
+| /api/v1/resource | GET | List resources | Bearer |
+| /api/v1/resource | POST | Create resource | Bearer |
+
+### Internal Communication
+
+| From | To | Type | Contract |
+|------|----|----- |----------|
+| A | B | HTTP | GET /internal/data |
+| B | C | Event | DataUpdated { id, payload } |
+
+### Conventions
+- **Naming**: [snake_case, camelCase, etc.]
+- **Errors**: [HTTP codes, error envelope format]
+- **Versioning**: [URL path, header, etc.]
+
+### Contract Enforcement
+> Rules that ensure consistent implementation
+
+- [Contract 1]: [Exact specification]
+- [Contract 2]: [Exact specification]
+```
+
+## Collaboration Menu (A/P/C)
+
+After generating interface definitions, present choices:
+
+- **[A] Advanced Elicitation** - Use discovery protocols to identify missing contracts or edge cases
+- **[P] Party Mode** - Bring multiple perspectives to evaluate API design from different consumer viewpoints
+- **[C] Continue** - Save the content and proceed to risk assessment
+- **[R] Revise** - Need to reconsider interface design or add missing contracts
+
+## Advanced Elicitation Mode
+
+When user selects [A]:
+1. Identify edge cases in API contracts
+2. Explore error scenarios and handling
+3. Question versioning and backward compatibility
+4. Consider rate limiting and quotas
+
+## Party Mode
+
+When user selects [P]:
+1. Present interface design from multiple viewpoints:
+   - **API consumer**: Is this intuitive to use?
+   - **Security engineer**: Are there auth/authz gaps?
+   - **Mobile developer**: Will this work on constrained networks?
+   - **Integration team**: How will this connect to existing systems?
+2. Synthesize perspectives into refined contracts
+
+## Success Metrics
+
+- External APIs clearly documented
+- Internal contracts specify exact message formats
+- Conventions established for naming, errors, versioning
+- Contracts explicit enough for independent implementation
+- User confirmed interfaces before proceeding
+
+## Failure Modes
+
+- Ambiguous contract specifications
+- Missing error handling definitions
+- Inconsistent naming conventions
+- Proceeding without user confirmation
+
+## Next Step
+
+After user selects [C], proceed to Risk Assessment to identify potential issues.

package/pennyfarthing-dist/workflows/architecture/steps/step-06-risks.md

@@ -0,0 +1,142 @@
+# Step 6: Risk Assessment
+
+<step-meta>
+number: 6
+name: risk-assessment
+gate: true
+</step-meta>
+
+## Mandatory Execution Rules
+
+- READ the complete step file before taking any action
+- IDENTIFY risks specific to AI agent implementation
+- ALWAYS treat this as collaborative discovery between architectural peers
+- FOCUS on risks that could cause implementation divergence
+
+## Execution Protocols
+
+- Show your analysis before taking any action
+- Present A/P/C menu after generating risk assessment
+- ONLY save when user chooses [C] Continue
+- Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` before loading next step
+- FORBIDDEN to load next step until [C] is selected
+
+## Purpose
+
+Identify technical risks, potential failure modes, and mitigation strategies. Include risks specific to AI-assisted implementation.
+
+## Instructions
+
+1. **Identify Technical Risks**:
+   - Performance bottlenecks
+   - Single points of failure
+   - Security vulnerabilities
+   - Data consistency challenges
+   - Operational complexity
+
+2. **Assess Impact and Likelihood**:
+   - What happens if this risk materializes?
+   - How likely is it?
+   - What's the blast radius?
+
+3. **Define Mitigations**:
+   - How can each risk be reduced or eliminated?
+   - What monitoring/alerting is needed?
+   - What's the fallback plan?
+
+4. **AI Implementation Risks** (BMAD pattern):
+   - Where could AI agents misinterpret requirements?
+   - What ambiguities could lead to incompatible implementations?
+   - How do we detect implementation drift early?
+
+## Actions
+
+- Analyze: Each component for failure modes
+- Review: Security considerations
+- Plan: Monitoring and alerting strategy
+- Identify: AI implementation risk points
+
+## Output
+
+Add to session file:
+
+```markdown
+## Risk Assessment
+
+### Technical Risks
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| [Risk 1] | High/Med/Low | High/Med/Low | [Strategy] |
+| [Risk 2] | High/Med/Low | High/Med/Low | [Strategy] |
+
+### Failure Modes
+
+| Component | Failure Mode | Detection | Recovery |
+|-----------|--------------|-----------|----------|
+| [A] | [How it fails] | [Monitoring] | [Steps] |
+| [B] | [How it fails] | [Monitoring] | [Steps] |
+
+### Security Considerations
+- [Authentication approach]
+- [Authorization model]
+- [Data protection measures]
+
+### AI Implementation Risks
+> Risks specific to AI-assisted development
+
+| Risk | Could Cause | Prevention |
+|------|-------------|------------|
+| Ambiguous requirement | Inconsistent implementation | [Clarification needed] |
+| Missing constraint | Invalid assumptions | [Explicit documentation] |
+
+### Operational Readiness
+- Monitoring: [What to watch]
+- Alerting: [Thresholds]
+- Runbooks: [Key procedures needed]
+```
+
+<!-- GATE -->
+
+## Collaboration Menu (A/P/C)
+
+After generating risk assessment, present choices:
+
+- **[A] Advanced Elicitation** - Use discovery protocols to explore hidden risks or unconsidered failure modes
+- **[P] Party Mode** - Bring multiple perspectives to identify risks from different operational angles
+- **[C] Continue** - Save the content and proceed to documentation
+- **[R] Revise** - Need to address unacceptable risks before proceeding
+
+## Advanced Elicitation Mode
+
+When user selects [A]:
+1. Explore cascading failure scenarios
+2. Question security assumptions
+3. Investigate edge cases in error handling
+4. Challenge operational readiness
+
+## Party Mode
+
+When user selects [P]:
+1. Present risk assessment from multiple viewpoints:
+   - **Security auditor**: What attack vectors exist?
+   - **Site reliability engineer**: What will page us at 3am?
+   - **Compliance officer**: What regulatory risks exist?
+   - **Incident responder**: How will we debug failures?
+2. Synthesize perspectives into comprehensive risk register
+
+## Success Metrics
+
+- Technical risks identified with impact assessment
+- Failure modes documented with recovery procedures
+- Security considerations explicitly addressed
+- AI implementation risks identified and mitigated
+- User confirmed risks are acceptable before proceeding
+
+## Failure Modes
+
+- Overlooking critical failure scenarios
+- Underestimating risk impact or likelihood
+- Missing security considerations
+- Not addressing AI implementation risks
+- Proceeding without user confirmation

package/pennyfarthing-dist/workflows/architecture/steps/step-07-document.md

@@ -0,0 +1,160 @@
+# Step 7: Decision Documentation
+
+<step-meta>
+number: 7
+name: documentation
+gate: false
+</step-meta>
+
+## Mandatory Execution Rules
+
+- READ the complete step file before taking any action
+- COMPILE all outputs from previous steps into cohesive document
+- VALIDATE completeness before finalizing
+- ALWAYS treat this as collaborative completion between architectural peers
+
+## Execution Protocols
+
+- Show your analysis before taking any action
+- Validate all sections are complete before generating document
+- Present completion summary and options
+- Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6, 7]`
+- NO MORE STEPS - this is the final step
+
+## Purpose
+
+Consolidate the architecture decision into a formal document (ADR or architecture spec). Validate completeness before finalizing.
+
+## Pre-Documentation Validation
+
+Before compiling the document, verify:
+
+- [ ] Context analysis is complete (Step 2)
+- [ ] Patterns selected with rationale (Step 3)
+- [ ] Components defined with boundaries (Step 4)
+- [ ] Interfaces specified with contracts (Step 5)
+- [ ] Risks assessed with mitigations (Step 6)
+
+If any section is incomplete, report to user before proceeding.
+
+## Instructions
+
+1. **Compile Decision Record**:
+   Gather outputs from all previous steps into a cohesive document:
+   - Context and problem statement
+   - Decision drivers (constraints, concerns)
+   - Considered options
+   - Decision outcome
+   - Consequences
+
+2. **Choose Document Type**:
+   - **ADR**: For significant, reversible decisions
+   - **Architecture Spec**: For system-wide design
+   - **Design Doc**: For feature-level architecture
+
+3. **Finalize and Store**:
+   - Write to appropriate location
+   - Link from session/story
+   - Update architecture index if exists
+
+## Actions
+
+- Validate: All previous step outputs are complete
+- Write: Architecture document using template
+- Store: In `docs/adr/` or `docs/architecture/`
+- Update: Any architecture index or registry
+
+## Output
+
+Create `{output_file}` using the template, containing:
+
+```markdown
+# ADR-NNNN: [Decision Title]
+
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Date:** {date}
+**Author:** {agent} ({persona})
+
+## Context
+
+[Summary from Step 2 - Context Analysis]
+
+## Decision Drivers
+
+[Key concerns from Step 2]
+
+## Considered Options
+
+[Patterns from Step 3 with trade-offs]
+
+## Decision Outcome
+
+[Selected pattern(s) and rationale]
+
+### Component Structure
+
+[From Step 4]
+
+### Interfaces
+
+[From Step 5]
+
+## Consequences
+
+### Positive
+- [Benefits]
+
+### Negative
+- [Trade-offs accepted]
+
+### Risks and Mitigations
+[From Step 6]
+
+## Implementation Consistency Rules
+
+[Rules that ensure AI agents implement consistently]
+
+## Related Decisions
+
+- [Links to related ADRs]
+```
+
+## Completion Menu
+
+After generating document, present completion options:
+
+- **[V] Validate** - Run comprehensive validation checks on the complete architecture
+- **[E] Edit** - Make revisions to specific sections
+- **[C] Complete** - Finalize document and end workflow
+- **[R] Restart Section** - Go back to a specific step
+
+## Validation Checks
+
+When user selects [V]:
+1. Verify all PRD requirements have corresponding architecture decisions
+2. Check component boundaries align with domain concepts
+3. Validate interfaces are complete and consistent
+4. Confirm risks have appropriate mitigations
+5. Report validation results with any gaps
+
+## Completion
+
+The architecture workflow is complete. The decision document is ready for review.
+
+**Next steps:**
+1. Review document with stakeholders
+2. Update status to "Accepted" after approval
+3. Begin implementation planning
+
+## Success Metrics
+
+- All previous step outputs compiled into document
+- Validation checks passed
+- Document written to appropriate location
+- User confirmed completion
+
+## Failure Modes
+
+- Missing sections from previous steps
+- Incomplete validation
+- Not confirming completion with user