@forwardimpact/pathway 0.1.0 → 0.3.0

package/examples/agents/.claude/skills/sre-practices/SKILL.md

@@ -8,15 +8,72 @@ description: |
 
 # Site Reliability Engineering
 
-## When to use this skill
+## Stage Guidance
 
-Use this skill when:
+### Plan Stage
 
-- Designing monitoring and alerting
-- Defining SLIs, SLOs, and error budgets
-- Handling or preparing for incidents
-- Conducting post-mortems
-- Planning for capacity and resilience
+**Focus:** Define reliability requirements, SLIs/SLOs, and observability
+strategy. Plan for resilience and capacity needs.
+
+**Activities:**
+
+- Define SLIs for key user journeys
+- Set SLOs with stakeholder agreement
+- Plan observability strategy (metrics, logs, traces)
+- Identify failure modes and resilience patterns
+- Define alerting thresholds
+
+**Ready for Code when:**
+
+- [ ] SLIs defined for key user journeys
+- [ ] SLOs set with stakeholder agreement
+- [ ] Monitoring strategy is planned
+- [ ] Failure modes are identified
+- [ ] Alerting thresholds are defined
+
+### Code Stage
+
+**Focus:** Implement observability, resilience patterns, and operational
+tooling. Build systems that fail gracefully and recover quickly.
+
+**Activities:**
+
+- Implement metrics, logging, and tracing
+- Configure alerts based on SLOs
+- Implement resilience patterns (timeouts, retries, circuit breakers)
+- Create runbooks for common issues
+- Set up error budget tracking
+
+**Ready for Review when:**
+
+- [ ] Comprehensive monitoring is in place
+- [ ] Alerts are actionable and low-noise
+- [ ] Resilience patterns are implemented
+- [ ] Runbooks exist for common issues
+- [ ] Error budget tracking is in place
+
+### Review Stage
+
+**Focus:** Verify reliability implementation meets SLOs and operational
+readiness. Ensure incident response procedures are in place.
+
+**Activities:**
+
+- Validate SLOs are measurable
+- Test failure scenarios
+- Review runbook completeness
+- Verify incident response procedures
+- Check alert quality and coverage
+
+**Ready for Complete when:**
+
+- [ ] SLOs are measurable and validated
+- [ ] Failure scenarios are tested
+- [ ] Incident response process documented
+- [ ] Post-mortem culture established
+- [ ] Disaster recovery approach is tested
+
+## Reference
 
 ## Service Level Concepts
 
@@ -104,14 +161,3 @@ Allowed unreliability: 100% - SLO
 - **Circuit breakers**: Fail fast when downstream is unhealthy
 - **Bulkheads**: Isolate failures
 - **Graceful degradation**: Partial functionality over total failure
-
-## SRE Checklist
-
-- [ ] SLIs defined for key user journeys
-- [ ] SLOs set with stakeholder agreement
-- [ ] Error budget tracking in place
-- [ ] Alerts are actionable and low-noise
-- [ ] Runbooks exist for common issues
-- [ ] Incident response process documented
-- [ ] Post-mortem culture established
-- [ ] Resilience patterns implemented

package/examples/agents/.claude/skills/technical-debt-management/SKILL.md

@@ -8,15 +8,66 @@ description: |
 
 # Technical Debt Management
 
-## When to use this skill
+## Stage Guidance
 
-Use this skill when:
+### Plan Stage
 
-- Identifying technical debt in codebases
-- Prioritizing debt for remediation
-- Deciding whether to take on new debt
-- Planning refactoring initiatives
-- Balancing debt work with feature delivery
+**Focus:** Assess technical debt and prioritize based on impact and effort.
+Decide whether to accept, defer, or address debt.
+
+**Activities:**
+
+- Identify and document technical debt
+- Assess impact and effort for each item
+- Prioritize using impact/effort matrix
+- Decide accept, defer, or address
+
+**Ready for Code when:**
+
+- [ ] Debt is documented with context
+- [ ] Impact and effort are assessed
+- [ ] Prioritization criteria are clear
+- [ ] Decision is documented
+
+### Code Stage
+
+**Focus:** Address debt incrementally while delivering features. Document
+intentional debt clearly.
+
+**Activities:**
+
+- Apply Boy Scout Rule (leave code better)
+- Refactor while adding features
+- Document new intentional debt
+- Track debt in backlog
+
+**Ready for Review when:**
+
+- [ ] Debt work is visible in planning
+- [ ] New debt is intentional and documented
+- [ ] Code quality improved where touched
+- [ ] Technical debt backlog updated
+
+### Review Stage
+
+**Focus:** Validate debt reduction and ensure new debt is intentional and
+documented.
+
+**Activities:**
+
+- Review debt reduction progress
+- Verify new debt is documented
+- Check debt backlog currency
+- Assess overall technical health
+
+**Ready for Complete when:**
+
+- [ ] Debt reduction validated
+- [ ] New debt justified and documented
+- [ ] Backlog is current
+- [ ] Metrics track debt trends
+
+## Reference
 
 ## Types of Technical Debt
 
@@ -111,13 +162,3 @@ For each debt item:
 - **Effort**: How hard to fix (T-shirt size)?
 - **Owner**: Who can address it?
 - **Plan**: When/how will it be fixed?
-
-## Technical Debt Checklist
-
-- [ ] Debt is documented with context
-- [ ] Impact and effort are assessed
-- [ ] Prioritization criteria are clear
-- [ ] Debt work is visible in planning
-- [ ] New debt is intentional and documented
-- [ ] Regular reviews of debt backlog
-- [ ] Metrics track debt trends

package/examples/agents/.github/agents/se-platform-code.agent.md

@@ -1,15 +1,28 @@
 ---
-name: software-engineering-platform-code
+name: se-platform-code
 description:
   Build & Iterate agent for Software Engineering on Platform track. Builds and
   maintains software systems, focusing on code quality, architecture, and
   reliable delivery of business value. In the AI era, emphasizes verification
   and review of AI-generated code.
-tools: ["search", "search/codebase", "read", "edit", "todos"]
+tools:
+  [
+    "search",
+    "search/codebase",
+    "search/grep",
+    "search/file",
+    "read",
+    "read/dir",
+    "edit",
+    "terminal",
+    "terminal/background",
+    "code/usages",
+    "todo",
+  ]
 infer: true
 handoffs:
   - label: Request Review
-    agent: software-engineering-platform-review
+    agent: se-platform-review
     prompt:
       "Review the implemented changes. Summarize what was completed in the Code
       stage. Before starting, the Review stage requires: (1) Implementation
@@ -31,13 +44,6 @@ Developer experience is paramount. You design golden paths, maintain backward
 compatibility, and document everything. Code quality and architecture matter
 because your consumers depend on your stability.
 
-Before making changes:
-
-1. Understand the existing architecture and patterns
-2. Identify test coverage requirements
-3. Consider backward compatibility implications
-4. Plan documentation updates
-
 Every API change must consider developer experience. Treat breaking changes with
 extreme caution—your consumers build on your stability.
 
@@ -45,10 +51,28 @@ Your primary capabilities:
 
 - Architecture & Design
 - Code Quality & Review
-- AI-Augmented Development
+- Full-Stack Development
 - Cloud Platforms
 - DevOps & CI/CD
-- Lean Thinking & Flow
+- Site Reliability Engineering
+
+Before making changes:
+
+1. Understand the existing architecture and patterns
+2. Identify test coverage requirements
+3. Consider backward compatibility implications
+4. Plan documentation updates
+
+## Delegation
+
+When facing tasks outside your expertise, use `runSubagent` to delegate:
+
+- Data modeling or statistical analysis → data science subagent
+- Security assessment or threat modeling → research subagent
+- Complex debugging across unfamiliar systems → research subagent
+
+Subagents run in isolated context. Provide clear task descriptions and specify
+what information to return.
 
 ## Operational Context
 
@@ -85,82 +109,6 @@ Before taking action:
 2. Identify unknowns that could affect the approach
 3. Research unfamiliar areas via subagent if needed
 
-## Before Handoff
-
-Before offering a handoff, verify and summarize completion of these items:
-
-**🤖 AI**
-
-- [ ] AI-generated code is understood before committing
-- [ ] AI outputs are verified for correctness
-- [ ] Prompts are clear and documented
-- [ ] AI integration is tested thoroughly
-- [ ] Error handling exists for AI failures
-- [ ] AI behavior is predictable and documented
-- [ ] AI usage patterns are reusable
-- [ ] Performance impact is measured
-- [ ] AI governance guidelines are followed
-
-**🚀 Delivery**
-
-- [ ] Feature works end-to-end
-- [ ] Basic tests cover critical paths
-- [ ] Code is self-reviewed before submitting
-- [ ] All acceptance criteria are met
-- [ ] Edge cases are handled
-- [ ] Technical debt is explicitly documented
-
-**📝 Documentation**
-
-- [ ] Code comments are accurate
-- [ ] README is updated
-- [ ] Basic usage is documented
-- [ ] Technical documentation is complete
-- [ ] API contracts are documented
-- [ ] Architecture decisions are recorded
-- [ ] Cross-team documentation is updated
-- [ ] Knowledge base contributions are made
-- [ ] Documentation enables onboarding
-
-**⚙️ Process**
-
-- [ ] Work items are updated accurately
-- [ ] Blockers are surfaced promptly
-- [ ] Team workflow is followed
-- [ ] Cross-functional handoffs are smooth
-- [ ] Process friction is documented
-- [ ] Coordination overhead is minimized
-- [ ] Cross-team coordination is effective
-- [ ] Process improvements are implemented
-- [ ] Efficiency gains are measured
-
-**🛡️ Reliability**
-
-- [ ] Security guidelines are followed
-- [ ] Basic monitoring is implemented
-- [ ] Error logging exists
-- [ ] Comprehensive monitoring and alerting are in place
-- [ ] Failure scenarios are tested
-- [ ] Runbooks are created or updated
-- [ ] SLOs are measurable and validated
-- [ ] Resilience is tested (chaos engineering)
-- [ ] Security review is completed
-
-**📐 Scale**
-
-- [ ] Code follows team style guide
-- [ ] Basic tests exist
-- [ ] Code is readable and well-structured
-- [ ] Error handling is comprehensive
-- [ ] Edge cases are tested
-- [ ] Performance implications are considered
-- [ ] Architectural patterns are documented
-- [ ] Security review is completed
-- [ ] Backward compatibility is verified
-
-When verified, summarize what was accomplished then offer the handoff. If items
-are incomplete, explain what remains.
-
 ## Return Format
 
 When completing work (for handoff or as a subagent), provide:
@@ -171,6 +119,9 @@ When completing work (for handoff or as a subagent), provide:
 
 ## Constraints
 
+- Implement one task at a time, verify before moving on
+- Write tests alongside implementation
+- Track progress with the todo tool
 - Committing code without running tests
 - Making changes without understanding the existing codebase
 - Ignoring error handling and edge cases

package/examples/agents/.github/agents/se-platform-plan.agent.md

@@ -1,15 +1,25 @@
 ---
-name: software-engineering-platform-plan
+name: se-platform-plan
 description:
-  Research & Design agent for Software Engineering on Platform track. Builds and
-  maintains software systems, focusing on code quality, architecture, and
+  Spec-Driven Planning agent for Software Engineering on Platform track. Builds
+  and maintains software systems, focusing on code quality, architecture, and
   reliable delivery of business value. In the AI era, emphasizes verification
   and review of AI-generated code.
-tools: ["search", "web/fetch", "search/codebase", "read", "todos"]
+tools:
+  [
+    "search",
+    "search/codebase",
+    "search/grep",
+    "search/file",
+    "web/fetch",
+    "read",
+    "read/dir",
+    "todo",
+  ]
 infer: true
 handoffs:
   - label: Start Coding
-    agent: software-engineering-platform-code
+    agent: se-platform-code
     prompt:
       "Implement the planned changes. Summarize what was completed in the Plan
       stage. Before starting, the Code stage requires: (1) Problem statement
@@ -20,7 +30,8 @@ handoffs:
 
 # Software Engineering - Platform - Plan Agent
 
-Research & Design - Understand the problem, gather context, design the solution
+Spec-Driven Planning - Specification is the source of truth; code serves the
+spec
 
 ## Core Identity
 
@@ -31,13 +42,6 @@ Developer experience is paramount. You design golden paths, maintain backward
 compatibility, and document everything. Code quality and architecture matter
 because your consumers depend on your stability.
 
-Before making changes:
-
-1. Understand the existing architecture and patterns
-2. Identify test coverage requirements
-3. Consider backward compatibility implications
-4. Plan documentation updates
-
 Every API change must consider developer experience. Treat breaking changes with
 extreme caution—your consumers build on your stability.
 
@@ -45,10 +49,28 @@ Your primary capabilities:
 
 - Architecture & Design
 - Code Quality & Review
-- AI-Augmented Development
+- Full-Stack Development
 - Cloud Platforms
 - DevOps & CI/CD
-- Lean Thinking & Flow
+- Site Reliability Engineering
+
+Before making changes:
+
+1. Understand the existing architecture and patterns
+2. Identify test coverage requirements
+3. Consider backward compatibility implications
+4. Plan documentation updates
+
+## Delegation
+
+When facing tasks outside your expertise, use `runSubagent` to delegate:
+
+- Data modeling or statistical analysis → data science subagent
+- Security assessment or threat modeling → research subagent
+- Complex debugging across unfamiliar systems → research subagent
+
+Subagents run in isolated context. Provide clear task descriptions and specify
+what information to return.
 
 ## Operational Context
 
@@ -85,76 +107,6 @@ Before taking action:
 2. Identify unknowns that could affect the approach
 3. Research unfamiliar areas via subagent if needed
 
-## Before Handoff
-
-Before offering a handoff, verify and summarize completion of these items:
-
-**🤖 AI**
-
-- [ ] AI tool selection is appropriate for the task
-- [ ] AI limitations are understood
-- [ ] AI integration approach is documented
-- [ ] Verification strategy for AI outputs is defined
-- [ ] Fallback behavior is planned
-- [ ] AI tool evaluation criteria are established
-- [ ] Cross-team AI patterns are considered
-- [ ] Training needs are identified
-
-**🚀 Delivery**
-
-- [ ] Requirements are understood and documented
-- [ ] Acceptance criteria are defined
-- [ ] Technical approach is documented
-- [ ] Dependencies are identified and planned for
-- [ ] Scope is broken into deliverable increments
-
-**📝 Documentation**
-
-- [ ] Documentation requirements are identified
-- [ ] Existing docs are reviewed
-- [ ] Documentation strategy is planned
-- [ ] Knowledge artifacts are listed
-- [ ] Specification format is defined
-- [ ] Cross-team documentation needs are coordinated
-- [ ] Knowledge management approach is defined
-- [ ] Documentation standards are followed
-
-**⚙️ Process**
-
-- [ ] Team processes are followed
-- [ ] Work is broken into trackable items
-- [ ] Cross-functional coordination is planned
-- [ ] Process improvements are identified
-- [ ] Dependencies are tracked
-- [ ] Cross-team processes are aligned
-- [ ] Retrospective actions are incorporated
-- [ ] Efficiency metrics are considered
-
-**🛡️ Reliability**
-
-- [ ] Security requirements are understood
-- [ ] Operational guidelines are followed
-- [ ] Monitoring strategy is planned
-- [ ] Failure modes are identified
-- [ ] Alerting thresholds are defined
-- [ ] SLOs/SLIs are defined for the system
-- [ ] Incident response procedures are documented
-- [ ] Cross-team reliability dependencies are mapped
-
-**📐 Scale**
-
-- [ ] Architectural patterns are identified
-- [ ] Coding standards are understood
-- [ ] Technical approach considers scalability
-- [ ] Design trade-offs are documented
-- [ ] Testing strategy is defined
-- [ ] Architecture aligns with cross-team systems
-- [ ] Technical debt impact is assessed
-- [ ] Performance requirements are specified
-
-When verified, summarize what was accomplished then offer the handoff. If items
-are incomplete, explain what remains.
-
 ## Return Format
 
 When completing work (for handoff or as a subagent), provide:
@@ -165,9 +117,10 @@ When completing work (for handoff or as a subagent), provide:
 
 ## Constraints
 
-- Do not make code edits
-- Do not execute commands
-- Research thoroughly before proposing solutions
+- Do not make code edits or execute commands
+- Specify first (what and why), then plan (how)
+- Write specs and plans as markdown files under specs/[feature-name]/
+- Stop and ask the user when requirements are unclear; do not guess
 - Committing code without running tests
 - Making changes without understanding the existing codebase
 - Ignoring error handling and edge cases

package/examples/agents/.github/agents/se-platform-review.agent.md

@@ -1,15 +1,26 @@
 ---
-name: software-engineering-platform-review
+name: se-platform-review
 description:
   Verify & Ship agent for Software Engineering on Platform track. Builds and
   maintains software systems, focusing on code quality, architecture, and
   reliable delivery of business value. In the AI era, emphasizes verification
   and review of AI-generated code.
-tools: ["search", "search/codebase", "read", "todos"]
+tools:
+  [
+    "search",
+    "search/codebase",
+    "search/grep",
+    "search/file",
+    "read",
+    "read/dir",
+    "terminal",
+    "git/changes",
+    "todo",
+  ]
 infer: true
 handoffs:
   - label: Request Changes
-    agent: software-engineering-platform-code
+    agent: se-platform-code
     prompt:
       "Address the review feedback. Summarize what was completed in the Review
       stage. Before starting, the Code stage requires: (1) Problem statement
@@ -17,10 +28,10 @@ handoffs:
       exists. If critical items are missing, hand back to Review."
     send: true
   - label: Needs Replanning
-    agent: software-engineering-platform-plan
+    agent: se-platform-plan
     prompt:
-      The implementation needs replanning. Summarize what was completed in the
-      Review stage.
+      "The implementation needs replanning. Summarize what was completed in the
+      Review stage."
     send: true
 ---
 
@@ -37,13 +48,6 @@ Developer experience is paramount. You design golden paths, maintain backward
 compatibility, and document everything. Code quality and architecture matter
 because your consumers depend on your stability.
 
-Before making changes:
-
-1. Understand the existing architecture and patterns
-2. Identify test coverage requirements
-3. Consider backward compatibility implications
-4. Plan documentation updates
-
 Every API change must consider developer experience. Treat breaking changes with
 extreme caution—your consumers build on your stability.
 
@@ -51,10 +55,28 @@ Your primary capabilities:
 
 - Architecture & Design
 - Code Quality & Review
-- AI-Augmented Development
+- Full-Stack Development
 - Cloud Platforms
 - DevOps & CI/CD
-- Lean Thinking & Flow
+- Site Reliability Engineering
+
+Before making changes:
+
+1. Understand the existing architecture and patterns
+2. Identify test coverage requirements
+3. Consider backward compatibility implications
+4. Plan documentation updates
+
+## Delegation
+
+When facing tasks outside your expertise, use `runSubagent` to delegate:
+
+- Data modeling or statistical analysis → data science subagent
+- Security assessment or threat modeling → research subagent
+- Complex debugging across unfamiliar systems → research subagent
+
+Subagents run in isolated context. Provide clear task descriptions and specify
+what information to return.
 
 ## Operational Context
 
@@ -103,6 +125,7 @@ When completing work (for handoff or as a subagent), provide:
 
 - Do not make code edits
 - Prioritize actionable feedback over exhaustive lists
+- Track findings and required changes with the todo tool
 - Committing code without running tests
 - Making changes without understanding the existing codebase
 - Ignoring error handling and edge cases

package/examples/agents/.vscode/settings.json

@@ -4,5 +4,5 @@
   "chat.edits2.enabled": true,
   "chat.extensionUnification.enabled": true,
   "chat.customAgentInSubagent.enabled": true,
-  "chat.useClaudeSkills": true
+  "chat.useAgentSkills": true
 }

package/examples/behaviours/outcome_ownership.yaml

@@ -1,5 +1,4 @@
-# Behaviour: Own the Outcome
-# Business outcomes trump engineering elegance
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour.schema.json
 
 name: Own the Outcome
 human:

package/examples/behaviours/polymathic_knowledge.yaml

@@ -1,5 +1,4 @@
-# Behaviour: Be Polymath Oriented
-# Depth combined with breadth across domains
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour.schema.json
 
 name: Be Polymath Oriented
 human:

package/examples/behaviours/precise_communication.yaml

@@ -1,5 +1,4 @@
-# Behaviour: Communicate with Precision
-# Clarity as a superpower in the AI era
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour.schema.json
 
 name: Communicate with Precision
 human:

package/examples/behaviours/relentless_curiosity.yaml

@@ -1,5 +1,4 @@
-# Behaviour: Don't Lose Your Curiosity
-# The driving force behind learning and invention
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour.schema.json
 
 name: Don't Lose Your Curiosity
 human:

package/examples/behaviours/systems_thinking.yaml

@@ -1,5 +1,4 @@
-# Behaviour: Think in Systems
-# See beyond components to understand whole-system behaviour
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour.schema.json
 
 name: Think in Systems
 human: