@pennyfarthing/core 9.2.0 → 9.3.0

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

@@ -1,150 +0,0 @@
-# Step 4: Component Design
-
-<purpose>
-Define major system components, their responsibilities, boundaries, and dependencies based on selected patterns. Establish implementation consistency rules that prevent AI agents from making conflicting architectural choices.
-</purpose>
-
-<instructions>
-Identify primary components from selected patterns with clear responsibilities and data ownership. Define component boundaries and communication protocols. Map component dependencies. Document explicit consistency rules for AI implementation to ensure compatible implementations across different agents.
-</instructions>
-
-<output>
-Component Design section with ASCII/Mermaid component diagram, Component Responsibilities table, Boundary Decisions, and Implementation Consistency Rules. Update frontmatter stepsCompleted array after user confirms [C].
-</output>
-
-<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,145 +0,0 @@
-# Step 5: Interface Definition
-
-<purpose>
-Define APIs, internal contracts, and communication patterns between components. Establish naming conventions, error handling, and versioning strategies that ensure explicit, unambiguous contracts for consistent implementation.
-</purpose>
-
-<instructions>
-Define external APIs with authentication and request/response formats. Specify internal component communication (synchronous/asynchronous) with exact message formats. Establish naming conventions, error codes, and versioning strategy. Document contract enforcement rules explicit enough for independent implementations.
-</instructions>
-
-<output>
-Interface Definitions section with External APIs table, Internal Communication protocols, Conventions documented, and Contract Enforcement rules. Update frontmatter stepsCompleted array after user confirms [C].
-</output>
-
-<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,154 +0,0 @@
-# Step 6: Risk Assessment
-
-<purpose>
-Identify technical risks, failure modes, and mitigation strategies. Include risks specific to AI-assisted implementation such as ambiguous requirements or inconsistent interpretations that could cause implementation divergence.
-</purpose>
-
-<instructions>
-Identify technical risks (bottlenecks, single points of failure, security, data consistency, operational complexity). Assess impact/likelihood for each. Define mitigations and monitoring/alerting strategies. Identify AI implementation risks where agents might misinterpret requirements or diverge on implementation.
-</instructions>
-
-<output>
-Risk Assessment section with Technical Risks table, Failure Modes with recovery procedures, Security Considerations, AI Implementation Risks, and Operational Readiness plan. Update frontmatter stepsCompleted array after user confirms [C].
-</output>
-
-<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,172 +0,0 @@
-# Step 7: Decision Documentation
-
-<purpose>
-Consolidate all architecture decisions from previous steps into a formal Architecture Decision Record (ADR) or specification. Validate completeness and finalize the decision document for stakeholder review.
-</purpose>
-
-<instructions>
-Validate all previous step outputs are complete before proceeding. Choose appropriate document type (ADR/Architecture Spec/Design Doc). Compile comprehensive decision record including context, drivers, options, outcome, components, interfaces, risks, and consistency rules. Write to appropriate location with proper linking.
-</instructions>
-
-<output>
-Finalized architecture decision document (ADR or spec format) stored in docs/adr/ or appropriate location, with complete sections from all previous steps, validation confirmation, and completion summary. Update frontmatter stepsCompleted array with all steps completed.
-</output>
-
-<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