hatch3r 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/README.md +12 -7
  2. package/agents/hatch3r-a11y-auditor.md +18 -11
  3. package/agents/hatch3r-architect.md +27 -12
  4. package/agents/hatch3r-ci-watcher.md +30 -9
  5. package/agents/hatch3r-context-rules.md +18 -8
  6. package/agents/hatch3r-dependency-auditor.md +30 -15
  7. package/agents/hatch3r-devops.md +18 -13
  8. package/agents/hatch3r-docs-writer.md +33 -12
  9. package/agents/hatch3r-fixer.md +46 -9
  10. package/agents/hatch3r-implementer.md +21 -9
  11. package/agents/hatch3r-learnings-loader.md +24 -7
  12. package/agents/hatch3r-lint-fixer.md +18 -9
  13. package/agents/hatch3r-perf-profiler.md +26 -10
  14. package/agents/hatch3r-researcher.md +57 -919
  15. package/agents/hatch3r-reviewer.md +29 -10
  16. package/agents/hatch3r-security-auditor.md +25 -10
  17. package/agents/hatch3r-test-writer.md +29 -9
  18. package/agents/modes/architecture.md +1 -0
  19. package/agents/modes/boundary-analysis.md +2 -1
  20. package/agents/modes/codebase-impact.md +1 -0
  21. package/agents/modes/complexity-risk.md +1 -0
  22. package/agents/modes/coverage-analysis.md +1 -0
  23. package/agents/modes/current-state.md +1 -0
  24. package/agents/modes/feature-design.md +1 -0
  25. package/agents/modes/impact-analysis.md +1 -0
  26. package/agents/modes/library-docs.md +2 -1
  27. package/agents/modes/migration-path.md +1 -0
  28. package/agents/modes/prior-art.md +1 -0
  29. package/agents/modes/refactoring-strategy.md +1 -0
  30. package/agents/modes/regression.md +1 -0
  31. package/agents/modes/requirements-elicitation.md +1 -0
  32. package/agents/modes/risk-assessment.md +1 -0
  33. package/agents/modes/risk-prioritization.md +1 -0
  34. package/agents/modes/root-cause.md +1 -0
  35. package/agents/modes/similar-implementation.md +2 -1
  36. package/agents/modes/symptom-trace.md +1 -0
  37. package/agents/modes/test-pattern.md +2 -1
  38. package/agents/shared/external-knowledge.md +31 -0
  39. package/agents/shared/quality-charter.md +96 -0
  40. package/checks/README.md +1 -0
  41. package/checks/accessibility.md +55 -0
  42. package/commands/board/pickup-azure-devops.md +5 -0
  43. package/commands/board/pickup-delegation-multi.md +9 -1
  44. package/commands/board/pickup-delegation.md +4 -0
  45. package/commands/board/pickup-github.md +5 -0
  46. package/commands/board/pickup-gitlab.md +5 -0
  47. package/commands/board/pickup-modes.md +1 -0
  48. package/commands/board/pickup-post-impl.md +9 -1
  49. package/commands/board/shared-azure-devops.md +14 -3
  50. package/commands/board/shared-board-overview.md +1 -0
  51. package/commands/board/shared-github.md +2 -0
  52. package/commands/board/shared-gitlab.md +10 -2
  53. package/commands/hatch3r-agent-customize.md +6 -1
  54. package/commands/hatch3r-api-spec.md +1 -0
  55. package/commands/hatch3r-benchmark.md +4 -3
  56. package/commands/hatch3r-board-fill.md +52 -9
  57. package/commands/hatch3r-board-groom.md +124 -7
  58. package/commands/hatch3r-board-init.md +7 -3
  59. package/commands/hatch3r-board-pickup.md +1 -0
  60. package/commands/hatch3r-board-refresh.md +1 -0
  61. package/commands/hatch3r-board-shared.md +71 -5
  62. package/commands/hatch3r-bug-plan.md +2 -1
  63. package/commands/hatch3r-codebase-map.md +4 -3
  64. package/commands/hatch3r-command-customize.md +6 -1
  65. package/commands/hatch3r-context-health.md +1 -0
  66. package/commands/hatch3r-cost-tracking.md +1 -0
  67. package/commands/hatch3r-debug.md +4 -3
  68. package/commands/hatch3r-dep-audit.md +3 -0
  69. package/commands/hatch3r-feature-plan.md +3 -2
  70. package/commands/hatch3r-healthcheck.md +1 -0
  71. package/commands/hatch3r-hooks.md +6 -1
  72. package/commands/hatch3r-learn.md +1 -0
  73. package/commands/hatch3r-migration-plan.md +3 -2
  74. package/commands/hatch3r-onboard.md +2 -1
  75. package/commands/hatch3r-project-spec.md +4 -3
  76. package/commands/hatch3r-quick-change.md +31 -3
  77. package/commands/hatch3r-recipe.md +1 -0
  78. package/commands/hatch3r-refactor-plan.md +2 -1
  79. package/commands/hatch3r-release.md +4 -1
  80. package/commands/hatch3r-revision.md +138 -17
  81. package/commands/hatch3r-roadmap.md +5 -4
  82. package/commands/hatch3r-rule-customize.md +5 -0
  83. package/commands/hatch3r-security-audit.md +1 -0
  84. package/commands/hatch3r-skill-customize.md +5 -0
  85. package/commands/hatch3r-test-plan.md +3 -2
  86. package/commands/hatch3r-workflow.md +15 -1
  87. package/dist/cli/index.js +7595 -4548
  88. package/dist/cli/index.js.map +1 -1
  89. package/hooks/hatch3r-ci-failure.md +1 -0
  90. package/hooks/hatch3r-file-save.md +1 -0
  91. package/hooks/hatch3r-post-merge.md +1 -0
  92. package/hooks/hatch3r-pre-commit.md +1 -0
  93. package/hooks/hatch3r-pre-push.md +1 -0
  94. package/hooks/hatch3r-session-start.md +1 -0
  95. package/package.json +30 -12
  96. package/rules/hatch3r-accessibility-standards.md +2 -1
  97. package/rules/hatch3r-accessibility-standards.mdc +1 -1
  98. package/rules/hatch3r-agent-orchestration-detail.md +207 -0
  99. package/rules/hatch3r-agent-orchestration-detail.mdc +202 -0
  100. package/rules/hatch3r-agent-orchestration.md +161 -318
  101. package/rules/hatch3r-agent-orchestration.mdc +212 -154
  102. package/rules/hatch3r-api-design.md +2 -1
  103. package/rules/hatch3r-api-design.mdc +1 -1
  104. package/rules/hatch3r-browser-verification.md +4 -2
  105. package/rules/hatch3r-browser-verification.mdc +1 -0
  106. package/rules/hatch3r-ci-cd.md +2 -1
  107. package/rules/hatch3r-ci-cd.mdc +1 -1
  108. package/rules/hatch3r-code-standards.md +15 -2
  109. package/rules/hatch3r-code-standards.mdc +22 -2
  110. package/rules/hatch3r-component-conventions.md +2 -1
  111. package/rules/hatch3r-component-conventions.mdc +1 -1
  112. package/rules/hatch3r-data-classification.md +2 -1
  113. package/rules/hatch3r-data-classification.mdc +1 -1
  114. package/rules/hatch3r-deep-context.md +26 -1
  115. package/rules/hatch3r-deep-context.mdc +54 -8
  116. package/rules/hatch3r-dependency-management.md +2 -1
  117. package/rules/hatch3r-dependency-management.mdc +17 -5
  118. package/rules/hatch3r-feature-flags.md +2 -0
  119. package/rules/hatch3r-feature-flags.mdc +1 -0
  120. package/rules/hatch3r-git-conventions.md +2 -1
  121. package/rules/hatch3r-git-conventions.mdc +2 -1
  122. package/rules/hatch3r-i18n.md +2 -1
  123. package/rules/hatch3r-i18n.mdc +1 -1
  124. package/rules/hatch3r-learning-consult.md +11 -1
  125. package/rules/hatch3r-learning-consult.mdc +11 -1
  126. package/rules/hatch3r-migrations.md +2 -1
  127. package/rules/hatch3r-migrations.mdc +12 -1
  128. package/rules/hatch3r-observability-logging.md +34 -0
  129. package/rules/hatch3r-observability-logging.mdc +30 -0
  130. package/rules/hatch3r-observability-metrics.md +74 -0
  131. package/rules/hatch3r-observability-metrics.mdc +70 -0
  132. package/rules/hatch3r-observability-tracing-detail.md +160 -0
  133. package/rules/hatch3r-observability-tracing-detail.mdc +63 -0
  134. package/rules/hatch3r-observability-tracing.md +86 -0
  135. package/rules/hatch3r-observability-tracing.mdc +77 -0
  136. package/rules/hatch3r-observability.md +9 -448
  137. package/rules/hatch3r-observability.mdc +7 -159
  138. package/rules/hatch3r-performance-budgets.md +2 -0
  139. package/rules/hatch3r-performance-budgets.mdc +1 -0
  140. package/rules/hatch3r-secrets-management.md +2 -1
  141. package/rules/hatch3r-secrets-management.mdc +1 -1
  142. package/rules/hatch3r-security-patterns.md +3 -2
  143. package/rules/hatch3r-security-patterns.mdc +12 -1
  144. package/rules/hatch3r-testing.md +12 -2
  145. package/rules/hatch3r-testing.mdc +11 -2
  146. package/rules/hatch3r-theming.md +3 -2
  147. package/rules/hatch3r-theming.mdc +1 -1
  148. package/rules/hatch3r-tooling-hierarchy.md +3 -2
  149. package/rules/hatch3r-tooling-hierarchy.mdc +19 -5
  150. package/skills/hatch3r-a11y-audit/SKILL.md +11 -4
  151. package/skills/hatch3r-agent-customize/SKILL.md +5 -72
  152. package/skills/hatch3r-api-spec/SKILL.md +9 -2
  153. package/skills/hatch3r-architecture-review/SKILL.md +7 -0
  154. package/skills/hatch3r-bug-fix/SKILL.md +16 -7
  155. package/skills/hatch3r-ci-pipeline/SKILL.md +8 -1
  156. package/skills/hatch3r-command-customize/SKILL.md +5 -62
  157. package/skills/hatch3r-context-health/SKILL.md +23 -2
  158. package/skills/hatch3r-cost-tracking/SKILL.md +16 -6
  159. package/skills/hatch3r-customize/SKILL.md +124 -0
  160. package/skills/hatch3r-dep-audit/SKILL.md +9 -2
  161. package/skills/hatch3r-feature/SKILL.md +12 -4
  162. package/skills/hatch3r-gh-agentic-workflows/SKILL.md +7 -0
  163. package/skills/hatch3r-incident-response/SKILL.md +7 -0
  164. package/skills/hatch3r-issue-workflow/SKILL.md +8 -1
  165. package/skills/hatch3r-logical-refactor/SKILL.md +8 -1
  166. package/skills/hatch3r-migration/SKILL.md +7 -0
  167. package/skills/hatch3r-perf-audit/SKILL.md +9 -2
  168. package/skills/hatch3r-pr-creation/SKILL.md +8 -1
  169. package/skills/hatch3r-qa-validation/SKILL.md +8 -1
  170. package/skills/hatch3r-recipe/SKILL.md +8 -1
  171. package/skills/hatch3r-refactor/SKILL.md +10 -2
  172. package/skills/hatch3r-release/SKILL.md +8 -1
  173. package/skills/hatch3r-rule-customize/SKILL.md +5 -65
  174. package/skills/hatch3r-skill-customize/SKILL.md +5 -62
  175. package/skills/hatch3r-visual-refactor/SKILL.md +12 -5
@@ -5,6 +5,7 @@ event: ci-failure
5
5
  agent: ci-watcher
6
6
  description: Diagnose CI pipeline failures
7
7
  tags: [core]
8
+ quality_charter: agents/shared/quality-charter.md
8
9
  ---
9
10
  # Hook: ci-failure → ci-watcher
10
11
 
@@ -6,6 +6,7 @@ agent: context-rules
6
6
  description: Activate context-specific rules on file save
7
7
  globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
8
8
  tags: [core]
9
+ quality_charter: agents/shared/quality-charter.md
9
10
  ---
10
11
  # Hook: file-save → context-rules
11
12
 
@@ -5,6 +5,7 @@ event: post-merge
5
5
  agent: ci-watcher
6
6
  description: Check CI pipeline status after merge
7
7
  tags: [core]
8
+ quality_charter: agents/shared/quality-charter.md
8
9
  ---
9
10
  # Hook: post-merge → ci-watcher
10
11
 
@@ -6,6 +6,7 @@ agent: lint-fixer
6
6
  description: Auto-fix lint and formatting issues before commit
7
7
  globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
8
8
  tags: [core]
9
+ quality_charter: agents/shared/quality-charter.md
9
10
  ---
10
11
  # Hook: pre-commit → lint-fixer
11
12
 
@@ -5,6 +5,7 @@ event: pre-push
5
5
  agent: security-auditor
6
6
  description: Scan for secrets and security issues before push
7
7
  tags: [core]
8
+ quality_charter: agents/shared/quality-charter.md
8
9
  ---
9
10
  # Hook: pre-push → security-auditor
10
11
 
@@ -5,6 +5,7 @@ event: session-start
5
5
  agent: learnings-loader
6
6
  description: Load relevant learnings at session start
7
7
  tags: [core]
8
+ quality_charter: agents/shared/quality-charter.md
8
9
  ---
9
10
  # Hook: session-start → learnings-loader
10
11
 
package/package.json CHANGED
@@ -1,8 +1,14 @@
1
1
  {
2
2
  "name": "hatch3r",
3
- "version": "1.3.0",
3
+ "version": "1.5.0",
4
4
  "description": "Battle-tested agentic coding setup framework. One command to hatch your agent stack -- agents, skills, rules, commands, and MCP for every major AI coding tool.",
5
5
  "type": "module",
6
+ "exports": {
7
+ ".": {
8
+ "import": "./dist/cli/index.js",
9
+ "types": "./dist/cli/index.d.ts"
10
+ }
11
+ },
6
12
  "bin": {
7
13
  "hatch3r": "./dist/cli/index.js"
8
14
  },
@@ -13,7 +19,8 @@
13
19
  "typecheck": "tsc --noEmit",
14
20
  "prepublishOnly": "npm run build",
15
21
  "test": "vitest run",
16
- "test:watch": "vitest"
22
+ "test:watch": "vitest",
23
+ "lockfile:check": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https"
17
24
  },
18
25
  "keywords": [
19
26
  "agents",
@@ -44,11 +51,15 @@
44
51
  "bugs": {
45
52
  "url": "https://github.com/hatch3r/hatch3r/issues"
46
53
  },
54
+ "publishConfig": {
55
+ "access": "public",
56
+ "registry": "https://registry.npmjs.org"
57
+ },
47
58
  "engines": {
48
59
  "node": ">=22.0.0"
49
60
  },
50
61
  "files": [
51
- "dist/",
62
+ "dist/cli/",
52
63
  "agents/",
53
64
  "checks/",
54
65
  "commands/",
@@ -64,18 +75,25 @@
64
75
  "dependencies": {
65
76
  "boxen": "^8.0.1",
66
77
  "chalk": "^5.4.0",
67
- "commander": "^13.0.0",
68
- "inquirer": "^12.0.0",
78
+ "commander": "^14.0.3",
79
+ "inquirer": "^13.3.2",
69
80
  "ora": "^9.3.0",
70
- "yaml": "^2.7.0"
81
+ "yaml": "^2.8.3"
71
82
  },
72
83
  "devDependencies": {
73
- "@types/node": "^25.3.0",
74
- "@vitest/coverage-v8": "^3.2.4",
75
- "eslint": "^9.0.0",
84
+ "@types/node": "^25.5.0",
85
+ "@vitest/coverage-v8": "^4.1.2",
86
+ "eslint": "^10.1.0",
87
+ "lockfile-lint": "^5.0.0",
76
88
  "tsup": "^8.0.0",
77
- "typescript": "^5.7.0",
78
- "typescript-eslint": "^8.56.0",
79
- "vitest": "^3.0.0"
89
+ "typescript": "^6.0.2",
90
+ "typescript-eslint": "^8.57.2",
91
+ "vitest": "^4.1.2"
92
+ },
93
+ "overrides": {
94
+ "flatted": "^3.4.2"
95
+ },
96
+ "comments": {
97
+ "overrides/flatted": "Pinned to >=3.4.2 to resolve security advisory in transitive eslint > flat-cache > flatted dependency"
80
98
  }
81
99
  }
@@ -2,8 +2,9 @@
2
2
  id: hatch3r-accessibility-standards
3
3
  type: rule
4
4
  description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
5
- scope: always
5
+ scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/*a11y*,**/*accessibility*"
6
6
  tags: [a11y]
7
+ quality_charter: agents/shared/quality-charter.md
7
8
  ---
8
9
  # Accessibility Standards
9
10
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
3
- alwaysApply: true
3
+ globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/components/**", "**/*.html", "**/*a11y*", "**/*accessibility*"]
4
4
  ---
5
5
  # Accessibility Standards
6
6
 
@@ -0,0 +1,207 @@
1
+ ---
2
+ id: hatch3r-agent-orchestration-detail
3
+ type: rule
4
+ description: Extended orchestration reference — PipelineContext schemas, resilience protocols, observability integration, and auto-mode guardrails
5
+ scope: conditional
6
+ globs: "**/.agents/**,**/pipeline/**,**/*orchestrat*,**/*agent*"
7
+ tags: [core]
8
+ quality_charter: agents/shared/quality-charter.md
9
+ ---
10
+ # Agent Orchestration — Extended Reference
11
+
12
+ This is the on-demand companion to `hatch3r-agent-orchestration`. Load when you need detailed schemas, failure handling protocols, or guardrail specifications.
13
+
14
+ ## PipelineContext Schema
15
+
16
+ The `PipelineContext` is the structured handoff object passed between pipeline phases. Each phase reads its inputs and writes its outputs to this context.
17
+
18
+ ```
19
+ PipelineContext {
20
+ correlationId: string // UUID v4, generated before Phase 1
21
+ taskType: "bug" | "feature" | "refactor" | "qa"
22
+ issueRef: string | null // Issue number or null for plain chat
23
+ deepContextTier: 1 | 2 | 3 // From hatch3r-deep-context scoring
24
+
25
+ // Detected project type for specialist selection (Finding #56)
26
+ projectType?: {
27
+ languages: string[] // From repo analysis (e.g., "typescript", "python", "go")
28
+ frameworks: string[] // Detected frameworks (e.g., "next", "express")
29
+ isMonorepo: boolean
30
+ packageManager: string // "npm" | "yarn" | "pnpm" | "bun" | "unknown"
31
+ }
32
+
33
+ // Phase 1 outputs (Research)
34
+ researchFindings: {
35
+ modes: string[] // Researcher modes used
36
+ affectedFiles: string[] // Files to create/modify/delete
37
+ blastRadius: string[] // Downstream consumers
38
+ existingTests: string[] // Test files covering affected code
39
+ dependencies: string[] // Internal + external dependencies
40
+ conventions: object | null // From similar-implementation mode
41
+ resolvedRequirements: object | null // From requirements-elicitation
42
+ }
43
+
44
+ // Research gap flags from mid-implementation checkpoint (Finding #52)
45
+ researchGaps?: string[] // Gaps identified during Phase 2
46
+
47
+ // Phase 2 outputs (Implementation)
48
+ implementationResult: {
49
+ filesChanged: string[]
50
+ testsWritten: string[]
51
+ status: "SUCCESS" | "PARTIAL" | "FAILED" | "SKIPPED" | "TIMEOUT"
52
+ reason: string | null
53
+ }
54
+
55
+ // Phase 3 outputs (Review)
56
+ reviewResult: {
57
+ iterations: number // 1-3
58
+ finalVerdict: "CLEAN" | "UNRESOLVED"
59
+ findings: ReviewFinding[]
60
+ confirmationPassResult: "PASS" | "FAIL"
61
+ }
62
+
63
+ // Phase 4 outputs (Quality)
64
+ qualityResults: {
65
+ specialists: SpecialistResult[]
66
+ validationPass: {
67
+ testsPass: boolean
68
+ typecheckPass: boolean
69
+ fixAttempts: number
70
+ regressionsPersist: boolean
71
+ }
72
+ }
73
+
74
+ // Metadata
75
+ startedAt: string // ISO-8601
76
+ completedAt: string | null
77
+ totalDuration: number | null // milliseconds
78
+ }
79
+ ```
80
+
81
+ The TypeScript implementation of this schema with runtime validation is in `src/pipeline/pipelineContext.ts`. Use `validatePhaseTransition()` to verify context completeness before advancing between phases.
82
+
83
+ ## Resilience and Failure Handling
84
+
85
+ ### Phase Failure Protocols
86
+
87
+ | Phase | Failure Mode | Protocol |
88
+ |-------|-------------|----------|
89
+ | Phase 1 (Research) | Researcher timeout | Proceed with partial findings; flag missing modes. |
90
+ | Phase 1 (Research) | No relevant findings | Surface to user; ask whether to proceed with implementation. |
91
+ | Phase 2 (Implementation) | Build/test failure | Attempt self-fix (max 2 iterations). Escalate to user if unresolved. |
92
+ | Phase 2 (Implementation) | Scope creep detected | Halt. Surface deviation to user. Resume only with approval. |
93
+ | Phase 3 (Review) | Max iterations (3) | Surface unresolved findings to user. Do not merge. |
94
+ | Phase 3 (Review) | DESIGN_OBJECTION verdict | Terminate review loop immediately. Surface the objection and alternative approaches to the user for an architectural decision. Do not spawn fixer. |
95
+ | Phase 3 (Review) | Fixer introduces regressions | Revert fixer changes. Surface original findings + regression to user. |
96
+ | Phase 4 (Quality) | Specialist timeout | Log timeout. Continue with available results. Flag in output. |
97
+ | Phase 4 (Quality) | Validation pass fails | Spawn fixer (max 2 attempts). Surface if unresolved. |
98
+
99
+ ### Subagent Error Recovery
100
+
101
+ 1. **Timeout:** Forward partial output. Mark status `TIMEOUT`. Continue pipeline.
102
+ 2. **Crash/no output:** Mark status `FAILED`. Log reason. Continue if non-blocking.
103
+ 3. **Conflicting outputs:** When two specialists disagree (e.g., security vs performance), escalate to user with both positions.
104
+ 4. **Resource exhaustion:** If context window is exhausted, summarize prior context and continue with summary.
105
+
106
+ ### Retry Policies
107
+
108
+ - Subagent retries: 0 (spawn a new agent with adjusted prompt instead).
109
+ - Phase retries: Phase 3 review loop retries up to 3 iterations. All other phases: 0 retries (escalate to user).
110
+ - Never retry the same failed operation identically — adjust the prompt or approach.
111
+
112
+ ## Observability Integration
113
+
114
+ ### Structured Logging
115
+
116
+ All pipeline events should produce structured log entries when the project has observability infrastructure:
117
+
118
+ ```
119
+ {
120
+ "event": "pipeline.phase.start" | "pipeline.phase.end" | "subagent.spawn" | "subagent.complete",
121
+ "correlationId": "...",
122
+ "phase": 1-4,
123
+ "agent": "hatch3r-implementer",
124
+ "status": "SUCCESS" | "PARTIAL" | "FAILED" | "TIMEOUT",
125
+ "duration": 12345,
126
+ "metadata": {}
127
+ }
128
+ ```
129
+
130
+ ### Metrics to Track
131
+
132
+ | Metric | Description |
133
+ |--------|-------------|
134
+ | Pipeline duration | Total time from Phase 1 start to Phase 4 end |
135
+ | Phase duration | Time per phase |
136
+ | Review iterations | Number of Phase 3 review cycles |
137
+ | Specialist invocations | Count of Phase 4 specialists launched |
138
+ | Fix attempts | Number of fixer invocations across all phases |
139
+ | Failure rate | Proportion of tasks not reaching SUCCESS |
140
+
141
+ ### Correlation ID Propagation
142
+
143
+ The correlation ID generated before Phase 1 MUST be:
144
+ - Included in every subagent prompt
145
+ - Included in every structured log entry
146
+ - Included in every status report and output
147
+ - Used as the key for cross-referencing pipeline artifacts
148
+
149
+ ## Auto-Mode Guardrails
150
+
151
+ When operating in unattended/auto mode (no human in the loop), enforce these guardrails after each phase:
152
+
153
+ ### Scope Containment
154
+
155
+ - **File scope:** Only modify files identified in Phase 1 research + files discovered during implementation that are direct dependencies. No drive-by refactors.
156
+ - **Dependency scope:** Do not add new external dependencies without explicit approval.
157
+ - **Destructive operations:** Never execute `rm -rf`, `DROP TABLE`, force push, or other destructive operations in auto mode. Queue for human review.
158
+
159
+ ### Output Schema Compliance
160
+
161
+ After each phase, validate that the output conforms to the expected PipelineContext schema fields. Missing required fields trigger a HALT.
162
+
163
+ ### Escalation Triggers
164
+
165
+ Auto-mode MUST halt and surface to user when:
166
+ 1. A CRITICAL finding is detected in Phase 3.
167
+ 2. Phase 4 validation pass fails after 2 fix attempts.
168
+ 3. Any specialist reports FAILED status.
169
+ 4. Scope containment violation detected.
170
+ 5. Implementation touches more than 20 files (may indicate scope creep).
171
+
172
+ ### Budget Guards
173
+
174
+ - **Token budget:** If cumulative subagent token usage exceeds 80% of estimated budget, surface to user before spawning additional agents.
175
+ - **Time budget:** If pipeline duration exceeds 2x the estimated time (based on deep context tier), surface status and request continuation approval.
176
+
177
+ ## Adaptive Pipeline Behavior
178
+
179
+ ### Complexity-Driven Adaptation
180
+
181
+ The pipeline should adapt its behavior based on observed task complexity, not just the initial tier assignment:
182
+
183
+ | Signal During Execution | Adaptation |
184
+ |------------------------|------------|
185
+ | Phase 1 research finds >10 affected files (initial estimate was <5) | Upgrade tier to 3 if currently 2. Re-run `codebase-impact` at `deep` depth before Phase 2. |
186
+ | Phase 2 implementer reports >3 research gaps | Pause Phase 2. Run targeted researcher with gap-specific modes before continuing. |
187
+ | Phase 3 review loop reaches iteration 2 with increasing Critical count | Classify as complexity underestimate. Surface to user with recommendation to break the task into smaller sub-tasks. |
188
+ | Phase 4 validation pass fails on first attempt | Check whether failure is in test-writer's new tests (expected -- fix test) or in pre-existing tests (regression -- fix implementation). Route to appropriate fixer. |
189
+
190
+ ### Post-Pipeline Learning
191
+
192
+ After pipeline completion, the orchestrator should capture lessons for future runs:
193
+
194
+ 1. **Tier accuracy:** Was the initial tier correct? If the pipeline needed adaptation (above), log the mismatch for the learnings system.
195
+ 2. **Phase duration ratios:** Record time spent per phase. Anomalous ratios (e.g., Phase 3 taking 5x Phase 2) indicate systemic issues worth investigating.
196
+ 3. **Specialist value:** Record which Phase 4 specialists produced actionable findings vs. clean reports. Over time, this data informs smarter specialist dispatch.
197
+
198
+ ## Context Token Optimization
199
+
200
+ When pipeline context exceeds 50% of the available context window, apply these compression strategies in order:
201
+
202
+ 1. **Summarize Phase 1 output.** Replace full research findings with a structured summary: affected files (list), blast radius (count + top 3), key conventions (bullet points). Keep raw data only for the fields the current phase needs.
203
+ 2. **Prune resolved findings.** After Phase 3 review loop, remove findings that were fixed and confirmed. Only carry forward unresolved findings.
204
+ 3. **Collapse specialist results.** In the final output, summarize specialist results as a single status table rather than including full specialist reports. Full reports are available on request.
205
+ 4. **Never truncate security findings.** Security auditor output is always included in full regardless of context pressure.
206
+
207
+ These strategies preserve decision-critical information while reducing token overhead for long pipelines.
@@ -0,0 +1,202 @@
1
+ ---
2
+ description: Extended orchestration reference — PipelineContext schemas, resilience protocols, observability integration, and auto-mode guardrails
3
+ globs: ["**/.agents/**", "**/pipeline/**", "**/*orchestrat*", "**/*agent*"]
4
+ alwaysApply: false
5
+ ---
6
+ # Agent Orchestration — Extended Reference
7
+
8
+ This is the on-demand companion to `hatch3r-agent-orchestration`. Load when you need detailed schemas, failure handling protocols, or guardrail specifications.
9
+
10
+ ## PipelineContext Schema
11
+
12
+ The `PipelineContext` is the structured handoff object passed between pipeline phases. Each phase reads its inputs and writes its outputs to this context.
13
+
14
+ ```
15
+ PipelineContext {
16
+ correlationId: string // UUID v4, generated before Phase 1
17
+ taskType: "bug" | "feature" | "refactor" | "qa"
18
+ issueRef: string | null // Issue number or null for plain chat
19
+ deepContextTier: 1 | 2 | 3 // From hatch3r-deep-context scoring
20
+
21
+ // Detected project type for specialist selection (Finding #56)
22
+ projectType?: {
23
+ languages: string[] // From repo analysis (e.g., "typescript", "python", "go")
24
+ frameworks: string[] // Detected frameworks (e.g., "next", "express")
25
+ isMonorepo: boolean
26
+ packageManager: string // "npm" | "yarn" | "pnpm" | "bun" | "unknown"
27
+ }
28
+
29
+ // Phase 1 outputs (Research)
30
+ researchFindings: {
31
+ modes: string[] // Researcher modes used
32
+ affectedFiles: string[] // Files to create/modify/delete
33
+ blastRadius: string[] // Downstream consumers
34
+ existingTests: string[] // Test files covering affected code
35
+ dependencies: string[] // Internal + external dependencies
36
+ conventions: object | null // From similar-implementation mode
37
+ resolvedRequirements: object | null // From requirements-elicitation
38
+ }
39
+
40
+ // Research gap flags from mid-implementation checkpoint (Finding #52)
41
+ researchGaps?: string[] // Gaps identified during Phase 2
42
+
43
+ // Phase 2 outputs (Implementation)
44
+ implementationResult: {
45
+ filesChanged: string[]
46
+ testsWritten: string[]
47
+ status: "SUCCESS" | "PARTIAL" | "FAILED" | "SKIPPED" | "TIMEOUT"
48
+ reason: string | null
49
+ }
50
+
51
+ // Phase 3 outputs (Review)
52
+ reviewResult: {
53
+ iterations: number // 1-3
54
+ finalVerdict: "CLEAN" | "UNRESOLVED"
55
+ findings: ReviewFinding[]
56
+ confirmationPassResult: "PASS" | "FAIL"
57
+ }
58
+
59
+ // Phase 4 outputs (Quality)
60
+ qualityResults: {
61
+ specialists: SpecialistResult[]
62
+ validationPass: {
63
+ testsPass: boolean
64
+ typecheckPass: boolean
65
+ fixAttempts: number
66
+ regressionsPersist: boolean
67
+ }
68
+ }
69
+
70
+ // Metadata
71
+ startedAt: string // ISO-8601
72
+ completedAt: string | null
73
+ totalDuration: number | null // milliseconds
74
+ }
75
+ ```
76
+
77
+ The TypeScript implementation of this schema with runtime validation is in `src/pipeline/pipelineContext.ts`. Use `validatePhaseTransition()` to verify context completeness before advancing between phases.
78
+
79
+ ## Resilience and Failure Handling
80
+
81
+ ### Phase Failure Protocols
82
+
83
+ | Phase | Failure Mode | Protocol |
84
+ |-------|-------------|----------|
85
+ | Phase 1 (Research) | Researcher timeout | Proceed with partial findings; flag missing modes. |
86
+ | Phase 1 (Research) | No relevant findings | Surface to user; ask whether to proceed with implementation. |
87
+ | Phase 2 (Implementation) | Build/test failure | Attempt self-fix (max 2 iterations). Escalate to user if unresolved. |
88
+ | Phase 2 (Implementation) | Scope creep detected | Halt. Surface deviation to user. Resume only with approval. |
89
+ | Phase 3 (Review) | Max iterations (3) | Surface unresolved findings to user. Do not merge. |
90
+ | Phase 3 (Review) | Fixer introduces regressions | Revert fixer changes. Surface original findings + regression to user. |
91
+ | Phase 4 (Quality) | Specialist timeout | Log timeout. Continue with available results. Flag in output. |
92
+ | Phase 4 (Quality) | Validation pass fails | Spawn fixer (max 2 attempts). Surface if unresolved. |
93
+
94
+ ### Subagent Error Recovery
95
+
96
+ 1. **Timeout:** Forward partial output. Mark status `TIMEOUT`. Continue pipeline.
97
+ 2. **Crash/no output:** Mark status `FAILED`. Log reason. Continue if non-blocking.
98
+ 3. **Conflicting outputs:** When two specialists disagree (e.g., security vs performance), escalate to user with both positions.
99
+ 4. **Resource exhaustion:** If context window is exhausted, summarize prior context and continue with summary.
100
+
101
+ ### Retry Policies
102
+
103
+ - Subagent retries: 0 (spawn a new agent with adjusted prompt instead).
104
+ - Phase retries: Phase 3 review loop retries up to 3 iterations. All other phases: 0 retries (escalate to user).
105
+ - Never retry the same failed operation identically — adjust the prompt or approach.
106
+
107
+ ## Observability Integration
108
+
109
+ ### Structured Logging
110
+
111
+ All pipeline events should produce structured log entries when the project has observability infrastructure:
112
+
113
+ ```
114
+ {
115
+ "event": "pipeline.phase.start" | "pipeline.phase.end" | "subagent.spawn" | "subagent.complete",
116
+ "correlationId": "...",
117
+ "phase": 1-4,
118
+ "agent": "hatch3r-implementer",
119
+ "status": "SUCCESS" | "PARTIAL" | "FAILED" | "TIMEOUT",
120
+ "duration": 12345,
121
+ "metadata": {}
122
+ }
123
+ ```
124
+
125
+ ### Metrics to Track
126
+
127
+ | Metric | Description |
128
+ |--------|-------------|
129
+ | Pipeline duration | Total time from Phase 1 start to Phase 4 end |
130
+ | Phase duration | Time per phase |
131
+ | Review iterations | Number of Phase 3 review cycles |
132
+ | Specialist invocations | Count of Phase 4 specialists launched |
133
+ | Fix attempts | Number of fixer invocations across all phases |
134
+ | Failure rate | Proportion of tasks not reaching SUCCESS |
135
+
136
+ ### Correlation ID Propagation
137
+
138
+ The correlation ID generated before Phase 1 MUST be:
139
+ - Included in every subagent prompt
140
+ - Included in every structured log entry
141
+ - Included in every status report and output
142
+ - Used as the key for cross-referencing pipeline artifacts
143
+
144
+ ## Auto-Mode Guardrails
145
+
146
+ When operating in unattended/auto mode (no human in the loop), enforce these guardrails after each phase:
147
+
148
+ ### Scope Containment
149
+
150
+ - **File scope:** Only modify files identified in Phase 1 research + files discovered during implementation that are direct dependencies. No drive-by refactors.
151
+ - **Dependency scope:** Do not add new external dependencies without explicit approval.
152
+ - **Destructive operations:** Never execute `rm -rf`, `DROP TABLE`, force push, or other destructive operations in auto mode. Queue for human review.
153
+
154
+ ### Output Schema Compliance
155
+
156
+ After each phase, validate that the output conforms to the expected PipelineContext schema fields. Missing required fields trigger a HALT.
157
+
158
+ ### Escalation Triggers
159
+
160
+ Auto-mode MUST halt and surface to user when:
161
+ 1. A CRITICAL finding is detected in Phase 3.
162
+ 2. Phase 4 validation pass fails after 2 fix attempts.
163
+ 3. Any specialist reports FAILED status.
164
+ 4. Scope containment violation detected.
165
+ 5. Implementation touches more than 20 files (may indicate scope creep).
166
+
167
+ ### Budget Guards
168
+
169
+ - **Token budget:** If cumulative subagent token usage exceeds 80% of estimated budget, surface to user before spawning additional agents.
170
+ - **Time budget:** If pipeline duration exceeds 2x the estimated time (based on deep context tier), surface status and request continuation approval.
171
+
172
+ ## Adaptive Pipeline Behavior
173
+
174
+ ### Complexity-Driven Adaptation
175
+
176
+ The pipeline should adapt its behavior based on observed task complexity, not just the initial tier assignment:
177
+
178
+ | Signal During Execution | Adaptation |
179
+ |------------------------|------------|
180
+ | Phase 1 research finds >10 affected files (initial estimate was <5) | Upgrade tier to 3 if currently 2. Re-run `codebase-impact` at `deep` depth before Phase 2. |
181
+ | Phase 2 implementer reports >3 research gaps | Pause Phase 2. Run targeted researcher with gap-specific modes before continuing. |
182
+ | Phase 3 review loop reaches iteration 2 with increasing Critical count | Classify as complexity underestimate. Surface to user with recommendation to break the task into smaller sub-tasks. |
183
+ | Phase 4 validation pass fails on first attempt | Check whether failure is in test-writer's new tests (expected -- fix test) or in pre-existing tests (regression -- fix implementation). Route to appropriate fixer. |
184
+
185
+ ### Post-Pipeline Learning
186
+
187
+ After pipeline completion, the orchestrator should capture lessons for future runs:
188
+
189
+ 1. **Tier accuracy:** Was the initial tier correct? If the pipeline needed adaptation (above), log the mismatch for the learnings system.
190
+ 2. **Phase duration ratios:** Record time spent per phase. Anomalous ratios (e.g., Phase 3 taking 5x Phase 2) indicate systemic issues worth investigating.
191
+ 3. **Specialist value:** Record which Phase 4 specialists produced actionable findings vs. clean reports. Over time, this data informs smarter specialist dispatch.
192
+
193
+ ## Context Token Optimization
194
+
195
+ When pipeline context exceeds 50% of the available context window, apply these compression strategies in order:
196
+
197
+ 1. **Summarize Phase 1 output.** Replace full research findings with a structured summary: affected files (list), blast radius (count + top 3), key conventions (bullet points). Keep raw data only for the fields the current phase needs.
198
+ 2. **Prune resolved findings.** After Phase 3 review loop, remove findings that were fixed and confirmed. Only carry forward unresolved findings.
199
+ 3. **Collapse specialist results.** In the final output, summarize specialist results as a single status table rather than including full specialist reports. Full reports are available on request.
200
+ 4. **Never truncate security findings.** Security auditor output is always included in full regardless of context pressure.
201
+
202
+ These strategies preserve decision-critical information while reducing token overhead for long pipelines.