Merge pull request #15 from kaakaww/feature/refinements

feat: agentic workflow support — app CRUD, scan detail, repo linking, git-aware init

Author: azconger

.claude/commands/add-api.md

@@ -1,11 +1,91 @@
 ---
-description: Add a new StackHawk API integration
+description: Add a new StackHawk API integration (with pattern matching + quirks check)
 ---
 
-Help me add a new StackHawk API endpoint integration. Ask me:
+Help me add a new StackHawk API endpoint integration.
+
+## Step 1: Research the Endpoint
+
+Before writing code, gather information:
+
+1. **Read the API reference** — `.claude/skills/stackhawk-api-sherpa/stackhawk-api.md`
+2. **Check the OpenAPI spec** — `stackhawk-openapi.json` for exact request/response schemas
+3. **Check API quirks** — `.claude/skills/stackhawk-api-sherpa/api-quirks.md` for known issues
+4. **Check the roadmap** — `docs/ROADMAP.md` for planned status
+
+Ask the user:
 1. What API endpoint should be integrated?
-2. What HTTP method (GET, POST, etc.)?
-3. What request/response structures are needed?
-4. Should this support pagination?
+2. What HTTP method (GET, POST, PUT, DELETE)?
+3. Should this support pagination?
+4. Is this a read-only query or a state mutation?
+
+## Step 2: Study Existing Patterns
+
+Read the most similar existing integration to match patterns:
+
+**For GET/list endpoints** — study:
+- `src/client/api/listing.rs` for pagination and query params
+- `src/client/pagination.rs` for `PaginationParams` and `PagedResponse`
+
+**For POST/PUT mutations** — study:
+- `src/client/stackhawk.rs` for `request_json_with_query()` and `request_with_body()`
+- The team update pattern (fetch-modify-put) if it's a PUT endpoint
+
+**For detail/drill-down** — study:
+- `src/client/api/scan_detail.rs` for nested resource fetching
+
+## Step 3: Implementation
+
+Follow this exact pattern:
+
+### 3.1 API Model (`src/client/models/<resource>.rs`)
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NewResource {
+    // Use #[serde(default)] for fields that may be missing
+    // Use #[serde(alias = "...")] for API field name differences
+    // Use Option<T> for truly optional fields
+}
+```
+
+### 3.2 Response Wrapper (in implementation file)
+```rust
+#[derive(Deserialize)]
+struct ListResponse {
+    items: Vec<NewResource>,
+    #[serde(default, deserialize_with = "deserialize_string_to_usize")]
+    total_count: usize,  // Some endpoints return this as a string!
+}
+```
+
+### 3.3 Trait Method (`src/client/mod.rs`)
+```rust
+async fn list_resource(&self, org_id: &str, pagination: Option<&PaginationParams>) -> Result<Vec<Resource>>;
+```
+
+### 3.4 Implementation
+- Use `self.request_with_query()` for GET with query params
+- Use `self.request_json_with_query()` for POST with body
+- Apply rate limiting category (check `src/client/rate_limit.rs`)
+- Add to `CachedStackHawkClient` in `src/cache/client.rs` with appropriate TTL
+
+### 3.5 Mock Implementation (`src/client/mock.rs`)
+Add the method to `MockStackHawkClient` returning fixture data.
+
+## Step 4: Verify
+
+```bash
+cargo check     # Compiles?
+cargo test      # Tests pass?
+cargo clippy -- -D warnings  # Lint clean?
+```
+
+## Common Pitfalls
 
-Then implement the API client method following the existing patterns in src/client/stackhawk.rs with proper error handling, rate limiting, and JWT authentication.
+From `api-quirks.md`:
+- **PUT = REPLACE-ALL** — Always fetch current state before PUT operations
+- **readOnly fields required** — Don't trust OpenAPI `readOnly` annotations
+- **String numbers** — Use `deserialize_string_to_usize` for `totalCount` fields
+- **Removed endpoints** — Check if the endpoint was removed from recent spec updates
+- **Rate limits** — Categorize correctly: Scan (80/sec), User (80/sec), AppList (80/sec), Default (6/sec)

.claude/commands/add-command.md

@@ -1,36 +1,118 @@
 ---
-description: Add a new CLI command to HawkOp
+description: Add a new CLI command to HawkOp (with design review + test-first workflow)
 ---
 
 Help me add a new command to the HawkOp CLI.
 
-**Before designing, invoke the `cli-designer` skill** to ensure the command follows clig.dev and 12-Factor CLI principles.
+## Phase 1: Design (before writing any implementation code)
 
-## Questions to Answer
+### 1.1 Gather Requirements
 
+Answer these questions with the user:
 1. What should the command do?
-2. What command name should be added?
-3. What subcommands (if any) should it have?
-4. What flags does it need? (prefer flags over multiple positional args)
-5. What arguments does it need? (max 1 type of positional arg)
-
-## Implementation Checklist
-
-- [ ] Add help text with examples in `after_help`
-- [ ] Support `--format json` for machine-readable output
-- [ ] Use stdout for data, stderr for messages
-- [ ] Return non-zero exit code on failure
-- [ ] Add navigation hints (`→ hawkop next-command`)
-- [ ] Test with pipes: `hawkop cmd | jq`
-
-## Implementation Steps
-
-1. Add API models in `src/client/mod.rs`
-2. Add trait method to `StackHawkApi` trait
-3. Implement in `src/client/stackhawk.rs`
-4. Add display model in `src/models/display.rs`
-5. Add CLI command enum in `src/cli/mod.rs`
-6. Create handler in `src/cli/<command>.rs`
-7. Wire up in `src/main.rs`
-
-Follow patterns in `src/cli/` and the cli-designer skill's `patterns.md`.
+2. What command name and subcommands?
+3. What flags and arguments? (prefer flags over multiple positional args)
+4. What API endpoint(s) does it call? (check `stackhawk-api.md` and `api-quirks.md`)
+
+### 1.2 Invoke CLI Designer
+
+**Invoke the `cli-designer` skill** to design the interface. Verify:
+- Command follows clig.dev and 12-Factor CLI principles
+- Args vs flags decision is correct
+- Help text includes examples in `after_help`
+- Matches existing HawkOp patterns (`--org`, `--format`, `--limit`, etc.)
+
+### 1.3 Check Existing Patterns
+
+Before implementing, study the closest existing command:
+- Read `src/cli/` files for a similar command (e.g., `scan.rs` for list+detail, `team.rs` for CRUD)
+- Read `src/client/api/` for the API integration pattern
+- Read `src/models/display/` for the display model pattern
+- Check `src/client/mod.rs` for trait method conventions
+
+### 1.4 Check API Quirks
+
+Read `.claude/skills/stackhawk-api-sherpa/api-quirks.md` to check if the endpoint has known quirks (field naming, replace-all PUT behavior, removed endpoints, etc.).
+
+## Phase 2: Test-First Contract
+
+### 2.1 Write Test Stubs First
+
+Before implementing the command, create test stubs that define the expected behavior:
+
+**Unit test** in the relevant source file:
+```rust
+#[cfg(test)]
+mod tests {
+    // Test that the command handler produces expected output
+    // Test error cases (not found, invalid args)
+    // Test JSON format output
+}
+```
+
+**Functional test** in `tests/functional/`:
+- Add to the appropriate test file (read_tests.rs, mutation_tests.rs, etc.)
+- At minimum, write stubs for:
+  - Happy-path test (command runs successfully)
+  - Error-path test (invalid input, not-found)
+  - JSON output test (`--format json` produces valid JSON)
+
+### 2.2 Update Coverage Script
+
+Add the new command to `scripts/check-test-coverage.sh` so it's tracked:
+```bash
+check_coverage "hawkop <cmd> <subcmd>" "test_<cmd>_<subcmd>|\"<cmd>\".*\"<subcmd>\""
+```
+
+## Phase 3: Implementation
+
+Follow this order (matches CLAUDE.md "Adding New Commands"):
+
+1. **API models** — `src/client/models/<resource>.rs`
+   - `#[serde(rename_all = "camelCase")]`
+   - Use `#[serde(default)]` for optional fields
+   - Check `stackhawk-openapi.json` for exact field names
+2. **Trait method** — `src/client/mod.rs`
+3. **API implementation** — `src/client/api/` (or `src/client/stackhawk.rs`)
+4. **Mock implementation** — `src/client/mock.rs`
+5. **Display model** — `src/models/display/<resource>.rs`
+6. **CLI command enum** — `src/cli/mod.rs`
+7. **Handler** — `src/cli/<command>.rs`
+8. **Main routing** — `src/main.rs`
+
+## Phase 4: Verification
+
+### 4.1 Run Tests
+```bash
+cargo test                        # All unit/integration tests
+cargo clippy -- -D warnings       # Lint check
+```
+
+### 4.2 Run CLI Design Checklist
+
+Verify against `docs/CLI_DESIGN_PRINCIPLES.md`:
+- [ ] `-h`/`--help` display useful help with examples
+- [ ] `--format json` produces valid JSON parseable by `jq`
+- [ ] Data on stdout, messages on stderr
+- [ ] Non-zero exit on failure
+- [ ] Navigation hints (`-> hawkop next-command`)
+- [ ] Works when piped (`hawkop cmd | jq`)
+- [ ] No ANSI codes when not TTY
+
+### 4.3 Run Functional Tests
+```bash
+HAWKOP_PROFILE=test HAWKOP_FUNCTIONAL_TESTS_CONFIRM=yes \
+  cargo test --features functional-tests --test functional -- --test-threads=1 --nocapture "<test_name>"
+```
+
+### 4.4 Check Test Coverage
+```bash
+./scripts/check-test-coverage.sh
+```
+
+## Phase 5: Documentation
+
+- [ ] Update `docs/CLI_REFERENCE.md` with the new command
+- [ ] Update `docs/ROADMAP.md` if this completes a planned endpoint
+- [ ] Add entry to `CHANGELOG.md` under `[Unreleased]`
+- [ ] Update `CLAUDE.md` command list if a new top-level command

.claude/commands/new-feature.md

@@ -0,0 +1,153 @@
+---
+description: "End-to-end feature workflow: API research -> CLI design -> test-first implementation -> docs"
+arguments:
+  - name: feature
+    description: "Brief description of the feature to implement"
+    required: true
+---
+
+Orchestrate a complete feature implementation for HawkOp. This command sequences
+all the right skills and checks so nothing falls through the cracks.
+
+**Feature requested**: $ARGUMENTS
+
+---
+
+## Stage 1: Research & Design
+
+### 1.1 API Research
+
+Invoke the **stackhawk-api-sherpa** skill to research the API endpoints needed:
+1. Read `.claude/skills/stackhawk-api-sherpa/stackhawk-api.md` for endpoint details
+2. Check `stackhawk-openapi.json` for request/response schemas
+3. Read `.claude/skills/stackhawk-api-sherpa/api-quirks.md` for known API gotchas
+4. Check `docs/ROADMAP.md` to see if this feature is planned and what phase it's in
+
+Present findings to the user:
+- Which endpoint(s) are needed
+- Any API quirks or limitations
+- Whether the endpoint is stable or under active development
+- Recommended approach
+
+**Wait for user approval before proceeding.**
+
+### 1.2 CLI Design
+
+Invoke the **cli-designer** skill to design the command interface:
+1. Command name, subcommands, flags, arguments
+2. Apply clig.dev and 12-Factor CLI principles
+3. Match existing HawkOp conventions
+4. Write help text with examples
+
+Present the proposed CLI interface to the user.
+
+**Wait for user approval before proceeding.**
+
+## Stage 2: Test-First Contract
+
+### 2.1 Study Existing Patterns
+
+Before writing any code, study the closest existing implementation:
+- Read the most similar command in `src/cli/` for handler patterns
+- Read the corresponding API method in `src/client/api/`
+- Read the display model in `src/models/display/`
+- Note any reusable utilities or shared patterns
+
+### 2.2 Write Test Stubs
+
+Create test stubs BEFORE implementation:
+
+1. **Unit tests** — Define expected behavior:
+   - Mock client returns expected data
+   - Error cases produce correct error types
+   - Display model converts correctly
+
+2. **Functional tests** — In `tests/functional/`:
+   - Happy-path test (command succeeds with real API)
+   - Error-path test (invalid input, not-found)
+   - JSON output test (`--format json` produces valid, parseable JSON)
+
+3. **Update coverage script** — Add to `scripts/check-test-coverage.sh`
+
+### 2.3 Verify Stubs Compile
+
+```bash
+cargo test --no-run
+```
+
+Tests should compile but may not pass yet (that's expected at this stage).
+
+## Stage 3: Implementation
+
+Follow the implementation order from `/add-command`:
+
+1. API models (`src/client/models/`)
+2. Trait method (`src/client/mod.rs`)
+3. API implementation (`src/client/api/` or `src/client/stackhawk.rs`)
+4. Mock implementation (`src/client/mock.rs`)
+5. Display model (`src/models/display/`)
+6. CLI command enum (`src/cli/mod.rs`)
+7. Handler (`src/cli/<command>.rs`)
+8. Main routing (`src/main.rs`)
+
+After each file, run `cargo check` to catch errors early.
+
+## Stage 4: Verify
+
+### 4.1 Quality Gate
+
+Run the full quality suite:
+```bash
+cargo fmt -- --check
+cargo clippy -- -D warnings
+cargo test
+```
+
+### 4.2 CLI Design Compliance
+
+Run through the CLI design checklist (`.claude/skills/cli-designer/checklist.md`):
+- Help text with examples
+- JSON output valid
+- stdout/stderr separation
+- Exit codes correct
+- Navigation hints present
+- Non-TTY compatible
+
+### 4.3 Functional Tests
+
+```bash
+HAWKOP_PROFILE=test HAWKOP_FUNCTIONAL_TESTS_CONFIRM=yes \
+  cargo test --features functional-tests --test functional -- --test-threads=1 --nocapture "<test_pattern>"
+```
+
+### 4.4 Test Coverage
+
+```bash
+./scripts/check-test-coverage.sh
+```
+
+## Stage 5: Documentation
+
+Update all relevant docs:
+- [ ] `docs/CLI_REFERENCE.md` — New command, flags, examples
+- [ ] `docs/ROADMAP.md` — Mark endpoint as complete, update coverage count
+- [ ] `CHANGELOG.md` — Entry under `[Unreleased]`
+- [ ] `CLAUDE.md` — Add to command list if new top-level command
+
+## Stage 6: Pre-Commit
+
+Run `/pre-commit` for the final check before the user commits.
+
+Present a summary:
+```
+Feature Implementation Summary
+==============================
+Command:           hawkop <cmd> <subcmd>
+API endpoint(s):   <method> <path>
+Files created:     N new files
+Files modified:    N existing files
+Tests:             N unit, N functional
+Docs updated:      CLI_REFERENCE, ROADMAP, CHANGELOG
+Quality:           fmt OK, clippy OK, tests OK
+Coverage:          N/N commands tested
+```