📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,331 @@
+# State Handoff Patterns
+
+How to pass state between workflow steps without relying on conversation context.
+
+## Why File-Based State
+
+| Problem | File-Based Solution |
+|---------|---------------------|
+| Context compaction loses history | Files persist |
+| Forked skills have no conversation access | Files are accessible |
+| State scattered across messages | Single source of truth |
+| Hard to audit what happened | Artifacts are reviewable |
+
+## Core Pattern
+
+```text
+Skill A writes → artifacts/step-a.md
+                        ↓
+Skill B reads artifacts/step-a.md → writes artifacts/step-b.md
+                                            ↓
+Skill C reads artifacts/step-b.md → ...
+```
+
+Each skill:
+1. Reads previous artifact(s)
+2. Does its work
+3. Writes its own artifact
+4. Updates context.md with decisions
+
+## Artifact Structure
+
+### Standard Header
+
+```markdown
+# {Step Name}: {Brief Description}
+
+**Generated**: {timestamp}
+**Input**: artifacts/{previous-step}.md
+**Status**: complete | partial | blocked
+
+---
+```
+
+### Sections by Step Type
+
+**Triage/Analysis artifacts:**
+```markdown
+## Problem Statement
+{clear definition}
+
+## Scope
+- Files: {list}
+- Modules: {list}
+
+## Findings
+{what was discovered}
+
+## Risks
+- {risk 1}
+- {risk 2}
+
+## Next Steps
+- [ ] {action 1}
+- [ ] {action 2}
+```
+
+**Plan artifacts:**
+```markdown
+## Goal
+{what we're trying to achieve}
+
+## Approach
+{chosen approach with rationale}
+
+## Task Breakdown
+1. {task 1}
+2. {task 2}
+3. {task 3}
+
+## Test Plan
+- [ ] {test 1}
+- [ ] {test 2}
+
+## Rollback Plan
+{how to undo if needed}
+```
+
+**Review artifacts:**
+```markdown
+## Summary
+{brief assessment}
+
+## Findings
+| Severity | Issue | Location | Recommendation |
+|----------|-------|----------|----------------|
+| {sev} | {desc} | {loc} | {rec} |
+
+## Concerns
+- {concern 1}
+- {concern 2}
+
+## Approval
+- [ ] Ready to proceed
+- [ ] Needs revision
+```
+
+**Test artifacts:**
+```markdown
+## Commands Run
+```bash
+{command 1}
+{command 2}
+```
+
+## Results
+| Suite | Pass | Fail | Skip |
+|-------|------|------|------|
+| {name} | {n} | {n} | {n} |
+
+## Failures
+### {test name}
+- Error: {message}
+- Fix: {resolution}
+
+## Coverage
+{coverage summary}
+```
+
+## context.md Pattern
+
+The shared context.md tracks living state across all steps:
+
+```markdown
+# Current Context
+
+## Task
+{what we're working on}
+
+## Decisions Made
+- {decision 1} — {rationale}
+- {decision 2} — {rationale}
+
+## Current Focus
+{what step we're on, what's next}
+
+## Blockers
+- {blocker if any}
+
+## Open Questions
+- {question if any}
+
+---
+Last updated: {timestamp}
+```
+
+### Update Pattern
+
+Each skill appends to decisions and updates current focus:
+
+```markdown
+## Decisions Made
+- {existing decisions}
+- Chose X over Y for {reason} — from /plan  ← NEW
+```
+
+## constraints.md Pattern
+
+Static project constraints, rarely changed:
+
+```markdown
+# Project Constraints
+
+## Security
+- No secrets in code
+- All inputs validated
+- {project-specific rules}
+
+## Style
+- {linting rules}
+- {naming conventions}
+
+## Performance
+- {latency budgets}
+- {size limits}
+
+## Testing
+- {coverage requirements}
+- {required test types}
+```
+
+## Gates Between Steps
+
+Use artifact existence as gates:
+
+```markdown
+---
+name: ship
+---
+
+# Prerequisites
+
+Check these artifacts exist and show success:
+- artifacts/test-report.md: all tests passing
+- artifacts/review-notes.md: no blocking issues
+- artifacts/preflight.md: all checks green
+
+If any missing or failing, do not proceed.
+```
+
+### Gate Validation Patterns
+
+```markdown
+# In skill body:
+
+Before proceeding, verify:
+1. artifacts/plan.md exists
+2. All tasks in plan.md are checked off
+3. artifacts/test-report.md shows no failures
+
+If any check fails:
+- Report what's missing
+- Do not proceed
+- Suggest next step
+```
+
+## Parallel Workflow Branches
+
+When workflow branches, use namespaced artifacts:
+
+```text
+artifacts/
+  triage.md
+  plan.md
+  security/
+    audit.md
+    review.md
+  performance/
+    profile.md
+    review.md
+  final-review.md  ← merges both branches
+```
+
+### Merge Pattern
+
+```markdown
+---
+name: final-review
+---
+
+Read and merge:
+- artifacts/security/review.md
+- artifacts/performance/review.md
+
+Synthesize into artifacts/final-review.md with:
+- Combined findings
+- Priority ranking
+- Unified recommendation
+```
+
+## Failure Recovery
+
+When a step fails, artifacts capture state for recovery:
+
+```markdown
+# artifacts/implement.md
+
+## Status: blocked
+
+## Completed
+- [x] Task 1
+- [x] Task 2
+
+## Blocked On
+- Task 3: {error message}
+
+## Recovery Steps
+1. {fix suggestion}
+2. Retry /implement
+
+## Context Preserved
+- Last working state at commit abc123
+- Rollback with: git checkout abc123
+```
+
+## Tips
+
+### Keep Artifacts Focused
+
+One purpose per artifact. If an artifact does multiple things, split it.
+
+### Include Timestamps
+
+```markdown
+**Generated**: 2026-01-26T10:30:00Z
+```
+
+Helps track freshness and debugging.
+
+### Link to Source
+
+```markdown
+## Findings
+Issue in `src/auth/login.ts:42` — missing validation
+```
+
+Specific file:line references for easy navigation.
+
+### Self-Contained
+
+Each artifact should be understandable without reading others:
+
+```markdown
+# Review: Authentication Refactor
+
+**Context**: Refactoring auth module to use JWT (from artifacts/plan.md)
+
+## Scope Reviewed
+- src/auth/*.ts
+- src/middleware/auth.ts
+```
+
+### Version Artifacts When Needed
+
+```text
+artifacts/
+  plan-v1.md
+  plan-v2.md  ← after revision
+  plan-final.md
+```
+
+Or use git to track history and keep single files.