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.
- package/README.md +12 -7
- package/agents/hatch3r-a11y-auditor.md +18 -11
- package/agents/hatch3r-architect.md +27 -12
- package/agents/hatch3r-ci-watcher.md +30 -9
- package/agents/hatch3r-context-rules.md +18 -8
- package/agents/hatch3r-dependency-auditor.md +30 -15
- package/agents/hatch3r-devops.md +18 -13
- package/agents/hatch3r-docs-writer.md +33 -12
- package/agents/hatch3r-fixer.md +46 -9
- package/agents/hatch3r-implementer.md +21 -9
- package/agents/hatch3r-learnings-loader.md +24 -7
- package/agents/hatch3r-lint-fixer.md +18 -9
- package/agents/hatch3r-perf-profiler.md +26 -10
- package/agents/hatch3r-researcher.md +57 -919
- package/agents/hatch3r-reviewer.md +29 -10
- package/agents/hatch3r-security-auditor.md +25 -10
- package/agents/hatch3r-test-writer.md +29 -9
- package/agents/modes/architecture.md +1 -0
- package/agents/modes/boundary-analysis.md +2 -1
- package/agents/modes/codebase-impact.md +1 -0
- package/agents/modes/complexity-risk.md +1 -0
- package/agents/modes/coverage-analysis.md +1 -0
- package/agents/modes/current-state.md +1 -0
- package/agents/modes/feature-design.md +1 -0
- package/agents/modes/impact-analysis.md +1 -0
- package/agents/modes/library-docs.md +2 -1
- package/agents/modes/migration-path.md +1 -0
- package/agents/modes/prior-art.md +1 -0
- package/agents/modes/refactoring-strategy.md +1 -0
- package/agents/modes/regression.md +1 -0
- package/agents/modes/requirements-elicitation.md +1 -0
- package/agents/modes/risk-assessment.md +1 -0
- package/agents/modes/risk-prioritization.md +1 -0
- package/agents/modes/root-cause.md +1 -0
- package/agents/modes/similar-implementation.md +2 -1
- package/agents/modes/symptom-trace.md +1 -0
- package/agents/modes/test-pattern.md +2 -1
- package/agents/shared/external-knowledge.md +31 -0
- package/agents/shared/quality-charter.md +96 -0
- package/checks/README.md +1 -0
- package/checks/accessibility.md +55 -0
- package/commands/board/pickup-azure-devops.md +5 -0
- package/commands/board/pickup-delegation-multi.md +9 -1
- package/commands/board/pickup-delegation.md +4 -0
- package/commands/board/pickup-github.md +5 -0
- package/commands/board/pickup-gitlab.md +5 -0
- package/commands/board/pickup-modes.md +1 -0
- package/commands/board/pickup-post-impl.md +9 -1
- package/commands/board/shared-azure-devops.md +14 -3
- package/commands/board/shared-board-overview.md +1 -0
- package/commands/board/shared-github.md +2 -0
- package/commands/board/shared-gitlab.md +10 -2
- package/commands/hatch3r-agent-customize.md +6 -1
- package/commands/hatch3r-api-spec.md +1 -0
- package/commands/hatch3r-benchmark.md +4 -3
- package/commands/hatch3r-board-fill.md +52 -9
- package/commands/hatch3r-board-groom.md +124 -7
- package/commands/hatch3r-board-init.md +7 -3
- package/commands/hatch3r-board-pickup.md +1 -0
- package/commands/hatch3r-board-refresh.md +1 -0
- package/commands/hatch3r-board-shared.md +71 -5
- package/commands/hatch3r-bug-plan.md +2 -1
- package/commands/hatch3r-codebase-map.md +4 -3
- package/commands/hatch3r-command-customize.md +6 -1
- package/commands/hatch3r-context-health.md +1 -0
- package/commands/hatch3r-cost-tracking.md +1 -0
- package/commands/hatch3r-debug.md +4 -3
- package/commands/hatch3r-dep-audit.md +3 -0
- package/commands/hatch3r-feature-plan.md +3 -2
- package/commands/hatch3r-healthcheck.md +1 -0
- package/commands/hatch3r-hooks.md +6 -1
- package/commands/hatch3r-learn.md +1 -0
- package/commands/hatch3r-migration-plan.md +3 -2
- package/commands/hatch3r-onboard.md +2 -1
- package/commands/hatch3r-project-spec.md +4 -3
- package/commands/hatch3r-quick-change.md +31 -3
- package/commands/hatch3r-recipe.md +1 -0
- package/commands/hatch3r-refactor-plan.md +2 -1
- package/commands/hatch3r-release.md +4 -1
- package/commands/hatch3r-revision.md +138 -17
- package/commands/hatch3r-roadmap.md +5 -4
- package/commands/hatch3r-rule-customize.md +5 -0
- package/commands/hatch3r-security-audit.md +1 -0
- package/commands/hatch3r-skill-customize.md +5 -0
- package/commands/hatch3r-test-plan.md +3 -2
- package/commands/hatch3r-workflow.md +15 -1
- package/dist/cli/index.js +7595 -4548
- package/dist/cli/index.js.map +1 -1
- package/hooks/hatch3r-ci-failure.md +1 -0
- package/hooks/hatch3r-file-save.md +1 -0
- package/hooks/hatch3r-post-merge.md +1 -0
- package/hooks/hatch3r-pre-commit.md +1 -0
- package/hooks/hatch3r-pre-push.md +1 -0
- package/hooks/hatch3r-session-start.md +1 -0
- package/package.json +30 -12
- package/rules/hatch3r-accessibility-standards.md +2 -1
- package/rules/hatch3r-accessibility-standards.mdc +1 -1
- package/rules/hatch3r-agent-orchestration-detail.md +207 -0
- package/rules/hatch3r-agent-orchestration-detail.mdc +202 -0
- package/rules/hatch3r-agent-orchestration.md +161 -318
- package/rules/hatch3r-agent-orchestration.mdc +212 -154
- package/rules/hatch3r-api-design.md +2 -1
- package/rules/hatch3r-api-design.mdc +1 -1
- package/rules/hatch3r-browser-verification.md +4 -2
- package/rules/hatch3r-browser-verification.mdc +1 -0
- package/rules/hatch3r-ci-cd.md +2 -1
- package/rules/hatch3r-ci-cd.mdc +1 -1
- package/rules/hatch3r-code-standards.md +15 -2
- package/rules/hatch3r-code-standards.mdc +22 -2
- package/rules/hatch3r-component-conventions.md +2 -1
- package/rules/hatch3r-component-conventions.mdc +1 -1
- package/rules/hatch3r-data-classification.md +2 -1
- package/rules/hatch3r-data-classification.mdc +1 -1
- package/rules/hatch3r-deep-context.md +26 -1
- package/rules/hatch3r-deep-context.mdc +54 -8
- package/rules/hatch3r-dependency-management.md +2 -1
- package/rules/hatch3r-dependency-management.mdc +17 -5
- package/rules/hatch3r-feature-flags.md +2 -0
- package/rules/hatch3r-feature-flags.mdc +1 -0
- package/rules/hatch3r-git-conventions.md +2 -1
- package/rules/hatch3r-git-conventions.mdc +2 -1
- package/rules/hatch3r-i18n.md +2 -1
- package/rules/hatch3r-i18n.mdc +1 -1
- package/rules/hatch3r-learning-consult.md +11 -1
- package/rules/hatch3r-learning-consult.mdc +11 -1
- package/rules/hatch3r-migrations.md +2 -1
- package/rules/hatch3r-migrations.mdc +12 -1
- package/rules/hatch3r-observability-logging.md +34 -0
- package/rules/hatch3r-observability-logging.mdc +30 -0
- package/rules/hatch3r-observability-metrics.md +74 -0
- package/rules/hatch3r-observability-metrics.mdc +70 -0
- package/rules/hatch3r-observability-tracing-detail.md +160 -0
- package/rules/hatch3r-observability-tracing-detail.mdc +63 -0
- package/rules/hatch3r-observability-tracing.md +86 -0
- package/rules/hatch3r-observability-tracing.mdc +77 -0
- package/rules/hatch3r-observability.md +9 -448
- package/rules/hatch3r-observability.mdc +7 -159
- package/rules/hatch3r-performance-budgets.md +2 -0
- package/rules/hatch3r-performance-budgets.mdc +1 -0
- package/rules/hatch3r-secrets-management.md +2 -1
- package/rules/hatch3r-secrets-management.mdc +1 -1
- package/rules/hatch3r-security-patterns.md +3 -2
- package/rules/hatch3r-security-patterns.mdc +12 -1
- package/rules/hatch3r-testing.md +12 -2
- package/rules/hatch3r-testing.mdc +11 -2
- package/rules/hatch3r-theming.md +3 -2
- package/rules/hatch3r-theming.mdc +1 -1
- package/rules/hatch3r-tooling-hierarchy.md +3 -2
- package/rules/hatch3r-tooling-hierarchy.mdc +19 -5
- package/skills/hatch3r-a11y-audit/SKILL.md +11 -4
- package/skills/hatch3r-agent-customize/SKILL.md +5 -72
- package/skills/hatch3r-api-spec/SKILL.md +9 -2
- package/skills/hatch3r-architecture-review/SKILL.md +7 -0
- package/skills/hatch3r-bug-fix/SKILL.md +16 -7
- package/skills/hatch3r-ci-pipeline/SKILL.md +8 -1
- package/skills/hatch3r-command-customize/SKILL.md +5 -62
- package/skills/hatch3r-context-health/SKILL.md +23 -2
- package/skills/hatch3r-cost-tracking/SKILL.md +16 -6
- package/skills/hatch3r-customize/SKILL.md +124 -0
- package/skills/hatch3r-dep-audit/SKILL.md +9 -2
- package/skills/hatch3r-feature/SKILL.md +12 -4
- package/skills/hatch3r-gh-agentic-workflows/SKILL.md +7 -0
- package/skills/hatch3r-incident-response/SKILL.md +7 -0
- package/skills/hatch3r-issue-workflow/SKILL.md +8 -1
- package/skills/hatch3r-logical-refactor/SKILL.md +8 -1
- package/skills/hatch3r-migration/SKILL.md +7 -0
- package/skills/hatch3r-perf-audit/SKILL.md +9 -2
- package/skills/hatch3r-pr-creation/SKILL.md +8 -1
- package/skills/hatch3r-qa-validation/SKILL.md +8 -1
- package/skills/hatch3r-recipe/SKILL.md +8 -1
- package/skills/hatch3r-refactor/SKILL.md +10 -2
- package/skills/hatch3r-release/SKILL.md +8 -1
- package/skills/hatch3r-rule-customize/SKILL.md +5 -65
- package/skills/hatch3r-skill-customize/SKILL.md +5 -62
- package/skills/hatch3r-visual-refactor/SKILL.md +12 -5
package/package.json
CHANGED
|
@@ -1,8 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hatch3r",
|
|
3
|
-
"version": "1.
|
|
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": "^
|
|
68
|
-
"inquirer": "^
|
|
78
|
+
"commander": "^14.0.3",
|
|
79
|
+
"inquirer": "^13.3.2",
|
|
69
80
|
"ora": "^9.3.0",
|
|
70
|
-
"yaml": "^2.
|
|
81
|
+
"yaml": "^2.8.3"
|
|
71
82
|
},
|
|
72
83
|
"devDependencies": {
|
|
73
|
-
"@types/node": "^25.
|
|
74
|
-
"@vitest/coverage-v8": "^
|
|
75
|
-
"eslint": "^
|
|
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": "^
|
|
78
|
-
"typescript-eslint": "^8.
|
|
79
|
-
"vitest": "^
|
|
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:
|
|
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
|
-
|
|
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.
|