harness-everything 0.2.1 → 0.3.6

package/fable-mode/references/execution-phases.md

@@ -0,0 +1,37 @@
+# Fable Mode — Execution Phases
+
+```mermaid
+flowchart TD
+  Start[Qualifying Tier 3 task] --> Discover[Discover sources, runtime, and authorized scope]
+  Discover --> Plan[Write stage map and pass conditions]
+  Plan --> Select[Resolve requested model and write audit record]
+  Select --> Delegate[Delegate to named agent or visible inline fallback]
+  Delegate --> Contract[Write stage contract]
+  Contract --> Verify[Run the named failable check]
+  Verify --> Review[Cold-review high-stakes deliverables]
+  Review --> Done[Record result or escalate blocker]
+```
+
+## Discovery and planning
+
+Read the relevant files and sources before producing an artifact. Lock the
+authorized write scope in the handoff. Number the stages, assign one artifact
+and one pass condition to each, and allow no more than two full replans.
+
+## Delegation
+
+Use `fable-orchestrator` for Opus macro work, `fable-worker-sonnet` for
+reasoning and synthesis, and `fable-worker-haiku` for mechanical work. Brief
+each worker with its exact output path, context, audit record, and check.
+Workers do not spawn workers. If the named agent is unavailable, choose the
+explicit inline fallback or stop and escalate; do not silently change models.
+
+## Verification and handoff
+
+Before each spot-check, create `.claude/harness-everything/state/contracts/<stage>.json`
+using `CONTRACT-FORMAT.md`, then run the exact command in that contract. A
+stage is not complete until the command passes and the audit record contains
+the verifier result. Use `fable-verifier` with only the spec and artifact for
+high-stakes or unsupervised delivery. Review scope-guard output before merging.
+
+When macro scaffolding ends, transition to `tdd` for focused implementation.

package/fable-mode/references/model-matrix.md

@@ -0,0 +1,39 @@
+# Fable model matrix and execution audit
+
+Issue #27 defines three explicit execution modes. The mode selector is the
+machine-readable gate; this document is the human-facing contract.
+
+| Mode | Use for | Named agent |
+|---|---|---|
+| Haiku | Bulk mechanical work and format conversion | `fable-worker-haiku` |
+| Sonnet | Non-trivial implementation, research synthesis, bounded reasoning | `fable-worker-sonnet` |
+| Opus | Macro orchestration, cross-stage synthesis, high-stakes architecture and final decisions | `fable-orchestrator` |
+
+Use the explicit entrypoints `fable-haiku`, `fable-sonnet`, and `fable-opus`.
+The accepted input `sonnect` normalizes to Sonnet. A normal Tier 2 prompt does
+not select a fable model.
+
+## Deterministic selection
+
+Before each stage, run `fable-mode/scripts/model-selector.js` with the requested
+mode, the runtime's available modes, the host model, and the stage contract:
+
+```text
+node fable-mode/scripts/model-selector.js --requested opus --available opus,sonnet,haiku --available-agents fable-orchestrator,fable-worker-sonnet,fable-worker-haiku --fallback stop --host-model opus --stage-brief "Synthesize the architecture" --pass-condition "ADR and dependency map exist" --verification-command "npm test" --verifier-result pending
+```
+
+The JSON result always records `requestedModel`, `effectiveModel`,
+`fallbackReason`, `stageBrief`, `passCondition`, `verificationCommand`, and
+`verifierResult`, plus available agents, status, agent, and escalation state. The
+CLI appends the same record as one JSON line to
+`.claude/harness-everything/state/fable-mode/audit.jsonl` (or the path supplied by
+`--audit-file`).
+
+If the requested model is unavailable, `--fallback inline` records the declared
+host model and a visible reason. `--fallback stop` emits `status: blocked`, a
+null effective model, and exit code 2. Neither path silently downgrades.
+
+The orchestrator still owns scope lock, at most two full replans, stage
+contracts, worker non-recursion, cold verification, and escalation. The native
+host TODO tracker or a Markdown checklist records stage progress; no CLI TODO
+state machine is part of this contract.

package/fable-mode/scripts/model-selector.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const MATRIX_PATH = path.join(__dirname, '..', 'model-matrix.json');
+const REQUIRED = ['stageBrief', 'passCondition', 'verificationCommand', 'verifierResult'];
+const VALID_VERIFIER_RESULTS = new Set(['pending', 'pass', 'fail', 'not-run', 'blocked']);
+
+function loadMatrix() {
+  return JSON.parse(fs.readFileSync(MATRIX_PATH, 'utf8'));
+}
+
+function normalizeModel(value, matrix) {
+  const input = String(value || '').trim().toLowerCase();
+  for (const [model, definition] of Object.entries(matrix.modes)) {
+    if (definition.aliases.includes(input)) return model;
+  }
+  return null;
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--help' || token === '-h') return { help: true };
+    if (!token.startsWith('--')) throw new Error(`unknown argument: ${token}`);
+    const key = token.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    const value = argv[i + 1];
+    if (typeof value === 'undefined' || value.startsWith('--')) throw new Error(`missing value for --${key}`);
+    args[key] = value;
+    i += 1;
+  }
+  return args;
+}
+
+function resolveMode(input, matrix = loadMatrix()) {
+  const requestedModel = normalizeModel(input.requested, matrix);
+  if (!requestedModel) throw new Error('requested model must be one of haiku, sonnet, sonnect, or opus');
+
+  const availableModels = String(input.available || '')
+    .split(/[\s,]+/)
+    .map(model => normalizeModel(model, matrix))
+    .filter(Boolean);
+  const availableAgents = String(input.availableAgents || '')
+    .split(/[\s,]+/)
+    .map(agent => agent.trim())
+    .filter(Boolean);
+  const fallback = input.fallback || 'stop';
+  if (!Object.prototype.hasOwnProperty.call(matrix.fallbacks, fallback)) {
+    throw new Error('fallback must be inline or stop');
+  }
+
+  for (const field of REQUIRED) {
+    if (!String(input[field] || '').trim()) throw new Error(`${field} is required for an auditable stage`);
+  }
+  if (!VALID_VERIFIER_RESULTS.has(input.verifierResult)) {
+    throw new Error(`verifierResult must be one of ${[...VALID_VERIFIER_RESULTS].join(', ')}`);
+  }
+
+  const requestedAgent = matrix.modes[requestedModel].agent;
+  const modelAvailable = availableModels.includes(requestedModel);
+  const agentAvailable = availableAgents.includes(requestedAgent);
+  const selected = modelAvailable && agentAvailable;
+  const hostModel = String(input.hostModel || 'current-host').trim();
+  const fallbackDefinition = matrix.fallbacks[fallback];
+  const status = selected ? 'selected' : fallbackDefinition.status;
+  const effectiveModel = selected
+    ? requestedModel
+    : fallback === 'inline'
+      ? hostModel
+      : fallbackDefinition.effectiveModel;
+  const missing = [];
+  if (!modelAvailable) missing.push(`${requestedModel} is not in availableModels`);
+  if (!agentAvailable) missing.push(`${requestedAgent} is not in availableAgents`);
+  const fallbackReason = selected
+    ? 'none'
+    : `${fallbackDefinition.reason}: ${missing.join('; ')}`;
+
+  return {
+    schemaVersion: matrix.schemaVersion,
+    status,
+    requestedModel,
+    requestedInput: String(input.requested).trim(),
+    effectiveModel,
+    availableModels: [...new Set(availableModels)],
+    availableAgents: [...new Set(availableAgents)],
+    fallbackPolicy: fallback,
+    fallbackReason,
+    agent: selected ? requestedAgent : null,
+    modelRole: matrix.modes[requestedModel].role,
+    stageBrief: String(input.stageBrief).trim(),
+    passCondition: String(input.passCondition).trim(),
+    verificationCommand: String(input.verificationCommand).trim(),
+    verifierResult: input.verifierResult,
+    escalationRequired: status === 'blocked'
+  };
+}
+
+function printHelp() {
+  console.log('Usage: node fable-mode/scripts/model-selector.js --requested <haiku|sonnet|sonnect|opus> --available <models> --available-agents <agent names> --stage-brief <text> --pass-condition <text> --verification-command <command> --verifier-result <pending|pass|fail|not-run|blocked> [--fallback <inline|stop>] [--host-model <model>] [--audit-file <path>]');
+}
+
+function appendAuditRecord(record, auditFile) {
+  const target = auditFile || process.env.FABLE_AUDIT_FILE || path.join(process.cwd(), '.claude', 'harness-everything', 'state', 'fable-mode', 'audit.jsonl');
+  fs.mkdirSync(path.dirname(path.resolve(target)), { recursive: true });
+  fs.appendFileSync(target, `${JSON.stringify(record)}\n`, 'utf8');
+}
+
+function main(argv = process.argv.slice(2)) {
+  try {
+    const input = parseArgs(argv);
+    if (input.help) {
+      printHelp();
+      return 0;
+    }
+    const record = resolveMode(input);
+    appendAuditRecord(record, input.auditFile);
+    console.log(JSON.stringify(record, null, 2));
+    return record.status === 'blocked' ? 2 : 0;
+  } catch (error) {
+    console.error(`[fable-mode/model-selector] ${error.message}`);
+    return 2;
+  }
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = { loadMatrix, normalizeModel, parseArgs, resolveMode, main };

package/find-skills/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: find-skills
+description: Search the agent-skills ecosystem (skills.sh / npx skills) when no installed skill fits; verify quality, apply ephemerally via temp cache by default, and install permanently via npx skills add only with explicit user approval 
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.4
+---
+
+# Find Skills (External Skill Discovery)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Request to find an external skill. |
+| **Expected Output** | Skill pointer, applied skill, or fallback. |
+| **State Mutations** | Temp cache (default); native install opt-in. |
+| **Enforcement Gate** | Local first; explicit approval required before applying third-party code; graceful npx failure. |
+
+## Workflow
+
+0. Check local coverage (router registry, `generated[]`) before live installs:
+```bash
+npx skills list --json          # project scope
+npx skills list -g --json       # global scope
+```
+1. Identify domain/task, check [skills.sh](https://skills.sh/), then search `npx skills find [query] [--owner <owner>]`.
+2. Verify: prefer 1K+ installs, official sources; read the unaudited SKILL.md.
+3. Present name/source/count; NEVER fetch/apply without explicit approval.
+4. Apply ephemerally (default, zero footprint):
+```bash
+node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>
+```
+Apply the output; OS-temp cache (6h); nothing written to repo or manifest.json.
+5. Permanent install ONLY when the user says they will reuse it: `npx skills add <owner/repo[@skill]> --agent <agent> [-g] -y`
+6. Nothing exists? Help directly; suggest `npx skills init <name>` if recurring.
+
+Deep dive: references/discovery-flow.md
+
+## USE FOR:
+- finding an external skill when none installed fits
+- vetting third-party skills before applying them
+- ephemeral skill use without permanent installs
+
+## DO NOT USE FOR:
+- authoring skills (`skill-creator`)
+- installing anything without explicit user approval

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) — read that output and apply it to the current task. 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,106 @@
+#!/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');
+
+const CACHE_DIR = path.join(os.tmpdir(), 'harness-find-skills-cache');
+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,55 +1,45 @@
----
-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
----
-
-# Git Commit (Angular Style)
-
-## 📋 Skill Contract
-
-| 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
+---
+name: git-commit
+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.3.4
+---
+
+# Git Commit (Angular Style)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **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 `git-commit/guides/SUBMODULES.md`.
+2. `git diff --cached`; nothing staged → prompt user / stage targeted files.
+3. Format `<type>(<scope>): <subject>` per `git-commit/guides/ANGULAR_STYLE.md`. Multiline/Windows → `.git-commit-msg.txt` + `git commit -F`, clean up.
+4. `git commit -m "..."`, verify with `git log -1`.
+
+Deep guides:
+- `git-commit/guides/ANGULAR_STYLE.md` — Conventional structure, scopes
+- `git-commit/guides/COMMIT_GENERATION.md` — Patterns, diff analysis
+- `git-commit/guides/LANGUAGE_DETECTION.md` — Subject language rules
+- `git-commit/guides/MAIN_REPO.md` — Monorepo commits
+- `git-commit/guides/SUBMODULES.md` — Submodules, nested repos
+
+## 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: references/commit-flow.md