Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
16 changes: 16 additions & 0 deletions .agents/skills/issue-spec-feedback/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
name: issue-spec-feedback
description: Capture reproducible friction from any project skill, CLI command, or workflow. Use when instructions, references, or scripts cause a concrete problem during work.
license: MIT
metadata:
requires: "Requires issue-spec CLI."
author: issue-spec
version: "1.0"
generatedBy: "issue-spec"
---

# Issue Spec Feedback

When a skill's instructions, references, or scripts cause a reproducible problem, record the skill name, repository-relative path, applicable revision, observed behavior, and impact on the task. Direct the report to the repository that owns the cause.

Follow the [feedback guide](../issue-spec-workflow/references/workflow-feedback.md) to load project guidance, verify the Issue destination, and record evidence. Issue writes use the task's authorization and the target backend's permissions.
2 changes: 2 additions & 0 deletions .agents/skills/issue-spec-workflow/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ For selected issue-spec steps, the built-in phase sequence and canonical artifac
3. Default to `--issue` for a bounded change with one code writer. A single child or subagent is an execution choice, not a reason to create TASK or PROCESS. Use `--proposal` with optional `--design` and `--implement` only when product, design, or concrete coordination risk requires them. File count does not select the path.
4. Read only selected issue bodies and typed planning artifacts. Historical REVIEW, VERIFY, evidence, receipt, finalization, Archive, and merge-authority data are explicit read-only audit history.

When authorized work exposes evidence-backed CLI, workflow, or project skill friction, use [Workflow feedback](references/workflow-feedback.md). Project guidance may refine routing and write authorization.

## Optional Planning and Implementation

- Create Proposal, Design, Implement, and TASK only when product, design, or coordination risk makes that planning useful. Create PROCESS only when a concrete execution need requires managed coordination: concurrent code writers, protection of pre-existing work through isolation, enforced path ownership, restartable cross-session handoff, or dependency-ordered integration. Generate selected canonical SPEC, QUESTION, TASK, and PROCESS planning artifacts; transition existing artifacts instead of regenerating them.
Expand Down
72 changes: 72 additions & 0 deletions .agents/skills/issue-spec-workflow/references/workflow-feedback.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Workflow feedback

Use this reference when authorized work exposes a reproducible problem with a project skill, CLI command, or workflow. The standalone `issue-spec-feedback` skill also links to this reference during ordinary project tasks. Continue the original task and use an ordinary Issue and comments. Apply the current task's publication authorization and any standing authorization in project guidance.

## Find the project context

From the checkout root, read `.issue-spec/config.json` to find the project's Issue repository (`repo`), `profile`, `hostname`, and self-hosted `server_instance_id` when present. If the file is absent, use the project Issue target established by the task. The code remote or Source Binding can point to a different repository.

Run `issue-spec workflow which --repo "$project_repo" --json` with the project's Issue repository. Read the config at `.workflow.source.config_path` when present, including `openspec/config.yaml` if selected. Apply the relevant project rules and load the repository-relative files in `.workflow.config.guidance.shared`.

## Route and record

1. Choose the destination repository by root cause. Use the project's Issue target for locally owned skills, guidance, validation, and release problems. For CLI limitations, reusable workflow improvements, or externally maintained skills, use the owning upstream Issue target identified by the task or project guidance. Set `feedback_repo` and `feedback_profile` from that destination. Keep an internal draft while the destination is uncertain.
2. Run `issue-spec --profile "$feedback_profile" auth status --json` and require `.ok` and the intended `.auth.profile`. Confirm the expected GitHub host or the self-hosted `.auth.server_instance_id` for the destination. For GitHub Enterprise with the built-in `github` profile, pass the destination's `--hostname` to auth and each Issue command as well. Use the same verified profile and repository for every destination read and write, including a retry. User or project authorization and backend permissions govern writes.
3. Search open and closed discussions for the same cause with `issue-spec --profile "$feedback_profile" search issues --repo "$feedback_repo" --scope discussion --state all --query 'specific behavior'`. Read plausible matches with `issue-spec --profile "$feedback_profile" read issue --repo "$feedback_repo" --issue N --comments`. Reuse an existing Issue for the same unresolved cause and supplement a closed decision with authorized evidence when appropriate. Link a distinct regression after a fix to its predecessor.
4. For a new authorized report, use `issue-spec --profile "$feedback_profile" issue create simple --repo "$feedback_repo" --title 'Observed problem' --body-file report.md`. Include the dated observation, originating project and revisions, expected and actual result, impact, owning layer, suggested correction and acceptance. Follow the destination's classification policy. An initial taxonomy uses `improvement/feedback` and one of `improvement/cli`, `improvement/workflow-generic`, or `improvement/workflow-project`. If classification needs a separate authorized label action, retain the original Issue identity and retry that action.
5. Record each independent event with its original context. For a skill problem, include the skill name, repository-relative path, applicable revision, and the step and impact that can be verified. Use the provider's stable source instance identifier, source repository and original task or release identifier. For a retried release, preserve its original key even when the run or attempt changes. A maintainer or configured trusted reporter can map each verifiable historical event to its own record and link the original evidence. Count independent events across Issue bodies and ordinary comments. Treat discussion, handoffs and repair verification as context for those events.
6. Preview the record. Confirm the returned `url` identifies the intended Issue and the count is correct. Omit `--dry-run` when the write is authorized.

```sh
issue-spec --profile "$feedback_profile" feedback record --repo "$feedback_repo" --issue 42 --event-file occurrence.json --dry-run --json
```

```json
{
"source_instance": "github:github.com",
"source_repository": "example/project",
"event_id": "release:v1.2.3@abc1234",
"observed_at": "2026-11-16T10:30:00+08:00",
"revision": "abc1234",
"summary": "The catalog deployment ran before publication and its download check returned HTTP 404.",
"evidence": ["https://github.com/example/project/actions/runs/123"]
}
```

Include only sanitized evidence. `revision` is optional. A preview reports the event key and projected confirmed count using the current identity. With a trusted reporter list, a contributor can record an event for confirmation. When the destination restricts trusted reporters, a configured reporter can confirm an earlier unconfirmed event by verifying the evidence and recording the same key. The backend supplies the comment author. A submitted field claiming confirmation or identity carries no authority.

An ambiguous submission is reconciled by rereading the Issue. Retry the same event file if needed. If the result shows a pending label action, an authorized caller can retry that action with the same event without increasing the count. Preserve the Issue URL in handoffs.

## Defaults and optional destination policy

Recording and preview work after ordinary initialization. The default policy counts distinct evidence from authenticated Issue authors and suggests `priority/high` at three confirmed occurrences.

To change the threshold or enable automatic escalation, publish a policy from an ordinary Issue in the **destination** repository. Its body contains a single JSON object, optionally fenced as JSON. To customize just the threshold, the entire body can be `{"threshold": 5}`.

Automatic escalation uses `"mode": "auto"` and a list of trusted reporters. For each trusted account, get the stable ID from `issue-spec --profile "$feedback_profile" auth status --json` (`.auth.user_id`). Write the IDs as strings.

```json
{
"threshold": 3,
"mode": "auto",
"priority_label": "priority/high",
"trusted_reporter_ids": ["123"],
"higher_priority_labels": ["priority/critical"],
"hold_labels": ["priority/deferred"]
}
```

An automatic assignment uses a predefined repository label. The priority label defaults to `priority/high`. Higher-priority and hold labels are optional. `issue-spec/feedback-hold` and `wontfix` are recognized holds. A closed or locked Issue is ineligible.

```sh
issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17 --dry-run --json
issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17
```

Publishing requires permission to manage repository label definitions. The command binds the exact policy body to the repository's `issue-spec/feedback-policy` label definition. Change the policy Issue body and publish again to activate a new revision. Remove the policy label definition to return to the built-in suggestion policy. GitHub enforces the caller's permission to assign a label. On self-hosted, a caller who can create Issues can request promotion. The server rechecks the published policy, persisted evidence and Issue eligibility before assigning the configured label. The ordinary issue-label API uses its triage authorization.

## Customize project guidance

Use an entry in `guidance.shared` in the selected workflow config to customize when to use feedback, project and upstream destinations, sanitization, or standing publication authorization. The standalone feedback skill and shared reference are available after ordinary init or a workflow update. Preview an existing checkout's update with `issue-spec workflow update --dry-run --repo "$project_repo"`.

For a requested interval review, include open and closed feedback Issues and compare their creation dates and dated evidence. Group by root cause and count distinct keys. Record the upstream fix, local adoption revision and comparable verification as they become available in relevant authorized work. Prefer the original Issue and its evidence links for handoff across sessions.
12 changes: 10 additions & 2 deletions .agents/skills/issue-spec-workflow/release.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,16 @@
"release": "development",
"source_revision": "unknown",
"requirements_skill_content_id": "sha256:35e55ba3b52b377acbd36ca4305cd958e3bd593008d576a7a82c9b06ab862ed1",
"content_digest": "sha256:6644c5543ea8dd9914a3c7d34da7d12f19505d1cb10e99591f7985bb8e3bff7f",
"content_digest": "sha256:cf1870225bea33dcc6a8058b06a2badab1db6a2a6dabb9b728a0c35f7f72134f",
"files": [
{
"path": ".agents/skills/issue-spec-apply/SKILL.md",
"sha256": "2351606737a7b0201c13ecc61ce4cd652d9d4bafaa66d20abc64c51ec56b2d56"
},
{
"path": ".agents/skills/issue-spec-feedback/SKILL.md",
"sha256": "247843d9acd7ae4fe8cb72289ab357c16bd665021f86df859505f985f98a7a72"
},
{
"path": ".agents/skills/issue-spec-github/SKILL.md",
"sha256": "a2a1cfeb647e737f66dbbbd97a53cfc752c84395ee4f6f080d7bfab3ee48d7d5"
Expand All @@ -19,7 +23,7 @@
},
{
"path": ".agents/skills/issue-spec-workflow/SKILL.md",
"sha256": "bc48b5f608258aa5b821738100c68e6d2fa4d8e24aafc1ec615649482369869a"
"sha256": "e94c748d919eff7fbd11e4f9de61d8268272a733278087d1fa19cb2a58348b58"
},
{
"path": ".agents/skills/issue-spec-workflow/references/durable-maintenance.md",
Expand All @@ -40,6 +44,10 @@
{
"path": ".agents/skills/issue-spec-workflow/references/question-decisions.md",
"sha256": "8c817bb08e73853101a42d8c4ca0e83e72fc81be04221f1f5004623588fa193c"
},
{
"path": ".agents/skills/issue-spec-workflow/references/workflow-feedback.md",
"sha256": "aff8d95d905aa39c10f78a0cb605582f7d55766478b74cb42bf31f909d70e06a"
}
]
}
1 change: 1 addition & 0 deletions .claude/skills/issue-spec-feedback
15 changes: 14 additions & 1 deletion docs/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ New durable specs default to `issue-spec/specs/<capability>/spec.md`. If `opensp

### Shared skills and safe updates

`init` defaults to `--delivery skills`. `.agents/skills/<name>` is canonical; Claude receives relative links per generated skill. `--delivery both|commands` remains an explicit legacy integration option. Root `AGENTS.md`/`CLAUDE.md` and project-specific skills remain project-owned.
`init` defaults to `--delivery skills`. When tool selection is omitted, skills delivery detects repository tool directories and falls back to canonical `.agents/skills` in a fresh checkout. GitHub init validates workflow inputs and checks file conflicts before saving the Issue binding and ensuring labels. Claude receives relative links when selected or detected. `--delivery both|commands` remains an explicit legacy integration option. Root `AGENTS.md`/`CLAUDE.md` and project-specific skills remain project-owned.

```yaml
# issue-spec/config.yaml — optional supplements, paths relative to checkout root
Expand All @@ -54,6 +54,19 @@ The preview reports paths, actions, hashes and conflicts. The apply performs the

A legacy whole-directory Claude link is split while preserving previously exposed entries. Later upgrades only add generated skills, never unrelated project skills. Exact redundant Claude copies can become links; differing copies block the update. Existing worktrees retain their own committed skill version. Runtime host discovery still needs verification in a fresh session.

### Workflow feedback

Ordinary `issue-spec init` supplies the standalone `issue-spec-feedback` skill. It can be discovered when using any project skill exposes a reproducible issue with instructions, references, or scripts. The skill shares the feedback guide with `issue-spec-workflow` and uses the existing recording and deduplication commands. The built-in policy suggests `priority/high` at three confirmed occurrences. Projects can use `guidance.shared` to refine routing and standing authorization. [Workflow feedback reference](../.agents/skills/issue-spec-workflow/references/workflow-feedback.md)

For feedback about your own project, start with `repo` and `profile` from `.issue-spec/config.json`. Use the verified destination profile and repository in both previews and writes.

```bash
issue-spec --profile "$feedback_profile" feedback record --repo "$feedback_repo" --issue 42 --event-file occurrence.json --dry-run --json
issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17 --dry-run --json
```

Omit `--dry-run` for authorized writes. Use `feedback configure` when the destination wants a custom threshold or automatic escalation. GitHub checks label permission. On self-hosted, the updated Server checks Issue creation permission and validates eligibility from stored evidence.

### HTML review authoring

HTML review authoring is enabled by default. To keep Proposal, Design, and Implement authoring on the typed Markdown workflow without loading or generating human-review projection instructions, configure the required boolean explicitly:
Expand Down
15 changes: 14 additions & 1 deletion docs/reference.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,19 @@ issue-spec workflow which --repo owner/repo --json

新的长期 spec 默认写入 `issue-spec/specs/<capability>/spec.md`。若 `openspec/specs/<capability>/spec.md` 已存在,`durable-spec` 可以更新那个遗留的长期 spec,并报告所选的兼容路径。

### 工作流反馈

常规 `issue-spec init` 默认生成独立的 `issue-spec-feedback` 技能。使用任意项目技能时遇到可复核的指令、引用或脚本问题,都能通过它找到反馈入口。它和 `issue-spec-workflow` 共用指引,沿用现有记录、去重和计数命令。默认累计三次确认复现时建议标记 `priority/high`。项目可通过 `guidance.shared` 定制上报去向和授权范围。 [反馈指引与配置示例](../.agents/skills/issue-spec-workflow/references/workflow-feedback.md)

反馈本项目的问题时,先读取 `.issue-spec/config.json` 中的 `repo` 和 `profile`。预览和写入都使用核验后的目标仓库和 profile。

```bash
issue-spec --profile "$feedback_profile" feedback record --repo "$feedback_repo" --issue 42 --event-file occurrence.json --dry-run --json
issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17 --dry-run --json
```

在授权写入时去掉 `--dry-run`。自定义阈值或开启自动升级时,由目标仓库维护者运行 `feedback configure`。GitHub 按标签权限校验。自托管由新版 Server 校验 Issue 创建权限,并根据已保存证据判断能否升级。

### HTML review 创作指引

HTML review 创作指引默认启用。若要让 Proposal、Design 与 Implement 创作只使用类型化 Markdown 工作流,而不加载或生成面向人工 review 的 projection 指令,请显式配置这个必填布尔值:
Expand Down Expand Up @@ -76,7 +89,7 @@ rules:

### 共享技能、项目补充与安全升级

`init` 默认 `--delivery skills`。通用技能保存在 `.agents/skills/<name>`,Claude 按技能目录使用相对软链。`--delivery both|commands` 仅在显式选择时生成旧命令。项目维护 `AGENTS.md`、`CLAUDE.md`、自有技能与补充规则。
`init` 默认 `--delivery skills`。省略 `--tools` 时按仓库已有目录探测宿主,空仓库默认生成 `.agents/skills`。GitHub 初始化会在保存 Issue 绑定和设置标签前校验工作流配置及文件冲突。显式选择或探测到 Claude 时按技能目录生成相对软链。`--delivery both|commands` 仅在显式选择时生成旧命令。项目维护 `AGENTS.md`、`CLAUDE.md`、自有技能与补充规则。

```yaml
# issue-spec/config.yaml,路径相对于仓库根目录
Expand Down
1 change: 1 addition & 0 deletions internal/auth/auth.go
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ type Token struct {
Value string `json:"-"`
Source string `json:"source"`
User string `json:"user,omitempty"`
UserID int64 `json:"user_id,string,omitempty"`
Scopes []string `json:"scopes,omitempty"`
Host string `json:"host"`
Profile string `json:"profile,omitempty"`
Expand Down
1 change: 1 addition & 0 deletions internal/commands/auth.go
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ func (a *app) runAuthStatus(ctx context.Context, args []string) int {
return 1
}
token.User = user.Login
token.UserID = user.ID
token.Scopes = scopes
if *jsonOut {
return a.outputJSON(map[string]any{"ok": true, "auth": token, "backend": token.Backend})
Expand Down
4 changes: 4 additions & 0 deletions internal/commands/commands.go
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,8 @@ func Execute(args []string, in io.Reader, out io.Writer, errOut io.Writer) int {
return a.runIssue(ctx, args[1:])
case "comment":
return a.runComment(ctx, args[1:])
case "feedback":
return a.runFeedback(ctx, args[1:])
case "question":
return a.runQuestion(ctx, args[1:])
case "projection":
Expand Down Expand Up @@ -223,6 +225,8 @@ Usage:
issue-spec comment create --repo owner/repo --issue N --body-file reply.md [--json]
issue-spec comment edit --repo owner/repo --comment-id N --body-file reply.md [--json]
issue-spec comment delete --repo owner/repo --comment-id N [--json]
issue-spec feedback configure --repo owner/repo --issue N [--dry-run] [--json]
issue-spec feedback record --repo owner/repo --issue N --event-file event.json [--dry-run] [--json]
issue-spec comment generate --type SPEC --id SPEC-1001 --input-file spec.json [--status confirmed] [--scope "..."]
issue-spec comment generate --type SPEC|TASK --example
issue-spec comment upsert --repo owner/repo --issue 1 --type SPEC --id SPEC-1001 --body-file file.md [--allow-noncanonical]
Expand Down
Loading
Loading