Skip to content

feat(skills): add harness integration to tentacle-creator skill #738

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
magicpro97 merged 2 commits into from
May 30, 2026
Merged

feat(skills): add harness integration to tentacle-creator skill #738

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
12da266
feat(skills): add harness integration to tentacle-creator skill (#735)
May 30, 2026
62c0fc1
fix: address reviewer comments in tentacle-creator/SKILL.md
May 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 234 additions & 0 deletions .github/skills/tentacle-creator/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,234 @@
---
name: tentacle-creator
description: Analyze a project and generate a customized tentacle-orchestration skill for multi-agent workflows. Use when someone says "set up tentacle", "configure multi-agent", "set up orchestration", or when onboarding a project that needs parallel agent coordination. Also use when the user wants to break complex tasks into scoped work units for multiple agents.
---

# Tentacle Creator

A meta-skill that analyzes your project and generates a customized `tentacle-orchestration` skill — tailored to your project's language, framework, folder structure, and available agents.

Think of it like `/init` — you run it once per project to bootstrap the tentacle pattern.

## Why customize per project

The generic tentacle skill works everywhere but produces generic dispatch prompts. A customized version knows your project's agent types (e.g., `lambda-developer` vs `general-purpose`), folder conventions (e.g., `src/app/api/**/*` vs `backend/handlers/*`), and coding standards. This means richer CONTEXT.md files and better agent output.

## Workflow

### Step 1: Analyze the project

Run these in parallel to understand what you're working with:

```bash
# Directory structure
find . -maxdepth 3 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' | head -50

# Language and framework
ls package.json pyproject.toml Cargo.toml go.mod pom.xml build.gradle Gemfile mix.exs 2>/dev/null
cat package.json 2>/dev/null | head -30

# Custom agents
cat AGENTS.md 2>/dev/null | head -50
ls .github/agents/ 2>/dev/null

# Existing skills
ls .github/skills/ 2>/dev/null

# Coding conventions
cat .editorconfig 2>/dev/null
ls doc/ docs/ 2>/dev/null | head -10

# Project workflow (any source)
cat .github/WORKFLOW.md WORKFLOW.md 2>/dev/null | head -30
grep -i 'phase\|workflow\|pipeline\|gate' CLAUDE.md .github/copilot-instructions.md AGENTS.md 2>/dev/null | head -20

# Git info
git remote -v 2>/dev/null | head -2
```

### Step 2: Build a project profile

From the analysis, determine:

| Field | Examples |
|-------|---------|
| Language | TypeScript, Python, Go, Java, Rust |
| Framework | Next.js, Django, Spring Boot, Express |
| Architecture | Monorepo, microservices, monolith, serverless |
| Layers | API, service, repository, model, test |
| Test framework | Jest, pytest, JUnit, go test |
| Custom agents | From AGENTS.md (if any) |
| Folder patterns | `src/app/api/*`, `backend/handlers/*`, `tests/**/*` |
| Workflow | Development phases described anywhere (WORKFLOW.md, CLAUDE.md, AGENTS.md, copilot-instructions) |

### Step 3: Generate agents (if missing)

If the project has no custom agents in AGENTS.md or `.github/agents/`, use the `agent-creator` skill to generate `.agent.md` files first. Tentacle orchestration works best when agents are domain-specific (e.g., `backend-dev`, `test-writer`) rather than generic `general-purpose`.

Run the agent-creator skill, or read `~/.copilot/tools/skills/agent-creator/SKILL.md` and follow its workflow to generate agents from the curated templates in `references/`.

### Step 4: Generate the skill file

Create `.github/skills/tentacle-orchestration/SKILL.md` customized for the project.

**IMPORTANT: Fork, don't rewrite.** Start from the canonical reference at
`~/.copilot/tools/skills/tentacle-orchestration/SKILL.md` and customize it.
Every section in the reference MUST appear in the output. You are ADDING
project-specific content, not cherry-picking sections.
Preserve the canonical task-step-generator-first planning discipline and the
decomposition review guidance; customize examples and commands, not the control flow.

#### 4a: Required sections (ALL must be present)

Read the reference and extract its section headings (`## ` and `### `). The generated file
MUST include ALL of these sections. The generated file must also comply with
`~/.copilot/tools/skills/references/skill-standards.md` (YAML frontmatter, line count,
example blocks, description trigger words). Use this checklist:

| # | Required Section | Source | Action |
|---|-----------------|--------|--------|
| 1 | `## Planning Discipline` | Reference | Keep task-step-generator first, reviewed step plan, and accepted/edited/rejected record |
| 2 | `## Decision Confidence Gate` | Reference | Keep confidence `< 1.0` research-first blocking rule and opus-class validation requirement |
| 3 | `## When to use` | Reference | Keep table, add project-specific rows |
| 4 | `## Anti-patterns` | Reference | Keep all items, add project-specific items |
| 5 | `## Core concept` | Reference | **Copy verbatim** — file tree diagram, octopus metaphor |
| 6 | `## Workflow` (or `## Internal Workflow`) | Reference | Keep 5-phase labels: Clarify → Plan → Execute → Verify → Close |
| 7 | `### Phase 0: Clarify Spec` | Reference | Keep motivation text ("bug found in spec costs 1x..."), Steps 0.0–0.5 |
| 8 | `### Phase 1: Plan` | Reference | Keep task-step-generator, decomposition review, and "Impact Analysis / Risk Assessment" mention; customize folder patterns |
| 9 | `### Phase 2: Execute` | Reference | Keep `--model` param in swarm, customize agent mapping table |
| 10 | `### Phase 3: Verify` | Reference | Keep 6-gate table, replace commands with project's build/lint/test |
| 11 | `### Phase 4: Close` | Reference | Keep `complete` before `delete` warning |
| 12 | `## Verification summary` | Reference | Keep 6-gate table (mirrors Phase 3 gates) |
| 13 | `## CLI reference` | Reference | Keep all commands, include `--model` in swarm |
| 14 | `## Tips` | Reference | Keep all tips, add project-specific tips |
| 15 | `## Reference docs` | New | Link to `~/.copilot/tools/skills/tentacle-orchestration/references/` |

**If a reference section exists but is not in the checklist above, include it anyway.**
The checklist is a minimum — not an exclusive list.

#### 4b: Project-specific additions

Layer these ON TOP of the canonical structure:

**Agent mapping table** — Map module types to agents (with model tier + ID). Use project-specific agent names:

| Tentacle type | agent_type | Model | Scope pattern |
|--------------|-----------|-------|--------------|
| Backend logic | backend-dev | claude-sonnet-4.6 | `src/app/api/**/*` |
| Tests | test-writer | claude-sonnet-4.6 | `tests/**/*` |
| Code review | code-review | claude-sonnet-4.6 | `src/**/*` |

**Verification commands** — Replace generic commands with the project's actual build/test/lint commands in the Phase 3 gate table (e.g., `npx tsc --noEmit`, `npx eslint .`, `yarn test`).

**CONTEXT.md template** — Include project-specific conventions (linting rules, import patterns,
naming conventions, theme tokens, i18n rules) so agents follow them.
Keep a "Step-plan review" section with source step file, accepted/edited/rejected steps,
dependency order, and evidence contract. This prevents generated plans from becoming
unreviewed instructions.

**Shared workspace warning** — Include the warning about parallel agents sharing filesystem.

**Knowledge integration** — If `~/.copilot/tools/briefing.py` exists, include `--briefing` and
`--learn` flags, `--budget 3000` for sub-agent injection, and agent timeout rules.
If not, note that session-knowledge can be installed for long-term memory.

**Workflow integration** — If the project describes a development workflow anywhere
(WORKFLOW.md, CLAUDE.md, AGENTS.md, copilot-instructions, or similar), add a
`## ⛔ WORKFLOW INTEGRATION` section mapping which outer phases run before/after
tentacle work. This prevents AI from treating the tentacle's internal lifecycle as
the entire workflow. Extract the phase names from whatever source describes them.

If no workflow is described anywhere, skip this section.

#### 4c: Structural validation (MANDATORY before proceeding)

After generating the file, run these checks:

```bash
# Validate all canonical headings are present
diff <(grep '^## ' ~/.copilot/tools/skills/tentacle-orchestration/SKILL.md | sort) \
<(grep '^## ' .github/skills/tentacle-orchestration/SKILL.md | sort)

# Verify Core concept has file tree
grep -q '\.octogent/tentacles/' .github/skills/tentacle-orchestration/SKILL.md || echo "FAIL: missing file tree"

# Verify Phase 0 motivation text
grep -q 'costs 1x' .github/skills/tentacle-orchestration/SKILL.md || echo "FAIL: missing motivation text"

# Verify low-confidence work is research-gated
grep -q 'Decision Confidence Gate' .github/skills/tentacle-orchestration/SKILL.md || echo "FAIL: missing confidence gate"
grep -q 'confidence.*1.0' .github/skills/tentacle-orchestration/SKILL.md || echo "FAIL: missing confidence threshold"
```

Any output (diff lines or FAIL messages) means the section is missing — add it before proceeding.

### Step 5: Set up .gitignore

```bash
if ! grep -qF '.octogent/' .gitignore 2>/dev/null; then
printf '\n# Tentacle orchestration (local work contexts)\n.octogent/\n' >> .gitignore
fi
```

### Step 6: Verify tentacle.py exists

```bash
ls ~/.copilot/tools/tentacle.py && sk tentacle --help
# fallback: python3 ~/.copilot/tools/tentacle.py --help
```

If missing, tell the user:
```
tentacle.py not found at ~/.copilot/tools/tentacle.py
Install: git clone https://github.com/magicpro97/copilot-session-knowledge.git ~/.copilot/tools
```

### Step 7: Report

Present a summary: project profile, files created, agent mappings detected, verification commands, and example usage commands. Also include a **Harness bootstrap** note: if `harness.yaml` does not exist in the project root, instruct the user to run `sk harness init` before their first tentacle dispatch.

<example>
**Project:** Next.js + TypeScript monorepo with yarn workspaces

**Profile:** Language: TypeScript | Framework: Next.js 14 | Test: Jest + Playwright | Agents: backend-dev, test-writer, code-review

**Generated:** `.github/skills/tentacle-orchestration/SKILL.md` (customized from reference)

**Agent mapping:** backend-dev → `src/app/api/**/*` | test-writer → `tests/**/*` | code-review → any PR

**Verification commands:** `npx tsc --noEmit` (build) · `npx eslint .` (lint) · `yarn test` (tests)

**Usage:** `sk tentacle create api-routes --scope "src/app/api/**/*" --desc "REST endpoint changes" --briefing`
</example>

## Compatibility

| Component | Required | Fallback |
|-----------|----------|----------|
| `tentacle.py` | `~/.copilot/tools/` | Prompt to install |
| `briefing.py` | `~/.copilot/tools/` | Skip knowledge integration |
| `learn.py` | `~/.copilot/tools/` | Skip auto-learn |
| `agent-creator` | `~/.copilot/tools/skills/` | Fall back to `general-purpose` agents |
| `task-step-generator` | `~/.copilot/tools/skills/` | Ask the orchestrator to draft and review a step file manually before creating tentacles |
| Custom agents | AGENTS.md or `.github/agents/` | Generate via agent-creator, or use `general-purpose` |
| Git repo | `.git/` | Required (tentacles stored in git root) |


## Harness Integration

**Quality over speed.** When this skill generates a `tentacle-orchestration` skill for a project:

1. **Ensure `sk harness check` stays in Phase 3 verification** — the canonical `tentacle-orchestration` reference already includes a Harness gate row; when generating a customized skill, preserve that row so agents never skip harness gates.
2. **Bootstrap harness for the project** — if `harness.yaml` does not yet exist, Step 7 (Report) must instruct the user to run `sk harness init` before their first tentacle dispatch.
3. **Wire harness into the generated CONTEXT.md template** — include a `sk harness check [--json]` step in the agent's verify phase.

```bash
# Bootstrap harness if harness.yaml is missing, then verify:
sk harness init --yes # skip if harness.yaml already exists
sk harness check --json
```

> **Quality gate:** A generated skill that drops the harness Phase 3 row is incomplete. Verify with:
> ```bash
> grep -q '| \*\*Harness\*\*\|Harness.*sk harness check' .github/skills/tentacle-orchestration/SKILL.md || echo "FAIL: harness gate row missing from Phase 3"
> ```
Loading