shoko/kugetsu
1
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Create unified agent skill combining all workflow guidelines #9

New Issue
Closed
opened 2026-03-27 15:50:20 +01:00 by shoko · 0 comments
shoko commented 2026-03-27 15:50:20 +01:00
Owner
Copy Link

Context

Issue #1 (Document Hermes Setup) produced several workflow documents that are currently scattered:

  • docs/SUBAGENT_WORKFLOW.md — Gitea-based subagent communication
  • Branch Hygiene — documented in PR #6 comments
  • Error-Resistant curl Patterns — documented in issue #1 comment #295
  • opencode-worktree skill — git worktree per session
  • docs/hermes-setup.md — Hermes configuration (PR #8)

Problem

Currently, an agent working on a Kugetsu issue needs to:

  1. Read docs/SUBAGENT_WORKFLOW.md for Gitea communication patterns
  2. Remember Branch Hygiene rules from comment threads
  3. Apply curl error patterns from comment #295
  4. Reference opencode-worktree skill separately

This fragmentation leads to inconsistent agent behavior and missed patterns.

Proposed Solution

Create a unified agent skill (skills/agent-protocol/SKILL.md) that combines all agreed-upon workflows into one loadable skill.

Proposed Structure

skills/agent-protocol/
└── SKILL.md   # Single file with all workflow guidelines

Content to Combine

Source Content
Branch Hygiene (comment #285) git checkout -b branch main, contamination detection/fix, --force-with-lease
Error-Resistant curl (comment #295) --max-time 30 --retry 3, response verification via HTTP code, /tmp for files
Git Worktree-per-Issue (comment #303) Each issue = dedicated worktree, agents jump in/out, worktree persists until PR merged
Gitea Communication (PR #6) Issue comment API template, PR creation API template, state machine
opencode-worktree skill Reference or incorporate existing skills/opencode-worktree/

Design Goals

  1. Single Source of Truth — One skill file, complete workflow reference
  2. Kugetsu-Specific — Gitea URLs, token naming, repo paths hardcoded
  3. Error-Resistant by Default — All curl commands include timeouts, retries, verification
  4. Per-Issue Isolation — Git worktree per issue (not per session)
  5. Auto-Loadable — Can be configured in Hermes skills config

Questions to Resolve

  1. Location: skills/agent-protocol/ (new) vs update existing skills/opencode-worktree/?
  2. Auto-load: Should this load automatically via Hermes skills config, or be referenceable on demand?
  3. OpenCode vs Hermes: Is this skill for OpenCode agents, Hermes agents, or both?

References

  • Issue #1: Document Hermes Setup (this builds on)
  • PR #6: Docs: Add subagent workflow documentation (merged)
  • PR #8: docs: add hermes-setup.md (open)
  • Comment #285: Branch Hygiene Workflow
  • Comment #295: Improved Subagent Workflow - Error Reduction Guide
  • Comment #300-303: Git Worktree-per-Issue discussion

Status

  • Analysis: Complete (this issue)
  • Implementation: Pending
## Context Issue #1 (Document Hermes Setup) produced several workflow documents that are currently scattered: - `docs/SUBAGENT_WORKFLOW.md` — Gitea-based subagent communication - Branch Hygiene — documented in PR #6 comments - Error-Resistant curl Patterns — documented in issue #1 comment #295 - `opencode-worktree` skill — git worktree per session - `docs/hermes-setup.md` — Hermes configuration (PR #8) ## Problem Currently, an agent working on a Kugetsu issue needs to: 1. Read `docs/SUBAGENT_WORKFLOW.md` for Gitea communication patterns 2. Remember Branch Hygiene rules from comment threads 3. Apply curl error patterns from comment #295 4. Reference `opencode-worktree` skill separately This fragmentation leads to inconsistent agent behavior and missed patterns. ## Proposed Solution Create a **unified agent skill** (`skills/agent-protocol/SKILL.md`) that combines all agreed-upon workflows into one loadable skill. ### Proposed Structure ``` skills/agent-protocol/ └── SKILL.md # Single file with all workflow guidelines ``` ### Content to Combine | Source | Content | |--------|---------| | Branch Hygiene (comment #285) | `git checkout -b branch main`, contamination detection/fix, `--force-with-lease` | | Error-Resistant curl (comment #295) | `--max-time 30 --retry 3`, response verification via HTTP code, `/tmp` for files | | Git Worktree-per-Issue (comment #303) | Each issue = dedicated worktree, agents jump in/out, worktree persists until PR merged | | Gitea Communication (PR #6) | Issue comment API template, PR creation API template, state machine | | opencode-worktree skill | Reference or incorporate existing `skills/opencode-worktree/` | ### Design Goals 1. **Single Source of Truth** — One skill file, complete workflow reference 2. **Kugetsu-Specific** — Gitea URLs, token naming, repo paths hardcoded 3. **Error-Resistant by Default** — All curl commands include timeouts, retries, verification 4. **Per-Issue Isolation** — Git worktree per issue (not per session) 5. **Auto-Loadable** — Can be configured in Hermes skills config ### Questions to Resolve 1. **Location:** `skills/agent-protocol/` (new) vs update existing `skills/opencode-worktree/`? 2. **Auto-load:** Should this load automatically via Hermes skills config, or be referenceable on demand? 3. **OpenCode vs Hermes:** Is this skill for OpenCode agents, Hermes agents, or both? ## References - Issue #1: Document Hermes Setup (this builds on) - PR #6: Docs: Add subagent workflow documentation (merged) - PR #8: docs: add hermes-setup.md (open) - Comment #285: Branch Hygiene Workflow - Comment #295: Improved Subagent Workflow - Error Reduction Guide - Comment #300-303: Git Worktree-per-Issue discussion ## Status - **Analysis:** Complete (this issue) - **Implementation:** Pending
shoko closed this issue 2026-03-31 11:30:03 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
0.2.x-only
Available only in 0.2.x, not backportable
 0.3.x-only
Available only in 0.3.x, not backportable
 backport
Backport compatible - can merge to 0.1.x
 blocked
Issue needs clarification/discussion before it can be worked on
 bug
Bug report
 critical
Critical - blocking parallel work
 feature
New feature
 foundation
Foundation work for 0.2.x
 high
High priority - workflow improvements
 meta
Meta issue tracking multiple issues
 need-review
PR needs review before merge
 parallelization
Issues related to parallelization
 ready
Issue is clear and ready to be implemented/delegated
 ready-to-merge
PR approved and ready to merge
 task-delegation
Issues related to task-delegation
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
shoko
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: shoko/kugetsu#9
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?