Skip to content

Commit 40afee6

Browse files
TabishBTabishB
authored
chore(openspec): add feedback command change proposal (Fission-AI#496)
Add change proposal for `openspec feedback` CLI command that enables users and agents to submit feedback via GitHub Issues. Key features: - Simple `openspec feedback <message>` command - GitHub Device OAuth for authentication - `/feedback` skill for agent-assisted feedback with context enrichment - Anonymization of sensitive data before submission - User confirmation required before submitting
1 parent 05023da commit 40afee6

3 files changed

Lines changed: 239 additions & 0 deletions

File tree

‎openspec/changes/add-feedback-command/proposal.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Why
2+
3+
Users and agents need a simple way to submit feedback about OpenSpec directly from the CLI. Currently there's no mechanism to collect user feedback, feature requests, or bug reports in a way that enables follow-up conversation.
4+
5+
## What Changes
6+
7+
- Add `openspec feedback <message>` CLI command
8+
- Add GitHub Device OAuth flow for user authentication
9+
- Create GitHub Issues in the openspec repository for each feedback submission
10+
- Add `/feedback` skill for agent-assisted feedback with context enrichment and anonymization
11+
12+
## Impact
13+
14+
- Affected specs: New `cli-feedback` capability
15+
- Affected code:
16+
- `src/cli/index.ts` - Register feedback command
17+
- `src/commands/feedback.ts` - Command implementation
18+
- `src/auth/github.ts` - GitHub OAuth device flow
19+
- `src/core/templates/skill-templates.ts` - Feedback skill template
20+
- `src/core/completions/command-registry.ts` - Shell completions

‎openspec/changes/add-feedback-command/specs/cli-feedback/spec.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
## ADDED Requirements
2+
3+
### Requirement: Feedback command
4+
5+
The system SHALL provide an `openspec feedback` command that creates a GitHub Issue in the openspec repository with the user's feedback.
6+
7+
#### Scenario: Simple feedback submission
8+
9+
- **WHEN** user executes `openspec feedback "Great tool!"`
10+
- **THEN** the system creates a GitHub Issue with title "Feedback: Great tool!"
11+
- **AND** the issue has the `feedback` label
12+
- **AND** the system displays the created issue URL
13+
14+
#### Scenario: Rich feedback with body
15+
16+
- **WHEN** user executes `openspec feedback "Title here" --body "Detailed description..."`
17+
- **THEN** the system creates a GitHub Issue with the specified title
18+
- **AND** the issue body contains the detailed description
19+
- **AND** the issue body includes metadata (OpenSpec version, platform)
20+
21+
#### Scenario: Multiline message
22+
23+
- **WHEN** user provides a multiline message (first line as title, rest as body)
24+
- **THEN** the system uses the first line as the issue title
25+
- **AND** the remaining lines become the issue body
26+
27+
### Requirement: GitHub authentication
28+
29+
The system SHALL authenticate users via GitHub Device OAuth flow before submitting feedback.
30+
31+
#### Scenario: First-time authentication
32+
33+
- **WHEN** user runs `openspec feedback` for the first time
34+
- **AND** no GitHub token is stored
35+
- **THEN** the system initiates GitHub Device OAuth flow
36+
- **AND** displays a URL and code for the user to authorize
37+
- **AND** polls for authorization completion
38+
- **AND** stores the token in global config on success
39+
40+
#### Scenario: Cached authentication
41+
42+
- **WHEN** user runs `openspec feedback`
43+
- **AND** a valid GitHub token is stored
44+
- **THEN** the system uses the cached token without re-authentication
45+
46+
#### Scenario: Token refresh
47+
48+
- **WHEN** the stored GitHub token is expired or invalid
49+
- **THEN** the system initiates a new Device OAuth flow
50+
- **AND** updates the stored token on success
51+
52+
#### Scenario: Authentication cancellation
53+
54+
- **WHEN** user cancels the OAuth flow (Ctrl+C)
55+
- **THEN** the system exits gracefully without storing any token
56+
- **AND** displays a message indicating feedback was not submitted
57+
58+
### Requirement: GitHub token storage
59+
60+
The system SHALL securely store GitHub authentication tokens in the global config directory.
61+
62+
#### Scenario: Token persistence
63+
64+
- **WHEN** GitHub authentication completes successfully
65+
- **THEN** the system stores the access token in `~/.config/openspec/config.json`
66+
- **AND** the token persists across CLI sessions
67+
68+
#### Scenario: Token isolation
69+
70+
- **WHEN** storing the GitHub token
71+
- **THEN** the token is stored separately from telemetry configuration
72+
- **AND** does not affect or depend on telemetry settings
73+
74+
### Requirement: Feedback always works
75+
76+
The system SHALL allow feedback submission regardless of telemetry settings.
77+
78+
#### Scenario: Feedback with telemetry disabled
79+
80+
- **WHEN** user has disabled telemetry via `OPENSPEC_TELEMETRY=0`
81+
- **AND** user runs `openspec feedback "message"`
82+
- **THEN** the feedback is still submitted to GitHub
83+
- **AND** telemetry events are not sent
84+
85+
#### Scenario: Feedback in CI environment
86+
87+
- **WHEN** `CI=true` is set in the environment
88+
- **AND** user runs `openspec feedback "message"`
89+
- **THEN** the feedback submission proceeds normally
90+
91+
### Requirement: Issue metadata
92+
93+
The system SHALL include relevant metadata in the GitHub Issue body.
94+
95+
#### Scenario: Standard metadata
96+
97+
- **WHEN** creating a GitHub Issue for feedback
98+
- **THEN** the issue body includes:
99+
- OpenSpec CLI version
100+
- Platform (darwin, linux, win32)
101+
- Submission timestamp
102+
- Separator line indicating "Submitted via OpenSpec CLI"
103+
104+
#### Scenario: No sensitive metadata
105+
106+
- **WHEN** creating a GitHub Issue for feedback
107+
- **THEN** the issue body does NOT include:
108+
- File paths from user's system
109+
- Project names or directory names
110+
- Environment variables
111+
- IP addresses
112+
113+
### Requirement: Error handling
114+
115+
The system SHALL handle feedback submission errors gracefully.
116+
117+
#### Scenario: Network failure
118+
119+
- **WHEN** GitHub API is unreachable
120+
- **THEN** the system displays a clear error message
121+
- **AND** suggests checking network connectivity
122+
- **AND** exits with non-zero code
123+
124+
#### Scenario: GitHub API error
125+
126+
- **WHEN** GitHub API returns an error (rate limit, server error)
127+
- **THEN** the system displays the error message from GitHub
128+
- **AND** exits with non-zero code
129+
130+
#### Scenario: Invalid token
131+
132+
- **WHEN** the stored token is revoked or invalid
133+
- **THEN** the system clears the stored token
134+
- **AND** initiates a new OAuth flow
135+
136+
### Requirement: Feedback skill for agents
137+
138+
The system SHALL provide a `/feedback` skill that guides agents through collecting and submitting user feedback.
139+
140+
#### Scenario: Agent-initiated feedback
141+
142+
- **WHEN** user invokes `/feedback <message>` in an agent conversation
143+
- **THEN** the agent gathers context from the conversation
144+
- **AND** drafts a feedback issue with enriched content
145+
- **AND** anonymizes sensitive information
146+
- **AND** presents the draft to the user for approval
147+
- **AND** submits via `openspec feedback` on user confirmation
148+
149+
#### Scenario: Context enrichment
150+
151+
- **WHEN** agent drafts feedback
152+
- **THEN** the agent includes relevant context such as:
153+
- What task was being performed
154+
- What worked well or poorly
155+
- Specific friction points or praise
156+
157+
#### Scenario: Anonymization
158+
159+
- **WHEN** agent drafts feedback
160+
- **THEN** the agent removes or replaces:
161+
- File paths with `<path>` or generic descriptions
162+
- API keys, tokens, secrets with `<redacted>`
163+
- Company/organization names with `<company>`
164+
- Personal names with `<user>`
165+
- Specific URLs with `<url>` unless public/relevant
166+
167+
#### Scenario: User confirmation required
168+
169+
- **WHEN** agent has drafted feedback
170+
- **THEN** the agent MUST show the complete draft to the user
171+
- **AND** ask for explicit approval before submitting
172+
- **AND** allow the user to request modifications
173+
- **AND** only submit after user confirms
174+
175+
### Requirement: Shell completions
176+
177+
The system SHALL provide shell completions for the feedback command.
178+
179+
#### Scenario: Command completion
180+
181+
- **WHEN** user types `openspec fee<TAB>`
182+
- **THEN** the shell completes to `openspec feedback`
183+
184+
#### Scenario: Flag completion
185+
186+
- **WHEN** user types `openspec feedback "msg" --<TAB>`
187+
- **THEN** the shell suggests available flags (`--body`)

‎openspec/changes/add-feedback-command/tasks.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
## 1. GitHub Authentication
2+
3+
- [ ] 1.1 Create `src/auth/github.ts` module with Device OAuth flow
4+
- [ ] 1.2 Implement token storage in global config (`~/.config/openspec/`)
5+
- [ ] 1.3 Add `getGitHubAuth()` function that returns cached token or initiates auth
6+
- [ ] 1.4 Add `clearGitHubAuth()` function for logout capability
7+
8+
## 2. Feedback Command
9+
10+
- [ ] 2.1 Create `src/commands/feedback.ts` with command implementation
11+
- [ ] 2.2 Register `feedback <message>` command in CLI
12+
- [ ] 2.3 Implement `--body` flag for rich content (title + body)
13+
- [ ] 2.4 Create GitHub Issue via API with `feedback` label
14+
- [ ] 2.5 Display created issue URL on success
15+
16+
## 3. Shell Completions
17+
18+
- [ ] 3.1 Add `feedback` command to command registry
19+
- [ ] 3.2 Regenerate completion scripts for all shells
20+
21+
## 4. Feedback Skill
22+
23+
- [ ] 4.1 Create feedback skill template in `skill-templates.ts`
24+
- [ ] 4.2 Document context gathering workflow
25+
- [ ] 4.3 Document anonymization rules
26+
- [ ] 4.4 Document user confirmation flow
27+
28+
## 5. Testing
29+
30+
- [ ] 5.1 Add unit tests for GitHub auth module
31+
- [ ] 5.2 Add unit tests for feedback command
32+
- [ ] 5.3 Add integration test for full feedback flow (mocked GitHub API)

0 commit comments

Comments
 (0)