diff --git a/CATALOG.md b/CATALOG.md index 5d6cade..e9b4bef 100644 --- a/CATALOG.md +++ b/CATALOG.md @@ -103,12 +103,11 @@ | `discover-tests-for-changes` | test-engineer | triage-report | Analyze local code changes to identify affected components and discover relevant tests. Finds test files near changed code, checks test configuration, and recommends execution strategy. | | `scaffold-test-project` | test-engineer | implementation-plan | Scaffold a complete test project with build configuration, test class boilerplate, and test runner setup for a given framework and language. | -### planning (2) +### planning (1) | Template | Persona | Format | Description | |----------|---------|--------|-------------| -| `plan-implementation` | software-architect | implementation-plan | Decompose a project into an actionable implementation plan with tasks, dependencies, and risk assessment. | -| `plan-refactoring` | software-architect | implementation-plan | Plan a safe, incremental refactoring with step-by-step changes that maintain correctness at each step. | +| `plan-implementation` | software-architect | implementation-plan | Decompose a project into an actionable implementation plan with tasks, dependencies, and risk assessment. Supports `mode=refactoring` for safe, incremental refactoring plans. | ### agent-authoring (1) @@ -164,8 +163,8 @@ | Protocol | Language | Used by | Description | |----------|----------|---------|-------------| -| `anti-hallucination` | — | `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `plan-refactoring`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` | Prevents fabrication. Enforces epistemic labeling (KNOWN/INFERRED/ASSUMED), uncertainty disclosure, and source attribution. Apply to all tasks. | -| `self-verification` | — | `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `plan-refactoring`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` | Quality gate requiring the LLM to verify its own output before finalizing. Sampling checks, citation audits, coverage confirmation, consistency checks. | +| `anti-hallucination` | — | `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` | Prevents fabrication. Enforces epistemic labeling (KNOWN/INFERRED/ASSUMED), uncertainty disclosure, and source attribution. Apply to all tasks. | +| `self-verification` | — | `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` | Quality gate requiring the LLM to verify its own output before finalizing. Sampling checks, citation audits, coverage confirmation, consistency checks. | | `operational-constraints` | — | `reverse-engineer-requirements`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `author-presentation`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `review-code`, `review-cpp-code`, `reconstruct-behavior`, `discover-tests-for-changes`, `audit-library-health`, `engineering-workflow`, `generate-implementation-changes`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` | Governs how the LLM scopes work, uses tools, manages context, and prefers deterministic analysis. Prevents over-ingestion and ensures reproducibility. | | `minimal-edit-discipline` | — | `find-and-fix-bugs`, `fix-compiler-warnings` | Constrains code modifications to be minimal, type-preserving, encoding-safe, and verifiable. Prevents collateral damage from automated fixes, refactoring, and code generation. | | `adversarial-falsification` | — | `exhaustive-bug-hunt`, `engineering-workflow`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` | Enforces adversarial self-falsification discipline. Requires the reviewer to disprove every candidate finding before reporting it, reject known-safe patterns, and resist premature summarization. | @@ -237,7 +236,7 @@ |---------|---------|-------------| | `systems-engineer` | `author-validation-plan`, `author-interface-contract`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt` | Senior systems engineer. Deep expertise in memory management, concurrency, performance, and debugging. Reasons from first principles. | | `security-auditor` | `investigate-security` | Principal security engineer. Adversarial mindset. Specializes in vulnerability discovery, threat modeling, and secure design. | -| `software-architect` | `author-requirements-doc`, `author-architecture-spec`, `author-north-star`, `author-design-doc`, `plan-implementation`, `plan-refactoring`, `generate-commit-message` | Staff software architect. System design, API contracts, tradeoff analysis, and long-term maintainability. | +| `software-architect` | `author-requirements-doc`, `author-architecture-spec`, `author-north-star`, `author-design-doc`, `plan-implementation`, `generate-commit-message` | Staff software architect. System design, API contracts, tradeoff analysis, and long-term maintainability. | | `promptkit-contributor` | `author-agent-instructions`, `extend-library`, `decompose-prompt` | PromptKit contribution guide. Understands the library's architecture, conventions, and quality standards. Guides contributors through designing and building new components. | | `devops-engineer` | `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure` | Senior DevOps / platform engineer. Deep expertise in CI/CD pipelines, release engineering, infrastructure-as-code, and platform APIs across GitHub Actions, Azure DevOps, GitLab CI, and other DevOps platforms. | | `reverse-engineer` | `reverse-engineer-requirements`, `reconstruct-behavior` | Senior reverse engineer. Extracts specifications, contracts, and behavioral requirements from existing implementations. Separates essential behavior from implementation details. | @@ -267,7 +266,7 @@ | `agent-instructions` | agent-instruction-file | — | `author-agent-instructions` | Output format for persistent agent instruction files, custom agent definitions, and CLI skills. Produces .github/instructions/, .github/agents/, .github/skills/, CLAUDE.md, and .cursorrules. Works with VS Code, JetBrains, GitHub.com, and the Copilot CLI. | | `copilot-prompt-file` | copilot-prompt-file | — | — | Output format for GitHub Copilot prompt files (.github/prompts/*.prompt.md). Packages an assembled PromptKit prompt as a reusable slash command invokable in Copilot Chat. Full semantic fidelity — no content condensation. | | `agentic-workflow` | agentic-workflow | — | — | Output format for GitHub Agentic Workflow files (.github/workflows/*.md). Packages an assembled PromptKit prompt as a scheduled or event-driven automation running in GitHub Actions with a coding agent. Requires `gh aw` CLI for compilation. | -| `implementation-plan` | implementation-plan | — | `scaffold-test-project`, `plan-implementation`, `plan-refactoring` | Output format for implementation and refactoring plans. Task breakdown, dependency ordering, risk assessment, and verification strategy. | +| `implementation-plan` | implementation-plan | — | `scaffold-test-project`, `plan-implementation` | Output format for implementation and refactoring plans. Task breakdown, dependency ordering, risk assessment, and verification strategy. | | `north-star-document` | north-star-document | — | `author-north-star` | Strategic north-star or architectural vision document. Describes the desired end state, guiding principles, and transition considerations — not the implementation plan. | | `structured-findings` | structured-findings | — | `fix-compiler-warnings`, `classify-findings` | Output format for structured findings documents. Transforms raw diagnostic output (compiler warnings, linter results, security scans) into consolidated, classified findings with root cause analysis, severity assessment, and remediation guidance. | | `exhaustive-review-report` | exhaustive-review-report | — | `exhaustive-bug-hunt` | Exhaustive code review report with per-file coverage ledgers, adversarial finding templates requiring falsification proof, and false-positive rejection logs. | @@ -346,7 +345,7 @@ Domain-agnostic incremental engineering workflow with human-in-the-loop review. ### Which templates use a given protocol? - **`adversarial-falsification`** → `exhaustive-bug-hunt`, `engineering-workflow`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` -- **`anti-hallucination`** → `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `plan-refactoring`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` +- **`anti-hallucination`** → `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` - **`bom-consistency`** → `review-bom` - **`change-propagation`** → `engineering-workflow`, `generate-spec-changes`, `generate-implementation-changes`, `maintenance-workflow` - **`code-compliance-audit`** → `audit-code-compliance`, `engineering-workflow`, `audit-implementation-alignment`, `maintenance-workflow` @@ -389,7 +388,7 @@ Domain-agnostic incremental engineering workflow with human-in-the-loop review. - **`schematic-compliance-audit`** → `review-schematic`, `design-schematic`, `hardware-design-workflow` - **`schematic-design`** → `design-schematic`, `hardware-design-workflow` - **`security-vulnerability`** → `investigate-security`, `review-infrastructure` -- **`self-verification`** → `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `plan-refactoring`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` +- **`self-verification`** → `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` - **`session-profiling`** → `profile-session` - **`simulation-validation`** → `validate-simulation` - **`spec-evolution-diff`** → `diff-specifications` @@ -414,7 +413,7 @@ Domain-agnostic incremental engineering workflow with human-in-the-loop review. - **`reverse-engineer`** → `reverse-engineer-requirements`, `reconstruct-behavior` - **`rf-engineer`** → `audit-link-budget` - **`security-auditor`** → `investigate-security` -- **`software-architect`** → `author-requirements-doc`, `author-architecture-spec`, `author-north-star`, `author-design-doc`, `plan-implementation`, `plan-refactoring`, `generate-commit-message` +- **`software-architect`** → `author-requirements-doc`, `author-architecture-spec`, `author-north-star`, `author-design-doc`, `plan-implementation`, `generate-commit-message` - **`specification-analyst`** → `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `diff-specifications`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `profile-session`, `audit-library-consistency`, `audit-library-health`, `audit-spec-alignment`, `audit-implementation-alignment` - **`systems-engineer`** → `author-validation-plan`, `author-interface-contract`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt` - **`test-engineer`** → `author-test-prompt`, `discover-tests-for-changes`, `scaffold-test-project` @@ -429,7 +428,7 @@ Domain-agnostic incremental engineering workflow with human-in-the-loop review. - **`copilot-prompt-file`** → — - **`design-doc`** → `author-design-doc` - **`exhaustive-review-report`** → `exhaustive-bug-hunt` -- **`implementation-plan`** → `scaffold-test-project`, `plan-implementation`, `plan-refactoring` +- **`implementation-plan`** → `scaffold-test-project`, `plan-implementation` - **`interface-contract`** → `author-interface-contract` - **`investigation-report`** → `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `audit-interface-contract`, `validate-budget`, `investigate-bug`, `find-and-fix-bugs`, `investigate-security`, `profile-session`, `review-code`, `review-cpp-code`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `audit-library-consistency`, `audit-library-health`, `root-cause-ci-failure`, `review-infrastructure`, `analyze-protocol-conflicts`, `audit-spec-alignment`, `audit-implementation-alignment` - **`multi-artifact`** → `author-workflow-prompts` diff --git a/README.md b/README.md index 33c9b58..cb5e1dc 100644 --- a/README.md +++ b/README.md @@ -569,12 +569,11 @@ personas, analysis protocols, and task templates. | `discover-tests-for-changes` | Find relevant tests for local code changes | | `scaffold-test-project` | Scaffold test project with build and runner setup | -**Planning** (2 templates): +**Planning** (1 template): | Name | Description | |------|-------------| -| `plan-implementation` | Implementation task breakdown with dependencies | -| `plan-refactoring` | Safe, incremental refactoring plan | +| `plan-implementation` | Implementation task breakdown with dependencies. Use `mode=refactoring` for safe, incremental refactoring plans. | **Agent Authoring** (1 template): diff --git a/docs/getting-started.md b/docs/getting-started.md index fd44686..203b901 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -93,7 +93,7 @@ For the full composition model and assembly internals, see the | Write requirements | `author-requirements-doc` | software-architect | | Design a system | `author-design-doc` | software-architect | | Plan implementation | `plan-implementation` | software-architect | -| Plan a refactoring | `plan-refactoring` | software-architect | +| Plan a refactoring | `plan-implementation` (mode=refactoring) | software-architect | | Create a test plan | `author-validation-plan` | software-architect | | Audit for security | `investigate-security` | security-auditor | | Set up CI/CD | `author-pipeline` | devops-engineer | diff --git a/manifest.yaml b/manifest.yaml index fc37ab6..d9b0d22 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -1522,16 +1522,9 @@ templates: path: templates/plan-implementation.md description: > Decompose a project into an actionable implementation plan - with tasks, dependencies, and risk assessment. - persona: software-architect - protocols: [anti-hallucination, self-verification] - format: implementation-plan - - - name: plan-refactoring - path: templates/plan-refactoring.md - description: > - Plan a safe, incremental refactoring with step-by-step - changes that maintain correctness at each step. + with tasks, dependencies, and risk assessment. Supports two + modes: "implementation" (new feature/project) and "refactoring" + (safe, incremental transformation of existing code). persona: software-architect protocols: [anti-hallucination, self-verification] format: implementation-plan diff --git a/protocols/guardrails/adversarial-falsification.md b/protocols/guardrails/adversarial-falsification.md index 79ea5b2..e6dd734 100644 --- a/protocols/guardrails/adversarial-falsification.md +++ b/protocols/guardrails/adversarial-falsification.md @@ -9,10 +9,12 @@ description: > Requires the reviewer to attempt to disprove every candidate finding before reporting it, reject known-safe patterns, and resist premature summarization. applicable_to: - - review-code - - investigate-bug - - investigate-security - exhaustive-bug-hunt + - engineering-workflow + - maintenance-workflow + - spec-extraction-workflow + - audit-spec-alignment + - audit-implementation-alignment --- # Protocol: Adversarial Falsification diff --git a/protocols/guardrails/anti-hallucination.md b/protocols/guardrails/anti-hallucination.md index 52870f8..8a3c70a 100644 --- a/protocols/guardrails/anti-hallucination.md +++ b/protocols/guardrails/anti-hallucination.md @@ -23,8 +23,8 @@ fabrication and enforce intellectual honesty. Every claim in your output MUST be categorized as one of: - **KNOWN**: Directly stated in or derivable from the provided context. -- **INFERRED**: A reasonable conclusion drawn from the context, with the - reasoning chain made explicit. +- **INFERRED**: A conclusion derived through a stated chain of logical steps + from the context, with the reasoning chain made explicit. - **ASSUMED**: Not established by context. The assumption MUST be flagged with `[ASSUMPTION]` and a justification for why it is reasonable. @@ -45,8 +45,9 @@ additional context instead of proceeding. - When multiple interpretations of a requirement or behavior are possible, enumerate them explicitly rather than choosing one silently. -- When confidence in a conclusion is low, state: "Low confidence — this conclusion - depends on [specific assumption]. Verify by [specific action]." +- When a conclusion depends on 2 or more ASSUMED premises (per Rule 1), flag it + explicitly: "Low confidence — this conclusion depends on [N] assumptions: + [list each]. Verify by [specific action]." ### 4. Source Attribution diff --git a/protocols/guardrails/definition-of-done.md b/protocols/guardrails/definition-of-done.md index ddd2996..25f49b2 100644 --- a/protocols/guardrails/definition-of-done.md +++ b/protocols/guardrails/definition-of-done.md @@ -10,6 +10,10 @@ description: > by requiring verification of functionality, tests, diagnostics, build health, regression safety, and plan alignment. applicable_to: [] +# User-composed protocol — not auto-included by any template. +# Intended for: implementation planning, engineering workflows, +# and any task where explicit completion criteria prevent premature +# "done" declarations. --- # Protocol: Definition of Done diff --git a/protocols/guardrails/input-clarity-gate.md b/protocols/guardrails/input-clarity-gate.md index 6cea753..21323a0 100644 --- a/protocols/guardrails/input-clarity-gate.md +++ b/protocols/guardrails/input-clarity-gate.md @@ -11,6 +11,10 @@ description: > natural language input and generates targeted clarifying questions instead of findings. applicable_to: [] +# User-composed protocol — not auto-included by any template. +# Intended for: interactive templates and workflows where user- +# provided natural language input must be validated for clarity +# before task execution begins. --- # Protocol: Input Clarity Gate diff --git a/protocols/guardrails/self-verification.md b/protocols/guardrails/self-verification.md index 312c956..3c94fbb 100644 --- a/protocols/guardrails/self-verification.md +++ b/protocols/guardrails/self-verification.md @@ -39,17 +39,13 @@ presenting it as final. Treat it as a pre-submission checklist. ### 2. Citation Audit -Every factual claim must use the epistemic categories defined in the -`anti-hallucination` protocol (KNOWN / INFERRED / ASSUMED). - -- Every factual claim in the output MUST be traceable to: - - A specific location in the provided code or context, OR - - An explicit `[ASSUMPTION]` or `[INFERRED]` label. -- Scan the output for claims that lack citations. For each: - - Add the citation if the source is identifiable. - - Label as `[ASSUMPTION]` if not grounded in provided context. - - Remove the claim if it cannot be supported or labeled. -- **Zero uncited factual claims** is the target. +Apply the epistemic labeling rules from the `anti-hallucination` protocol +(Rules 1–4: KNOWN/INFERRED/ASSUMED classification, refusal to fabricate, +uncertainty disclosure, source attribution). Scan the output for factual +claims that lack epistemic labels or source citations, and remediate each: +add the appropriate epistemic label (`[KNOWN]`, `[INFERRED]`, or +`[ASSUMPTION]`), add the citation, or remove the claim. **Zero uncited factual +claims** is the target. ### 3. Coverage Confirmation @@ -59,11 +55,9 @@ Every factual claim must use the epistemic categories defined in the but not covered in the output? - If any areas were intentionally excluded, document why in a "Limitations" or "Coverage" section. -- State explicitly: - - "**Examined**: [what was analyzed — directories, files, patterns]." - - "**Method**: [how items were found — search queries, commands, scripts]." - - "**Excluded**: [what was intentionally not examined, and why]." - - "**Limitations**: [what could not be examined due to access, time, or context]." +- Include the 4-field coverage statement defined in the + `operational-constraints` protocol (Rule 9: Examined, Method, + Excluded, Limitations). ### 4. Internal Consistency Check @@ -95,7 +89,9 @@ other directive text intended for LLM consumption, scan for language that introduces non-deterministic interpretation: - [ ] Are all instructions specific enough that two different LLMs - would produce structurally similar output? + would produce output with the same section headings, the same + number of items per section (±20%), and the same classification + labels? - [ ] Are quantifiers concrete (specific counts or ranges, not "some" or "several")? - [ ] Are evaluation criteria observable (not subjective adjectives diff --git a/protocols/guardrails/tool-reliability-defense.md b/protocols/guardrails/tool-reliability-defense.md index 474b860..17d733e 100644 --- a/protocols/guardrails/tool-reliability-defense.md +++ b/protocols/guardrails/tool-reliability-defense.md @@ -10,6 +10,10 @@ description: > confirmation. Addresses known failure modes in AI coding tools including edit corruption, rendering artifacts, and encoding errors. applicable_to: [] +# User-composed protocol — not auto-included by any template. +# Intended for: agentic workflows and agent instruction authoring +# where tool outputs (file edits, shell commands, search results) +# must be independently verified before proceeding. --- # Protocol: Tool Reliability Defense diff --git a/protocols/reasoning/fixed-point-verification.md b/protocols/reasoning/fixed-point-verification.md index deb7b3b..df39c9e 100644 --- a/protocols/reasoning/fixed-point-verification.md +++ b/protocols/reasoning/fixed-point-verification.md @@ -10,6 +10,10 @@ description: > outputs differ, the transformation does not reach a fixed point and is not idempotent or round-trip stable. applicable_to: [] +# User-composed protocol — not auto-included by any template. +# Intended for: compiler, formatter, serializer, migrator, or +# linter auto-fix tasks where idempotency or round-trip stability +# must be verified. --- # Protocol: Fixed-Point Verification diff --git a/templates/plan-implementation.md b/templates/plan-implementation.md index 60067f6..2c99c2b 100644 --- a/templates/plan-implementation.md +++ b/templates/plan-implementation.md @@ -5,127 +5,215 @@ name: plan-implementation description: > Decompose a feature or project into an actionable implementation plan - with tasks, dependencies, and risk assessment. + with tasks, dependencies, and risk assessment. Supports two modes: + "implementation" (new feature/project) and "refactoring" (safe, + incremental transformation of existing code). persona: software-architect protocols: - guardrails/anti-hallucination - guardrails/self-verification format: implementation-plan params: - project_name: "Name of the project or feature" - requirements_doc: "Requirements document (if available)" - design_doc: "Design document (if available)" - description: "Natural language description of what needs to be implemented" - constraints: "Timeline, team size, technology constraints" + project_name: "Name of the project, feature, or refactoring effort" + mode: "Planning mode — 'implementation' (default) for new work, or 'refactoring' for incremental transformation of existing code" + requirements_doc: "(implementation mode) Requirements document, if available" + design_doc: "(implementation mode) Design document, if available" + description: "Natural language description of what needs to be implemented or refactored" + current_code: "(refactoring mode) The code to refactor" + language: "(refactoring mode) Programming language" + constraints: "Timeline, team size, technology constraints, or backward compatibility requirements" + context: "Additional context — why this work is needed, known concerns" input_contract: - type: requirements-document | design-document + type: requirements-document | design-document | source-code description: > - Ideally both a requirements doc and design doc. If only a natural - language description is provided, the plan will note that - requirements and design should be formalized first. + For implementation mode: ideally both a requirements doc and design doc. + For refactoring mode: the current code to be refactored. + If only a natural language description is provided, the plan will note + that formal inputs should be gathered first. output_contract: type: implementation-plan description: > A structured implementation plan with tasks, dependencies, - risk assessment, and milestones. + risk assessment, and milestones — or a refactoring plan with + incremental steps, each maintaining correctness, with rollback strategy. --- # Task: Plan Implementation -You are tasked with producing an **implementation plan** that breaks -down a project into actionable, ordered tasks. +You are tasked with producing a structured plan. The **mode** parameter +determines the planning approach. ## Inputs **Project Name**: {{project_name}} +**Mode**: {{mode}} + +**Description**: +{{description}} + +**Constraints**: +{{constraints}} + +**Context**: +{{context}} + +### Implementation Mode Inputs + **Requirements Document** (if available): {{requirements_doc}} **Design Document** (if available): {{design_doc}} -**Description**: -{{description}} +### Refactoring Mode Inputs -**Constraints**: -{{constraints}} +**Current Code** (if applicable): +```{{language}} +{{current_code}} +``` + +**Language**: {{language}} ## Instructions 1. **Apply the anti-hallucination protocol.** Base the plan on the - provided requirements and design. Do NOT invent tasks for - requirements that do not exist. If the inputs are insufficient - to produce a complete plan, state what is missing. + provided inputs only. Do NOT invent tasks for requirements that do + not exist or assume behaviors not shown in the code. If the inputs + are insufficient, state what is missing. + +2. **Validate the mode parameter.** Only `implementation` and `refactoring` + are valid values. If `mode` is empty, missing, or any other value, + treat it as `implementation` (the default). + +3. **If mode is "implementation"**, follow the + implementation planning workflow: + + a. If requirements or design documents are not provided, begin + with a note: "This plan is based on the natural language description + only. A formal requirements document and design document should be + produced first to validate the plan." + + b. **Decompose into tasks**: + - Each task MUST be specific enough to be assigned to one engineer + - Each task MUST have clear acceptance criteria (how to know it's done) + - Each task MUST have a complexity estimate: Small / Medium / Large + - Tasks should be ordered by dependency, not by perceived importance + + c. **Structure the plan**: + + ```markdown + # Implementation Plan: {{project_name}} + + ## Prerequisites + + + ## Task Breakdown + + ### Phase 1: + + #### TASK-001: + - **Description**: + - **Requirements**: + - **Dependencies**: + - **Acceptance Criteria**: + - **Complexity**: Small / Medium / Large + - **Risks**: + + ### Phase 2: + ... + + ## Dependency Graph + + + ## Risk Assessment + | Risk | Likelihood | Impact | Mitigation | + |------|-----------|--------|------------| + + ## Open Questions + + ``` + + d. **Identify the critical path**: which sequence of dependent tasks + determines the minimum time to completion? + + e. **Flag risky tasks**: tasks with high uncertainty, external + dependencies, or novel technology that could cause delays. + +4. **If mode is "refactoring"**, follow the refactoring planning workflow: -2. **If requirements or design documents are not provided**, begin - with a note: "This plan is based on the natural language description - only. A formal requirements document and design document should be - produced first to validate the plan." + a. **Analyze the current state**: + - What does this code do? (behavioral summary) + - What are its public interfaces / contracts? + - What are its dependencies? + - What implicit assumptions does it make? + - What tests exist (if mentioned in context)? -3. **Decompose into tasks**: - - Each task MUST be specific enough to be assigned to one engineer - - Each task MUST have clear acceptance criteria (how to know it's done) - - Each task MUST have a complexity estimate: Small / Medium / Large - - Tasks should be ordered by dependency, not by perceived importance + b. **Identify refactoring risks**: + - What could break? (callers, downstream consumers, integrations) + - What behaviors are relied upon but not tested? + - Are there hidden coupling points? -4. **Structure the plan**: + c. **Produce an incremental plan** where each step: + - Is a self-contained, committable change + - Maintains all existing behavior (unless explicitly changing it) + - Can be verified before proceeding to the next step + - Has a clear rollback path (revert the commit) - ```markdown - # Implementation Plan: {{project_name}} + d. **Structure the plan**: - ## Prerequisites - + ```markdown + # Refactoring Plan: {{project_name}} - ## Task Breakdown + ## Current State Analysis + - ### Phase 1: - - #### TASK-001: - - **Description**: - - **Requirements**: - - **Dependencies**: - - **Acceptance Criteria**: - - **Complexity**: Small / Medium / Large - - **Risks**: + ## Target State + - ### Phase 2: - ... + ## Risks and Mitigation + | Risk | Impact | Mitigation | + |------|--------|------------| - ## Dependency Graph - + ## Steps - ## Risk Assessment - | Risk | Likelihood | Impact | Mitigation | - |------|-----------|--------|------------| + ### Step 1: + - **Change**: + - **Preserves**: + - **Verify**: + - **Rollback**: - ## Open Questions - - ``` + ### Step 2: ... -5. **Identify the critical path**: which sequence of dependent tasks - determines the minimum time to completion? + ## Verification Strategy + + ``` -6. **Flag risky tasks**: tasks with high uncertainty, external - dependencies, or novel technology that could cause delays. + e. **Prefer small, safe steps** over large, risky ones. + The ideal refactoring step changes structure without changing behavior + (or changes behavior without changing structure), never both at once. ## Non-Goals -- Do NOT implement any tasks — produce the plan only. +- Do NOT implement any tasks or perform the refactoring — produce the plan only. - Do NOT generate requirements or design — consume them as inputs. - Do NOT estimate calendar time or assign tasks to specific people. - Do NOT recommend technology choices unless directly relevant to task decomposition. +- Do NOT add new features as part of a refactoring plan. +- Do NOT assume callers, tests, or dependencies not shown in the + provided code. ## Quality Checklist Before finalizing, verify: -- [ ] Every task has a unique TASK-ID -- [ ] Every task has acceptance criteria -- [ ] Every task has a complexity estimate (Small/Medium/Large) -- [ ] Dependencies between tasks are explicit (no implicit ordering) -- [ ] The critical path is identified +- [ ] Every task/step has a unique identifier (TASK-ID or step number) +- [ ] Every task/step has acceptance criteria or a verification method +- [ ] For implementation: every task has a complexity estimate (Small/Medium/Large) +- [ ] For refactoring: every step has a rollback path +- [ ] Dependencies between tasks/steps are explicit (no implicit ordering) - [ ] Risk assessment covers at least the top 3 risks -- [ ] Requirements traceability is present (REQ-IDs mapped to tasks) -- [ ] No fabricated requirements — unknowns marked with [UNKNOWN] +- [ ] For implementation: the critical path is identified +- [ ] For implementation: requirements traceability is present (REQ-IDs mapped to tasks) +- [ ] No fabricated requirements or code paths — unknowns marked with [UNKNOWN] diff --git a/templates/plan-refactoring.md b/templates/plan-refactoring.md deleted file mode 100644 index a90fabf..0000000 --- a/templates/plan-refactoring.md +++ /dev/null @@ -1,124 +0,0 @@ - - - ---- -name: plan-refactoring -description: > - Plan a safe, incremental refactoring of existing code. Analyze the - current state, identify risks, and produce a step-by-step plan - that maintains correctness at each step. -persona: software-architect -protocols: - - guardrails/anti-hallucination - - guardrails/self-verification -format: implementation-plan -params: - goal: "What the refactoring should achieve" - current_code: "The code to refactor" - language: "Programming language" - constraints: "What must not break, backward compatibility requirements" - context: "Why this refactoring is needed, what problems it solves" -input_contract: null -output_contract: - type: implementation-plan - description: > - A refactoring plan with incremental steps, each maintaining - correctness, with rollback strategy. ---- - -# Task: Plan Refactoring - -You are tasked with producing a **refactoring plan** that transforms -existing code safely and incrementally. - -## Inputs - -**Goal**: {{goal}} - -**Current Code**: -```{{language}} -{{current_code}} -``` - -**Language**: {{language}} - -**Constraints**: {{constraints}} - -**Context**: {{context}} - -## Instructions - -1. **Apply the anti-hallucination protocol.** Base the plan on the - provided code only. Do NOT assume behaviors, dependencies, or - callers that are not shown. - -2. **Analyze the current state**: - - What does this code do? (behavioral summary) - - What are its public interfaces / contracts? - - What are its dependencies? - - What implicit assumptions does it make? - - What tests exist (if mentioned in context)? - -3. **Identify refactoring risks**: - - What could break? (callers, downstream consumers, integrations) - - What behaviors are relied upon but not tested? - - Are there hidden coupling points? - -4. **Produce an incremental plan** where each step: - - Is a self-contained, commitable change - - Maintains all existing behavior (unless explicitly changing it) - - Can be verified before proceeding to the next step - - Has a clear rollback path (revert the commit) - -5. **Structure the plan**: - - ```markdown - # Refactoring Plan: {{goal}} - - ## Current State Analysis - - - ## Target State - - - ## Risks and Mitigation - | Risk | Impact | Mitigation | - |------|--------|------------| - - ## Steps - - ### Step 1: - - **Change**: - - **Preserves**: - - **Verify**: - - **Rollback**: - - ### Step 2: ... - - ## Verification Strategy - - ``` - -6. **Prefer small, safe steps** over large, risky ones. - The ideal refactoring step changes structure without changing behavior - (or changes behavior without changing structure), never both at once. - -## Non-Goals - -- Do NOT perform the refactoring — produce the plan only. -- Do NOT redesign the architecture — focus on incremental improvement. -- Do NOT add new features as part of the refactoring plan. -- Do NOT assume callers, tests, or dependencies not shown in the - provided code. - -## Quality Checklist - -Before finalizing, verify: - -- [ ] Every step is a self-contained, committable change -- [ ] Every step maintains existing behavior (unless explicitly stated) -- [ ] Every step has a verification method -- [ ] Every step has a rollback path -- [ ] Risks and mitigations are documented -- [ ] Current state analysis matches the provided code -- [ ] No fabricated code paths or behaviors — unknowns marked with [UNKNOWN] diff --git a/templates/review-code.md b/templates/review-code.md index 24bb8ef..cade684 100644 --- a/templates/review-code.md +++ b/templates/review-code.md @@ -84,10 +84,24 @@ following code. - Are error messages revealing internal details? ### Maintainability - - Is the code clear and readable? - - Are abstractions appropriate (not too much, not too little)? - - Are there obvious violations of SOLID, DRY, or other design principles? + - Does each function/method have a single, stated responsibility? + - Can a new team member determine each function's purpose from its + name, signature, and the first 5 non-comment lines or top-level + statements of its body? + - Are names (variables, functions, types) specific enough to + distinguish them from siblings in the same scope? - Is error handling consistent with the codebase's conventions? + - Does any abstraction directly combine more than 3 responsibility + categories from this list: state mutation, I/O, parsing/validation, + external service access, concurrency/synchronization, + formatting/presentation, domain rule orchestration? + - Does any abstraction duplicate logic already present in a sibling + module or function, based on the same sequence of steps or the same + conditional/data-transformation logic? Cite the overlapping code. + - Does any class, module, or function lack a clear single + responsibility (i.e., its purpose cannot be stated in one sentence)? + - Are there concrete instances of duplicated code, missing + encapsulation, or violated interface contracts? 4. **Format each finding as**: