goatcode-sh 0.0.1 → 0.1.3

package/src/features/skills/builtin/git-master.ts

@@ -0,0 +1,109 @@
+import type { Skill } from "../skill-loader";
+
+export const gitMasterSkill: Skill = {
+  name: "git-master",
+  description:
+    "MUST USE for any git operations. Atomic commits, branch strategy, rebase safety, and PR readiness workflow.",
+  template: `# Git Master
+
+You are a Git specialist focused on clean history, safe collaboration, and reviewer-friendly pull requests.
+
+## Operating Principles
+
+1. Make atomic commits that can be reverted independently.
+2. Keep branch history readable for reviewers.
+3. Never run destructive git commands unless explicitly asked.
+4. Prefer safe defaults: \`--force-with-lease\` over \`--force\`, never rewrite shared main/master history.
+
+## Commit Strategy
+
+### Before committing
+
+- Inspect status and both staged/unstaged diff.
+- Detect existing commit-message style from recent history.
+- Group changes by concern, not by file extension.
+- Pair implementation and tests in the same commit.
+
+### Atomic grouping rules
+
+- 3+ changed files across unrelated concerns must be split.
+- Different directories generally imply different commits.
+- A commit message should explain intent and impact, not file list.
+
+### Message style
+
+- Follow repository conventions (semantic or plain style based on git log).
+- Keep messages concise and specific.
+- Avoid vague messages like "update" or "fix stuff".
+
+## Branch Naming
+
+Use descriptive branch names:
+
+- \`feat/<short-feature>\`
+- \`fix/<bug-summary>\`
+- \`refactor/<scope>\`
+- \`chore/<task>\`
+
+Examples:
+
+- \`feat/skill-loader-project-overrides\`
+- \`fix/retry-timeout-handling\`
+
+## Rebase and History Cleanup
+
+### Safe rebase policy
+
+- Never rebase main/master directly.
+- Rebase feature branches onto latest base branch before PR.
+- If branch was pushed and rewritten, communicate clearly and use \`--force-with-lease\`.
+
+### Conflict handling
+
+1. Resolve conflicts file-by-file.
+2. Keep intended behavior and tests intact.
+3. Run validation again after conflict resolution.
+
+## Pull Request Workflow
+
+### Pre-PR checklist
+
+- Working tree clean.
+- Typecheck and tests pass.
+- Commits are logically split and ordered.
+- PR diff is scoped and reviewable.
+
+### PR content
+
+- Title: concise summary of user value.
+- Body should include:
+  - Summary
+  - Validation done
+  - Risks / follow-ups
+
+## Safety Rules
+
+- Never commit secrets (\`.env\`, credential files, tokens).
+- Never bypass hooks unless explicitly requested.
+- Never force-push to main/master.
+- Prefer a new commit over amend after hook failure.
+
+## Quick Command Sequence
+
+\`\`\`bash
+git status
+git diff --staged --stat
+git diff --stat
+git log -20 --pretty=format:"%s"
+\`\`\`
+
+Then create focused commits in dependency order and verify with:
+
+\`\`\`bash
+git status
+git log --oneline --decorate -20
+\`\`\`
+
+Apply this workflow for all git operations unless the user gives explicit alternative constraints.
+`,
+};

package/src/features/skills/index.ts

@@ -0,0 +1,97 @@
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { log } from "../../shared/logger";
+import { getDataDir } from "../../shared/data-path";
+import { gitMasterSkill } from "./builtin/git-master";
+import {
+  createProjectSkillLoader,
+  loadProjectSkills,
+  type Skill,
+  type SkillLoader,
+} from "./skill-loader";
+import { mergeSkills } from "./skill-merger";
+import * as skillHandler from "../../tools/skill/handler";
+
+export { gitMasterSkill } from "./builtin/git-master";
+export { createProjectSkillLoader, loadProjectSkills } from "./skill-loader";
+export { mergeSkills } from "./skill-merger";
+export type { Skill, SkillInfo, SkillLoader } from "./skill-loader";
+
+export function getBuiltinSkills(): Skill[] {
+  return [gitMasterSkill];
+}
+
+function skillToMarkdown(skill: Skill): string {
+  return `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n\n${skill.template.trim()}\n`;
+}
+
+export function getBuiltinSkillsDir(): string | null {
+  try {
+    return join(getDataDir(), "goatcode-sh", "skills");
+  } catch (err) {
+    log("[skills] Failed to resolve built-in skills directory", { err });
+    return null;
+  }
+}
+
+export function syncBuiltinSkillFiles(): string | null {
+  const skillsDir = getBuiltinSkillsDir();
+  if (!skillsDir) return null;
+
+  const builtinSkills = getBuiltinSkills();
+  const expected = new Set(builtinSkills.map((skill) => skill.name));
+  let syncFailed = false;
+
+  try {
+    mkdirSync(skillsDir, { recursive: true });
+    for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && !expected.has(entry.name)) {
+        rmSync(join(skillsDir, entry.name), { recursive: true, force: true });
+      }
+    }
+  } catch (err) {
+    syncFailed = true;
+    log("[skills] Failed to reconcile built-in skills directory", { err });
+  }
+
+  for (const skill of builtinSkills) {
+    const skillDir = join(skillsDir, skill.name);
+    const skillFile = join(skillDir, "SKILL.md");
+
+    try {
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(skillFile, skillToMarkdown(skill), "utf8");
+    } catch (err) {
+      syncFailed = true;
+      log(`[skills] Failed to write skill file: ${skillFile}`, { err });
+    }
+  }
+  return syncFailed ? null : skillsDir;
+}
+
+export function createMergedSkillLoader(directory: string): SkillLoader {
+  const projectSkills = loadProjectSkills(directory);
+  const mergedSkills = mergeSkills(getBuiltinSkills(), projectSkills);
+  const byName = new Map(mergedSkills.map((skill) => [skill.name, skill.template]));
+
+  return {
+    load(name: string): string | undefined {
+      return byName.get(name);
+    },
+    list() {
+      return mergedSkills.map((s) => ({ name: s.name, description: s.description }));
+    },
+  };
+}
+
+export function registerProjectSkillLoader(directory: string): void {
+  syncBuiltinSkillFiles();
+
+  if (typeof skillHandler.registerSkillLoader === "function") {
+    const loader = createMergedSkillLoader(directory);
+    skillHandler.registerSkillLoader(loader);
+    return;
+  }
+
+  log("[skills] registerSkillLoader not available in handler module");
+}

package/src/features/skills/skill-loader.ts

@@ -0,0 +1,133 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { log } from "../../shared/logger";
+
+export type Skill = {
+  name: string;
+  description: string;
+  template: string;
+};
+
+export type SkillInfo = {
+  name: string;
+  description: string;
+};
+
+export type SkillLoader = {
+  load(name: string): string | undefined;
+  list(): SkillInfo[];
+};
+
+type ParsedSkillFrontmatter = {
+  name?: string;
+  description?: string;
+  body: string;
+};
+
+const SKILLS_RELATIVE_DIR = ".opencode/skills";
+
+export function parseSkillMarkdown(markdown: string): ParsedSkillFrontmatter {
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return { body: normalized.trim() };
+  }
+
+  const closingIndex = normalized.indexOf("\n---\n", 4);
+  if (closingIndex < 0) {
+    return { body: normalized.trim() };
+  }
+
+  const frontmatterBlock = normalized.slice(4, closingIndex);
+  const body = normalized.slice(closingIndex + 5).trim();
+  const parsed: ParsedSkillFrontmatter = { body };
+
+  for (const line of frontmatterBlock.split("\n")) {
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex <= 0) {
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim();
+    const rawValue = line.slice(separatorIndex + 1).trim();
+    const value = stripSurroundingQuotes(rawValue);
+
+    if (key === "name") {
+      parsed.name = value;
+      continue;
+    }
+
+    if (key === "description") {
+      parsed.description = value;
+    }
+  }
+
+  return parsed;
+}
+
+export function loadProjectSkills(directory: string): Skill[] {
+  const skillsDir = join(directory, SKILLS_RELATIVE_DIR);
+  if (!existsSync(skillsDir)) {
+    return [];
+  }
+
+  const files = readdirSync(skillsDir).filter((entry) => entry.endsWith(".md"));
+  const skills: Skill[] = [];
+
+  for (const fileName of files) {
+    const filePath = join(skillsDir, fileName);
+
+    try {
+      const content = readFileSync(filePath, "utf8");
+      const parsed = parseSkillMarkdown(content);
+      const fallbackName = basename(fileName, ".md");
+      const name = parsed.name?.trim() || fallbackName;
+      const description = parsed.description?.trim() || "";
+      const template = parsed.body.trim();
+
+      if (!name || !template) {
+        log("[skills] skipped invalid project skill", {
+          filePath,
+          name,
+          hasTemplate: template.length > 0,
+        });
+        continue;
+      }
+
+      skills.push({ name, description, template });
+    } catch (error) {
+      log("[skills] failed to load project skill file", { filePath, error });
+    }
+  }
+
+  return skills;
+}
+
+export function createProjectSkillLoader(directory: string): SkillLoader {
+  const skills = loadProjectSkills(directory);
+  const byName = new Map(skills.map((skill) => [skill.name, skill.template]));
+
+  return {
+    load(name: string): string | undefined {
+      return byName.get(name);
+    },
+    list(): SkillInfo[] {
+      return skills.map((s) => ({ name: s.name, description: s.description }));
+    },
+  };
+}
+
+function stripSurroundingQuotes(value: string): string {
+  if (value.length < 2) {
+    return value;
+  }
+
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}

package/src/features/skills/skill-merger.ts

@@ -0,0 +1,15 @@
+import type { Skill } from "./skill-loader";
+
+export function mergeSkills(builtinSkills: Skill[], userSkills: Skill[]): Skill[] {
+  const merged = new Map<string, Skill>();
+
+  for (const builtinSkill of builtinSkills) {
+    merged.set(builtinSkill.name, builtinSkill);
+  }
+
+  for (const userSkill of userSkills) {
+    merged.set(userSkill.name, userSkill);
+  }
+
+  return Array.from(merged.values());
+}

package/src/features/skills/skills.test.ts

@@ -0,0 +1,120 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createMergedSkillLoader,
+  gitMasterSkill,
+  loadProjectSkills,
+  mergeSkills,
+  registerProjectSkillLoader,
+} from "./index";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+  for (const tempDirectory of tempDirectories.splice(0)) {
+    rmSync(tempDirectory, { recursive: true, force: true });
+  }
+});
+
+describe("#given builtin git-master skill", () => {
+  describe("#when reading its metadata", () => {
+    it("#then it has name, description, and non-empty template", () => {
+      expect(gitMasterSkill.name).toBe("git-master");
+      expect(gitMasterSkill.description.length).toBeGreaterThan(0);
+      expect(gitMasterSkill.template.length).toBeGreaterThan(0);
+    });
+  });
+});
+
+describe("#given project skills in .opencode/skills", () => {
+  describe("#when loading markdown files", () => {
+    it("#then frontmatter + body are parsed into skills", () => {
+      const projectDirectory = createTempProjectDirectory();
+      writeProjectSkill(
+        projectDirectory,
+        "release-checklist.md",
+        `---
+name: release-checklist
+description: release readiness checks
+---
+Validate release notes and run smoke tests.
+`,
+      );
+
+      const loaded = loadProjectSkills(projectDirectory);
+
+      expect(loaded).toHaveLength(1);
+      expect(loaded[0]).toEqual({
+        name: "release-checklist",
+        description: "release readiness checks",
+        template: "Validate release notes and run smoke tests.",
+      });
+    });
+  });
+});
+
+describe("#given builtin and user skills with same name", () => {
+  describe("#when merging skills", () => {
+    it("#then user skill overrides builtin by name", () => {
+      const merged = mergeSkills(
+        [{ name: "git-master", description: "builtin", template: "builtin template" }],
+        [{ name: "git-master", description: "user", template: "user template" }],
+      );
+
+      expect(merged).toHaveLength(1);
+      expect(merged[0]).toEqual({
+        name: "git-master",
+        description: "user",
+        template: "user template",
+      });
+    });
+  });
+});
+
+describe("#given a user override file for git-master", () => {
+  describe("#when creating merged skill loader", () => {
+    it("#then load('git-master') returns user template", () => {
+      const projectDirectory = createTempProjectDirectory();
+      writeProjectSkill(
+        projectDirectory,
+        "git-master.md",
+        `---
+name: git-master
+description: custom project git policy
+---
+Use custom git policy for this repository.
+`,
+      );
+
+      const loader = createMergedSkillLoader(projectDirectory);
+
+      expect(loader.load("git-master")).toBe("Use custom git policy for this repository.");
+    });
+  });
+});
+
+describe("#given registerProjectSkillLoader", () => {
+  describe("#when skillHandler.registerSkillLoader is not available", () => {
+    it("#then logs that registration is unavailable without throwing", () => {
+      //#given
+      const projectDirectory = createTempProjectDirectory();
+
+      //#when / #then — should not throw
+      expect(() => registerProjectSkillLoader(projectDirectory)).not.toThrow();
+    });
+  });
+});
+
+function createTempProjectDirectory(): string {
+  const directory = mkdtempSync(join(tmpdir(), "goatcode-skills-"));
+  tempDirectories.push(directory);
+  return directory;
+}
+
+function writeProjectSkill(projectDirectory: string, fileName: string, contents: string): void {
+  const skillDirectory = join(projectDirectory, ".opencode", "skills");
+  mkdirSync(skillDirectory, { recursive: true });
+  writeFileSync(join(skillDirectory, fileName), contents, "utf8");
+}

package/src/features/slash-commands/command-registry.ts

@@ -0,0 +1,36 @@
+import { log } from "../../shared/logger";
+import type { SlashCommand } from "./types";
+import { loopCommand } from "./commands/loop";
+import { cancelLoopCommand } from "./commands/cancel-loop";
+import { startWorkCommand } from "./commands/start-work";
+import { stopContinuationCommand } from "./commands/stop-continuation";
+import { handoffCommand } from "./commands/handoff";
+import { initDeepCommand } from "./commands/init-deep";
+
+const COMMANDS: SlashCommand[] = [
+  loopCommand,
+  cancelLoopCommand,
+  startWorkCommand,
+  stopContinuationCommand,
+  handoffCommand,
+  initDeepCommand,
+];
+
+const COMMAND_MAP: Map<string, SlashCommand> = new Map();
+for (const cmd of COMMANDS) {
+  if (COMMAND_MAP.has(cmd.name)) {
+    throw new Error(`Duplicate slash command name detected: ${cmd.name}`);
+  }
+  COMMAND_MAP.set(cmd.name, cmd);
+}
+
+export function getCommand(name: string): SlashCommand | undefined {
+  const command = COMMAND_MAP.get(name);
+  log("slash-commands: getCommand", { name, found: command !== undefined });
+  return command;
+}
+
+export function getAllCommands(): SlashCommand[] {
+  log("slash-commands: getAllCommands", { count: COMMANDS.length });
+  return [...COMMANDS];
+}

package/src/features/slash-commands/commands/cancel-loop.ts

@@ -0,0 +1,17 @@
+import type { SlashCommand } from "../types";
+
+export const cancelLoopCommand: SlashCommand = {
+  name: "cancel-loop",
+  description: "Cancel active loop and clear persisted loop state",
+  template: `<command-instruction>
+Cancel the currently active unified loop.
+
+This will:
+1. Stop the loop from continuing
+2. Clear in-memory loop state for the session
+3. Remove only this session's loop entry from .sisyphus/loop-state.json (do not delete other sessions)
+4. Allow the session to end normally
+
+Check if a loop is active, cancel it, and inform the user of the result.
+</command-instruction>`,
+};

package/src/features/slash-commands/commands/handoff.ts

@@ -0,0 +1,59 @@
+import type { SlashCommand } from "../types";
+
+export const handoffCommand: SlashCommand = {
+  name: "handoff",
+  description: "Create a detailed context summary for continuing work in a new session",
+  template: `<command-instruction>
+# Handoff Command
+
+## Purpose
+
+Use /handoff when:
+- The current session context is getting too long and quality is degrading
+- You want to start fresh while preserving essential context from this session
+- The context window is approaching capacity
+
+This creates a detailed context summary that can be used to continue work in a new session.
+
+## PHASE 1: GATHER PROGRAMMATIC CONTEXT
+
+Execute these tools to gather concrete data:
+
+1. session_read({ session_id: "$SESSION_ID" }) - full session history
+2. todoread() - current task progress
+3. Bash({ command: "git diff --stat HEAD~10..HEAD" }) - recent file changes
+4. Bash({ command: "git status --porcelain" }) - uncommitted changes
+
+## PHASE 2: EXTRACT CONTEXT
+
+Write the context summary from first person perspective ("I did...", "I told you...").
+
+Focus on:
+- Capabilities and behavior, not file-by-file implementation details
+- What matters for continuing the work
+- USER REQUESTS (AS-IS) must be verbatim (do not paraphrase)
+- EXPLICIT CONSTRAINTS must be verbatim only (do not invent)
+
+## PHASE 3: FORMAT OUTPUT
+
+Generate a handoff summary using the HANDOFF CONTEXT format with sections:
+USER REQUESTS (AS-IS), GOAL, WORK COMPLETED, CURRENT STATE, PENDING TASKS,
+KEY FILES, IMPORTANT DECISIONS, EXPLICIT CONSTRAINTS, CONTEXT FOR CONTINUATION.
+
+## IMPORTANT CONSTRAINTS
+
+- DO NOT attempt to programmatically create new sessions
+- DO provide a self-contained summary that works without access to this session
+- DO NOT include sensitive information (API keys, credentials, secrets)
+- DO NOT exceed 10 files in the KEY FILES section
+</command-instruction>
+
+<session-context>
+Session ID: $SESSION_ID
+Timestamp: $TIMESTAMP
+</session-context>
+
+<user-request>
+$ARGUMENTS
+</user-request>`,
+};

package/src/features/slash-commands/commands/init-deep.ts

@@ -0,0 +1,40 @@
+import type { SlashCommand } from "../types";
+
+export const initDeepCommand: SlashCommand = {
+  name: "init-deep",
+  description: "Initialize hierarchical AGENTS.md knowledge base",
+  template: `<command-instruction>
+# /init-deep
+
+Generate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.
+
+## Usage
+
+\`\`\`
+/init-deep                      # Update mode: modify existing + create new where warranted
+/init-deep --create-new         # Read existing -> remove all -> regenerate from scratch
+/init-deep --max-depth=2        # Limit directory depth (default: 3)
+\`\`\`
+
+## Workflow
+
+1. **Discovery + Analysis** (concurrent)
+   - Fire background explore agents immediately
+   - Main session: bash structure + LSP codemap + read existing AGENTS.md
+2. **Score & Decide** - Determine AGENTS.md locations from merged findings
+3. **Generate** - Root first, then subdirs in parallel
+4. **Review** - Deduplicate, trim, validate
+
+## Critical Rules
+
+- TodoWrite ALL phases. Mark in_progress -> completed in real-time.
+- Root AGENTS.md is ALWAYS created
+- Child AGENTS.md never repeats parent content
+- Remove generic advice that applies to ALL projects
+- Telegraphic style: dense, no filler
+</command-instruction>
+
+<user-request>
+$ARGUMENTS
+</user-request>`,
+};

package/src/features/slash-commands/commands/loop.ts

@@ -0,0 +1,39 @@
+import type { SlashCommand } from "../types";
+
+export const loopCommand: SlashCommand = {
+  name: "loop",
+  description: "Start unified continuation loop until completion",
+  template: `<command-instruction>
+You are starting a unified LOOP that can run in memory or with disk persistence.
+
+## How LOOP Works
+
+1. You will work on the task continuously
+2. When fully complete, output: \`<promise>{{COMPLETION_PROMISE}}</promise>\`
+3. If the promise is not emitted, the loop injects a continuation prompt automatically
+
+## Options
+
+- \`--persist\`: use disk-backed state in \`.sisyphus/loop-state.json\` (resumable)
+- without \`--persist\`: in-memory loop state (default)
+- \`--max-iterations=N\`: set an explicit iteration limit
+
+Default completion promise is "DONE".
+Default max iterations is 100 for in-memory loops and 1000 for persisted loops.
+
+## Exit Conditions
+
+1. **Completion**: You emit the completion promise tag
+2. **Max Iterations**: Loop stops at configured limit
+3. **Cancel**: User runs \`/cancel-loop\`
+
+## Your Task
+
+Parse the arguments below and begin working on the task. The format is:
+\`"task description" [--completion-promise=TEXT] [--max-iterations=N] [--persist] [--strategy=reset|continue]\`
+</command-instruction>
+
+<user-task>
+$ARGUMENTS
+</user-task>`,
+};