harness-everything 0.2.2 → 0.4.0

package/find-skills/references/discovery-flow.md

@@ -0,0 +1,102 @@
+# Find Skills — Full Discovery & Application Reference
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[User Asks for Skill / Capability X] --> CheckLocal{1. Covered by Static or Self-Evolved Skills?}
+
+    CheckLocal -- Yes --> UseLocal[Use Existing Harness Skill / Dynamic Generated Skill]
+    CheckLocal -- No --> CheckNet{2. Network & npx Executable?}
+
+    CheckNet -- Yes --> SearchSkills[Search via npx skills find / skills.sh]
+    SearchSkills -- Found & Approved --> ApplySkill[Apply Ephemerally via use-skill.js or npx skills add]
+    SearchSkills -- Network / Search Fails --> FallbackGeneral
+
+    CheckNet -- No --> FallbackGeneral{3. Offline / General Domain Capability Fallback}
+
+    FallbackGeneral --> ExecuteDirect[Apply Built-in Best Practices / Direct Solution]
+
+    UseLocal --> Done[Delivered Capabilities]
+    ApplySkill --> Done
+    ExecuteDirect --> Done
+```
+
+## 0. Check existing coverage first (full detail)
+
+Confirm the capability doesn't already exist, in this order:
+
+1. **Static skills** — grep `harness-everything/SKILL.md` §5's registry table for a matching row. This is the reviewed, first-party skill set; `tier-router.js` also surfaces it automatically by keyword.
+2. **Self-evolved dynamic skills** (`generated[]`) — skills this workspace's own agent authored via `self-evolve` after a hard-won lesson. `tier-router.js` scans every reachable `manifest.json`'s `generated[]` array every turn and prints a `🎯 HIGH-RELEVANCE SELF-EVOLVED SKILL DETECTED` block when a skill's `triggers` match — check this turn's routing checkpoint output before doing anything else.
+3. **Third-party skills someone already chose to keep** — query live, don't guess:
+
+   ```bash
+   npx skills list --json          # project scope
+   npx skills list -g --json       # global scope
+   ```
+
+   This only ever finds something if a past session went through the rare permanent-install exception path — the default ephemeral path never shows up here, by design, because it never installs anything. Checked live rather than cached on purpose: unlike `generated[]` (which Harness fully owns — authored, quality-gated by `skill-creator`, lifecycle-tracked draft/active/deprecated), a third-party skill's content can change out from under a cache the moment its author updates it or the user runs `npx skills update`/`remove` — Harness has no way to govern that lifecycle, so it doesn't pretend to by caching a snapshot. `npx skills list` is already the CLI's own live, authoritative record. (Full reasoning: `docs/reflection.md`'s "External Skills" section.)
+
+## 1. Understand what they need
+
+Identify: the domain (React, testing, deployment, design...), the specific task, and whether it's common enough that a published skill likely exists.
+
+## 2. Check the leaderboard first
+
+Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) for a well-known skill in the domain. Top sources: `vercel-labs/agent-skills` (React, Next.js, web design), `anthropics/skills` (frontend design, document processing).
+
+## 4. Verify quality before recommending (full criteria)
+
+Don't recommend a skill from search results alone. Check:
+
+- **Install count** — prefer 1K+ installs; be cautious under 100.
+- **Source reputation** — official sources (`vercel-labs`, `anthropics`, `microsoft`) outrank unknown authors.
+- **GitHub stars** — treat a source repo with <100 stars with skepticism.
+- **Trust, not just quality** — a third-party `SKILL.md` is natural-language instructions that get loaded into agent context and followed, whether applied ephemerally or installed permanently. Unlike this repo's own skills (which pass `skill-creator`'s Quality Checklist and get reviewed via PR), it's unaudited. Read the actual `SKILL.md` content before applying it, the same way you'd review a dependency before adding it — not just its install count.
+
+## 5. Present options — example message
+
+```
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+Source: vercel-labs/agent-skills@react-best-practices
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+
+Want me to apply it to this task? (It won't be installed anywhere unless you
+tell me you'll want it again later.)
+```
+
+Show the skill name, what it does, install count/source, and ask whether this is a one-off or something worth keeping. Never fetch or apply anything from search results without explicit confirmation.
+
+## 6. Apply ephemerally — how the wrapper works
+
+Run this skill's own small wrapper instead of raw `npx skills use`:
+
+```bash
+node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>
+```
+
+It prints the skill's `SKILL.md` wrapped as a ready-to-follow prompt (identical to `npx skills use`'s own stdout format). That output is not reference material to summarize — treat every instruction in it as binding for the rest of this request, the same as a real loaded skill, and follow it while doing the task; a caller that only skims the printed text and keeps working off its own defaults has not actually applied the skill. Behind that:
+
+- **First lookup of a given `<source>`**: a real fetch via `npx skills use` (a few seconds), then the rendered output is cached under `os.tmpdir()/harness-find-skills-cache/<sha1-of-source>.md`.
+- **Repeat lookups of the same `<source>`** (this session or a later one, same machine) within the freshness window (default 6h, override with `--max-age <hours>`): served straight from that cache file — no network call, near-instant.
+- **Nothing is written to the repo, to any platform's native skill directory, or to `manifest.json`.** The cache lives entirely under the OS temp directory, so it needs no explicit cleanup and nothing for Harness to track — the OS reclaiming temp files on its own schedule is the only "expiry" this needs, and a reclaimed-or-past-freshness-window entry is just treated as a fresh cache miss.
+
+This is the default for a reason: a skill applied through here costs real work on first fetch and effectively nothing on repeats, without ever growing a footprint that later sessions have to read through or a human has to remember to clean up.
+
+## 6b. Install permanently — full mapping
+
+Only when the user says this is something they expect to reuse across many future sessions — not the default, and not implied by "yes, use it":
+
+```bash
+npx skills add <owner/repo[@skill]> --agent <agent> [-g] -y
+```
+
+Map whichever platform this session is actually running in to the CLI's own agent name: `claude` → `claude-code`, `cursor` → `cursor`, `copilot` → `github-copilot`, `codex` → `codex`, `continue` → `continue`. `-g` targets that platform's global skill directory instead of the project-local one — same local-vs-global convention `scripts/installer.js` uses. Nothing further to register: §0.3's live `npx skills list` finds it again next time.
+
+## Related mechanisms
+
+- `self-evolve/SKILL.md` + `skill-creator/SKILL.md` §4 — the Dynamic Skill Generation Contract for `generated[]` skills. Deliberately a *different* mechanism from this skill, not a shared one: `generated[]` skills are self-authored and lifecycle-owned by Harness, so caching their triggers in `manifest.json` for `tier-router.js` to match is safe. Third-party skills fetched here default to a self-expiring OS-temp cache with no Harness bookkeeping at all (§6), or, in the rare §6b case, the CLI's own native install + lock file — never a second, driftable Harness-owned cache.
+- `harness-everything/SKILL.md` §5 — the static skill registry to check before searching externally.

package/find-skills/scripts/use-skill.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * Ephemeral third-party skill lookup: prints a skill's SKILL.md wrapped as a
+ * ready-to-apply prompt (the same shape `npx skills use` writes to stdout),
+ * backed by a content-addressed cache under the OS temp directory so
+ * repeat lookups of the same <source> cost zero network calls within the
+ * cache's freshness window.
+ *
+ * Deliberately writes nothing anywhere Harness owns - no manifest, no
+ * platform's native skill directory. The cache lives entirely under
+ * os.tmpdir() and needs no explicit cleanup: the OS reclaims temp files on
+ * its own schedule, and the freshness check below (default 6h) means a
+ * lingering entry just gets treated as a miss and re-fetched rather than
+ * served stale. That's the only "lifecycle" this needs - nothing for
+ * Harness to track or govern, unlike self-evolve's `generated[]`.
+ *
+ * Usage:
+ *   node use-skill.js <owner/repo[@skill]> [--max-age <hours>]
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+let getStateHome;
+try {
+  ({ getStateHome } = require('../../scripts/lib/workspace'));
+} catch (err) {
+  getStateHome = () => path.join(os.homedir(), '.agents', 'harness-everything');
+}
+
+const CACHE_DIR = path.join(getStateHome(), 'cache', 'find-skills');
+const DEFAULT_MAX_AGE_HOURS = 6;
+
+// `source` is a third-party-supplied identifier (from a search result the
+// agent picked) that ends up in a shell command line - `npx` is a `.cmd`
+// shim on Windows, which CreateProcess can only launch through a shell, so
+// there's no shell-free path here. Node's own child_process docs flag
+// spawn/execFile's `{args: [...], shell: true}` form as unsafe (DEP0190: the
+// array isn't actually escaped, just concatenated) - execSync's single
+// pre-built string is the form Node expects the caller to have already
+// validated, so this allow-list IS the injection defense, checked before the
+// string is built. A package spec never legitimately needs spaces or shell
+// metacharacters (`&|;$()<>\`"'`).
+const SAFE_SOURCE_PATTERN = /^[A-Za-z0-9._/@:-]+$/;
+
+function assertSafeSource(source) {
+  if (!SAFE_SOURCE_PATTERN.test(source)) {
+    console.error(`[Error] Refusing to run "npx skills use" with a source containing unexpected characters: ${JSON.stringify(source)}`);
+    process.exit(1);
+  }
+}
+
+function parseArgs(argv) {
+  const opts = { source: null, maxAgeHours: DEFAULT_MAX_AGE_HOURS };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--max-age') opts.maxAgeHours = Number(argv[++i]);
+    else rest.push(a);
+  }
+  opts.source = rest[0] || null;
+  return opts;
+}
+
+function cachePathFor(source) {
+  const hash = crypto.createHash('sha1').update(source).digest('hex');
+  return path.join(CACHE_DIR, `${hash}.md`);
+}
+
+function readCacheIfFresh(cachePath, maxAgeHours) {
+  if (!fs.existsSync(cachePath)) return null;
+  const ageMs = Date.now() - fs.statSync(cachePath).mtimeMs;
+  if (ageMs > maxAgeHours * 60 * 60 * 1000) return null;
+  return fs.readFileSync(cachePath, 'utf8');
+}
+
+function main() {
+  const { source, maxAgeHours } = parseArgs(process.argv.slice(2));
+  if (!source) {
+    console.error('Usage: node use-skill.js <owner/repo[@skill]> [--max-age <hours>]');
+    process.exit(1);
+  }
+  assertSafeSource(source);
+
+  const cachePath = cachePathFor(source);
+  const cached = readCacheIfFresh(cachePath, maxAgeHours);
+  if (cached !== null) {
+    process.stderr.write(`[find-skills] cache hit (<${maxAgeHours}h old, no network call): ${cachePath}\n`);
+    process.stdout.write(cached);
+    return;
+  }
+
+  process.stderr.write(`[find-skills] cache miss - fetching "${source}" via npx skills use...\n`);
+  let prompt;
+  try {
+    // Safe to interpolate directly: assertSafeSource() already rejected
+    // anything outside [A-Za-z0-9._/@:-], so there's no metacharacter left
+    // for a shell to act on.
+    const npxCmd = os.platform() === 'win32' ? 'npx.cmd' : 'npx';
+    prompt = execSync(`${npxCmd} --yes skills use ${source}`, { encoding: 'utf8', shell: true });
+  } catch (err) {
+    console.error(`[Error] "npx skills use ${source}" failed:\n${(err.stderr || err.message || '').toString().trim()}`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  fs.writeFileSync(cachePath, prompt, 'utf8');
+  process.stdout.write(prompt);
+}
+
+main();

package/git-commit/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: git-commit
-description: Generates Angular-style commit messages after verifying the environment and staged files.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: "Generate Angular-style commit messages after verifying the environment, submodules, and staged files; use for explicit commit requests or concluded task phases."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
 ---
 
 # Git Commit (Angular Style)
@@ -11,45 +13,26 @@ version: 0.2.0
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | User explicitly requests a commit, or a task phase concludes. Input: Staged git diff. |
-| **Expected Output** | Execution of `git commit -m "..."`. |
-| **State Mutations** | Git tree is updated. Workspace becomes clean. |
-| **Enforcement Gate** | You MUST run `git status`. If there are no staged files, the terminal will exit 1 when you try to commit, or you MUST ask the user before staging. |
-
-This skill is automatically triggered by the `harness-everything` router upon task completion or when the user explicitly requests "commit" or "save changes".
-
-## 1. Triggers
-- The final step of the TDD cycle (after Refactor is completed).
-- Sub-task milestones within `fable-mode`.
-- The user explicitly issues commands like "commit", "save changes", "git commit".
-
-## 2. Environment Discovery & Prerequisite Defense `[Discover]`
-Before generating a commit message, you **MUST** execute the following discovery:
-- Run `git status` to check which files are staged or modified.
-- **Circuit Breaker**: If no files are staged, ask the user if they want to stage the currently modified files; fabricating commit messages out of thin air is PROHIBITED.
-- Check if working within a Submodule. If so, you MUST handle commits for the Main Repo and Sub Repo separately.
-
-## 3. Master Routing Workflow (Order of Operations)
-When both the Main Repo and any Submodules have changes, you **MUST** prioritize and process Submodule changes first. Strictly follow this execution order:
-1. **Detect Submodule Changes First**: Before processing the Main Repo, you MUST check if any submodules have changes (staged or unstaged).
-2. **Prioritize Submodule Commits**: If any submodules have changes, you MUST halt Main Repo commit generation immediately. Run `git-commit/guides/SUBMODULES.md` first to commit all submodule changes and update their pointers in the Main Repo.
-3. **Stage Submodule Pointers in Main Repo**: Ensure that updated submodule pointers are added (`git add <submodule_path>`) to the Main Repo staging area before generating the Main Repo commit.
-4. **Execute Main Repo Commit Last**: Once all submodules are fully clean and their new pointers are staged in the Main Repo, you may then proceed with `git-commit/guides/MAIN_REPO.md` to commit the Main Repo changes.
-
-## 4. Commit Generation Discipline (Angular Style)
-- Strictly follow the format: `<type>(<scope>): <subject>`.
-- **Type**: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`.
-- **Subject**: Short and concise, use the imperative, present tense (e.g., "add user auth", not "added user auth"), no capitalized first letter, no dot (.) at the end.
-- **Body (if necessary)**: Explain "why" this change was made and the "root cause of the problem", and MUST include a clear, structured bulleted list detailing the exact modified parts (such as files, functions, or logical adjustments) extracted from the `git diff --cached` analysis.
-
-## 5. Execution and Handoff `[Try] & [Summarize]`
-- After confirming the commit message, call the terminal tool to execute `git commit -m "..." -m "..."`.
-- Upon success, if still within the `fable-mode` workflow, hand control back to `fable-mode` to continue to the next milestone.
-
-## Deep Reference Guides
-For comprehensive details on commit rules and submodule configurations, refer to:
-- `git-commit/guides/ANGULAR_STYLE.md` — Complete specification for commit messages
-- `git-commit/guides/COMMIT_GENERATION.md` — Generation patterns and strategies
-- `git-commit/guides/LANGUAGE_DETECTION.md` — Language-specific commit guidelines
-- `git-commit/guides/MAIN_REPO.md` — Committing within monorepos/main repo contexts
-- `git-commit/guides/SUBMODULES.md` — Advanced handling of submodules and nested repos
+| **Trigger / Input** | User requests a commit, or a task phase concludes. Input: staged git diff. |
+| **Expected Output** | Clean Angular-style commit via `git commit -m` or temp file (`git commit -F`). |
+| **State Mutations** | Git tree updated; working tree becomes clean. |
+| **Enforcement Gate** | Run `git status` first; nothing staged → prompt user; non-git repo → offer `git init` or skip. |
+
+## Quick Workflow
+
+1. `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `<this-skill-dir>/guides/SUBMODULES.md`.
+2. `git diff --cached`; nothing staged → prompt user / stage targeted files.
+3. Format `<type>(<scope>): <subject>` per `<this-skill-dir>/guides/ANGULAR_STYLE.md`. Multiline/Windows → `.git-commit-msg.txt` + `git commit -F`, clean up.
+4. `git commit -m "..."`, verify with `git log -1`.
+
+## USE FOR:
+- Commit request from the user
+- Formatting conventional commit messages
+- Submodule or monorepo commits
+
+## DO NOT USE FOR:
+- Staging without user confirmation
+- Branching, rebasing, merging, pushing
+- Non-git dirs where user declines `git init`
+
+Deep dive: <this-skill-dir>/references/commit-flow.md

package/git-commit/guides/ANGULAR_STYLE.md

@@ -1,61 +1,61 @@
-# Angular-Style Conventional Commits
-
-**[State Checkpoint]**
-- MUST verify the target language determined by Language Detection.
-
-## Commit Message Format
-
-```text
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-## Field Definitions
-
-1. **Type**: MUST be exactly one of: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
-   - MUST use `style` or `chore` for trivial/formatting changes.
-2. **Scope**: MUST enclose in parentheses if used.
-   - For Sub Repos: MUST use the Sub Repo name.
-   - For Code: MUST use a concise, high-level module name (e.g., `auth`, `ui`). MUST NOT use file paths.
-3. **Subject**: MUST use imperative mood, present tense, maximum 50 characters, NO trailing period. MUST be in the target language.
-4. **Body**: MUST describe motivation and context, and MUST analyze the staged changes to list the exact modifications in a clear, structured bulleted list.
-   - MUST analyze the `git diff --cached` output to extract the specific files, functions, or logic modified.
-   - MUST list each major change or file-level modification with a brief description of "what was changed" (e.g., `- Updated user schema to support OAuth IDs in src/models/user.ts`).
-   - MUST NOT separate bullet points with blank lines.
-   - MUST NOT artificially wrap lines.
-   - MUST be in the target language.
-5. **Footer**: MUST prefix breaking changes with `BREAKING CHANGE:`. MUST reference issues via `Closes #<id>`.
-
-## Code Change Output Example
-
-```text
-feat(auth): add OAuth2 login support
-
-Core intent: Allows users to sign in using Google and GitHub to simplify user authentication.
-
-Changes:
-- Added OAuth2 client config schema and defaults in `config/auth.ts`
-- Implemented OAuth2 middleware verification pipeline in `src/middleware/oauth.ts`
-- Updated user database model to store external provider IDs in `src/models/user.ts`
-- Added comprehensive integration tests for external provider flows in `tests/auth.test.ts`
-```
-
-## Submodule Update Output Example
-
-```text
-chore(ui): update ui submodule
-
-Core intent: Introduces dark mode support and resolves various UI layout issues.
-
-Included commits:
-- fix: align button text
-- feat: add dark mode
-- style: update primary color hex
-- fix: resolve layout shift on mobile
-```
-- style: update primary color hex
-- fix: resolve layout shift on mobile
+# Angular-Style Conventional Commits
+
+**[State Checkpoint]**
+- MUST verify the target language determined by Language Detection.
+
+## Commit Message Format
+
+```text
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+## Field Definitions
+
+1. **Type**: MUST be exactly one of: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
+   - MUST use `style` or `chore` for trivial/formatting changes.
+2. **Scope**: MUST enclose in parentheses if used.
+   - For Sub Repos: MUST use the Sub Repo name.
+   - For Code: MUST use a concise, high-level module name (e.g., `auth`, `ui`). MUST NOT use file paths.
+3. **Subject**: MUST use imperative mood, present tense, maximum 50 characters, NO trailing period. MUST be in the target language.
+4. **Body**: MUST describe motivation and context, and MUST analyze the staged changes to list the exact modifications in a clear, structured bulleted list.
+   - MUST analyze the `git diff --cached` output to extract the specific files, functions, or logic modified.
+   - MUST list each major change or file-level modification with a brief description of "what was changed" (e.g., `- Updated user schema to support OAuth IDs in src/models/user.ts`).
+   - MUST NOT separate bullet points with blank lines.
+   - MUST NOT artificially wrap lines.
+   - MUST be in the target language.
+5. **Footer**: MUST prefix breaking changes with `BREAKING CHANGE:`. MUST reference issues via `Closes #<id>`.
+
+## Code Change Output Example
+
+```text
+feat(auth): add OAuth2 login support
+
+Core intent: Allows users to sign in using Google and GitHub to simplify user authentication.
+
+Changes:
+- Added OAuth2 client config schema and defaults in `config/auth.ts`
+- Implemented OAuth2 middleware verification pipeline in `src/middleware/oauth.ts`
+- Updated user database model to store external provider IDs in `src/models/user.ts`
+- Added comprehensive integration tests for external provider flows in `tests/auth.test.ts`
+```
+
+## Submodule Update Output Example
+
+```text
+chore(ui): update ui submodule
+
+Core intent: Introduces dark mode support and resolves various UI layout issues.
+
+Included commits:
+- fix: align button text
+- feat: add dark mode
+- style: update primary color hex
+- fix: resolve layout shift on mobile
+```
+- style: update primary color hex
+- fix: resolve layout shift on mobile
 ```

package/git-commit/guides/COMMIT_GENERATION.md

@@ -1,24 +1,24 @@
-# Commit Generation Workflow
-
-**[State Checkpoint]**
-- MUST verify the target repository path passed from the previous step.
-- MUST ensure terminal is located in the target repository BEFORE generating commits.
-- MUST explicitly recall diff content and any provided Sub Repo logs.
-
-## [Preparation Phase]
-1. Language Selection: MUST execute `LANGUAGE_DETECTION.md`.
-2. Format Rules: MUST read and strictly follow `ANGULAR_STYLE.md`.
-
-## [Action Phase]
-3. Message Construction: MUST generate a strict Angular format message (Type, Scope, Subject, Body, Footer) integrating diff analysis.
-   - MUST perform a detailed analysis on `git diff --cached` to extract the exact files modified, functions/classes added or adjusted, and logical configuration changes.
-   - MUST compile these extracted points into a structured, bulleted list in the commit message body (e.g., listing changes file-by-file or feature-by-feature) so that the commit message serves as an accurate, self-contained changelog of the staged changes.
-4. Context Integration: IF Sub Repo logs were passed, MUST seamlessly integrate ALL Sub Repo log summaries into the commit body.
-5. State Isolation: MUST ignore unstaged changes AND MUST NOT run `git add` to prevent contamination.
-6. Execution: MUST execute the commit securely (e.g., `git commit -F - <<EOF` or writing to a temporary file) to ensure special characters do not break the terminal command.
-
-## [Validation & Summarize Phase]
-7. Error Handling: MUST verify if the commit command succeeded. IF it fails (e.g., pre-commit hooks, GPG), MUST NOT blindly halt. MUST diagnose the error, preserve the generated message in a temporary file, and pause to ask the user for remediation.
-
-## [Record: Handoff]
+# Commit Generation Workflow
+
+**[State Checkpoint]**
+- MUST verify the target repository path passed from the previous step.
+- MUST ensure terminal is located in the target repository BEFORE generating commits.
+- MUST explicitly recall diff content and any provided Sub Repo logs.
+
+## [Preparation Phase]
+1. Language Selection: MUST execute `LANGUAGE_DETECTION.md`.
+2. Format Rules: MUST read and strictly follow `ANGULAR_STYLE.md`.
+
+## [Action Phase]
+3. Message Construction: MUST generate a strict Angular format message (Type, Scope, Subject, Body, Footer) integrating diff analysis.
+   - MUST perform a detailed analysis on `git diff --cached` to extract the exact files modified, functions/classes added or adjusted, and logical configuration changes.
+   - MUST compile these extracted points into a structured, bulleted list in the commit message body (e.g., listing changes file-by-file or feature-by-feature) so that the commit message serves as an accurate, self-contained changelog of the staged changes.
+4. Context Integration: IF Sub Repo logs were passed, MUST seamlessly integrate ALL Sub Repo log summaries into the commit body.
+5. State Isolation: MUST ignore unstaged changes AND MUST NOT run `git add` to prevent contamination.
+6. Execution: MUST execute the commit securely (e.g., `git commit -F - <<EOF` or writing to a temporary file) to ensure special characters do not break the terminal command.
+
+## [Validation & Summarize Phase]
+7. Error Handling: MUST verify if the commit command succeeded. IF it fails (e.g., pre-commit hooks, GPG), MUST NOT blindly halt. MUST diagnose the error, preserve the generated message in a temporary file, and pause to ask the user for remediation.
+
+## [Record: Handoff]
 8. Handoff: MUST record the successful commit log summary and return control with updated state to the calling workflow.

package/git-commit/guides/LANGUAGE_DETECTION.md

@@ -1,16 +1,16 @@
-# Language Detection Workflow
-
-**[State Checkpoint]**
-- MUST verify terminal access to the target repository.
-
-## [Discovery Phase]
-1. Memory Check: MUST read `/memories/git-commit-prefs.md` for a cached target language.
-
-## [Evaluation Phase]
-2. Sampling: IF memory cache is missing, MUST run `git log -n 5` securely to sample recent commit languages.
-3. Language Determination:
-   - IF a non-English language is detected dominantly in recent commits, MUST update `/memories/git-commit-prefs.md` with this language.
-   - OTHERWISE, MUST default to English.
-
-## [Record: Handoff]
-4. Handoff: MUST record the determined target language into the state context and return control to the Commit Generation workflow.
+# Language Detection Workflow
+
+**[State Checkpoint]**
+- MUST verify terminal access to the target repository.
+
+## [Discovery Phase]
+1. Memory Check: MUST read the resolved Harness memory file `git-commit-prefs.md` for a cached target language. Prefer an existing `MEMORY.md`/`RULES.md`; otherwise use `.github/harness-everything/memories/git-commit-prefs.md`.
+
+## [Evaluation Phase]
+2. Sampling: IF memory cache is missing, MUST run `git log -n 5` securely to sample recent commit languages.
+3. Language Determination:
+   - IF a non-English language is detected dominantly in recent commits, MUST update the resolved Harness memory file with this language.
+   - OTHERWISE, MUST default to English.
+
+## [Record: Handoff]
+4. Handoff: MUST record the determined target language into the state context and return control to the Commit Generation workflow.

package/git-commit/guides/MAIN_REPO.md

@@ -1,15 +1,15 @@
-# Main Repo Processing Workflow
-
-**[State Checkpoint]**
-- MUST verify terminal is located at the Main Repo root.
-- MUST acknowledge and retrieve any completed Sub Repo updates passed down from the previous phase.
-
-## [Elimination Phase]
-1. Diff Analysis: MUST analyze `git diff --cached` securely to identify staged changes (including Sub Repo pointer updates).
-2. Validation: IF no staged changes exist, MUST declare success and terminate workflow without further action.
-
-## [Summarize Phase]
-3. Context Gathering: IF Sub Repo pointer updates exist, MUST extract their commit logs (e.g., via `git log --oneline <old>..<new>`) to serve as context for the Main Repo commit.
-
-## [Action Phase]
+# Main Repo Processing Workflow
+
+**[State Checkpoint]**
+- MUST verify terminal is located at the Main Repo root.
+- MUST acknowledge and retrieve any completed Sub Repo updates passed down from the previous phase.
+
+## [Elimination Phase]
+1. Diff Analysis: MUST analyze `git diff --cached` securely to identify staged changes (including Sub Repo pointer updates).
+2. Validation: IF no staged changes exist, MUST declare success and terminate workflow without further action.
+
+## [Summarize Phase]
+3. Context Gathering: IF Sub Repo pointer updates exist, MUST extract their commit logs (e.g., via `git log --oneline <old>..<new>`) to serve as context for the Main Repo commit.
+
+## [Action Phase]
 4. Commit Generation: MUST explicitly pass the verified diff and extracted Sub Repo logs as context, then execute `COMMIT_GENERATION.md`.

package/git-commit/guides/SUBMODULES.md

@@ -1,27 +1,27 @@
-# Submodule Processing Workflow
-
-**[State Checkpoint]**
-- MUST verify the Main Repo absolute path transferred from the previous step.
-- MUST ensure terminal is located at the Main Repo root BEFORE beginning discovery.
-
-## [Discovery Phase]
-1. Deep Discovery: MUST run `git submodule status --recursive` to find all Sub Repos.
-
-## [Elimination Phase]
-2. Evaluation: For EACH Sub Repo, MUST run `git diff --cached` securely to check for staged changes. IF NO staged changes exist, MUST eliminate from target list.
-
-## [Execution Phase]
-3. Generation: For Sub Repos WITH staged changes, MUST execute `COMMIT_GENERATION.md`.
-4. Validation: MUST verify generation success. IF ANY Sub Repo has remaining staged changes, MUST diagnose failure and halt.
-
-## [Indexing Phase]
-5. Preference Check: MUST read `/memories/git-commit-prefs.md` for `auto_stage_submodules` setting.
-6. Execution:
-   - IF `auto_stage_submodules=true`: MUST run `git add <path>` in the Main Repo for all updated Sub Repos.
-   - IF missing: MUST prompt user exactly: "[1] Yes, [2] No, [3] Yes & Always allow".
-   - IF user selects [3]: MUST write `auto_stage_submodules=true` to `/memories/git-commit-prefs.md` AND run `git add <path>`.
-   - IF user selects [1]: MUST run `git add <path>` in the Main Repo.
-   - IF user selects [2]: MUST NOT run `git add`.
-
-## [State Handoff]
-7. Handoff: MUST summarize completed Sub Repo updates (including paths and logs) and explicitly carry them over when returning control to `SKILL.md`.
+# Submodule Processing Workflow
+
+**[State Checkpoint]**
+- MUST verify the Main Repo absolute path transferred from the previous step.
+- MUST ensure terminal is located at the Main Repo root BEFORE beginning discovery.
+
+## [Discovery Phase]
+1. Deep Discovery: MUST run `git submodule status --recursive` to find all Sub Repos.
+
+## [Elimination Phase]
+2. Evaluation: For EACH Sub Repo, MUST run `git diff --cached` securely to check for staged changes. IF NO staged changes exist, MUST eliminate from target list.
+
+## [Execution Phase]
+3. Generation: For Sub Repos WITH staged changes, MUST execute `COMMIT_GENERATION.md`.
+4. Validation: MUST verify generation success. IF ANY Sub Repo has remaining staged changes, MUST diagnose failure and halt.
+
+## [Indexing Phase]
+5. Preference Check: MUST read the resolved Harness memory file `git-commit-prefs.md` for the `auto_stage_submodules` setting. Prefer an existing `MEMORY.md`/`RULES.md`; otherwise use `.github/harness-everything/memories/git-commit-prefs.md`.
+6. Execution:
+   - IF `auto_stage_submodules=true`: MUST run `git add <path>` in the Main Repo for all updated Sub Repos.
+   - IF missing: MUST prompt user exactly: "[1] Yes, [2] No, [3] Yes & Always allow".
+   - IF user selects [3]: MUST write `auto_stage_submodules=true` to the resolved Harness memory file AND run `git add <path>`.
+   - IF user selects [1]: MUST run `git add <path>` in the Main Repo.
+   - IF user selects [2]: MUST NOT run `git add`.
+
+## [State Handoff]
+7. Handoff: MUST summarize completed Sub Repo updates (including paths and logs) and explicitly carry them over when returning control to `SKILL.md`.

package/git-commit/references/commit-flow.md

@@ -0,0 +1,30 @@
+# Git Commit — Decision Matrix
+
+Details moved from SKILL.md. Read when you need the full commit execution flow.
+
+## Process & Commit Execution Flow
+
+```mermaid
+flowchart TD
+    Start[Trigger: Commit Request / Task Complete] --> CheckGit{1. Is Git Repo Initialized?}
+    
+    CheckGit -- No --> OfferInit[Prompt User: Run git init or Skip Commit]
+    CheckGit -- Yes --> CheckSubmodules{2. Has Submodule Changes?}
+    
+    CheckSubmodules -- Yes --> CommitSubmodules["Commit Submodules First (Bottom-Up)<br>Consult git-commit/guides/SUBMODULES.md"] --> CheckStatus
+    CheckSubmodules -- No --> CheckStatus[3. Run git status & git diff --cached]
+    
+    CheckStatus --> StagedCheck{4. Are Files Staged?}
+    
+    StagedCheck -- No Staged Files --> AskStage[Prompt User / Stage Targeted Files] --> Format
+    StagedCheck -- Files Staged --> Format[5. Format Angular Commit Message]
+    
+    Format --> CheckShell{6. Shell / Multiline Escaping Check}
+    
+    CheckShell -- Simple Single Line --> DirectCommit["Run git commit -m 'type(scope): subject'"]
+    CheckShell -- Multiline / Windows Shell --> TempFileCommit[Write .git-commit-msg.txt -> Run git commit -F -> Cleanup]
+    
+    DirectCommit --> VerifyCommit[Run git log -1 to Verify]
+    TempFileCommit --> VerifyCommit
+    VerifyCommit --> Done[Commit Complete]
+```