@harness-forge/cli 0.1.0

package/templates/instructions/root-agents-template.md

@@ -0,0 +1,88 @@
+---
+id: root-agents-template
+kind: task-template
+title: Root Agents Guidance
+summary: Draft one repo-root guidance surface when the repository does not justify extra scoped instruction files.
+status: stable
+version: 1
+supported_targets:
+  - codex
+  - claude-code
+supported_languages:
+  - any
+owner: core
+generated: false
+---
+
+## Purpose
+
+Capture the minimum repo-wide guidance required to make the root instruction
+surface useful without creating avoidable instruction sprawl.
+
+## When to Use
+
+Use when a repository can be served primarily by one root guidance file such as
+`AGENTS.md` that points back to the hidden `.hforge/` AI layer and the shared
+`.hforge/runtime/` intelligence runtime.
+
+## Inputs
+
+- repo map or equivalent repository evidence
+- chosen target harness
+- shared runtime index or equivalent runtime summary
+- hidden canonical AI-layer paths under `.hforge/library/` and `.hforge/templates/`
+- existing root guidance files, if any
+
+## Optional Inputs
+
+- benchmark expectations
+- recommended profiles or skills
+- known high-risk paths
+
+## Constraints
+
+- keep scope at the repository root unless evidence justifies more
+- avoid repeating guidance that already exists elsewhere
+- preserve target-support honesty when describing runtime behavior
+
+## Expected Outputs
+
+- one root guidance recommendation or draft
+- explicit pointer back to `.hforge/runtime/index.json` plus the hidden canonical `.hforge/library/` surfaces
+- explicit risk notes for any degraded target capability
+- evidence showing why root-only guidance is sufficient
+
+## Acceptance Criteria
+
+- the root surface has a clear purpose and target
+- evidence is cited for major guidance choices
+- no extra scoped guidance is proposed without justification
+
+## Quality Gates
+
+- support claims align with `manifests/catalog/harness-capability-matrix.json`
+- repo-map evidence is traceable
+- generated output is reviewable before any write
+
+## Suggested Workflow
+
+1. Inspect the repo map and existing instruction surfaces.
+2. Draft one root guidance surface that routes back to the hidden AI layer instead of duplicating canonical content at the repo root.
+3. Call out risk areas and validation commands.
+4. Stop if scoped guidance is not clearly justified.
+
+## Related Commands
+
+- `node scripts/intelligence/cartograph-repo.mjs <repo> --json`
+- `node scripts/intelligence/synthesize-instructions.mjs <repo> --dry-run --json`
+
+## Related Agents
+
+- `skills/repo-cartographer/SKILL.md`
+- `skills/repo-onboarding/SKILL.md`
+
+## Examples
+
+- add one repo-root `AGENTS.md` recommendation for a single-service app
+- keep a small library on root-only guidance because no stable sub-boundaries
+  need separate rules

package/templates/instructions/scoped-agents-template.md

@@ -0,0 +1,90 @@
+---
+id: scoped-agents-template
+kind: task-template
+title: Scoped Agents Guidance
+summary: Draft a justified scoped guidance surface when root-only instructions would be too coarse.
+status: stable
+version: 1
+supported_targets:
+  - codex
+  - claude-code
+supported_languages:
+  - any
+owner: core
+generated: false
+---
+
+## Purpose
+
+Capture narrow, evidence-backed scoped guidance for one boundary that the root
+guidance surface cannot cover well on its own.
+
+## When to Use
+
+Use when the repo map identifies a stable service, app, or subsystem that needs
+local constraints beyond the repo root while still inheriting the shared
+`.hforge/runtime/` intelligence layer and the hidden canonical `.hforge/`
+knowledge surfaces.
+
+## Inputs
+
+- repo map with service boundaries
+- chosen target harness
+- shared runtime index or equivalent runtime summary
+- hidden canonical AI-layer paths under `.hforge/library/` and `.hforge/templates/`
+- existing root guidance surface
+
+## Optional Inputs
+
+- benchmark expectations
+- quality gaps for the scoped boundary
+- high-risk paths inside the scope
+
+## Constraints
+
+- explain why root-only guidance is insufficient
+- keep the scope boundary explicit and narrow
+- do not duplicate repo-wide guidance without need
+
+## Expected Outputs
+
+- one scoped guidance recommendation or draft
+- one scoped bridge that still points back to the shared runtime and hidden canonical AI layer
+- evidence for the boundary choice
+- risk notes for any target-specific limitations
+
+## Acceptance Criteria
+
+- the scoped path is stable and justified
+- the local guidance adds value beyond the root surface
+- the recommendation remains reviewable before write
+
+## Quality Gates
+
+- scope choice is backed by repo-map evidence
+- guidance does not overstate target-native support
+- overlap with the root surface is minimized
+
+## Suggested Workflow
+
+1. Confirm the boundary from cartography output.
+2. State why the root surface is not enough.
+3. Draft only the local constraints that differ materially while preserving the shared runtime pointer and hidden-layer authority.
+4. Keep the write mode conservative unless explicitly approved.
+
+## Related Commands
+
+- `node scripts/intelligence/classify-boundaries.mjs <repo> --json`
+- `node scripts/intelligence/synthesize-instructions.mjs <repo> --dry-run --json`
+
+## Related Agents
+
+- `skills/repo-cartographer/SKILL.md`
+- `skills/architecture-decision-records/SKILL.md`
+
+## Examples
+
+- recommend `apps/web/AGENTS.md` for a monorepo where frontend review rules
+  differ from backend services
+- recommend a scoped rule for a migration-heavy service with stricter local
+  safety notes

package/templates/tasks/fix-bug.md

@@ -0,0 +1,93 @@
+---
+id: fix-bug
+kind: task-template
+title: Fix Bug
+summary: Fix a reproducible defect with regression coverage and concise root-cause notes.
+category: quality
+status: stable
+version: 1
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+languages:
+  - any
+supported_targets:
+  - codex
+  - claude-code
+  - cursor
+supported_languages:
+  - any
+recommended_agents:
+  - planner
+recommended_commands:
+  - test
+owner: core
+generated: false
+---
+
+## Purpose
+
+Fix a known defect with reproducible verification and minimal regression risk.
+
+## When to Use
+
+Use when a user-facing, developer-facing, or installer-facing bug has been
+identified and needs a verified fix.
+
+## Inputs
+
+- bug description
+- reproduction steps
+- affected files or modules
+
+## Optional Inputs
+
+- logs
+- screenshots
+- prior fixes
+
+## Constraints
+
+- reproduce before patching
+- document the failing scenario
+- avoid unrelated refactors
+
+## Expected Outputs
+
+- bug fix
+- regression test or validator coverage
+- concise root-cause summary
+
+## Acceptance Criteria
+
+- bug can be reproduced before the change
+- bug no longer reproduces after the change
+- related behavior still works
+
+## Quality Gates
+
+- failing test or reproducible check exists before implementation
+- post-fix validation passes
+
+## Validation Tools
+
+- `scripts/templates/shell/check-template-frontmatter.sh`
+- `scripts/templates/powershell/Check-TemplateFrontmatter.ps1`
+- `scripts/templates/config/required-sections.json`
+
+## Suggested Workflow
+
+Use `triage-reproduce-fix-verify`.
+
+## Related Commands
+
+- `test`
+
+## Related Agents
+
+- `planner`
+
+## Examples
+
+- fix a target mapping collision during installation

package/templates/tasks/implement-feature.md

@@ -0,0 +1,95 @@
+---
+id: implement-feature
+kind: task-template
+title: Implement Feature
+summary: Deliver a new feature with explicit verification, updated docs, and clear artifact boundaries.
+category: delivery
+status: stable
+version: 1
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+languages:
+  - any
+supported_targets:
+  - codex
+  - claude-code
+  - cursor
+supported_languages:
+  - any
+recommended_agents:
+  - planner
+recommended_commands:
+  - plan
+  - test
+owner: core
+generated: false
+---
+
+## Purpose
+
+Deliver a new feature in a way that preserves user value, verification, and
+clear artifact boundaries.
+
+## When to Use
+
+Use this template when adding a new feature or major capability.
+
+## Inputs
+
+- approved spec or task brief
+- implementation plan
+- affected files or modules
+
+## Optional Inputs
+
+- architecture notes
+- prior incident or bug history
+- migration expectations
+
+## Constraints
+
+- keep changes scoped to the approved feature
+- define verification before implementation
+- update docs when behavior changes
+
+## Expected Outputs
+
+- implementation summary
+- changed files
+- validation results
+
+## Acceptance Criteria
+
+- feature behavior matches the approved spec
+- validations pass or blockers are documented
+- affected docs and guidance are updated
+
+## Quality Gates
+
+- tests fail before implementation and pass after changes
+- no unresolved critical validation findings remain
+
+## Validation Tools
+
+- `scripts/templates/shell/check-template-frontmatter.sh`
+- `scripts/templates/powershell/Check-TemplateFrontmatter.ps1`
+- `scripts/templates/config/required-sections.json`
+
+## Suggested Workflow
+
+Use `research-plan-implement-validate`.
+
+## Related Commands
+
+- `plan`
+- `test`
+
+## Related Agents
+
+- `planner`
+
+## Examples
+
+- implement target-aware install guidance for a new assistant environment

package/templates/workflows/implement-cpp-change.md

@@ -0,0 +1,175 @@
+---
+id: implement-cpp-change
+kind: workflow-template
+title: Implement C++ Change
+summary: Deliver C++ work using the promoted common guidance, language rules, and structured language pack.
+mode: sequential
+status: stable
+version: 1
+applies_to:
+  - codex
+  - claude-code
+languages:
+  - cpp
+supported_targets:
+  - codex
+  - claude-code
+supported_languages:
+  - cpp
+default_agents:
+  - planner
+owner: core
+generated: false
+---
+
+## Purpose
+
+Deliver a C++ change with explicit use of the promoted rules, structured references, and validation steps.
+
+## When to Use
+
+Use when the dominant task language is C++ or when the touched files match the shipped cpp pack.
+
+## Entry Conditions
+
+- the affected files are known
+- the dominant language is C++
+- `rules/common/` and the matching language rule directory are available
+
+## Workflow Stages
+
+### Stage 1: Orient
+
+**Goal**
+Load the common guidance and the C++-specific references relevant to the task.
+
+**Consumes**
+- `rules/common/`
+- `skills/cpp-engineering/SKILL.md`
+- `knowledge-bases/structured/cpp/docs/overview.md`
+
+**Produces**
+- selected rule set
+- implementation constraints
+
+**Exit Criteria**
+- the applicable guidance is identified
+- the validation path is known
+
+**Failure Conditions**
+- the task language is mismatched
+- the structured references are unavailable
+
+**Next Trigger**
+Move to design once the active rules and examples are pinned down.
+
+### Stage 2: Design
+
+**Goal**
+Map the change to modules, boundaries, validation, and tests.
+
+**Consumes**
+- `rules/common/`
+- `rules/cpp/`
+- `knowledge-bases/structured/cpp/examples/01-reference-scenario.md`
+
+**Produces**
+- file touch list
+- verification approach
+
+**Exit Criteria**
+- file-level intent is explicit
+- the test or review path is clear
+
+**Failure Conditions**
+- dependencies or boundaries remain ambiguous
+- no workable validation path exists
+
+**Next Trigger**
+Move to implementation when the change is concrete enough to execute safely.
+
+### Stage 3: Implement
+
+**Goal**
+Apply the change following the promoted guidance.
+
+**Consumes**
+- selected design
+- `rules/common/security.md`
+- `rules/cpp/security.md`
+
+**Produces**
+- code or script changes
+- updated docs if behavior changes
+
+**Exit Criteria**
+- the implementation matches the intended design
+- obvious safety checks are addressed
+
+**Failure Conditions**
+- the implementation diverges from the selected pattern
+- a blocking compile or runtime issue appears without a safe fix
+
+**Next Trigger**
+Move to verification after the implementation compiles or is otherwise ready to validate.
+
+### Stage 4: Verify
+
+**Goal**
+Validate behavior against the structured review and testing guidance.
+
+**Consumes**
+- `knowledge-bases/structured/cpp/docs/review-checklist.md`
+- `rules/cpp/testing.md`
+- repo-specific build or test commands
+
+**Produces**
+- validation results
+- release notes or follow-up tasks if needed
+
+**Exit Criteria**
+- the intended behavior is verified
+- outstanding follow-ups are captured clearly
+
+**Failure Conditions**
+- tests fail without a safe remediation path
+- the change introduces a release-blocking regression
+
+**Next Trigger**
+End the workflow or hand off follow-up tasks.
+
+## Handoff Contracts
+
+- record which `rules/common/` and `rules/cpp/` files were applied
+- note the commands or manual checks used to validate the change
+
+## Exit Conditions
+
+- the implementation aligns with the promoted C++ rules and structured references
+- verification results or blockers are captured clearly
+
+## Failure Modes
+
+- changing ownership or ABI-sensitive surfaces without checking the C++ rules first
+- finishing without running or documenting the repo's verification path
+
+## Escalation Rules
+
+- escalate when the task touches threading, memory ownership, or platform-specific code
+- escalate when interface compatibility risks remain unresolved
+
+## Artifacts Produced
+
+- changed source files
+- validation output
+- implementation summary
+
+## Human Approval Points
+
+- approve ABI or public-header changes
+- approve deviations from the promoted modern C++ guidance
+
+## Examples
+
+- update a library header and implementation pair with focused verification
+- refactor a C++ module using the structured reference scenario

package/templates/workflows/implement-dotnet-change.md

@@ -0,0 +1,175 @@
+---
+id: implement-dotnet-change
+kind: workflow-template
+title: Implement .NET Change
+summary: Deliver .NET work using the seeded .NET rules, examples, and review guidance.
+mode: sequential
+status: stable
+version: 1
+applies_to:
+  - codex
+  - claude-code
+languages:
+  - dotnet
+supported_targets:
+  - codex
+  - claude-code
+supported_languages:
+  - dotnet
+default_agents:
+  - planner
+owner: core
+generated: false
+---
+
+## Purpose
+
+Deliver .NET work with explicit use of the promoted rules and seeded examples.
+
+## When to Use
+
+Use when a task touches C#, ASP.NET Core, workers, libraries, or .NET CLI code.
+
+## Entry Conditions
+
+- the affected files are known
+- the dominant language is .NET or C#
+- `rules/common/` and `rules/dotnet/` are available
+
+## Workflow Stages
+
+### Stage 1: Orient
+
+**Goal**
+Load the .NET rules and seeded references relevant to the task.
+
+**Consumes**
+- `rules/common/coding-style.md`
+- `rules/dotnet/coding-style.md`
+- `knowledge-bases/seeded/dotnet/docs/overview.md`
+
+**Produces**
+- selected rule set
+- implementation constraints
+
+**Exit Criteria**
+- required .NET constraints are identified
+- an example path is chosen if one is relevant
+
+**Failure Conditions**
+- the task language is mismatched
+- the seeded references are unavailable
+
+**Next Trigger**
+Move to design once the applicable rules are pinned down.
+
+### Stage 2: Design
+
+**Goal**
+Map the change to services, workers, contracts, and tests.
+
+**Consumes**
+- `rules/common/patterns.md`
+- `rules/dotnet/patterns.md`
+- `knowledge-bases/seeded/dotnet/examples/`
+
+**Produces**
+- file touch list
+- verification approach
+
+**Exit Criteria**
+- dependency direction is explicit
+- verification strategy is clear
+
+**Failure Conditions**
+- structure remains ambiguous
+- test strategy is missing
+
+**Next Trigger**
+Move to implementation when file-level changes are concrete.
+
+### Stage 3: Implement
+
+**Goal**
+Apply the change following the promoted .NET and common rules.
+
+**Consumes**
+- selected design
+- `rules/common/security.md`
+- `rules/dotnet/security.md`
+
+**Produces**
+- code changes
+- updated docs if behavior changes
+
+**Exit Criteria**
+- implementation follows the planned structure
+- security and validation concerns are addressed
+
+**Failure Conditions**
+- layering or runtime compatibility regresses
+- validation is incomplete
+
+**Next Trigger**
+Move to verification after implementation is complete.
+
+### Stage 4: Verify
+
+**Goal**
+Check behavior against the seeded review and testing guidance.
+
+**Consumes**
+- `rules/common/testing.md`
+- `rules/dotnet/testing.md`
+- `knowledge-bases/seeded/dotnet/docs/review-checklist.md`
+
+**Produces**
+- test results
+- final review notes
+
+**Exit Criteria**
+- validations are run or blockers are documented
+- the review checklist is satisfied
+
+**Failure Conditions**
+- tests fail without a safe fix
+- critical review issues remain
+
+**Next Trigger**
+Complete the workflow when verification is documented.
+
+## Handoff Contracts
+
+- record which rule files shaped the implementation
+- list the validation commands that were run
+
+## Exit Conditions
+
+- code aligns with `rules/common/` and `rules/dotnet/`
+- relevant seeded examples or review notes were consulted
+
+## Failure Modes
+
+- bypassing the promoted .NET rules
+- shipping service or worker changes without seeded review coverage
+
+## Escalation Rules
+
+- escalate when runtime or framework constraints conflict with the promoted guidance
+- escalate when the seeded examples do not cover the required architecture
+
+## Artifacts Produced
+
+- changed source files
+- validation output
+- implementation summary
+
+## Human Approval Points
+
+- approve any major runtime or hosting model change
+- approve any deviation from the seeded .NET guidance
+
+## Examples
+
+- add an ASP.NET Core endpoint using the seeded CRUD API example
+- implement a background worker change using the queue-processing example