spec-kitty / spec-kitty/spec-kitty

harness/skill/hook surfaces hardcode assumptions that break on other harnesses, repo layouts, and mission phases (opencode capability_matrix, review-skill -- src/ scope, PostToolUse point-cut nudges)

Open
#2,746 1 comment 0 reactions 0 assignees View on GitHub
agent-profiles catfooding priority:P2 workflow
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
14h 52m
Merged PRs (30d)
303

Description

## Summary
Three tooling-surface defects share one root cause: harness/skill/hook logic hardcodes an assumption that is false outside spec-kitty's own environment. The capability matrix says OpenCode has no native agents (it now does), the review skills diff only `-- src/` (blind on root-layout repos), and the PostToolUse hook fires point-cut nudges keyed off command invocation rather than the mission's actual phase.

Related open: #1808 (Epic: agent harness support), #582 (harden implement-review for OpenCode + shared lanes), #2703 (implement-review changed-file lint recipe not portable to zsh), #2329/#2330 (non-src / non-Python layouts). Related closed: #1940 (native agent profile projection provider), #1578 (opencode reviewer failure → hollow self-approval), #1874 (stale OpenCode worktree docs).

## Sub-issues

### B05 — capability_matrix.py OpenCode entry is stale ("No native agent primitive") — OpenCode now has native agents
- Symptom: capability_matrix records OpenCode as "No native agent primitive; use command surfaces", but OpenCode v1.17.x (2026-07) ships `.opencode/agent/.md` persona files + an `--agent` flag on `opencode run` — a native agent primitive analogous to Claude's `.claude/agents/`. Tier-3 local probe (opencode-ai@1.17.18) confirmed: (1) `.opencode/agent/.md` persona files load & apply (singular `agent/` dir observed live; docs also say `agents/` — verify spelling); (2) an unknown `--agent` name warns + silently falls back to the DEFAULT agent (typo → wrong persona, not fail-closed); (3) OpenCode has THREE permission-bypass aliases feeding one boolean: `--auto`, hidden `--yolo`, hidden `--dangerously-skip-permissions` (a forbidden-flag scan must name all three; the hidden two aren't in `--help`).
- Repro: inspect `capability_matrix.py` opencode row vs opencode-ai@1.17.x behavior.
- Expected: update capability_matrix for OpenCode's native agents; add a process note that fast-moving harness entries need version stamps (opencode shipped 6 patches in 9 days + moved orgs sst → anomalyco).
- Source: `specify_cli tool_surface/profiles/capability_matrix.py`.

### B18 — mission-review / implement-review skills hardcode a -- src/ scope-diff blind to root-layout repos
- Symptom: both skills prescribe a "confirm only intended surfaces changed" check via `git diff ..HEAD -- src/`, written against spec-kitty's own `src/` layout. On a repo whose production code lives at the ROOT (app.py/actor_api.py/actions.py/core.py…), the `-- src/` filter shows only test/fixture diff and is completely blind to the production diff (evidence: 25 files / 3509 insertions of fixtures shown, ZERO of the 1393-insertion production diff) — a silent green scope-confirmation reviewing zero real lines.
- Repro: run the review skill on a root-layout repo; observe the scope diff excludes production files.
- Expected: derive diff paths from the repo's actual layout (or diff unfiltered / at repo root); at minimum document that `-- src/` must be adapted to the target repo. Related to #2703 (same skills, portability).
- Source: `~/.agents/skills/spec-kitty-mission-review/SKILL.md`, `~/.agents/skills/spec-kitty-implement-review/SKILL.md`.

### B21 — PostToolUse hook fires premature / false gate point-cut nudges (keyed off command invocation, not phase_complete)
- Symptom: the hook emits "post-plan point-cut reached" / "post-spec point-cut reached" keyed off "a spec-kitty command was invoked" rather than the actual phase reached. E.g. `agent mission setup-plan --json` scaffolds a TEMPLATE plan.md even when it BLOCKS (`plan_substantive:false`) → the hook fires "post-plan" BEFORE any plan is authored; a "post-spec" nudge fired after `spec-commit` returned blocked. Nudge text reads as if the phase completed. Flagged independently by 3+ subagents across 3 missions.
- Repro: run `setup-plan --json` on a mission that blocks; observe the "post-plan point-cut reached" nudge.
- Expected: trigger point-cut nudges on the mission's actual `phase_complete` transition, not on command invocation. (Harmless when gate scheduling is orchestrator-owned, but a real detection gap: an agent trusting the nudge would run a gate prematurely against a template/empty artifact.)
- Source: PostToolUse hook (gate point-cut nudges).

## Why bundled
All three are "tooling surface hardcodes a false assumption": harness capability (opencode), repo layout (-- src/), and phase detection (command-invocation vs phase_complete). They live in the harness/skill/hook layer and are a single campsite-style correctness pass over the surfaces that generate/gate agent work. Split later if the operator prefers per-surface issues.

Reported from weekend dogfooding of spec-kitty 3.2.5 (Mission Control multi-mission program), 2026-07-11/12. Filed as a bundle to fix as one governed mission.

Contributor guide

Open the contributing guide

Research direction

Start with specify_cli/tool_surface/profiles/capability_matrix.py and compare its OpenCode row with the reported OpenCode 1.17.x behavior. Then inspect ~/.agents/skills/spec-kitty-mission-review/SKILL.md, ~/.agents/skills/spec-kitty-implement-review/SKILL.md, and the PostToolUse hook while reproducing the root-layout diff and blocked setup-plan cases. Done means each surface reflects the target harness, repository layout, and actual phase_complete state.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, python
Domain
cli, developer-experience, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.