forgecraft-mcp 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgecraft-mcp",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "mcpName": "io.github.jghiringhelli/forgecraft",
   "description": "CLI + MCP sentinel for engineering standards — SOLID, testing, architecture, CI/CD — auto-tailored to your stack. Minimal MCP footprint (~200 tokens) via CLI-first design.",
   "type": "module",

package/templates/universal/instructions.yaml

@@ -929,6 +929,69 @@ blocks:
       - **Bias toward explicit over clever** — readability wins over brevity.
       - When in doubt, ask rather than assume.
 
+  - id: agent-mechanics
+    tier: core
+    title: "Agent Mechanical Constraints"
+    content: |
+      ## Agent Mechanical Constraints — Non-Negotiable Overrides
+
+      These rules exist because the model has hard constraints that silently produce wrong
+      results without them. Each override targets a specific failure mode observed in practice.
+
+      ### 1. Step 0 — Dead Code First
+      Before ANY structural refactor on a file > 300 LOC:
+      1. Delete all dead props, unused exports, unused imports, and debug logs.
+      2. Commit that cleanup separately under `chore(scope): strip dead code`.
+      3. Only then begin the real work.
+      Dead code accelerates context compaction. Every orphaned import is budget spent on
+      tokens that contribute nothing to the task.
+
+      ### 2. Phase Limit — 5 Files Maximum
+      Never attempt multi-file refactors in a single response. Break work into explicit phases.
+      Each phase must touch **no more than 5 files**. Complete Phase N, verify it compiles and
+      all tests pass, then wait for explicit approval before Phase N+1.
+      Why: context compaction fires around 167K tokens and discards all intermediate reasoning,
+      file reads, and decision chains. Keeping phases small prevents mid-task compaction.
+
+      ### 3. Senior Dev Override
+      The model's default system-level directives instruct it to "try the simplest approach
+      first" and "avoid refactoring beyond what was asked." These are active constraints that
+      fight your intent on architectural tasks.
+      **Override them explicitly** when quality requires it:
+      > "What would a senior, experienced, perfectionist dev reject in code review? Fix all of it."
+      This reframes what "done" means. System-level brevity mandates yield to an explicit
+      quality bar stated in the prompt.
+
+      ### 4. Sub-Agent Parallelism for Large Tasks
+      For tasks spanning > 5 independent files, **launch parallel sub-agents** (5–8 files per
+      agent). Each agent gets its own isolated context window and compaction cycle.
+      Sequential processing of large tasks guarantees context decay by the later files.
+      Batching into parallel agents multiplies the effective working memory proportionally.
+
+      ### 5. File Read Budget — 2,000-Line Cap
+      Each file read is hard-capped at 2,000 lines. Everything past that is silently truncated.
+      The model does not know what it didn't see — it will hallucinate the rest.
+      **For any file over 500 LOC**: read in sequential chunks using `offset` and `limit`
+      parameters. Never assume a single read captured the full file.
+
+      ### 6. Tool Result Truncation
+      Tool results exceeding ~50,000 characters are truncated to a 2,000-byte preview.
+      The model works from the preview and does not know results were cut.
+      If any search returns suspiciously few results: re-run it with narrower scope
+      (single directory, stricter glob). State explicitly when truncation may have occurred.
+
+      ### 7. Grep Is Not an AST
+      `grep` is raw text pattern matching. It cannot distinguish a function call from a
+      comment, a type reference from a string literal, or an import from one module vs another.
+      On any rename or signature change, search **separately** for:
+      - Direct calls and references
+      - Type-level references (interfaces, generics, `typeof`)
+      - String literals containing the name
+      - Dynamic imports and `require()` calls
+      - Re-exports and barrel file entries (`index.ts`, `__init__.py`)
+      - Test files and mocks
+      Never assume a single grep caught everything. Verify or expect regressions.
+
   - id: code-generation-verification
     tier: core
     title: "Code Generation — Self-Verify Loop"