@forwardimpact/pathway 0.1.0 → 0.2.0

package/examples/capabilities/business.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/capability.schema.json
+
 name: Business
 emoji: 💼
 displayOrder: 8
@@ -5,40 +7,6 @@ description: |
   Understanding and driving business value.
   Includes domain knowledge, stakeholder management, strategic thinking,
   and translating between technical and business contexts.
-transitionChecklists:
-  plan_to_code:
-    foundational:
-      - Business context is understood
-      - User needs are identified
-    working:
-      - Business requirements are documented
-      - Stakeholder expectations are aligned
-      - Value proposition is clear
-    practitioner:
-      - Business impact is quantified
-      - Strategic alignment is verified
-      - Cross-team business needs are considered
-    expert:
-      - Enterprise business goals are addressed
-      - Strategic technology decisions are aligned
-      - Executive stakeholders are engaged
-  code_to_review:
-    foundational:
-      - Solution addresses the stated business need
-      - User-facing behavior is correct
-      - Business requirements are met
-    working:
-      - Stakeholder feedback is incorporated
-      - Business value is delivered
-      - Success metrics can be measured
-    practitioner:
-      - Cross-team business requirements are met
-      - ROI is demonstrable
-      - Business risks are mitigated
-    expert:
-      - Strategic business outcomes are enabled
-      - Enterprise value is created
-      - Business innovation is demonstrated
 professionalResponsibilities:
   awareness:
     Understand the business context for your assigned work and communicate
@@ -134,118 +102,88 @@ skills:
           initiatives.
     agent:
       name: technical-writing
-      description: >
+      description: |
         Guide for creating clear technical documentation. Use when writing
-        READMEs,
-
-        API docs, specifications, or any technical content that needs to be
-        clear
-
-        and accurate.
-      body: |
-        # Technical Writing
-
-        ## When to use this skill
+        READMEs, API docs, specifications, or any technical content that needs
+        to be clear and accurate.
+      stages:
+        specify:
+          focus: |
+            Define documentation requirements and audience needs.
+            Clarify what the documentation must accomplish.
+          activities:
+            - Identify target audience and their skill level
+            - Document what questions the docs must answer
+            - Define documentation type (README, API, spec, tutorial)
+            - Specify accuracy and completeness requirements
+            - Mark ambiguities with [NEEDS CLARIFICATION]
+          ready:
+            - Audience is identified
+            - Questions to answer are documented
+            - Documentation type is chosen
+            - Requirements are clear
+        plan:
+          focus: Understanding audience and planning documentation
+          activities:
+            - Identify target audience and their needs
+            - Determine document type and structure
+            - List prerequisites and assumptions
+            - Outline key sections and content
+          ready:
+            - Audience is identified
+            - Document type and structure planned
+            - Prerequisites listed
+            - Outline complete
+        code:
+          focus: Writing clear and accurate documentation
+          activities:
+            - Write using simple, direct language
+            - Structure content for scanning
+            - Include tested, runnable examples
+            - Define technical terms
+          ready:
+            - Purpose clear in first paragraph
+            - Examples are tested and work
+            - Technical terms are defined
+            - Structure supports scanning
+        review:
+          focus: Verifying documentation quality
+          activities:
+            - Check accuracy against implementation
+            - Verify examples are runnable
+            - Review for clarity and completeness
+            - Test with target audience if possible
+          ready:
+            - Documentation matches implementation
+            - All examples verified working
+            - No ambiguous pronouns
+            - Structure is logical and complete
+        deploy:
+          focus: |
+            Publish documentation and ensure it reaches the audience.
+            Set up maintenance process.
+          activities:
+            - Publish to documentation site
+            - Announce to relevant teams
+            - Add to search indexes and navigation
+            - Establish update and review schedule
+          ready:
+            - Documentation is published and accessible
+            - Audience can discover and find it
+            - Search and navigation are updated
+            - Maintenance schedule is established
+      reference: |
+        ## Document Types
 
-        Use this skill when:
-        - Writing README files
-        - Creating API documentation
-        - Writing technical specifications
-        - Documenting code and systems
-        - Creating guides and tutorials
+        | Type | Purpose | Key Sections |
+        |------|---------|--------------|
+        | README | Project overview | Description, Getting Started, Usage |
+        | API Docs | API reference | Endpoints, Parameters, Examples |
+        | Spec | Design proposal | Problem, Solution, Alternatives |
+        | Tutorial | Learning guide | Objective, Steps, Outcomes |
 
         ## Writing Principles
-
-        ### Clarity First
         - Use simple, direct language
         - One idea per sentence
         - Active voice over passive
-        - Avoid jargon unless defined
-        - Be specific, not vague
-
-        ### Know Your Audience
-        - What do they already know?
-        - What do they need to accomplish?
-        - What's their skill level?
-        - What questions will they have?
-
-        ### Structure for Scanning
-        - Lead with the most important information
-        - Use headings and subheadings
-        - Keep paragraphs short
-        - Use lists for multiple items
-        - Highlight key terms
-
-        ## Document Types
-
-        ### README
-        - What is this project?
-        - How do I get started?
-        - How do I use it?
-        - Where do I get help?
-
-        ### API Documentation
-        - Endpoint description
-        - Parameters and types
-        - Request/response examples
-        - Error codes and handling
-
-        ### Technical Specification
-        - Problem statement
-        - Proposed solution
-        - Alternatives considered
-        - Implementation plan
-
-        ### Tutorial
-        - Clear learning objective
-        - Prerequisites listed
-        - Step-by-step instructions
-        - Expected outcomes shown
-
-        ## README Template
-
-        ```markdown
-        # Project Name
-
-        Brief description of what this project does.
-
-        ## Getting Started
-
-        ### Prerequisites
-        - Required software and versions
-
-        ### Installation
-        Step-by-step installation instructions.
-
-        ### Quick Start
-        Minimal example to get running.
-
-        ## Usage
-        Common use cases with examples.
-
-        ## Contributing
-        How to contribute to the project.
-
-        ## License
-        License information.
-        ```
-
-        ## Code Examples
-
-        Good examples are:
-        - Complete and runnable
-        - Minimal but realistic
-        - Copy-pasteable
-        - Annotated with comments
-        - Tested and verified
-
-        ## Technical Writing Checklist
-
-        - [ ] Purpose is clear in first paragraph
-        - [ ] Audience is identified
-        - [ ] Prerequisites are listed
-        - [ ] Examples are tested and work
-        - [ ] Technical terms are defined
-        - [ ] Structure supports scanning
-        - [ ] No ambiguous pronouns
-        - [ ] Updated when code changes
+        - Lead with most important info

package/examples/capabilities/delivery.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/capability.schema.json
+
 name: Delivery
 emoji: 🚀
 displayOrder: 1
@@ -5,40 +7,6 @@ description: |
   Building and shipping solutions that solve real problems.
   Encompasses full-stack development, data integration, problem discovery,
   and rapid prototyping.
-transitionChecklists:
-  plan_to_code:
-    foundational:
-      - Requirements are understood and documented
-      - Acceptance criteria are defined
-    working:
-      - Technical approach is documented
-      - Dependencies are identified and planned for
-      - Scope is broken into deliverable increments
-    practitioner:
-      - Cross-team dependencies are coordinated
-      - Risks are identified with mitigation strategies
-      - Delivery timeline is realistic and communicated
-    expert:
-      - Strategic alignment is validated with stakeholders
-      - Resource allocation is optimized across teams
-      - Success metrics are defined and measurable
-  code_to_review:
-    foundational:
-      - Feature works end-to-end
-      - Basic tests cover critical paths
-      - Code is self-reviewed before submitting
-    working:
-      - All acceptance criteria are met
-      - Edge cases are handled
-      - Technical debt is explicitly documented
-    practitioner:
-      - Solution addresses cross-team requirements
-      - Integration points are tested
-      - Rollback plan exists
-    expert:
-      - Organizational standards are followed
-      - Pattern can be reused across teams
-      - Documentation enables others to extend
 professionalResponsibilities:
   awareness:
     Complete assigned implementation tasks within established patterns with
@@ -109,133 +77,90 @@ skills:
         Guide for designing software systems and making architectural decisions.
         Use when asked to design a system, evaluate architecture options, or
         make structural decisions about code organization.
-      body: >
-        # Architecture & Design
-
-
-        ## When to use this skill
-
-
-        Use this skill when:
-
-        - Designing new systems or major features
-
-        - Evaluating architectural options and trade-offs
-
-        - Making decisions about code organization and structure
-
-        - Reviewing or improving existing architecture
-
-
-        ## Design Process
-
-
-        ### 1. Understand Requirements
-
-
-        Before designing, clarify:
-
-        - What problem are we solving?
-
-        - What are the non-functional requirements (scale, latency,
-        availability)?
-
-        - What are the constraints (existing systems, team skills, timeline)?
-
-        - What will change over time?
-
-
-        ### 2. Identify Key Decisions
-
-
-        Architecture is the set of decisions that are hard to change:
-
-        - Data storage and schema design
-
-        - Service boundaries and communication patterns
-
-        - Synchronous vs asynchronous processing
-
-        - Stateful vs stateless components
-
-
-        ### 3. Evaluate Trade-offs
-
-
-        Every architectural choice has trade-offs:
-
-        - Consistency vs availability
-
-        - Simplicity vs flexibility
-
-        - Performance vs maintainability
-
-        - Build vs buy
-
-
-        Document trade-offs explicitly.
-
-
-        ### 4. Design for Change
-
-
-        Good architecture accommodates change:
-
-        - Separate what changes from what stays the same
-
-        - Define clear interfaces between components
-
-        - Prefer composition over inheritance
-
-        - Make dependencies explicit
-
-
+      stages:
+        specify:
+          focus: |
+            Define system requirements and constraints before design.
+            Clarify functional and non-functional requirements.
+          activities:
+            - Document functional requirements and use cases
+            - Identify non-functional requirements (scale, latency,
+              availability)
+            - Document system constraints and integration points
+            - Identify stakeholders and their concerns
+            - Mark ambiguities with [NEEDS CLARIFICATION]
+          ready:
+            - Functional requirements are documented
+            - Non-functional requirements are specified
+            - Constraints are identified
+            - Stakeholder concerns are understood
+        plan:
+          focus: Understanding requirements and designing solutions
+          activities:
+            - Gather context about existing systems and constraints
+            - Clarify non-functional requirements (scale, latency, availability)
+            - Identify key decisions that are hard to change later
+            - Evaluate trade-offs between architectural options
+            - Document approach with rationale
+          ready:
+            - Requirements are clearly understood
+            - Key decisions are documented with rationale
+            - Trade-offs are explicit
+            - Dependencies are identified
+        code:
+          focus: Implementing architecture faithfully while adapting to reality
+          activities:
+            - Verify implementation aligns with design decisions
+            - Implement interfaces and boundaries before internals
+            - Document any deviations from design with rationale
+            - Keep architecture documentation in sync with implementation
+          ready:
+            - Implementation matches documented design
+            - Deviations documented with rationale
+            - Failure modes are considered and handled
+            - Security implications are reviewed
+        review:
+          focus: Verifying architecture implementation and documentation
+          activities:
+            - Compare implementation to design documentation
+            - Verify all decisions were followed or documented
+            - Assess maintainability and extensibility
+            - Ensure architecture enables future changes
+          ready:
+            - Design docs reflect actual implementation
+            - Architecture decisions validated in practice
+            - Scalability requirements addressed
+        deploy:
+          focus: |
+            Deploy architecture and verify it performs as designed
+            in production environment.
+          activities:
+            - Deploy system components to production
+            - Verify architectural boundaries work under load
+            - Monitor performance against requirements
+            - Document any operational learnings
+          ready:
+            - System deployed successfully
+            - Performance meets requirements
+            - Monitoring confirms design assumptions
+            - Operational procedures are documented
+      reference: |
         ## Common Patterns
 
-
         ### Service Architecture
-
-        - Microservices: Independent deployment, clear boundaries
-
-        - Monolith: Simpler deployment, easier refactoring
-
-        - Modular monolith: Boundaries within single deployment
-
+        - **Microservices**: Independent deployment, clear boundaries
+        - **Monolith**: Simpler deployment, easier refactoring
+        - **Modular monolith**: Boundaries within single deployment
 
         ### Data Patterns
-
-        - Event sourcing: Full audit trail, complex queries
-
-        - CQRS: Separate read and write models
-
-        - Repository pattern: Abstract data access
-
+        - **Event sourcing**: Full audit trail, complex queries
+        - **CQRS**: Separate read and write models
+        - **Repository pattern**: Abstract data access
 
         ### Communication Patterns
-
-        - REST: Synchronous, request-response
-
-        - Event-driven: Asynchronous, loose coupling
-
-        - gRPC: Efficient, strongly typed
-
-
-        ## Architecture Checklist
-
-
-        - [ ] Requirements are clearly understood
-
-        - [ ] Key decisions are documented with rationale
-
-        - [ ] Trade-offs are explicit
-
-        - [ ] Failure modes are considered
-
-        - [ ] Scalability requirements are addressed
-
-        - [ ] Security implications are reviewed
-
-        - [ ] Dependencies are minimal and explicit
+        - **REST**: Synchronous, request-response
+        - **Event-driven**: Asynchronous, loose coupling
+        - **gRPC**: Efficient, strongly typed
   - id: full_stack_development
     name: Full-Stack Development
     human:
@@ -270,24 +195,78 @@ skills:
           polymathic engineering.
     agent:
       name: full-stack-development
-      description: >
+      description: |
         Guide for building complete solutions across the full technology stack.
-
-        Use when asked to implement features spanning frontend, backend,
-        database,
-
+        Use when implementing features spanning frontend, backend, database,
         and infrastructure layers.
-      body: |
-        # Full-Stack Development
-
-        ## When to use this skill
-
-        Use this skill when:
-        - Building features that span multiple layers
-        - Implementing end-to-end functionality
-        - Working across frontend, backend, and infrastructure
-        - Debugging issues that cross layer boundaries
-
+      stages:
+        specify:
+          focus: |
+            Define full-stack feature requirements and acceptance criteria.
+            Clarify user needs and system integration points.
+          activities:
+            - Identify user stories and acceptance criteria
+            - Document expected user interactions
+            - Clarify integration requirements with existing systems
+            - Define non-functional requirements (performance, security)
+            - Mark ambiguities with [NEEDS CLARIFICATION]
+          ready:
+            - User stories are documented
+            - Acceptance criteria are defined
+            - Integration points are identified
+            - Non-functional requirements are clear
+        plan:
+          focus: Designing the complete solution across layers
+          activities:
+            - Define the API contract between frontend and backend
+            - Design database schema to support the feature
+            - Plan infrastructure requirements
+            - Identify cross-layer dependencies
+          ready:
+            - API contract is defined
+            - Database schema is designed
+            - Infrastructure needs identified
+            - Layer boundaries are clear
+        code:
+          focus: Building vertically across all layers
+          activities:
+            - Implement backend API endpoints
+            - Build frontend components and integrate with API
+            - Set up database migrations and queries
+            - Configure infrastructure as code
+            - Test across layer boundaries
+          ready:
+            - Frontend connects to backend correctly
+            - Database schema supports the feature
+            - Error handling spans all layers
+            - Feature works end-to-end
+        review:
+          focus: Verifying integration across the stack
+          activities:
+            - Test complete user flows end-to-end
+            - Verify error handling at each layer
+            - Check deployment pipeline works
+            - Validate monitoring and logging
+          ready:
+            - End-to-end tests pass
+            - Deployment is automated
+            - Cross-layer errors are handled gracefully
+        deploy:
+          focus: |
+            Deploy full-stack feature to production and verify end-to-end
+            functionality in live environment.
+          activities:
+            - Deploy backend services
+            - Deploy frontend changes
+            - Run database migrations
+            - Verify feature works in production
+            - Monitor for errors and performance issues
+          ready:
+            - All components deployed successfully
+            - Feature works end-to-end in production
+            - No errors in monitoring
+            - Performance meets requirements
+      reference: |
         ## Technology Stack
 
         ### Primary Languages
@@ -301,52 +280,9 @@ skills:
 
         ## Layer Responsibilities
 
-        ### Frontend
-        - User interface and experience
-        - Client-side validation
-        - API integration
-        - State management
-
-        ### Backend API
-        - Business logic
-        - Data validation
-        - Authentication/authorization
-        - External service integration
-
-        ### Database
-        - Data persistence
-        - Query optimization
-        - Schema migrations
-        - Data integrity
-
-        ### Infrastructure
-        - Deployment pipelines
-        - Environment configuration
-        - Scaling and reliability
-        - Monitoring and logging
-
-        ## Development Process
-
-        ### 1. Start with the Interface
-        - Define the API contract first
-        - Frontend and backend can work in parallel
-        - Clear interface = fewer integration issues
-
-        ### 2. Build Vertically
-        - Complete one feature end-to-end before starting another
-        - Validates assumptions early
-        - Delivers demonstrable progress
-
-        ### 3. Test Across Layers
-        - Unit tests per layer
-        - Integration tests across layers
-        - End-to-end tests for critical paths
-
-        ## Full-Stack Checklist
-
-        - [ ] API contract is defined
-        - [ ] Frontend connects to backend correctly
-        - [ ] Database schema supports the feature
-        - [ ] Error handling spans all layers
-        - [ ] Feature works end-to-end
-        - [ ] Deployment is automated
+        | Layer | Responsibilities |
+        |-------|-----------------|
+        | Frontend | UI/UX, client validation, API integration |
+        | Backend | Business logic, auth, external services |
+        | Database | Persistence, queries, migrations |
+        | Infrastructure | Deployment, scaling, monitoring |