setup-workflow

Files (8)

• SKILL.md
• AGENTS_TEMPLATE.md · references/
• CLAUDE_TEMPLATE.md · references/
• domain.md · references/
• issue-tracker-github.md · references/
• issue-tracker-gitlab.md · references/
• issue-tracker-local.md · references/
• triage-labels.md · references/

SKILL.md (first lines)

# Setup Workflow — Multi-Agent Framework + Tool Config

Scaffold everything a repo needs so Hermes, OpenCode, and any other agent can collaborate:
- **Shared context** — AGENTS.md, CLAUDE.md, docs/adr/, PLAN.md, .hermes/
- **Git worktree convention** — isolated feature branches
- **Tool configuration** — issue tracker, triage labels, domain doc layout

This merges the old `setup-workflow` + `setup-skills` into one unified invocation. Run once per repo before using other skills.

## What This Creates

```
project/
├── AGENTS.md              ← shared context for ALL agents
├── CLAUDE.md              ← OpenCode adapter (references AGENTS.md)
├── docs/adr/
│   ├── index.md           ← ADR log
│   └── (numbered ADRs)    ← filled as decisions are made
├── PLAN.md                ← active plan + progress tracker
├── .hermes/
│   ├── context.md         ← Hermes session context
│   ├── blocker.md         ← when stuck, write context here
│   └── session-notes/     ← per-session summaries
├── docs/agents/
│   ├── issue-tracker.md   ← where issues live and how to use the CLI
│   ├── triage-labels.md   ← five canonical role labels
│   └── domain.md          ← domain doc consumer rules
└── .gitignore             ← .worktrees/ + .hermes/session-notes/
```

## Workflow Pipeline

This skill is the entry point. After it runs, the pipeline is:

```
setup-workflow (done) → grill-plan → write-prd → write-todo → implement
```

## Process

### 1. Discover

Check what already exists. Don't assume anything:

- `git remote -v` — detect host (GitHub/GitLab) and infer repo
- `AGENTS.md` — does it exist? Read it.
- `CLAUDE.md` — does it exist? Read it.

- `docs/adr/` — does it exist? List contents.
- `PLAN.md` — does it exist? Read it.
- `.hermes/` — does it exist? List contents.
- `docs/agents/` — does this skill's prior output already exist?
- `.scratch/` — sign that a local-markdown issue tracker is in use
- `go.mod`, `package.json`, `Cargo.toml`, etc. — detect tech stack
- Is the project a git repo? (`git rev-parse --git-dir`)
- Is there at least one commit?

### 2. Present findings

Summarise what exists and what's missing. If AGENTS.md already has a `## Agent skills` block and all framework files exist, confirm with the user before making changes or ask if they want to reconfigure.

**If framework files already exist, skip Phase 1 and go straight to Phase 2.**

### 3. Phase 1 — Scaffold framework

For each missing file, create it using the templates in `references/`.

**CRITICAL:** Never overwrite an existing file without user confirmation. If a file exists, read it, show the user, and ask: "Replace, merge, or skip?"

Create these files:

**AGENTS.md** — from [AGENTS_TEMPLATE.md](./references/AGENTS_TEMPLATE.md). Fill in `{{PROJECT_NAME}}`, `{{STACK}}`, `{{REPO_URL}}`.

**CLAUDE.md** — from [CLAUDE_TEMPLATE.md](./references/CLAUDE_TEMPLATE.md). Fill in `{{PROJECT_NAME}}`, `{{STACK}}`.

**docs/adr/** — create directory with `index.md`:
```markdown
# Architecture Decision Records

| ADR | Title | Status |
|-----|-------|--------|
| 001 | [Title](001-title.md) | Proposed |
```

**PLAN.md** — create with initial structure:
```markdown
# Plan

## Current goal
[what we're working on]

## Progress
- [ ] Not started

## Notes
```

**.hermes/** — create with `context.md`, `.gitkeep` in `session-notes/`.

**Git worktree setup** — add to `.gitignore` if not present:
```bash
echo '.worktrees/' >> .gitignore
echo '.hermes/session-notes/' >> .gitignore
```

Explain the worktree convention:
```bash
git worktree add .worktrees/<feature-name> main
cd .worktrees/<feature-name>
# ... implement ...
git worktree remove .worktrees/<feature-name>
```

### 4. Phase 2 — Configure tools

Walk the user through three decisions **one at a time**. Present a section, get the answer, then move to the next.

#### Section A — Issue tracker

From atalariq/skills, MIT.

More from atalariq/skills