sdg-agents 1.1.3 → 1.2.3

package/README.md

@@ -69,9 +69,8 @@ your-project/
 │   │   └── competencies/        ← Layer-specific rules (frontend, backend)
 │   ├── commands/                ← Context files for feat/fix/docs cycles
 │   └── dev-guides/              ← Reference files, spec templates, and guides
-└── .ai-backlog/                 ← Session memory (gitignored)
-    ├── context.md               ← Project brief, decisions, current state
-    └── tasks.md                 ← Task list (TODO / IN_PROGRESS / DONE)
+└── .ai-backlog/                 ← Session memory & Expertise (gitignored)
+    └── ...                      ← (See docs/PROJECT-STRUCTURE.md for details)
 ```
 
 `dev-guides/` is always included. It contains the 5-phase cycle guide, the internal decision-gate flow, SDLC reference, UI prompt guide, and spec templates (`prompt-tracks/`) for authoring the SPEC phase of any task.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "sdg-agents",
-  "version": "1.1.3",
+  "version": "1.2.3",
   "description": "Structured working protocol and engineering rules for AI agents. Works with Claude Code, Antigravity, Codex, and others.",
   "type": "module",
   "main": "./src/engine/bin/index.mjs",
   "bin": {
-    "sdg-agents": "./src/engine/bin/index.mjs"
+    "sdg-agents": "src/engine/bin/index.mjs"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/assets/instructions/commands/sdg-end.md

@@ -12,14 +12,20 @@ Write one sentence per completed PLAN task. If no PLAN existed (e.g. `[S]` tasks
 
 ## Step 2 — CHANGELOG
 
-Append an entry under `## [Unreleased]` in `CHANGELOG.md`:
+- Append an entry under `## [Unreleased]` in `CHANGELOG.md`:
 
-- `feat:` cycle → `### Added`
-- `fix:` cycle → `### Fixed`
-- `docs:` cycle → skip this step
-- `land:` cycle → skip this step
+1. **Identify Version**: Check `package.json` (or equivalent) for the current version.
+2. **Calculate Next**: Determine the next version (patch/minor) based on the cycle type (`feat` → minor/patch, `fix` → patch).
+3. **Update Header**:
+   - If the project uses auto-bump or a release is intended: Create/Update the header to `## [NEXT_VERSION] - YYYY-MM-DD`.
+   - Otherwise: Append under `## [Unreleased]`.
+4. **Append Entry**:
+   - `feat:` cycle → `### Added`
+   - `fix:` cycle → `### Fixed`
+   - `docs:` cycle → skip this step
+   - `land:` cycle → skip this step
 
-If `## [Unreleased]` does not exist, create it above the most recent versioned entry.
+If `## [Unreleased]` (or the appropriate version header) does not exist, create it above the most recent entry.
 
 ## Step 3 — BACKLOG: tasks.md
 
@@ -30,9 +36,13 @@ If `## [Unreleased]` does not exist, create it above the most recent versioned e
 
 Update `## Now` with the next objective, or set it to `Ready for next instruction.` if nothing is pending.
 
-## Step 5 — INSIGHTS
+## Step 5 — KNOWLEDGE (INSIGHTS)
 
-Log any patterns, findings, or rework discovered during this cycle in `context.md ## Engineering Insights`. Curate stale or irrelevant entries.
+Log any patterns, findings, or rework discovered during this cycle. Curate stale or irrelevant entries.
+
+- **feat:** cycle → Update `.ai-backlog/learned.md` with success patterns and research findings.
+- **fix:** cycle → Update `.ai-backlog/troubleshoot.md` with the Root Cause Analysis (RCA) and "gotchas" discovered.
+- **Other:** If specific insights exist but don't fit the above, announce them or update `.ai-backlog/learned.md`.
 
 ## Step 6 — CURATE
 

package/src/assets/instructions/commands/sdg-feat.md

@@ -10,10 +10,11 @@ We are initializing a new feature: $ARGUMENTS. This command prepares the context
    - **Frontend** (UI/UX) → read `.ai/instructions/competencies/frontend.md`
    - **Fullstack** → read both
 3. **Architecture Standards**: If `.ai/instructions/flavor/principles.md` exists, read the established data pipeline (Vertical Slice, MVC, etc.).
-4. **Code Style Load** (mandatory — do not skip):
+4. **Backlog Knowledge**: Read `.ai-backlog/learned.md` to load successful patterns and past research findings.
+5. **Code Style Load** (mandatory — do not skip):
    - **Engineering Standards** → read `.ai/instructions/core/engineering-standards.md`
    - **Code Style & NarrativeCascade** → read `.ai/instructions/core/code-style.md`
-5. **Quality & Debugging**:
+6. **Quality & Debugging**:
    - **Testing Strategy** → read `.ai/instructions/core/testing-principles.md`
    - **Observability** → read `.ai/instructions/core/observability.md`
 

package/src/assets/instructions/commands/sdg-fix.md

@@ -10,10 +10,11 @@ We are correcting a recorded incident: $ARGUMENTS. This command prepares the con
    - **Frontend** (UI/UX) → read `.ai/instructions/competencies/frontend.md`
    - **Fullstack** → read both
 3. **Architecture Standards**: If `.ai/instructions/flavor/principles.md` exists, read the architectural principles.
-4. **Code Style & Standards** (mandatory):
+4. **Backlog Knowledge**: Read `.ai-backlog/troubleshoot.md` to load previous RCA logs and critical failure records.
+5. **Code Style & Standards** (mandatory):
    - **Engineering Standards** → read `.ai/instructions/core/engineering-standards.md`
    - **Code Style & Narrative Scansion** → read `.ai/instructions/core/code-style.md`
-5. **Diagnostic Standards**:
+6. **Diagnostic Standards**:
    - **Testing Principles** → read `.ai/instructions/core/testing-principles.md`
    - **Observability** → read `.ai/instructions/core/observability.md`
 

package/src/assets/instructions/core/engineering-standards.md

@@ -226,6 +226,7 @@ function buildOrderSummary(order) {
 - **Idempotency:** Operations involving money, state changes, or side-effects must use **Idempotency Keys (UUIDs)**.
 - **Graceful Degradation:** Use **Error Boundaries** and defensive type checking (`data?.user?.name`) to prevent UI collapses.
 - **Failure Narrative:** Prefer typed error objects (or Result objects when they clarify the happy/failure path) over magic strings or raw exceptions. Do not force the pattern where idiomatic error handling is already clear.
+- **Toolchain Discoverability & Boot Sanity:** Non-interactive processes (hooks, CI, agents) must explicitly verify or discover their dependencies instead of assuming a pre-configured interactive `$PATH`. Any script that relies on a specific binary (Node, Go, Python, etc.) should fail-fast with a clear diagnostic message if the binary is missing, or attempt to locate it in common installation paths.
   </rule>
 
 ## Rule: Result Pattern & HTTP Envelope

package/src/assets/instructions/idioms/javascript/patterns.md

@@ -216,7 +216,29 @@ export default UserService;
 >
 > </rule>
 
->
+---
+
+## Operational Resilience
+
+### Node Discovery (Shell Resilience)
+
+> <rule name="NodeDiscovery">
+> When writing shell hooks (Husky, CI, git hooks) for a Node project, attempt to discover `node` and `npm` if they are missing from the current `$PATH`. This prevents failures in restricted environments (AI agents, GUI clients).
+
+```bash
+# Node Discovery — Staff-grade Resilience
+if ! command -v node >/dev/null 2>&1; then
+  export PATH="$PATH:/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin"
+  # Source common environment managers
+  [ -f "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh" && nvm use --silent >/dev/null 2>&1
+  [ -f "$HOME/.asdf/asdf.sh" ] && . "$HOME/.asdf/asdf.sh" >/dev/null 2>&1
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "❌ Error: 'node' not found in PATH."
+  exit 1
+fi
+```
 
 > </rule>
 

package/src/assets/instructions/idioms/typescript/patterns.md

@@ -301,4 +301,28 @@ return <div className={headerContainerClassName}>...</div>
 > Fetch and validation in the server block (`---`). Only data is passed to client islands (`client:load`, `client:visible`).
 > </ rule>
 
+## Operational Resilience
+
+### Node Discovery (Shell Resilience)
+
+> <rule name="NodeDiscovery">
+> When writing shell hooks (Husky, CI, git hooks) for a Node project, attempt to discover `node` and `npm` if they are missing from the current `$PATH`. This prevents failures in restricted environments (AI agents, GUI clients).
+
+```bash
+# Node Discovery — Staff-grade Resilience
+if ! command -v node >/dev/null 2>&1; then
+  export PATH="$PATH:/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin"
+  # Source common environment managers
+  [ -f "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh" && nvm use --silent >/dev/null 2>&1
+  [ -f "$HOME/.asdf/asdf.sh" ] && . "$HOME/.asdf/asdf.sh" >/dev/null 2>&1
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "❌ Error: 'node' not found in PATH."
+  exit 1
+fi
+```
+
+> </rule>
+
 </ruleset>

package/src/assets/instructions/templates/workflow.md

@@ -140,10 +140,10 @@ On every request, classify intent before acting:
 ### END Checklist (mandatory — execute in order, mark each before proceeding)
 
 - [ ] **SUMMARIZE** — one sentence per completed PLAN task written in response
-- [ ] **CHANGELOG** — entry appended under `## [Unreleased]` (`### Added` for feat, `### Fixed` for fix; skip for docs)
+- [ ] **CHANGELOG** — Append entry. **Identify next version** (check \`package.json\`) to determine the header (\`## [NEXT_VERSION] - YYYY-MM-DD\` for releases/auto-bump, or \`## [Unreleased]\`). Categories: \`### Added\` (feat), \`### Fixed\` (fix).
 - [ ] **BACKLOG: tasks.md** — all completed tasks moved to `## Done` with `[DONE]` status
 - [ ] **BACKLOG: context.md** — \`## Now\` updated with next objective or cleared
-- [ ] **INSIGHTS** — log patterns, research findings, or rework in \`context.md\` ## Engineering Insights (curate stale or irrelevant items)
+- [ ] **KNOWLEDGE** — Log any patterns, findings, or rework discovered during this cycle. Update \`.ai-backlog/learned.md\` (for successful feats) or \`.ai-backlog/troubleshoot.md\` (for fixed incidents). Curate stale or irrelevant items.
 - [ ] **CURATE** — final scan for slop, "AI-isms", and unfinished comments. Run `git status` to ensure only intended changes are staged.
 - [ ] **LINT** — if lint script exists (`lint`, `lint:fix`, `lint:all`, or config file detected), run it; auto-fix what's possible; block commit if errors remain
 - [ ] **COMMIT** — **PROPOSE** the commit message and **WAIT** for explicit Developer approval
@@ -184,10 +184,6 @@ entry: <main entry point file>
 ## Now
 
 - Ready for next instruction.
-
-## Engineering Insights
-
-- [topic]: [lesson learned or research finding]
 ```
 
 ### Checkpoint (after each atomic task)

package/src/engine/lib/instruction-assembler.mjs

@@ -137,7 +137,9 @@ function buildMasterInstructions(selections) {
         | File | Purpose |
         | :--- | :------ |
         | \`.ai-backlog/context.md\` | Project Brief — read before anything else |
-        | \`.ai-backlog/tasks.md\` | Active tasks and handoff state |`;
+        | \`.ai-backlog/tasks.md\` | Active tasks and handoff state |
+        | \`.ai-backlog/learned.md\` | Lessons Learned — success patterns and research |
+        | \`.ai-backlog/troubleshoot.md\` | Troubleshooting — RCA logs and failure records |`;
 
       return routingString;
     }
@@ -292,6 +294,8 @@ function writeBacklogFiles(targetDir, selections) {
 
   writeContextFile(backlogDir, targetDir, selections);
   writeTasksFile(backlogDir);
+  writeLearnedFile(backlogDir);
+  writeTroubleshootFile(backlogDir);
 
   function writeContextFile(backlogDirPath, projectDir, currentSelections) {
     const contextPath = path.join(backlogDirPath, 'context.md');
@@ -313,9 +317,6 @@ function writeBacklogFiles(targetDir, selections) {
 
       ## Now
       [what is actively being worked on]
-
-      ## Engineering Insights
-      - [topic]: [lesson learned or research finding]
     `;
 
     fs.writeFileSync(contextPath, contextContent);
@@ -343,6 +344,46 @@ function writeBacklogFiles(targetDir, selections) {
 
     fs.writeFileSync(tasksPath, tasksContent);
   }
+
+  function writeLearnedFile(backlogDirPath) {
+    const learnedPath = path.join(backlogDirPath, 'learned.md');
+    if (fs.existsSync(learnedPath)) return;
+
+    const learnedContent = dedent`
+      # Lessons Learned & Research
+
+      > Persistent repository for success patterns, technical research, and architecture decisions.
+      > Loaded during \`feat:\` cycles.
+
+      ## Success Patterns
+      - [topic]: [pattern or approach that worked well]
+
+      ## Research Findings
+      - [topic]: [discovery or validated hypothesis]
+    `;
+
+    fs.writeFileSync(learnedPath, learnedContent);
+  }
+
+  function writeTroubleshootFile(backlogDirPath) {
+    const troubleshootPath = path.join(backlogDirPath, 'troubleshoot.md');
+    if (fs.existsSync(troubleshootPath)) return;
+
+    const troubleshootContent = dedent`
+      # Troubleshooting & RCA Logs
+
+      > Persistent repository for failure records, Root Cause Analysis (RCA), and technical debt.
+      > Loaded during \`fix:\` cycles to prevent regression.
+
+      ## Failure Records (RCA)
+      - [date] [topic]: [what failed, why, and the "gotcha" to avoid]
+
+      ## Technical Debt & Risks
+      - [topic]: [known limitation or fragile area]
+    `;
+
+    fs.writeFileSync(troubleshootPath, troubleshootContent);
+  }
 }
 
 /**
@@ -368,7 +409,8 @@ function buildClaudeContent() {
 
     1. **Check backlog**: Read \`.ai-backlog/context.md\` — understand the project brief. **Priority**: Always check the local directory first to avoid redundant scans.
     2. **Check tasks**: Read \`.ai-backlog/tasks.md\` — resume any \`[IN_PROGRESS]\` task before accepting new work.
-    3. **Bootstrap if missing**: If \`.ai-backlog/context.md\` does not exist, follow the **Context Bootstrap** defined in the Working Protocol (loaded via \`@.ai/skill/AGENTS.md\` above).
+    3. **Terminal Sanity Check**: Run \`node -v\` and \`npm -v\` (or the project's primary toolchain) to "wake up" the terminal and confirm execution capabilities in the current shell.
+    4. **Bootstrap if missing**: If \`.ai-backlog/context.md\` does not exist, follow the **Context Bootstrap** defined in the Working Protocol (loaded via \`@.ai/skill/AGENTS.md\` above).
 
     ## Intent Routing (quick reference)