@forwardimpact/pathway 0.4.0 → 0.5.0

package/examples/stages.yaml

@@ -2,9 +2,10 @@
 
 - id: specify
   name: Specify
-  emoji: "🎯"
+  emojiIcon: "🎯"
   description:
-    Define What and Why - User stories, acceptance criteria, requirements
+    Your primary task is to define WHAT users need and WHY, not how to build it.
+    Gather requirements, write user stories, and define acceptance criteria.
   handoffs:
     - targetStage: specify
       label: Refine Spec
@@ -28,9 +29,10 @@
 
 - id: plan
   name: Plan
-  emoji: "📐"
+  emojiIcon: "📐"
   description:
-    Define How - Technology choices, architecture, contracts, data models
+    Your primary task is to define HOW to build the solution. Make technology
+    choices, design architecture, define contracts and data models.
   handoffs:
     - targetStage: plan
       label: Refine Plan
@@ -57,8 +59,10 @@
 
 - id: code
   name: Code
-  emoji: "💻"
-  description: Build and Iterate - Implement, test, refine
+  emojiIcon: "💻"
+  description:
+    Your primary task is to implement the solution. Write code, write tests, and
+    iterate until the implementation is complete.
   handoffs:
     - targetStage: review
       label: Request Review
@@ -78,8 +82,10 @@
 
 - id: review
   name: Review
-  emoji: "🔍"
-  description: Verify and Ship - Review, approve, document
+  emojiIcon: "🔍"
+  description:
+    Your primary task is to verify the implementation works correctly. Run the
+    application, test against acceptance criteria, document findings.
   handoffs:
     - targetStage: code
       label: Request Changes
@@ -109,8 +115,10 @@
 
 - id: deploy
   name: Deploy
-  emoji: "🚀"
-  description: Ship to Production - Push, monitor workflows, verify deployment
+  emojiIcon: "🚀"
+  description:
+    Your primary task is to ship the changes to production. Push code, monitor
+    CI/CD workflows, and verify successful deployment.
   handoffs:
     - targetStage: code
       label: Fix Pipeline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Engineering Pathway framework for human and AI collaboration",
   "license": "Apache-2.0",
   "repository": {
@@ -59,6 +59,7 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "mustache": "^4.2.0",
+    "simple-icons": "^16.7.0",
     "yaml": "^2.3.4"
   },
   "devDependencies": {

package/templates/agent.template.md

@@ -1,9 +1,25 @@
 ---
-
-{{#name}}name: {{name}} {{/name}}description: {{{description}}} {{#infer}}infer:
-{{infer}} {{/infer}}{{#handoffs.length}}handoffs: {{#handoffs}} - label:
-{{label}} {{#agent}} agent: {{agent}} {{/agent}} prompt: "{{{prompt}}}"
-{{#send}} send: {{send}} {{/send}}{{/handoffs}}{{/handoffs.length}}---
+{{#name}}
+name: {{name}}
+{{/name}}
+description: {{{description}}}
+{{#infer}}
+infer: {{infer}}
+{{/infer}}
+{{#handoffs.length}}
+handoffs:
+{{#handoffs}}
+  - label: {{label}}
+{{#agent}}
+    agent: {{agent}}
+{{/agent}}
+    prompt: "{{{prompt}}}"
+{{#send}}
+    send: {{send}}
+{{/send}}
+{{/handoffs}}
+{{/handoffs.length}}
+---
 
 # {{title}}
 
@@ -13,29 +29,43 @@
 
 {{{identity}}}
 
-{{#priority}} {{{priority}}}
+{{#priority}}
+{{{priority}}}
+
+{{/priority}}
+{{#hasSkills}}
+## Available Skills
 
-{{/priority}} {{#capabilities.length}} Your primary capabilities:
-{{#capabilities}}
+IMPORTANT: Before starting work, read the relevant skill file for project-specific
+guidance. Do not rely solely on pre-training knowledge.
 
-- {{{.}}} {{/capabilities}}
+| Skill | Location | Use When |
+|-------|----------|----------|
+{{#skillIndex}}
+| {{{name}}} | `.claude/skills/{{dirname}}/SKILL.md` | {{{useWhen}}} |
+{{/skillIndex}}
 
-{{/capabilities.length}} {{#beforeMakingChanges.length}} Before making changes:
-{{#beforeMakingChanges}} {{index}}. {{{text}}} {{/beforeMakingChanges}}
+{{/hasSkills}}
+{{#beforeMakingChanges.length}}
+Before making changes:
 
-{{/beforeMakingChanges.length}} {{#delegation}}
+{{#beforeMakingChanges}}
+{{index}}. {{{text}}}
+{{/beforeMakingChanges}}
+{{/beforeMakingChanges.length}}
 
+{{#delegation}}
 ## Delegation
 
 {{{delegation}}}
-
 {{/delegation}}
 
 ## Operational Context
 
 {{{operationalContext}}}
 
-{{{workingStyle}}} {{#beforeHandoff}}
+{{{workingStyle}}}
+{{#beforeHandoff}}
 
 ## Before Handoff
 
@@ -57,9 +87,9 @@ When completing work (for handoff or as a subagent), provide:
 3. **Recommendation**: Ready for next stage, or needs more work
 
 {{#constraints.length}}
-
 ## Constraints
 
 {{#constraints}}
-
-- {{{.}}} {{/constraints}} {{/constraints.length}}
+- {{{.}}}
+{{/constraints}}
+{{/constraints.length}}

package/templates/job.template.md

@@ -1,8 +1,8 @@
-# {{title}}
+# {{{title}}}
 
-- **Level:** {{gradeId}}
-- **Experience:** {{typicalExperienceRange}}
-{{#trackName}}- **Track:** {{trackName}}
+- **Level:** {{{gradeId}}}
+- **Experience:** {{{typicalExperienceRange}}}
+{{#trackName}}- **Track:** {{{trackName}}}
 {{/trackName}}
 
 ## ROLE SUMMARY
@@ -21,21 +21,21 @@
 ## ROLE RESPONSIBILITIES
 
 {{#responsibilities}}
-- **{{capabilityName}}:** {{responsibility}}
+- **{{{capabilityName}}}:** {{{responsibility}}}
 {{/responsibilities}}
 
 ## ROLE BEHAVIOURS
 
 {{#behaviours}}
-- **{{behaviourName}}:** {{maturityDescription}}
+- **{{{behaviourName}}}:** {{{maturityDescription}}}
 {{/behaviours}}
 
 {{#skillLevels}}
 
-## {{levelHeading}}
+## {{{levelHeading}}}
 
 {{#skills}}
-- **{{skillName}}:** {{levelDescription}}
+- **{{{skillName}}}:** {{{levelDescription}}}
 {{/skills}}
 
 {{/skillLevels}}

package/templates/skill.template.md

@@ -1,18 +1,19 @@
 ---
-
 name: {{name}}
 description: |
-{{#descriptionLines}}  {{{.}}}
+{{#descriptionLines}}
+  {{{.}}}
 {{/descriptionLines}}
-
-{{#useWhenLines.length}}  **Use When:** {{#useWhenLines}}{{{.}}}
-{{/useWhenLines}}{{/useWhenLines.length}}---
+{{#useWhenLines.length}}
+  **Use When:** {{#useWhenLines}}{{{.}}}{{/useWhenLines}}
+{{/useWhenLines.length}}
+---
 
 # {{{title}}}
 
 {{#useWhenLines.length}}
-**Use This Skill When:** {{#useWhenLines}}{{{.}}}
-{{/useWhenLines}}{{/useWhenLines.length}}
+**Use This Skill When:** {{#useWhenLines}}{{{.}}}{{/useWhenLines}}
+{{/useWhenLines.length}}
 
 ## Stage Guidance
 {{#stages}}
@@ -40,8 +41,10 @@ description: |
 {{#toolReferences}}
 | {{#url}}[{{{name}}}]({{{url}}}){{/url}}{{^url}}{{{name}}}{{/url}} | {{{useWhen}}} |
 {{/toolReferences}}
-{{/toolReferences.length}} {{#reference}}
+{{/toolReferences.length}}
+{{#reference}}
 
 ## Reference
 
-{{{reference}}} {{/reference}}
+{{{reference}}}
+{{/reference}}

package/examples/agents/.claude/skills/architecture-design/SKILL.md

@@ -1,130 +0,0 @@
----
-name: architecture-design
-description: |
-  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.
----
-
-# Architecture & Design
-
-## Stage Guidance
-
-### Plan Stage
-
-**Focus:** Understand requirements and identify key architectural decisions.
-Document trade-offs and design rationale.
-
-**Activities:**
-
-- Clarify functional and non-functional requirements
-- Identify constraints (existing systems, team skills, timeline)
-- Document key decisions and trade-offs
-- Design for anticipated change
-
-**Ready for Code when:**
-
-- [ ] Requirements are clearly understood
-- [ ] Key decisions are documented with rationale
-- [ ] Trade-offs are explicit
-- [ ] Failure modes are considered
-
-### Code Stage
-
-**Focus:** Implement architecture with clear boundaries and interfaces. Ensure
-components can evolve independently.
-
-**Activities:**
-
-- Define clear interfaces between components
-- Implement with appropriate patterns
-- Document design decisions in code
-- Test architectural boundaries
-
-**Ready for Review when:**
-
-- [ ] Dependencies are minimal and explicit
-- [ ] Interfaces are well-defined
-- [ ] Design patterns are documented
-- [ ] Architecture tests pass
-
-### Review Stage
-
-**Focus:** Validate architecture meets requirements and is maintainable. Ensure
-scalability and security are addressed.
-
-**Activities:**
-
-- Verify architecture meets requirements
-- Review for scalability concerns
-- Check security implications
-- Validate documentation completeness
-
-**Ready for Complete when:**
-
-- [ ] Scalability requirements are addressed
-- [ ] Security implications are reviewed
-- [ ] Architecture is documented
-- [ ] Design is maintainable
-
-## Reference
-
-## 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
-
-## Common Patterns
-
-### Service Architecture
-
-- 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
-
-### Communication Patterns
-
-- REST: Synchronous, request-response
-- Event-driven: Asynchronous, loose coupling
-- gRPC: Efficient, strongly typed

package/examples/agents/.claude/skills/cloud-platforms/SKILL.md

@@ -1,131 +0,0 @@
----
-name: cloud-platforms
-description: |
-  Guide for working with cloud infrastructure and services. Use when
-  deploying to cloud, selecting cloud services, configuring infrastructure,
-  or solving cloud-specific challenges.
----
-
-# Cloud Platforms
-
-## Stage Guidance
-
-### Plan Stage
-
-**Focus:** Select appropriate cloud services and design for availability,
-security, and cost efficiency.
-
-**Activities:**
-
-- Identify service requirements
-- Select appropriate cloud services
-- Plan for high availability
-- Consider security and cost
-
-**Ready for Code when:**
-
-- [ ] Service selection matches requirements
-- [ ] Availability approach planned
-- [ ] Security model defined
-- [ ] Cost controls considered
-
-### Code Stage
-
-**Focus:** Implement cloud infrastructure with security best practices. Use
-infrastructure as code for reproducibility.
-
-**Activities:**
-
-- Define infrastructure as code
-- Configure security groups and IAM
-- Set up monitoring and alerting
-- Implement deployment automation
-
-**Ready for Review when:**
-
-- [ ] Multi-AZ deployment for availability
-- [ ] Security groups properly configured
-- [ ] IAM follows least privilege
-- [ ] Data encrypted at rest and in transit
-- [ ] Infrastructure defined as code
-
-### Review Stage
-
-**Focus:** Validate security, availability, and operational readiness. Ensure
-cost controls are in place.
-
-**Activities:**
-
-- Verify security configuration
-- Test availability and failover
-- Review cost projections
-- Validate monitoring coverage
-
-**Ready for Complete when:**
-
-- [ ] Security review completed
-- [ ] Monitoring and alerting in place
-- [ ] Cost controls established
-- [ ] Operational runbooks exist
-
-## Reference
-
-## Service Categories
-
-### Compute
-
-- **VMs/EC2**: Full control, any workload
-- **Containers/ECS/GKE**: Portable, scalable applications
-- **Serverless/Lambda**: Event-driven, pay-per-use
-- **Kubernetes**: Container orchestration at scale
-
-### Storage
-
-- **Object Storage (S3/GCS)**: Unstructured data, backups, static assets
-- **Block Storage (EBS)**: VM disks, databases
-- **File Storage (EFS)**: Shared file systems
-- **Archive (Glacier)**: Long-term, infrequent access
-
-### Databases
-
-- **Managed SQL (RDS/Cloud SQL)**: Relational, ACID transactions
-- **NoSQL (DynamoDB/Firestore)**: Flexible schema, high scale
-- **Cache (ElastiCache/Memorystore)**: Low-latency data access
-- **Data Warehouse (Redshift/BigQuery)**: Analytics at scale
-
-### Messaging
-
-- **Queues (SQS/Cloud Tasks)**: Decoupled processing
-- **Pub/Sub (SNS/Cloud Pub/Sub)**: Event distribution
-- **Streaming (Kinesis/Dataflow)**: Real-time data processing
-
-## Cloud-Native Design
-
-### Principles
-
-- Design for failure (everything fails eventually)
-- Use managed services when possible
-- Automate everything (infrastructure as code)
-- Monitor and alert on all services
-
-### High Availability
-
-- Deploy across multiple availability zones
-- Use load balancers for traffic distribution
-- Implement health checks and auto-healing
-- Design for graceful degradation
-
-### Security
-
-- Principle of least privilege for IAM
-- Encrypt data at rest and in transit
-- Use security groups and network policies
-- Rotate credentials regularly
-
-## Cost Optimization
-
-- Right-size instances based on actual usage
-- Use reserved instances for predictable workloads
-- Leverage spot/preemptible instances for fault-tolerant work
-- Set up billing alerts and budgets
-- Delete unused resources

package/examples/agents/.claude/skills/code-quality-review/SKILL.md

@@ -1,108 +0,0 @@
----
-name: code-quality-review
-description: |
-  Guide for reviewing code quality, identifying issues, and suggesting
-  improvements. Use when asked to review code, check for best practices,
-  or conduct code reviews.
----
-
-# Code Quality & Review
-
-## Stage Guidance
-
-### Plan Stage
-
-**Focus:** Understand code review scope and establish review criteria. Consider
-what quality standards apply.
-
-**Activities:**
-
-- Identify code review scope
-- Understand applicable standards
-- Plan review approach
-- Consider risk level
-
-**Ready for Code when:**
-
-- [ ] Review scope is clear
-- [ ] Standards are understood
-- [ ] Review approach is planned
-- [ ] Risk level is assessed
-
-### Code Stage
-
-**Focus:** Write clean, maintainable, tested code. Follow project conventions
-and ensure adequate coverage.
-
-**Activities:**
-
-- Write readable, well-structured code
-- Add appropriate tests
-- Follow project conventions
-- Document non-obvious logic
-
-**Ready for Review when:**
-
-- [ ] Code compiles and passes all tests
-- [ ] Changes are covered by tests
-- [ ] Code follows project conventions
-- [ ] No unnecessary complexity
-
-### Review Stage
-
-**Focus:** Verify correctness, maintainability, and adherence to standards.
-Ensure no code is shipped that isn't understood.
-
-**Activities:**
-
-- Verify code does what it claims
-- Check test coverage
-- Review for maintainability
-- Confirm style compliance
-
-**Ready for Complete when:**
-
-- [ ] No obvious security vulnerabilities
-- [ ] Error handling is appropriate
-- [ ] Documentation updated if needed
-- [ ] No code you don't fully understand
-
-## Reference
-
-## Review Process
-
-### 1. Correctness First
-
-Before anything else, verify the code does what it claims:
-
-- Does it implement the intended behavior?
-- Are there logic errors or off-by-one bugs?
-- Does it handle all specified requirements?
-- Are error conditions handled appropriately?
-
-### 2. Test Coverage
-
-Check that changes are properly tested:
-
-- Unit tests for new functionality
-- Edge cases and error conditions
-- Integration tests where appropriate
-- Tests are readable and maintainable
-
-### 3. Maintainability
-
-Evaluate long-term code health:
-
-- Clear naming (variables, functions, classes)
-- Appropriate abstraction levels
-- No unnecessary duplication (DRY)
-- Single responsibility principle applied
-
-### 4. Code Style
-
-Verify consistency with project standards:
-
-- Follows project coding conventions
-- Consistent formatting and indentation
-- Appropriate comments for non-obvious logic
-- Documentation updated if needed