@pennyfarthing/core 7.4.1 → 7.5.0

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

@@ -1,133 +0,0 @@
-# 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

@@ -1,138 +0,0 @@
-# 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

@@ -1,133 +0,0 @@
-# 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

@@ -1,142 +0,0 @@
-# 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

@@ -1,160 +0,0 @@
-# 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