forgecraft-mcp 1.2.0 → 1.3.2

package/templates/universal/skills.yaml

@@ -1,262 +1,262 @@
-tag: UNIVERSAL
-section: skills
-skills:
-  - id: code-review
-    name: Code Review
-    filename: code-review.md
-    description: "Structured code review with checklist and severity ratings"
-    tier: core
-    content: |
-      Review the code changes in this project. For each file changed:
-
-      1. **Read** the file and understand the context
-      2. **Check** against these criteria:
-         - Correctness: Does the logic do what it claims?
-         - Security: Any injection, auth bypass, or data leak risks?
-         - Performance: Any N+1 queries, unbounded loops, or memory leaks?
-         - Readability: Are names intention-revealing? Is complexity justified?
-         - Tests: Are edge cases covered? Can tests fail?
-
-      3. **Output** findings in this format:
-         - **File**: path/to/file
-         - **Line**: number
-         - **Severity**: CRITICAL | IMPORTANT | SUGGESTION
-         - **Issue**: description
-         - **Fix**: recommended change
-
-      If $ARGUMENTS is provided, focus the review on those specific files or concerns.
-      Otherwise, review all staged or recently changed files (use `git diff --name-only`).
-
-  - id: run-tests
-    name: Run Tests
-    filename: run-tests.md
-    description: "Run test suite and analyze failures"
-    tier: core
-    content: |
-      Run the project's test suite and analyze the results.
-
-      Steps:
-      {{#if language_is_typescript}}
-      1. Run `npm test` or `npx vitest run`
-      2. If tests fail, read the failing test files and the source code they test
-      3. Identify root cause — is it a test bug or a source bug?
-      4. Propose a fix with explanation
-      {{/if}}
-      {{#if language_is_python}}
-      1. Run `pytest -v` or `python -m pytest`
-      2. If tests fail, read the failing test files and the source code they test
-      3. Identify root cause — is it a test bug or a source bug?
-      4. Propose a fix with explanation
-      {{/if}}
-
-      If $ARGUMENTS is provided, run only matching tests (e.g., a specific file or pattern).
-
-      Always report:
-      - Total tests: passed / failed / skipped
-      - Coverage summary if available
-      - Any flaky test patterns detected
-
-  - id: debug-error
-    name: Debug Error
-    filename: debug-error.md
-    description: "Investigate and fix an error from logs or stack trace"
-    tier: recommended
-    content: |
-      Debug the following error. $ARGUMENTS should contain the error message or stack trace.
-
-      Investigation steps:
-      1. Parse the error message and stack trace
-      2. Identify the source file and line number
-      3. Read the relevant source code
-      4. Trace the data flow backward to find the root cause
-      5. Check for similar patterns elsewhere in the codebase
-      6. Propose a fix with:
-         - **Root cause**: why this happened
-         - **Fix**: the code change
-         - **Prevention**: how to prevent recurrence (test, type guard, validation)
-
-      Do NOT guess. Read the actual code before proposing solutions.
-
-  - id: refactor-file
-    name: Refactor File
-    filename: refactor-file.md
-    description: "Refactor a file following SOLID principles and project conventions"
-    tier: recommended
-    content: |
-      Refactor the file specified in $ARGUMENTS following project conventions.
-
-      Analysis steps:
-      1. Read the file completely
-      2. Check against SOLID principles:
-         - **S**: Does each function/class have one responsibility?
-         - **O**: Can behavior be extended without modifying existing code?
-         - **L**: Are subtypes substitutable?
-         - **I**: Are interfaces focused?
-         - **D**: Are dependencies injected?
-      3. Check project conventions:
-         - Max function length: 50 lines
-         - Max file length: 300 lines
-         - Max parameters: 5 (use parameter object if more)
-         - Intention-revealing names, no abbreviations
-      4. Propose changes grouped by priority:
-         - MUST: Violations of project standards
-         - SHOULD: Improvements to readability/maintainability
-         - COULD: Optional enhancements
-
-      Make changes incrementally. Run tests after each change to verify nothing breaks.
-
-  - id: tdd-workflow
-    name: TDD Workflow
-    filename: tdd-workflow.md
-    description: "Phase-gated TDD cycle: RED → GREEN → REFACTOR with mandatory output at each gate"
-    tier: core
-    content: |
-      Implement the behavior described in $ARGUMENTS using strict TDD. Follow this exact
-      sequence. Do not collapse phases. Each gate requires actual test runner output.
-
-      ---
-
-      ## PHASE 1 — Define and RED
-
-      1. **State the behavior** (one sentence, active voice):
-         > "When [precondition], [actor] [action], and [postcondition]."
-         If you cannot state this precisely, stop. Ask for clarification before writing anything.
-
-      2. **Write the test** — one test, one behavior. Name it as a specification:
-         `it('returns empty cart when last item is removed', ...)`
-         Write against the public interface, not implementation internals.
-
-      3. **Run the test now. Paste the full failure output below.**
-         ```
-         [PASTE FAILURE OUTPUT HERE]
-         ```
-         - If the test PASSES: the test is wrong. It is testing something that already exists
-           or is vacuously true. Do not proceed. Rewrite the test.
-         - If the test errors (import failure, missing module): fix the import, run again,
-           confirm the error is now a test assertion failure, not a setup failure.
-         - If the test fails with the expected assertion: proceed to Phase 2.
-
-      4. **Commit the failing test:**
-         ```
-         git add tests/...
-         git commit -m "test(scope): [RED] [behavior description]"
-         ```
-         The `[RED]` marker in the commit message is the machine-readable signal that this
-         commit represents a known-failing test. Do not commit `src/` files in this commit.
-
-      ---
-
-      ## PHASE 2 — GREEN (minimum implementation)
-
-      5. **Write the minimum code** to make the test pass.
-         - Minimum means: no code that is not required by the current red test.
-         - Do not generalize, do not anticipate the next feature.
-         - If you write more than ~20 lines to make one test pass, the test is too coarse.
-           Split it: write a smaller test, make that pass first.
-
-      6. **Run the full test suite now. Paste the summary output.**
-         ```
-         [PASTE TEST OUTPUT HERE]
-         ```
-         - If new test fails: the implementation introduced a regression. Fix before committing.
-         - If the target test still fails: the implementation is wrong. Do not commit.
-         - If all tests pass: proceed to commit.
-
-      7. **Commit the implementation:**
-         ```
-         git add src/...
-         git commit -m "feat(scope): [behavior description]"
-         ```
-         This commit should contain only `src/` (or equivalent) changes. No test changes.
-         If you need to modify the test to make it pass, that is a test bug — fix the test
-         in a separate commit first with an explanation of why the test was wrong.
-
-      ---
-
-      ## PHASE 3 — REFACTOR
-
-      8. **Inspect the implementation** for structure, not correctness:
-         - Does this function have one responsibility?
-         - Is there any duplication with existing code in `shared/`?
-         - Is the naming consistent with the layer-scoped vocabulary in the constitution?
-         - Is the complexity justified or can it be expressed more simply?
-
-      9. **Refactor one thing at a time. Run tests after each change.**
-         A refactor that breaks a test is not a refactor — it is a behavior change.
-         Revert it and find a correct structural change.
-
-      10. **Commit each refactor separately:**
-          ```
-          git commit -m "refactor(scope): [what changed and why]"
-          ```
-
-      ---
-
-      ## Repeat for next behavior
-
-      Return to Phase 1 with the next behavior. The commit log for a complete feature
-      will read as an alternating sequence: test → feat → refactor → test → feat → ...
-
-      ---
-
-      ## Failure modes to call out explicitly
-
-      If you find yourself in any of these states, stop and flag it:
-      - **"I'll write the test after, the implementation is straightforward"** — this is the
-        most common collapse. The implementation is never so straightforward that the test
-        adds no information. Write the test first.
-      - **"The test passes already"** — the behavior already existed, or the test is wrong.
-        Investigate before proceeding.
-      - **"I need to change the test to make it pass"** — this is acceptable only if the
-        test was incorrectly specified. Commit the test fix with explanation first.
-      - **Multiple behaviors failing at once** — you wrote too much implementation at once
-        in Phase 2. Revert to the minimum, pass the test, then add the next behavior in a
-        new RED cycle.
-
-  - id: static-analysis-duplication
-    name: Check Code Duplication
-    filename: static-analysis-duplication.md
-    description: "Detect copy-paste duplication in source files. Duplicated lines must be < 5% (min 50 tokens per clone)."
-    tier: recommended
-    tags: [UNIVERSAL, CLI, API]
-    content: |
-      Run a copy-paste duplication detector on the source directory.
-      Use the tool appropriate for your language (see project-gates.yaml: no-code-duplication).
-
-      Pass condition: Duplicated lines < 5% of total source lines (min-tokens: 50).
-      If above threshold, extract duplicated logic to a shared utility before committing.
-
-      Evidence: AX experiment — treatment-v6 achieved 2.50% with explicit DRY gate;
-      treatment-v3 reached 7.99% without it.
-
-  - id: static-analysis-circular-deps
-    name: Check Circular Dependencies
-    filename: static-analysis-circular-deps.md
-    description: "Detect circular import chains in the source directory. Zero tolerance."
-    tier: recommended
-    tags: [UNIVERSAL, CLI, API]
-    content: |
-      Run a dependency graph analyzer on the source directory.
-      Use the tool appropriate for your language (see project-gates.yaml: no-circular-dependencies).
-      Some languages (Go, Rust) reject circular imports at compile time natively.
-
-      Pass condition: Zero circular dependencies detected.
-      If cycles are found, extract a shared abstraction or invert the dependency direction.
-
-  - id: static-analysis-mutation
-    name: Run Mutation Tests (Stryker)
-    filename: static-analysis-mutation.md
-    description: "Run Stryker mutation testing. MSI must be >= 65% overall, >= 70% on changed code."
-    tier: recommended
-    tags: [UNIVERSAL, CLI, API]
-    content: |
-      Run Stryker on the changed module to verify test assertions actually catch bugs.
-
-      ```
-      npx stryker run
-      ```
-
-      Pass condition: Mutation Score Indicator (MSI) >= 65% overall, >= 70% on new/changed code.
-      Surviving mutants = missing assertions. Add targeted assertions before proceeding.
-
-      Run after writing each test batch, not only pre-release.
+tag: UNIVERSAL
+section: skills
+skills:
+  - id: code-review
+    name: Code Review
+    filename: code-review.md
+    description: "Structured code review with checklist and severity ratings"
+    tier: core
+    content: |
+      Review the code changes in this project. For each file changed:
+
+      1. **Read** the file and understand the context
+      2. **Check** against these criteria:
+         - Correctness: Does the logic do what it claims?
+         - Security: Any injection, auth bypass, or data leak risks?
+         - Performance: Any N+1 queries, unbounded loops, or memory leaks?
+         - Readability: Are names intention-revealing? Is complexity justified?
+         - Tests: Are edge cases covered? Can tests fail?
+
+      3. **Output** findings in this format:
+         - **File**: path/to/file
+         - **Line**: number
+         - **Severity**: CRITICAL | IMPORTANT | SUGGESTION
+         - **Issue**: description
+         - **Fix**: recommended change
+
+      If $ARGUMENTS is provided, focus the review on those specific files or concerns.
+      Otherwise, review all staged or recently changed files (use `git diff --name-only`).
+
+  - id: run-tests
+    name: Run Tests
+    filename: run-tests.md
+    description: "Run test suite and analyze failures"
+    tier: core
+    content: |
+      Run the project's test suite and analyze the results.
+
+      Steps:
+      {{#if language_is_typescript}}
+      1. Run `npm test` or `npx vitest run`
+      2. If tests fail, read the failing test files and the source code they test
+      3. Identify root cause — is it a test bug or a source bug?
+      4. Propose a fix with explanation
+      {{/if}}
+      {{#if language_is_python}}
+      1. Run `pytest -v` or `python -m pytest`
+      2. If tests fail, read the failing test files and the source code they test
+      3. Identify root cause — is it a test bug or a source bug?
+      4. Propose a fix with explanation
+      {{/if}}
+
+      If $ARGUMENTS is provided, run only matching tests (e.g., a specific file or pattern).
+
+      Always report:
+      - Total tests: passed / failed / skipped
+      - Coverage summary if available
+      - Any flaky test patterns detected
+
+  - id: debug-error
+    name: Debug Error
+    filename: debug-error.md
+    description: "Investigate and fix an error from logs or stack trace"
+    tier: recommended
+    content: |
+      Debug the following error. $ARGUMENTS should contain the error message or stack trace.
+
+      Investigation steps:
+      1. Parse the error message and stack trace
+      2. Identify the source file and line number
+      3. Read the relevant source code
+      4. Trace the data flow backward to find the root cause
+      5. Check for similar patterns elsewhere in the codebase
+      6. Propose a fix with:
+         - **Root cause**: why this happened
+         - **Fix**: the code change
+         - **Prevention**: how to prevent recurrence (test, type guard, validation)
+
+      Do NOT guess. Read the actual code before proposing solutions.
+
+  - id: refactor-file
+    name: Refactor File
+    filename: refactor-file.md
+    description: "Refactor a file following SOLID principles and project conventions"
+    tier: recommended
+    content: |
+      Refactor the file specified in $ARGUMENTS following project conventions.
+
+      Analysis steps:
+      1. Read the file completely
+      2. Check against SOLID principles:
+         - **S**: Does each function/class have one responsibility?
+         - **O**: Can behavior be extended without modifying existing code?
+         - **L**: Are subtypes substitutable?
+         - **I**: Are interfaces focused?
+         - **D**: Are dependencies injected?
+      3. Check project conventions:
+         - Max function length: 50 lines
+         - Max file length: 300 lines
+         - Max parameters: 5 (use parameter object if more)
+         - Intention-revealing names, no abbreviations
+      4. Propose changes grouped by priority:
+         - MUST: Violations of project standards
+         - SHOULD: Improvements to readability/maintainability
+         - COULD: Optional enhancements
+
+      Make changes incrementally. Run tests after each change to verify nothing breaks.
+
+  - id: tdd-workflow
+    name: TDD Workflow
+    filename: tdd-workflow.md
+    description: "Phase-gated TDD cycle: RED → GREEN → REFACTOR with mandatory output at each gate"
+    tier: core
+    content: |
+      Implement the behavior described in $ARGUMENTS using strict TDD. Follow this exact
+      sequence. Do not collapse phases. Each gate requires actual test runner output.
+
+      ---
+
+      ## PHASE 1 — Define and RED
+
+      1. **State the behavior** (one sentence, active voice):
+         > "When [precondition], [actor] [action], and [postcondition]."
+         If you cannot state this precisely, stop. Ask for clarification before writing anything.
+
+      2. **Write the test** — one test, one behavior. Name it as a specification:
+         `it('returns empty cart when last item is removed', ...)`
+         Write against the public interface, not implementation internals.
+
+      3. **Run the test now. Paste the full failure output below.**
+         ```
+         [PASTE FAILURE OUTPUT HERE]
+         ```
+         - If the test PASSES: the test is wrong. It is testing something that already exists
+           or is vacuously true. Do not proceed. Rewrite the test.
+         - If the test errors (import failure, missing module): fix the import, run again,
+           confirm the error is now a test assertion failure, not a setup failure.
+         - If the test fails with the expected assertion: proceed to Phase 2.
+
+      4. **Commit the failing test:**
+         ```
+         git add tests/...
+         git commit -m "test(scope): [RED] [behavior description]"
+         ```
+         The `[RED]` marker in the commit message is the machine-readable signal that this
+         commit represents a known-failing test. Do not commit `src/` files in this commit.
+
+      ---
+
+      ## PHASE 2 — GREEN (minimum implementation)
+
+      5. **Write the minimum code** to make the test pass.
+         - Minimum means: no code that is not required by the current red test.
+         - Do not generalize, do not anticipate the next feature.
+         - If you write more than ~20 lines to make one test pass, the test is too coarse.
+           Split it: write a smaller test, make that pass first.
+
+      6. **Run the full test suite now. Paste the summary output.**
+         ```
+         [PASTE TEST OUTPUT HERE]
+         ```
+         - If new test fails: the implementation introduced a regression. Fix before committing.
+         - If the target test still fails: the implementation is wrong. Do not commit.
+         - If all tests pass: proceed to commit.
+
+      7. **Commit the implementation:**
+         ```
+         git add src/...
+         git commit -m "feat(scope): [behavior description]"
+         ```
+         This commit should contain only `src/` (or equivalent) changes. No test changes.
+         If you need to modify the test to make it pass, that is a test bug — fix the test
+         in a separate commit first with an explanation of why the test was wrong.
+
+      ---
+
+      ## PHASE 3 — REFACTOR
+
+      8. **Inspect the implementation** for structure, not correctness:
+         - Does this function have one responsibility?
+         - Is there any duplication with existing code in `shared/`?
+         - Is the naming consistent with the layer-scoped vocabulary in the constitution?
+         - Is the complexity justified or can it be expressed more simply?
+
+      9. **Refactor one thing at a time. Run tests after each change.**
+         A refactor that breaks a test is not a refactor — it is a behavior change.
+         Revert it and find a correct structural change.
+
+      10. **Commit each refactor separately:**
+          ```
+          git commit -m "refactor(scope): [what changed and why]"
+          ```
+
+      ---
+
+      ## Repeat for next behavior
+
+      Return to Phase 1 with the next behavior. The commit log for a complete feature
+      will read as an alternating sequence: test → feat → refactor → test → feat → ...
+
+      ---
+
+      ## Failure modes to call out explicitly
+
+      If you find yourself in any of these states, stop and flag it:
+      - **"I'll write the test after, the implementation is straightforward"** — this is the
+        most common collapse. The implementation is never so straightforward that the test
+        adds no information. Write the test first.
+      - **"The test passes already"** — the behavior already existed, or the test is wrong.
+        Investigate before proceeding.
+      - **"I need to change the test to make it pass"** — this is acceptable only if the
+        test was incorrectly specified. Commit the test fix with explanation first.
+      - **Multiple behaviors failing at once** — you wrote too much implementation at once
+        in Phase 2. Revert to the minimum, pass the test, then add the next behavior in a
+        new RED cycle.
+
+  - id: static-analysis-duplication
+    name: Check Code Duplication
+    filename: static-analysis-duplication.md
+    description: "Detect copy-paste duplication in source files. Duplicated lines must be < 5% (min 50 tokens per clone)."
+    tier: recommended
+    tags: [UNIVERSAL, CLI, API]
+    content: |
+      Run a copy-paste duplication detector on the source directory.
+      Use the tool appropriate for your language (see project-gates.yaml: no-code-duplication).
+
+      Pass condition: Duplicated lines < 5% of total source lines (min-tokens: 50).
+      If above threshold, extract duplicated logic to a shared utility before committing.
+
+      Evidence: AX experiment — treatment-v6 achieved 2.50% with explicit DRY gate;
+      treatment-v3 reached 7.99% without it.
+
+  - id: static-analysis-circular-deps
+    name: Check Circular Dependencies
+    filename: static-analysis-circular-deps.md
+    description: "Detect circular import chains in the source directory. Zero tolerance."
+    tier: recommended
+    tags: [UNIVERSAL, CLI, API]
+    content: |
+      Run a dependency graph analyzer on the source directory.
+      Use the tool appropriate for your language (see project-gates.yaml: no-circular-dependencies).
+      Some languages (Go, Rust) reject circular imports at compile time natively.
+
+      Pass condition: Zero circular dependencies detected.
+      If cycles are found, extract a shared abstraction or invert the dependency direction.
+
+  - id: static-analysis-mutation
+    name: Run Mutation Tests (Stryker)
+    filename: static-analysis-mutation.md
+    description: "Run Stryker mutation testing. MSI must be >= 65% overall, >= 70% on changed code."
+    tier: recommended
+    tags: [UNIVERSAL, CLI, API]
+    content: |
+      Run Stryker on the changed module to verify test assertions actually catch bugs.
+
+      ```
+      npx stryker run
+      ```
+
+      Pass condition: Mutation Score Indicator (MSI) >= 65% overall, >= 70% on new/changed code.
+      Surviving mutants = missing assertions. Add targeted assertions before proceeding.
+
+      Run after writing each test batch, not only pre-release.

package/templates/universal/structure.yaml

@@ -1,67 +1,67 @@
-tag: UNIVERSAL
-section: structure
-language: both
-entries:
-  - path: CLAUDE.md
-    type: file
-    description: "CC persistent instruction set"
-  - path: Status.md
-    type: file
-    description: "Session bridge — updated every session"
-  - path: .env.example
-    type: file
-    description: "All required env vars documented"
-  - path: .claude/hooks
-    type: directory
-    description: "Git quality gate scripts"
-  - path: docs
-    type: directory
-    description: "PRD, Tech Spec, ADRs"
-  - path: docs/PRD.md
-    type: file
-    description: "Product requirements document"
-  - path: DEVELOPMENT_PROMPTS.md
-    type: file
-    description: "Bound roadmap — session-scoped prompts with spec refs, preconditions, scope, acceptance criteria, and commit message. One entry per roadmap item. Procedural Memory."
-  - path: docs/TechSpec.md
-    type: file
-    description: "Technical specification"
-  - path: docs/adr
-    type: directory
-    description: "Architecture Decision Records"
-  - path: scripts
-    type: directory
-    description: "Project utility scripts"
-  - path: src
-    type: directory
-    description: "Application source code"
-  - path: src/shared/config
-    type: directory
-    description: "Env validation, fail-fast on startup"
-  - path: src/shared/exceptions
-    type: directory
-    description: "Base exception hierarchy"
-  - path: src/shared/logging
-    type: directory
-    description: "Structured logging setup"
-  - path: tests
-    type: directory
-    description: "Test suites"
-  - path: tests/unit
-    type: directory
-    description: "Unit tests"
-  - path: tests/integration
-    type: directory
-    description: "Integration tests"
-  - path: docs/adr
-    type: directory
-    description: "Architecture Decision Records — ADR-NNNN-short-title.md format"
-  - path: docs/diagrams
-    type: directory
-    description: "C4, sequence, state machine, and flow diagrams (PlantUML, Mermaid)"
-  - path: docs/use-cases
-    type: directory
-    description: "Precise use cases: actor, precondition, trigger, main flow, postcondition, acceptance criteria"
-  - path: specs
-    type: directory
-    description: "Platform-independent behavioral specs, session prompts, and generative asset acceptance criteria"
+tag: UNIVERSAL
+section: structure
+language: both
+entries:
+  - path: CLAUDE.md
+    type: file
+    description: "CC persistent instruction set"
+  - path: Status.md
+    type: file
+    description: "Session bridge — updated every session"
+  - path: .env.example
+    type: file
+    description: "All required env vars documented"
+  - path: .claude/hooks
+    type: directory
+    description: "Git quality gate scripts"
+  - path: docs
+    type: directory
+    description: "PRD, Tech Spec, ADRs"
+  - path: docs/PRD.md
+    type: file
+    description: "Product requirements document"
+  - path: DEVELOPMENT_PROMPTS.md
+    type: file
+    description: "Bound roadmap — session-scoped prompts with spec refs, preconditions, scope, acceptance criteria, and commit message. One entry per roadmap item. Procedural Memory."
+  - path: docs/TechSpec.md
+    type: file
+    description: "Technical specification"
+  - path: docs/adr
+    type: directory
+    description: "Architecture Decision Records"
+  - path: scripts
+    type: directory
+    description: "Project utility scripts"
+  - path: src
+    type: directory
+    description: "Application source code"
+  - path: src/shared/config
+    type: directory
+    description: "Env validation, fail-fast on startup"
+  - path: src/shared/exceptions
+    type: directory
+    description: "Base exception hierarchy"
+  - path: src/shared/logging
+    type: directory
+    description: "Structured logging setup"
+  - path: tests
+    type: directory
+    description: "Test suites"
+  - path: tests/unit
+    type: directory
+    description: "Unit tests"
+  - path: tests/integration
+    type: directory
+    description: "Integration tests"
+  - path: docs/adr
+    type: directory
+    description: "Architecture Decision Records — ADR-NNNN-short-title.md format"
+  - path: docs/diagrams
+    type: directory
+    description: "C4, sequence, state machine, and flow diagrams (PlantUML, Mermaid)"
+  - path: docs/use-cases
+    type: directory
+    description: "Precise use cases: actor, precondition, trigger, main flow, postcondition, acceptance criteria"
+  - path: specs
+    type: directory
+    description: "Platform-independent behavioral specs, session prompts, and generative asset acceptance criteria"