heimdall-agent 1.0.0 → 1.1.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 +57 -26
- package/README.pt-BR.md +429 -0
- package/agents/cloud-engineer.md +77 -0
- package/agents/code-sentinel.md +66 -35
- package/agents/database-architect.md +31 -25
- package/agents/frontend-designer.md +30 -28
- package/agents/mobile-designer.md +25 -24
- package/agents/modernizer.md +66 -0
- package/agents/orchestrator.md +94 -93
- package/agents/reviewer.md +100 -71
- package/agents/security-auditor.md +27 -27
- package/agents/tester.md +97 -90
- package/commands/grill-me.md +20 -4
- package/commands/orchestrate.md +16 -0
- package/commands/orchestrator.md +16 -0
- package/commands/plan.md +17 -1
- package/config/agents.json +21 -3
- package/config/mcp.json +72 -0
- package/config/models.json +26 -16
- package/config/profiles.json +2 -4
- package/config/skills.json +210 -100
- package/docs/SKILLS.md +341 -245
- package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
- package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
- package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
- package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
- package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
- package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
- package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
- package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
- package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
- package/docs/runs/skill-audit/customization-report.json +380 -0
- package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
- package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
- package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
- package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
- package/docs/runs/skill-audit/inventory.json +308 -0
- package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
- package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
- package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
- package/docs/runs/skill-audit/probe.ps1 +16 -0
- package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
- package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
- package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
- package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
- package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
- package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
- package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
- package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
- package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
- package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
- package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
- package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
- package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
- package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
- package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
- package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
- package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
- package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
- package/docs/runs/skill-audit/update-manifest.md +88 -0
- package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
- package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
- package/docs/runs/skill-audit/upstream-status.json +563 -0
- package/docs/runs/skill-audit/verification-results.json +252 -0
- package/doctrine/AGENTS.md +39 -77
- package/hooks/git/pre-commit +11 -0
- package/hooks/heimdall-hook.cjs +81 -2
- package/hooks/herdr-agent-state.ps1 +55 -0
- package/hooks/hooks.json +0 -11
- package/lib/catalog-sync.cjs +162 -0
- package/lib/hermes-context.cjs +57 -0
- package/lib/model-context.cjs +123 -0
- package/lib/path-discovery.cjs +94 -0
- package/package.json +7 -3
- package/playbooks/01-interactive-grilling-gate.md +14 -1
- package/playbooks/02-fast-code-deep-verification.md +3 -2
- package/playbooks/03-adversarial-code-review.md +3 -3
- package/playbooks/05-canonical-plan-template.md +32 -18
- package/playbooks/06-model-registry-matrix.md +24 -13
- package/playbooks/07-legacy-code-modernization.md +74 -0
- package/playbooks/08-backlog-and-change-request-flow.md +122 -0
- package/setup.mjs +592 -172
- package/skills/antislop/SKILL.md +76 -56
- package/skills/antislop/VERSION +1 -0
- package/skills/antislop-copywriting/SKILL.md +372 -372
- package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-human/SKILL.md +204 -147
- package/skills/antislop-human/contrast-check.py +168 -165
- package/skills/antislop-human/contrast-mcp.py +6 -3
- package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
- package/skills/antislop-human/references/WCAG.md +127 -0
- package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-ui/SKILL.md +344 -304
- package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
- package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
- package/skills/brainstorming/SKILL.md +274 -265
- package/skills/brainstorming/builder-check-prompt.md +23 -0
- package/skills/brainstorming/scripts/frame-template.html +213 -213
- package/skills/brainstorming/scripts/server.cjs +723 -723
- package/skills/brandkit/SKILL.md +798 -798
- package/skills/brutalist-skill/SKILL.md +93 -92
- package/skills/caveman/README.md +68 -0
- package/skills/caveman/SKILL.md +73 -38
- package/skills/claude-collaborator/SKILL.md +24 -44
- package/skills/clean-code/SKILL.md +152 -0
- package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
- package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
- package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
- package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
- package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
- package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
- package/skills/cloudflare-security-audit/HUNTING.md +251 -251
- package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
- package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
- package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
- package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
- package/skills/cloudflare-security-audit/SKILL.md +192 -192
- package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
- package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
- package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
- package/skills/cloudflare-security-audit/report-schema.json +461 -461
- package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
- package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
- package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
- package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
- package/skills/codex-collaborator/SKILL.md +24 -45
- package/skills/communication-doctrine/SKILL.md +89 -0
- package/skills/diagnosing-superpowers/SKILL.md +1 -1
- package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
- package/skills/diagnosing-superpowers/templates/issue.md +23 -4
- package/skills/executing-plans/SKILL.md +0 -52
- package/skills/executing-plans/scripts/task-done +52 -52
- package/skills/executing-plans/scripts/task-start +28 -28
- package/skills/gemini-collaborator/SKILL.md +24 -56
- package/skills/herdr/SKILL.md +243 -0
- package/skills/image-to-code-skill/SKILL.md +1228 -1228
- package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
- package/skills/imagegen-frontend-web/SKILL.md +987 -987
- package/skills/karpathy-guidelines/SKILL.md +67 -67
- package/skills/mcp-engineering/SKILL.md +74 -0
- package/skills/minimalist-skill/SKILL.md +87 -85
- package/skills/output-skill/SKILL.md +49 -49
- package/skills/ponytail/SKILL.md +36 -52
- package/skills/postgres-best-practices/SKILL.md +30 -52
- package/skills/postgres-best-practices/references/backup-restore.md +372 -0
- package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
- package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
- package/skills/postgres-best-practices/references/hot-standby.md +221 -0
- package/skills/postgres-best-practices/references/indexing.md +318 -0
- package/skills/postgres-best-practices/references/logical-replication.md +610 -0
- package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
- package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
- package/skills/postgres-best-practices/references/query-optimization.md +294 -0
- package/skills/postgres-best-practices/references/query-patterns.md +566 -0
- package/skills/postgres-best-practices/references/schema-design.md +362 -0
- package/skills/postgres-best-practices/references/security-roles.md +489 -0
- package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
- package/skills/progressive-disclosure/SKILL.md +68 -0
- package/skills/pstack-discipline/SKILL.md +40 -0
- package/skills/receiving-code-review/SKILL.md +2 -23
- package/skills/requesting-code-review/SKILL.md +7 -36
- package/skills/soft-skill/SKILL.md +99 -98
- package/skills/stitch-skill/DESIGN.md +121 -121
- package/skills/stitch-skill/SKILL.md +185 -184
- package/skills/strix-security/SKILL.md +54 -53
- package/skills/subagent-driven-development/SKILL.md +28 -260
- package/skills/subagent-driven-development/references/batching.md +11 -0
- package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
- package/skills/subagent-driven-development/references/final-review.md +47 -0
- package/skills/subagent-driven-development/references/fix-loop.md +77 -0
- package/skills/subagent-driven-development/references/handling-reports.md +15 -0
- package/skills/subagent-driven-development/references/preflight.md +26 -0
- package/skills/subagent-driven-development/references/resuming.md +12 -0
- package/skills/subagent-driven-development/scripts/review-package +53 -53
- package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
- package/skills/subagent-driven-development/scripts/task-brief +43 -43
- package/skills/systematic-debugging/SKILL.md +283 -306
- package/skills/taste-skill/SKILL.md +542 -1206
- package/skills/taste-skill/references/app-screens.md +1199 -0
- package/skills/taste-skill/references/colour.md +141 -0
- package/skills/taste-skill/references/copy.md +177 -0
- package/skills/taste-skill/references/critique.md +182 -0
- package/skills/taste-skill/references/imagery.md +791 -0
- package/skills/taste-skill/references/layout.md +292 -0
- package/skills/taste-skill/references/motion.md +980 -0
- package/skills/taste-skill/references/research.md +356 -0
- package/skills/taste-skill/references/scenes.md +174 -0
- package/skills/taste-skill/references/tells.md +115 -0
- package/skills/taste-skill/references/type.md +170 -0
- package/skills/test-driven-development/SKILL.md +330 -337
- package/skills/thermo/SKILL.md +67 -0
- package/skills/threat-modeling/SKILL.md +55 -0
- package/skills/trailofbits-audit-context/SKILL.md +72 -72
- package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
- package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
- package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
- package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
- package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
- package/skills/verification-before-completion/SKILL.md +0 -14
- package/skills/writing-plans/SKILL.md +11 -15
- package/skills/writing-skills/SKILL.md +21 -303
- package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
- package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
- package/skills/writing-skills/references/bulletproofing.md +80 -0
- package/skills/writing-skills/references/discovery.md +201 -0
- package/skills/writing-skills/references/flowcharts.md +37 -0
- package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
- package/skills/writing-skills/references/persuasion-principles.md +187 -0
- package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
- package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
- package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
- package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
- package/skills/gpt-tasteskill/SKILL.md +0 -74
- package/skills/taste-skill-v1/SKILL.md +0 -226
- /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
- /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
- /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
- /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
- /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
- /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
- /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
- /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
|
@@ -4,12 +4,19 @@
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
## 1. Access Channels
|
|
7
|
+
## 1. Access Channels & Multi-Agent Multiplexing
|
|
8
8
|
|
|
9
|
-
Models are
|
|
10
|
-
|
|
11
|
-
- **
|
|
12
|
-
-
|
|
9
|
+
Models are partitioned into two architectural access channels:
|
|
10
|
+
|
|
11
|
+
- **Channel 1: GhostCLI Unified Gateway (`https://ghostcli.cloud`)**
|
|
12
|
+
- Powers **Claude Code CLI**, **OpenAI Codex CLI**, and **Hermes Agent**.
|
|
13
|
+
- Serves all Anthropic models (`claude-*`), OpenAI models (`gpt-6-astra`), and Zhipu AI models (`z-ai/glm-5.3`, `z-ai/glm-5.3-flash`).
|
|
14
|
+
- Because GhostCLI exposes multi-protocol translation (`/v1/messages`, `/v1/responses`, `/v1/chat/completions`), Claude Code can run GPT-6 Astra or GLM directly (`claude --model gpt-6-astra`), and Codex can run Claude Sonnet directly (`codex --model claude-sonnet-5`).
|
|
15
|
+
- When coordinating between harnesses in Herdr (`HERDR_ENV=1`), use native Herdr multiplexing (`herdr agent start/prompt`) directly.
|
|
16
|
+
|
|
17
|
+
- **Channel 2: Google Gemini Direct API (`gemini.googleapis.com`)**
|
|
18
|
+
- Powers **Google Antigravity** natively (via direct Google OAuth).
|
|
19
|
+
- Coordinated across harnesses via native Herdr (`herdr agent start <name> --kind agy`).
|
|
13
20
|
|
|
14
21
|
---
|
|
15
22
|
|
|
@@ -22,20 +29,23 @@ All GhostCLI models support text and image input:
|
|
|
22
29
|
| **Claude Opus 5.5** | `claude-opus-5-5` | 256K / 1M extended | 128K | ✅ | ✅ | `low`, `medium`, `high`, `xhigh` | Deepest architectural reasoning, complex multi-system debugging, critical security audits, knotty algorithms. |
|
|
23
30
|
| **Claude Sonnet 5** | `claude-sonnet-5` | 256K / 1M extended | 128K | ✅ | ✅ | `low`, `medium`, `high`, `xhigh` | Primary full-stack coding driver, type-safe API schemas, database mutation logic, Playwright E2E test authoring. |
|
|
24
31
|
| **Claude Fable 5.1** | `claude-fable-5.1` | 256K / 1M extended | 128K | ✅ | ✅ | `low`, `medium`, `high`, `xhigh` | Visual storytelling, high-polish frontend design, copycrafting, UI aesthetic alignment, interaction flows. |
|
|
25
|
-
| **GLM 5.3** | `z-ai/glm-5.3` | 1M | 128K | ❌ | ❌ | `low`, `medium`, `high`, `xhigh` | Massive context analysis, long-document processing, Zhipu AI reasoning. |
|
|
32
|
+
| **GLM 5.3** | `z-ai/glm-5.3` | 1M | 128K | ❌ | ❌ | `low`, `medium`, `high`, `xhigh` | Massive context analysis, long-document processing, Zhipu AI reasoning (upstream may experience upstream queue delays). |
|
|
33
|
+
| **GLM 5.3 Flash** | `z-ai/glm-5.3-flash` | 1M | 128K | ❌ | ❌ | `low`, `medium`, `high` | Fast responses for code tasks, rapid reasoning, lightweight context queries. |
|
|
26
34
|
| **GPT-6 Astra** | `gpt-6-astra` | 1M | 128K | ✅ | ✅ | `low`, `medium`, `high`, `xhigh` | OpenAI reasoning, broad general-purpose tasks, alternative perspective for cross-validation. |
|
|
27
35
|
|
|
36
|
+
> [!WARNING]
|
|
37
|
+
> **Naming Asymmetry Guardrail**: Opus is version **5.5** (`claude-opus-5-5`), while Sonnet is strictly version **5** (`claude-sonnet-5`). Do NOT hallucinate `claude-sonnet-5-5` or `sonnet-5-5`. There is no 5.5 release for Sonnet.
|
|
38
|
+
|
|
28
39
|
---
|
|
29
40
|
|
|
30
|
-
## 3.
|
|
41
|
+
## 3. Google Antigravity Models (Google API Direct)
|
|
31
42
|
|
|
32
|
-
Accessed via
|
|
43
|
+
Accessed natively via Google Antigravity / `agy` CLI (never through GhostCLI):
|
|
33
44
|
|
|
34
45
|
| Model Name | Canonical Flag | Allowed Effort Levels | Optimal Specialization |
|
|
35
46
|
| :--- | :--- | :--- | :--- |
|
|
36
|
-
| **Gemini 4
|
|
37
|
-
| **Gemini 3.8 Flash** | `gemini-3.8-flash` | `low`, `medium`, `high` | Fast scans, workspace audits, boilerplate generation, unit test scaffolding, rapid prototyping, responsive styling. |
|
|
38
|
-
| **Gemini 3.1 Pro** | `gemini-3.1-pro` | `medium`, `high`, `xhigh` | Massive context analysis, repository-wide multi-file refactoring, deep documentation synthesis, architectural audits. |
|
|
47
|
+
| **Gemini 4 Argon** | `gemini-4-argon-{effort}` (e.g. `gemini-4-argon-high`) | `low`, `medium`, `high`, `xhigh` | Next-generation flagship Gemini reasoning, complex multi-file architecture, deep cross-workspace synthesis, high-velocity full-stack implementation. |
|
|
48
|
+
| **Gemini 3.8 Flash** | `gemini-3.8-flash-{effort}` (e.g. `gemini-3.8-flash-high`) | `low`, `medium`, `high` | Fast scans, workspace audits, boilerplate generation, unit test scaffolding, rapid prototyping, responsive styling. |
|
|
39
49
|
|
|
40
50
|
---
|
|
41
51
|
|
|
@@ -62,11 +72,12 @@ The `/model` picker in Claude Code shows a hardcoded list that may include model
|
|
|
62
72
|
|
|
63
73
|
To dispatch any GhostCLI model — including those invisible in the picker — pass its canonical flag via the Agent tool's `model` parameter when spawning subagents (e.g. `model: "gpt-6-astra"`, `model: "z-ai/glm-5.3"`). The API call routes through GhostCLI regardless of what `/model` displays.
|
|
64
74
|
|
|
65
|
-
Gemini models (`gemini-4`, `gemini-3.8-flash`, `gemini-3.1-pro`) are never reachable through GhostCLI; they
|
|
75
|
+
Gemini models (`gemini-4`, `gemini-3.8-flash`, `gemini-3.1-pro`) are never reachable through GhostCLI; they are accessed natively via Google Antigravity (`agy` CLI in Herdr).
|
|
66
76
|
|
|
67
77
|
---
|
|
68
78
|
|
|
69
79
|
## 6. Effort Constraint & Fallback Rules
|
|
70
80
|
|
|
71
81
|
- **Effort Constraint Rule**: Each task in a plan must explicitly declare one of the registered models and an allowed effort level matching the tables above.
|
|
72
|
-
- **Quota Fallback Rule**: When Gemini 4 Argon reaches quota cooldown, immediately fallback to Gemini 3.8 Flash (for fast scans/reviews) or
|
|
82
|
+
- **Quota Fallback Rule**: When Gemini 4 Argon reaches quota cooldown, immediately fallback to Gemini 3.8 Flash (for fast scans/reviews) or Claude Sonnet 5 / GPT-6 Astra via GhostCLI.
|
|
83
|
+
- **Headless Execution Limitation**: The `agy` CLI requires a TTY for all execution modes including `--print`. Non-interactive/headless invocations from scripts, CI, or piped environments will hang indefinitely. Use Herdr split/tab/window modes instead, or run `agy` interactively.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Playbook 07: Legacy Code Modernization & Transformation
|
|
2
|
+
|
|
3
|
+
> **For Desktop & Web AI**: Use this playbook whenever undertaking legacy codebase upgrades, runtime migrations, dependency modernizations, or monolithic subsystem refactoring.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Overview & Core Philosophy
|
|
8
|
+
Modernizing legacy software using AI coding agents carries a significant risk: models frequently discard critical, undocumented business logic because it looks messy or idiomatic to older language versions.
|
|
9
|
+
|
|
10
|
+
This playbook enforces Anthropic's **Code Modernization Playbook** framework: transformations must proceed through disciplined **Characterization Testing (Golden Master)** and **Vertical Slice Migrations**, guaranteeing zero behavioral regressions.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 2. The 4-Phase Modernization Workflow
|
|
15
|
+
|
|
16
|
+
```mermaid
|
|
17
|
+
flowchart LR
|
|
18
|
+
P1["Phase 1: Discovery & Boundary Mapping"] --> P2["Phase 2: Golden Master Characterization"]
|
|
19
|
+
P2 --> P3["Phase 3: Vertical Slice Migration"]
|
|
20
|
+
P3 --> P4["Phase 4: Dual-Run Parity & Cutover"]
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
### Phase 1: Discovery & Boundary Mapping
|
|
24
|
+
1. **Identify the Seam**: Locate where the legacy subsystem interacts with the rest of the application (API contracts, DB tables, file I/O, exported functions).
|
|
25
|
+
2. **Blast-Radius Assessment**:
|
|
26
|
+
- Classify downstream consumers into Tier 1 (internal non-critical), Tier 2 (user-facing views), or Tier 3 (database mutations, auth, financial transactions).
|
|
27
|
+
3. **Document Invariants**: Record all expected input formats, edge cases, and known quirks in `docs/modernization/<subsystem>-invariants.md`.
|
|
28
|
+
|
|
29
|
+
### Phase 2: Golden Master (Characterization) Test Baseline
|
|
30
|
+
> [!CRITICAL]
|
|
31
|
+
> **Zero-Mutation Rule**: Do NOT touch, clean up, or refactor legacy code during this phase.
|
|
32
|
+
|
|
33
|
+
1. **Write Characterization Tests**:
|
|
34
|
+
- Capture real-world inputs and record outputs from the *existing* legacy implementation.
|
|
35
|
+
- Include: valid payloads, malformed inputs, boundary values (null, empty, negative, maximum length), and error conditions.
|
|
36
|
+
2. **Lock the Baseline**:
|
|
37
|
+
- Run the tests against the untouched legacy code.
|
|
38
|
+
- Every characterization test must pass (100% baseline).
|
|
39
|
+
3. **Commit Baseline**:
|
|
40
|
+
- Commit the characterization suite to git before proceeding to Phase 3.
|
|
41
|
+
|
|
42
|
+
### Phase 3: Incremental Vertical Slice Migration (Strangler Fig)
|
|
43
|
+
1. **Define the Modern Interface**: Author clean TypeScript/Node.js or target language interfaces representing the modernized seam.
|
|
44
|
+
2. **Implement Behind an Adapter**:
|
|
45
|
+
- Create a routing adapter that can switch between the legacy implementation and the modernized implementation via an environment variable or feature flag:
|
|
46
|
+
```typescript
|
|
47
|
+
export async function processTransaction(data: TransactionInput): Promise<TransactionResult> {
|
|
48
|
+
if (process.env.USE_MODERN_TRANSACTIONS === "true") {
|
|
49
|
+
return modernProcessor.execute(data);
|
|
50
|
+
}
|
|
51
|
+
return legacyProcessor.execute(data);
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
3. **Surgical Implementation**: Write the modernized implementation adhering strictly to Karpathy simplicity and native platform features.
|
|
55
|
+
|
|
56
|
+
### Phase 4: Dual-Run Parity & Cutover
|
|
57
|
+
1. **Dual-Run Verification**:
|
|
58
|
+
- Run the Golden Master test suite with the feature toggle enabled.
|
|
59
|
+
- Verify that all outputs match the legacy outputs bit-for-bit (or within explicitly documented architectural updates).
|
|
60
|
+
2. **Peer Adversarial Review**:
|
|
61
|
+
- Dispatch the diff to the Reviewer (via `herdr agent prompt <reviewer-agent> "Review diff..." --wait` or child subagent review).
|
|
62
|
+
3. **Decommissioning**:
|
|
63
|
+
- Remove the feature toggle and safely delete the legacy code branch.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## 3. Mandatory Modernization Guardrails
|
|
68
|
+
|
|
69
|
+
1. **Ban Big-Bang Rewrites**:
|
|
70
|
+
- Any refactoring plan proposing to replace more than 500 lines of legacy code in a single pull request without incremental seams must be rejected.
|
|
71
|
+
2. **Preserve Business Quirks**:
|
|
72
|
+
- Never "fix" undocumented behavioral quirks during a modernization pass unless the user explicitly commands the behavioral change.
|
|
73
|
+
3. **Automated Rollback Readiness**:
|
|
74
|
+
- Every modernized vertical slice must have an immediate, zero-downtime rollback mechanism (feature toggle or reversible commit) until production stability is established.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Playbook 08: Backlog Governance, Change Request (CR) Analysis & Execution Flows
|
|
2
|
+
|
|
3
|
+
> **For Desktop & Web AI**: Use this operational protocol to govern issue intake, feature backlogs, Change Request (CR) reviews, and implementation lifecycles.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Governance Overview
|
|
8
|
+
|
|
9
|
+
Heimdall distinguishes between **fast-path bugfixes** and **evaluated feature requests** to maintain stability while preventing architectural drift:
|
|
10
|
+
|
|
11
|
+
```mermaid
|
|
12
|
+
flowchart TD
|
|
13
|
+
A["Incoming Engineering Request"] --> B{"Classify Intake"}
|
|
14
|
+
|
|
15
|
+
%% Flow 1: Bugfixes
|
|
16
|
+
B -->|Bug / Defect| C["Flow 1: Bugfix Fast-Path"]
|
|
17
|
+
C --> C1["1. Receive Report & Triage"]
|
|
18
|
+
C1 --> C2["2. Assess Root Cause & Plan Fix"]
|
|
19
|
+
C2 --> C3["3. Implement with Failing Test First (TDD)"]
|
|
20
|
+
C3 --> C4["4. Run Verification (Automated + Playwright if UI)"]
|
|
21
|
+
C4 --> C5["5. Completed & Merged"]
|
|
22
|
+
|
|
23
|
+
%% Flow 2 & 3: Features & Backlog
|
|
24
|
+
B -->|New Feature / Idea| D["Flow 2: Backlog Intake"]
|
|
25
|
+
D --> D1["Log into docs/backlog.md with context & priority"]
|
|
26
|
+
D1 --> E["Flow 3: Change Request (CR) Analysis"]
|
|
27
|
+
E --> E1["CR Assessment (Blast Radius, Architecture, Scope)"]
|
|
28
|
+
E1 --> E2{"Human Decision Gate"}
|
|
29
|
+
|
|
30
|
+
%% Approved Path
|
|
31
|
+
E2 -->|Approved| F["Flow 3a: Execution Cycle"]
|
|
32
|
+
F --> F1["Author Plan: docs/designs/YYYY-MM-DD <name>.md"]
|
|
33
|
+
F1 --> F2["Implementation & Testing"]
|
|
34
|
+
F2 --> F3["Archive Plan to docs/designs/old/"]
|
|
35
|
+
F3 --> F4["Mark Backlog Item as [Completed]"]
|
|
36
|
+
|
|
37
|
+
%% Rejection Path
|
|
38
|
+
E2 -->|Not Approved| G["Flow 4: Rejection Handling"]
|
|
39
|
+
G --> G1["Return to Backlog with Rebuttal/Notes OR Delete if Discarded"]
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 2. The Four Distinct Lifecycle Flows
|
|
45
|
+
|
|
46
|
+
### Flow 1: Bugfixes (Fast-Path Loop)
|
|
47
|
+
* **Trigger**: Bug report, runtime error, broken assertion, or security defect.
|
|
48
|
+
* **Protocol**:
|
|
49
|
+
1. **Receive Report**: Extract steps to reproduce, affected files, error logs, and expected behavior.
|
|
50
|
+
2. **Assess & Plan Fix**: Identify root cause; for <50 LOC (Tier 1), plan surgically in-chat; for complex defects, author a brief plan.
|
|
51
|
+
3. **Implement via TDD**: Write a failing regression test proving the bug exists; implement minimal surgical code until the test passes.
|
|
52
|
+
4. **Verify**: Run full test suite (`pnpm test` / `pytest`) and Playwright E2E if user interface is touched.
|
|
53
|
+
5. **Complete**: Mark resolved, record fix in commit message.
|
|
54
|
+
|
|
55
|
+
### Flow 2: New Features (Backlog Intake)
|
|
56
|
+
* **Trigger**: New requirement, enhancement proposal, or architectural improvement.
|
|
57
|
+
* **Protocol**:
|
|
58
|
+
1. **Do not immediately implement.**
|
|
59
|
+
2. Log the item into [`docs/backlog.md`](file:///C:/Apps/heimdall-agent/docs/backlog.md) under `## Active Backlog`.
|
|
60
|
+
3. Capture:
|
|
61
|
+
- **ID**: `FEAT-XXX` or `CR-XXX`
|
|
62
|
+
- **Title**: Descriptive name
|
|
63
|
+
- **Motivation & Details**: Context, target users, business justification
|
|
64
|
+
- **Impact & Estimated Scope**: Tier 1, 2, or 3
|
|
65
|
+
- **Status**: `Backlog` (or `Under Analysis`)
|
|
66
|
+
|
|
67
|
+
### Flow 3: Change Request (CR) Analysis & Implementation
|
|
68
|
+
* **Trigger**: User requests evaluation of a specific backlog item (or a batch sweep of the backlog).
|
|
69
|
+
* **Protocol**:
|
|
70
|
+
1. **CR Analysis Phase**:
|
|
71
|
+
- Evaluate technical feasibility, architectural fit, dependency footprint, and blast radius.
|
|
72
|
+
- Review backward compatibility and potential regressions.
|
|
73
|
+
- Present findings clearly:
|
|
74
|
+
- Scope classification (Tier 1, 2, or 3)
|
|
75
|
+
- Architectural impact & trade-offs
|
|
76
|
+
- Effort estimation & model allocation recommendation
|
|
77
|
+
2. **Human Approval Gate**:
|
|
78
|
+
- STOP and wait for explicit user sign-off to proceed.
|
|
79
|
+
3. **Implementation Cycle (Upon Approval)**:
|
|
80
|
+
- **Step A**: Author a formal 7-section plan in:
|
|
81
|
+
`docs/designs/YYYY-MM-DD <feature-name>.md`
|
|
82
|
+
- **Step B**: Execute plan task-by-task following TDD and anti-slop guidelines.
|
|
83
|
+
- **Step C**: Verify thoroughly with automated tests and Playwright E2E.
|
|
84
|
+
- **Step D**: Archive the plan:
|
|
85
|
+
Move `docs/designs/YYYY-MM-DD <feature-name>.md` to `docs/designs/old/YYYY-MM-DD <feature-name>.md`.
|
|
86
|
+
- **Step E**: Update [`docs/backlog.md`](file:///C:/Apps/heimdall-agent/docs/backlog.md), moving item to `## Completed`.
|
|
87
|
+
|
|
88
|
+
### Flow 4: Rejection & Postponement
|
|
89
|
+
* **Trigger**: CR Analysis concludes the feature is out of scope, premature, high risk, or user rejects proposal.
|
|
90
|
+
* **Protocol**:
|
|
91
|
+
- **Option 4A (Postpone / Defer)**: Move the item back to `## Active Backlog` or `## Icebox`, appending the rejection rationale, unanswered questions, or blockers.
|
|
92
|
+
- **Option 4B (Delete / Discard)**: If permanently discarded, record in `## Discarded / Rejected` with reason (or delete from the document if instructed by user).
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 3. Backlog Document Schema (`docs/backlog.md`)
|
|
97
|
+
|
|
98
|
+
All projects governed by Heimdall must maintain [`docs/backlog.md`](file:///C:/Apps/heimdall-agent/docs/backlog.md) adhering to this authoritative structure:
|
|
99
|
+
|
|
100
|
+
```markdown
|
|
101
|
+
# Product & Engineering Backlog
|
|
102
|
+
|
|
103
|
+
## 1. Under Analysis / Change Requests (In-Flight Evaluation)
|
|
104
|
+
| ID | Title | Priority | Scope Tier | CR Status | Analysis Notes / Design Link |
|
|
105
|
+
| :--- | :--- | :--- | :--- | :--- | :--- |
|
|
106
|
+
|
|
107
|
+
## 2. Active Backlog (Prioritized Features)
|
|
108
|
+
| ID | Title | Priority (P0-P3) | Type (Feature/Enchancement) | Description & Value | Target Milestone |
|
|
109
|
+
| :--- | :--- | :--- | :--- | :--- | :--- |
|
|
110
|
+
|
|
111
|
+
## 3. Icebox / Deferred
|
|
112
|
+
| ID | Title | Date Added | Deferral Reason / Unresolved Questions |
|
|
113
|
+
| :--- | :--- | :--- | :--- |
|
|
114
|
+
|
|
115
|
+
## 4. Completed
|
|
116
|
+
| ID | Title | Completed Date | Plan Reference (docs/designs/old/) | Verified By |
|
|
117
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
118
|
+
|
|
119
|
+
## 5. Discarded / Rejected
|
|
120
|
+
| ID | Title | Decision Date | Rejection Rationale |
|
|
121
|
+
| :--- | :--- | :--- | :--- |
|
|
122
|
+
```
|