plugsuits 1.0.0

package/src/skills/git-workflow.md

@@ -0,0 +1,405 @@
+---
+name: Git Workflow
+description: Complete git workflow including branch management, commits, and GitHub PR creation using gh CLI. Use when user requests to create PR, push changes, commit code, or perform git operations with GitHub.
+triggers:
+  - create pr
+  - make pull request
+  - commit and push
+  - gh pr create
+  - push changes
+  - create pull request
+  - 올려줘
+  - PR 만들어줘
+  - 커밋해줘
+  - 푸시해줘
+version: 1.0.0
+---
+
+# Git Workflow Skill
+
+## Overview
+
+This skill provides comprehensive guidance for git operations, branch management, commit creation, and **GitHub Pull Request creation using GitHub CLI**.
+
+## Core Responsibilities
+
+1. **Branch Management** - Create, switch, and manage feature branches
+2. **Commit Operations** - Stage changes and create meaningful commits
+3. **Push Operations** - Push branches to remote repository
+4. **Pull Request Creation** - Create PRs using GitHub CLI (`gh pr create`)
+5. **Workflow Completion** - Ensure full cycle from changes to PR
+
+## Available Tools
+
+- `shell_execute` - Execute git and gh CLI commands
+- `read_file` - Read git config, commit messages, PR templates
+- `grep_files` - Search for patterns in git history
+- `glob_files` - Find git-related files
+
+## Git Command Reference
+
+### Safe Commands (Always OK)
+```bash
+git status                    # Check working tree status
+git branch                    # List branches
+git log                       # View commit history
+git diff                      # Show changes
+git show                      # Show commit details
+gh pr list                    # List pull requests
+gh pr view                    # View PR details
+```
+
+### Careful Commands (Require Verification)
+```bash
+git checkout -b <branch>      # Create new branch
+git add .                     # Stage all changes
+git commit -m "message"       # Create commit
+git push -u origin <branch>   # Push new branch
+gh pr create                  # Create pull request
+```
+
+### Dangerous Commands (Require Explicit User Confirmation)
+```bash
+git push --force              # Force push (NEVER on main/master)
+git reset --hard              # Discard changes permanently
+git rebase                    # Rewrite history
+git push --delete             # Delete remote branch
+```
+
+## Workflow Patterns
+
+### Standard Feature Workflow
+
+When user requests "create PR" or "make a pull request":
+
+**Step 1: Check Current State**
+```bash
+git status
+git branch
+```
+
+**Step 2: Create Feature Branch (if needed)**
+```bash
+# Branch naming conventions:
+# - feature/description
+# - fix/issue-description
+# - refactor/component-name
+# - docs/topic
+
+git checkout -b feature/descriptive-name
+```
+
+**Step 3: Stage Changes**
+```bash
+git add .
+# Or selectively:
+git add src/specific/file.ts
+```
+
+**Step 4: Create Descriptive Commit**
+```bash
+# Commit message format:
+# <type>: <short description>
+#
+# <detailed explanation if needed>
+#
+# Types: feat, fix, refactor, docs, test, chore
+
+git commit -m "feat: add user authentication system
+
+- Implement JWT token generation
+- Add login/logout endpoints
+- Create auth middleware"
+```
+
+**Step 5: Push to Remote**
+```bash
+git push -u origin feature/descriptive-name
+```
+
+**Step 6: Create Pull Request**
+```bash
+# Basic PR creation:
+gh pr create --base main --head feature/descriptive-name \
+  --title "Add user authentication system" \
+  --body "## Summary
+- Implements JWT-based authentication
+- Adds login/logout endpoints
+- Includes auth middleware
+
+## Testing
+- All tests passing
+- Manual testing completed"
+
+# Interactive PR creation (if user wants to review):
+gh pr create --web
+```
+
+### Quick Commit and PR Workflow
+
+For simple changes where user says "commit and create PR":
+
+```bash
+# All in one flow:
+git add .
+git commit -m "fix: resolve authentication bug"
+git push -u origin fix/auth-bug
+gh pr create --base main --title "Fix authentication bug" --body "Resolves issue with token expiration"
+```
+
+### PR Creation Options
+
+**Option 1: Direct Creation (Recommended)**
+```bash
+gh pr create \
+  --base main \
+  --head feature/branch-name \
+  --title "Clear, descriptive title" \
+  --body "## Summary
+What changed and why
+
+## Changes
+- Bullet point list
+- Of key changes
+
+## Testing
+How it was tested"
+```
+
+**Option 2: Interactive Web UI**
+```bash
+gh pr create --web
+# Opens browser for user to fill in details
+```
+
+**Option 3: Using PR Template**
+```bash
+# If .github/pull_request_template.md exists:
+gh pr create --base main --fill
+# Automatically uses template
+```
+
+### Checking PR Status
+
+After creating PR:
+```bash
+# Get PR URL and status:
+gh pr view
+
+# Check CI status:
+gh pr checks
+
+# List all PRs:
+gh pr list
+```
+
+## Branch Naming Conventions
+
+Follow these patterns:
+- `feature/user-auth` - New features
+- `fix/login-bug` - Bug fixes
+- `refactor/api-client` - Code refactoring
+- `docs/readme-update` - Documentation
+- `test/auth-coverage` - Test additions
+- `chore/deps-update` - Maintenance tasks
+
+## Commit Message Guidelines
+
+### Format
+```
+<type>: <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+- `feat` - New feature
+- `fix` - Bug fix
+- `refactor` - Code restructuring
+- `docs` - Documentation changes
+- `test` - Test additions/changes
+- `chore` - Maintenance tasks
+- `perf` - Performance improvements
+- `style` - Code style changes (formatting)
+
+### Examples
+
+**Good:**
+```
+feat: add GitHub OAuth integration
+
+- Implement OAuth flow
+- Add callback handler
+- Store tokens securely
+
+Closes #123
+```
+
+**Bad:**
+```
+update stuff
+```
+
+## PR Description Template
+
+When creating PR, use this structure:
+
+```markdown
+## Summary
+Brief overview of what changed and why
+
+## Changes
+- Key change 1
+- Key change 2
+- Key change 3
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Manual testing completed
+- [ ] All tests passing
+
+## Related Issues
+Closes #123
+Relates to #456
+```
+
+## Safety Guardrails
+
+### NEVER Do These Without Explicit User Confirmation:
+1. `git push --force` on main/master branch
+2. `git reset --hard` (loses uncommitted changes)
+3. Delete remote branches that others might use
+4. Rebase commits that have been pushed
+5. Amend commits that have been pushed
+
+### ALWAYS Do These:
+1. Check `git status` before committing
+2. Review `git diff` before staging
+3. Use descriptive commit messages
+4. Push to feature branch, not main
+5. Create PR instead of pushing directly to main
+
+## Error Handling
+
+### Common Issues and Solutions
+
+**Issue: "gh: command not found"**
+```bash
+# Solution: Install GitHub CLI
+# macOS:
+brew install gh
+
+# Linux:
+# See: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+
+# Then authenticate:
+gh auth login
+```
+
+**Issue: "failed to push some refs"**
+```bash
+# Solution: Pull latest changes first
+git pull origin main
+# Resolve conflicts if any
+git push
+```
+
+**Issue: "not a git repository"**
+```bash
+# Solution: Initialize git repo
+git init
+git remote add origin <repo-url>
+```
+
+**Issue: "gh: Not authenticated"**
+```bash
+# Solution: Login to GitHub
+gh auth login
+# Follow interactive prompts
+```
+
+## Complete Example Workflow
+
+User says: "이 변경사항들을 PR로 올려줘"
+
+**AI Response:**
+```bash
+# Step 1: Check current state
+git status
+
+# Step 2: Create feature branch (if on main)
+git checkout -b feature/implement-todo-system
+
+# Step 3: Stage all changes
+git add .
+
+# Step 4: Create commit
+git commit -m "feat: implement todo system with auto-resume
+
+- Add todo_write and todo_read tools
+- Implement auto-continuation middleware
+- Update system prompts for autonomous execution
+- Add session-based todo isolation"
+
+# Step 5: Push branch
+git push -u origin feature/implement-todo-system
+
+# Step 6: Create PR
+gh pr create \
+  --base main \
+  --title "Implement todo system with auto-resume functionality" \
+  --body "## Summary
+Adds a comprehensive todo system that enables AI to track and automatically continue incomplete tasks.
+
+## Changes
+- Created todo_write and todo_read tools
+- Built auto-continuation middleware
+- Updated system prompts for autonomous execution
+- Implemented session-based todo isolation
+
+## Testing
+- All unit tests passing (7/7)
+- TypeScript compilation clean
+- Linting passing
+- Manual testing completed in CLI mode"
+
+# Step 7: Report success
+echo "✅ Pull request created successfully!"
+gh pr view --web
+```
+
+## Integration with Other Skills
+
+This skill works with:
+- **Shell Execution** - All git/gh commands use `shell_execute`
+- **File Reading** - Read commit templates, PR templates
+- **Todo System** - Mark "create PR" tasks as complete after success
+
+## Key Principles
+
+1. **Complete the Cycle** - Don't stop at commit; create the PR
+2. **Descriptive Messages** - Commits and PRs should explain WHY, not just WHAT
+3. **Safety First** - Never force push to main, always use feature branches
+4. **User Visibility** - Report each step and final PR URL
+5. **Autonomous Execution** - Don't ask user to run commands; execute them
+
+## When to Use This Skill
+
+Trigger phrases:
+- "create a PR"
+- "make a pull request"
+- "commit and push"
+- "올려줘" / "PR 만들어줘"
+- "push these changes"
+- "create PR from these changes"
+
+## Expected Outcomes
+
+After using this skill:
+- ✅ Changes committed with descriptive message
+- ✅ Branch pushed to remote
+- ✅ Pull request created on GitHub
+- ✅ PR URL provided to user
+- ✅ User can review PR in browser

package/src/tool-fallback-mode.ts

@@ -0,0 +1,34 @@
+export const TOOL_FALLBACK_MODES = [
+  "disable",
+  "morphxml",
+  "hermes",
+  "qwen3coder",
+] as const;
+
+export type ToolFallbackMode = (typeof TOOL_FALLBACK_MODES)[number];
+
+export const DEFAULT_TOOL_FALLBACK_MODE: ToolFallbackMode = "disable";
+export const LEGACY_ENABLED_TOOL_FALLBACK_MODE: ToolFallbackMode = "morphxml";
+
+const isToolFallbackMode = (value: string): value is ToolFallbackMode => {
+  return TOOL_FALLBACK_MODES.includes(value as ToolFallbackMode);
+};
+
+export const parseToolFallbackMode = (
+  rawValue: string
+): ToolFallbackMode | null => {
+  const value = rawValue.toLowerCase();
+  if (isToolFallbackMode(value)) {
+    return value;
+  }
+
+  if (value === "on" || value === "enable" || value === "true") {
+    return LEGACY_ENABLED_TOOL_FALLBACK_MODE;
+  }
+
+  if (value === "off" || value === "false") {
+    return DEFAULT_TOOL_FALLBACK_MODE;
+  }
+
+  return null;
+};

package/src/tools/AGENTS.md

@@ -0,0 +1,44 @@
+# TOOLS SUBSYSTEM KNOWLEDGE BASE
+
+**Generated:** 2026-02-23 14:40 KST
+**Scope:** `src/tools/**`
+
+## OVERVIEW
+`src/tools/` implements all callable tools and maps stable public tool keys to concrete executors.
+
+## STRUCTURE
+```text
+src/tools/
+|- index.ts              # Public tool registry keys
+|- execute/              # Shell execution and process management
+|- explore/              # Read, glob, grep, and safety checks
+|- modify/               # Deterministic file mutation operations
+|  `- AGENTS.md          # High-risk mutation constraints
+`- planning/             # Skill loading and todo state updates
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Add or rename a tool key | `src/tools/index.ts` | Keep key names stable for model/tool contracts |
+| Shell execution semantics | `src/tools/execute/shell-execute.ts` | Timeout, background handling, non-interactive wrapping |
+| File read/search behavior | `src/tools/explore/read-file.ts` | Enforces limits and safe read semantics |
+| Deterministic file editing | `src/tools/modify/edit-file.ts` | Hashline-native edits |
+| Todo persistence semantics | `src/tools/planning/todo-write.ts` | Status accounting and validation |
+| Skill content resolution | `src/tools/planning/load-skill.ts` | Local/project/bundled skill lookup behavior |
+
+## CONVENTIONS
+- `index.ts` is the single source of truth for exported tool key names (`shell_execute`, `read_file`, `edit_file`, etc.).
+- Keep per-tool description files (`<tool-name>.txt`) synchronized with implementation and prompt wiring.
+- Prefer dedicated `explore/modify` tools for file operations; shell is for build/test/git/system operations.
+- `modify/edit-file.ts` is hashline-first: preserve `expected_file_hash` checks and deterministic anchors.
+- New tool behavior must ship with colocated tests under the same subdirectory.
+
+## ANTI-PATTERNS
+- Introducing file reads/writes through shell commands when dedicated tools already exist.
+- Changing tool key strings in `index.ts` without coordinated updates to callers and tests.
+- Bypassing stale-safety checks in edit flows (`expected_file_hash`, anchored operations).
+- Expanding planning behavior without updating validation and summary outputs in tests.
+
+## NOTES
+- `src/tools/modify/AGENTS.md` is the source of truth for hashline/legacy-edit constraints.

package/src/tools/execute/shell-execute.test.ts

@@ -0,0 +1,114 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { executeCommand } from "./shell-execute";
+
+describe("executeCommand", () => {
+  let tempDir: string;
+
+  beforeAll(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "shell-test-"));
+  });
+
+  afterAll(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true });
+    }
+  });
+
+  describe("basic execution", () => {
+    it("executes simple echo command", async () => {
+      const result = await executeCommand('echo "hello world"');
+
+      expect(result.output).toContain("hello world");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("captures multiline output", async () => {
+      const result = await executeCommand("printf 'line1\\nline2\\nline3'");
+
+      expect(result.output).toContain("line1");
+      expect(result.output).toContain("line2");
+      expect(result.output).toContain("line3");
+    });
+
+    it("combines stdout and stderr", async () => {
+      const result = await executeCommand('echo "stdout" && echo "stderr" >&2');
+
+      expect(result.output).toContain("stdout");
+      expect(result.output).toContain("stderr");
+    });
+
+    it("handles empty output", async () => {
+      const result = await executeCommand("true");
+
+      expect(result.output).toBe("");
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("executes command in specified workdir", async () => {
+      const result = await executeCommand("pwd", { workdir: tempDir });
+
+      expect(result.output).toContain("shell-test-");
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  describe("exit code propagation", () => {
+    it("returns non-zero exit code for failed command", async () => {
+      const result = await executeCommand("exit 42");
+
+      expect(result.exitCode).toBe(42);
+    });
+
+    it("returns zero for successful command", async () => {
+      const result = await executeCommand("echo ok");
+
+      expect(result.exitCode).toBe(0);
+    });
+
+    it("returns exit code from last command in chain", async () => {
+      const result = await executeCommand("true && exit 5");
+
+      expect(result.exitCode).toBe(5);
+    });
+  });
+
+  describe("timeout formatting", () => {
+    it("includes [TIMEOUT] prefix when command exceeds timeout", async () => {
+      const result = await executeCommand("sleep 10", { timeoutMs: 200 });
+
+      expect(result.output).toContain("[TIMEOUT]");
+      expect(result.exitCode).toBe(124);
+    }, 5000);
+
+    it("includes timeout duration in timeout message", async () => {
+      const result = await executeCommand("sleep 10", { timeoutMs: 300 });
+
+      expect(result.output).toContain("300ms");
+    }, 5000);
+  });
+
+  describe("background process detection", () => {
+    it("wraps output with background message for commands ending with &", async () => {
+      const result = await executeCommand("sleep 0.1 &");
+
+      expect(result.exitCode).toBe(0);
+      expect(result.output).toContain("[Background process started]");
+    });
+
+    it("does not treat && as background operator", async () => {
+      const result = await executeCommand('echo "first" && echo "second"');
+
+      expect(result.output).toContain("first");
+      expect(result.output).not.toContain("[Background process started]");
+    });
+
+    it("does not treat mid-command & as background", async () => {
+      const result = await executeCommand("sleep 0.1 & wait");
+
+      expect(result.output).not.toContain("[Background process started]");
+    });
+  });
+});

package/src/tools/execute/shell-execute.ts

@@ -0,0 +1,74 @@
+import { tool } from "ai";
+import { z } from "zod";
+import {
+  formatBackgroundMessage,
+  formatTimeoutMessage,
+} from "../utils/execute/format-utils";
+import { executeCommand as pmExecuteCommand } from "../utils/execute/process-manager";
+import SHELL_EXECUTE_DESCRIPTION from "./shell-execute.txt";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+function isBackgroundCommand(command: string): boolean {
+  const trimmed = command.trimEnd();
+  return trimmed.endsWith("&") && !trimmed.endsWith("&&");
+}
+
+export interface ToolOutput {
+  exit_code: number;
+  output: string;
+}
+
+export async function executeCommand(
+  command: string,
+  options: { workdir?: string; timeoutMs?: number } = {}
+): Promise<{ exitCode: number; output: string }> {
+  const { workdir, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+  const result = await pmExecuteCommand(command, { workdir, timeoutMs });
+
+  if (result.timedOut) {
+    return {
+      exitCode: result.exitCode,
+      output: formatTimeoutMessage(timeoutMs, result.output),
+    };
+  }
+
+  if (isBackgroundCommand(command)) {
+    return {
+      exitCode: result.exitCode,
+      output: formatBackgroundMessage(result.output),
+    };
+  }
+
+  return {
+    exitCode: result.exitCode,
+    output: result.output,
+  };
+}
+
+export const shellExecuteTool = tool({
+  description: SHELL_EXECUTE_DESCRIPTION,
+
+  inputSchema: z.object({
+    command: z.string().describe("Shell command to execute"),
+    workdir: z
+      .string()
+      .optional()
+      .describe("Working directory (absolute path)"),
+    timeout_ms: z
+      .number()
+      .optional()
+      .describe("Timeout in milliseconds (default: 120000)"),
+  }),
+
+  execute: async ({ command, workdir, timeout_ms }): Promise<ToolOutput> => {
+    const result = await executeCommand(command, {
+      workdir,
+      timeoutMs: timeout_ms ?? DEFAULT_TIMEOUT_MS,
+    });
+    return {
+      exit_code: result.exitCode,
+      output: result.output,
+    };
+  },
+});

package/src/tools/execute/shell-execute.txt

@@ -0,0 +1,27 @@
+### shell_execute
+**Purpose**: Run shell commands with configurable timeout (default: 120s)
+
+**When to use**:
+- Package management: `npm install`, `pip install`, `cargo build`
+- Version control: `git status`, `git commit`, `git push`
+- Build systems: `make`, `npm run build`, `docker build`
+- Running tests: `npm test`, `pytest`, `cargo test`
+- OS-level only: `chmod`, `ln -s`, `chown`
+
+**Timeout guidance**:
+- Quick commands: default 120s
+- Build/test/install: use larger timeout (`300000`-`600000` ms)
+
+**Non-interactive behavior**:
+- Wrapper applies non-interactive flags/env when possible (`CI=true`, `DEBIAN_FRONTEND=noninteractive`, `GIT_TERMINAL_PROMPT=0`)
+
+**Background commands**:
+- Commands ending with `&` run in background
+- Always verify startup with follow-up checks (`sleep`, health check, logs)
+
+**Notes**:
+- Large outputs are truncated automatically
+- Background commands (`&`) should be verified with follow-up checks
+
+**Do not use shell for file ops**:
+- Use dedicated tools for read/write/edit/delete/search/glob